@vzn/vx 0.0.634 → 0.0.636

package/src/config.ts

@@ -42,7 +42,8 @@ export interface WorkspaceConfig {
    * then the trusted ones, and writes go to the scope's only, so a PR never
    * writes what the default branch reads. A client-side convention, not a
    * security boundary: only a cache server that scopes writes by token
-   * can refuse a run that ignores it. `VX_CACHE_SCOPE` beats it. Never
+   * can refuse a run that ignores it. `VX_CACHE_SCOPE` beats it, and
+   * `vx run --cache-scope` beats both. Never
    * folded into a cache key.
    */
   cacheScope?: string
@@ -55,6 +56,12 @@ export interface WorkspaceConfig {
    * `schedule` plugin's weights still come first; this breaks their ties.
    */
   schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
+  /**
+   * The `cache.inputStability` of every task that does not set its own
+   * field. `VX_INPUT_STABILITY` / `VX_INPUT_STABILITY_SEVERITY` override
+   * both for the run.
+   */
+  inputStability?: InputStability
   /**
    * Graph rules a run checks before it schedules anything. Each is on unless
    * set to `false`; turning one off allows a shape vx handles correctly but
@@ -65,9 +72,11 @@ export interface WorkspaceConfig {
    * Plugins registered for this workspace, consulted in this order once
    * per `vx run`: each fills any of the pipeline stages and capabilities
    * below, and core's own executor and cache store sit at the tail of
-   * every list. See `docs/design/pipeline-2026-09.md`.
+   * every list. See `docs/design/pipeline-2026-09.md`. An `undefined`,
+   * `null` or `false` entry is skipped, so a factory that declines
+   * (`github()` off Actions) or `cond && plugin()` needs no filter.
    */
-  plugins?: readonly Plugin[]
+  plugins?: readonly (Plugin | undefined | null | false)[]
 }
 
 /** `WorkspaceConfig.rules`. */
@@ -488,6 +497,30 @@ export interface CacheConfig {
   inputs: CacheInputs
   /** What this task produces. Captured for restore on a cache hit. */
   outputs: CacheOutputs
+  /**
+   * What a write to an input while the command runs means. Each field,
+   * highest first: its env var, this, the workspace's `inputStability`,
+   * the default (`'immutable'`, `'warn'`).
+   */
+  inputStability?: InputStability
+}
+
+export interface InputStability {
+  /**
+   * `'immutable'` (the default): any write to an input during the command
+   * withholds the entry, whatever the file holds after, since an edit
+   * undone mid-run cannot be told from no edit. `'mutable'`: a file
+   * rewritten to the bytes the key folded counts as unchanged, for a task
+   * that rewrites its own input identically (tsdown's `package.json`).
+   * `'unchecked'`: no check.
+   */
+  strategy?: 'immutable' | 'mutable' | 'unchecked'
+  /**
+   * What a withheld entry does to the run. `'warn'` (the default): the
+   * result stands, vx says why, and the run goes on. `'error'`: the task
+   * fails, so the run fails.
+   */
+  severity?: 'warn' | 'error'
 }
 
 export interface CacheOutputs {

package/src/graph/scheduler.ts

@@ -208,6 +208,15 @@ export interface TaskOutcome {
    * inline in the task's block instead of as loose status output.
    */
   sandboxViolationLines?: string[]
+  /** The `exec.sandbox.allow` entries that would have granted the denials. */
+  sandboxFix?: {
+    read?: string[]
+    write?: string[]
+    network?: string[]
+    systemInfo?: string[]
+    /** Credential paths denied and left out of the grants: an agent applies the fix as given. */
+    withheld?: string[]
+  }
 }
 
 export type ContinueMode = 'never' | 'deps-ok' | 'always'
@@ -804,14 +813,16 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       // tasks are never asked, so they never park.
       const takeFitting = (): string | undefined => {
         if (holding) return undefined
-        // No pools, no policy and a full exec lane: nothing on the
-        // exec queue can be admitted, so it is not scanned — scanning it
+        // No pools and a full exec lane: nothing on the exec queue can be
+        // admitted, so it is not scanned — an admit policy only narrows
+        // the count gate, never widens it (scanning under one cost the
+        // history plugin's cold bench run 10 s, 2026-10-09) — scanning it
         // would pop and re-park every ready exec task on every tick, and
         // with a wide frontier that is O(R) per tick, O(R²) per run (the
         // 6,000-task scale pin went 0.5 s → 28 s when the restore lane's
         // first cut let the scan run past a full exec lane, 2026-09-10).
         // This is the legacy O(1) gate, kept per lane.
-        const execAdmissible = poolOf !== undefined || admitActive || execRoom()
+        const execAdmissible = poolOf !== undefined || execRoom()
         if (execAdmissible) {
           while (execReady.size > 0) {
             const seq = execReady.peekSeq()

package/src/graph/task-graph.ts

@@ -302,6 +302,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}`,
+    'VX_E_DEPENDS_ON',
   )
 }
 
@@ -492,7 +493,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}`)
+        throw new UserError(`Task ${id}: ${err.message}`, 'VX_E_DEPENDS_ON')
       }
       throw err
     }
@@ -503,14 +504,21 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     // operations. PARTIAL patterns (`build.*`, `^build.*`) are legal:
     // 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}")`)
+      throw new UserError(
+        `Task ${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}")`)
+      throw new UserError(
+        `Task ${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}")`,
+        'VX_E_DEPENDS_ON',
       )
     }
     if (spec.kind === 'self') {
@@ -530,6 +538,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         if (!visit(frame, projectName, spec.task, false)) {
           throw new UserError(
             `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
+            'VX_E_DEPENDS_ON',
           )
         }
         goPast(frame, projectName, spec.task, new Set([projectName]))
@@ -594,9 +603,11 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         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`,
+            'VX_E_DEPENDS_ON',
           )
         throw new UserError(
           `Task ${id} depends on ${taskId(spec.project, spec.task)} but no such project or task is declared`,
+          'VX_E_DEPENDS_ON',
         )
       }
       goPast(frame, spec.project, spec.task, new Set([projectName, spec.project]))
@@ -1109,7 +1120,7 @@ function collideAcross(
         `cache.outputs.files — vx cleans a task's declared outputs before it runs and before a ` +
         `cache-hit restore, so whichever of these runs second DELETES the other's output`
       if (exclusive && (reaches(files.id, ws.id) || reaches(ws.id, files.id))) {
-        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`)
+        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`, 'VX_E_OUTPUT_OVERLAP')
       }
       if (reaches(files.id, ws.id)) {
         ;(files.addsToOutputsOf ??= []).push(ws.id)
@@ -1132,11 +1143,13 @@ function collideAcross(
           `${head}. ${ws.id} depends on ${files.id}, but adding to its output needs every ` +
             `cache.outputs.workspaceFiles entry inside ${rel === '' ? 'the workspace root' : rel}, ` +
             `and ${JSON.stringify(outside)} is not. Give each task its own output path.`,
+          'VX_E_OUTPUT_OVERLAP',
         )
       }
       throw new UserError(
         `${head} and the run still reports success. Give each task its own output path` +
           (exclusive ? '.' : ', or make one depend on the other.'),
+        'VX_E_OUTPUT_OVERLAP',
       )
     }
   }
@@ -1373,7 +1386,8 @@ function collide(
       // `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] : []
-      if (up !== undefined && exclusive) throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`)
+      if (up !== undefined && exclusive)
+        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`, 'VX_E_OUTPUT_OVERLAP')
       if (up !== undefined && down !== undefined) {
         const downGlobs = splitNegations(
           (field === 'files'
@@ -1386,6 +1400,7 @@ function collide(
       }
       throw new UserError(
         `${head} and the run still reports success. Give each task its own output path.`,
+        'VX_E_OUTPUT_OVERLAP',
       )
     }
   }
@@ -1440,6 +1455,7 @@ function refuseSelfClean(node: TaskNode): void {
           `its own output — vx removes a task's outputs before it runs, so the task would ` +
           `delete its own sources. A task that rewrites files in place (a formatter) declares ` +
           `no outputs.`,
+        'VX_E_INPUT_IS_OUTPUT',
       )
     }
   }
@@ -1663,6 +1679,7 @@ function readsOutputs(
           `Exclude it: add ${JSON.stringify(`!${out}`)} to ${reader.node.id}'s ` +
           `cache.inputs.${field}, or set rules: { upfrontKeys: false } in vx.workspace.ts to ` +
           `let it wait for its producer.`,
+        'VX_E_INPUT_IS_OUTPUT',
       )
     }
   }

package/src/index.ts

@@ -48,6 +48,7 @@ export type {
   CacheConfig,
   CacheInputs,
   CacheOutputs,
+  InputStability,
   SandboxConfig,
   SandboxGrants,
   SandboxDenials,
@@ -65,7 +66,12 @@ export { run, planRun, prepareRun } from './orchestrator/index.js'
 // (`@vzn/vx-schedule-history` does; a plugin package reaches core only
 // through this façade, which is what put these here).
 export { LocalHistoryProvider } from './orchestrator/index.js'
-export type { HistoryProvider, HistoryTable, TaskHistory } from './orchestrator/index.js'
+export type {
+  HistoryProvider,
+  HistoryTable,
+  TaskHistory,
+  TaskResources,
+} from './orchestrator/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
 // `RunOptions.affected`: what `--affected`'s diff changed, per project.
 export type { AffectedChanges } from './workspace/index.js'

package/src/orchestrator/execute-task.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import type { ExecConfig, TaskConfig, CacheConfig } from '../config.js'
+import type { ExecConfig, TaskConfig, CacheConfig, InputStability } from '../config.js'
 import {
   ArtifactVanishedError,
   type CacheEntry,
@@ -78,6 +78,7 @@ import type { FingerprintWatch } from './fingerprint-watch.js'
 import { restoreHit } from './hit-restore.js'
 import type { MissExplainer } from './miss-reason.js'
 import { shellVerdict } from './shell-verdict.js'
+import { sandboxFix } from './sandbox-fix.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'
@@ -174,6 +175,11 @@ export interface ExecuteArgs {
    * `exec.timeout` wins. Threaded as an option only — never hashed.
    */
   timeout?: number
+  /**
+   * The run's `inputStability` layers around the task's own: `run` from
+   * the env vars (above the task), `workspace` from `vx.workspace` (below).
+   */
+  inputStability?: { run: InputStability; workspace?: InputStability }
   /** Per-run memo for `git ls-files` (one entry per project dir). */
   gitFilesCache?: GitFilesCache
   /** Per-run memo for derived hashes (package.json bytes + task config). */
@@ -336,6 +342,24 @@ async function restoreOrMiss(
   }
 }
 
+/**
+ * What a write to an input during the command means, each field highest
+ * first: the env var (`layers.run`), the task's `cache.inputStability`,
+ * the workspace's, then `'immutable'` and `'warn'` (owner, 2026-10-12), so
+ * by default any such write withholds the save, on CI too, since a
+ * concurrent task can change an input and put it back.
+ */
+function inputStabilityOf(
+  cache: CacheConfig | undefined,
+  layers: ExecuteArgs['inputStability'],
+): Required<InputStability> {
+  const task = cache?.inputStability
+  return {
+    strategy: layers?.run.strategy ?? task?.strategy ?? layers?.workspace?.strategy ?? 'immutable',
+    severity: layers?.run.severity ?? task?.severity ?? layers?.workspace?.severity ?? 'warn',
+  }
+}
+
 /**
  * The workspace fingerprint every key here folded has moved (a task
  * rewrote the lockfile), said once per run.
@@ -1449,6 +1473,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
 
   const wallclockEndNs = process.hrtime.bigint() - args.runStartHrTimeNs
 
+  const stability = inputStabilityOf(args.node.config.cache, args.inputStability)
+  let movedFails = false
   let own: Awaited<ReturnType<typeof ownOutputs>>
   if (effectiveExitCode === 0 && willSave && deferralRequested) {
     // The outputs never landed here: no artifact, no rows. A partial local
@@ -1558,7 +1584,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
    */
   async function movedSinceKey(): Promise<string | null | undefined> {
     if (described!.hash !== hash) return null
-    return (await movedInput(described!.facts, cache, described!.describedAt)) ?? described!.added()
+    return (
+      (await movedInput(
+        described!.facts,
+        cache,
+        described!.describedAt,
+        stability.strategy === 'mutable',
+      )) ?? described!.added()
+    )
   }
 
   /**
@@ -1577,6 +1610,10 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       unkeyed = true
       return false
     }
+    // `'unchecked'` skips the check of the command's own window; a key the
+    // re-derive before the command already disagreed with still withholds,
+    // since it never described the bytes the command read.
+    if (stability.strategy === 'unchecked' && described!.hash === hash) return true
     const endCheck = span('miss: recheck inputs')
     const moved = await movedSinceKey()
     endCheck()
@@ -1591,15 +1628,25 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       moved === null || path.basename(moved) === 'package.json'
         ? ''
         : '; if the task writes it, declare it in cache.outputs'
-    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${hint}`,
-    )
+    if (stability.severity === 'error') {
+      log.status(
+        `[vx] ${node.id}: ${what} changed after its key was taken — the result is not saved, ` +
+          `and inputStability.severity is 'error', so the task fails${hint}`,
+      )
+      movedFails = true
+    } else {
+      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${hint}`,
+      )
+    }
     forgetUndeclaredWrites(args, wsOutputs.length > 0 ? 'workspace' : 'project')
     unkeyed = true
     return false
   }
 
+  if (movedFails) effectiveExitCode = 1
+
   if (unkeyedUpstream !== undefined && willWrite && effectiveExitCode === 0) {
     log.status(
       `[vx] ${node.id}: ran over ${unkeyedUpstream.node.id}'s outputs, which its key no longer ` +
@@ -1608,6 +1655,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   }
 
   const finalViolations = violations
+  const fixOf = (fix: TaskOutcome['sandboxFix']) => (fix === undefined ? {} : { sandboxFix: fix })
 
   return {
     node,
@@ -1640,6 +1688,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
           sandboxViolations: finalViolations.filter((v) => v.hint !== true).length,
           // A denied path is the task's own spelling, a secret in it too.
           sandboxViolationLines: finalViolations.map((v) => secrets?.mask(v.line) ?? v.line),
+          ...fixOf(
+            sandboxFix(
+              finalViolations,
+              node.projectDir,
+              (t) => secrets?.mask(t) ?? t,
+              cacheCfg?.inputs.files,
+            ),
+          ),
         }
       : {}),
   }

package/src/orchestrator/framed-output.ts

@@ -32,6 +32,7 @@ import { paint, type ColorSupport } from './colors.js'
 import { neverStarted } from './summary.js'
 import { outcomeLabel, ranNoCache, skippedReason } from './events.js'
 import { fileMemo, linkPaths } from './path-links.js'
+import { sandboxFixLine } from './sandbox-fix.js'
 
 const NO_COLOR: ColorSupport = { enabled: false }
 
@@ -529,7 +530,32 @@ function violationSection(outcome: TaskOutcome, colors: ColorSupport): string[]
   // every record for telemetry.
   const body = [...new Set(vlines)]
   // Red, not amber: a violation fails the task, so it reads as a failure.
-  return [sectionLine(`SANDBOX VIOLATIONS (${body.length})`, ERROR, colors), '', ...body, '']
+  // vx's note, after the evidence: the grants that would have allowed it.
+  // A read the output depends on is a key input too; the sandbox never
+  // adds one (owner, 2026-10-09).
+  const fix = outcome.sandboxFix
+  const line = fix === undefined ? undefined : sandboxFixLine(fix)
+  const dim = (text: string): string => paint('', text, colors, { dim: true })
+  const note =
+    fix === undefined
+      ? []
+      : [
+          ...(line !== undefined ? [dim(`fix: ${line}`)] : []),
+          ...(fix.read !== undefined
+            ? [dim('a read the output depends on belongs in cache.inputs.files too')]
+            : []),
+          ...(fix.withheld !== undefined
+            ? [dim(`credential path, grant it only on purpose: ${fix.withheld.join(', ')}`)]
+            : []),
+          '',
+        ]
+  return [
+    sectionLine(`SANDBOX VIOLATIONS (${body.length})`, ERROR, colors),
+    '',
+    ...body,
+    '',
+    ...note,
+  ]
 }
 
 export function formatFrameClose(

package/src/orchestrator/history.ts

@@ -21,7 +21,8 @@ const DEFAULT_RECENT = 50
 
 // A hit is recorded as `cache-hit` / `cache-hit-remote` and replays a
 // success; the list is derived so a new status cannot miss it.
-const PASS_STATUSES = `(${TASK_STATUSES.filter(isPassStatus)
+/** The pass set as SQL, `(…)`: one definition, `isPassStatus`. */
+export const PASS_STATUSES = `(${TASK_STATUSES.filter(isPassStatus)
   .map((s) => `'${s}'`)
   .join(', ')})`
 
@@ -58,6 +59,12 @@ export interface TaskHistory {
 /** Map keyed by `project#task`. */
 export type HistoryTable = ReadonlyMap<string, TaskHistory>
 
+/** What a scheduler learns from a task's history: its p50 and its resource maxima. */
+export type TaskResources = Pick<
+  TaskHistory,
+  'p50DurationMs' | 'maxPeakRssBytes' | 'maxCpuParallelism'
+>
+
 export interface HistoryProvider {
   loadFor(taskIds: readonly string[]): Promise<HistoryTable>
   /**
@@ -213,6 +220,73 @@ export class LocalHistoryProvider implements HistoryProvider {
     return out
   }
 
+  /**
+   * `loadFor`'s p50 and resource maxima over the same window, without its
+   * rates. The rates group every row of the window and join each hit to
+   * its entry: 407 ms at 168,000 rows (8,002 tasks, 21 runs), most of a
+   * nothing-changed run's schedule stage. Here the executed successes are
+   * grouped alone, and the hits only as distinct keys, each joined to its
+   * entry once: 148 ms on the same table, the same numbers.
+   */
+  async resourcesFor(taskIds: readonly string[]): Promise<ReadonlyMap<string, TaskResources>> {
+    const out = new Map<string, TaskResources>()
+    if (taskIds.length === 0) return out
+    const floor = this.floor()
+    const wanted = new Set(taskIds)
+    type Executed = {
+      project: string
+      task: string
+      ds: string
+      rss: number | null
+      cpu: number | null
+    }
+    const executed = this.db
+      .query(
+        `SELECT project, task, GROUP_CONCAT(duration_ms) AS ds, MAX(peak_rss_bytes) AS rss,
+           MAX(CASE WHEN cpu_ms IS NOT NULL AND duration_ms > 0
+                    THEN cpu_ms * 1.0 / duration_ms END) AS cpu
+         FROM runs
+         WHERE id >= ? AND status = 'success' AND (cache_hit IS NULL OR cache_hit = 0)
+         GROUP BY project, task`,
+      )
+      .all(floor) as Executed[]
+    for (const row of executed) {
+      const key = `${row.project}#${row.task}`
+      if (!wanted.has(key)) continue
+      const durations = row.ds.split(',').map(Number)
+      durations.sort((a, b) => a - b)
+      out.set(key, {
+        p50DurationMs: pickPercentile(durations, 0.5),
+        ...(row.rss !== null ? { maxPeakRssBytes: row.rss } : {}),
+        ...(row.cpu !== null ? { maxCpuParallelism: row.cpu } : {}),
+      })
+    }
+    type Hit = { project: string; task: string; rss: number | null; cpu: number | null }
+    const hits = this.db
+      .query(
+        `SELECT h.project, h.task, MAX(e.peak_rss_bytes) AS rss,
+           MAX(CASE WHEN e.cpu_ms IS NOT NULL AND e.duration_ms > 0
+                    THEN e.cpu_ms * 1.0 / e.duration_ms END) AS cpu
+         FROM (SELECT DISTINCT project, task, hash FROM runs WHERE id >= ? AND cache_hit = 1) h
+         JOIN entries e ON e.hash = h.hash
+         GROUP BY h.project, h.task`,
+      )
+      .all(floor) as Hit[]
+    for (const row of hits) {
+      const key = `${row.project}#${row.task}`
+      if (!wanted.has(key) || (row.rss === null && row.cpu === null)) continue
+      const had = out.get(key)
+      const rss = Math.max(had?.maxPeakRssBytes ?? -Infinity, row.rss ?? -Infinity)
+      const cpu = Math.max(had?.maxCpuParallelism ?? -Infinity, row.cpu ?? -Infinity)
+      out.set(key, {
+        p50DurationMs: had?.p50DurationMs,
+        ...(rss !== -Infinity ? { maxPeakRssBytes: rss } : {}),
+        ...(cpu !== -Infinity ? { maxCpuParallelism: cpu } : {}),
+      })
+    }
+    return out
+  }
+
   /** The first `runs` id of the newest `recent` invocations (see `loadFor`). */
   private floor(): number {
     const row = this.db

package/src/orchestrator/index.ts

@@ -56,6 +56,7 @@ export {
   type HistoryTable,
   LocalHistoryProvider,
   type TaskHistory,
+  type TaskResources,
 } from './history.js'
 export {
   detectFlaky,

package/src/orchestrator/options.ts

@@ -86,6 +86,8 @@ export interface RunOptions {
    * saying it is not.
    */
   remoteRequested?: boolean
+  /** This run's `cacheScope` (the CLI's `--cache-scope`), above `VX_CACHE_SCOPE` and `vx.workspace`. */
+  cacheScope?: string
   /**
    * The `cacheScope` a run takes when `vx.workspace` names none. The CLI
    * passes `'read-only'` off CI (`CI` unset, `0` or `false`) unless

package/src/orchestrator/path-links.ts

@@ -35,7 +35,9 @@ export function linkPaths(text: string, dir: string, isFile: (abs: string) => bo
 
 /**
  * The files `text` names that exist (resolved against `dir`), each with the
- * line and column it gave, unique, in order of first appearance.
+ * line and column it gave, unique, in order of first appearance. A file also
+ * named with a line drops its bare mention: bun test heads a failure with
+ * `app.test.js:` and gives the line only in the stack below it.
  */
 export function fileLocations(
   text: string,
@@ -56,9 +58,9 @@ export function fileLocations(
       ...(line !== undefined ? { line: Number(line) } : {}),
       ...(col !== undefined ? { col: Number(col) } : {}),
     })
-    if (out.length === LOCATIONS_CAP) break
   }
-  return out
+  const lined = new Set(out.filter((l) => l.line !== undefined).map((l) => l.file))
+  return out.filter((l) => l.line !== undefined || !lined.has(l.file)).slice(0, LOCATIONS_CAP)
 }
 
 /** A file test that asks the file system once per path. */

package/src/orchestrator/plugin.ts

@@ -127,7 +127,9 @@ export interface VxPlugin {
   /**
    * Scheduling priorities: task id → weight, higher runs first among READY
    * tasks (merged over the structural baseline, which stays the tie-break).
-   * Runs once, after the graph is final. A later plugin's weight for a task
+   * Runs once, after the graph is final and the local hits are known, and
+   * only when a task will start: a run of confirmed local hits restores
+   * in no order a weight changes. A later plugin's weight for a task
    * overrides an earlier one's. Return undefined to leave the baseline.
    */
   schedule?(

package/src/orchestrator/prepare.ts

@@ -102,9 +102,11 @@ export interface PreparedRun {
   /**
    * Scheduling priorities from plugins' `schedule` stage (task id → weight,
    * merged over the structural baseline by the scheduler). Empty when no
-   * plugin declares the stage.
+   * plugin declares the stage. Asked only by a run with a task to start:
+   * the stage reads history (148 ms at 8,002 tasks) to order work a
+   * nothing-changed run never dispatches. Runs the stage once.
    */
-  priorities: ReadonlyMap<string, number>
+  priorities: () => Promise<ReadonlyMap<string, number>>
   nodes: Map<string, TaskNode>
   /**
    * The tasks `--exclude-dependencies` took out of the schedule: keyed as a
@@ -286,13 +288,13 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
 
   // The local cache opens BEFORE the configs load: it is also where their
   // cached evaluations live.
-  // `VX_CACHE_SCOPE` wins over the workspace (and `github()`'s guess):
+  // `--cache-scope`, then `VX_CACHE_SCOPE`, win over the workspace (and `github()`'s guess):
   // a CI job that knows its trust level says so without editing config.
   const envScope = process.env['VX_CACHE_SCOPE'] || undefined
   if (envScope !== undefined && !isCacheScope(envScope)) throw cacheScopeEnvError()
   const policy: CachePolicy = scopeCachePolicy(
     options.cache ?? FULL_CACHE_POLICY,
-    envScope ?? workspaceConfig?.cacheScope ?? options.defaultCacheScope,
+    options.cacheScope ?? envScope ?? workspaceConfig?.cacheScope ?? options.defaultCacheScope,
   )
   const localCache = new Cache(
     cacheDir,
@@ -491,7 +493,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       localCache,
       hasRemoteLayer,
       cachePolicy: policy,
-      priorities: new Map(),
+      priorities: () => Promise.resolve(new Map()),
       nodes: new Map(),
       keyOnly: new Map(),
       unresolvedTasks,
@@ -687,15 +689,16 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         })
       }
     }
-    let priorities: ReadonlyMap<string, number> = new Map()
-    if (hasHook(plugins, 'schedule')) {
-      priorities = await applyScheduleHooks(plugins, nodes, {
-        workspaceRoot,
-        cacheDir,
-        warn: (m) => log.status(m),
-        localCache,
-      })
-    }
+    let scheduled: Promise<ReadonlyMap<string, number>> | undefined
+    const priorities = (): Promise<ReadonlyMap<string, number>> =>
+      (scheduled ??= hasHook(plugins, 'schedule')
+        ? applyScheduleHooks(plugins, nodes, {
+            workspaceRoot,
+            cacheDir,
+            warn: (m) => log.status(m),
+            localCache,
+          })
+        : Promise.resolve(new Map()))
 
     return {
       workspaceRoot,