@vzn/vx 0.0.635 → 0.0.637

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,
@@ -48,6 +39,7 @@ export type {
   CacheConfig,
   CacheInputs,
   CacheOutputs,
+  InputStability,
   SandboxConfig,
   SandboxGrants,
   SandboxDenials,
@@ -64,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,
@@ -81,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,
@@ -95,44 +88,40 @@ 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 { Cache } from './cache/index.js'
 export type { CacheLayer, 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'
 export type {
   ApplyMigrationArgs,
   MigrationFormat,
+  MigrationMember,
   GeneratedProject,
   GeneratedTask,
   MigrationPlan,
@@ -142,7 +131,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
@@ -152,6 +141,7 @@ export {
   reachDigests,
   type LockfileClaimHooks,
   type LockfileClaimOptions,
+  type LockfileImporter,
   type ReachGraph,
 } from './orchestrator/index.js'
 export type {
@@ -161,6 +151,7 @@ export type {
   PluginOptionKinds,
   CacheContext,
   ExecutorContext,
+  OutputContext,
   CommandContext,
   FingerprintChange,
   FingerprintClaim,
@@ -173,7 +164,7 @@ export type {
   AdmitContext,
   WorkspaceHookContext,
   DiscoverContext,
-  NamedProject,
+  DiscoveredProject,
   PluginSetupContext,
   PluginHookName,
   PluginHookHandlers,
@@ -243,26 +234,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
 }
@@ -157,7 +159,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)),