@vzn/vx 0.0.635 → 0.0.637

package/src/orchestrator/doctor.ts

@@ -1,5 +1,5 @@
-// The workspace doctor's facts — what `vx info` prints and `vx mcp`'s
-// `getWorkspaceInfo` returns: versions, the git status cache, the
+// The workspace doctor's facts — what `vx info` prints and its JSON
+// returns: versions, the git status cache, the
 // workspace's shape, the plugins and the seams each fills, what a run
 // will use (workers, memory) and where those come from, the cache's
 // versions and state, the flaky tasks, the lock. One collector, so the
@@ -13,32 +13,27 @@ import {
   cgroupCpuQuota,
   cgroupMemoryLimitBytes,
   executablePath,
+  gitEnv,
   isUnsupportedBun,
+  isUserError,
   machineMemoryBytes,
   machineParallelism,
-  maskedLine,
   parseSize,
-  relPosix,
+  treeBytes,
 } from '../util/index.js'
+import { vxPath } from '../handoff.js'
 import { VERSION } from '../version.js'
 import { probeSandbox, resetSandbox, untracedReason } from '../exec/index.js'
 import {
-  computeWorkspaceFingerprint,
   findWorkspaceRoot,
-  type LoadReads,
-  loadWorkspace,
   lockfilePath,
   resolveCacheDir,
   resolveStoreRoot,
 } from '../workspace/index.js'
 import { flakyTasks, type FlakyTask } from './failure-mode.js'
 import type { VxPlugin } from './plugin.js'
-import {
-  discoverProjects,
-  type LoadProjectsArgs,
-  loadProjects,
-  loadWorkspacePlugins,
-} from './projects.js'
+import { discoverProjects, loadProjects, loadWorkspacePlugins, lockReader } from './projects.js'
+import { atPath, envName, resolveSetting, SETTINGS, type SettingSource } from '../settings.js'
 
 const warnToStderr = (message: string): void => {
   process.stderr.write(`${message}\n`)
@@ -47,6 +42,10 @@ const warnToStderr = (message: string): void => {
 /** The doctor's facts, typed: what `--format json` prints and the pretty rows render. */
 export interface InfoFacts {
   vx: string
+  /** The file that ran: the compiled binary, or the source entry. */
+  vxPath: string
+  /** The vx that handed this call to the project's own (`VX_HANDED_OFF`), else null. */
+  handedOffFrom: string | null
   bun: string
   /**
    * False when `bun` is below `MIN_BUN`. A separate field on purpose: `bun`
@@ -62,23 +61,16 @@ export interface InfoFacts {
   workspaceRoot: string
   projects: number
   tasks: number
-  /**
-   * The project configs that did not load, each with the loader's own
-   * message (the path stripped). A broken config counts as zero tasks
-   * rather than failing the doctor — and the doctor says which, since a
-   * `0 tasks` that hides a typo is the one fact a bug report needs.
-   */
-  configErrors: Array<{ path: string; message: string }>
   plugins: Array<{ name: string; seams: string[] }>
   /**
-   * The worker count a run defaults to and where it comes from: the
-   * workspace's `concurrency`, else the cores this process may use — the
+   * The worker count a run defaults to and where it comes from:
+   * `run.concurrency` (variable, then workspace), else the cores this process may use — the
    * CPU count capped by a cgroup quota (`cpuQuota`, in cores, null when
    * none binds).
    */
   workers: {
     count: number
-    source: 'workspace' | 'cgroup' | 'cores'
+    source: 'env' | 'workspace' | 'cgroup' | 'cores'
     cores: number
     cpuQuota: number | null
   }
@@ -88,13 +80,26 @@ export interface InfoFacts {
    */
   memory: { usableBytes: number; totalBytes: number; cgroupLimitBytes: number | null }
   cacheDir: string
+  /** Bytes on disk under `cacheDir`: the index and run history, and the entries when no store holds them. */
+  cacheDirBytes: number
   /** The shared store holding the entries, or null when `cacheDir` holds them. */
   cacheStore: string | null
+  /** Bytes on disk under `cacheStore`, shared by the repo's checkouts; null with no store. */
+  cacheStoreBytes: number | null
   cacheVersion: string
   schemaVersion: string
   cacheEntries: number
   cacheBytes: number
-  /** The workspace's `cacheRetention`, with `maxSize` in bytes; null when none is declared. */
+  /**
+   * Every setting (src/settings.ts) as a run with no flags takes it: its
+   * variable's value, else the workspace's (after the `config` stage),
+   * else null with source `default` (docs/schema.md names each default).
+   */
+  settings: Record<
+    string,
+    { value: string | number | boolean | null; source: 'env' | 'workspace' | 'default' }
+  >
+  /** `cache.retention`, with `maxSize` in bytes; null when none is set. */
   cacheRetention: { olderThan?: string; maxSize?: string; maxBytes?: number } | null
   orphans: { artifacts: number; bytes: number }
   runs24h: number
@@ -126,10 +131,9 @@ export interface CollectInfoOptions {
 
 export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): Promise<InfoFacts> {
   const warn = opts.warn ?? warnToStderr
-  const reads: LoadReads = new Map()
   // Both first: outside a workspace, or under a workspace config that does
   // not load, the doctor refuses at once, with no probe (~180 ms) ahead.
-  const root = await findWorkspaceRoot(cwd, reads)
+  const root = await findWorkspaceRoot(cwd)
   const workspace = await loadWorkspacePlugins(root, warn)
   // The sandbox probe asks nothing of the workspace, so it runs under the
   // loads below instead of after them. Awaited on every path: it resets
@@ -138,7 +142,7 @@ export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): P
   // Rejects only if the reset does; awaited below, never unhandled.
   probing.catch(() => {})
   try {
-    return await collectWorkspaceInfo(cwd, root, reads, workspace, opts, probing)
+    return await collectWorkspaceInfo(cwd, root, workspace, opts, probing)
   } catch (err) {
     // The workspace's refusal is the error worth reporting.
     await probing.catch(() => {})
@@ -149,7 +153,6 @@ export async function collectInfo(cwd: string, opts: CollectInfoOptions = {}): P
 async function collectWorkspaceInfo(
   cwd: string,
   root: string,
-  reads: LoadReads,
   { workspaceConfig, plugins }: Awaited<ReturnType<typeof loadWorkspacePlugins>>,
   opts: CollectInfoOptions,
   probing: Promise<Omit<InfoFacts['sandbox'], 'declared'>>,
@@ -159,7 +162,17 @@ async function collectWorkspaceInfo(
     opts.cacheDir === undefined
       ? resolveCacheDir(root, workspaceConfig)
       : path.resolve(cwd, opts.cacheDir)
-  const metas = await discoverProjects(await loadWorkspace(root, reads), plugins, cacheDir, warn)
+  // The lock's projects: none without a lock, or with one a run would
+  // refuse, which is `vx lock`'s to report.
+  const lock = lockReader(root)
+  const held = await lock().then(
+    () => true,
+    (err: unknown) => {
+      if (!isUserError(err)) throw err
+      return false
+    },
+  )
+  const metas = held ? await discoverProjects(root, lock, plugins, cacheDir, warn) : []
   const storeRoot =
     opts.cacheDir === undefined ? await resolveStoreRoot(root, workspaceConfig) : null
   const cache = new Cache(cacheDir, undefined, undefined, undefined, 'inspect', storeRoot)
@@ -168,45 +181,34 @@ async function collectWorkspaceInfo(
   let flaky: FlakyTask[]
   let taskCount = 0
   let sandboxed = 0
-  let configErrors: InfoFacts['configErrors'] = []
   try {
     stats = cache.stats()
     orphans = await cache.orphanStats()
     flaky = flakyTasks(cache.dbHandle())
-    // The run path's load — a plugin's `project` stage counts — so the
-    // doctor's task count is the number a run would see. A broken config
-    // must not take the doctor down with it: the count then falls back to
-    // the same load, one project at a time, the broken ones as zero.
-    const load = {
-      workspaceRoot: root,
-      cacheDir,
-      plugins,
-      projectMetas: metas,
-      closure: false,
-      lock: null,
-      evalCache: {
-        store: cache,
-        workspaceRoot: root,
-        workspaceFingerprint: await computeWorkspaceFingerprint(root, reads),
-      },
-      warn,
-    } as const
+    // The run path's load — the lock, a plugin's `project` stage counted —
+    // so the doctor's task count is the number a run would see. No lock, or
+    // one a run would refuse, counts zero: broken configs are `vx lock`'s
+    // to report.
     try {
-      const loaded = await loadProjects({ ...load, seeds: 'all' })
+      const loaded = await loadProjects({
+        workspaceRoot: root,
+        cacheDir,
+        plugins,
+        projectMetas: metas,
+        seeds: 'all',
+        closure: false,
+        configs: lock,
+        warn,
+      })
       for (const p of loaded.projects.values()) {
         const tasks = p.config.tasks ?? {}
         taskCount += Object.keys(tasks).length
         for (const t of Object.values(tasks)) if (t?.exec?.sandbox !== undefined) sandboxed++
       }
-    } catch {
-      // A config that will not load counts as zero, for both numbers: the
-      // sandbox row's "N tasks declare" must not read 0 because one other
-      // project's config is broken while this one's declares a sandbox.
-      ;({
-        tasks: taskCount,
-        sandboxed,
-        errors: configErrors,
-      } = await countLoadableTasks(load, root))
+    } catch (err) {
+      if (!isUserError(err)) throw err
+      taskCount = 0
+      sandboxed = 0
     }
   } finally {
     cache.close()
@@ -217,8 +219,11 @@ async function collectWorkspaceInfo(
   const git = gitVersion()
   const statusCache = gitStatusCache(root)
   const sandbox = { ...(await probing), declared: sandboxed }
+  const cacheStore = cache.storeDir ?? storeRoot
   return {
     vx: VERSION,
+    vxPath: vxPath(),
+    handedOffFrom: process.env['VX_HANDED_OFF'] ?? null,
     // An unsupported Bun does not stop a run, it makes the run's ANSWERS
     // wrong (util/bun-version.ts measures which). The row a reader already
     // consults for "is my setup sane" is where that belongs: a warning on
@@ -235,17 +240,19 @@ async function collectWorkspaceInfo(
     workspaceRoot: root,
     projects: metas.length,
     tasks: taskCount,
-    configErrors,
     // Which plugins loaded and which seams each fills, in pipeline order —
     // the answer to "why did this task run there / cache there / not at
     // all" before reading any config. A declined seam still costs nothing;
     // this names the declarations, not what a run consulted.
     plugins: plugins.map((p) => ({ name: p.name, seams: filledSeams(p) })),
-    workers: workersFact(workspaceConfig?.concurrency),
+    workers: workersFact(resolveSetting('run.concurrency', workspaceConfig)),
     memory: memoryFact(),
     cacheDir,
+    // On disk, not the index's sum: the size `vx cache clean` would free.
+    cacheDirBytes: treeBytes(cacheDir),
     // The store the index records, else the one a first run would open.
-    cacheStore: cache.storeDir ?? storeRoot,
+    cacheStore,
+    cacheStoreBytes: cacheStore === null ? null : treeBytes(cacheStore),
     // The two versions a bug report needs and the reset notice names: the
     // key prefix (a bump orphans every entry) and the index schema (a
     // mismatch drops every table).
@@ -253,9 +260,10 @@ async function collectWorkspaceInfo(
     schemaVersion: SCHEMA_VERSION,
     cacheEntries: stats.entryCount,
     cacheBytes: stats.totalBytes,
-    cacheRetention: retentionFact(workspaceConfig?.cacheRetention),
+    settings: settingsFact(workspaceConfig),
+    cacheRetention: retentionFact(workspaceConfig),
     // A row-less artifact is indexed again only when its task asks for its
-    // key; the rest only `vx cache prune` reclaims (after an upgrade's
+    // key; the rest only `vx cache clean` reclaims (after an upgrade's
     // schema reset, most often).
     orphans: { artifacts: orphans.orphans, bytes: orphans.orphanBytes },
     runs24h: stats.runCountLast24h,
@@ -313,11 +321,11 @@ function filledSeams(p: VxPlugin): string[] {
  * numbers would be the OOM killer's. The doctor says which one a run
  * reads, because nothing else would.
  */
-function workersFact(workspaceConcurrency: number | undefined): InfoFacts['workers'] {
+function workersFact(set: { value: unknown; source: SettingSource }): InfoFacts['workers'] {
   const cores = Math.max(1, navigator.hardwareConcurrency)
   const quota = process.platform === 'linux' ? (cgroupCpuQuota() ?? null) : null
-  if (workspaceConcurrency !== undefined) {
-    return { count: workspaceConcurrency, source: 'workspace', cores, cpuQuota: quota }
+  if (set.source === 'env' || set.source === 'workspace') {
+    return { count: set.value as number, source: set.source, cores, cpuQuota: quota }
   }
   const machine = machineParallelism()
   return { count: machine, source: machine < cores ? 'cgroup' : 'cores', cores, cpuQuota: quota }
@@ -339,6 +347,7 @@ function gitStatusCache(root: string): InfoFacts['gitStatusCache'] {
   try {
     const p = Bun.spawnSync({
       cmd: [executablePath('git'), 'config', '--get-regexp', '^core\\.(fsmonitor|untrackedcache)$'],
+      env: gitEnv(),
       cwd: root,
       stdout: 'pipe',
       stderr: 'pipe',
@@ -358,6 +367,7 @@ function gitVersion(): string | null {
   try {
     const p = Bun.spawnSync({
       cmd: [executablePath('git'), '--version'],
+      env: gitEnv(),
       stdout: 'pipe',
       stderr: 'pipe',
     })
@@ -371,52 +381,30 @@ function gitVersion(): string | null {
   }
 }
 
-async function countLoadableTasks(
-  load: Omit<LoadProjectsArgs, 'seeds'> & { closure: false },
-  root: string,
-): Promise<{ tasks: number; sandboxed: number; errors: InfoFacts['configErrors'] }> {
-  let tasks = 0
-  let sandboxed = 0
-  const errors: InfoFacts['configErrors'] = []
-  // No seeds loads nothing and answers which projects an 'all' load seeds.
-  const { configured } = await loadProjects({ ...load, seeds: [] })
-  await Promise.all(
-    configured.map(async (meta) => {
-      try {
-        const loaded = await loadProjects({ ...load, seeds: [meta.name] })
-        const declared = Object.values(loaded.projects.get(meta.name)?.config.tasks ?? {})
-        tasks += declared.length
-        for (const t of declared) if (t?.exec?.sandbox !== undefined) sandboxed++
-      } catch (err) {
-        // Counted as zero, and named: the loader's message opens with the
-        // absolute path — bare for a schema refusal, behind `Project config`
-        // for an import that failed, and with `:line:col` after it for a
-        // syntax error — which the row carries workspace-relative instead,
-        // once (the second form named the file twice, 2026-09-16; the third
-        // still did).
-        const raw = err instanceof Error ? err.message : String(err)
-        const bare = raw.startsWith('Project config ') ? raw.slice('Project config '.length) : raw
-        const where = meta.configPath ?? meta.dir
-        const message = bare.startsWith(`${where}:`)
-          ? bare.slice(where.length + 1).trimStart()
-          : raw
-        errors.push({
-          path: relPosix(root, where),
-          // A config's own throw is its author's text, a secret too (L-11).
-          message: maskedLine(message),
-        })
-      }
-    }),
-  )
-  errors.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
-  return { tasks, sandboxed, errors }
+function settingsFact(config: WorkspaceConfig | null): InfoFacts['settings'] {
+  const out: InfoFacts['settings'] = {}
+  for (const s of SETTINGS) {
+    const env = process.env[envName(s.path)]
+    const declared = s.config === false ? undefined : atPath(config, s.path)
+    out[s.path] =
+      env !== undefined && env !== ''
+        ? { value: env, source: 'env' }
+        : declared !== undefined
+          ? { value: declared as string | number | boolean, source: 'workspace' }
+          : { value: null, source: 'default' }
+  }
+  return out
 }
 
-function retentionFact(r: WorkspaceConfig['cacheRetention']): InfoFacts['cacheRetention'] {
-  if (r === undefined) return null
+function retentionFact(config: WorkspaceConfig | null): InfoFacts['cacheRetention'] {
+  const raw = (path: string): string | undefined =>
+    process.env[envName(path)] || (atPath(config, path) as string | undefined)
+  const olderThan = raw('cache.retention.olderThan')
+  const maxSize = raw('cache.retention.maxSize')
+  if (olderThan === undefined && maxSize === undefined) return null
   return {
-    ...(r.olderThan !== undefined ? { olderThan: r.olderThan } : {}),
-    // Validated at load, so it parses.
-    ...(r.maxSize !== undefined ? { maxSize: r.maxSize, maxBytes: parseSize(r.maxSize)! } : {}),
+    ...(olderThan !== undefined ? { olderThan } : {}),
+    // Validated before the run (env) or at load (workspace), so it parses.
+    ...(maxSize !== undefined ? { maxSize, maxBytes: parseSize(maxSize)! } : {}),
   }
 }

package/src/orchestrator/download-policy.ts

@@ -1,4 +1,4 @@
-// `--download` policy: which tasks may leave their outputs in the remote
+// `--cache-download` policy: which tasks may leave their outputs in the remote
 // store instead of landing them on this machine, and which must not.
 //
 // See docs/design/download-policy-cas-cache-2026-08.md. Two decisions live
@@ -27,7 +27,7 @@ export type DownloadMode = 'eager' | 'deferred' | 'never'
  * (the shape the design doc first sketched): that rule fires whenever a
  * sibling reads the project at all, which is every ordinary workspace —
  * `test` reads `src/**` while `build` writes `dist/**` — and would leave
- * `--download=none` with nothing to defer. Comparing the globs' static
+ * `--cache-download=none` with nothing to defer. Comparing the globs' static
  * prefixes answers the question actually being asked, and stays
  * conservative in every direction that matters: a leading wildcard yields
  * `.` and reaches everything, a cacheable task with no declared `files`
@@ -176,7 +176,7 @@ export function resolveDownloadModes(args: {
     //
     // SURFACED counts as asked-for. A requested GROUP has no outputs of its
     // own — `markSurfacedDeps` marks the real tasks it chains — so keying on
-    // `requested` alone made `vx run ci --download=toplevel` (ci being a
+    // `requested` alone made `vx run ci --cache-download=toplevel` (ci being a
     // group) bring home NOTHING, which is the one thing the mode exists to
     // avoid. run.ts already pairs the two flags for the same reason when it
     // decides which persistent children to keep alive.

package/src/orchestrator/events.ts

@@ -254,6 +254,8 @@ export interface OutcomeView {
   timedOut?: true
   /** A persistent task that never became ready, and why (see `TaskOutcome`). */
   notReady?: 'timeout' | 'exited' | 'spawn'
+  /** The input that changed while the command ran (see `TaskOutcome`). */
+  inputMoved?: string
   /** A skipped task: the failed (or aborted) task at the root of the block
    *  (see `TaskOutcome`); absent for fail-fast's skip, which nothing blocked. */
   blockedBy?: string
@@ -301,11 +303,18 @@ export function outcomeWord(o: Pick<OutcomeView, 'status' | 'restored'>): string
 export function outcomeLabel(
   o: Pick<
     OutcomeView,
-    'status' | 'restored' | 'exitCode' | 'timedOut' | 'sandboxViolations' | 'notReady' | 'blockedBy'
+    | 'status'
+    | 'restored'
+    | 'exitCode'
+    | 'timedOut'
+    | 'sandboxViolations'
+    | 'notReady'
+    | 'inputMoved'
+    | 'blockedBy'
   >,
 ): string {
   if (o.status === 'failed')
-    return failedLabel(o.exitCode, o.timedOut, o.sandboxViolations, o.notReady)
+    return failedLabel(o.exitCode, o.timedOut, o.sandboxViolations, o.notReady, o.inputMoved)
   if (o.status === 'skipped') return skippedLabel(o.blockedBy)
   return outcomeWord(o)
 }
@@ -330,7 +339,9 @@ export function skippedLabel(blockedBy: string | undefined): string {
  * status line, the run report, the Actions annotation): the exit code, and
  * above 128 the signal it stands for — `failed (exit 137, 128 + SIGKILL)` —
  * or, for vx's own timeout, `failed (timed out, exit 143)`, or a persistent
- * task that never became ready, `failed (never ready: timed out, exit 1)`; a
+ * task that never became ready, `failed (never ready: timed out, exit 1)`,
+ * or an input changed under `inputStability.severity: 'error'`,
+ * `failed (src/a.ts changed during the run, exit 1)`; a
  * sandboxed task's violations are counted after: `failed (exit 1, 2 sandbox
  * violations)`.
  */
@@ -339,6 +350,7 @@ export function failedLabel(
   timedOut?: true,
   sandboxViolations?: number,
   notReady?: 'timeout' | 'exited' | 'spawn',
+  inputMoved?: string,
 ): string {
   // A sandboxed task that touched what it never declared fails on that
   // alone (its exit is forced to 1 when it was 0): the count is the reason.
@@ -353,6 +365,9 @@ export function failedLabel(
       notReady === 'timeout' ? 'timed out' : notReady === 'exited' ? 'exited' : 'spawn failed'
     return `failed (never ready: ${why}, exit ${exitCode}${violations})`
   }
+  // `inputStability.severity: 'error'` forced the 1: the input is the reason.
+  if (inputMoved !== undefined)
+    return `failed (${inputMoved === '' ? 'an input' : inputMoved} changed during the run, exit ${exitCode}${violations})`
   // A timeout's 143 is vx's own SIGTERM: the reason, not the signal, reads.
   if (timedOut === true) return `failed (timed out, exit ${exitCode}${violations})`
   const signal = exitSignal(exitCode)
@@ -398,6 +413,7 @@ export function projectOutcome(outcome: TaskOutcome): OutcomeView {
   if (outcome.saveMs !== undefined) view.saveMs = outcome.saveMs
   if (outcome.timedOut === true) view.timedOut = true
   if (outcome.notReady !== undefined) view.notReady = outcome.notReady
+  if (outcome.inputMoved !== undefined) view.inputMoved = outcome.inputMoved
   if (outcome.blockedBy !== undefined) view.blockedBy = outcome.blockedBy
   if (outcome.restored !== undefined) view.restored = outcome.restored
   if (outcome.sandboxViolations !== undefined) view.sandboxViolations = outcome.sandboxViolations

package/src/orchestrator/excluded-keys.ts

@@ -25,7 +25,6 @@ export interface KeyExcludedArgs {
   dropped: ReadonlyMap<string, readonly string[]>
   cache: CacheLayer
   workspaceRoot: string
-  workspaceFingerprint: string
   forwardArgs?: readonly string[] | undefined
   nestedDirsByProject: ReadonlyMap<string, string[]>
   gitFilesCache: GitFilesCache
@@ -57,7 +56,6 @@ export async function keyExcludedDependencies(args: KeyExcludedArgs): Promise<vo
       node,
       upstream,
       workspaceRoot: args.workspaceRoot,
-      workspaceFingerprint: args.workspaceFingerprint,
       cache: args.cache,
       forwardArgs: args.forwardArgs,
       nestedProjectDirs: args.nestedDirsByProject.get(node.projectName) ?? [],