Module reference

One markdown per module under src/; a slice or helper is documented with the module that owns it (the cache parts in cache.md, the sandbox helpers in sandbox.md), and the CLI verb parsers in docs/cli.md. Each documents:

• Purpose — what the module exists to do.
• Public surface — exported types + functions consumed by other modules. The seam for forks / replacements.
• Algorithm / construction rules — how it works at a high level.
• What it does NOT do — explicit non-features (helps prevent scope creep on future PRs).
• Tests — where coverage lives.
• Replacing this module — what to swap to extend or fork.

Internal helpers are not part of the contract; they can change.

For the high-level data flow, read ../architecture.md first.

Root files

File	Topic
index.md	src/bin.ts — shebang entry; wires process.argv to cli run.
index.md	src/config.ts — public schema types + defineProject helpers.
index.md	src/index.ts — public package façade (re-exports only).
index.md	src/settings.ts — every setting once: path, variable, flag, parser.
index.md	src/version.ts — the VERSION constant (cycle-free leaf).

CLI

File	Topic
cli.md	src/cli/index.ts — module contract: the dispatcher, every verb loaded on use.
	src/cli/workspace-config.ts — the workspace as every verb sees it: config stage applied, cache dir, staged projects (see cli.md).
cli.md	src/cli/run.ts — the vx run parser and verb; src/cli/select.ts — scope, affected owners, picker; src/cli/task-verb.ts — a task typed as a verb, or Nx’s project:target outside a project, answered with its vx run.
cli.md	src/cli/watch.ts — vx watch <task>: re-run on FS change; src/cli/watch-loop.ts — the watchers and the cycles they start; src/cli/watch-fs.ts — the OS watcher, its poller fallback, the mtime clock. src/cli/watch-filter.ts — which events matter; src/cli/watch-set.ts — what is watched; src/cli/watch-judge.ts — which settled paths are changes; src/cli/watch-cycle.ts — one run, stoppable by an edit.
cli.md	src/cli/cache.ts — vx cache clean, duration / size parsers.
	src/cli/docs.ts — vx docs <query>: the reference at the version’s tag on GitHub, searched (cli.md § vx docs).
cli.md	src/cli/help.ts — static help text; src/cli/core-alias.ts — the @vzn/vx virtual module bin.ts registers (see index.md); src/cli/completions.ts — the vx completions script over the verb table and each verb’s help cut.
cli.md	src/cli/plugin-commands.ts — plugin-contributed verbs (VxPlugin.commands).
cli.md	src/cli/format.ts — formatBytes and other shared formatters.
cli.md	src/cli/plan-format.ts — plan → text / JSON / DOT.
index.md	src/handoff.ts — a global vx hands off to the project’s own.
cli.md	src/cli/upgrade.ts — vx upgrade: a verified binary, or its package manager; src/cli/registry.ts — the npm registry releases are read from.

The remaining subcommand parsers — src/cli/{lock,show,info,last,why,init}.ts — are user-facing commands documented in docs/cli.md rather than as module pages; src/cli/plugin-templates.ts is the generated copy of the example plugins vx init --plugin writes. tests/doc-references.test.ts holds this index to the tree: every src/**/*.ts except the index.ts files is named here, itself or in a brace group.

Orchestrator

File	Topic
orchestrator.md	src/orchestrator/{index,run}.ts — module contract + run() / planRun() entry.
	src/orchestrator/run-records.ts — the runs rows, invocation header and telemetry mirror from one pass (see orchestrator.md).
	src/orchestrator/run-report.ts — the report plugin teardowns read; keeps each task’s run bytes in a remote as it ends (see plugin.md).
	src/orchestrator/task-artifacts.ts — a task’s entry by key, saved and restored for an executor that runs it elsewhere (see orchestrator.md).
	src/orchestrator/persistent.ts — keep-alive selection and bounded shutdown of persistent children (see orchestrator.md).
	src/orchestrator/run-stop.ts — one stop for the run: RunOptions.signal and a process signal abort it; owns the live-child registries (see orchestrator.md).
	src/orchestrator/run-lock.ts — one run at a time per workspace on this machine; runs in one process share it (see orchestrator.md).
	src/orchestrator/run-live.ts — the run in progress on a socket beside its lock, for vx last --live (see orchestrator.md).
	src/orchestrator/live-usage.ts — each running task’s cpu and memory for the live list, looked at only once it draws.
	src/orchestrator/steps.ts — vx’s own steps (vx:keys, <plugin>:setup) timed for the logger, a passthrough when nothing renders them (see logger.md).
orchestrator.md	src/orchestrator/options.ts — RunOptions / RunSummary declarations; src/orchestrator/run-settings.ts fills them from the settings.
orchestrator.md	src/orchestrator/execute-task.ts — per-task: hash → cache lookup → spawn → save.
	src/orchestrator/execute-args.ts — a dispatch’s ExecuteArgs: the run’s RunContext, built once and shared, plus the task’s half (see orchestrator.md).
	src/orchestrator/{cached-task,task-policy,miss-inputs,miss-run,task-secrets,attempts,attempt,attempt-request,attempt-signal,attempt-stream,attempt-outputs,input-recheck,task-save,miss-outcome}.ts — a task with a command, one file per step: policy, key and probe, describe, attempts, the inputs re-check, the one save verdict, the outcome (see execute-task.md).
	src/orchestrator/{persistent-task,held-servers}.ts — a persistent task: keyed, spawned, held until readyWhen (see orchestrator.md § B); a server held until the remote answers its dependants.
	src/orchestrator/task-process.ts — a task process’s env and timeout, shared by both spawning paths (see execute-task.md).
orchestrator.md	src/orchestrator/keyed-projects.ts — the projects a task’s key answers for, which bound a cached task’s linked-package grant.
orchestrator.md § Verdict	src/orchestrator/shell-verdict.ts — the frame line for exit 126, 127 and 128 + n: the PATH rule, the file, the signal.
orchestrator.md	src/orchestrator/miss-save.ts — what a miss leaves behind: resolve outputs, save, mark git.
orchestrator.md § The save lane	src/orchestrator/save-lane.ts — the bounded off-slot save queue run() drains before the upload drain.
	src/orchestrator/undeclared-state.ts — the ignored files a miss stamps before its command; one it changed, or empty outputs beside one, is not saved.
orchestrator.md	src/orchestrator/lockfile-claim.ts — the claimant’s shell a lockfile plugin wraps its parser in, and reachDigests.
orchestrator.md	src/orchestrator/{hit-restore,output-log}.ts — what a hit leaves behind: the two proofs, clean + restore, mark git, replay output; the stored output log.
orchestrator.md	src/orchestrator/task-hash.ts — cache-key derivation (computeTaskHash & co.).
orchestrator.md	src/orchestrator/upstream.ts — which upstream hashes a key folds, by inputs.tasks (over graph/folds.ts’s selectFoldedDeps, one matcher for every path).
orchestrator.md	src/orchestrator/{affected-tasks,graph-stage}.ts — which requested tasks --affected’s diff reaches along dependsOn; the graph stage.
orchestrator.md	src/orchestrator/migration.ts — applyMigration: workspace writes, report draws.
orchestrator.md	src/orchestrator/excluded-keys.ts — the key of a dependency --exclude-dependencies keeps from running, and the taint it seeds.
orchestrator.md	src/orchestrator/plan.ts — --dry planning (no exec).
orchestrator.md	src/orchestrator/placement.ts — where each task runs: pins, executor order, 'only', pools, the --dry view.
	src/orchestrator/local-floor.ts — the local executor outside a run, arming the sandbox where no run did; the worker runtime’s floor.
	src/orchestrator/worker-runtime.ts — the one entry a distributed executor’s worker runs a task through, as the local floor would.
	src/orchestrator/local-executor.ts — the floor: run it here (see exec.md, plugins.md).
orchestrator.md	src/orchestrator/signals.ts — SIGINT/SIGTERM/SIGHUP forwarded, as a group signal, to every child, then die of it (128+signo).
orchestrator.md	src/orchestrator/admission.ts — between scheduler and task: in-flight dedup (an embedder’s registry) and continue-taint.
orchestrator.md	src/orchestrator/run-artifacts.ts — --profile trace writer.
orchestrator.md	src/orchestrator/prepare.ts — shared run / planRun setup (workspace, graph, cache).
orchestrator.md	src/orchestrator/projects.ts — the staged project-config load runs and vx show share.
orchestrator.md	src/orchestrator/{plugin,read-only}.ts — VxPlugin capabilities + installer; what a plugin observes, read-only.
orchestrator.md	src/orchestrator/{plugin-host,output-host}.ts — capability consultation + end-of-run teardown/flush; the output claim.
orchestrator.md	src/orchestrator/telemetry.ts — versioned telemetry export contract.
orchestrator.md	src/orchestrator/telemetry-host.ts — sink consultation (zero-sink = zero cost).
orchestrator.md	src/orchestrator/run-context.ts — git / CI / host capture (≤1 spawn).
orchestrator.md	src/orchestrator/stable-keys.ts — shared stable-key derivation + stability gate.
orchestrator.md	src/orchestrator/run-keys.ts — a warm run’s up-front keys, read back whole when nothing they fold moved.
orchestrator.md	src/orchestrator/graph-memo.ts — the task graph, read back whole when the lock and edges did not move.
orchestrator.md	src/orchestrator/fingerprint-watch.ts — has a task rewritten the lockfile mid-run? Re-checked only after one that may.
orchestrator.md	src/orchestrator/command-windows.ts — when each command ran and where it may write, for 'mutable' (described in task-hash.md).
orchestrator.md	src/orchestrator/download-policy.ts — --cache-download modes + the deferral eligibility gate.
orchestrator.md	src/orchestrator/deferred-outputs.ts — deferred-output registry + lazy materialise/converge.
orchestrator.md	src/orchestrator/local-shortcircuit.ts — restore-ahead classify (two-tier schedule).
orchestrator.md	src/orchestrator/remote-prefetch.ts — background remote GETs (LayeredCache only).
history.md	src/orchestrator/run-failures.ts, src/history/run-notes.ts — a failed run’s kept output, the steps a run did not wait on, its warnings; src/orchestrator/run-id.ts — a run id whole or by unique prefix.
orchestrator.md	src/orchestrator/doctor.ts — the workspace doctor’s facts behind vx info.
orchestrator.md	src/orchestrator/task-log-buffer.ts — bounded per-task log capture for telemetry sinks.

Report

File	Topic
report.md	src/report/{logger,forecast}.ts — default logger (flow-aware policy, frames, replay), live ETA and critical path.
report.md	src/report/status-line.ts — serialized writer + dynamic bottom status line.
report.md	src/report/framed-output.ts — ┌─ task ─┐ border helpers + one-liners.
ui.md	src/report/plain-output.ts — task output stripped of ANSI where no terminal reads it (see ui.md) .
	src/util/plain-text.ts — stripEscapes: escapes stripped, an unterminated string escape ending at its line.
util.md	src/util/raw-utf8.ts — task output decoded with each non-UTF-8 byte kept, and written back as that byte.
report.md	src/report/summary.ts — the footer: projects / tasks / cache meters, info and time rows.
report.md	src/report/tally.ts — outcome tally for the end-of-run footer.
report.md	src/report/events.ts — run event bus + serializable WireEvent contract.
report.md	src/report/migration.ts — applyMigration: a migration written by workspace, then drawn.

History

File	Topic
history.md	src/history/history.ts — per-task duration history behind --dry predictions.
	src/history/failure-mode.ts — the flakiness verdict, in one place (see history.md).
history.md	src/history/metrics.ts — run-history queries behind vx last / vx why.
history.md	src/history/miss-reason.ts — what a miss’s key changed since the last saved entry, for a telemetry sink.
history.md	src/history/history-writes.ts — runHistory(cache): a run’s rows into the store’s index.
history.md	src/history/run-history.ts — the runs, invocations and task_durations writes, and their shapes.
history.md	src/history/{history-stream,history-writer}.ts — a run’s hits written on a thread while the graph runs.

Workspace + discovery

File	Topic
workspace.md	src/workspace/{workspace,load-reads,repo-id}.ts — findWorkspaceRoot, findProjectConfigs, names, cacheDir, store id; root reads once.
	src/workspace/canonical-dir.ts — canonicalDir: a directory as the real path it leads to, spelled under the root (see workspace.md).
workspace.md	src/workspace/project-loader.ts — vx.config.* / .vx/workspace.* evaluation.
workspace.md	src/workspace/config-schema.ts — what a config may say: the validators, every level.
	src/workspace/json-data.ts — a config is JSON data: the one rule the loader and the config worker run (see config-schema.md).
	src/workspace/bracket-literal.ts — vx lock refuses a bracket class that names an existing path (see config-schema.md).
workspace.md	src/workspace/package-graph.ts — project graph from plugin edges.
	src/workspace/dependency-rules.ts — run.rules.dependencies held to the graph’s direct deps (see package-graph.md).
workspace.md	src/workspace/filter.ts — pnpm-style --filter DSL parser + applier.
workspace.md	src/workspace/affected.ts — git-relative project selection.
workspace.md	src/workspace/config-imports.ts — the config-import selection channel; the files vx watch watches.
workspace.md	src/workspace/nested-dirs.ts — boundary set (other projects rooted under each).
workspace.md	src/workspace/fingerprint.ts — reads the root files a plugin claims (a lockfile, install settings); folds none.
workspace.md	src/workspace/lockfile.ts — .vx/projects.lock.json freeze / trust / audit; src/workspace/dependencies-lock.ts — .vx/dependencies.lock.json; src/orchestrator/locked-digests.ts — a run’s read of it.
workspace.md	src/workspace/migration.ts — the plan → files seam @vzn/vx-migrate and any adoption tool write through.
	src/workspace/config-eval.ts — fresh re-evaluation in a Worker (see project-loader.md).
	src/workspace/config-bytecode.ts — the workspace config’s cached bytecode bundle (see project-loader.md).
	src/workspace/module-state.ts — what a shared module’s exports hold, to refuse a config that changes one (see project-loader.md).

Graph + scheduler

File	Topic
graph.md	src/graph/task-graph.ts — TaskNode DAG builder + cycle detection.
	src/graph/definition.ts — taskDefinition(s), what history keys a task by (see task-graph.md).
	src/graph/default-build.ts — the build a project declaring none gets (see task-graph.md).
	src/graph/critical-path.ts — criticalPath, the order a schedule plugin returns (see task-graph.md).
	src/graph/stand-ins.ts — what an edge past a cycle’s default build stands in for (see task-graph.md).
graph.md	src/graph/scheduler.ts — parallel topological executor.
	src/graph/priorities.ts — the ready-queue ranking (see scheduler.md).
	src/graph/task-status.ts — the status vocabulary (see scheduler.md).
	src/graph/outcome.ts — TaskOutcome, its errors and marks (see scheduler.md).
	src/graph/lanes.ts — the slots running tasks hold (see scheduler.md).
	src/graph/ready-heap.ts — the ready queue’s heap (see scheduler.md).
util.md	src/util/dependency-spec.ts — shared Turbo/Nx micro-syntax parser.
graph.md	src/graph/folds.ts — which dependencies a key folds (inputs.tasks).

Cache cluster

File	Topic
cache.md	src/cache/cache.ts — local cache: bun:sqlite index + tar.zst artifacts.
	src/cache/{layer,policy,zstd,key-fold,store-index,lookup,restore,save,prune,cache-dir}.ts — the parts Cache delegates to (cache.md § Files); src/cache/checkpointer.ts — the index WAL checkpointed on a thread while a run saves (cache.md); src/cache/linked-inputs.ts — what a symlinked input points to, keyed (cache.md); src/cache/{archive,tar-stream}.ts — pack / scan / extract (cache.md, caching.md § Storage layout).
cache.md	src/cache/layered-cache.ts — the local cache with the declared remotes behind it + RemoteCacheLayer seam.
cache.md	src/cache/remote-lane.ts — one declared remote: its gate, boundary, upload pool and warnings.
cache.md	src/cache/inputs.ts — glob resolution, boundary enforcement, cleanOutputs.
cache.md	src/cache/git-inputs.ts — the git enumeration (ls-files, status, check-attr) the resolver trusts.

Memo

File	Topic
memo.md	src/memo/local-memo.ts — LocalMemo: the store’s memos as one object, Cache.memo.
memo.md	src/memo/file-hashes.ts — the per-file blob-OID memo, fileIdentity.
memo.md	src/memo/fold-memo.ts — each task’s last key by its probe.
memo.md	src/memo/fs-clock.ts — the file system clock lag every racy window adds.
memo.md	src/memo/output-index.ts — output rows and stamps, the two proofs a hit runs.
memo.md	src/memo/remote-hits.ts — the keys a remote last said it holds.
memo.md	src/memo/lockfile-memo.ts — a lockfile claimant’s parse, one row per file and claimant.

Index database

File	Topic
index-db.md	src/index-db/schema.ts — every table of cache.db, SCHEMA_VERSION, the SQLite helpers.

Exec (process primitives)

File	Topic
util.md	src/exec/runner.ts — runCommand, runPersistent, shellQuote.
util.md	src/exec/spawn-off.ts — spawnOff: a task’s spawn on a thread of its own, off the scheduler’s.
util.md	src/exec/pipes.ts — TaskPipes: a task’s stdout, stderr and held stdin as pipes vx makes (Linux).
util.md	src/exec/warm-shell.ts — takeSpare: a task’s shell started before the task, so a freed slot runs at once.
exec.md	src/exec/kill-tree.ts — killTree: a task’s process group dies with it (timeout, signal, shutdown).
exec.md	src/exec/proc-sample.ts — sampleTrees: a running task’s process tree CPU and memory, for task.sample.
exec.md	src/exec/env.ts — child env composition; src/util/essential-env.ts — the essential allowlist.
exec.md	src/exec/executor.ts — TaskExecutor contract + selectExecutor.

Sandbox

File	Topic
sandbox.md	src/sandbox/runtime.ts — runSandboxed + violation tracking via @anthropic-ai/sandbox-runtime.
	src/sandbox/violations.ts — strace pass, seatbelt record description, report filters.
	src/sandbox/binds.ts — bwrap-honourable write grants, read-grant punching, the SRT custom config.
	src/sandbox/paths.ts — toRealPath, absolutize, atOrUnder, isUnderAny, sandboxReads, unique.
	src/sandbox/deny-scan.ts — SRT’s mandatory write denies, scanned within each task’s write grants.
	src/sandbox/task-proxy.ts — startTaskProxy: one task’s own network proxy, its list before the run’s.
sandbox.md	src/sandbox/request.ts — arming the runtime for a run; the sandbox half of an ExecuteRequest: grants, binds.
sandbox.md	src/sandbox/fix.ts — the grants a failed run needed, credential stores left out.

Plugins

File	Topic
orchestrator.md	Core ships no plugin: the floor (run here, cache here) and where plugins live (packages/vx-*).
cache.md	src/cache/scoped-cache.ts — the key a scope stores a plugin entry under.
cache.md	src/cache/{plugin-cache,run-store}.ts — a plugin’s own entries (ctx.cache); a run’s kept bytes.

UI

File	Topic
ui.md	src/ui/{theme,components,terminal,kit,live-region,ansi,terminal-signals,links,refusal,version-line}.ts — the only module that draws: tokens, components, panels, streams.

Utilities

File	Topic
util.md	src/util/paths.ts — POSIX-path normaliser for stable cache keys.
util.md	src/util/hash.ts — xxHash3 helpers shared by every key-derivation site.
util.md	src/util/ulid.ts — run-id generator (Bun.randomUUIDv7 wrapper).
util.md	src/util/errors.ts — UserError class for stack-less error reporting; src/util/config-frame.ts — a config refusal at its line.
util.md	src/util/timing.ts — the VX_DEBUG_TIMING=1 stage table + per-task spans.
util.md	src/util/edit-distance.ts — the one “did you mean” rule.
util.md	src/util/bun-version.ts — the Bun floor, read at run time, and what breaks below it.
util.md	src/util/num.ts — MAX_TIMEOUT_MS, clampInt, parseDecimalInt.
util.md	src/util/settle.ts — the end-of-run settle bound for plugin teardown.
util.md	src/util/tail.ts — head-evicting tail for a persistent task’s output.
util.md	src/util/notice.ts — a warning from below the terminal as a fact; ui draws it.
util.md	src/util/styled.ts — Style, Tone, Inline: styled text as data.
util.md	src/util/memo-parts.ts — memoParts: a memo’s token built from a declaration of every input field.
util.md	src/util/secret-mask.ts — masks secret-named variables’ values in what vx shows.
util.md	src/util/hide-env.ts — hideEnvFromTasks: non-dumpable on Linux, startup values zeroed on macOS, so tasks cannot read vx’s env.
util.md	src/util/which.ts — executablePath: a tool’s absolute path on vx’s own PATH, found once.
util.md	src/util/procfs.ts — procfsIsOwn: is /proc this pid namespace’s view, asked once.
util.md	src/util/{secrets,hidden-prompt}.ts — ctx.secret: a plugin’s OS keychain entries, asked once on a terminal when missing.
util.md	src/util/hangup.ts — hangupIgnored: did vx start with SIGHUP ignored (nohup), asked once.
util.md	src/util/signal-relay.ts — relayedCopy: a stop heard again through a relaying parent (bun vx) is the same stop.
util.md	src/util/before-exit.ts — beforeExit: work a verb leaves running, settled before the process exits.
util.md	src/util/git-attributes.ts — which paths a clean filter can rewrite, asked of git (check-attr --all).
util.md	src/util/git-ignored.ts — whether git ignores everything an output glob writes, asked of git (check-ignore, ls-files).
util.md	src/util/real-path.ts — realPath: the OS’s final path; realpathOf: realpath past a backslash; sameDir: two spellings, one directory.
util.md	src/util/foreign-cache-dir.ts — refuseForeignCacheDir: a cache dir that resolves to home, / or the workspace is refused before vx writes there.
util.md	src/util/cgroup.ts — the cores and memory this process may use, as its cgroup bounds them.
	src/util/{size,verbs}.ts — parseSize, parseDuration, treeBytes, diskBytes (cli-cache.md) and the core verb list (cli.md).
	src/util/task-id.ts — splitTaskId, the first-# inverse of taskId (task-graph.md).
	src/util/env-flag.ts — envFlagOn: whether CI and the like are on (0, false and empty are off).
	src/util/write-file.ts — refuseSymlink, writeNoFollow: a generated file never written through a link (migration.md); writeAllOrNone: the locks, all renamed or none.
util.md	src/util/umask.ts — the process umask a restore applies, and the modes it gives.

For the public package surface (what import('@vzn/vx') resolves to) see index.md.