@vzn/vx 0.0.21 → 0.0.23

package/src/orchestrator/plugin.ts

@@ -103,8 +103,14 @@ export interface VxPlugin {
    * fingerprint every key sees (the config-evaluation cache still keys on
    * it — a config may import a dependency), and `--affected` asks
    * `affected` which projects a change to it touches instead of selecting
-   * every project. A file has one claimant; a name core does not fold is
-   * refused, since there is nothing to take out.
+   * every project. A file has one claimant.
+   *
+   * A root file core does NOT fold is claimed the same way when the
+   * plugin's stages read it: `turbo()` shapes every task from
+   * `turbo.json`, so an edit to it re-keys tasks through their resolved
+   * configs while no project owns the path. Nothing is taken out;
+   * `--affected` asks `affected` (undefined: every project) and `vx watch`
+   * re-runs on an edit (item 961). A claim is a bare name at the root.
    */
   readonly fingerprint?: FingerprintClaim
 
@@ -187,9 +193,13 @@ export interface VxPlugin {
     | Promise<TelemetrySink | TelemetrySink[] | undefined>
 
   /**
-   * Optional one-time setup before any capability is consulted (validate the
-   * workspace, open a connection, read a token). Throwing aborts the run with
-   * a clean UserError naming the plugin — same contract as the old setup().
+   * Optional one-time setup per run (validate the workspace, open a
+   * connection, read a token). Throwing aborts the run with a clean
+   * UserError naming the plugin. It is not a guard over the pipeline: the
+   * config, project, cache, graph, key and schedule stages have run by the
+   * time it is called, and a plan (`--dry`, `planRun`) never calls it. It
+   * precedes the executors, the telemetry sinks, admission and the first
+   * task (tests/plugin-e2e.test.ts).
    */
   setup?(ctx: PluginSetupContext): void | Promise<void>
 
@@ -252,7 +262,7 @@ export interface KeyHookContext extends BaseContext {}
 
 /** A plugin's claim on workspace fingerprint files — see `VxPlugin.fingerprint`. */
 export interface FingerprintClaim {
-  /** Root-relative names from `WORKSPACE_FINGERPRINT_FILES`, e.g. `['pnpm-lock.yaml']`. */
+  /** Bare names at the workspace root: a lockfile core folds (`pnpm-lock.yaml`) or a file the plugin reads (`turbo.json`). */
   readonly files: readonly string[]
   /**
    * The projects (package names) a change to a claimed file affects. Called
@@ -308,7 +318,10 @@ export interface PluginContext {
   readonly workspaceRoot: string
   /** Where vx's cache lives — read-only as far as the plugin is concerned. */
   readonly cacheDir: string
-  /** The run event bus. A plugin can subscribe directly if its needs exceed the hooks. */
+  /**
+   * The run event bus. A plugin can subscribe directly if its needs exceed
+   * the hooks; the subscription ends with the run, as a hook's does.
+   */
   readonly bus: EventBus
   /**
    * Convenience: register a typed handler keyed off `RunEvent.kind`.
@@ -460,7 +473,17 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
     const ctx: PluginContext = {
       workspaceRoot,
       cacheDir,
-      bus,
+      // A subscription made past the hooks leaves with the run like a
+      // hook's does: the bus can outlive the run (`RunOptions.bus`), and
+      // one left behind hears every later run on it (item 635).
+      bus: {
+        emit: (event) => bus.emit(event),
+        subscribe(subscriber) {
+          const dispose = bus.subscribe(subscriber)
+          disposers.push(dispose)
+          return dispose
+        },
+      },
       on(hook, handler) {
         const dispose = bus.subscribe((event) => {
           if (disabled.has(plugin.name)) return

package/src/orchestrator/prepare.ts

@@ -28,6 +28,7 @@ import {
   computeNestedProjectDirs,
   computeWorkspaceFingerprints,
   findWorkspaceRoot,
+  type LoadReads,
   listProjects,
   loadWorkspace,
   FROZEN_WITHOUT_LOCK,
@@ -37,8 +38,10 @@ import {
 } from '../workspace/index.js'
 import {
   buildTaskGraph,
+  excludeDependencies,
   expandRequested,
   type TaskNode,
+  undeclaredDepsError,
   unresolvedRequests,
 } from '../graph/index.js'
 import {
@@ -50,6 +53,8 @@ import {
   resolveCache,
 } from './plugin-host.js'
 import { loadProjects, loadWorkspacePlugins, type LoadedProjects } from './projects.js'
+import { keyExcludedDependencies } from './excluded-keys.js'
+import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
 import { createHashCache, type HashCache } from './task-hash.js'
 import type { Logger } from './logger.js'
@@ -99,6 +104,8 @@ export interface PreparedRun {
    */
   anyProjectConfig: boolean
   workspaceFingerprint: string
+  /** Whether a task has since rewritten what that fingerprint folded (fingerprint-watch.ts). */
+  fingerprintWatch: FingerprintWatch
   nestedDirsByProject: Map<string, string[]>
   /**
    * Per-run memo for `git ls-files` output, keyed by project dir.
@@ -143,7 +150,10 @@ export interface PreparedRun {
  */
 export async function prepareRun(options: RunOptions, log: Logger): Promise<PreparedRun> {
   mark('startup')
-  const workspaceRoot = await findWorkspaceRoot(options.cwd)
+  // The root manifest is read once for the root, the globs and the
+  // fingerprint. A watch cycle is a new run and reads it afresh.
+  const reads: LoadReads = new Map()
+  const workspaceRoot = await findWorkspaceRoot(options.cwd, reads)
   // An UNSCOPED run (no explicit scope, at least one bare task name)
   // enumerates the whole tree whatever the configs say, so git starts
   // HERE — the walk needs only the root — and overlaps the workspace
@@ -160,7 +170,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // handler keeps that from surfacing as an unhandled rejection (the real
   // await further down still sees the error).
   earlyGit?.catch(() => {})
-  const workspace = await loadWorkspace(workspaceRoot)
+  const workspace = await loadWorkspace(workspaceRoot, reads)
   const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, (m) =>
     log.status(m),
   )
@@ -191,6 +201,11 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   }
   const seeds: 'all' | string[] =
     options.projects !== undefined ? [...options.projects, ...anchored] : hasBare ? 'all' : anchored
+  // Its own mark: the package graph is the bulk of what used to be charged
+  // to `open cache` (measured on a 1,000-project tree, 2026-09-20 — the
+  // graph 3-8 ms against the cache open's ~1 ms and the fingerprints' ~0.3),
+  // so a reader profiling that stage was sent to the wrong code.
+  mark('package graph')
 
   // The local cache opens BEFORE the configs load: it is also where their
   // cached evaluations live. `--cache-dir <path>` (RunOptions.cacheDir)
@@ -200,14 +215,22 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   const cacheDir = options.cacheDir
     ? path.resolve(options.cwd, options.cacheDir)
     : resolveCacheDir(workspaceRoot, workspaceConfig)
-  const localCache = new Cache(cacheDir, { read: policy.localRead, write: policy.localWrite })
+  const localCache = new Cache(
+    cacheDir,
+    { read: policy.localRead, write: policy.localWrite },
+    workspaceRoot,
+    options.artifactCeiling,
+  )
+  localCache.assertWritable()
   noteSchemaReset(localCache, (m) => log.status(m))
   // Two digests from one read: the config-evaluation cache keys on every
   // file (a config may import a dependency), the task keys on the files no
   // plugin claims (`VxPlugin.fingerprint`).
+  const fingerprintsAt = Date.now()
   const fingerprints = await computeWorkspaceFingerprints(
     workspaceRoot,
     new Set(fingerprintClaims(plugins).keys()),
+    reads,
   )
   const workspaceFingerprint = fingerprints.unclaimed
   mark('open cache')
@@ -224,19 +247,22 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     throw new UserError(FROZEN_WITHOUT_LOCK)
   }
 
+  const loadArgs = {
+    workspaceRoot,
+    cacheDir,
+    plugins,
+    projectMetas,
+    packageGraph,
+    lock,
+    evalCache: { store: localCache, workspaceFingerprint: fingerprints.all },
+    warn: (m: string) => log.status(m),
+  }
   let loaded: LoadedProjects
   try {
     loaded = await loadProjects({
-      workspaceRoot,
-      cacheDir,
-      plugins,
-      projectMetas,
-      packageGraph,
+      ...loadArgs,
       seeds,
       closure: true,
-      lock,
-      evalCache: { store: localCache, workspaceFingerprint: fingerprints.all },
-      warn: (m) => log.status(m),
       ...(options.staged !== undefined ? { staged: options.staged } : {}),
     })
   } catch (err) {
@@ -319,6 +345,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   applyGitEnumeration(enumeration, workspaceRoot, projectDirs, gitFilesCache, usesWorkspaceInputs)
   mark('git enumeration')
   const hashCache = createHashCache()
+  const fingerprintWatch = new FingerprintWatch(workspaceRoot, fingerprints, fingerprintsAt)
 
   // Empty-cases bookkeeping. We still construct the cache + fingerprint
   // so the caller's try/finally pattern can close it uniformly.
@@ -337,6 +364,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       projects,
       anyProjectConfig: projectsWithConfigs.length > 0,
       workspaceFingerprint,
+      fingerprintWatch,
       nestedDirsByProject,
       gitFilesCache,
       hashCache,
@@ -345,14 +373,26 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     }
   }
 
+  // The whole graph, whatever `--exclude-dependencies` says: the stages
+  // below shape and key the tasks it drops as a full run would, because
+  // a dropped task is still keyed (excluded-keys.ts). A scoped load is not
+  // the whole workspace: a `^name` nothing loaded declares may be declared
+  // by a config the scope left out, so the builder hands it back instead of
+  // refusing it, and the rest decide.
+  const unproven: Array<[taskId: string, name: string]> = []
   const nodes = buildTaskGraph({
     projects,
     packageGraph,
     requested,
-    ...(options.excludeDependencies !== undefined
-      ? { excludeDependencies: options.excludeDependencies }
+    ...(projects.size < projectsWithConfigs.length
+      ? { undeclaredDeps: (id: string, name: string) => void unproven.push([id, name]) }
       : {}),
   })
+  if (unproven.length > 0) {
+    await refuseUndeclaredDeps(unproven, () =>
+      loadProjects({ ...loadArgs, seeds: 'all', closure: false, staged: projects }),
+    )
+  }
   // The graph is built; what follows is the plugins' (graph, key,
   // schedule). Two rows, so a plugin's key stage reads as its own cost
   // and not as graph building — a lockfile plugin's 1000 stats per run
@@ -369,6 +409,24 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   if (hasHook(plugins, 'key')) {
     await applyKeyHooks(plugins, nodes, { workspaceRoot, cacheDir, warn: (m) => log.status(m) })
   }
+  const exclude = options.excludeDependencies
+  if (exclude !== undefined && (exclude === 'all' || exclude.length > 0)) {
+    const { keyOnly, dropped } = excludeDependencies(nodes, exclude)
+    if (dropped.size > 0) {
+      await keyExcludedDependencies({
+        nodes,
+        keyOnly,
+        dropped,
+        cache,
+        workspaceRoot,
+        workspaceFingerprint,
+        forwardArgs: options.forwardArgs,
+        nestedDirsByProject,
+        gitFilesCache,
+        hashCache,
+      })
+    }
+  }
   let priorities: ReadonlyMap<string, number> = new Map()
   if (hasHook(plugins, 'schedule')) {
     priorities = await applyScheduleHooks(plugins, nodes, {
@@ -393,6 +451,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     projects,
     anyProjectConfig: projectsWithConfigs.length > 0,
     workspaceFingerprint,
+    fingerprintWatch,
     nestedDirsByProject,
     gitFilesCache,
     hashCache,
@@ -400,3 +459,30 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     empty: nodes.size === 0 ? 'empty-graph' : null,
   }
 }
+
+/**
+ * Refuses the first `^name` in `unproven` that no project in the whole
+ * workspace declares. `load` evaluates the configs a scoped run left out;
+ * it is reached only when a `^name` found no holder and nothing loaded
+ * declares it, so a run that names only declared tasks never pays for it.
+ * The rest failing to load leaves the names unjudged: an out-of-scope
+ * broken config does not fail a scoped run.
+ */
+async function refuseUndeclaredDeps(
+  unproven: ReadonlyArray<readonly [taskId: string, name: string]>,
+  load: () => Promise<LoadedProjects>,
+): Promise<void> {
+  let all: LoadedProjects
+  try {
+    all = await load()
+  } catch {
+    return
+  }
+  const declared = new Set<string>()
+  for (const p of all.projects.values()) {
+    for (const t of Object.keys(p.config.tasks ?? {})) declared.add(t)
+  }
+  for (const [id, name] of unproven) {
+    if (!declared.has(name)) throw undeclaredDepsError(id, name)
+  }
+}

package/src/orchestrator/projects.ts

@@ -10,6 +10,7 @@ import {
   loadProjectConfigs,
   validateProjectConfig,
   type LoadProjectConfigOptions,
+  type LoadReads,
   type Lockfile,
   type PackageGraph,
   type ProjectEntry,
@@ -113,19 +114,28 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
   const metaByName = new Map<string, ProjectMeta>(configured.map((m) => [m.name, m]))
   const needed = new Set<string>()
   const pending: ProjectMeta[] = []
+  // Counted, not read off `pending`: a round empties `pending`, and a guard
+  // on its length let every cross edge after the first round walk its
+  // whole closure again (1,500 walks at 300 projects, item 932).
+  let neededConfigured = 0
   const consider = (name: string): void => {
     if (needed.has(name)) return
     needed.add(name)
     const meta = metaByName.get(name)
-    if (meta) pending.push(meta)
+    if (meta) {
+      pending.push(meta)
+      neededConfigured++
+    }
   }
+  const walked = new Set<string>()
   const considerWithDeps = (name: string): void => {
     consider(name)
-    // Every config-bearing project already pending: the closure can add
-    // nothing, and asking for it would build the package graph's
+    // Every config-bearing project already considered: the closure can
+    // add nothing, and asking for it would build the package graph's
     // transitive bitsets — a cost the unscoped run (every project a seed)
-    // otherwise never pays.
-    if (pending.length === metaByName.size) return
+    // otherwise never pays. A closure already walked adds nothing either.
+    if (neededConfigured === metaByName.size || walked.has(name)) return
+    walked.add(name)
     for (const dep of packageGraph.transitiveDeps(name)) consider(dep)
   }
   const seeds = args.seeds === 'all' ? metaByName.keys() : [...args.seeds]
@@ -231,10 +241,11 @@ export async function loadResolvedProjects(
   opts: { scope?: 'all' | readonly string[]; warn?: (message: string) => void } = {},
 ): Promise<Map<string, ProjectEntry>> {
   const warn = opts.warn ?? ((): void => {})
-  const metas = await listProjects(await loadWorkspace(workspaceRoot))
+  const reads: LoadReads = new Map()
+  const metas = await listProjects(await loadWorkspace(workspaceRoot, reads))
   const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warn)
   const cacheDir = resolveCacheDir(workspaceRoot, workspaceConfig)
-  const cache = new Cache(cacheDir)
+  const cache = new Cache(cacheDir, { read: true, write: true }, workspaceRoot)
   noteSchemaReset(cache, warn)
   try {
     const loaded = await loadProjects({
@@ -248,7 +259,7 @@ export async function loadResolvedProjects(
       lock: null,
       evalCache: {
         store: cache,
-        workspaceFingerprint: await computeWorkspaceFingerprint(workspaceRoot),
+        workspaceFingerprint: await computeWorkspaceFingerprint(workspaceRoot, reads),
       },
       warn,
     })

package/src/orchestrator/remote-prefetch.ts

@@ -78,6 +78,11 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
   const present = (await args.cache.remoteHasMany?.(uniqueHashes)) ?? null
   if (present !== null) {
     args.cache.markRemoteAbsent?.(uniqueHashes.filter((h) => !present.has(h)))
+    // The pre-mark above already answers a pull for an absent hash from
+    // the in-flight map, so on the wire this filter is the pump's
+    // economy: deleting it alone GETs nothing extra, deleting both GETs
+    // every absent key. What it decides is which hashes the pump asks
+    // the layer for, and that is what the row pins (item 643, 645).
     toPrefetch = stableKeys.filter((k) => present.has(k.hash))
     if (toPrefetch.length === 0) return
   }
@@ -92,9 +97,24 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
     while (next < toPrefetch.length) {
       const { hash, node } = toPrefetch[next++]!
       await args.cache
-        .prefetch(hash, { taskId: node.id, command: node.config.exec?.command ?? '' })
+        .prefetch(hash, getContext(node, node.config.exec?.command ?? ''))
         .catch(() => false)
     }
   }
   await Promise.all(Array.from({ length: workers }, () => pump()))
 }
+
+/**
+ * What a cache lookup is told about the task: its id and command for the
+ * row a remote hit inserts, and its declared outputs, the only names a
+ * remote artifact may carry (item 942). Shared with execute-task's own
+ * lookup, the other one that can reach a remote.
+ */
+export function getContext(node: TaskNode, command: string) {
+  const outputs = node.config.cache?.outputs
+  return {
+    taskId: node.id,
+    command,
+    outputs: { files: outputs?.files ?? [], workspaceFiles: outputs?.workspaceFiles ?? [] },
+  }
+}

package/src/orchestrator/run-artifacts.ts

@@ -64,6 +64,15 @@ function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): Record<string, unknown
     ...(o.storedPeakRssBytes !== undefined ? { storedPeakRssBytes: o.storedPeakRssBytes } : {}),
     // Present only when an `admit` policy held the task with a worker free.
     ...(o.admissionHeldMs !== undefined ? { admissionHeldMs: o.admissionHeldMs } : {}),
+    // A skipped row names the failed (or aborted) task at the root of what
+    // blocked it; a fail-fast skip has none.
+    ...(o.blockedBy !== undefined ? { blockedBy: o.blockedBy } : {}),
+    // A failure vx's own `timeout` killed; absent on every other row.
+    ...(o.timedOut === true ? { timedOut: true } : {}),
+    // The sandbox's violation count; present only on a task it recorded any for.
+    ...(o.sandboxViolations !== undefined ? { sandboxViolations: o.sandboxViolations } : {}),
+    // A persistent task that never became ready, and why.
+    ...(o.notReady !== undefined ? { notReady: o.notReady } : {}),
     // hrtime spans are bigints → emit as strings so JSON.parse on
     // the consumer side doesn't truncate the ns precision.
     ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: String(o.wallclockStartNs) } : {}),

package/src/orchestrator/run-context.ts

@@ -11,7 +11,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { ulid, xxh3hex } from '../util/index.js'
+import { executablePath, ulid, xxh3hex } from '../util/index.js'
 
 export interface GitContext {
   /** `git rev-parse HEAD`, or null outside a repo / on failure. */
@@ -65,7 +65,15 @@ export function captureGitContext(
   }
   try {
     const proc = Bun.spawnSync({
-      cmd: ['git', '-C', workspaceRoot, 'rev-parse', 'HEAD', '--abbrev-ref', 'HEAD'],
+      cmd: [
+        executablePath('git'),
+        '-C',
+        workspaceRoot,
+        'rev-parse',
+        'HEAD',
+        '--abbrev-ref',
+        'HEAD',
+      ],
       stdout: 'pipe',
       stderr: 'ignore',
     })
@@ -205,7 +213,14 @@ export function captureDefaultBranch(
 
   try {
     const proc = Bun.spawnSync({
-      cmd: ['git', '-C', workspaceRoot, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD'],
+      cmd: [
+        executablePath('git'),
+        '-C',
+        workspaceRoot,
+        'symbolic-ref',
+        '--short',
+        'refs/remotes/origin/HEAD',
+      ],
       stdout: 'pipe',
       stderr: 'ignore',
     })
@@ -310,7 +325,7 @@ export function captureWorkspaceIdentity(workspaceRoot: string): WorkspaceIdenti
       // rewrites, so two developers mirroring the same repo through
       // different proxies would derive different workspace ids. The raw
       // configured URL is the identity.
-      cmd: ['git', '-C', workspaceRoot, 'config', '--get', 'remote.origin.url'],
+      cmd: [executablePath('git'), '-C', workspaceRoot, 'config', '--get', 'remote.origin.url'],
       stdout: 'pipe',
       stderr: 'ignore',
     })