@vzn/vx 0.0.636 → 0.0.638

package/src/handoff.ts

@@ -0,0 +1,169 @@
+// A global vx hands off to the project's own (owner, 2026-10-13), found
+// from the workspace root, the one lookup every verb shares. Here for
+// the compiled binary installed by hand; an npm install's launcher
+// (npm-launcher.sh) walks the same way and `exec`s, which Bun cannot. The
+// walk runs before anything else loads, through `Bun.file(…).exists()`:
+// importing `node:fs` alone was ~1.1 ms of a 4 ms start (2026-10-13).
+
+/**
+ * The project-local vx to run instead of this one, or null: the workspace
+ * root's ({@link workspaceFile}) `node_modules/@vzn/vx`, run through its
+ * `.bin/vx`. Null once handed
+ * off (one hop), for a vx that is not a standalone compiled binary (source;
+ * an npm install, whose launcher already walked), outside a workspace,
+ * when the local one is this binary, and when another user owns it.
+ */
+export async function localVx(
+  cwd: string,
+  execPath: string,
+  compiled: boolean,
+  uid = process.getuid?.(),
+): Promise<string | null> {
+  if (process.env['VX_HANDED_OFF'] !== undefined || !compiled) return null
+  if (execPath.includes('/node_modules/')) return null
+  const file = await workspaceFile(cwd)
+  if (file === null) return null
+  const root = workspaceRootOf(file)
+  if (!(await Bun.file(`${root}/node_modules/@vzn/vx/package.json`).exists())) return null
+  const bin = `${root}/node_modules/.bin/vx`
+  const { realpathSync, statSync } = await import('node:fs')
+  try {
+    const real = realpathSync(bin)
+    // One another user planted would run as you.
+    if (statSync(real).uid !== uid) return null
+    return real === realpathSync(execPath) ? null : bin
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The workspace config's paths under the root, in lookup order: one marks
+ * the workspace root, the directory holding its `.vx` (owner, 2026-10-14).
+ */
+export const WORKSPACE_CONFIG_FILENAMES = [
+  '.vx/workspace.ts',
+  '.vx/workspace.mts',
+  '.vx/workspace.js',
+  '.vx/workspace.mjs',
+  // A CommonJS config (`module.exports = …`), as Vite and TS name theirs: it
+  // was ignored without a word (D-86).
+  '.vx/workspace.cts',
+  '.vx/workspace.cjs',
+]
+
+/** The workspace root a workspace config marks: the directory above its `.vx`. */
+export function workspaceRootOf(file: string): string {
+  return file.slice(0, file.lastIndexOf('/.vx/')) || '/'
+}
+
+const files = new Map<string, Promise<string | null>>()
+
+/**
+ * The workspace config that marks the root for `dir`: the first
+ * `.vx/workspace.*` from `dir` up to the git top-level ({@link gitTop}),
+ * inclusive, or to `/` outside git (owner, 2026-10-13: "Workspace file is
+ * the ultimate" and "never go out of git root"). Null when there is none.
+ * Learned once per directory per run: the hand-off and the workspace root
+ * share it (principle 9).
+ */
+export function workspaceFile(dir: string): Promise<string | null> {
+  let file = files.get(dir)
+  if (file === undefined) {
+    file = findWorkspaceFile(dir)
+    files.set(dir, file)
+  }
+  return file
+}
+
+/** vx wrote a workspace config (`vx init`): what was learned before it is stale. */
+export function workspaceFileWritten(): void {
+  files.clear()
+}
+
+async function findWorkspaceFile(start: string): Promise<string | null> {
+  const top = await gitTop(start)
+  const passed: string[] = []
+  let found: string | null = null
+  walk: for (let d = start; ; d = d.slice(0, d.lastIndexOf('/'))) {
+    passed.push(d || '/')
+    for (const name of WORKSPACE_CONFIG_FILENAMES) {
+      const file = `${d}/${name}`
+      if (await Bun.file(file).exists()) {
+        found = file
+        break walk
+      }
+    }
+    if (d === '' || d === top) break
+  }
+  // Every directory walked has the same answer: the loader asks for the root's.
+  for (const d of passed) if (!files.has(d)) files.set(d, Promise.resolve(found))
+  return found
+}
+
+const tops = new Map<string, Promise<string | null>>()
+
+/**
+ * The git top-level holding `dir`, or null outside git: the nearest `.git`
+ * up from it, a directory in a clone, a file in a worktree. A submodule's
+ * `.git` file points into its superproject's `.git/modules`, so the walk
+ * goes on to the superproject's. Learned once per directory per run: the
+ * hand-off and the workspace root walk share it (principle 9).
+ */
+export function gitTop(dir: string): Promise<string | null> {
+  let top = tops.get(dir)
+  if (top === undefined) {
+    top = findGitTop(dir)
+    tops.set(dir, top)
+  }
+  return top
+}
+
+async function findGitTop(start: string): Promise<string | null> {
+  for (let d = start; ; d = d.slice(0, d.lastIndexOf('/'))) {
+    // A file each: `exists()` is false for a directory.
+    if (await Bun.file(`${d}/.git/HEAD`).exists()) return d || '/'
+    const file = Bun.file(`${d}/.git`)
+    if (await file.exists()) {
+      const gitdir = await file.text().catch(() => '')
+      if (!/(^|[\s/])\.git\/modules\//.test(gitdir)) return d || '/'
+    }
+    if (d === '') return null
+  }
+}
+
+/** This vx's own file: the compiled binary, else the source entry Bun runs. */
+export function vxPath(): string {
+  return Bun.main.startsWith('/$bunfs') ? process.execPath : Bun.main
+}
+
+/**
+ * Run `bin` with this process's arguments and stdio, and exit as it does.
+ * A signal sent to this vx alone (`kill`, a process manager) is passed on;
+ * one the terminal sent reached the whole foreground group already, and a
+ * second would read as "stop now" (npm-launcher.cjs, the same rule).
+ */
+export async function handOff(bin: string, args: readonly string[]): Promise<never> {
+  const child = Bun.spawn([bin, ...args], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+    env: { ...process.env, VX_HANDED_OFF: process.execPath },
+  })
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
+    process.on(sig, () => {
+      if (!inForeground()) child.kill(sig)
+    })
+  }
+  const code = await child.exited
+  const { constants } = await import('node:os')
+  process.exit(child.signalCode === null ? code : 128 + (constants.signals[child.signalCode] ?? 1))
+}
+
+function inForeground(): boolean {
+  try {
+    const stat = Bun.spawnSync(['ps', '-o', 'pgid=,tpgid=', '-p', String(process.pid)])
+    const [pgid, tpgid] = stat.stdout.toString().trim().split(/\s+/)
+    return pgid !== undefined && pgid === tpgid
+  } catch {
+    return false
+  }
+}

package/src/index.ts

@@ -9,19 +9,11 @@
 export { VERSION } from './version.js'
 
 // Clean error type — user-input failures print a message without a stack.
-// `clampInt` rides along for the same reason the status predicates do:
-// without it on the façade an integration package writes its own, and that
-// had already happened. A bounds helper whose floor is load-bearing (a
-// fractional SQL LIMIT is a datatype mismatch, not a smaller page) should
-// have one implementation.
-export { clampInt, UserError, isUserError } from './util/index.js'
+export { UserError, isUserError } from './util/index.js'
 // Every hook a plugin may fill, in pipeline order — the one list the
 // loader, the host and `vx info` read; exported so a doc pin outside core
 // (the site's guides) holds its tables to the same list.
 export { PLUGIN_HOOKS, type PluginHook } from './config.js'
-// The workspace doctor's facts (`vx info`), for a host that answers the
-// same question over another surface — `@vzn/vx-mcp`'s `getWorkspaceInfo`.
-export { collectInfo, type CollectInfoOptions, type InfoFacts } from './orchestrator/index.js'
 // The machine as this process may use it — cores and memory capped by the
 // cgroup a container runs under. Core's default worker count reads the
 // first; a policy that budgets memory (`@vzn/vx-schedule-history`) reads
@@ -31,16 +23,15 @@ export { machineMemoryBytes, machineParallelism } from './util/index.js'
 // wildcards (`[` `]` are not; item 667) — for a plugin that turns declared
 // outputs into something else (`@vzn/vx-reapi`'s literal `output_paths`).
 export { isLiteralPattern, normalizeGlob } from './util/index.js'
-// A task's command as vx prints it: values of its `exec.env.secret` names
-// masked. `vx show` and telemetry show this; a plugin that hands a command
-// to someone else (`@vzn/vx-mcp`'s `listTasks`, an AI agent) does too (L-26).
-// `maskedLine` is the same for a line no one task owns: the error `vx mcp`
-// hands an agent (L-11).
-export { maskedCommand, maskedLine } from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {
   WorkspaceConfig,
+  RunSettings,
+  CacheSettings,
+  LockSettings,
+  WatchSettings,
+  Duration,
   ProjectConfig,
   TaskConfig,
   ExecConfig,
@@ -65,7 +56,7 @@ export { run, planRun, prepareRun } from './orchestrator/index.js'
 // The per-task duration history a `schedule` plugin learns from
 // (`@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 { currentBranch, LocalHistoryProvider } from './orchestrator/index.js'
 export type {
   HistoryProvider,
   HistoryTable,
@@ -82,6 +73,7 @@ export type { AffectedChanges } from './workspace/index.js'
 export type { RunPlan, PlannedTask } from './orchestrator/index.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './orchestrator/index.js'
 export type {
+  CacheFlags,
   CachePolicy,
   Logger,
   OutputView,
@@ -96,44 +88,48 @@ export { outputsOverlap, splitTaskId } from './graph/index.js'
 export type { TaskNode, TaskOutcome, TaskStatus } from './graph/index.js'
 
 // Cache classes + the layer interface (the `cache` capability's currency).
-export { Cache, LayeredCache } from './cache/index.js'
-export type { CacheLayer, RemoteCacheLayer, RunRecord, InvocationRecord } from './cache/index.js'
+export { Cache } from './cache/index.js'
+export type {
+  CacheLayer,
+  PluginCache,
+  RemoteCacheLayer,
+  RunRecord,
+  InvocationRecord,
+} from './cache/index.js'
 
 // Workspace discovery + the project/config catalog surface — an
 // out-of-process service/CLI needs these. `loadProjectConfig` is the RAW
 // per-file load (`vx lock` freezes exactly that); the resolved view a run
 // or `vx show` sees — plugin stages applied — is `loadResolvedProjects`
-// below. Workspace's `listProjects` re-exports as `listProjectMetas` (the
-// bare name once belonged to a metrics query).
-export { findWorkspaceRoot } from './workspace/index.js'
-export {
-  loadWorkspace,
-  loadProjectConfig,
-  listProjects as listProjectMetas,
-} from './workspace/index.js'
+// below. `PROJECT_CONFIG_FILENAMES` are the names a project's config may
+// have, in precedence order, for a tool that finds or writes one.
+export { findWorkspaceRoot, PROJECT_CONFIG_FILENAMES } from './workspace/index.js'
+export { loadProjectConfig } from './workspace/index.js'
 export type { ProjectMeta } from './workspace/index.js'
-// The package graph as a run sees it (workspace deps by manifest), for a tool
-// that needs a project's transitive closure the way `vx run` computes it.
-export { buildPackageGraph } from './workspace/index.js'
 // The run path's RESOLVED view — plugin `config` and `project` stages
-// applied, cached evaluations served — for a reader outside the CLI (the
-// MCP server's `listTasks`, an embedder's task catalog). What `vx show`
+// applied — for a reader outside the CLI
+// (`@vzn/vx-schedule-history`, an embedder's task catalog). What `vx show`
 // prints.
 export { loadResolvedProjects } from './orchestrator/index.js'
 export type { ProjectEntry } from './workspace/index.js'
 // The migration seam: how a generated config is planned, rendered, guarded
-// and written. `vx init` (package.json scripts) uses it in core;
-// `@vzn/vx-migrate` (Turbo, Nx) and any other adoption tool use it from here.
+// and written. `@vzn/vx-migrate` (package.json scripts, Turbo, Nx) and any
+// other adoption tool use it from here; `taskNameProblem` is why a name
+// cannot be a task's, so a mapper leaves such a script out.
 export {
   applyMigration,
   foldScriptHooks,
   PERSISTENT_TODO,
   pruneOrphanPersistentNotes,
   quoteTsLiteral,
+  taskNameProblem,
 } from './workspace/index.js'
+// Output components: a plugin draws its lines with core's, so they look alike.
+export { ui } from './util/index.js'
 export type {
   ApplyMigrationArgs,
   MigrationFormat,
+  MigrationMember,
   GeneratedProject,
   GeneratedTask,
   MigrationPlan,
@@ -143,7 +139,7 @@ export type {
 // Plugin API — the run-level extension points. Behavior capabilities
 // (executor / cache) change WHAT/HOW work runs; the observe-only `telemetry`
 // capability is the canonical data-export path and cannot change behavior.
-// A plugin is declared in vx.workspace.ts via defineWorkspace({ plugins }).
+// A plugin is declared in .vx/workspace.ts via defineWorkspace({ plugins }).
 // See docs/design/observability-architecture-2026-06.md.
 // The claimant's shell for a lockfile plugin (`@vzn/vx-lockfile`):
 // the claim, the per-project key, the memo and the `--affected` diff around
@@ -153,6 +149,7 @@ export {
   reachDigests,
   type LockfileClaimHooks,
   type LockfileClaimOptions,
+  type LockfileImporter,
   type ReachGraph,
 } from './orchestrator/index.js'
 export type {
@@ -162,6 +159,7 @@ export type {
   PluginOptionKinds,
   CacheContext,
   ExecutorContext,
+  OutputContext,
   CommandContext,
   FingerprintChange,
   FingerprintClaim,
@@ -174,8 +172,10 @@ export type {
   AdmitContext,
   WorkspaceHookContext,
   DiscoverContext,
-  NamedProject,
+  DiscoveredProject,
   PluginSetupContext,
+  RunReport,
+  RunReportTask,
   PluginHookName,
   PluginHookHandlers,
   RunStartInfo,
@@ -244,26 +244,3 @@ export type {
 
 // The serializable run result and its per-task views (what `run()` returns).
 export type { RunResult, TaskView, OutcomeView } from './orchestrator/index.js'
-
-// The run-history queries a reader outside the CLI takes today: `vx why`'s
-// answer, a run's failures and a task's log, which `@vzn/vx-mcp` serves. The event bus /
-// wire form and the other history readers (`listRuns`, `getRun`, …) left the
-// façade 2026-09-10 with no consumer; the telemetry seam above is the
-// canonical export path.
-export {
-  cacheKeyDiff,
-  latestRunId,
-  resolveRunId,
-  rootCauses,
-  runFailures,
-  taskLog,
-  whyDidThisRerunQuery,
-} from './orchestrator/index.js'
-export type {
-  CacheKeyDiff,
-  OutputLocation,
-  RootCause,
-  RunFailures,
-  TaskFailure,
-  TaskLog,
-} from './orchestrator/index.js'

package/src/orchestrator/affected-tasks.ts

@@ -29,7 +29,7 @@ import type { VxPlugin } from './plugin.js'
 import { isDefaultBuild } from './projects.js'
 
 /** Every file in this set re-keys each of its project's tasks, whatever their inputs. */
-const KEYED_BY_EVERY_TASK = new Set(['package.json', ...PROJECT_CONFIG_FILENAMES])
+const KEYED_BY_EVERY_TASK: ReadonlySet<string> = new Set(PROJECT_CONFIG_FILENAMES)
 
 /**
  * The projects every task of which the change reaches: the whole ones the
@@ -41,8 +41,9 @@ const KEYED_BY_EVERY_TASK = new Set(['package.json', ...PROJECT_CONFIG_FILENAMES
 function wholeProjects(
   changes: AffectedChanges,
   projects: ReadonlyMap<string, ProjectEntry>,
-): Set<string> {
-  const whole = new Set(changes.whole)
+): Map<string, string | undefined> {
+  // Each whole project, with the path no cached task claims when one did it.
+  const whole = new Map<string, string | undefined>([...changes.whole].map((n) => [n, undefined]))
   for (const [name, rels] of changes.paths) {
     if (whole.has(name)) continue
     const caches = Object.values(projects.get(name)?.config.tasks ?? {}).flatMap((t) =>
@@ -50,7 +51,8 @@ function wholeProjects(
     )
     const unclaimed = (rel: string): boolean =>
       KEYED_BY_EVERY_TASK.has(rel) || !caches.some((c) => declaresInput(c, rel, null))
-    if (rels.some(unclaimed)) whole.add(name)
+    const rel = rels.find(unclaimed)
+    if (rel !== undefined) whole.set(name, rel)
   }
   return whole
 }
@@ -60,13 +62,15 @@ function wholeProjects(
  * `input`, a changed `file` is one of its declared inputs; `project`, its
  * project changed and the task reads it whole (an uncached task, a path no
  * cached task declares, or no single `file`: a lockfile claim, a manifest
- * edge, a config import); `package`, a `^` edge passes through `project`, a
+ * edge, a config import); `workspace`, a workspace-wide `file` (the
+ * workspace config, a root file a plugin claims) reached every task of its
+ * project; `package`, a `^` edge passes through `project`, a
  * changed package with no such task; `named`, asked as `pkg#task`;
  * `selected`, another filter selected its project outright. `via` is the
  * `dependsOn` chain, nearest first, to the task the change seeded.
  */
 export interface AffectedReason {
-  kind: 'input' | 'project' | 'package' | 'named' | 'selected'
+  kind: 'input' | 'project' | 'workspace' | 'package' | 'named' | 'selected'
   /** Workspace-relative. */
   file?: string
   project?: string
@@ -100,7 +104,10 @@ export function affectedRoots(
   const seeds = explain === undefined ? null : new Map<string, AffectedReason>()
   const through = explain === undefined ? null : new Map<string, string>()
   const inProject = (name: string, rel: string | undefined): AffectedReason => {
-    if (rel === undefined) return { kind: 'project' }
+    if (rel === undefined) {
+      const file = changes.wholeBy?.get(name)
+      return file === undefined ? { kind: 'project' } : { kind: 'workspace', file }
+    }
     const dir = path.relative(explain!.workspaceRoot, projects.get(name)!.dir)
     return { kind: 'project', file: dir === '' ? rel : path.posix.join(dir, rel) }
   }
@@ -157,7 +164,7 @@ export function affectedRoots(
       return hit
     }
     if (whole.has(n.projectName)) {
-      seeds?.set(n.id, inProject(n.projectName, undefined))
+      seeds?.set(n.id, inProject(n.projectName, whole.get(n.projectName)))
       return true
     }
     const rel = rels.find((r) => declaresInput(cache, r, null))

package/src/orchestrator/command-windows.ts

@@ -0,0 +1,44 @@
+// When each command of the run ran and where it may write, so
+// `inputStability.strategy: 'mutable'` can tell a task's own identical
+// rewrite from another task's write and restore (STATUS item 28): a file
+// whose bytes match the key after a write is the task's own only if no
+// other command that may write it ran between the describe and that write.
+
+import path from 'node:path'
+import type { WriteReach } from './sandbox-request.js'
+
+interface Window {
+  id: string
+  projectDir: string
+  reach: WriteReach
+  from: number
+  to: number
+}
+
+export interface CommandWindows {
+  /** A command starts; the returned function marks its end. A server never calls it. */
+  open(id: string, projectDir: string, reach: WriteReach): () => void
+  /** Another command that may write `file` and ran at some point in [from, to]. */
+  writerDuring(self: string, file: string, from: number, to: number): string | undefined
+}
+
+export function commandWindows(): CommandWindows {
+  const windows: Window[] = []
+  return {
+    open(id, projectDir, reach) {
+      if (reach === 'none') return () => {}
+      const w: Window = { id, projectDir, reach, from: Date.now(), to: Infinity }
+      windows.push(w)
+      return () => {
+        w.to = Date.now()
+      }
+    },
+    writerDuring(self, file, from, to) {
+      for (const w of windows) {
+        if (w.id === self || w.from > to || w.to < from) continue
+        if (w.reach === 'workspace' || file.startsWith(w.projectDir + path.sep)) return w.id
+      }
+      return undefined
+    },
+  }
+}

package/src/orchestrator/deferred-outputs.ts

@@ -1,5 +1,5 @@
 // The run-scoped registry of tasks whose outputs were left in the remote
-// store (`--download=none`), and the lazy materialisation that fetches
+// store (`--cache-download=none`), and the lazy materialisation that fetches
 // them when a locally-placed task turns out to need them.
 //
 // See docs/design/download-policy-cas-cache-2026-08.md §5. The two
@@ -9,11 +9,12 @@
 //     remote store (the executor's own record) is the entry.
 //   - Materialisation CONVERGES: after the bytes land, core runs the
 //     ordinary `cache.save`, so the machine is indistinguishable from a
-//     `--download=all` run and every later reader (get, prune, verify,
+//     `--cache-download=all` run and every later reader (get, prune, verify,
 //     metrics) sees one entry shape, not two.
 
 import {
   cleanOutputs,
+  committedFiles,
   resolveOutputs,
   type CacheLayer,
   type GitFilesCache,
@@ -73,7 +74,7 @@ export class DeferredOutputs {
    */
   async materializeFor(node: TaskNode): Promise<void> {
     // Nothing deferred, nothing to find: the closure walk is the size of
-    // the graph, and every task of a run without `--download=none` paid it
+    // the graph, and every task of a run without `--cache-download=none` paid it
     // (1.4 s of a 3,270-task cold run's main thread).
     if (this.entries.size === 0) return
     const needed: string[] = []
@@ -116,7 +117,12 @@ export class DeferredOutputs {
     // workspace-anchored can reach this path.
     const outputs = producer.config.cache?.outputs.files ?? []
     const nestedProjectDirs = this.args.nestedDirsByProject.get(producer.projectName) ?? []
-    const cleanArgs = { projectDir: producer.projectDir, outputs, nestedProjectDirs }
+    const cleanArgs = {
+      projectDir: producer.projectDir,
+      outputs,
+      nestedProjectDirs,
+      committed: committedFiles(this.args.gitFilesCache, producer.projectDir),
+    }
 
     // Mirror `restoreHit`'s sequencing so the two paths cannot drift: wipe
     // the declared outputs, write, then tell the git snapshot what moved.
@@ -135,14 +141,10 @@ export class DeferredOutputs {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       throw new Error(
-        `could not fetch deferred outputs of ${taskId}: ${msg} — re-run it with --force, or use --download=all`,
+        `could not fetch deferred outputs of ${taskId}: ${msg} — re-run it with --force, or use --cache-download=all`,
       )
     }
-    const outputFiles = await resolveOutputs({
-      projectDir: producer.projectDir,
-      outputs,
-      nestedProjectDirs,
-    })
+    const outputFiles = await resolveOutputs(cleanArgs)
     this.args.gitFilesCache?.markOutputsChanged(
       producer.projectDir,
       outputFiles.map((f) => f.slice(producer.projectDir.length + 1)),