@vzn/vx 0.0.595 → 0.0.597

package/src/orchestrator/miss-save.ts

@@ -70,8 +70,8 @@ export interface SaveMissArgs {
   nestedProjectDirs: string[]
   gitFilesCache?: GitFilesCache | undefined
   /** Declared `cache.outputs.files` / `.workspaceFiles`. */
-  outputs: string[]
-  wsOutputs: string[]
+  outputs: readonly string[]
+  wsOutputs: readonly string[]
   /**
    * An ADDITIVE task's own set (item 588): the files its run added or
    * changed under its declared outputs, resolved by execute-task against
@@ -148,11 +148,9 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
     // `cache.outputs` is not a write grant; `exec.sandbox.allow.write` is.
     const sandboxed = node.config.exec?.sandbox !== undefined
     const grantsWrite = (node.config.exec?.sandbox?.allow?.write?.length ?? 0) > 0
-    // The workspace side too: a `workspaceFiles` directory linked out of
-    // the workspace drops every file the same way (M-65).
-    const linkedOut =
-      outputDirLinkedOut(node.projectDir, a.outputs, 'the project') ??
-      outputDirLinkedOut(a.workspaceRoot, a.wsOutputs, 'the workspace')
+    // A `workspaceFiles` directory linked out of the workspace drops every
+    // file (M-65); a project one is refused by the resolver (X-88).
+    const linkedOut = outputDirLinkedOut(a.workspaceRoot, a.wsOutputs)
     log.status(
       `[vx] ${node.id}: cache.outputs matched no files (${[...a.outputs, ...a.wsOutputs].join(', ')}) — ` +
         `an empty artifact is saved; a later hit restores nothing` +
@@ -300,15 +298,13 @@ function markWritten(
 }
 
 /**
- * The first output directory a pattern names that is a symlink resolving
- * outside `baseDir` (the project, or the workspace root for
- * `workspaceFiles`): every file under it is dropped as outside, and the
- * empty-artifact warning blamed the glob (M-61, M-65).
+ * The first `workspaceFiles` directory that is a symlink resolving outside
+ * the workspace root: every file under it is dropped as outside, and the
+ * empty-artifact warning blamed the glob (M-65).
  */
 function outputDirLinkedOut(
   baseDir: string,
   outputs: readonly string[],
-  base: string,
 ): { dir: string; target: string; base: string } | undefined {
   const realProject = realpathOrNull(baseDir) ?? baseDir
   // `dist` names the tree `dist/**`: the same reading the resolver gives.
@@ -326,7 +322,7 @@ function outputDirLinkedOut(
       }
       const target = realpathOrNull(abs)
       if (target !== null && target !== realProject && !target.startsWith(realProject + path.sep)) {
-        return { dir, target, base }
+        return { dir, target, base: 'the workspace' }
       }
     }
   }

package/src/orchestrator/options.ts

@@ -171,6 +171,13 @@ export interface RunOptions {
    * else is treated as the literal file path (cwd-relative).
    */
   summarize?: string
+  /**
+   * Text printed just above the run's footer, given the outcomes the
+   * footer counts, after the `summaryTable`: nothing prints below the
+   * footer (owner), so a caller's end-of-run report (`--report`) rides
+   * here. Not called on a refused run.
+   */
+  beforeFooter?: (outcomes: readonly TaskOutcome[], ok: boolean) => string
   /**
    * If set, write a Chrome-trace JSON profile of the run's wallclock
    * spans. Path is cwd-relative. Default `profile.json` is selected

package/src/orchestrator/plan.ts

@@ -12,17 +12,12 @@
 // side-effect-free pure probes.
 
 import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
-import { FULL_CACHE_POLICY } from '../cache/index.js'
-import {
-  idleServers,
-  isGroupTask,
-  runGraph,
-  type TaskNode,
-  type TaskOutcome,
-} from '../graph/index.js'
+import { cachesNothing, FULL_CACHE_POLICY } from '../cache/index.js'
+import { ranNoCache } from './events.js'
+import { idleServers, isGroupTask, runGraph, type TaskNode } from '../graph/index.js'
 import type { HistoryProvider } from './history.js'
 import { computeGroupKey, computeTaskHash } from './task-hash.js'
-import { keyUpstream } from './upstream.js'
+import { keyedOutcome, keyUpstream } from './upstream.js'
 
 export type CacheStatus =
   | 'hit-local' // entry exists in local cache
@@ -156,7 +151,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       }
       if (isGroupTask(node)) {
         cacheStatusById.set(node.id, 'group')
-        return planOutcome(node, await computeGroupKey(hashArgs))
+        return keyedOutcome(node, await computeGroupKey(hashArgs))
       }
 
       const hash = await computeTaskHash(hashArgs)
@@ -169,9 +164,8 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       // policy-aware cache layer, which itself respects read gating.
       const policy = args.cachePolicy ?? FULL_CACHE_POLICY
       const reads = policy.localRead || policy.remoteRead
-      const writes = policy.localWrite || policy.remoteWrite
       let status: CacheStatus
-      if (node.config.cache === undefined || (!reads && !writes)) {
+      if (ranNoCache({ node, cacheOff: cachesNothing(policy) })) {
         status = 'no-cache'
       } else if (!reads) {
         status = 'miss'
@@ -180,7 +174,7 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
         status = where === null ? 'miss' : where === 'remote' ? 'hit-remote' : 'hit-local'
       }
       cacheStatusById.set(node.id, status)
-      return planOutcome(node, hash)
+      return keyedOutcome(node, hash)
     },
   })
 
@@ -303,13 +297,3 @@ function predictPlan(tasks: PlannedTask[]): PlanPrediction {
   }
   return { wallMs, workMs, unknownCount }
 }
-
-function planOutcome(node: TaskNode, hash: string | undefined): TaskOutcome {
-  return {
-    node,
-    status: 'success',
-    exitCode: 0,
-    durationMs: 0,
-    ...(hash !== undefined ? { hash } : {}),
-  }
-}

package/src/orchestrator/plugin.ts

@@ -142,9 +142,9 @@ export interface VxPlugin {
    * many times per run, so it must be cheap and synchronous; a throw, or
    * an answer that is a Promise, is reported once and the plugin admits
    * from then on — a policy never
-   * breaks a run. Restore-tier hits and tasks on an executor pool hold no
-   * local resources and are never asked. When several plugins answer, all
-   * must admit. Core keeps no notion of what a task needs: a plugin that
+   * breaks a run. Restore-tier hits, tasks on an executor pool and groups
+   * hold no local resources: never asked, never in `ctx.running`. When
+   * several plugins answer, all must admit. Core keeps no notion of what a task needs: a plugin that
    * packs memory or CPU learns or declares the numbers itself
    * (`@vzn/vx-schedule-history` packs what past executions used).
    */
@@ -341,7 +341,12 @@ export interface FingerprintContext extends BaseContext {
 }
 
 export interface AdmitContext {
-  /** The tasks executing on this machine right now, in dispatch order. */
+  /**
+   * The tasks holding a worker on this machine right now, in dispatch
+   * order. A persistent task leaves at ready, when it gives its worker
+   * back: it runs until the graph ends, so a policy that counted it would
+   * hold its dependants with no completion left to ask again.
+   */
   readonly running: readonly TaskNode[]
   /** The run's worker count — the ceiling the count gate already applies. */
   readonly concurrency: number
@@ -601,7 +606,8 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
   const { plugins, bus, workspaceRoot, cacheDir } = args
   const warn = args.warn ?? ((m) => console.error(m))
   const disposers: Array<() => void> = []
-  const disabled = new Set<string>()
+  // By object, not name: one package can export two plugins.
+  const disabled = new Set<Plugin>()
 
   for (const plugin of plugins) {
     if (typeof plugin.name !== 'string' || plugin.name.length === 0) {
@@ -615,6 +621,13 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       throw new UserError(`plugin '${plugin.name}' setup is not a function`)
     }
 
+    const fail = (where: string, err: unknown): void => {
+      if (disabled.has(plugin)) return
+      disabled.add(plugin)
+      warn(
+        `[vx] plugin '${plugin.name}' threw in ${where}; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
     const ctx: PluginContext = {
       workspaceRoot,
       cacheDir,
@@ -625,7 +638,18 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
       bus: {
         emit: (event) => bus.emit(event),
         subscribe(subscriber) {
-          const dispose = bus.subscribe(subscriber)
+          // Isolated like an `on` handler: the bus itself swallows a throw.
+          const dispose = bus.subscribe((event) => {
+            if (disabled.has(plugin)) return
+            let ret: unknown
+            try {
+              ret = subscriber(event)
+            } catch (err) {
+              fail('a bus subscriber', err)
+              return
+            }
+            if (ret instanceof Promise) ret.catch((err: unknown) => fail('a bus subscriber', err))
+          })
           disposers.push(dispose)
           return dispose
         },
@@ -638,15 +662,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
             `ctx.on: unknown hook '${String(hook)}' (one of ${Object.keys(HOOK_NAMES).join(', ')})`,
           )
         }
-        const fail = (err: unknown): void => {
-          if (disabled.has(plugin.name)) return
-          disabled.add(plugin.name)
-          warn(
-            `[vx] plugin '${plugin.name}' threw in ${hook}; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
-          )
-        }
+        const onFail = (err: unknown): void => fail(hook, err)
         const dispose = bus.subscribe((event) => {
-          if (disabled.has(plugin.name)) return
+          if (disabled.has(plugin)) return
           // Not awaited: the bus is synchronous and plugin work runs off the
           // critical path. A handler's rejection is caught like its throw.
           let ret: unknown
@@ -681,10 +699,10 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
                 break
             }
           } catch (err) {
-            fail(err)
+            onFail(err)
             return
           }
-          if (ret instanceof Promise) ret.catch(fail)
+          if (ret instanceof Promise) ret.catch(onFail)
         })
         disposers.push(dispose)
       },
@@ -693,6 +711,9 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
     try {
       await plugin.setup(ctx)
     } catch (err) {
+      // Earlier plugins' subscriptions too: the caller never gets the
+      // disposer, and a bus that outlives the run would keep them.
+      for (const d of disposers) d()
       throw new PluginSetupError(
         plugin,
         `plugin '${plugin.name}' failed in setup: ${err instanceof Error ? err.message : String(err)}`,

package/src/orchestrator/prepare.ts

@@ -368,8 +368,11 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     ? options.projects.filter((p) => projects.has(p))
     : [...projects.keys()]
 
-  const requested = expandRequested(tasks, candidateProjects, projects)
-  let unresolvedTasks = unresolvedRequests(tasks, candidateProjects, projects)
+  // A bare name skips the default `build`: it runs nothing, and matched,
+  // `vx run build` in a project declaring none ran 0 tasks, exit 0 (X-102).
+  // A dependant's `^build` still reaches it, and `lib#build` names it.
+  const requested = expandRequested(tasks, candidateProjects, projects, isDefaultBuild)
+  let unresolvedTasks = unresolvedRequests(tasks, candidateProjects, projects, isDefaultBuild)
   if (options.selectedByDiff === true && unresolvedTasks.some((t) => !t.includes('#'))) {
     // A name a loaded project declares is no typo, whether or not the load
     // was whole: an unaffected dependency loaded for the closure declared
@@ -750,14 +753,20 @@ async function declaredNowhere(
   return undeclaredIn(unresolved, all.projects)
 }
 
-/** The bare names in `unresolved` no project in `projects` declares; `a#b` forms pass through. */
+/**
+ * The bare names in `unresolved` no project in `projects` declares; `a#b`
+ * forms pass through. Every project has a `build`, its default one if
+ * nothing declares it, and a bare name does not select that (X-102).
+ */
 function undeclaredIn(
   unresolved: readonly string[],
   projects: LoadedProjects['projects'],
 ): string[] {
   const declared = new Set<string>()
   for (const p of projects.values()) {
-    for (const t of Object.keys(p.config.tasks ?? {})) declared.add(t)
+    for (const [t, task] of Object.entries(p.config.tasks ?? {})) {
+      if (!isDefaultBuild(task)) declared.add(t)
+    }
   }
   return unresolved.filter((t) => t.includes('#') || !declared.has(t))
 }

package/src/orchestrator/run-artifacts.ts

@@ -18,6 +18,7 @@ import { isGroupTask, type TaskOutcome } from '../graph/index.js'
 import { tallyOutcomes, type Tally } from './tally.js'
 import type { FlakyFinding } from './failure-mode.js'
 import { isCacheHit } from './telemetry.js'
+import { ranNoCache } from './events.js'
 
 export interface SummarizeArgs {
   /** Empty string → default path; otherwise the explicit file path. */
@@ -92,9 +93,9 @@ function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): SummaryTaskJson {
     // the flag a consumer computing a hit rate cannot tell a miss from a
     // task that could never hit (its `hash` is still set — dependents fold
     // it). Present only when true, so every other row is byte-identical.
-    ...(o.node.config.cache === undefined ? { noCache: true } : {}),
-    // Present only when the run proved the task flaky: this exact key has
-    // both passed and failed on record (this run counted), or the task
+    ...(ranNoCache(o) ? { noCache: true } : {}),
+    // Present only when the run proved the task flaky: this exact key
+    // failed after it had passed (this run counted), or the task
     // needed a retry. A consumer gating on `failed` can tell a break from a
     // flake without the history; every other row is byte-identical.
     ...(flaky !== undefined

package/src/orchestrator/run-lock.ts

@@ -43,7 +43,8 @@
 // waited for itself forever (nx#36473 reproduced on vx, 2026-09-24). So a
 // lock naming OUR pid is stale unless this process placed that entry and
 // has not left it (`placed`) — and on Linux the entry also carries the holder's start
-// time, so a pid another process now wears is stale too. Where the lock
+// time, so a pid another process now wears is stale too, and so is a
+// holder procfs shows as a zombie (killed, not yet reaped). Where the lock
 // cannot be made or read for any reason but "held" (a temp directory this
 // user cannot write), the run says so once and proceeds unlocked: the
 // lock is a courtesy between cooperating runs, and refusing to run would
@@ -183,7 +184,7 @@ function ownLockRoot(lockDir: string): void {
 
 interface Holder {
   pid: number
-  /** The holder's start time as `startTime` read it; null where the lock names none. */
+  /** The holder's start time as `procStat` read it; null where the lock names none. */
   start: string | null
   /** The entry in the lock directory that names it. */
   entry: string
@@ -223,17 +224,18 @@ async function holder(lockDir: string): Promise<Holder | 'free' | null> {
 }
 
 /**
- * When a process started, in clock ticks since boot: field 22 of
- * `/proc/<pid>/stat`. Two processes that wore one pid differ here. Null
- * off Linux, where the answer costs a `ps` spawn per run, under a procfs
- * mounted for another pid namespace, and for a pid procfs does not show.
+ * `/proc/<pid>/stat` from field 3 on: the state first, and at [19] field
+ * 22, the start time in clock ticks since boot, where two processes that
+ * wore one pid differ. Null off Linux, where the answer costs a `ps`
+ * spawn, under a procfs mounted for another pid namespace, and for a pid
+ * procfs does not show.
  */
-function startTime(pid: number | 'self'): string | null {
+function procStat(pid: number | 'self'): string[] | null {
   if (!procfsIsOwn()) return null
   try {
     const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
     // Fields after the LAST ')' start at field 3; comm may hold spaces.
-    return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] ?? null
+    return stat.slice(stat.lastIndexOf(')') + 2).split(' ')
   } catch {
     return null
   }
@@ -244,21 +246,24 @@ let ownId: string | undefined
 /** Tells this process's takings of a lock apart, and their staging names. */
 let takings = 0
 function nextEntry(): string {
-  ownId ??= `h-${process.pid}-${startTime('self') ?? 'x'}`
+  ownId ??= `h-${process.pid}-${procStat('self')?.[19] ?? 'x'}`
   return `${ownId}-${++takings}`
 }
 
 /**
- * Is the lock's holder a live run of another process? `sameAsLast`: this
- * holder's start time already matched on an earlier poll, so a wait reads
- * procfs once per holder, not once per poll.
+ * Is the lock's holder a live run of another process? Read on every poll:
+ * a holder killed whose parent does not reap it (a container's pid 1 that
+ * never waits) is a zombie, which signal 0 still reaches and whose start
+ * time still matches, and a wait that trusted either waited for it until
+ * the reaper came, or for good.
  */
-function holderLive(h: Holder, sameAsLast: boolean): boolean {
+function holderLive(h: Holder): boolean {
   if (h.pid === process.pid) return placed.has(h.entry)
   if (!alive(h.pid)) return false
-  if (h.start === null || sameAsLast) return true
-  const now = startTime(h.pid)
-  return now === null || now === h.start
+  const stat = procStat(h.pid)
+  if (stat === null) return true
+  if (stat[0] === 'Z' || stat[0] === 'X') return false
+  return h.start === null || stat[19] === h.start
 }
 
 function alive(pid: number): boolean {
@@ -326,7 +331,6 @@ export async function acquireRunLock(
   const lockDir = runLockPath(workspaceRoot, opts.dir)
   const started = Date.now()
   let said = false
-  let lastLive: Holder | undefined
   const release = async (): Promise<void> => {
     const left = (heldHere.get(lockDir) ?? 1) - 1
     if (left > 0) {
@@ -377,7 +381,7 @@ export async function acquireRunLock(
           await rm(lockDir, { recursive: true, force: true })
           continue
         }
-      } else if (!holderLive(h, lastLive?.entry === h.entry && lastLive.start === h.start)) {
+      } else if (!holderLive(h)) {
         if (h.entry === LEGACY_PID) await rm(lockDir, { recursive: true, force: true })
         else await leave(lockDir, h.entry)
         continue
@@ -391,12 +395,9 @@ export async function acquireRunLock(
       )
       return async () => {}
     }
-    if (h !== null) {
-      lastLive = h
-      if (!said && Date.now() - started >= SAY_AFTER_MS) {
-        said = true
-        opts.log(`[vx] waiting for another vx run (pid ${h.pid}) on this workspace to finish…`)
-      }
+    if (h !== null && !said && Date.now() - started >= SAY_AFTER_MS) {
+      said = true
+      opts.log(`[vx] waiting for another vx run (pid ${h.pid}) on this workspace to finish…`)
     }
     await Bun.sleep(POLL_MS)
   }

package/src/orchestrator/run.ts

@@ -6,7 +6,13 @@ import type { ProjectEntry } from '../workspace/index.js'
 import { loadWorkspace, unreachedHint, unreachedPackages } from '../workspace/index.js'
 import { realpathSync } from 'node:fs'
 import path from 'node:path'
-import { Cache, type CacheLayer, type CachePolicy, stopRuntimeProbes } from '../cache/index.js'
+import {
+  Cache,
+  type CacheLayer,
+  type CachePolicy,
+  cachesNothing,
+  stopRuntimeProbes,
+} from '../cache/index.js'
 import { VERSION } from '../version.js'
 import {
   resetSandbox,
@@ -44,6 +50,7 @@ import {
   secretMask,
 } from '../util/index.js'
 import { keyedProjects } from './keyed-projects.js'
+import { isDefaultBuild } from './projects.js'
 import { prepareSandbox } from './sandbox-request.js'
 import type { OutputDirSnapshot, SaveFacts } from './miss-save.js'
 import { admitTasks, taintTracker } from './admission.js'
@@ -624,6 +631,7 @@ async function runOnBus(
       stopRun.abort(signal)
     },
     done: runLeft,
+    handsTerminal: holders.size > 0,
     // The grace, then one flush and each teardown at their own bound, and
     // slack for the summary and the cache close.
     boundMs:
@@ -1017,6 +1025,7 @@ async function runOnBus(
     // is one probe of the failed-row index.
     const flaky: FlakyFinding[] = []
     const historyDb = prepared.localCache.dbHandle()
+    const cacheOff = cachesNothing(policy)
     const judgeFlaky = (o: TaskOutcome): void => {
       const candidates = flakyCandidates([o])
       if (candidates.length === 0) return
@@ -1044,6 +1053,7 @@ async function runOnBus(
         log.taskStart?.(node)
       },
       onFinish: (o) => {
+        if (cacheOff) o.cacheOff = true
         taint.settled(o)
         judgeFlaky(o)
         log.taskComplete(o.node, o)
@@ -1346,6 +1356,8 @@ async function runOnBus(
     // task's own facts (flaky, blocked) ride its row. Only a kept server's
     // own output follows.
     if (options.summaryTable === true) for (const line of formatOutcomeTable(list)) log.status(line)
+    const above = options.beforeFooter?.(list, ok)
+    if (above) log.status(above.replace(/\n$/, ''))
     for (const line of formatRunSummary(list, totalMs, colors, runContext)) log.status(line)
 
     // Edge case the summary already reported: the user requested a
@@ -1430,7 +1442,9 @@ async function runOnBus(
       await summarize(ok && first.code === 0, final)
       if (historyAfterWait) {
         recordHistory(() => {
-          const local = Cache.inspect(prepared.cacheDir)
+          // A writer's open: another vx version may have reset the index
+          // to its schema during the session, and a mismatch resets silently.
+          const local = new Cache(prepared.cacheDir, undefined, prepared.workspaceRoot)
           try {
             local.recordRunBundle(recordsOf(final, ok && first.code === 0))
           } finally {
@@ -1632,7 +1646,7 @@ async function initHint(prepared: {
   // Single-project mode with packages the root's missing `workspaces`
   // never reaches: `vx init` would find no scripts either (item 248).
   const unreached = await unreachedPackages(await loadWorkspace(prepared.workspaceRoot))
-  if (unreached.length > 0) return ` ${unreachedHint(unreached)}`
+  if (unreached.length > 0) return ` ${unreachedHint(unreached, prepared.workspaceRoot)}`
   return ' No package declares a vx.config — run `vx init` to write one per package from its package.json scripts.'
 }
 
@@ -1649,8 +1663,11 @@ function didYouMean(
   elsewhere: readonly string[] = [],
 ): string {
   const tasksOf = (p: ProjectEntry | undefined): string[] => Object.keys(p?.config.tasks ?? {})
+  // What a bare name can select: a default `build` is no match (X-102).
   const allTasks = new Set<string>()
-  for (const p of projects.values()) for (const t of tasksOf(p)) allTasks.add(t)
+  for (const p of projects.values()) {
+    for (const t of tasksOf(p)) if (!isDefaultBuild(p.config.tasks![t])) allTasks.add(t)
+  }
   // A Set: two typos of the same task hint it once, not once per typo.
   const hints = new Set<string>()
   // A typo past two edits named nothing to pick from (M-56): with no near
@@ -1746,7 +1763,7 @@ function flakyCandidates(outcomes: readonly TaskOutcome[]): FlakyCandidate[] {
   const out: FlakyCandidate[] = []
   for (const o of outcomes) {
     if (o.status !== 'success' && o.status !== 'failed') continue
-    // "Same inputs, different outcome" is a claim only a task with declared
+    // "Same inputs, failed after passing" is a claim only a task with declared
     // inputs can make: a task with no `cache` block keys on its config alone
     // and runs every time, so one bad network day would read as a flake for
     // thirty days. Groups do no work.