@vzn/vx 0.0.49 → 0.0.51

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, realpathSync } from 'node:fs'
+import { existsSync, lstatSync, 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`. */
@@ -257,6 +257,8 @@ interface GitLsResult {
   oids: Map<string, string>
   /** Paths flagged skip-worktree / assume-unchanged (only when `-v` was passed). */
   flagged: Set<string>
+  /** Gitlinks (mode 160000): a submodule or an embedded repository, one entry for its whole tree. */
+  gitlinks: Set<string>
   /** cwd-relative paths whose names are not UTF-8, spelled lossily (`decodeGitZ`). */
   undecodable: string[]
 }
@@ -334,7 +336,46 @@ export function runGitLsFiles(cwd: string): GitLsResult {
     )
   }
   const { text, undecodable } = decodeGitZ(proc.stdout)
-  return parseLsFilesOutput(text, undecodable)
+  const parsed = parseLsFilesOutput(text, undecodable)
+  const nested = expandNestedRepos(cwd, parsed.files, parsed.gitlinks)
+  parsed.files = nested.files
+  parsed.undecodable.push(...nested.undecodable)
+  return parsed
+}
+
+/**
+ * Replace each nested repository in a listing — a gitlink (a submodule) or
+ * an untracked `dir/` (an embedded repository) — with the files its OWN git
+ * lists, prefixed by its path. The outer repository holds one entry for the
+ * whole tree and none of its files, and a directory is no input, so a task
+ * reading `vendor/lib/x.txt` under `**` folded nothing of it: an edit there
+ * was a green hit on the old output while `git status` named the path. The
+ * files carry no index OID from here, so they hash by content. A nested
+ * repository with no `.git` (a submodule never initialised) has no files to
+ * read and stays out. A listing with none is returned as it came.
+ */
+function expandNestedRepos(
+  cwd: string,
+  files: string[],
+  gitlinks: ReadonlySet<string>,
+): { files: string[]; undecodable: string[] } {
+  let out: string[] | undefined
+  const undecodable: string[] = []
+  for (let i = 0; i < files.length; i++) {
+    const rel = files[i]!
+    const nested = rel.endsWith('/') ? rel.slice(0, -1) : gitlinks.has(rel) ? rel : undefined
+    if (nested === undefined) {
+      out?.push(rel)
+      continue
+    }
+    out ??= files.slice(0, i)
+    const abs = path.join(cwd, nested)
+    if (!existsSync(path.join(abs, '.git'))) 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}`)
+  }
+  return { files: out ?? files, undecodable }
 }
 
 /**
@@ -359,8 +400,9 @@ function parseLsFilesOutput(out: string, undecodableRecords: ReadonlySet<string>
   const files: string[] = []
   const oids = new Map<string, string>()
   const flagged = new Set<string>()
+  const gitlinks = new Set<string>()
   const undecodable: string[] = []
-  if (out.length === 0) return { files, oids, flagged, undecodable }
+  if (out.length === 0) return { files, oids, flagged, gitlinks, undecodable }
   // NUL-separated; trailing NUL produces an empty segment we skip.
   for (const record of out.split('\0')) {
     if (record.length === 0) continue
@@ -373,6 +415,8 @@ function parseLsFilesOutput(out: string, undecodableRecords: ReadonlySet<string>
     const stage = m[4]!
     if ((mode === '100644' || mode === '100755' || mode === '120000') && stage === '0') {
       oids.set(filePath, fileIdentity(mode, m[3]!))
+    } else if (mode === '160000') {
+      gitlinks.add(filePath)
     }
     // A LOWERCASE letter means skip-worktree or assume-unchanged (`S` is the
     // older spelling of skip-worktree): git has been told to stop looking at
@@ -380,7 +424,7 @@ function parseLsFilesOutput(out: string, undecodableRecords: ReadonlySet<string>
     const flag = m[1]
     if (flag !== undefined && (flag === 'S' || (flag >= 'a' && flag <= 'z'))) flagged.add(filePath)
   }
-  return { files, oids, flagged, undecodable }
+  return { files, oids, flagged, gitlinks, undecodable }
 }
 
 /** One completed `git` invocation. */
@@ -557,6 +601,40 @@ function gitVarList(listing: string): Map<string, string> {
   return vars
 }
 
+/**
+ * `true` when git ignores the executable bit (`core.fileMode=false`, the
+ * default on WSL's DrvFs and what `git init` writes on a filesystem without
+ * one). Then `git status` reports no `chmod`, and a trusted file's index mode
+ * says nothing about the worktree.
+ */
+function fileModeIgnored(gitVars: string): boolean {
+  const v = gitVarList(gitVars).get('core.filemode')?.trim().toLowerCase()
+  return v === 'false' || v === 'no' || v === 'off' || v === '0'
+}
+
+/**
+ * Under `core.fileMode=false`, each trusted identity's mode from an lstat of
+ * the worktree file, as `hashFile` takes it; the OID stays the index's. The
+ * index mode alone kept the key through a `chmod +x`, and the task replayed
+ * the output a 644 input built (item 1076). A path that does not stat goes
+ * back to the probe.
+ */
+function restampModes(trusted: Map<string, string>, workspaceRoot: string): void {
+  for (const [rel, id] of trusted) {
+    const colon = id.indexOf(':')
+    const oid = colon === -1 ? id : id.slice(colon + 1)
+    let st
+    try {
+      st = lstatSync(path.join(workspaceRoot, rel))
+    } catch {
+      trusted.delete(rel)
+      continue
+    }
+    const mode = st.isSymbolicLink() ? '120000' : (st.mode & 0o100) !== 0 ? '100755' : '100644'
+    trusted.set(rel, fileIdentity(mode, oid))
+  }
+}
+
 /** `true` when git may rewrite bytes for EVERY auto-detected text file. */
 export function autocrlfConverts(gitVars: string): boolean {
   const v = gitVarList(gitVars).get('core.autocrlf')?.trim().toLowerCase()
@@ -825,6 +903,7 @@ export async function startGitEnumeration(
     files: tracked,
     oids,
     flagged,
+    gitlinks,
     undecodable,
   } = parseLsFilesOutput(ls.stdout, ls.undecodable)
   // Normalize `status`'s repo-root-relative paths to workspace-relative (strip
@@ -846,7 +925,10 @@ export async function startGitEnumeration(
   // set. Without a status answer the enumeration is the index alone.
   const untracked =
     parsedStatus === null ? [] : [...stripPrefixFromSet(new Set(parsedStatus.untracked), gitPrefix)]
-  const all = untracked.length === 0 ? tracked : tracked.concat(untracked)
+  const listed = untracked.length === 0 ? tracked : tracked.concat(untracked)
+  const nested = expandNestedRepos(workspaceRoot, listed, gitlinks)
+  const all = nested.files
+  undecodable.push(...nested.undecodable)
   // Aggregate dirtiness for the Tier-3 invocation record — derived from
   // this same status spawn so `run()` needs no second `git status`.
   // null when the status spawn failed (non-repo / git error).
@@ -883,6 +965,9 @@ export async function startGitEnumeration(
     gitVars: vars !== null && vars.exitCode === 0 ? vars.stdout : '',
     spawnGit,
   })
+  if (vars !== null && vars.exitCode === 0 && fileModeIgnored(vars.stdout)) {
+    restampModes(trusted, workspaceRoot)
+  }
   if (parsedStatus !== null && parsedStatus.undecodable.size > 0) {
     undecodable.push(...stripPrefixFromSet(parsedStatus.undecodable, gitPrefix))
   }
@@ -939,12 +1024,12 @@ export function applyGitEnumeration(
       if (oid !== undefined) projOids.set(path.join(workspaceRoot, rel), oid)
     }
     // An empty slice is a directory git did not see, not an empty project:
-    // a project has at least its package.json, tracked or untracked. What
-    // hides a directory from this listing is a nested repository — a
-    // submodule, an embedded repository — which the workspace's git holds as
-    // ONE entry (a gitlink, `dir/` when untracked) and, under a pathspec
-    // naming the project, as nothing at all; or a directory ignored
-    // outright. Storing the empty slice made the key never move: `cache.inputs
+    // a project has at least its package.json, tracked or untracked. A
+    // nested repository — a submodule, an embedded repository, which the
+    // workspace's git holds as ONE entry (a gitlink, `dir/` when untracked)
+    // — is listed through its own git above (`expandNestedRepos`), but under
+    // a pathspec naming a project inside it the workspace's git lists
+    // nothing at all; so is a directory ignored outright. Storing the empty slice made the key never move: `cache.inputs
     // matched no files`, then a stale hit under a green run once the source
     // changed (2026-09-16). No partition instead: `resolveFiles` spawns
     // `git ls-files` in the project's own directory, which a nested

package/src/cache/index.ts

@@ -23,6 +23,7 @@ export {
   OUTPUT_DIRS_CAP,
   FILE_HASH_RACY_MS,
   OUTPUT_DIRS_RACY_MS,
+  racyWindowMs,
   noteSchemaReset,
   type SchemaReset,
   SCHEMA_VERSION,

package/src/cache/layer.ts

@@ -377,6 +377,23 @@ export const OUTPUT_DIRS_RACY_MS = 50
 /** The stat memo's twin of `OUTPUT_DIRS_RACY_MS`: a file changed within this window of the stat is not memoised. */
 export const FILE_HASH_RACY_MS = 50
 
+/**
+ * The racy window for one timestamp. `windowMs` assumes a clock finer than
+ * itself; a file system that keeps whole seconds (ext3, HFS+, FAT/exFAT,
+ * some NFS mounts) stamps a write at 12:00:00.900 as 12:00:00, so a write
+ * later in that second keeps the stamp, and a stat 120 ms after the first
+ * write passed a 50 ms window: the memo served the first bytes' digest for
+ * a same-size rewrite 120 ms on (A-2, reproduced on an ext2 mount). A stamp
+ * with no sub-second part is read as such a second and widens the window by
+ * it, as git judges racy entries at its index's own granularity. Pass the
+ * UNFLOORED stamp: a kernel's nanosecond stamp lands on a whole second about
+ * once in 10^9, one set through a millisecond `utimes` once in a thousand,
+ * and either is then trusted a second later — never wrongly.
+ */
+export function racyWindowMs(stampMs: number, windowMs: number): number {
+  return stampMs % 1000 === 0 ? windowMs + 1000 : windowMs
+}
+
 /**
  * Context passed to `get()`. Optional, but required when the lookup
  * may resolve through the remote layer — the local SQL row inserted on
@@ -568,9 +585,17 @@ export interface CacheLayer {
    * `loadOutputDirsBatch` reads them back; `outputDirsCurrent` is true iff
    * every recorded directory still carries its recorded mtime, which proves
    * no file was added or removed anywhere the glob could see. Machine-local
-   * state, like the output rows: a remote ingest records none.
-   */
-  recordOutputDirs?(hash: string, projectDir: string, prefixes: readonly string[]): Promise<void>
+   * state, like the output rows: a remote ingest records none. `holds`,
+   * when given, is asked with every non-directory path the walk saw
+   * (project-relative); false records nothing, since a snapshot of a tree
+   * the entry does not hold would vouch for it on every later hit.
+   */
+  recordOutputDirs?(
+    hash: string,
+    projectDir: string,
+    prefixes: readonly string[],
+    holds?: (files: readonly string[]) => boolean,
+  ): Promise<void>
   /**
    * Stamp `hash`'s output rows with each file's inode and ctime once a
    * save or restore has left the tree equal to the entry (optional — a

package/src/cache/layered-cache.ts

@@ -531,8 +531,13 @@ export class LayeredCache implements CacheLayer {
     return this.local.isOutputsCurrent(projectDir, expected)
   }
 
-  recordOutputDirs(hash: string, projectDir: string, prefixes: readonly string[]): Promise<void> {
-    return this.local.recordOutputDirs(hash, projectDir, prefixes)
+  recordOutputDirs(
+    hash: string,
+    projectDir: string,
+    prefixes: readonly string[],
+    holds?: (files: readonly string[]) => boolean,
+  ): Promise<void> {
+    return this.local.recordOutputDirs(hash, projectDir, prefixes, holds)
   }
   recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void {
     this.local.recordOutputStamps(hash, projectDir, workspaceRoot)

package/src/cache/output-index.ts

@@ -16,6 +16,7 @@ import {
   OUTPUT_DIRS_CAP,
   OUTPUT_DIRS_RACY_MS,
   type OutputDirRow,
+  racyWindowMs,
   type OutputFileRow,
   WORKSPACE_OUTPUT_PREFIX,
 } from './layer.js'
@@ -164,18 +165,23 @@ export class OutputIndex {
   }
 
   /**
-   * Snapshot every directory under each of `prefixes` for `hash`. Called
-   * after a save and after a restore, when the tree is known to equal the
-   * entry's set. Symlinked directories are not descended (the output walk
-   * refuses them too). Over `OUTPUT_DIRS_CAP` directories, or on any
-   * error, the rows are cleared and the next hit keeps the walk.
+   * Snapshot every directory under each of `prefixes` for `hash`, for a
+   * tree that equals the entry's set. The run takes it at run end, when
+   * the directories are past the racy window, and by then another task or
+   * process may have written into them: `holds` is asked with the files
+   * the walk saw, and a tree it refuses records nothing (item 1087).
+   * Symlinked directories are not descended (the output walk refuses them
+   * too). Over `OUTPUT_DIRS_CAP` directories, or on any error, the rows
+   * are cleared and the next hit keeps the walk.
    */
   async recordOutputDirs(
     hash: string,
     projectDir: string,
     prefixes: readonly string[],
+    holds?: (files: readonly string[]) => boolean,
   ): Promise<void> {
     const rows: Array<[string, number]> = []
+    const files: string[] = []
     const walk = async (rel: string, isPrefix = false): Promise<boolean> => {
       const abs = path.join(projectDir, rel)
       let st
@@ -205,6 +211,8 @@ export class OutputIndex {
       for (const e of entries) {
         if (e.isDirectory() && !e.isSymbolicLink()) {
           if (!(await walk(`${rel}/${e.name}`))) return false
+        } else {
+          files.push(`${rel}/${e.name}`)
         }
       }
       return true
@@ -218,8 +226,9 @@ export class OutputIndex {
     }
     // All or nothing: a racy directory dropped alone would leave its
     // parent trusted while an addition inside it bumps only the dropped one.
-    const youngest = Date.now() - OUTPUT_DIRS_RACY_MS
-    if (rows.some(([, mtime]) => mtime > youngest)) ok = false
+    const now = Date.now()
+    if (rows.some(([, mtime]) => mtime > now - racyWindowMs(mtime, OUTPUT_DIRS_RACY_MS))) ok = false
+    if (ok && holds !== undefined && !holds(files)) ok = false
     this.pendingDirs.set(hash, ok ? rows : null)
   }
 

package/src/cache/run-history.ts

@@ -4,6 +4,7 @@
 // its statements over the store's handle; `Cache` delegates.
 
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
+import { xxh3hex } from '../util/index.js'
 import type { InvocationRecord, RunRecord } from './layer.js'
 
 export class RunHistory {
@@ -98,7 +99,10 @@ function bindRun(run: RunRecord): SQLQueryBindings[] {
     run.status,
     run.exitCode,
     run.durationMs,
-    run.forwardArgs ? JSON.stringify(run.forwardArgs) : null,
+    // A digest, as entry_inputs keeps: args after `--` carry tokens
+    // (`--token=…`), and cache.db holds no plaintext secret at rest; nothing
+    // reads the column but for whether the args changed (item 1091).
+    run.forwardArgs ? xxh3hex(JSON.stringify(run.forwardArgs)) : null,
     run.startedAt,
     run.endedAt,
     run.runId ?? null,

package/src/cache/zstd.ts

@@ -47,6 +47,36 @@ export function zstdContentSize(b: Uint8Array): bigint | null {
   return v
 }
 
+/**
+ * Whether `b` is exactly ONE zstd frame: its header, its blocks by their
+ * own sizes (RFC 8878 §3.1.1.2), the checksum when the header asks for one,
+ * and not a byte after. `zstdContentSize` reads the first frame alone, and
+ * `Bun.zstdDecompress` decodes every frame there is: a 100-byte frame with a
+ * second one appended passed a 64 MiB ceiling and expanded to 2 GiB of
+ * memory from a 32 KB remote body before the result's length was checked
+ * (A-5). Anything but one whole frame decodes as a stream, under the running
+ * count. A few header reads per block, on bytes already in memory.
+ */
+function isOneFrame(b: Uint8Array): boolean {
+  if (b.length < 6) return false
+  const desc = b[4]!
+  const fcsFlag = desc >> 6
+  const singleSegment = (desc >> 5) & 1
+  const checksum = (desc >> 2) & 1
+  const dictIdFlag = desc & 3
+  let off = 5 + (singleSegment === 0 ? 1 : 0) + (dictIdFlag === 3 ? 4 : dictIdFlag)
+  off += fcsFlag === 0 ? singleSegment : 1 << fcsFlag
+  for (;;) {
+    if (off + 3 > b.length) return false
+    const h = b[off]! | (b[off + 1]! << 8) | (b[off + 2]! << 16)
+    const type = (h >> 1) & 3
+    if (type === 3) return false
+    off += 3 + (type === 1 ? 1 : h >>> 3)
+    if ((h & 1) === 1) break
+  }
+  return off + (checksum === 1 ? 4 : 0) === b.length
+}
+
 /**
  * Decompress a zstd artifact that DECLARES its content size, with a hard
  * output ceiling: refused before a byte is allocated when the declaration
@@ -65,13 +95,13 @@ async function zstdDecompressBounded(
   assertDeclaredSize(compressed, hash, cap)
   const out = await Bun.zstdDecompress(compressed)
   // UNREACHABLE as written, and kept deliberately. `assertDeclaredSize`
-  // above refuses any frame DECLARING more than the cap, and Bun refuses a
+  // above refuses any frame DECLARING more than the cap, Bun refuses a
   // frame whose declaration disagrees with its body ("Decompression
-  // failed" on a forged Frame_Content_Size, measured item 487) — so a frame
-  // that gets here declared <= cap and produced exactly that. The only way
-  // this fires again is a decoder that stops validating the declaration.
-  // That is what it is for; it is not a second live layer, and no test can
-  // reach it.
+  // failed" on a forged Frame_Content_Size, measured item 487), and only
+  // ONE whole frame comes here (`isOneFrame`) — so what gets here declared
+  // <= cap and produced exactly that. Before A-5 a second frame appended
+  // after the first reached it, past the whole expansion. The only way it
+  // fires again is a decoder that stops validating the declaration.
   if (out.length > cap) {
     throw new CorruptArtifactError(hash, `decompressed to ${out.length} bytes (> ${cap} cap)`)
   }
@@ -139,14 +169,16 @@ export async function decodedTar(
   cap: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
 ): Promise<ReadableStream<Uint8Array>> {
   if (source instanceof Uint8Array) {
-    if (assertDeclaredSize(source, hash, cap) === null) {
+    if (assertDeclaredSize(source, hash, cap) === null || !isOneFrame(source)) {
       return zstdDecodeStream(new Blob([source]), hash, cap)
     }
     return oneChunk(await zstdDecompressBounded(source, hash, cap))
   }
   if (source.size <= STREAM_DECODE_FROM) {
     const bytes = await source.bytes()
-    if (assertDeclaredSize(bytes, hash, cap) === null) return zstdDecodeStream(source, hash, cap)
+    if (assertDeclaredSize(bytes, hash, cap) === null || !isOneFrame(bytes)) {
+      return zstdDecodeStream(source, hash, cap)
+    }
     return oneChunk(await zstdDecompressBounded(bytes, hash, cap))
   }
   assertDeclaredSize(await source.slice(0, 32).bytes(), hash, cap)

package/src/cli/cache.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs'
 import { Cache, noteSchemaReset } from '../cache/index.js'
 import { seeHelp } from './help.js'
 import { nearest, parseDuration, parseSize } from '../util/index.js'
@@ -143,6 +144,26 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
   // wrong path.
   // A dry run only reads: it never resets the index (item 896).
   const dir = await cliCacheDir(root, parsed.cacheDir)
+  // A workspace that never ran has nothing to prune, and opening the cache
+  // to find that out made it: `.vx/cache` with a database and a
+  // `.gitignore`, where item 900 had held the dry run to making nothing
+  // (and a read-only checkout was refused as unwritable instead).
+  if (!existsSync(dir)) {
+    process.stdout.write(
+      parsed.dryRun === true ? 'Would prune 0 entries (0 B)\n' : 'Pruned 0 entries (0 B freed)\n',
+    )
+    return 0
+  }
+  if (parsed.dryRun === true) {
+    const earlier = await Cache.orphansBeforeReset(dir)
+    if (earlier !== null) {
+      warnToStderr(
+        `[vx] the cache index is schema ${earlier.found} from an earlier vx: the prune resets it first, and every artifact past the hour's grace is then an orphan`,
+      )
+      printPruned({ evicted: 0, bytesFreed: 0, ...earlier }, true)
+      return 0
+    }
+  }
   const cache = parsed.dryRun === true ? Cache.inspect(dir) : new Cache(dir)
   // A prune deletes rows and artifacts; a cache this user cannot write is
   // refused up front with the directory named, as a run refuses it, rather
@@ -163,18 +184,23 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
     if (parsed.olderThanMs !== undefined) opts.olderThanMs = parsed.olderThanMs
     if (parsed.maxBytes !== undefined) opts.maxBytes = parsed.maxBytes
     if (parsed.dryRun) opts.dryRun = true
-    const result = await cache.prune(opts)
-    const dry = parsed.dryRun === true
-    const orphans =
-      result.orphans > 0
-        ? `, ${dry ? 'would reap' : 'reaped'} ${result.orphans} orphaned artifact${result.orphans === 1 ? '' : 's'} (${formatBytes(result.orphanBytes)})`
-        : ''
-    process.stdout.write(
-      `${dry ? 'Would prune' : 'Pruned'} ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)}${dry ? '' : ' freed'})${orphans}\n`,
-    )
+    printPruned(await cache.prune(opts), parsed.dryRun === true)
   } finally {
     cache.close()
     await releaseRunLock()
   }
   return 0
 }
+
+function printPruned(
+  result: { evicted: number; bytesFreed: number; orphans: number; orphanBytes: number },
+  dry: boolean,
+): void {
+  const orphans =
+    result.orphans > 0
+      ? `, ${dry ? 'would reap' : 'reaped'} ${result.orphans} orphaned artifact${result.orphans === 1 ? '' : 's'} (${formatBytes(result.orphanBytes)})`
+      : ''
+  process.stdout.write(
+    `${dry ? 'Would prune' : 'Pruned'} ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)}${dry ? '' : ' freed'})${orphans}\n`,
+  )
+}

package/src/cli/completions.ts

@@ -1,20 +1,23 @@
 // `vx completions <shell>` — a bash / zsh / fish script over the verb table
-// and each verb's help cut, so the verbs and every flag of each complete
-// from the one text `vx <verb> --help` prints. Plugin verbs of the
+// and each verb's Usage line in the help text, so the verbs and every flag
+// of each complete from the one text `vx <verb> --help` prints. Plugin verbs of the
 // workspace around the cwd are included at generation time; task and
 // project names are not (a completion that evaluates configs on every
 // Tab is the wrong price).
 
-import { CORE_VERBS, seeHelp, verbHelpText } from './help.js'
+import { acceptedFlags, CORE_VERBS, seeHelp } from './help.js'
 
 export type CompletionShell = 'bash' | 'zsh' | 'fish'
 const SHELLS: readonly CompletionShell[] = ['bash', 'zsh', 'fish']
 
-/** Every `--flag` the verb's help cut names, plus `--help`; deduped, in order of appearance. */
+/**
+ * `--help` and every flag the verb accepts. Not every `--flag` its help cut
+ * mentions: the cut's prose names other verbs' flags, and `vx watch`
+ * completed only `--dry --graph --summarize --profile`, the four its line
+ * says it refuses, while `vx show` offered `--run` and `--list`.
+ */
 export function verbFlags(verb: string): string[] {
-  const flags = new Set<string>(['--help'])
-  for (const f of verbHelpText(verb).match(/--[a-zA-Z][a-zA-Z-]*/g) ?? []) flags.add(f)
-  return [...flags]
+  return [...new Set(['--help', ...acceptedFlags(verb)])]
 }
 
 /** The words that follow `vx <verb>` besides flags: subcommands and fixed choices. */

package/src/cli/help.ts

@@ -113,9 +113,11 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Watch mode:',
     '  vx watch <task>            Initial run, then re-run on filesystem changes.',
     '                             Uses the same flags as `vx run` except --dry /',
-    '                             --graph / --summarize / --profile. Press Ctrl+C',
-    '                             to stop. Cache means most re-runs are near-zero',
-    '                             cost (cache hits restore outputs + replay logs).',
+    '                             --graph / --summarize / --profile / --report /',
+    '                             --report-file / --verbosity (they plan or report',
+    '                             one run). Press Ctrl+C to stop. Cache means most',
+    '                             re-runs are near-zero cost (cache hits restore',
+    '                             outputs + replay logs).',
     '',
     'Cache management:',
     '  vx cache prune --older-than 30d     Evict entries last accessed > 30 days ago.',
@@ -189,7 +191,10 @@ export function seeHelp(verb: string): string {
 /**
  * The documented `--flags` of one verb, read from the help text's
  * sections headed `… (for <verb>):` so there is no second list to drift —
- * and no hint that names another verb's flag.
+ * and no hint that names another verb's flag. Only the flag an option line
+ * OPENS with is one: `--frozen`'s line says "pair with vx lock --check", and
+ * reading every flag on it put `--check` in the list, so `vx run --chek`
+ * was told "did you mean --check?" and `--check` was then refused.
  */
 export function documentedFlags(verb: string): string[] {
   const flags = new Set<string>()
@@ -198,7 +203,46 @@ export function documentedFlags(verb: string): string[] {
     if (/^[A-Z][A-Za-z ]*(?: \(for [a-z]+\))?:$/.test(line))
       inVerb = line.endsWith(`(for ${verb}):`)
     if (!inVerb) continue
+    const own = /^\s+(--[a-zA-Z][a-zA-Z-]*)/.exec(line)
+    if (own !== null) flags.add(own[1]!)
+  }
+  return [...flags]
+}
+
+/**
+ * The `vx run` flags `vx watch` refuses: each plans or reports ONE run
+ * (`watchRefusal` in watch.ts, held to this list by a test).
+ */
+export const WATCH_REFUSED_FLAGS: readonly string[] = [
+  '--dry',
+  '--graph',
+  '--summarize',
+  '--profile',
+  '--report',
+  '--report-file',
+  '--verbosity',
+]
+
+/**
+ * The flags one verb accepts: those on its own Usage line, and for a verb
+ * that takes `[OPTIONS]` (run, watch) the documented run flags — less the
+ * ones watch refuses. The Usage line is the verb's synopsis; a section's
+ * prose names other verbs' flags (`vx lock --check`, `--run <id>` under
+ * `vx why`) and is not read.
+ */
+export function acceptedFlags(verb: string): string[] {
+  const quoted = verb.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const usage = helpText()
+    .split('\n')
+    .filter((line) => new RegExp(`^  vx ${quoted}( |$)`).test(line))
+  const flags = new Set<string>()
+  for (const line of usage) {
     for (const f of line.match(/--[a-zA-Z][a-zA-Z-]*/g) ?? []) flags.add(f)
+    if (line.includes('[OPTIONS]')) {
+      for (const f of documentedFlags('run')) {
+        if (verb !== 'watch' || !WATCH_REFUSED_FLAGS.includes(f)) flags.add(f)
+      }
+    }
   }
   return [...flags]
 }

package/src/cli/index.ts

@@ -79,10 +79,12 @@ export async function run(argv: readonly string[]): Promise<number> {
         const code = await resolved.command.run(rest, resolved.ctx)
         // A plugin is a boundary: a JS-authored verb that resolves nothing
         // would reach `process.exit(undefined)` and read as SUCCESS. A verb
-        // that cannot say whether it succeeded fails, naming its owner.
-        if (!Number.isInteger(code)) {
+        // that cannot say whether it succeeded fails, naming its owner. So
+        // does one past a byte: the OS keeps the low eight bits, and a verb
+        // that returned 256 (a count of failures, say) exited 0.
+        if (!Number.isInteger(code) || code < 0 || code > 255) {
           throw new UserError(
-            `plugin '${resolved.plugin.name}': command '${command}' resolved ${JSON.stringify(code)} instead of an exit code`,
+            `plugin '${resolved.plugin.name}': command '${command}' resolved ${JSON.stringify(code)} instead of an exit code (an integer 0–255)`,
           )
         }
         return code

package/src/cli/info.ts

@@ -17,7 +17,7 @@ export interface InfoArgs {
   error?: string
 }
 
-function parseInfoArgs(args: readonly string[]): InfoArgs {
+export function parseInfoArgs(args: readonly string[]): InfoArgs {
   const out: InfoArgs = { format: 'pretty' }
   for (let i = 0; i < args.length; i++) {
     const a = args[i]

package/src/cli/plugin-commands.ts

@@ -10,6 +10,7 @@
 import type { VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { loadCliWorkspace } from './workspace-config.js'
+import { machineParallelism } from '../util/index.js'
 
 export interface ResolvedPluginCommand {
   plugin: VxPlugin
@@ -41,7 +42,7 @@ export interface UnresolvedPluginCommand {
 async function workspacePlugins(
   cwd: string,
 ): Promise<
-  | { workspaceRoot: string; cacheDir: string; plugins: readonly VxPlugin[] }
+  | { workspaceRoot: string; cacheDir: string; concurrency: number; plugins: readonly VxPlugin[] }
   | UnresolvedPluginCommand
   | null
 > {
@@ -57,7 +58,13 @@ async function workspacePlugins(
   } catch (err) {
     return { loadError: err instanceof Error ? err.message : String(err) }
   }
-  return { workspaceRoot, cacheDir: ws.cacheDir, plugins: ws.plugins }
+  return {
+    workspaceRoot,
+    cacheDir: ws.cacheDir,
+    // What run.ts takes when no --concurrency is given.
+    concurrency: ws.workspaceConfig?.concurrency ?? machineParallelism(),
+    plugins: ws.plugins,
+  }
 }
 
 /**
@@ -84,6 +91,7 @@ export async function resolvePluginCommand(
       ctx: {
         workspaceRoot: ws.workspaceRoot,
         cacheDir: ws.cacheDir,
+        concurrency: ws.concurrency,
         warn: (m) => process.stderr.write(`${m}\n`),
       },
     }

package/src/cli/run.ts

@@ -556,6 +556,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
         ...(parsed.frozen ? { frozen: true } : {}),
       },
     )
+    if (picked === 'interrupted') return 130
     if (!picked) return 1
     tasks = [`${picked.project}#${picked.task}`]
   }