@vzn/vx 0.0.350 → 0.0.353

package/README.md

@@ -180,7 +180,7 @@ keep your Turbo or Nx remote cache. [Parity map](packages/vx/docs/parity.md) ·
 | Config                    | TypeScript, evaluated into the cache key  | JSON (static)                  | JSON (static)    |
 | Output ownership          | **Strict**: wiped before exec and restore | Additive (stale files survive) | Additive         |
 | Clean-tree hashing        | **Zero reads** (git index OIDs)           | git OIDs                       | re-hash / daemon |
-| Daemon required for speed | **No**                                    | Optional                       | Yes              |
+| Daemon required for speed | **No**                                    | No (`turbo run` has none)      | Yes              |
 | Per-task sandbox          | **Yes**: kernel-level, opt-in             | No                             | No               |
 | Plugin API                | **Yes**: every pipeline stage             | No                             | Yes (TS-tied)    |
 | OTel CI/CD spans          | **Yes**: `otel()` plugin, no OTel SDK     | No                             | Paid             |

package/package.json

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

package/src/cache/cache.ts

@@ -674,7 +674,7 @@ export class Cache implements CacheLayer {
             }
             if (found === SCHEMA_VERSION) return null
             this.db.exec(
-              'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs; DROP TABLE IF EXISTS config_evals; DROP TABLE IF EXISTS config_closures; DROP TABLE IF EXISTS output_dirs;',
+              'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS blob_sizes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs; DROP TABLE IF EXISTS config_evals; DROP TABLE IF EXISTS config_closures; DROP TABLE IF EXISTS output_dirs;',
             )
             this.db
               .prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'")
@@ -798,6 +798,14 @@ export class Cache implements CacheLayer {
   hashFiles(paths: readonly string[]): Promise<Map<string, string>> {
     return this.guard(() => this.files.hashFiles(paths))
   }
+  /** `BlobSizeMemo`: the sizes of these blobs this cache has learned. */
+  knownBlobSizes(oids: readonly string[]): Map<string, number> {
+    return this.guard(() => this.files.knownBlobSizes(oids))
+  }
+  /** `BlobSizeMemo`: remember blob sizes, honouring the local WRITE axis. */
+  rememberBlobSizes(sizes: ReadonlyMap<string, number>): void {
+    this.guard(() => this.files.rememberBlobSizes(sizes))
+  }
   /**
    * `relPosix` against the run's workspace root, memoized: the same three
    * thousand files are re-relativized for every task of the project, which
@@ -807,11 +815,25 @@ export class Cache implements CacheLayer {
    */
   private relMemo = new Map<string, string>()
   private relMemoRoot: string | undefined
+  /** `root` and a slash, when a file under it is relative by slicing; else undefined. */
+  private relPrefix: string | undefined
   private relFor(root: string, file: string): string {
     if (root !== this.relMemoRoot) {
       this.relMemoRoot = root
       this.relMemo.clear()
+      this.relPrefix =
+        path.sep === '/' && path.isAbsolute(root) && path.normalize(root) === root
+          ? root.endsWith('/')
+            ? root
+            : `${root}/`
+          : undefined
     }
+    // An input file is a normalized absolute path (`resolveInputs` makes
+    // every one), and under a normalized root that is the root, a slash and
+    // its relative path: a slice, where the memo hashed the whole path per
+    // file per task (~15 ms over 36,000 files, I-31).
+    const prefix = this.relPrefix
+    if (prefix !== undefined && file.startsWith(prefix)) return file.slice(prefix.length)
     let rel = this.relMemo.get(file)
     if (rel === undefined) this.relMemo.set(file, (rel = relPosix(root, file)))
     return rel

package/src/cache/file-hashes.ts

@@ -68,12 +68,42 @@ export class FileHashStore {
     if (last !== null && now - Number(last.value) < DAY_MS) return
     this.db.transaction(() => {
       this.db.prepare('DELETE FROM file_hashes WHERE seen_at < ?').run(cutoff)
+      this.db.prepare('DELETE FROM blob_sizes WHERE seen_at < ?').run(cutoff)
       this.db
         .prepare('INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)')
         .run(FILE_HASHES_SWEPT_AT, String(now))
     })()
   }
 
+  /** Each of `oids` whose size a `rememberBlobSizes` stored: one `IN` query per 900. */
+  knownBlobSizes(oids: readonly string[]): Map<string, number> {
+    const out = new Map<string, number>()
+    for (let i = 0; i < oids.length; i += 900) {
+      const chunk = oids.slice(i, i + 900)
+      const rows = this.db
+        .query(`SELECT oid, size FROM blob_sizes WHERE oid IN (${chunk.map(() => '?').join(',')})`)
+        .all(...chunk) as Array<{ oid: string; size: number }>
+      for (const r of rows) out.set(r.oid, r.size)
+    }
+    return out
+  }
+
+  /** Store blob sizes in one transaction; a memo, so a full disk skips it. */
+  rememberBlobSizes(sizes: ReadonlyMap<string, number>): void {
+    if (!this.write || sizes.size === 0) return
+    const now = Date.now()
+    const insert = this.db.prepare(
+      'INSERT OR REPLACE INTO blob_sizes(oid, size, seen_at) VALUES (?, ?, ?)',
+    )
+    try {
+      this.db.transaction(() => {
+        for (const [oid, size] of sizes) insert.run(oid, size, now)
+      })()
+    } catch (err) {
+      if (!isIndexFull(err)) throw err
+    }
+  }
+
   /**
    * Content-hash a file (as a git blob OID, v20) with an mtime+size
    * fast path. If the `file_hashes` table has a row for `path` whose

package/src/cache/git-inputs.ts

@@ -6,7 +6,7 @@
 // task declared. Nothing here reads a config or applies a boundary.
 
 import path from 'node:path'
-import { existsSync, lstatSync, realpathSync } from 'node:fs'
+import { existsSync, lstatSync, readdirSync, realpathSync } from 'node:fs'
 import { UserError, executablePath, gitSpawnRefusal } from '../util/index.js'
 
 /** Three facts of the repository a directory is in, from one `git rev-parse`. */
@@ -394,7 +394,14 @@ function expandNestedRepos(
     }
     out ??= files.slice(0, i)
     const abs = path.join(cwd, nested)
-    if (!existsSync(path.join(abs, '.git'))) continue
+    if (!existsSync(path.join(abs, '.git'))) {
+      // No repository answers for it: a submodule never initialised (empty)
+      // or one whose `.git` was removed to vendor its files, the gitlink
+      // left in the index and `git status` silent. Its files are what the
+      // task reads, so a walk lists them; they hash by content (A-61).
+      for (const f of walkFiles(abs)) out.push(`${nested}/${f}`)
+      continue
+    }
     const inner = runGitLsFiles(abs)
     for (const f of inner.files) out.push(`${nested}/${f}`)
     for (const f of inner.undecodable) undecodable.push(`${nested}/${f}`)
@@ -402,6 +409,24 @@ function expandNestedRepos(
   return { files: out ?? files, undecodable }
 }
 
+/** Every file and symlink under `dir`, relative and `/`-separated; a `.git` is skipped, a link not followed. */
+function walkFiles(dir: string, rel = ''): string[] {
+  let entries
+  try {
+    entries = readdirSync(path.join(dir, rel), { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const out: string[] = []
+  for (const e of entries) {
+    if (e.name === '.git') continue
+    const r = rel === '' ? e.name : `${rel}/${e.name}`
+    if (e.isDirectory()) out.push(...walkFiles(dir, r))
+    else out.push(r)
+  }
+  return out
+}
+
 /**
  * A file's identity as the key folds it: its blob OID, prefixed by its git
  * mode unless that is a plain file's (100644). A blob OID holds no mode, so
@@ -451,6 +476,108 @@ function parseLsFilesOutput(out: string, undecodableRecords: ReadonlySet<string>
   return { files, oids, flagged, gitlinks, undecodable }
 }
 
+/**
+ * `ls-files -s -v -z --debug` as the plain `-s -v -z` stream, plus the size
+ * the index records for each regular stage-0 entry's worktree file and its
+ * raw OID. With `-z`, each record's NUL is followed by its five
+ * newline-ended debug lines (ctime, mtime, dev/ino, uid/gid, size/flags),
+ * then the next record.
+ */
+function stripLsDebug(run: GitRun): {
+  plain: string
+  undecodable: Set<string>
+  indexed: Map<string, { oid: string; size: number }>
+} {
+  const segs = run.stdout.split('\0')
+  const records: string[] = []
+  const undecodable = new Set<string>()
+  const indexed = new Map<string, { oid: string; size: number }>()
+  let record = segs[0]!
+  let recordRaw = record
+  for (let i = 1; i <= segs.length; i++) {
+    const seg = segs[i]
+    let rest = ''
+    let size = -1
+    if (seg !== undefined) {
+      let at = 0
+      for (let k = 0; k < 5 && at >= 0; k++) {
+        const nl = seg.indexOf('\n', at)
+        if (nl < 0) at = -1
+        else {
+          if (k === 4) size = Number(/size: (\d+)/.exec(seg.slice(at, nl))?.[1] ?? -1)
+          at = nl + 1
+        }
+      }
+      rest = at < 0 ? '' : seg.slice(at)
+    }
+    if (record.length > 0) {
+      records.push(record)
+      if (run.undecodable.has(recordRaw)) undecodable.add(record)
+      const m = LS_FILES_STAGE_RE.exec(record)
+      if (m !== null && m[4] === '0' && (m[2] === '100644' || m[2] === '100755')) {
+        indexed.set(record.slice(m[0].length), { oid: m[3]!, size })
+      }
+    }
+    record = rest
+    recordRaw = seg ?? ''
+  }
+  return { plain: records.join('\0'), undecodable, indexed }
+}
+
+/** Blob sizes learned once and kept: a blob's size is fixed for its OID. `Cache` is one. */
+export interface BlobSizeMemo {
+  knownBlobSizes(oids: readonly string[]): Map<string, number>
+  rememberBlobSizes(sizes: ReadonlyMap<string, number>): void
+}
+
+/**
+ * Drop each trusted OID whose blob is not the size the index recorded for
+ * the worktree file (A-60). A clean filter's blob differs from the file it
+ * was added from, and git holds a stat-clean entry clean without re-reading
+ * it once the filter is gone (`core.autocrlf` turned off, a `.gitattributes`
+ * rule removed): `status` and the filter gate, which reads today's config,
+ * both let the blob stand for bytes it does not hold. The recorded sizes
+ * cost no read of the worktree; the blob sizes come from `memo`, and only
+ * the ones it lacks from one `cat-file` (65 ms over 3,000 loose objects,
+ * the whole of the cost, measured 2026-10-02). A smudged (racy) entry
+ * records 0 and is hashed from disk. An answer that cannot be read trusts
+ * nothing.
+ */
+async function dropResizedOids(enumeration: GitEnumeration, memo?: BlobSizeMemo): Promise<void> {
+  const { trusted, indexed } = enumeration
+  const wanted = new Set<string>()
+  for (const rel of trusted.keys()) {
+    const entry = indexed.get(rel)
+    if (entry !== undefined) wanted.add(entry.oid)
+  }
+  if (wanted.size === 0) return
+  const sizes = memo?.knownBlobSizes([...wanted]) ?? new Map<string, number>()
+  const unknown = [...wanted].filter((oid) => !sizes.has(oid))
+  if (unknown.length > 0) {
+    const run = await enumeration.catFile(unknown.join('\n') + '\n')
+    if (run === null || run.exitCode !== 0) {
+      trusted.clear()
+      return
+    }
+    const learned = new Map<string, number>()
+    for (const line of run.stdout.split('\n')) {
+      const sp = line.indexOf(' ')
+      const n = Number(line.slice(sp + 1))
+      if (sp > 0 && line.slice(sp + 1) !== '' && Number.isInteger(n))
+        learned.set(line.slice(0, sp), n)
+    }
+    for (const [oid, n] of learned) sizes.set(oid, n)
+    memo?.rememberBlobSizes(learned)
+  }
+  for (const rel of trusted.keys()) {
+    const entry = indexed.get(rel)
+    if (entry === undefined) continue // a symlink: its blob is its target string
+    const size = sizes.get(entry.oid)
+    // The index keeps the low 32 bits of a size.
+    if (size === undefined || size % 2 ** 32 !== entry.size) trusted.delete(rel)
+  }
+}
+
 /** One completed `git` invocation. */
 interface GitRun {
   exitCode: number
@@ -825,7 +952,7 @@ export async function populateGitFilesCache(
     workspaceRoot,
     gitPathspecs(workspaceRoot, projectDirs, workspaceWide),
   )
-  applyGitEnumeration(enumeration, workspaceRoot, projectDirs, cache, workspaceWide)
+  await applyGitEnumeration(enumeration, workspaceRoot, projectDirs, cache, workspaceWide)
 }
 
 /** What one workspace-wide enumeration learned, before it is partitioned per project. */
@@ -851,6 +978,10 @@ export interface GitEnumeration {
   undecodable: readonly string[]
   /** `Date.now()` before the spawns: what `trusted` says is true as of no earlier. */
   startedAtMs: number
+  /** Each regular stage-0 entry's raw OID and the worktree size the index recorded. */
+  indexed: ReadonlyMap<string, { oid: string; size: number }>
+  /** `git cat-file --batch-check` over `stdin`'s OIDs; null when it could not spawn. */
+  catFile(stdin: string): Promise<{ exitCode: number; stdout: string } | null>
 }
 
 /** Above this many project dirs the enumeration walks the whole tree. */
@@ -891,7 +1022,11 @@ export async function startGitEnumeration(
   // bulk-populate costs max(ls-files, status) wall time, not the sum
   // (status alone is ~74 ms on a 1000-project tree; serial spawning
   // was a measurable warm-path regression vs the pre-OID code).
-  const spawnGit = async (args: string[], stdin?: string): Promise<GitRun | null> => {
+  const spawnGit = async (
+    args: string[],
+    stdin?: string,
+    env?: Record<string, string>,
+  ): Promise<GitRun | null> => {
     try {
       const proc = Bun.spawn({
         // `status` refreshes the index when it can take `index.lock`, so
@@ -903,6 +1038,7 @@ export async function startGitEnumeration(
         stdin: stdin === undefined ? 'ignore' : new TextEncoder().encode(stdin),
         stdout: 'pipe',
         stderr: 'pipe',
+        ...(env !== undefined ? { env: { ...process.env, ...env } } : {}),
       })
       const [stdout, stderr, exitCode] = await Promise.all([
         new Response(proc.stdout).bytes(),
@@ -924,8 +1060,14 @@ export async function startGitEnumeration(
   // tracked paths are dirty AND which files are untracked. Asking
   // `ls-files --others` for the untracked set walked the same tree a second
   // time (~50 ms of CPU, concurrent with status but contending with it).
+  // `--debug` adds each entry's recorded stat, for the blob-size check
+  // (`dropResizedOids`, A-60).
+  const listing = spawnGit(['ls-files', '-s', '-v', '-z', '--debug', '--', ...pathspecs]).then(
+    (run) =>
+      run === null || run.exitCode !== 0 ? { run, debug: null } : { run, debug: stripLsDebug(run) },
+  )
   const running = Promise.all([
-    spawnGit(['ls-files', '-s', '-v', '-z', '--', ...pathspecs]),
+    listing,
     // `--ignored=matching` names an ignored path without descending into an
     // ignored directory: git applies an ignored `.gitattributes` as it does
     // any other, and the filter gate below must see it (A-19).
@@ -965,7 +1107,7 @@ export async function startGitEnumeration(
   // at all. `--git-dir` named the per-worktree directory, so the gate
   // looked where the rule can never be.
   const facts = repoFacts(workspaceRoot)
-  const [ls, status, vars] = await running
+  const [{ run: ls, debug }, status, vars] = await running
   if (ls === null) {
     throw gitSpawnRefusal(workspaceRoot)
   }
@@ -982,7 +1124,7 @@ export async function startGitEnumeration(
     flagged,
     gitlinks,
     undecodable,
-  } = parseLsFilesOutput(ls.stdout, ls.undecodable)
+  } = parseLsFilesOutput(debug!.plain, debug!.undecodable)
   // Normalize `status`'s repo-root-relative paths to workspace-relative (strip
   // the `--show-prefix`) so the dirty set is keyed identically to the trusted
   // OID map. Without this, when the workspace root is a git subdir, a modified
@@ -1060,6 +1202,13 @@ export async function startGitEnumeration(
     untracked: dirty === null ? null : untracked,
     undecodable,
     startedAtMs,
+    indexed: debug!.indexed,
+    // A missing blob is an answer ("missing"), never a fetch from a partial
+    // clone's promisor remote.
+    catFile: (stdin) =>
+      spawnGit(['cat-file', '--batch-check=%(objectname) %(objectsize)'], stdin, {
+        GIT_NO_LAZY_FETCH: '1',
+      }),
   }
 }
 
@@ -1089,13 +1238,15 @@ export function lazyGitEnumeration(workspaceRoot: string): LazyGitEnumeration {
 }
 
 /** The partition half of `populateGitFilesCache`: store per-project slices of one enumeration. */
-export function applyGitEnumeration(
+export async function applyGitEnumeration(
   enumeration: GitEnumeration,
   workspaceRoot: string,
   projectDirs: readonly string[],
   cache: GitFilesCache,
   workspaceWide = false,
-): void {
+  memo?: BlobSizeMemo,
+): Promise<void> {
+  await dropResizedOids(enumeration, memo)
   const { all, trusted } = enumeration
   cache.setWorktreeDirty(enumeration.dirty)
   cache.enumeratedAtMs = enumeration.startedAtMs

package/src/cache/index.ts

@@ -43,6 +43,7 @@ export {
   ownWorkspaceOutputsSince,
   stampOutputs,
   stampWorkspaceOutputs,
+  stopRuntimeProbes,
   type OutputStamp,
 } from './inputs.js'
 export {

package/src/cache/inputs.ts

@@ -448,6 +448,22 @@ async function runRuntimeCommand(
  */
 const liveProbes = new Set<ReturnType<typeof Bun.spawn>>()
 let probeExitHooked = false
+
+/**
+ * Kill every runtime probe still running, with its tree. A run's stop asks
+ * this: a Ctrl-C while a probe ran waited for the probe, or for the signal
+ * handler's bound, about 7 s, before vx exited (C-65). Its answer is no
+ * longer needed; its caller sees it fail and the run reads it aborted.
+ */
+export function stopRuntimeProbes(): void {
+  for (const p of liveProbes) {
+    try {
+      process.kill(-p.pid, 'SIGKILL')
+    } catch {
+      // the group is gone
+    }
+  }
+}
 function killProbesOnExit(): void {
   if (probeExitHooked) return
   probeExitHooked = true
@@ -1041,6 +1057,13 @@ interface FilesPlan {
   positiveGlobs: Bun.Glob[]
   /** The literal entries, each naming one path (see `unmatchedLiterals`). */
   literals: string[]
+  /**
+   * Whether a project-relative path is an input by the declaration alone:
+   * a positive glob selects it, and no exclude and no own output takes it
+   * back. Projects repeat their relative paths (`src/index.ts`,
+   * `package.json`), so each is matched once per plan.
+   */
+  verdicts: Map<string, boolean>
 }
 
 /**
@@ -1082,6 +1105,7 @@ function filesPlan(
           ownOutput: outputMatcher(ownOutputs, globFor),
           positiveGlobs: asTrees(positive).map(globFor),
           literals: positive.map(normalizeGlob).filter(isLiteralPattern).map(stripTrailingSlash),
+          verdicts: new Map<string, boolean>(),
         }
   filesPlans.set(key, plan)
   return plan
@@ -1144,17 +1168,18 @@ async function resolveFiles(args: ResolveFilesArgs): Promise<string[]> {
   const unmatchedLiterals = new Set(plan.literals)
   // First pass: glob-filter to candidate absolute paths (no I/O).
   const candidates: string[] = []
+  const verdicts = plan.verdicts
   for (const rel of gitFiles) {
     if (unmatchedLiterals.size > 0) settleLiterals(unmatchedLiterals, rel)
-    let matched = false
-    for (const g of positiveGlobs) {
-      if (g.match(rel)) {
-        matched = true
-        break
-      }
+    let input = verdicts.get(rel)
+    if (input === undefined) {
+      input =
+        positiveGlobs.some((g) => g.match(rel)) &&
+        !excludeGlobs.some((g) => g.match(rel)) &&
+        !ownOutput(rel)
+      verdicts.set(rel, input)
     }
-    if (!matched) continue
-    if (nested(rel) || excludeGlobs.some((g) => g.match(rel)) || ownOutput(rel)) continue
+    if (!input || nested(rel)) continue
     candidates.push(path.resolve(args.projectDir, rel))
   }
   if (unmatchedLiterals.size > 0) {

package/src/cache/key-fold.ts

@@ -99,7 +99,11 @@ import type { CacheKeyInput } from './layer.js'
 // v37: an entry saved while `git status` hid a deletion (paired as an
 // unmerged path's rename source) holds output built without a file its key
 // folds (A-59).
-export const CACHE_VERSION = 'vx-cache-v37'
+// v38: an entry saved while the key folded a filtered LF blob for CRLF
+// bytes on disk, the filter since removed, holds the CRLF build (A-60).
+// v39: an entry saved while a gitlink without `.git` held files the key
+// never listed sits under the key of that directory empty (A-61).
+export const CACHE_VERSION = 'vx-cache-v39'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its

package/src/cache/schema.ts

@@ -115,6 +115,15 @@ export function createTables(db: Database): void {
       content_hash TEXT NOT NULL,
       seen_at      INTEGER NOT NULL
     );
+    -- The size of each index blob the enumeration checked against the
+    -- worktree size git recorded (A-60). Fixed for its OID, so a warm
+    -- run asks git for none; swept with file_hashes by seen_at, the
+    -- time the row was written.
+    CREATE TABLE IF NOT EXISTS blob_sizes (
+      oid     TEXT PRIMARY KEY,
+      size    INTEGER NOT NULL,
+      seen_at INTEGER NOT NULL
+    );
     -- v16: per-output-file fingerprints, scoped by the cache entry
     -- that produced them. Lets loadOutputFilesBatch(hashes) answer
     -- "for entry X, what are its outputs supposed to look like?"

package/src/cli/show.ts

@@ -339,6 +339,12 @@ function taskBlock(taskName: string, raw: TaskConfig): string {
     add('outputs.workspaceFiles', list(cache.outputs.workspaceFiles))
   }
   const labelW = Math.max(...rows.map(([label]) => label.length))
-  const body = rows.map(([label, value]) => `  ${`${label}:`.padEnd(labelW + 1)} ${value}`)
+  // A multi-line value (a generated `vx_script` wrapper, a heredoc)
+  // continues under its first line, not at column 0 where it reads as
+  // the next task's header.
+  const indent = `\n${' '.repeat(labelW + 4)}`
+  const body = rows.map(
+    ([label, value]) => `  ${`${label}:`.padEnd(labelW + 1)} ${value.replaceAll('\n', indent)}`,
+  )
   return `${taskName}\n${body.join('\n')}\n`
 }

package/src/cli/workspace-config.ts

@@ -141,7 +141,7 @@ export async function loadCliProjects(
       projectMetas: metas,
       seeds: scope,
       closure: false,
-      lock,
+      lock: lock === null ? null : async () => lock,
       evalCache:
         cache === null
           ? undefined

package/src/exec/index.ts

@@ -29,7 +29,13 @@ export {
   thrownReason,
 } from './sandbox-runtime.js'
 export { type DeniedCall } from './sandbox-violations.js'
-export { atOrUnder, isMountableLiteral, MOUNT_WILDCARDS, toRealPath } from './sandbox-paths.js'
+export {
+  atOrUnder,
+  isMountableLiteral,
+  MOUNT_WILDCARDS,
+  sandboxReads,
+  toRealPath,
+} from './sandbox-paths.js'
 export { bindableWrites, punchWalls } from './sandbox-binds.js'
 export { isLocalExecutor, localExecutor } from './local-executor.js'
 export { holdGroups, killTree, untilGroupsGone } from './kill-tree.js'

package/src/exec/sandbox-paths.ts

@@ -76,3 +76,25 @@ export function unique(arr: readonly string[]): string[] {
 export function localBindingOn(c: { localBinding?: boolean | readonly number[] }): boolean {
   return c.localBinding === true || (Array.isArray(c.localBinding) && c.localBinding.length > 0)
 }
+
+/**
+ * Whether a sandboxed task may read `file`: it lies under a read grant,
+ * a write grant or a baseline read, by its canonical path. A path no
+ * grant holds is not there inside the sandbox, which the shell reports
+ * as "not found" with no denial a trace can see (an `execve`).
+ */
+export function sandboxReads(
+  sandbox: {
+    readonly baseAllowRead: readonly string[]
+    readonly config: {
+      readonly allowRead: readonly string[]
+      readonly allowWrite: readonly string[]
+    }
+  },
+  file: string,
+): boolean {
+  const real = toRealPath(file)
+  return [...sandbox.baseAllowRead, ...sandbox.config.allowRead, ...sandbox.config.allowWrite].some(
+    (g) => atOrUnder(real, toRealPath(g)),
+  )
+}

package/src/exec/sandbox-runtime.ts

@@ -1006,12 +1006,21 @@ export async function wrapSandboxedCommand(
     process.platform === 'linux'
       ? ownGroupCommand(tag, inTmp, args.trace)
       : { command: taggedCommand, forwards: false, traced: false }
-  const inner =
-    ports.length > 0 ? `${portBridgeInner(ports, tag)} ${grouped.command}` : grouped.command
+  const inner = [
+    ports.length > 0 ? portBridgeInner(ports, tag) : '',
+    process.platform === 'linux' && args.config.network !== undefined ? PROXY_BRIDGE_WAIT : '',
+    grouped.command,
+  ]
+    .filter((part) => part !== '')
+    .join(' ')
   let wrapped = await wrapForTask(
     SandboxManager,
     inner,
-    process.platform === 'linux' ? literalReadPaths(customConfig) : customConfig,
+    process.platform === 'linux'
+      ? literalReadPaths(customConfig)
+      : process.platform === 'darwin'
+        ? seatbeltBrackets(customConfig)
+        : customConfig,
     ports.length > 0 || asksUnixSockets(args.config),
     args.config.gitConfig === true,
   )
@@ -1176,6 +1185,30 @@ function literalReadPaths(
   }
 }
 
+/**
+ * macOS: a grant's escaped bracket as seatbelt's SRT can read it. vx hands
+ * it the pattern, and SRT compiles any spelling holding `[` as a regex in
+ * which a backslash is a literal one, so `pages/\[id\].tsx` matched no
+ * file and the route could not be granted. `[[]` is a class of one `[`; a
+ * lone `]` is plain text (B-65).
+ */
+function seatbeltBrackets(
+  config: Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2],
+): Parameters<SrtModule['SandboxManager']['wrapWithSandbox']>[2] {
+  const fs = config?.filesystem
+  if (fs === undefined) return config
+  const literal = (paths: readonly string[]): string[] =>
+    paths.map((p) => p.replaceAll('\\[', '[[]').replaceAll('\\]', ']'))
+  return {
+    ...config,
+    filesystem: {
+      ...fs,
+      allowWrite: literal(fs.allowWrite),
+      ...(fs.allowRead !== undefined ? { allowRead: literal(fs.allowRead) } : {}),
+    },
+  }
+}
+
 /** SRT's wrap, with the socket lift and the git-config grant this task asked for, or none (L-6, B-41). */
 function wrapForTask(
   SandboxManager: SrtModule['SandboxManager'],
@@ -1203,6 +1236,18 @@ export function bridgedPorts(c: Pick<ResolvedSandboxConfig, 'localBinding'>): nu
   return Array.isArray(c.localBinding) ? [...new Set(c.localBinding)] : []
 }
 
+/**
+ * Linux: SRT starts its in-sandbox proxy bridges (`socat TCP-LISTEN:3128`
+ * and `:1080`) in the background and runs the command at once, so a
+ * networked task that dialled the proxy first met "connection refused"
+ * (curl's `000`) on a loaded box (M-20). This waits, in front of the
+ * command, until both listen in the task's network namespace, read off
+ * /proc/net (IPv4 or IPv6, state 0A). Bounded at ~5 s: a bridge that never
+ * listens leaves the command to meet the refusal it met before.
+ */
+const PROXY_BRIDGE_WAIT =
+  "( i=0; until grep -qsE ':0C38 [0-9A-F]+:0000 0A' /proc/net/tcp /proc/net/tcp6 && grep -qsE ':0438 [0-9A-F]+:0000 0A' /proc/net/tcp /proc/net/tcp6; do [ $i -ge 500 ] && break; i=$((i+1)); sleep 0.01; done );"
+
 /** Where a bridge's unix socket lives: the sandbox tmpdir, bound read-write on both sides. */
 export function portBridgeSocket(tag: string, port: number): string {
   return path.join(taskTmpdir(tag), `vx-port-${tag}-${port}.sock`)

package/src/exec/sandbox-violations.ts

@@ -100,7 +100,14 @@ export interface DeniedCall {
 // a child starts in its parent's cwd as it was at the fork.
 const CHDIR_DONE_RE = new RegExp(`^(\\d+)\\s+chdir\\(${QUOTED}\\)\\s*=\\s*0`)
 const CHDIR_UNFINISHED_RE = new RegExp(`^(\\d+)\\s+chdir\\(${QUOTED} <unfinished`)
-const CHDIR_RESUMED_RE = /^(\d+)\s+<\.\.\. chdir resumed>.*?=\s*(-?\d+)/
+const CHDIR_RESUMED_RE =
+  /^(\d+)\s+<\.\.\. chdir resumed>.*?=\s*(-?\d+)(?:\s+(ENOENT|EACCES|EPERM))?/
+// A denied `chdir` is a denied read of the directory: `cd src` into a
+// directory no grant holds failed with no line of the trace's own, and
+// `cd src || …` passed and cached.
+const CHDIR_DENIED_RE = new RegExp(
+  `^(\\d+)\\s+chdir\\(${QUOTED}\\)\\s*=\\s*-1\\s+(ENOENT|EACCES|EPERM)`,
+)
 const FCHDIR_RE = /^(\d+)\s+(?:fchdir\(\d+\)|<\.\.\. fchdir resumed>.*?)\s*=\s*0/
 const FORK = '(?:clone3?|v?fork)'
 const FORK_DONE_RE = new RegExp(`^(\\d+)\\s+${FORK}\\(.*\\)\\s*=\\s*(\\d+)$`)
@@ -150,6 +157,17 @@ export function deniedCalls(text: string, cwd?: string): DeniedCall[] {
     out.push(call)
   }
   for (const line of text.split('\n')) {
+    // Most lines are opens that succeeded: two substring tests skip them.
+    const opener =
+      line.includes('= -1') || line.includes('<unfinished') || line.includes('resumed>')
+    if (!opener) {
+      if (
+        cwd !== undefined &&
+        (line.includes('chdir(') || line.includes('fork(') || line.includes('clone'))
+      )
+        follow(line)
+      continue
+    }
     const done = STRACE_DONE_RE.exec(line)
     if (done?.[2] !== undefined && done[3] !== undefined && done[4] !== undefined) {
       denied(done[1]!, { syscall: done[2], rawPath: cStringPath(done[3]), errno: done[4] })
@@ -176,15 +194,32 @@ export function deniedCalls(text: string, cwd?: string): DeniedCall[] {
       }
       continue
     }
-    if (cwd === undefined) continue
+    // A refused or split `chdir` arrives here: its denial counts with or
+    // without the cwd tracking.
+    follow(line)
+  }
+  function follow(line: string): void {
     let m: RegExpExecArray | null
-    if ((m = CHDIR_DONE_RE.exec(line)) !== null) opsOf(m[1]!).push({ chdir: cStringPath(m[2]!) })
-    else if ((m = CHDIR_UNFINISHED_RE.exec(line)) !== null) chdirring.set(m[1]!, cStringPath(m[2]!))
-    else if ((m = CHDIR_RESUMED_RE.exec(line)) !== null) {
+    if ((m = CHDIR_DENIED_RE.exec(line)) !== null) {
+      denied(m[1]!, { syscall: 'chdir', rawPath: cStringPath(m[2]!), errno: m[3]! })
+      return
+    }
+    if ((m = CHDIR_UNFINISHED_RE.exec(line)) !== null) {
+      chdirring.set(m[1]!, cStringPath(m[2]!))
+      return
+    }
+    if ((m = CHDIR_RESUMED_RE.exec(line)) !== null) {
       const to = chdirring.get(m[1]!)
       chdirring.delete(m[1]!)
       if (to !== undefined && m[2] === '0') opsOf(m[1]!).push({ chdir: to })
-    } else if ((m = FCHDIR_RE.exec(line)) !== null) opsOf(m[1]!).push({ lost: true })
+      else if (to !== undefined && m[3] !== undefined) {
+        denied(m[1]!, { syscall: 'chdir', rawPath: to, errno: m[3] })
+      }
+      return
+    }
+    if (cwd === undefined) return
+    if ((m = CHDIR_DONE_RE.exec(line)) !== null) opsOf(m[1]!).push({ chdir: cStringPath(m[2]!) })
+    else if ((m = FCHDIR_RE.exec(line)) !== null) opsOf(m[1]!).push({ lost: true })
     else if ((m = FORK_DONE_RE.exec(line)) !== null) {
       forked(m[1]!, m[2]!, opsOf(m[1]!).length, line.includes('CLONE_FS'))
     } else if ((m = FORK_UNFINISHED_RE.exec(line)) !== null) {

package/src/graph/scheduler.ts

@@ -726,14 +726,22 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
               return
             }
             const message = err instanceof Error ? err.message : String(err)
+            // After the run's stop a rejection is the stop's doing (a probe
+            // it killed, C-65): aborted, as any task it kills, and unsaid.
+            const stopped = aborted()
             const outcome: TaskOutcome = withHold({
               node,
-              status: 'failed',
+              status: stopped ? 'aborted' : 'failed',
               exitCode: 1,
               durationMs: 0,
             })
             leave()
             untrack()
+            if (stopped) {
+              finishOne(id, outcome)
+              tick()
+              return
+            }
             // A UserError is a config/input failure (e.g. a failed
             // `cache.inputs.runtime` command), not a vx bug — report it
             // plainly, never as an "internal error".

package/src/orchestrator/execute-task.ts

@@ -33,6 +33,7 @@ import {
   type TaskExecutor,
   type TaskInputs,
   PersistentReadyError,
+  sandboxReads,
 } from '../exec/index.js'
 import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import { killGraceMs, maskedEmitter, printable, relPosix, secretMask, span } from '../util/index.js'
@@ -875,6 +876,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         cwd: node.projectDir,
         bins: taskBinDirs(node, args.workspaceRoot),
         signal: res.signal,
+        hidden: req.sandbox && ((f: string) => !sandboxReads(req.sandbox!, f)),
       })
       if (verdict !== undefined) log.taskStderr(node, `\n${verdict}\n`)
       // A committed file another task's clean removed, still gone: vx

package/src/orchestrator/options.ts

@@ -230,7 +230,8 @@ export interface RunOptions {
    * The raw command string for the `invocations` row (e.g.
    * `'vx run build test --all'`). When absent, run() falls back to
    * `process.argv.slice(1).join(' ')` so programmatic callers still
-   * record something useful.
+   * record something useful. Telemetry sinks get it with what follows
+   * `--` counted, not quoted, as they get the argv (C-67).
    */
   command?: string
   /**

package/src/orchestrator/prepare.ts

@@ -32,6 +32,7 @@ import {
   type LoadReads,
   loadWorkspace,
   FROZEN_WITHOUT_LOCK,
+  type Lockfile,
   readLockfile,
   resolveCacheDir,
   type ProjectEntry,
@@ -282,10 +283,24 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // so consuming the lock by default would silently serve stale
   // freezes. `vx lock --check` is the full re-evaluation audit.
   // See docs/design/config-lock-2026-06.md.
-  const lock = options.frozen === true ? await readLockfile(workspaceRoot) : null
-  if (options.frozen === true && lock === null) {
-    throw new UserError(FROZEN_WITHOUT_LOCK)
-  }
+  // Read once, and only when a config is to be read from it: the CLI's
+  // selection pass may have staged every config (`options.staged`), and
+  // its load refused a frozen run without a lock. A 1,000-project lock is
+  // 1.1 MB of JSON (I-27).
+  let lockRead: Promise<Lockfile> | undefined
+  const readLock = (): Promise<Lockfile> =>
+    (lockRead ??= readLockfile(workspaceRoot).then((read) => {
+      if (read === null) throw new UserError(FROZEN_WITHOUT_LOCK)
+      return read
+    }))
+  const staged = options.staged
+  const allStaged =
+    staged !== undefined &&
+    projectMetas.every(
+      (m) => typeof m.configPath !== 'string' || m.configPath === '' || staged.has(m.name),
+    )
+  if (options.frozen === true && !allStaged) await readLock()
+  const lock = options.frozen === true ? readLock : null
 
   const loadArgs = {
     workspaceRoot,
@@ -441,7 +456,14 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         workspaceRoot,
         gitPathspecs(workspaceRoot, projectDirs, usesWorkspaceInputs),
       ))
-    applyGitEnumeration(enumeration, workspaceRoot, projectDirs, gitFilesCache, usesWorkspaceInputs)
+    await applyGitEnumeration(
+      enumeration,
+      workspaceRoot,
+      projectDirs,
+      gitFilesCache,
+      usesWorkspaceInputs,
+      localCache,
+    )
     mark('git enumeration')
     const hashCache = createHashCache()
     const fingerprintWatch = new FingerprintWatch(workspaceRoot, fingerprints, fingerprintsAt)

package/src/orchestrator/projects.ts

@@ -116,8 +116,12 @@ interface LoadProjectsBase {
    * way, since the package graph cannot see the cross form.
    */
   seeds: 'all' | Iterable<string>
-  /** Read configs from the lock instead of evaluating them (`--frozen`). */
-  lock: Lockfile | null
+  /**
+   * Read configs from the lock instead of evaluating them (`--frozen`),
+   * asked only when a config is to be read: a run whose every config the
+   * CLI's selection pass staged never parses it again.
+   */
+  lock: (() => Promise<Lockfile>) | null
   evalCache: LoadProjectConfigOptions['evalCache']
   warn: (message: string) => void
   /**
@@ -223,7 +227,9 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
         typeof m.configPath === 'string' && args.staged?.get(m.name) === undefined,
     )
     const loaded = lock
-      ? await frozenProjectConfigs(lock, withFile, workspaceRoot, args.evalCache?.store)
+      ? withFile.length === 0
+        ? []
+        : await frozenProjectConfigs(await lock(), withFile, workspaceRoot, args.evalCache?.store)
       : await loadProjectConfigs(
           withFile.map((m) => m.configPath),
           args.evalCache !== undefined ? { evalCache: args.evalCache } : {},

package/src/orchestrator/run.ts

@@ -5,7 +5,12 @@
 import type { ProjectEntry } from '../workspace/index.js'
 import { loadWorkspace, unreachedHint, unreachedPackages } from '../workspace/index.js'
 import path from 'node:path'
-import { type CacheLayer, type CachePolicy, FULL_CACHE_POLICY } from '../cache/index.js'
+import {
+  type CacheLayer,
+  type CachePolicy,
+  FULL_CACHE_POLICY,
+  stopRuntimeProbes,
+} from '../cache/index.js'
 import { VERSION } from '../version.js'
 import {
   resetSandbox,
@@ -533,6 +538,7 @@ async function runOnBus(
   // ends after it is the stop's own kill, and was named a crash (item 1061).
   let endedBeforeStop: ReadonlySet<ReturnType<typeof Bun.spawn>> | undefined
   const onAbort = (): void => {
+    stopRuntimeProbes()
     endedBeforeStop = new Set([...persistentRegistry.values()].filter(hasEnded))
     aborting = terminateChildren(
       () => [...liveChildren, ...persistentRegistry.values()],
@@ -634,7 +640,9 @@ async function runOnBus(
       runContextRecord = {
         runId,
         vxVersion: VERSION,
-        command: options.command ?? invocationCommand(process.argv.slice(1)),
+        // An embedder's `command` is redacted as the argv is: it passed a
+        // token after `--` to every sink verbatim (C-67).
+        command: invocationCommand(options.command?.split(' ') ?? process.argv.slice(1)),
         requestedTasks: [...options.tasks],
         cachePolicy: compactCachePolicy(policy),
         concurrency,

package/src/orchestrator/sandbox-request.ts

@@ -187,13 +187,14 @@ export async function sandboxRequestFor(
    */
   cacheDir?: string,
 ): Promise<SandboxRequest> {
-  // SRT reads a Linux path holding a bracket as a glob and drops it from
-  // the writes, so no grant here could be mounted (B-60).
+  // The runtime reads a path holding a bracket as a pattern: on Linux it
+  // mounts no such write path (B-60); seatbelt's rules compile it as a
+  // character class, so vx's own workspace wall matched nothing (B-65).
   const home = toRealPath(node.projectDir)
-  if (process.platform === 'linux' && /[[\]]/.test(home)) {
+  if (process.platform !== 'win32' && /[[\]]/.test(home)) {
     throw new UserError(
-      `exec.sandbox: ${home} holds a bracket ([ or ]), and the Linux sandbox mounts no path ` +
-        `that does — rename the directory, or run the task without exec.sandbox`,
+      `exec.sandbox: ${home} holds a bracket ([ or ]), which the sandbox runtime reads as a ` +
+        `pattern, not a name — rename the directory, or run the task without exec.sandbox`,
     )
   }
   const depDirs = [

package/src/orchestrator/shell-verdict.ts

@@ -23,13 +23,22 @@ export function shellVerdict(args: {
   bins: string[]
   /** The signal that killed the child when the runner saw one (`RunResult.signal`). */
   signal?: string | undefined
+  /** A sandboxed task's view: whether a file is hidden from it (no grant reads it). */
+  hidden?: ((file: string) => boolean) | undefined
 }): string | undefined {
   if (args.code !== 127 && args.code !== 126) return signalVerdict(args.code, args.signal)
   const word = execWord(args.command)
   const what = word ?? 'a command in this task'
   if (word !== undefined && word.includes('/')) {
     const file = path.resolve(args.cwd, word)
-    return `[vx] exit ${args.code} is the shell's "${args.code === 127 ? 'not found' : 'cannot execute'}": ${word} ${fileVerdict(file)}`
+    // The file the host has may be one the sandbox does not: then the
+    // shell's "not found" is the sandbox's, and the file's own state (its
+    // `#!` line) is not the reason.
+    const verdict =
+      existsSync(file) && args.hidden?.(file) === true
+        ? `exists, but no sandbox grant reads it, so inside the sandbox it is not there — add it (or its directory) to exec.sandbox.allow.read`
+        : fileVerdict(file)
+    return `[vx] exit ${args.code} is the shell's "${args.code === 127 ? 'not found' : 'cannot execute'}": ${word} ${verdict}`
   }
   if (args.code === 126) {
     return `[vx] exit 126 is the shell's "found but cannot execute": ${what} is not executable or is a directory — chmod +x it`

package/src/workspace/config-schema.ts

@@ -765,6 +765,24 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       implicitDependencies: 'a `dependsOn` entry `pkg#task`, or a package.json dependency',
       name: 'the package.json `name` (a project is named by its package)',
       tags: '`--filter` (a name glob or a directory) to select projects',
+      // A package.json's, turbo.json's and project.json's keys, and a
+      // task's fields one level too high (D-99).
+      scripts:
+        "`tasks` (a script is a task's `exec.command`; `vx init` writes them from package.json)",
+      pipeline: '`tasks` (`bunx @vzn/vx-migrate` writes them from turbo.json)',
+      namedInputs: 'a module the vx.config imports, spread into `cache.inputs.files`',
+      root: "no field: a project's directory is where its package.json sits",
+      sourceRoot: "a task's `cache.inputs.files`",
+      projectType: 'no field: vx runs every project alike',
+      ...Object.fromEntries(
+        ['dependsOn', 'cache', 'exec', 'description'].map((k) => [
+          k,
+          `\`tasks.<name>.${k}\`: a project holds tasks, and each task its own \`${k}\``,
+        ]),
+      ),
+      inputs: '`tasks.<name>.cache.inputs.files`',
+      outputs: '`tasks.<name>.cache.outputs.files`',
+      env: '`tasks.<name>.cache.inputs.env` (to key a task on it) or `tasks.<name>.exec.env`',
     },
   ],
   // Turbo's turbo.json and Nx's nx.json keys, written into vx.workspace

package/src/workspace/migrate-scripts.ts

@@ -55,12 +55,14 @@ const LIFECYCLE = /^(pre|post)(install|publish|pack|version)$|^(prepare|prepubli
  */
 export function delegatedScript(command: string): string | null {
   const m =
-    /^(?:(?:npm run|(pnpm|yarn|bun)(?: (run))?) ([^\s&|;<>()$`'"\\]+)|npm (test|start))$/.exec(
+    /^(?:(?:npm run|(pnpm|pn|yarn|bun)(?: (run))?) ([^\s&|;<>()$`'"\\]+)|npm (test|start))$/.exec(
       command.trim(),
     )
   if (m === null) return null
   if (m[4] !== undefined) return m[4]
-  const [, manager, run, name] = m
+  const [, alias, run, name] = m
+  // `pn` is pnpm's own short name (pnpm 11; pnpm/pnpm's scripts run it).
+  const manager = alias === 'pn' ? 'pnpm' : alias
   // Bare, the manager's own command wins over a script of that name:
   // `bun test` is Bun's test runner and `bun build` its bundler, never the
   // `test` / `build` script, and a group over the script ran the wrong
@@ -305,7 +307,7 @@ const MEMBER_FLAG =
 function pmRunsMembers(script: string): boolean {
   for (const segment of script.split(/&&|\|\||[;|()]/)) {
     const words = segment.trim().split(/\s+/)
-    let i = words.findIndex((w) => /^(pnpm|npm|yarn|bun)$/.test(w))
+    let i = words.findIndex((w) => /^(pnpm|pn|npm|yarn|bun)$/.test(w))
     // npm/cli runs itself: `node . run test --workspaces`.
     if (i < 0) i = words.findIndex((w, j) => w === 'run' && words[j - 2] === 'node')
     if (i < 0) continue
@@ -343,7 +345,7 @@ function cdsToMembers(script: string, rootDir: string, memberDirs: readonly stri
 
 /** A package manager running a script by name: `pnpm build`, `npm run x`, `bun run x`. */
 const RUNS_SCRIPT =
-  /(?:^|[\s;&|(])(?:pnpm|npm|yarn|bun)\s+(?:run(?:-script)?\s+)?([^\s;&|()'"-][^\s;&|()'"]*)/g
+  /(?:^|[\s;&|(])(?:pnpm|pn|npm|yarn|bun)\s+(?:run(?:-script)?\s+)?([^\s;&|()'"-][^\s;&|()'"]*)/g
 
 /**
  * The scripts a command runs by name: a package manager's (`pnpm x`, `npm

package/src/workspace/migration.ts

@@ -8,7 +8,7 @@
 import { existsSync } from 'node:fs'
 import { unlink } from 'node:fs/promises'
 import path from 'node:path'
-import { relPosix, UserError } from '../util/index.js'
+import { executablePath, relPosix, UserError } from '../util/index.js'
 import type { ProjectMeta } from './workspace.js'
 import { loadWorkspace, unreachedHint, unreachedPackages } from './workspace.js'
 import { WORKSPACE_CONFIG_FILENAMES } from './project-loader.js'
@@ -412,14 +412,36 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     report.push('', 'no task caches yet: add the cache block a TODO shows, and a second run hits')
   }
   const installed = existsSync(path.join(root, 'node_modules', '@vzn', 'vx', 'package.json'))
-  report.push(
-    '',
-    `next: ${vxInvocation(process.env['npm_config_user_agent'], installed)} run ${firstTask} --all`,
-  )
+  // The line is the next thing to type, so it names what that run would
+  // refuse without: a git work tree (vx keys inputs on git's view) and,
+  // with no scripts mapped, a task to run.
+  const run = `${vxInvocation(process.env['npm_config_user_agent'], installed)} run ${firstTask} --all`
+  const steps = [
+    ...(inGitWorkTree(root) ? [] : ['git init']),
+    ...(empty ? [`declare a task as the example shows`] : []),
+  ]
+  report.push('', `next: ${steps.length === 0 ? run : `${steps.join(', ')}, then ${run}`}`)
   process.stdout.write(`${report.join('\n')}\n`)
   return 0
 }
 
+function inGitWorkTree(root: string): boolean {
+  try {
+    return (
+      Bun.spawnSync({
+        cmd: [executablePath('git'), 'rev-parse', '--is-inside-work-tree'],
+        cwd: root,
+        stdout: 'pipe',
+        stderr: 'ignore',
+      })
+        .stdout.toString()
+        .trim() === 'true'
+    )
+  } catch {
+    return false
+  }
+}
+
 /**
  * How the user runs vx, for the report's `next:` line. After `npx vx init`
  * or `bunx @vzn/vx init` a bare `vx` is on no PATH (the first-five-minutes