@vzn/vx 0.0.633 → 0.0.634

package/docs/caching.md

@@ -465,7 +465,10 @@ fold, and runtime probes after a writer still leave a key preliminary.
 The
 short-circuit never runs under a `LayeredCache` (remote prefetch owns
 those runs — an up-front `get` there would put remote GETs on the
-critical path), never fires with local reads off, and never throws —
+critical path), never fires with local reads off or on a local cache
+that holds no artifact (`Cache.holdsNothing`: every probe would miss,
+and a cold 1,090-package run started its first task ~90 ms sooner
+without it), and never throws —
 any error degrades to the normal lazy schedule. Measured: −6.6% on a
 mixed slow-upstream/warm-downstream workload; parity on all-hit warm
 runs.

package/docs/cli.md

@@ -976,6 +976,10 @@ single `file` for a lockfile claim, a manifest edge or a config import),
 selected its project). `via` is the `dependsOn` chain, nearest first, to
 the task the change reached. A dependency the kept tasks pull in carries
 none. The reasons are gathered only for a plan; a run pays nothing.
+`--dry=json` also states `affectedBase`, the ref the diff was taken
+against: a bare `--affected` guesses it (`origin/HEAD`, a trunk branch,
+else `HEAD~1`), so a reason that names no file may come from a commit
+the base reaches, a root `package.json` edit among them.
 
 `--graph` prints Graphviz DOT (stdout by default; `--graph=path`
 writes a file):
@@ -2287,26 +2291,89 @@ refuses `--dry` (use `--dry=json`), a bare `--graph` and
 
 A verb asked for JSON (`--format json`, `--format=json`, `--dry=json`,
 before any `--`) answers a refusal on stdout too, as one line that
-`schemas/error.json` describes: `{"ok":false,"error":{"code","message"}}`.
-The exit code (1) and the prose on stderr do not change. Branch on the
-code; the message may change.
-
-| Code                   | When                                                                  |
-| ---------------------- | --------------------------------------------------------------------- |
-| `VX_E_USAGE`           | A flag, argument or selection the verb does not take.                 |
-| `VX_E_UNKNOWN_COMMAND` | No verb of that name here, core's or a declared plugin's.             |
-| `VX_E_UNKNOWN_TASK`    | No project in scope declares a requested task.                        |
-| `VX_E_UNKNOWN_PROJECT` | `vx show` names a project the workspace does not have.                |
-| `VX_E_NO_HISTORY`      | `vx why` / `vx last` find no recorded run for what they were asked.   |
-| `VX_E_AMBIGUOUS`       | `vx why <task>` matches the task in several projects; name one.       |
-| `VX_E_CONFIG`          | A `vx.config.*` or `vx.workspace.*` that does not load or is refused. |
-| `VX_E_CYCLE`           | The task graph has a cycle.                                           |
-| `VX_E_NO_WORKSPACE`    | No workspace root above the working directory.                        |
-| `VX_E_CACHE_VERSION`   | A reading verb met a cache index from another vx version.             |
-| `VX_E_REFUSED`         | Any other refusal (a plugin's, a check's) with no code of its own.    |
-| `VX_E_FS`              | The file system refused a write: permissions, a full disk.            |
-| `VX_E_FDS`             | Out of file descriptors.                                              |
-| `VX_E_INTERNAL`        | A defect in vx; stderr carries the stack.                             |
+`schemas/error.json` describes: `{"ok":false,"error":{"code","message","docs"}}`.
+`docs` links the code's section below, which says what to do;
+`vx docs <code>` prints that section offline. The exit code (1) and the
+prose on stderr do not change. Branch on the code; the message may change.
+
+#### `VX_E_USAGE`
+
+A flag, argument or selection the verb does not take. The message names
+it, and a close spelling the verb does take when there is one;
+`vx <verb> --help` lists every flag.
+
+#### `VX_E_UNKNOWN_COMMAND`
+
+No verb of that name here, core's or a declared plugin's. `vx --help`
+lists core's verbs. A plugin's verb exists once its plugin is in
+`vx.workspace.ts` `plugins`; a task runs as `vx run <task>`.
+
+#### `VX_E_UNKNOWN_TASK`
+
+No project in scope declares a requested task. The message lists the
+tasks it found; `vx show --format json` lists each project's. Check the
+spelling, and the scope: `--filter`, `--all`, or the project the working
+directory is in.
+
+#### `VX_E_UNKNOWN_PROJECT`
+
+`vx show` names a project the workspace does not have. A project is named
+by its `package.json` `name`; `vx show --format json` lists them.
+
+#### `VX_E_NO_HISTORY`
+
+`vx why` / `vx last` find no recorded run for what they were asked. Run
+the task once (`vx run <task>`); history is this checkout's own.
+
+#### `VX_E_AMBIGUOUS`
+
+`vx why <task>` matches the task in several projects. Name one:
+`vx why <project>#<task>`.
+
+#### `VX_E_CONFIG`
+
+A `vx.config.*` or `vx.workspace.*` that does not load or is refused. The
+message names the file and the field; fix that field
+(`vx docs <field>` prints its reference). `vx info --format json` lists
+every config error at once.
+
+#### `VX_E_CYCLE`
+
+The task graph has a cycle. The message names the loop; drop one of its
+`dependsOn` edges.
+
+#### `VX_E_NO_WORKSPACE`
+
+No workspace root above the working directory. Run vx inside the repo,
+or create a `package.json` and run `vx init`.
+
+#### `VX_E_CACHE_VERSION`
+
+A reading verb met a cache index from another vx version. It reads
+nothing from it and leaves it be; the next `vx run` resets it. Or run the
+vx version that wrote it.
+
+#### `VX_E_REFUSED`
+
+Any other refusal (a plugin's, a check's) with no code of its own. The
+message is that plugin's or check's: do what it says.
+`vx info --format json` lists the plugins.
+
+#### `VX_E_FS`
+
+The file system refused a write: permissions, a full disk. The message
+names the path. Free space (`vx cache prune --max-size <size>` trims the
+cache) or grant the write, then re-run.
+
+#### `VX_E_FDS`
+
+Out of file descriptors. Raise the limit (`ulimit -n 4096`), or run fewer
+tasks at once (`--concurrency`), then re-run.
+
+#### `VX_E_INTERNAL`
+
+A defect in vx; stderr carries the stack. Report it with that stack at
+https://github.com/vznjs/vx/issues.
 
 A plugin can give its refusal a code: `new UserError(message, 'MY_CODE')`.
 
@@ -2786,7 +2853,9 @@ parse error.
 `schema`, `caching`, `execution`, `patterns`, `security` and `features`,
 which ship inside the package and the compiled binary. Each page is cut
 at its headings; a section that holds every word of the query matches,
-and a word in its heading ranks it above any count in its text. The best
+and a word in its heading ranks it above any count in its text; a
+one-word query that titles a section, an error code
+(`vx docs VX_E_CYCLE`), prints that section alone. The best
 `--limit` sections (default 3) print whole, each under its page,
 heading and URL on the site. `--format json` prints
 `{query, hits: [{page, heading, url, text}]}` (`schemas/docs.json`).

package/docs/execution.md

@@ -45,7 +45,7 @@ terminal and a task succeeding or failing. Read it alongside
  │    3. loadWorkspacePlugins — loadWorkspaceConfig reads the optional
  │       vx.workspace.{ts,mts,js,mjs,cts,cjs} at the root (concurrency /
  │       cacheDir / timeout / cacheRetention / affectedBase / cacheScope /
- │       rules / plugins),
+ │       rules / schedule / plugins),
  │       then the plugin `config` stage runs on it.
  │    4. listProjects — globs every workspace member's package.json,
  │       finds sibling vx.config.* files, detects duplicate package

package/docs/features.md

@@ -28,6 +28,7 @@ config key or an environment variable is missing here.
 - **Turbo and Nx spellings** (`-t`, `-p`, `--exclude`, `--parallel`, `--base`, `--dry-run`, `--skip-nx-cache`) — accepted, or refused naming the vx spelling. [page](https://vznjs.github.io/vx/features/turbo-nx-flags/) · post: [Flags you already know](https://vznjs.github.io/vx/blog/flags-you-already-know/)
 - **Ctrl-C leaves nothing running** (`VX_KILL_GRACE_MS`, `VX_TEARDOWN_TIMEOUT_MS`) — the whole process tree stops, then teardown runs. [page](https://vznjs.github.io/vx/features/ctrl-c/) · post: [Ctrl-C leaves nothing running](https://vznjs.github.io/vx/blog/ctrl-c/)
 - **Longest chain first** — the scheduler starts the critical path first; `@vzn/vx-schedule-history` learns it from past runs. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Bitsets, popcount, and a scheduler tick](https://vznjs.github.io/vx/blog/bitsets-and-the-scheduler/)
+- **Schedule strategy** (`schedule`) — pick the order with no timings: most work waiting (default), longest chain, most direct dependents, or ready order; plugins still lead. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Pick the order your graph wants](https://vznjs.github.io/vx/blog/schedule-strategy/)
 - **No daemon** — every run starts cold and still answers in milliseconds. [page](https://vznjs.github.io/vx/features/no-daemon/) · post: [No daemon, on purpose](https://vznjs.github.io/vx/blog/no-daemon/)
 - **Group tasks** (`dependsOn` with no `exec`) — a task that only runs its dependencies; `dependsOn: []` is a named no-op. [page](https://vznjs.github.io/vx/features/group-tasks/) · post: [Say exactly which tasks to run](https://vznjs.github.io/vx/blog/pick-your-tasks/)
 - **Keyed groups** (`cache` with no `exec`) — a key a dependant folds: it re-runs on those inputs, and nothing spawns or counts for the group. [page](https://vznjs.github.io/vx/features/group-tasks/) · post: [A key with nothing to run](https://vznjs.github.io/vx/blog/keyed-groups/)
@@ -68,10 +69,10 @@ config key or an environment variable is missing here.
 - **vx info** (`vx info`) — workspace doctor: versions, projects, cache size against `cacheRetention.maxSize`. [page](https://vznjs.github.io/vx/features/vx-info/) · post: [One command to know your workspace](https://vznjs.github.io/vx/blog/know-your-workspace/)
 - **JSON everywhere** (`--format`) — `show`, `info`, `why`, `last` and `cache` print JSON for agents. [page](https://vznjs.github.io/vx/features/json-everywhere/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 - **Run analytics in SQLite** — every task's time, CPU, peak memory and cache result, queryable with `sqlite3`. [page](https://vznjs.github.io/vx/features/run-analytics/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
-- **Stable error codes** (`VX_E_…`) — under `--format json` a refusal is a JSON line on stdout with a code an agent branches on. [page](https://vznjs.github.io/vx/features/error-codes/) · post: [A refusal an agent can read](https://vznjs.github.io/vx/blog/error-codes/)
+- **Stable error codes** (`VX_E_…`) — under `--format json` a refusal is a JSON line on stdout with a code an agent branches on and a `docs` link to its fix (`vx docs <code>` offline). [page](https://vznjs.github.io/vx/features/error-codes/) · post: [A refusal an agent can read](https://vznjs.github.io/vx/blog/error-codes/)
 - **Shipped JSON Schemas** (`@vzn/vx/schemas/`) — every `--format json` shape has a schema, and stdout always parses. [page](https://vznjs.github.io/vx/features/json-schemas/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 - **Docs for agents** (`llms.txt`, `llms-full.txt`) — the whole site as markdown for coding agents. [page](https://vznjs.github.io/vx/features/llms-txt/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
-- **vx docs** (`vx docs`, `--limit`) — search the CLI, config and cache reference offline; it ships inside vx. [page](https://vznjs.github.io/vx/cli/#vx-docs) · post: [The reference, offline](https://vznjs.github.io/vx/blog/vx-docs-offline/)
+- **vx docs** (`vx docs`, `--limit`) — search the CLI, config and cache reference offline; it ships inside vx. [page](https://vznjs.github.io/vx/features/vx-docs/) · post: [The reference, offline](https://vznjs.github.io/vx/blog/vx-docs-offline/)
 - **Affected reasons** (`--affected --dry`) — each kept task says the changed file or the dependency chain that reached it, text or JSON. [page](https://vznjs.github.io/vx/features/affected-reasons/) · post: [See inside a run](https://vznjs.github.io/vx/blog/see-inside-a-run/)
 - **Agent skill** (`skills/vx/SKILL.md`) — an installable skill that teaches a coding agent to run, debug and query vx. [page](https://vznjs.github.io/vx/features/agent-skill/) · post: [Built for the agent at the keyboard](https://vznjs.github.io/vx/blog/built-for-agents/)
 
@@ -170,3 +171,4 @@ config key or an environment variable is missing here.
 - **Install as a remote action** (`exec.remote: 'only'`) — `node_modules` is built by an action, so stateless workers have it. [page](https://vznjs.github.io/vx/features/remote-install/) · post: [Remote execution without moving the scheduler](https://vznjs.github.io/vx/blog/remote-execution/)
 - **OTel live export** (`otel({ live })`) — spans and metrics stream as tasks end, so a dashboard follows a CI run live. [page](https://vznjs.github.io/vx/features/otel-live/) · post: [Watch a CI run while it runs](https://vznjs.github.io/vx/blog/otel-live/)
 - **Memory-aware admission** (`@vzn/vx-schedule-history`) — tasks are packed by the peak memory learned from past runs. [page](https://vznjs.github.io/vx/features/memory-admission/) · post: [A scheduler that learns from your runs](https://vznjs.github.io/vx/blog/a-scheduler-that-learns/)
+- **CI timings file** (`@vzn/vx-schedule-history`, `file`) — one JSON file of learned task times a CI cache carries between runners, so a fresh runner orders by real times. [page](https://vznjs.github.io/vx/features/critical-path/) · post: [Carry the scheduler's memory between CI runners](https://vznjs.github.io/vx/blog/ci-timings-file/)

package/docs/schema.md

@@ -1534,6 +1534,7 @@ export default defineWorkspace({
   affectedBase: 'origin/main',
   cacheScope: 'trusted',
   rules: { exclusiveOutputs: true, upfrontKeys: true },
+  schedule: 'most-work',
   plugins: [otel()],
 })
 ```
@@ -1554,6 +1555,8 @@ interface WorkspaceConfig {
   cacheScope?: string
   /** Graph rules checked before anything runs; each on unless set to false. */
   rules?: WorkspaceRules
+  /** Which ready task starts first with no timings: 'most-work' (default), 'critical-path', 'direct-dependents', 'ready-order'. */
+  schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
   /** Run-level plugins (cache / executor / telemetry capabilities). */
   plugins?: readonly Plugin[]
 }
@@ -1631,6 +1634,17 @@ run` takes `'read-only'` off CI (`CI` unset, `0` or `false`) and
   boundary: a run holding a write credential can write any key, so only
   a cache server that scopes writes by token can refuse one
   (`docs/security.md` § Cache poisoning). Not folded into any cache key.
+- **`schedule`** — which ready task starts first when more are ready
+  than workers, with no timings. `most-work` (the default): the one the
+  most tasks wait on, at any depth. `critical-path`: the head of the
+  longest chain of tasks below it. `direct-dependents`: the one the most
+  tasks wait on directly (Nx's rule). `ready-order`: the one that became
+  ready first (Turbo's rule). Each loses some graph shape the others win
+  (`blog/scheduling-strategies`). A `schedule` plugin's weights
+  (`@vzn/vx-schedule-history`) still sort first, and the strategy breaks
+  their ties. The default costs what it did; another strategy is
+  computed only when named. Any other value is refused. Never folded
+  into a cache key.
 - **`rules`** — checks on the task graph, each on unless set to
   `false`. Turning one off allows a shape vx runs correctly but more
   slowly; never folded into a cache key. A value that is not a boolean,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.633",
+  "version": "0.0.634",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.633",
-    "@vzn/vx-linux-arm64": "0.0.633",
-    "@vzn/vx-darwin-x64": "0.0.633",
-    "@vzn/vx-darwin-arm64": "0.0.633"
+    "@vzn/vx-linux-x64": "0.0.634",
+    "@vzn/vx-linux-arm64": "0.0.634",
+    "@vzn/vx-darwin-x64": "0.0.634",
+    "@vzn/vx-darwin-arm64": "0.0.634"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/error.json

@@ -16,7 +16,11 @@
           "type": "string",
           "description": "Stable; branch on it. VX_E_USAGE, VX_E_UNKNOWN_COMMAND, VX_E_UNKNOWN_TASK, VX_E_UNKNOWN_PROJECT, VX_E_NO_HISTORY, VX_E_AMBIGUOUS, VX_E_CONFIG, VX_E_CYCLE, VX_E_NO_WORKSPACE, VX_E_CACHE_VERSION, VX_E_REFUSED, VX_E_FS, VX_E_FDS, VX_E_INTERNAL."
         },
-        "message": { "type": "string", "description": "The refusal in prose; may change." }
+        "message": { "type": "string", "description": "The refusal in prose; may change." },
+        "docs": {
+          "type": "string",
+          "description": "For a core code (VX_E_…): its section of the CLI reference, which says what to do. A plugin's code has none."
+        }
       }
     }
   }

package/schemas/plan.json

@@ -6,6 +6,10 @@
   "additionalProperties": false,
   "required": ["tasks"],
   "properties": {
+    "affectedBase": {
+      "type": "string",
+      "description": "under --affected: the ref the diff was taken against (a bare --affected guesses it: origin/HEAD, a trunk branch, else HEAD~1)"
+    },
     "tasks": {
       "type": "array",
       "items": {

package/skills/vx/SKILL.md

@@ -21,6 +21,9 @@ vx run build --all --format json    # the result as JSON on stdout; logs go to s
 The exit code is the verdict: `0` every task passed or hit the cache, `1` a
 task failed or was skipped, or the command was refused. `--format json`
 prints `schemas/summary.json` (`runId`, `ok`, `exitCode`, a row per task).
+A refusal under `--format json` is one line on stdout,
+`{"ok":false,"error":{"code","message","docs"}}`: branch on `code`;
+`docs` (or `vx docs <code>` offline) says what to do.
 Without a TTY a missing task name never prompts: vx exits 1 and lists the
 tasks it found.
 
@@ -31,7 +34,10 @@ vx show --format json                          # projects, their tasks and depen
 vx run test --affected=origin/main --dry=json  # what would run, cache hit or miss, and why
 ```
 
-Under `--affected`, each kept task in `--dry=json` carries `affected`:
+Under `--affected`, `--dry=json` states `affectedBase` (the ref it diffed
+against; name one, `--affected=origin/main`, rather than trust the guess)
+and each task you asked for carries `affected` (a dependency it pulls in
+does not):
 `{ kind, file?, project?, via? }`, where `kind` is `input` (a changed file
 is one of its inputs), `project`, `package`, `named` or `selected`, and
 `via` is the `dependsOn` chain that carried the change.

package/src/cache/cache.ts

@@ -122,6 +122,13 @@ import { CACHE_VERSION, foldKey } from './key-fold.js'
  */
 const ORPHAN_GRACE_MS = 60 * 60 * 1000
 
+/**
+ * Row-less lookups answered by a stat each before the artifact directory
+ * is listed once instead: a warm run's few misses keep their stat, a
+ * cold run's thousands share one listing.
+ */
+const ADOPT_STATS = 64
+
 /**
  * A hit renews an entry's `accessed_at` only once it is older than this:
  * renewing every hit rewrote 2,180 rows at a warm 1,090-package run's
@@ -730,6 +737,10 @@ export class Cache implements CacheLayer {
   private readonly heldInlineAt = new Map<string, number>()
   /** Keys the last lookups found an inline artifact for and no row: `adopt`'s to read. */
   private readonly rowless = new Set<string>()
+  /** Row-less lookups that stat'ed their artifact path (`artifactFileMayExist`). */
+  private adoptStats = 0
+  /** The artifact directory's names, listed once past `ADOPT_STATS`; this process's writes kept in it. */
+  private artifactNames: Set<string> | undefined
   private readonly insertEntryInput: ReturnType<Database['prepare']>
   /** The per-file (mtime, size) → blob-OID memo behind `hashFile`. */
   private readonly files: FileHashStore
@@ -1472,20 +1483,21 @@ export class Cache implements CacheLayer {
    * reader reads it, and indexed in one transaction with its bytes.
    */
   private async adopt(hash: string, ctx: CacheGetContext): Promise<boolean> {
-    const meta: IngestMeta = {
+    // Built only for an artifact found: its command is masked on read.
+    const meta = (): IngestMeta => ({
       taskId: ctx.taskId,
       command: ctx.command,
       durationMs: 0,
       ...(ctx.outputs !== undefined ? { outputs: ctx.outputs } : {}),
-    }
+    })
     // Only a key whose lookup saw a row-less inline artifact asks for it: a
     // statement per miss otherwise, on every cold save.
     const blob = this.rowless.delete(hash)
       ? (this.selectBlob.get(hash) as { bytes: Uint8Array } | null)
       : null
-    if (blob !== null) return this.adopted(this.writeArtifactAndIndex(hash, blob.bytes, meta))
+    if (blob !== null) return this.adopted(this.writeArtifactAndIndex(hash, blob.bytes, meta()))
     const finalPath = this.tarPath(hash)
-    if (!existsSync(finalPath)) return false
+    if (!this.artifactFileMayExist(hash)) return false
     const tmpPath = this.tempPath(hash)
     try {
       // A second name for the same bytes: the index step renames it over
@@ -1500,7 +1512,28 @@ export class Cache implements CacheLayer {
     } catch {
       return false
     }
-    return this.adopted(this.writeArtifactAndIndex(hash, { tmpPath }, meta))
+    return this.adopted(this.writeArtifactAndIndex(hash, { tmpPath }, meta()))
+  }
+
+  /**
+   * Whether `hash` may have a file artifact: a stat for the first
+   * `ADOPT_STATS` asks, then one listing of the directory. A cold
+   * 1,090-package run asked 3,270 times before its first task ran. A
+   * name listed and since removed fails the adopt's link, a miss; a file
+   * another process writes after the listing is missed too, and its own
+   * row serves it.
+   */
+  private artifactFileMayExist(hash: string): boolean {
+    const name = `${hash}.tar.zst`
+    if (this.artifactNames === undefined) {
+      if (++this.adoptStats <= ADOPT_STATS) return existsSync(path.join(this.artifactDir, name))
+      try {
+        this.artifactNames = new Set(readdirSync(this.artifactDir))
+      } catch {
+        this.artifactNames = new Set()
+      }
+    }
+    return this.artifactNames.has(name)
   }
 
   /** An adoption's verdict: an artifact that fails the checks is a miss. */
@@ -1562,6 +1595,27 @@ export class Cache implements CacheLayer {
     return entry
   }
 
+  /**
+   * Whether no lookup here can hit: no artifact, inline or file. Every
+   * entry has one, and a row-less one is still a hit (`adopt`). The listing
+   * is kept for `adopt`.
+   */
+  holdsNothing(): boolean {
+    if (!this.read) return true
+    if (this.guard(() => this.db.query('SELECT 1 FROM artifacts LIMIT 1').get()) != null) {
+      return false
+    }
+    let names: string[]
+    try {
+      names = readdirSync(this.artifactDir)
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return false
+      names = []
+    }
+    this.artifactNames ??= new Set(names)
+    return !names.some((n) => n.endsWith('.tar.zst'))
+  }
+
   /**
    * `get` for many hashes at once: one `entries` query and one
    * `output_files` query per chunk instead of two per hash, with the
@@ -2391,6 +2445,7 @@ export class Cache implements CacheLayer {
       } else {
         aside = moveAside()
         renameSync(tmpPath!, finalPath)
+        this.artifactNames?.add(path.basename(finalPath))
         renamed = true
         deleteBlob.run(hash)
       }

package/src/cache/inputs.ts

@@ -219,7 +219,7 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
     // Dedupe: when the project dir IS the workspace root (or a glob
     // overlaps), the same absolute path can arrive via both lists —
     // it must contribute to the key exactly once.
-    if (wsFiles.length > 0) files = [...new Set([...projectFiles, ...wsFiles])].sort()
+    if (wsFiles.length > 0) files = mergeSorted(projectFiles, wsFiles)
   }
   // Two awaited empty resolutions per task were ~3 ms of a 1000-task warm
   // run (profiled 2026-09-09); a task declaring neither skips the fan-out.
@@ -285,7 +285,6 @@ function resolveWorkspaceFiles(args: {
   }
   if (positive.length === 0) return undefined
 
-  const isExcluded = anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)])
   // A path the task's own outputs take back with `!` is no output, so it
   // stays an input (A-44).
   const ownOutput = outputMatcher(args.ownWorkspaceOutputs)
@@ -310,40 +309,44 @@ function resolveWorkspaceFiles(args: {
   // The memo is valid for the snapshot it was computed over: a task that
   // wrote workspace outputs mid-run replaces the partition, and the next
   // caller sees a different array and scans again.
-  const memoKey =
-    args.memo === undefined
-      ? undefined
-      : JSON.stringify([
-          positive,
-          negative,
-          args.ownWorkspaceOutputs,
-          args.ownOutputs,
-          args.projectRel,
-        ])
+  let isExcluded: ((rel: string) => boolean) | undefined
   let isPositive: ((rel: string) => boolean) | undefined
-  const excluded = (rel: string): boolean => isExcluded(rel) || ownOutput(rel) || ownProject(rel)
+  const excludedByDeclaration = (rel: string): boolean =>
+    (isExcluded ??= anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)]))(rel)
+  const own = (rel: string): boolean => ownOutput(rel) || ownProject(rel)
   const listing: InputListing = {
     root: args.workspaceRoot,
     listed: gitFiles,
-    isInput: (rel) => (isPositive ??= anyTaskGlob(asTrees(positive)))(rel) && !excluded(rel),
+    isInput: (rel) =>
+      (isPositive ??= anyTaskGlob(asTrees(positive)))(rel) &&
+      !excludedByDeclaration(rel) &&
+      !own(rel),
     nested: () => false,
     ...reachOf(positive),
   }
-  if (memoKey !== undefined) {
-    const hit = args.memo!.get(memoKey)
-    if (hit !== undefined && hit.snapshot === gitFiles) return { files: hit.result, listing }
+  // Two levels: the declaration's files over the snapshot, shared by every
+  // task that declares it, then the task's own outputs taken out. A
+  // Turbo-mapped repo gives two thousand tasks one 400-entry list, and a
+  // memo keyed by the project too scanned, resolved and sorted the 4,000
+  // files it matched once per task (astro, 2026-10-09).
+  const declared = JSON.stringify([positive, negative])
+  let base: Promise<string[]> | undefined
+  const hit = args.memo?.get(declared)
+  if (hit !== undefined && hit.snapshot === gitFiles) base = hit.result
+  if (base === undefined) {
+    isPositive ??= anyTaskGlob(asTrees(positive))
+    base = resolveWorkspaceFilesOver(args, gitFiles, positive, isPositive, excludedByDeclaration)
+    args.memo?.set(declared, { snapshot: gitFiles, result: base })
   }
-  isPositive ??= anyTaskGlob(asTrees(positive))
-  const result = resolveWorkspaceFilesOver(
-    args,
-    gitFiles,
-    positive,
-    isPositive,
-    excluded,
-    undecodable,
-  )
-  if (memoKey !== undefined) args.memo!.set(memoKey, { snapshot: gitFiles, result })
-  return { files: result, listing }
+  const ownsAny =
+    splitNegations(args.ownWorkspaceOutputs).positive.length > 0 ||
+    splitNegations(args.ownOutputs).positive.length > 0
+  const files = base.then((all) => {
+    const kept = ownsAny ? all.filter((abs) => !own(relPosix(args.workspaceRoot, abs))) : all
+    refuseUndecodable(kept, undecodable, args.workspaceRoot, 'workspaceFiles')
+    return kept
+  })
+  return { files, listing }
 }
 
 async function resolveWorkspaceFilesOver(
@@ -352,7 +355,6 @@ async function resolveWorkspaceFilesOver(
   positive: readonly string[],
   isPositive: (rel: string) => boolean,
   excluded: (rel: string) => boolean,
-  undecodable: ReadonlySet<string> | undefined,
 ): Promise<string[]> {
   // Second call site of the literal-input guard. `resolveWorkspaceFiles`
   // carries its own copy of the filter-over-git-set design, so the same
@@ -371,13 +373,47 @@ async function resolveWorkspaceFilesOver(
   if (unmatchedLiterals.size > 0) {
     await assertNoInvisibleLiteralInputs(unmatchedLiterals, args.workspaceRoot, 'workspaceFiles')
   }
-  refuseUndecodable(candidates, undecodable, args.workspaceRoot, 'workspaceFiles')
   // Same OID-trust shortcut as project files: a clean-per-status
   // tracked file necessarily exists on disk.
   const oids = args.gitFilesCache?.oidsFor(args.workspaceRoot)
   return candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs)).sort()
 }
 
+/**
+ * The sorted union of two path lists, each once. Both sides arrive sorted
+ * and distinct, so one merge does what a Set and a sort of the
+ * concatenation did: 3.7 s of an astro plan, where 2,000 tasks each joined
+ * a few project files to the same 4,000 workspace files (2026-10-09). A
+ * side out of order takes the general path.
+ */
+function mergeSorted(a: readonly string[], b: readonly string[]): string[] {
+  if (a.length === 0 && isStrictlySorted(b)) return b as string[]
+  if (!isStrictlySorted(a) || !isStrictlySorted(b)) return [...new Set([...a, ...b])].sort()
+  const out: string[] = []
+  let i = 0
+  let j = 0
+  while (i < a.length && j < b.length) {
+    const x = a[i]!
+    const y = b[j]!
+    if (x <= y) {
+      out.push(x)
+      i++
+      if (x === y) j++
+    } else {
+      out.push(y)
+      j++
+    }
+  }
+  while (i < a.length) out.push(a[i++]!)
+  while (j < b.length) out.push(b[j++]!)
+  return out
+}
+
+function isStrictlySorted(list: readonly string[]): boolean {
+  for (let i = 1; i < list.length; i++) if (!(list[i - 1]! < list[i]!)) return false
+  return true
+}
+
 /** A project-relative matcher asked of root-relative paths: false outside the project. */
 function underProject(
   projectRel: string,

package/src/cli/docs.ts

@@ -48,7 +48,7 @@ export interface DocsHit {
 }
 
 function words(s: string): string[] {
-  return s.toLowerCase().match(/[a-z0-9][a-z0-9._-]*/g) ?? []
+  return s.toLowerCase().match(/[a-z0-9][a-z0-9_.-]*/g) ?? []
 }
 
 /** GitHub's heading anchor, which Starlight shares: lowercase, punctuation dropped, spaces to `-`. */
@@ -99,7 +99,11 @@ function count(hay: string, term: string): number {
   return n
 }
 
-/** The sections holding every term, best first: a term in the heading outweighs any count in the text. */
+/**
+ * The sections holding every term, best first: a term in the heading
+ * outweighs any count in the text. A section titled by the one word asked
+ * (an error code) is the answer alone.
+ */
 export function searchDocs(
   pages: Readonly<Record<string, string>>,
   terms: readonly string[],
@@ -123,7 +127,9 @@ export function searchDocs(
     }
   }
   scored.sort((a, b) => b.score - a.score || a.order - b.order)
-  return scored.slice(0, limit).map(({ s }) => ({
+  const exact =
+    terms.length === 1 ? scored.filter(({ s }) => words(s.heading).join(' ') === terms[0]) : []
+  return (exact.length > 0 ? exact : scored).slice(0, limit).map(({ s }) => ({
     page: s.page,
     heading: s.heading,
     url: s.heading === '' ? pageUrl(s.page) : `${pageUrl(s.page)}#${anchor(s.heading)}`,

package/src/cli/help.ts

@@ -261,7 +261,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Docs:',
     '  vx docs <query>      Search the reference offline (cli, schema, caching, execution,',
     '                       patterns, security, features): the sections holding every',
-    '                       word of the query print whole, best first, with their URL.',
+    '                       word of the query print whole, best first, with their URL;',
+    '                       an error code (vx docs VX_E_CYCLE) prints its fix alone.',
     '      --limit N        How many sections (default 3).',
     '      --format json    {query, hits: [{page, heading, url, text}]}.',
     '',

package/src/cli/init.ts

@@ -421,12 +421,17 @@ const INSTALL: Record<PackageManager, string> = {
 
 const EXEC: Record<PackageManager, string> = { pnpm: 'pnpm', yarn: 'yarn', bun: 'bunx', npm: 'npx' }
 
-/** Install what the workspace file imports, if missing, then run the repo's build. */
+/**
+ * Install what the workspace file imports, if missing, then run the repo's
+ * build. Pinned to this vx's version: every @vzn package releases in
+ * lockstep, and `latest` beside an older vx mismatched them (agent trial 2).
+ */
 export function adoptionNext(
   root: string,
   runner: 'turbo' | 'nx',
   source: string,
   needs: readonly string[] = ['@vzn/vx', '@vzn/vx-migrate'],
+  version: string = VERSION,
 ): string {
   const pm = LOCKFILES.find(([f]) => existsSync(path.join(root, f)))?.[1] ?? 'npm'
   const missing = needs.filter(
@@ -443,7 +448,9 @@ export function adoptionNext(
     pm === 'yarn' && !readText(path.join(root, 'yarn.lock')).includes('__metadata:')
       ? `${INSTALL.yarn} -W`
       : INSTALL[pm]
-  return `${install} ${missing.join(' ')} && ${run}`
+  // A source checkout is 0.0.0, which npm never had.
+  const pinned = version === '0.0.0' ? missing : missing.map((p) => `${p}@${version}`)
+  return `${install} ${pinned.join(' ')} && ${run}`
 }
 
 function readText(file: string): string {

package/src/cli/plan-format.ts

@@ -145,10 +145,12 @@ export interface PlanTaskJson {
   affected?: AffectedReason
 }
 
-export function formatPlanJson(plan: RunPlan): string {
+/** `affectedBase`: the ref a bare `--affected` guessed (or was given), so a reader knows what the diff was against. */
+export function formatPlanJson(plan: RunPlan, affectedBase?: string): string {
   return (
     JSON.stringify(
       {
+        ...(affectedBase !== undefined ? { affectedBase } : {}),
         tasks: plan.tasks.map((t): PlanTaskJson => {
           const description = shownDescription(t)
           return {

package/src/cli/run.ts

@@ -521,6 +521,8 @@ export async function resolveRunOptions(
   cwd: string,
   tasks: readonly string[],
   verb: 'run' | 'watch' = 'run',
+  /** Given, it learns the ref `--affected` diffed from (`--dry=json` states it). */
+  scopeOut?: { affectedBase?: string },
 ): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
   for (const t of tasks) {
     const idx = t.indexOf('#')
@@ -536,6 +538,9 @@ export async function resolveRunOptions(
   const scope = await scopeFilters(parsed, cwd)
   if ('error' in scope) return scope
   const { filterStrings, affectedFilter } = scope
+  // `...[<base>]`: the base alone.
+  if (scopeOut !== undefined && affectedFilter !== undefined)
+    scopeOut.affectedBase = affectedFilter.slice(4, -1)
 
   // Project scope applies to bare task names only. Anchored entries
   // (pkg#task) resolve directly to their own project regardless.
@@ -709,7 +714,8 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     tasks = [picked]
   }
 
-  const resolved = await resolveRunOptions(parsed, cwd, tasks)
+  const scopeOut: { affectedBase?: string } = {}
+  const resolved = await resolveRunOptions(parsed, cwd, tasks, 'run', scopeOut)
   if ('error' in resolved) return refuse('run', args, resolved.error, 'VX_E_USAGE')
   if ('nothingSelected' in resolved) {
     process.stderr.write(`vx run: ${resolved.nothingSelected}\n`)
@@ -769,7 +775,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
         }
       }
     } else if (parsed.dry === 'json') {
-      process.stdout.write(formatPlanJson(plan))
+      process.stdout.write(formatPlanJson(plan, scopeOut.affectedBase))
     } else {
       process.stdout.write(formatPlanText(plan))
     }

package/src/config.ts

@@ -46,6 +46,15 @@ export interface WorkspaceConfig {
    * folded into a cache key.
    */
   cacheScope?: string
+  /**
+   * Which ready task starts first when there are more than workers, with no
+   * timings: `most-work` (the default) the one the most work waits on at
+   * any depth, `critical-path` the head of the longest chain of tasks,
+   * `direct-dependents` the one the most tasks wait on directly (Nx's
+   * rule), `ready-order` the one that became ready first (Turbo's). A
+   * `schedule` plugin's weights still come first; this breaks their ties.
+   */
+  schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
   /**
    * Graph rules a run checks before it schedules anything. Each is on unless
    * set to `false`; turning one off allows a shape vx handles correctly but

package/src/graph/priorities.ts

@@ -125,20 +125,26 @@ export function computeReverseDepCount(nodes: Map<string, TaskNode>): Map<string
   }
 
   // Reverse-topo sweep: every direct dependent's closure is final
-  // before its dependency folds it in. closure[i] = bitset over node
-  // indices of i's transitive dependents.
+  // before its dependency folds it in. closure[t] = bitset over topo
+  // POSITIONS of the node at position t's transitive dependents. A
+  // dependent sits after its dependency, so a closure holds only bits
+  // past its own position, and each OR starts at the dependent's word:
+  // half the words of indexing by insertion order on a layered graph.
+  const pos = new Int32Array(n)
+  for (let t = 0; t < tail; t++) pos[topo[t]!] = t
   const closure = new Uint32Array(n * words)
   const counts = new Map<string, number>()
   for (let t = tail - 1; t >= 0; t--) {
     const i = topo[t]!
-    const base = i * words
-    for (const r of directReverse[i]!) {
+    const base = t * words
+    for (const ri of directReverse[i]!) {
+      const r = pos[ri]!
       closure[base + (r >>> 5)]! |= 1 << (r & 31)
       const rbase = r * words
-      for (let w = 0; w < words; w++) closure[base + w]! |= closure[rbase + w]!
+      for (let w = r >>> 5; w < words; w++) closure[base + w]! |= closure[rbase + w]!
     }
     let count = 0
-    for (let w = 0; w < words; w++) {
+    for (let w = t >>> 5; w < words; w++) {
       let v = closure[base + w]!
       v = v - ((v >>> 1) & 0x55555555)
       v = (v & 0x33333333) + ((v >>> 2) & 0x33333333)
@@ -153,6 +159,66 @@ export function computeReverseDepCount(nodes: Map<string, TaskNode>): Map<string
   return counts
 }
 
+/**
+ * The ready-queue baseline a workspace may pick in place of the default
+ * (`schedule` in vx.workspace.ts). Each ranks with no timings; a `schedule`
+ * plugin's weights still sort above it, and it breaks their ties.
+ *   - `most-work`: transitive dependents (`computeReverseDepCount`), the default.
+ *   - `critical-path`: steps on the longest chain of dependents below a task.
+ *   - `direct-dependents`: direct dependents only, Nx's rule.
+ *   - `ready-order`: none; the task that became ready first starts first, Turbo's rule.
+ */
+export type ScheduleStrategy = 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
+
+/** The baseline for a strategy other than `most-work`, over the whole graph. */
+export function strategyPriorities(
+  nodes: Map<string, TaskNode>,
+  strategy: Exclude<ScheduleStrategy, 'most-work'>,
+): Map<string, number> {
+  const out = new Map<string, number>()
+  if (strategy === 'ready-order') {
+    for (const id of nodes.keys()) out.set(id, 0)
+    return out
+  }
+  const dependents = new Map<string, string[]>()
+  for (const node of nodes.values()) {
+    for (const dep of node.deps) {
+      if (!nodes.has(dep)) continue
+      const list = dependents.get(dep)
+      if (list === undefined) dependents.set(dep, [node.id])
+      else list.push(node.id)
+    }
+  }
+  if (strategy === 'direct-dependents') {
+    for (const id of nodes.keys()) out.set(id, dependents.get(id)?.length ?? 0)
+    return out
+  }
+  // Longest chain below each task, dependents first: a task's depth is one
+  // more than its deepest dependent's. Iterative, as a deep chain would
+  // overflow a recursive walk.
+  const left = new Map<string, number>()
+  const ready: string[] = []
+  for (const id of nodes.keys()) {
+    const n = dependents.get(id)?.length ?? 0
+    left.set(id, n)
+    if (n === 0) ready.push(id)
+  }
+  while (ready.length > 0) {
+    const id = ready.pop()!
+    let depth = 0
+    for (const d of dependents.get(id) ?? []) depth = Math.max(depth, out.get(d)! + 1)
+    out.set(id, depth)
+    for (const dep of nodes.get(id)!.deps) {
+      if (!nodes.has(dep)) continue
+      const n = left.get(dep)! - 1
+      left.set(dep, n)
+      if (n === 0) ready.push(dep)
+    }
+  }
+  for (const id of nodes.keys()) if (!out.has(id)) out.set(id, 0)
+  return out
+}
+
 export function mergePriorities(
   baseline: ReadonlyMap<string, number>,
   overrides: ReadonlyMap<string, number>,

package/src/graph/scheduler.ts

@@ -5,7 +5,13 @@ import {
   isUserError,
   OUT_OF_FDS_HINT,
 } from '../util/index.js'
-import { computeReverseDepCount, mergePriorities, tieredReverseDepCount } from './priorities.js'
+import {
+  computeReverseDepCount,
+  mergePriorities,
+  strategyPriorities,
+  tieredReverseDepCount,
+  type ScheduleStrategy,
+} from './priorities.js'
 import { isGroupTask, type TaskNode } from './task-graph.js'
 
 /**
@@ -278,6 +284,11 @@ export interface ScheduleOptions {
    * heuristic (the default and historically the only behavior).
    */
   priorities?: ReadonlyMap<string, number>
+  /**
+   * The baseline ranking under `priorities` (`schedule` in vx.workspace.ts).
+   * Undefined or `most-work` is the reverse-deps count above.
+   */
+  strategy?: ScheduleStrategy
   /**
    * Restore-tier task ids: confirmed stable-key LOCAL cache hits (the
    * local short-circuit). A restore-tier task:
@@ -494,9 +505,11 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
   // use those weights. Falls back to the reverse-deps-count heuristic
   // for nodes the caller didn't score, so partial coverage works.
   const baseline =
-    options.restoreTier !== undefined && options.restoreTier.size > 0
-      ? tieredReverseDepCount(nodes, options.restoreTier)
-      : computeReverseDepCount(nodes)
+    options.strategy !== undefined && options.strategy !== 'most-work'
+      ? strategyPriorities(nodes, options.strategy)
+      : options.restoreTier !== undefined && options.restoreTier.size > 0
+        ? tieredReverseDepCount(nodes, options.restoreTier)
+        : computeReverseDepCount(nodes)
   const priority: ReadonlyMap<string, number> = options.priorities
     ? mergePriorities(baseline, options.priorities)
     : baseline

package/src/graph/task-graph.ts

@@ -1517,6 +1517,7 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
   const filesWriters: TaskNode[] = []
   let projectReaders = false
   let rootReaders = false
+  const memo: TakeBackMemo = { bySide: new Map(), byList: new Map() }
   const bucket = (name: string): Side[] => {
     let list = byProject.get(name)
     if (list === undefined) byProject.set(name, (list = []))
@@ -1557,7 +1558,7 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
         (s) => s.globs,
         (s) => s.reads,
       )) {
-        readsOutputs(sides[i]!, sides[j]!, 'files')
+        readsOutputs(memo, sides[i]!, sides[j]!, 'files')
       }
     }
   }
@@ -1575,7 +1576,7 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
       (s) => s.globs,
       (s) => s.reads,
     )) {
-      readsOutputs(sides[i]!, sides[j]!, 'files')
+      readsOutputs(memo, sides[i]!, sides[j]!, 'files')
     }
   }
   if (!rootReaders) return
@@ -1593,26 +1594,63 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
     (s) => s.globs,
     (s) => s.reads,
   )) {
-    readsOutputs(rooted[i]!, rooted[j]!, 'workspaceFiles')
+    readsOutputs(memo, rooted[i]!, rooted[j]!, 'workspaceFiles')
   }
 }
 
-function readsOutputs(x: Side, y: Side, field: 'files' | 'workspaceFiles'): void {
+/**
+ * Whether a reader's take-back list covers an output glob, asked once per
+ * list and glob: a Turbo-mapped repo gives two thousand readers one
+ * 400-entry list, and asking it per reader and writer pair was 2.7 s of an
+ * astro plan (2026-10-09). One per `detectInputOverlaps` call.
+ */
+interface TakeBack {
+  list: string[]
+  verdicts: Map<string, boolean>
+}
+type TakeBackMemo = { bySide: Map<Side, TakeBack>; byList: Map<string, TakeBack> }
+
+function takenBack(
+  memo: TakeBackMemo,
+  reader: Side,
+  field: 'files' | 'workspaceFiles',
+  go: string,
+): boolean {
+  let tb = memo.bySide.get(reader)
+  if (tb === undefined) {
+    const cache = reader.node.config.cache!
+    // A reader rebased to the root (X-135) speaks in its project's terms.
+    const at = reader.rel === undefined || reader.rel === '' ? '' : `${reader.rel}/`
+    // What the reader's key never reads: its `!` entries and its own outputs.
+    const list = [
+      ...splitNegations(
+        field === 'files' ? cache.inputs.files : (cache.inputs.workspaceFiles ?? []),
+      ).negative,
+      ...splitNegations(
+        field === 'files' ? cache.outputs.files : (cache.outputs.workspaceFiles ?? []),
+      ).positive,
+    ].map((g) => at + g)
+    const key = list.join('\0')
+    tb = memo.byList.get(key)
+    if (tb === undefined) memo.byList.set(key, (tb = { list, verdicts: new Map() }))
+    memo.bySide.set(reader, tb)
+  }
+  let verdict = tb.verdicts.get(go)
+  if (verdict === undefined) tb.verdicts.set(go, (verdict = outputTakenBack(go, tb.list)))
+  return verdict
+}
+
+function readsOutputs(
+  memo: TakeBackMemo,
+  x: Side,
+  y: Side,
+  field: 'files' | 'workspaceFiles',
+): void {
   if (x.reads === y.reads || x.node === y.node) return
   const [reader, writer] = x.reads ? [x, y] : [y, x]
-  const cache = reader.node.config.cache!
-  // A reader rebased to the root (X-135) speaks in its project's terms.
   const at = reader.rel === undefined || reader.rel === '' ? '' : `${reader.rel}/`
-  // What the reader's key never reads: its `!` entries and its own outputs.
-  const takeBack = [
-    ...splitNegations(field === 'files' ? cache.inputs.files : (cache.inputs.workspaceFiles ?? []))
-      .negative,
-    ...splitNegations(
-      field === 'files' ? cache.outputs.files : (cache.outputs.workspaceFiles ?? []),
-    ).positive,
-  ].map((g) => at + g)
   for (const go of writer.globs) {
-    if (outputTakenBack(go, takeBack)) continue
+    if (takenBack(memo, reader, field, go)) continue
     for (const gi of reader.globs) {
       if (!outputsOverlap(gi, go)) continue
       const shown =

package/src/orchestrator/remote-prefetch.ts

@@ -113,11 +113,17 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
  */
 export function getContext(node: TaskNode, command: string) {
   const outputs = node.config.cache?.outputs
+  let masked: string | undefined
   return {
     taskId: node.id,
     // Stored in the entry row a remote hit inserts: masked as a save's is,
-    // or the token a config inlined sat in cache.db (L-27).
-    command: maskedCommand(command, node.config.exec?.env),
+    // or the token a config inlined sat in cache.db (L-27). Masked on the
+    // first read: only an adopt or a remote hit reads it, and masking every
+    // lookup's command cost a cold 1,090-package run ~20 ms before its
+    // first task.
+    get command() {
+      return (masked ??= maskedCommand(command, node.config.exec?.env))
+    },
     outputs: { files: outputs?.files ?? [], workspaceFiles: outputs?.workspaceFiles ?? [] },
   }
 }

package/src/orchestrator/run.ts

@@ -945,7 +945,15 @@ async function runOnBus(
     // shouldShortCircuit (local reads on, no remote layer); when off, both
     // maps are empty and the run is byte-identical.
     let shortCircuit: ShortCircuit = emptyShortCircuit()
-    if (shouldShortCircuit(nodes, policy, cache)) {
+    // An empty local cache answers every probe with a miss: each task
+    // derives its key as it starts instead (~100 ms before a cold 1,090-
+    // package run's first spawn), and every sandboxed task runs.
+    const coldLocal =
+      cache === prepared.localCache &&
+      shouldShortCircuit(nodes, policy, cache) &&
+      prepared.localCache.holdsNothing()
+    if (coldLocal) prewarm()
+    else if (shouldShortCircuit(nodes, policy, cache)) {
       shortCircuit = await startLocalShortCircuit({
         nodes,
         cache,
@@ -1165,6 +1173,10 @@ async function runOnBus(
       // A `schedule` plugin's weights; the scheduler keeps its structural
       // baseline as the tie-break. Empty map → baseline only.
       ...(prepared.priorities.size > 0 ? { priorities: prepared.priorities } : {}),
+      // The baseline under them; `most-work` when the workspace names none.
+      ...(prepared.workspaceConfig?.schedule !== undefined
+        ? { strategy: prepared.workspaceConfig.schedule }
+        : {}),
       // Local short-circuit: confirmed stable local hits the scheduler
       // runs ahead of their deps as low-priority worker-slot backfill.
       // Empty when the short-circuit didn't fire → byte-identical.

package/src/util/errors.ts

@@ -62,9 +62,16 @@ export function wantsJson(argv: readonly string[]): boolean {
   return false
 }
 
-/** The JSON a verb that answers JSON prints for a refusal: one line. */
+/**
+ * The JSON a verb that answers JSON prints for a refusal: one line. A
+ * core code (`VX_E_…`) links its section of cli.md, which says the fix;
+ * `vx docs <code>` prints the same section offline. A plugin's code has none.
+ */
 export function errorDocument(code: string, message: string): string {
-  return `${JSON.stringify({ ok: false, error: { code, message } })}\n`
+  const docs = code.startsWith('VX_E_')
+    ? { docs: `https://vznjs.github.io/vx/cli/#${code.toLowerCase()}` }
+    : {}
+  return `${JSON.stringify({ ok: false, error: { code, message, ...docs } })}\n`
 }
 
 /**

package/src/util/paths.ts

@@ -195,6 +195,30 @@ export const EXTGLOB = /[!@+*?]\(/
  * else: one site that forgot is a route directory that keys nothing.
  */
 export function taskGlob(pattern: string): Bun.Glob {
+  const memo = memoFor(taskGlobs)
+  let glob = memo.get(pattern)
+  if (glob === undefined) memo.set(pattern, (glob = compileTaskGlob(pattern)))
+  return glob
+}
+
+/**
+ * Compiled once per pattern: a Turbo-mapped config repeats one 400-entry
+ * list across two thousand tasks, and the graph's overlap checks compiled
+ * each entry per task pair, 3.3 s of an astro plan (2026-10-09). A pattern
+ * comes from a config, so the set is bounded by what the configs say. Kept
+ * per `Bun.Glob` in force: the playground and a test swap it, and a glob
+ * built by one is not the other's.
+ */
+const taskGlobs = new WeakMap<object, Map<string, Bun.Glob>>()
+const anyTaskGlobs = new WeakMap<object, Map<string, (rel: string) => boolean>>()
+
+function memoFor<T>(memos: WeakMap<object, Map<string, T>>): Map<string, T> {
+  let memo = memos.get(Bun.Glob)
+  if (memo === undefined) memos.set(Bun.Glob, (memo = new Map()))
+  return memo
+}
+
+function compileTaskGlob(pattern: string): Bun.Glob {
   // A `]` with no `[` before it is already literal to `Bun.Glob`.
   const source = pattern.includes('[') ? pattern.replace(/(?<!\\)[[\]]/g, '\\$&') : pattern
   const glob = new Bun.Glob(source)
@@ -228,6 +252,14 @@ export function taskGlob(pattern: string): Bun.Glob {
  * `src/a.ts` and never `src/deep/a.ts`, and an edit there was a stale hit.
  */
 export function anyTaskGlob(rawPatterns: readonly string[]): (rel: string) => boolean {
+  const memo = memoFor(anyTaskGlobs)
+  const key = rawPatterns.join('\0')
+  let any = memo.get(key)
+  if (any === undefined) memo.set(key, (any = compileAnyTaskGlob(rawPatterns)))
+  return any
+}
+
+function compileAnyTaskGlob(rawPatterns: readonly string[]): (rel: string) => boolean {
   const patterns = rawPatterns.flatMap(braceAlternatives)
   if (patterns.length === 0) return () => false
   const sources = patterns.map(regExpSource)

package/src/workspace/config-schema.ts

@@ -56,9 +56,18 @@ const WORKSPACE_FIELDS = new Set([
   'affectedBase',
   'cacheScope',
   'rules',
+  'schedule',
   'plugins',
 ])
 
+type Schedule = NonNullable<WorkspaceConfig['schedule']>
+const SCHEDULES = {
+  'most-work': true,
+  'critical-path': true,
+  'direct-dependents': true,
+  'ready-order': true,
+} satisfies Record<Schedule, true>
+
 const RULE_FIELDS = new Set(['exclusiveOutputs', 'upfrontKeys'])
 
 function validateRules(rules: unknown, configPath: string): void {
@@ -184,6 +193,13 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     throw new UserError(`${configPath}: \`cacheScope\` ${CACHE_SCOPE_RULE}`)
   }
   if (config.rules !== undefined) validateRules(config.rules, configPath)
+  if (config.schedule !== undefined && !Object.hasOwn(SCHEDULES, config.schedule)) {
+    throw new UserError(
+      `${configPath}: \`schedule\` must be one of ${Object.keys(SCHEDULES)
+        .map((k) => `'${k}'`)
+        .join(', ')}`,
+    )
+  }
   if (config.plugins !== undefined) {
     if (!Array.isArray(config.plugins)) {
       throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)

package/src/workspace/lockfile.ts

@@ -36,6 +36,8 @@ export interface LockfileEntry {
 export interface Lockfile {
   version: number
   projects: Record<string, LockfileEntry>
+  /** Written by `writeLockfile` from the bytes; never read off the object. */
+  validated?: string
 }
 
 export function lockfilePath(root: string): string {
@@ -100,12 +102,33 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
     }
   }
   lockDigests.set(parsed, xxh3(text).toString(16))
+  const stamped = VALIDATED_LINE.exec(text)
+  if (stamped !== null && stamped[1] === validatedDigest(text.slice(0, stamped.index) + '\n}')) {
+    selfValidated.add(parsed)
+  }
   return parsed as Lockfile
 }
 
 /** The digest of the bytes each lock `readLockfile` returned was parsed from. */
 const lockDigests = new WeakMap<object, string>()
 
+/**
+ * The lock's own record that this vx validated its entries: `vx lock`
+ * evaluates and validates every config, then writes a digest of the bytes
+ * it wrote, under vx's version (validation's rules are vx's alone, so Bun's
+ * is left out and does not churn a committed lock), as the last field. A lock
+ * whose digest matches is validated already, and a cold `--frozen` run
+ * skips the ~30 ms of validating 1,090 entries before its first task. An
+ * edit, a merge, or another vx version leaves it unmatched, and the
+ * entries are validated as before.
+ */
+const VALIDATED_LINE = /,\n {2}"validated": "([0-9a-f]+)"\n\}\n?$/
+const selfValidated = new WeakSet<object>()
+
+function validatedDigest(body: string): string {
+  return xxh3(`vx-lock-valid-v${CONFIG_EVAL_VERSION}\0${VERSION}\0${body}`).toString(16)
+}
+
 export async function writeLockfile(root: string, lock: Lockfile): Promise<void> {
   // Written beside its name and renamed over it: `Bun.write` truncates in
   // place, so a `--frozen` run, or `vx watch --frozen` woken by the write
@@ -114,7 +137,8 @@ export async function writeLockfile(root: string, lock: Lockfile): Promise<void>
   const file = lockfilePath(root)
   const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`
   try {
-    await Bun.write(tmp, `${JSON.stringify(lock, null, 2)}\n`)
+    const body = JSON.stringify({ version: lock.version, projects: lock.projects }, null, 2)
+    await Bun.write(tmp, `${body.slice(0, -2)},\n  "validated": "${validatedDigest(body)}"\n}\n`)
     await rename(tmp, file)
   } catch (err) {
     // Best effort: where the write was refused the temp cannot be named
@@ -187,7 +211,10 @@ export async function frozenProjectConfigs(
   // asked for 1,090 per-project rows in one `IN` query, ~10 ms of its
   // config load, where the eval-cache path it replaces is cheaper (X-181).
   // A scoped run still validates, and remembers, only what it loads.
-  if (prefix !== undefined && store !== undefined && store.getConfigEval(prefix) !== null) {
+  if (
+    selfValidated.has(lock) ||
+    (prefix !== undefined && store !== undefined && store.getConfigEval(prefix) !== null)
+  ) {
     return entries.map((e) => e.config)
   }
   const keys = prefix === undefined ? undefined : metas.map((m) => `${prefix}\0${m.name}`)