@vzn/vx 0.0.596 → 0.0.597

package/launcher.cjs

@@ -18,12 +18,16 @@
 // CommonJS, not ESM: Node's ESM loader cost every `vx` call ~8 ms of a
 // ~65 ms launch (min of 21, interleaved, Node 22, 2026-10-01).
 const { execFileSync, spawn, spawnSync } = require('node:child_process')
-const { existsSync, readFileSync } = require('node:fs')
+const { existsSync, readFileSync, realpathSync } = require('node:fs')
 const { constants: osConstants } = require('node:os')
 const { dirname, join } = require('node:path')
 
-const here = __dirname
-const pkg = require('./package.json')
+// The real directory, not `__dirname`: npm's `node_modules/.bin/vx` is a
+// symlink to this file, and under `--preserve-symlinks-main` (NODE_OPTIONS)
+// `__dirname` is `.bin`, where `./package.json` does not resolve and
+// the launcher died MODULE_NOT_FOUND before vx started.
+const here = dirname(realpathSync(__filename))
+const pkg = require(join(here, 'package.json'))
 
 // Derive the platform-package prefix + binary basename from this package's
 // name. `base` is the unscoped name — the command AND the binary filename

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.596",
+  "version": "0.0.597",
   "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.596",
-    "@vzn/vx-linux-arm64": "0.0.596",
-    "@vzn/vx-darwin-x64": "0.0.596",
-    "@vzn/vx-darwin-arm64": "0.0.596"
+    "@vzn/vx-linux-x64": "0.0.597",
+    "@vzn/vx-linux-arm64": "0.0.597",
+    "@vzn/vx-darwin-x64": "0.0.597",
+    "@vzn/vx-darwin-arm64": "0.0.597"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/archive.ts

@@ -233,7 +233,7 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const few = args.outputs.size <= ON_THREAD_STATS
   const lstatOf = few ? async (p: string) => lstatSync(p) : lstat
   const statOf = few ? async (p: string) => statSync(p) : stat
-  const realpathOf = few ? async (p: string) => realpathSync(p) : realpath
+  const realpathOf = (p: string) => realOf(p, few)
   let withinReal: Promise<string> | undefined
   // Where this artifact's own non-link outputs really are: a link to one of
   // them packs bytes the task wrote itself. A root-anchored output tree is
@@ -262,6 +262,16 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
         : name.startsWith(WORKSPACE_OUTPUT_PREFIX)
           ? `workspaceFiles output ${name.slice(WORKSPACE_OUTPUT_PREFIX.length)}`
           : `output ${name}`
+      // The index stores a project row as its bare rel and reads one under
+      // `workspace-outputs/` as a workspace output, so every hit of this
+      // entry was "missing a recorded output", dropped and run again. The
+      // loader refuses a glob written under the name; one that reaches it
+      // otherwise (`**/*.js`, `w*/**`) is refused here, where names are known.
+      if (name.startsWith(`outputs/${WORKSPACE_OUTPUT_PREFIX}`)) {
+        throw new UserError(
+          `${shown} is under workspace-outputs/, a name vx's artifacts reserve for outputs.workspaceFiles — write the task's files to another directory, or take them back with a '!' entry`,
+        )
+      }
       const dangling = (err: NodeJS.ErrnoException): never => {
         if (err.code === 'ENOENT') {
           throw new UserError(
@@ -293,12 +303,12 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
         )
       }
       const mode = st.mode & 0o777
-      meta.files[name] = [mode, Math.floor(st.mtimeMs)]
       return {
         name,
         abs: src,
         size: st.size,
         mode,
+        mtimeMs: Math.floor(st.mtimeMs),
         // ustar's octal field holds no sign: an mtime before 1970 made the
         // header unreadable and every save of it a "corrupt artifact". The
         // sidecar above carries the real value.
@@ -306,6 +316,8 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       }
     }),
   )
+  // In the outputs' order, not as each stat settled: one tree, one artifact.
+  for (const f of files) meta.files[f.name] = [f.mode, f.mtimeMs]
   const stdout = new TextEncoder().encode(args.stdout)
   const metaBytes = new TextEncoder().encode(JSON.stringify(meta))
   const inputs: TarInput[] = [
@@ -624,11 +636,11 @@ class Extractor {
       // deepest EXISTING ancestor and re-append the rest: the answer is the
       // same before and after the base is created, which is what makes the
       // memo safe.
-      r = await realpath(key).catch(async () => {
+      r = await realOf(key).catch(async () => {
         let probe = path.dirname(key)
         const tail: string[] = [path.basename(key)]
         while (probe !== path.dirname(probe)) {
-          const real = await realpath(probe).then(
+          const real = await realOf(probe).then(
             (v) => v,
             () => null,
           )
@@ -674,7 +686,7 @@ class Extractor {
     // resolve was a round trip spent on a comparison never made (item 627).
     let probe = path.dirname(targetResolved)
     while (probe.startsWith(baseResolved + path.sep)) {
-      const real = await realpath(probe).then(
+      const real = await realOf(probe).then(
         (r) => r,
         () => null,
       )
@@ -854,7 +866,7 @@ class Extractor {
       const top = path.resolve(s.created)
       // Created at a dangling link's resolved target (`mkdirThroughLink`),
       // so the chain is pruned from where the link leads.
-      if (!dir.startsWith(top)) dir = await realpath(dir).catch(() => dir)
+      if (!dir.startsWith(top)) dir = await realOf(dir).catch(() => dir)
       while (dir.startsWith(top)) {
         if (
           !(await rmdir(dir).then(
@@ -903,6 +915,23 @@ async function linkOutError(base: string, probe: string, realBase: string): Prom
   )
 }
 
+/**
+ * `realpath`, for a path holding a backslash too: Bun's answers ENOENT for
+ * any such path (1.4.2), so the containment walk took a link named
+ * `dist\x` for absent and wrote through it, and a save called a linked
+ * output under one dangling. Such a path's links are read one by one.
+ */
+async function realOf(p: string, sync = false): Promise<string> {
+  try {
+    return sync ? realpathSync(p) : await realpath(p)
+  } catch (err) {
+    if (!p.includes('\\')) throw err
+    const real = await resolveThrough(p)
+    await stat(real)
+    return real
+  }
+}
+
 /**
  * Where `p` leads, every link on the way followed, a dangling one included:
  * `realpath` for the part that exists, and past the first missing name the

package/src/cache/cache.ts

@@ -662,7 +662,7 @@ export class Cache implements CacheLayer {
 
   /**
    * The store this open was asked for and could not use, with why: the
-   * entries went to a store inside `cacheDir` instead.
+   * entries went to a store inside `cacheDir` instead. Never printed.
    */
   readonly storeFallback: string | null = null
 
@@ -849,24 +849,33 @@ export class Cache implements CacheLayer {
         this.schemaReset = this.db
           .transaction((): SchemaReset | null => {
             const found = readVersion()
-            if (found !== undefined && found !== SCHEMA_VERSION) refuseUnreadable(found)
-            if (found === undefined) {
-              this.db
-                .prepare("INSERT INTO schema_meta(key, value) VALUES ('version', ?)")
-                .run(SCHEMA_VERSION)
-              return null
-            }
             if (found === SCHEMA_VERSION) return null
+            if (found !== undefined) refuseUnreadable(found)
             // `main.` on every name: unqualified, a table the index lacks
             // resolves to an attached store's (none is attached yet; this
             // keeps it so).
-            this.db.exec(
-              'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.store_meta;',
-            )
+            if (found !== undefined) {
+              this.db.exec(
+                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.store_meta;',
+              )
+            }
+            // The tables land under the same write lock as the stamp: made
+            // after it, another vx's reset could stamp its own schema in
+            // between and keep these tables under it. An index beside a
+            // store keeps no entry tables (they would shadow the store's).
+            createTables(this.db, 'main')
+            const recordedStore = this.db
+              .prepare("SELECT 1 FROM schema_meta WHERE key = 'store_dir'")
+              .get()
+            if (storeRoot === undefined ? recordedStore != null : storeRoot !== null) {
+              for (const t of STORE_TABLES) this.db.exec(`DROP TABLE main.${t}`)
+            }
             this.db
-              .prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'")
+              .prepare(
+                "INSERT INTO schema_meta(key, value) VALUES ('version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+              )
               .run(SCHEMA_VERSION)
-            return { from: found, to: SCHEMA_VERSION }
+            return found === undefined ? null : { from: found, to: SCHEMA_VERSION }
           })
           .immediate()
       } catch (err) {
@@ -904,7 +913,8 @@ export class Cache implements CacheLayer {
         // the entries stay in this workspace rather than fail the run.
         const fallback = cacheDir
         if (fallback !== storeDir) {
-          // Said by the open that falls back; the ones after it find it recorded.
+          // Set by the open that falls back, never printed; the ones after it
+          // find it recorded.
           if (recorded !== fallback) this.storeFallback = `${storeDir} (${blocked})`
           storeDir = fallback
           openCacheDir(fallback)
@@ -1769,6 +1779,9 @@ export class Cache implements CacheLayer {
         hash,
         `remote body runs past ${cap} bytes (the artifact ceiling's bound)`,
       )
+    // Every refusal releases the remote body: a held response pins its
+    // connection, and a layer that settles on the body's end never hears.
+    let counted: ReadableStream<Uint8Array> | undefined
     try {
       if (body instanceof Blob) {
         if (body.size > cap) throw past()
@@ -1777,7 +1790,7 @@ export class Cache implements CacheLayer {
         throw past()
       } else {
         let n = 0
-        const counted = body.body?.pipeThrough(
+        counted = body.body?.pipeThrough(
           new TransformStream<Uint8Array, Uint8Array>({
             transform(chunk, controller) {
               n += chunk.byteLength
@@ -1789,6 +1802,9 @@ export class Cache implements CacheLayer {
         await Bun.write(tmpPath, new Response(counted ?? null))
       }
     } catch (err) {
+      // A failed write leaves the pipe's end unlocked; cancelling it
+      // cancels the source. A body refused by its length is cancelled itself.
+      if (!(body instanceof Blob)) void (counted ?? body.body)?.cancel(err).catch(() => undefined)
       await unlink(tmpPath).catch(() => undefined)
       throw err
     }

package/src/cache/git-inputs.ts

@@ -87,6 +87,29 @@ export function repoFacts(dir: string): RepoFacts | null {
   return facts
 }
 
+/**
+ * The refusal a run would meet at its enumeration, asked up front by a
+ * verb that waits on the user first (the picker); undefined when git
+ * tracks `dir`. Free when it does: `repoFacts` is the answer the run
+ * reuses.
+ */
+export function gitRefusal(dir: string): UserError | undefined {
+  if (repoFacts(dir) !== null) return undefined
+  let proc
+  try {
+    proc = Bun.spawnSync({
+      cmd: [executablePath('git'), 'rev-parse', '--is-inside-work-tree'],
+      cwd: dir,
+      stdout: 'ignore',
+      stderr: 'pipe',
+    })
+  } catch {
+    return gitSpawnRefusal(dir)
+  }
+  if (proc.exitCode === 0) return undefined
+  return notAWorkTree(dir, new TextDecoder().decode(proc.stderr).trim())
+}
+
 /** Variables that move where git finds the repository or its index: with any set, git is asked. */
 const GIT_LOCATION_ENV = [
   'GIT_INDEX_FILE',

package/src/cache/index.ts

@@ -36,6 +36,7 @@ export {
   cleanOutputs,
   cleanWorkspaceOutputs,
   declaresInput,
+  workspaceFilesReachInto,
   resolveInputs,
   resolveOutputs,
   resolveWorkspaceOutputs,
@@ -52,6 +53,7 @@ export {
 } from './inputs.js'
 export {
   GitFilesCache,
+  gitRefusal,
   applyGitEnumeration,
   gitPathspecs,
   MAX_SCOPED_PATHSPECS,

package/src/cache/inputs.ts

@@ -17,7 +17,7 @@
 // be a git work tree; non-git environments are not supported.
 
 import path from 'node:path'
-import { lstatSync, readdirSync, realpathSync, rmdirSync, rmSync } from 'node:fs'
+import { lstatSync, readdirSync, realpathSync, rmdirSync, rmSync, statSync } from 'node:fs'
 import { rm, rmdir } from 'node:fs/promises'
 import type { CacheConfig, CacheInputs } from '../config.js'
 import {
@@ -33,6 +33,7 @@ import {
   slashBraceExpansions,
   splitNegations,
   staticPrefix,
+  stripTrailingSlash,
   taskGlob,
   UserError,
 } from '../util/index.js'
@@ -643,7 +644,11 @@ function outputExcludes(outputs: readonly string[]): Bun.Glob[] {
   return (namesNodeModules ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**']).map(globFor)
 }
 
-/** Resolve declared output globs (project-relative) to actual produced files. */
+/**
+ * Resolve declared output globs (project-relative) to actual produced files.
+ * An output directory linked out of the project is refused by name (X-88):
+ * dropping its files silently saved an empty entry under a green run.
+ */
 export async function resolveOutputs(args: {
   projectDir: string
   outputs: readonly string[]
@@ -652,9 +657,11 @@ export async function resolveOutputs(args: {
   const { positive, negative } = splitNegations(args.outputs)
   if (positive.length === 0) return []
   const excludeGlobs = [...outputExcludes(positive), ...asTrees(negative).map(globFor)]
+  const trees = asTrees(positive)
+  refuseDirLinkedOut(args.projectDir, trees)
   const scanned = [
     ...(await scanUnion(
-      asTrees(positive),
+      trees,
       excludeGlobs,
       args.projectDir,
       inNestedProject(args.projectDir, args.nestedProjectDirs),
@@ -670,6 +677,53 @@ export async function resolveOutputs(args: {
   return containedIn(args.projectDir, scanned).sort()
 }
 
+/**
+ * The literal head of each output glob, walked: the scan follows a link
+ * there (`dist -> ../elsewhere` for `dist/**`) and only there. A link to a
+ * FILE is the archive's to judge (L-23); a dangling one the restore's.
+ */
+function refuseDirLinkedOut(projectDir: string, trees: readonly string[]): void {
+  let realRoot: string | undefined
+  for (const tree of trees) {
+    let at = projectDir
+    for (const part of staticPrefix(tree).split('/')) {
+      if (part === '' || part === '.') continue
+      at = path.join(at, part)
+      if (!isInside(projectDir, at)) break
+      let st
+      try {
+        st = lstatSync(at)
+      } catch {
+        break
+      }
+      if (!st.isSymbolicLink()) continue
+      let real: string
+      try {
+        real = realpathSync(at)
+        if (!statSync(real).isDirectory()) break
+      } catch {
+        break
+      }
+      realRoot ??= realOr(projectDir)
+      if (!isInside(realRoot, real)) {
+        throw new UserError(
+          `${at} is a symbolic link to ${real}, outside ${projectDir} — vx never cleans, saves ` +
+            'or restores declared outputs through a link that leaves the project. Remove the ' +
+            'link and re-run, or stop declaring outputs under it.',
+        )
+      }
+    }
+  }
+}
+
+function realOr(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
 /**
  * Keep only the paths that are REALLY inside `root` — lexically, and after
  * resolving symlinks.
@@ -708,16 +762,9 @@ function containedIn(root: string, paths: readonly string[]): string[] {
   // Sync, as `hashFile`'s lstat: a realpath is microseconds, and the
   // promise round trip per call was most of this function's cost on every
   // miss (B, 2026-09-30).
-  const real = (p: string): string | null => {
-    try {
-      return realpathSync(p)
-    } catch {
-      return null
-    }
-  }
-  const realRoot = real(root) ?? root
+  const realRoot = realOrNull(root) ?? root
   const uniqueDirs = [...new Set(lexDirs)]
-  const resolved = uniqueDirs.map(real)
+  const resolved = uniqueDirs.map(realOrNull)
   const contained = new Set<string>()
   for (const [i, dir] of uniqueDirs.entries()) {
     const real = resolved[i]
@@ -899,7 +946,7 @@ const SYNC_CLEAN_MAX = 128
  * sends the reader to file a bug against a permission bit.
  */
 async function removeAll(all: readonly string[], root: string): Promise<string[]> {
-  const files = notThroughLink(all, root)
+  const files = insideRoot(all, root)
   const refused = (f: string, err: NodeJS.ErrnoException): UserError => {
     const rel = relPosix(root, f)
     return new UserError(
@@ -929,21 +976,14 @@ async function removeAll(all: readonly string[], root: string): Promise<string[]
 }
 
 /**
- * The paths whose directory is really where it sits, not reached through a
- * symlinked directory. A save follows `dist -> real-out` on purpose
- * (turborepo#13042), but a clean through a link deletes the target's
- * files: `public -> static` in the same project took the tracked
- * `static/logo.svg` before every run (X-5). The link is a declared
- * output's own entry; what it leads to is not.
+ * The paths whose directory resolves inside `root`. A link inside the
+ * project is followed, as the save follows it (turborepo#13042): a clean
+ * that skipped `dist -> real-out` left the last run's files for the next
+ * entry to save (X-88). One that leaves the project is never deleted
+ * through (X-5); `cleanOutputPaths` takes recorded rows, not the resolver's
+ * contained set, so the check is here too.
  */
-function notThroughLink(files: readonly string[], root: string): string[] {
-  const real = (p: string): string | null => {
-    try {
-      return realpathSync(p)
-    } catch {
-      return null
-    }
-  }
+function insideRoot(files: readonly string[], root: string): string[] {
   // Resolved only once a directory exists to compare: after a clean pruned
   // the outputs (the common restore) nothing does, and the call was most
   // of an empty clean.
@@ -955,9 +995,8 @@ function notThroughLink(files: readonly string[], root: string): string[] {
     if (ok === undefined) {
       // A directory already gone has nothing to delete through; its path
       // stays so the prune still reaches the parents it emptied.
-      const r = real(dir)
-      ok =
-        r === null || r === path.join((realRoot ??= real(root) ?? root), path.relative(root, dir))
+      const r = realOrNull(dir)
+      ok = r === null || isInside((realRoot ??= realOrNull(root) ?? root), r)
       own.set(dir, ok)
     }
     return ok
@@ -1101,8 +1140,12 @@ export async function cleanWorkspaceOutputs(args: {
   return files.map((f) => relPosix(args.workspaceRoot, f))
 }
 
-function stripTrailingSlash(p: string): string {
-  return p.replace(/\/+$/, '')
+function realOrNull(p: string): string | null {
+  try {
+    return realpathSync(p)
+  } catch {
+    return null
+  }
 }
 
 // The literal-is-a-tree rule moved to `util/paths.ts` (item 442): it
@@ -1356,6 +1399,18 @@ export function declaresInput(
   return matcher(workspaceRel)
 }
 
+/**
+ * Whether a cached task's `workspaceFiles` may name a file under `dir`
+ * (workspace-relative): a nested repository git reports as that one path,
+ * whose files the key folds and a match against the path alone misses.
+ * By the entries' static prefixes, so a glob that may descend counts.
+ */
+export function workspaceFilesReachInto(cache: CacheConfig, dir: string): boolean {
+  const ws = cache.inputs.workspaceFiles
+  if (ws === undefined || ws.length === 0) return false
+  return reaches(reachOf(splitNegations(ws).positive).prefixes, dir)
+}
+
 function inPlan(plan: FilesPlan, rel: string): boolean {
   let input = plan.verdicts.get(rel)
   if (input === undefined) {

package/src/cache/key-fold.ts

@@ -103,7 +103,7 @@ import type { CacheKeyInput } from './layer.js'
 // 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-v40'
+export const CACHE_VERSION = 'vx-cache-v41'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its

package/src/cache/layer.ts

@@ -332,7 +332,8 @@ export interface PruneResult {
  * discriminator — least-invasive row format, no schema change. A
  * project output dir literally named `workspace-outputs/` would
  * collide with the namespace; the name is reserved, and a project
- * output glob under it is refused at load (config-schema.ts).
+ * output glob under it is refused at load (config-schema.ts), a file
+ * another glob reaches there at save (`planArtifact`).
  */
 export const WORKSPACE_OUTPUT_PREFIX = 'workspace-outputs/'
 

package/src/cli/cache.ts

@@ -140,13 +140,13 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
         return {
           error: `${refusedWord(a ?? '')}: ${a}${flagHint('cache prune', a ?? '')}${seeHelp('cache')}`,
         }
-      if ('error' in cd) return { error: cd.error }
+      if ('error' in cd) return { error: `${cd.error}${seeHelp('cache')}` }
       out.cacheDir = cd.cacheDir
       i = cd.next
     }
   }
   if (out.olderThanMs === undefined && out.maxBytes === undefined) {
-    return { error: 'must pass --older-than <duration> or --max-size <bytes>' }
+    return { error: `needs --older-than <duration> or --max-size <size>${seeHelp('cache')}` }
   }
   return out
 }

package/src/cli/foreign-flags.ts

@@ -1,4 +1,4 @@
-// What a Turbo or Nx user's hands type, and what `vx run` does with it.
+// What a Turbo, Nx or Vite Task (`vp run`) user's hands type, and what `vx run` does with it.
 // Every flag here has one outcome: vx takes it as it is (`same`), takes it
 // as another spelling (`alias`, rewritten before the parse), or refuses it
 // with the vx way to say it (`refuse`). Nothing is dropped in silence: a
@@ -7,7 +7,7 @@
 // cli.md's parity section (`renderForeignFlags`), pinned by a test.
 
 interface ForeignFlag {
-  runner: 'turbo' | 'nx'
+  runner: 'turbo' | 'nx' | 'vp'
   /** Every spelling, first the one shown. */
   names: readonly string[]
   /** It takes a value: `--flag <v>` or `--flag=<v>`. */
@@ -598,6 +598,60 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     outcome: 'refuse',
     vx: 'vx has no cloud: drop it',
   },
+  {
+    runner: 'vp',
+    names: ['-r', '--recursive'],
+    value: false,
+    outcome: 'alias',
+    vx: '`--all`',
+    to: () => ['--all'],
+  },
+  {
+    runner: 'vp',
+    names: ['-w', '--workspace-root'],
+    value: false,
+    outcome: 'alias',
+    vx: '`--filter //` (the root project)',
+    to: () => ['--filter', '//'],
+  },
+  {
+    runner: 'vp',
+    names: ['--concurrency-limit'],
+    value: true,
+    outcome: 'alias',
+    vx: '`--concurrency <n>`',
+    to: (v) => (v === undefined ? ['--concurrency'] : ['--concurrency', v]),
+  },
+  {
+    runner: 'vp',
+    names: ['--ignore-depends-on'],
+    value: false,
+    outcome: 'alias',
+    vx: '`--exclude-dependencies`',
+    to: () => ['--exclude-dependencies'],
+  },
+  {
+    runner: 'vp',
+    names: ['--fail-if-no-match'],
+    value: false,
+    outcome: 'alias',
+    vx: 'nothing: a filter that matches nothing already fails the run',
+    to: () => [],
+  },
+  {
+    runner: 'vp',
+    names: ['--log'],
+    value: true,
+    outcome: 'refuse',
+    vx: 'vx frames each task’s output: `--output-logs <mode>` sets how much',
+  },
+  {
+    runner: 'vp',
+    names: ['--last-details'],
+    value: false,
+    outcome: 'refuse',
+    vx: '`vx last` prints the last run',
+  },
 ]
 
 /** Nx's verbs, as its users type them: `vx run` takes their flags. */

package/src/cli/info.ts

@@ -29,7 +29,7 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
     }
     const cd = parseCacheDirFlag(args, i)
     if (cd !== null) {
-      if ('error' in cd) return { ...out, error: cd.error }
+      if ('error' in cd) return { ...out, error: `${cd.error}${seeHelp('info')}` }
       out.cacheDir = cd.cacheDir
       i = cd.next
       continue

package/src/cli/init.ts

@@ -42,7 +42,7 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
       if (seam === undefined || !Object.hasOwn(PLUGIN_TEMPLATES, seam)) {
         return {
           ...out,
-          error: `--plugin takes a seam: one of ${seams}${seam === undefined ? '' : ` (got '${seam}')`}`,
+          error: `--plugin takes a seam: one of ${seams}${seam === undefined ? '' : ` (got '${seam}')`}${seeHelp('init')}`,
         }
       }
       out.plugin = seam
@@ -56,7 +56,7 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
   if (out.plugin !== undefined && out.mjs) {
     return {
       ...out,
-      error: '--mjs does not combine with --plugin: the plugin templates are TypeScript',
+      error: `--mjs does not combine with --plugin: the plugin templates are TypeScript${seeHelp('init')}`,
     }
   }
   return out

package/src/cli/last.ts

@@ -80,7 +80,7 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
     }
     const cd = parseCacheDirFlag(args, i)
     if (cd !== null) {
-      if ('error' in cd) return { ...out, error: cd.error }
+      if ('error' in cd) return { ...out, error: `${cd.error}${seeHelp('last')}` }
       out.cacheDir = cd.cacheDir
       i = cd.next
       continue
@@ -99,11 +99,14 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
   if (out.runId !== undefined && out.list !== undefined) {
     return {
       ...out,
-      error: `a run id and --list do not combine: replay ${out.runId}, or list runs`,
+      error: `a run id and --list do not combine: replay ${out.runId}, or list runs${seeHelp('last')}`,
     }
   }
   if (out.runId !== undefined && out.failed === true) {
-    return { ...out, error: `a run id and --failed do not combine: replay ${out.runId}` }
+    return {
+      ...out,
+      error: `a run id and --failed do not combine: replay ${out.runId}${seeHelp('last')}`,
+    }
   }
   return out
 }