@vzn/vx 0.0.591 → 0.0.595

package/src/cli/cache.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { Cache } from '../cache/index.js'
-import { flagHint, refusedWord, seeHelp } from './help.js'
+import { flagHint, formatValue, refusedWord, seeHelp } from './help.js'
 import { nearest, parseDuration, parseSize } from '../util/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
@@ -125,10 +125,8 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
     } else if (a === '--dry-run') {
       out.dryRun = true
     } else if (a === '--format' || a?.startsWith('--format=')) {
-      const v = a === '--format' ? args[++i] : a.slice('--format='.length)
-      if (v !== 'pretty' && v !== 'json') {
-        return { error: `--format must be pretty or json${seeHelp('cache')}` }
-      }
+      const v = formatValue(a === '--format' ? args[++i] : a.slice('--format='.length), 'cache')
+      if (typeof v === 'object') return v
       out.format = v
     } else {
       const cd = parseCacheDirFlag(args, i)
@@ -187,19 +185,9 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
     printPruned({ evicted: 0, bytesFreed: 0, orphans: 0, orphanBytes: 0 }, dry, json)
     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 another vx version: the prune resets it first, and every artifact past the hour's grace is then an orphan`,
-      )
-      printPruned({ evicted: 0, bytesFreed: 0, ...earlier }, true, json)
-      return 0
-    }
-  }
   const cache =
     parsed.dryRun === true
-      ? new Cache(dir, undefined, undefined, undefined, 'inspect', storeRoot)
+      ? new Cache(dir, undefined, undefined, undefined, 'preview', storeRoot)
       : new Cache(dir, undefined, root, undefined, 'open', storeRoot)
   // 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

package/src/cli/completions.ts

@@ -8,6 +8,13 @@
 import { acceptedFlags, CORE_VERBS, flagHint, seeHelp } from './help.js'
 import { nearest } from '../util/index.js'
 
+/** A flag whose value is one of a fixed set; the tests hold each to its parser. */
+export const FLAG_VALUES: Readonly<Record<string, readonly string[]>> = {
+  '--format': ['pretty', 'json'],
+  '--output-logs': ['full', 'errors-only', 'hash-only', 'none'],
+  '--download': ['all', 'toplevel', 'none'],
+}
+
 export type CompletionShell = 'bash' | 'zsh' | 'fish'
 const SHELLS: readonly CompletionShell[] = ['bash', 'zsh', 'fish']
 
@@ -36,6 +43,14 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
       ...((CORE_VERBS as readonly string[]).includes(v) ? verbFlags(v) : ['--help']),
     ],
   }))
+  // `vx run --output-logs <Tab>` offered the flags again; a flag with a
+  // fixed value set offers that set.
+  const values = table.flatMap((t) =>
+    t.words.flatMap((w) => {
+      const vs = FLAG_VALUES[w]
+      return vs === undefined ? [] : [{ verb: t.verb, flag: w, values: vs.join(' ') }]
+    }),
+  )
   switch (shell) {
     case 'bash':
       return [
@@ -43,10 +58,23 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         '_vx() {',
         '  local cur="${COMP_WORDS[COMP_CWORD]}"',
         '  local verb="${COMP_WORDS[1]}"',
+        '  local prev="${COMP_WORDS[COMP_CWORD-1]}"',
         '  if [ "$COMP_CWORD" -eq 1 ]; then',
         `    COMPREPLY=($(compgen -W "${verbs.join(' ')}" -- "$cur"))`,
         '    return',
         '  fi',
+        // bash splits `--format=js` at the `=` (COMP_WORDBREAKS).
+        '  if [ "$cur" = "=" ]; then',
+        '    cur=""',
+        '  elif [ "$prev" = "=" ]; then',
+        '    prev="${COMP_WORDS[COMP_CWORD-2]}"',
+        '  fi',
+        '  case "$verb $prev" in',
+        ...values.map(
+          (v) =>
+            `    "${v.verb} ${v.flag}") COMPREPLY=($(compgen -W "${v.values}" -- "$cur")); return ;;`,
+        ),
+        '  esac',
         '  case "$verb" in',
         ...table.map(
           (t) => `    ${t.verb}) COMPREPLY=($(compgen -W "${t.words.join(' ')}" -- "$cur")) ;;`,
@@ -66,6 +94,9 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         `    compadd -- ${verbs.join(' ')}`,
         '    return',
         '  fi',
+        '  case "${words[2]} ${words[CURRENT-1]}" in',
+        ...values.map((v) => `    "${v.verb} ${v.flag}") compadd -- ${v.values}; return ;;`),
+        '  esac',
         '  case "${words[2]}" in',
         ...table.map((t) => `    ${t.verb}) compadd -- ${t.words.join(' ')} ;;`),
         '  esac',
@@ -86,11 +117,14 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         'complete -c vx -f',
         ...verbs.map((v) => `complete -c vx -n __fish_use_subcommand -a ${v}`),
         ...table.flatMap((t) =>
-          t.words.map((w) =>
-            w.startsWith('--')
-              ? `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}" -l ${w.slice(2)}`
-              : `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}" -a ${w}`,
-          ),
+          t.words.map((w) => {
+            const on = `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}"`
+            if (!w.startsWith('--')) return `${on} -a ${w}`
+            const vs = FLAG_VALUES[w]
+            return vs === undefined
+              ? `${on} -l ${w.slice(2)}`
+              : `${on} -l ${w.slice(2)} -x -a "${vs.join(' ')}"`
+          }),
         ),
         '',
       ].join('\n')
@@ -111,7 +145,9 @@ export async function completionsCmd(
       return 1
     }
     const one = shell !== undefined && args.length === 1
-    const best = one ? nearest(shell, SHELLS) : undefined
+    // One edit: shell names are three or four letters, so two edits took
+    // `tcsh` to `bash`, a different shell.
+    const best = one ? nearest(shell, SHELLS, 1) : undefined
     process.stderr.write(
       `vx completions: expected one shell — bash, zsh or fish${one ? ` (got ${shell})` : ''}${best === undefined ? '' : `. Did you mean ${best}?`}${seeHelp('completions')}\n`,
     )

package/src/cli/foreign-flags.ts

@@ -6,7 +6,7 @@
 // on left a `turbo run --dry-run` user at a dead end. The table renders
 // cli.md's parity section (`renderForeignFlags`), pinned by a test.
 
-export interface ForeignFlag {
+interface ForeignFlag {
   runner: 'turbo' | 'nx'
   /** Every spelling, first the one shown. */
   names: readonly string[]
@@ -19,6 +19,13 @@ export interface ForeignFlag {
   outcome: 'same' | 'alias' | 'refuse'
   /** The vx spelling, or what to use instead. */
   vx: string
+  /**
+   * The runner reads `=true` / `=false` on it (Turbo's `--force [FORCE]`,
+   * Nx's yargs booleans): `=false` is the flag left out, `=true` the flag
+   * bare. `--skip-nx-cache=false` forced every task, `--summarize=true`
+   * wrote the summary to a file named `true`.
+   */
+  bool?: true
   /** For an alias: the vx argv. For a refusal: none. */
   to?: (value: string | undefined) => string[]
 }
@@ -29,6 +36,17 @@ const list = (v: string | undefined): string[] =>
     .map((s) => s.trim())
     .filter((s) => s !== '')
 
+// Nx's `--projects` labels (find-matching-projects, 23.2.1): `name:` and
+// `directory:` say which match to make; vx's filter says it by form. `tag:`
+// is a filter form already.
+const nxPattern = (p: string): string => {
+  const neg = p.startsWith('!') ? '!' : ''
+  const s = neg === '' ? p : p.slice(1)
+  if (s.startsWith('name:')) return `${neg}${s.slice(5)}`
+  if (s.startsWith('directory:')) return `${neg}./${s.slice(10)}`
+  return p
+}
+
 const GRAPH_IMAGE = /\.(svg|png|jpe?g|pdf|json|html|mermaid)$/i
 
 export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
@@ -100,6 +118,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--force'],
     value: false,
+    bool: true,
     outcome: 'same',
     vx: '`--force`: skip cache reads, keep writes',
   },
@@ -114,6 +133,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--summarize'],
     value: false,
+    bool: true,
     outcome: 'same',
     vx: '`--summarize[=<path>]`',
   },
@@ -133,7 +153,14 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     outcome: 'same',
     vx: '`--output-logs full|errors-only|hash-only|none`',
   },
-  { runner: 'turbo', names: ['--no-cache'], value: false, outcome: 'same', vx: '`--no-cache`' },
+  {
+    runner: 'turbo',
+    names: ['--no-cache'],
+    value: false,
+    outcome: 'same',
+    // Turbo 2.11's own help: "Equivalent to `--cache=local:r,remote:r`".
+    vx: "`--no-cache` reads nothing either; Turbo's (reads, no writes) is `--cache local:r,remote:r`",
+  },
   {
     runner: 'turbo',
     names: ['--cache'],
@@ -268,6 +295,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--remote-only'],
     value: false,
+    bool: true,
     outcome: 'refuse',
     vx: 'use `--cache local:,remote:rw`',
   },
@@ -275,6 +303,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--remote-cache-read-only'],
     value: false,
+    bool: true,
     outcome: 'refuse',
     vx: 'use `--cache local:rw,remote:r`',
   },
@@ -396,8 +425,16 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['-p', '--projects'],
     value: true,
     outcome: 'alias',
-    vx: '`--filter <pattern>`, one per project',
-    to: (v) => list(v).flatMap((p) => ['--filter', p]),
+    vx: "`--filter <pattern>`, one per project (`directory:<d>` is `./<d>`, `name:<n>` is `<n>`); a list opening with `!` starts from all (`--filter '*'`)",
+    // Nx reads a leading exclusion as "all projects but": `-p '!b,a'` is
+    // every project except b, where vx's filters alone would select a.
+    to: (v) => {
+      const ps = list(v)
+      return [...(ps[0]?.startsWith('!') ? ['*'] : []), ...ps].flatMap((p) => [
+        '--filter',
+        nxPattern(p),
+      ])
+    },
   },
   {
     runner: 'nx',
@@ -405,7 +442,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     value: true,
     outcome: 'alias',
     vx: "`--filter '!<pattern>'`, one per project",
-    to: (v) => list(v).flatMap((p) => ['--filter', `!${p}`]),
+    to: (v) => list(v).flatMap((p) => ['--filter', `!${nxPattern(p)}`]),
   },
   {
     runner: 'nx',
@@ -436,6 +473,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--skip-nx-cache'],
     value: false,
+    bool: true,
     outcome: 'alias',
     vx: '`--force`',
     to: () => ['--force'],
@@ -445,6 +483,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--nx-bail'],
     value: false,
+    bool: true,
     outcome: 'alias',
     vx: '`--continue=never`',
     to: () => ['--continue=never'],
@@ -482,6 +521,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--exclude-task-dependencies'],
     value: false,
+    bool: true,
     outcome: 'alias',
     vx: '`--exclude-dependencies`',
     to: () => ['--exclude-dependencies'],
@@ -490,6 +530,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--skip-remote-cache'],
     value: false,
+    bool: true,
     outcome: 'alias',
     vx: '`--cache local:rw,remote:`',
     to: () => ['--cache', 'local:rw,remote:'],
@@ -605,6 +646,13 @@ export function translateForeign(args: readonly string[]): string[] | { error: s
       name = kebab
       a = inline === undefined ? kebab : `${kebab}=${inline}`
     }
+    if (
+      (inline === 'true' || inline === 'false') &&
+      FOREIGN_FLAGS.some((f) => f.bool && f.names.includes(name))
+    ) {
+      if (inline === 'false') continue
+      a = name
+    }
     const entries = FOREIGN_FLAGS.filter((f) => f.names.includes(name) || f.names.includes(a))
     const next = before[i + 1]
     const spaced = inline === undefined && next !== undefined && !next.startsWith('-')
@@ -627,7 +675,9 @@ export function translateForeign(args: readonly string[]): string[] | { error: s
 /** cli.md's parity table, one row per entry. */
 export function renderForeignFlags(): string {
   const rows = FOREIGN_FLAGS.map((f) => {
-    const flag = f.shown ?? f.names.map((n) => `\`${n}${f.value ? ' <v>' : ''}\``).join(', ')
+    const flag =
+      f.shown ??
+      f.names.map((n) => `\`${n}${f.value ? ' <v>' : f.bool ? '[=<bool>]' : ''}\``).join(', ')
     return `| ${f.runner} | ${flag.replaceAll('|', '\\|')} | ${f.outcome} | ${f.vx.replaceAll('|', '\\|')} |`
   })
   return ['| runner | flag | outcome | in vx |', '| --- | --- | --- | --- |', ...rows].join('\n')

package/src/cli/help.ts

@@ -110,10 +110,10 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
     '  vx lock [--check]',
     '  vx init [--dry] [--force] [--mjs] [--plugin <seam>]',
-    '  vx upgrade [tag]',
-    '  vx show [PROJECT[#TASK] | TASK] [--format pretty|json]',
+    '  vx upgrade [TAG]',
+    '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
-    '  vx why (TASK | PKG#TASK) [--run <runId>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]',
     '  vx last [RUNID] [--list[=N]] [--failed] [--format pretty|json] [--cache-dir <path>]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
@@ -140,8 +140,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                                  to its flags; unnamed layers keep their value. Examples:',
     '                                  local:rw,remote:r (remote read-only), remote: (remote off),',
     '                                  local:r (local read-only).',
-    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats the workspace',
-    '                                  cacheDir field + the .vx/cache default.',
+    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats VX_CACHE_DIR,',
+    '                                  the workspace cacheDir field and the ~/.vx/<id>/cache default.',
     '      --retry <n>                 Re-run a failed task up to <n> more times (default for tasks',
     "                                  without their own exec.retries; explicit config wins). Doesn't",
     '                                  affect cache keys.',
@@ -209,22 +209,26 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       evaluation, not the lock), one block per task.',
     "  vx show <pkg>#<task> Print a single task's resolved config.",
     '  vx show <task>       That task in every project declaring it.',
+    "      --filter <pattern>  The list (or a task's projects) as `vx run --filter` selects.",
+    '      --affected[=<ref>]  Only what `vx run --affected` selects: changed and dependents.',
     '      --format <fmt>   pretty (default) | json.',
     '  vx info              Workspace doctor: vx/bun/git versions, project +',
     '                       task counts, cache dir/entries/size, recent runs,',
     '                       lock status.',
     '      --format <fmt>   pretty (default) | json.',
     "  vx why <task>        Why did this task re-run? Compares the task's latest",
-    '                       run (or --run <id>) against its previous run: names the',
+    '                       run (or --run RUNID) against its previous run: names the',
     '                       exact changed cache-key components (files / env / runtime',
     '                       / upstream) from the persisted input fingerprints.',
     '      --format <fmt>   pretty (default) | json.',
-    "  vx last [runId]      Replay a recorded run's summary from the local history —",
+    "  vx last [RUNID]      Replay a recorded run's summary from the local history —",
     '                       header (command, when, branch, counts) plus the per-task',
     '                       table, failures first. No re-execution, no cache probe.',
     '      --list[=N]       List the N most recent runs (default 10) with run ids.',
     '      --failed         Only failed runs: the latest one, or with --list the list.',
     '      --format <fmt>   pretty (default) | json.',
+    '  info, why and last:',
+    '      --cache-dir <path>  Read the cache a run with the same flag uses.',
     '',
     'Migration:',
     '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
@@ -233,6 +237,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       only vx.workspace.ts, declaring turbo() or nx().',
     '      --dry            Print the generated files instead of writing them.',
     '      --force          Overwrite existing vx.config.* files.',
+    '      --mjs            Write .mjs files (no type import) instead of .ts.',
     '      --plugin <seam>  Instead: write plugins/<seam>.ts, a runnable plugin, and its',
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
@@ -267,6 +272,20 @@ export function seeHelp(verb: string): string {
   return ` (see \`vx ${verb} --help\`)`
 }
 
+/** `--format`'s value, or the one refusal every verb gives for a bad one. */
+export function formatValue(
+  v: string | undefined,
+  verb: string,
+): 'pretty' | 'json' | { error: string } {
+  if (v === 'pretty' || v === 'json') return v
+  return {
+    error:
+      v === undefined || v === ''
+        ? `--format requires a value: pretty or json${seeHelp(verb)}`
+        : `--format must be pretty or json (got ${v})${seeHelp(verb)}`,
+  }
+}
+
 /** How a verb names a word it refuses: a flag, or a positional it takes no more of. */
 export function refusedWord(arg: string): string {
   return arg.startsWith('-') ? 'unknown flag' : 'unexpected argument'
@@ -339,7 +358,7 @@ export const WATCH_REFUSED_FLAGS: readonly string[] = [
  * 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
+ * prose names other verbs' flags (`vx lock --check`, `--run RUNID` under
  * `vx why`) and is not read.
  */
 export function acceptedFlags(verb: string): string[] {

package/src/cli/info.ts

@@ -5,12 +5,12 @@
 // too; this file parses the flags and renders the rows.
 
 import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
-import { flagHint, refusedWord, seeHelp } from './help.js'
+import { flagHint, formatValue, refusedWord, seeHelp } from './help.js'
 import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 import { MIN_BUN } from '../util/index.js'
 
-export interface InfoArgs {
+interface InfoArgs {
   format: 'pretty' | 'json'
   /** `--cache-dir`: report on the cache a run with the same flag uses. */
   cacheDir?: string
@@ -22,10 +22,8 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '--format' || a?.startsWith('--format=')) {
-      const v = a === '--format' ? args[++i] : a.slice('--format='.length)
-      if (v !== 'pretty' && v !== 'json') {
-        return { ...out, error: `--format must be pretty or json${seeHelp('info')}` }
-      }
+      const v = formatValue(a === '--format' ? args[++i] : a.slice('--format='.length), 'info')
+      if (typeof v === 'object') return { ...out, ...v }
       out.format = v
       continue
     }

package/src/cli/init.ts

@@ -11,7 +11,7 @@ import { mkdir, unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
-import { isUserError, UserError } from '../util/index.js'
+import { isUserError, relPosix, UserError } from '../util/index.js'
 import {
   applyMigration,
   discoverProjects,
@@ -22,7 +22,7 @@ import {
   WORKSPACE_CONFIG_FILENAMES,
 } from '../workspace/index.js'
 
-export interface InitArgs {
+interface InitArgs {
   dry: boolean
   force: boolean
   /** `vx.config.mjs` instead of `.ts` — see `ApplyMigrationArgs.format`. */
@@ -369,7 +369,7 @@ function namelessNotes(root: string, dirs: readonly string[]): string[] {
   const withScripts = dirs
     .filter((dir) => {
       const scripts = (
-        JSON.parse(readText(path.join(dir, 'package.json')) || '{}') as {
+        JSON.parse(readText(path.join(dir, 'package.json')).replace(/^\uFEFF/, '') || '{}') as {
           scripts?: unknown
         }
       ).scripts
@@ -379,7 +379,7 @@ function namelessNotes(root: string, dirs: readonly string[]): string[] {
         Object.values(scripts).some((v) => typeof v === 'string' && v !== '')
       )
     })
-    .map((dir) => path.relative(root, dir).split(path.sep).join('/'))
+    .map((dir) => relPosix(root, dir))
     .sort()
     // The root's own manifest is the empty relative path: a nameless
     // single-package repo read `not mapped:  — its package.json…` (M-54).

package/src/cli/last.ts

@@ -1,4 +1,4 @@
-// `vx last [runId]` — replay a recorded run's summary from the terminal,
+// `vx last [RUNID]` — replay a recorded run's summary from the terminal,
 // without re-executing anything. Comparison gap #12: with the dashboard's
 // run-detail page gone (the 2026-08-23 cloud removal), the local run
 // history in cache.db is the only replay surface, and this verb reads it.
@@ -7,7 +7,7 @@
 import type { Database } from 'bun:sqlite'
 import { Cache } from '../cache/index.js'
 import { formatBytes } from './format.js'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, seeHelp } from './help.js'
 import {
   exitSignal,
   getInvocation,
@@ -70,16 +70,8 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       continue
     }
     if (a === '--format' || a.startsWith('--format=')) {
-      const fv = a === '--format' ? args[++i] : a.slice(9)
-      if (fv !== 'pretty' && fv !== 'json') {
-        return {
-          ...out,
-          error:
-            fv === undefined || fv === ''
-              ? '--format requires a value (pretty | json)'
-              : `invalid --format: ${fv} (expected pretty | json)`,
-        }
-      }
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice(9), 'last')
+      if (typeof fv === 'object') return { ...out, ...fv }
       out.format = fv
       continue
     }
@@ -241,6 +233,47 @@ function hitsLine(
   return `${hits} (${inv.upToDateCount} up-to-date, ${restored} restored${layers})`
 }
 
+/**
+ * `vx last --list`'s rows, in columns: the counts vary with what a run
+ * hit and failed, so unpadded they pushed each run's duration and command
+ * to a different column and the list could not be scanned down.
+ */
+export function formatRunList(
+  runs: readonly {
+    inv: Pick<
+      InvocationDetail,
+      | 'exitOk'
+      | 'startedAt'
+      | 'taskCount'
+      | 'failedCount'
+      | 'totalDurationMs'
+      | 'command'
+      | 'hitCount'
+      | 'upToDateCount'
+      | 'restoredLocalCount'
+      | 'restoredRemoteCount'
+    >
+    id: string
+  }[],
+): string[] {
+  const rows = runs.map(({ inv, id }) => ({
+    head: `${inv.exitOk ? 'ok    ' : 'FAILED'} ${fmtWhen(inv.startedAt)}`,
+    id,
+    counts:
+      `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${hitsLine(inv)}` +
+      (inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''),
+    ms: fmtMs(inv.totalDurationMs),
+    command: inv.command,
+  }))
+  const idW = Math.max(...rows.map((r) => r.id.length))
+  const countsW = Math.max(...rows.map((r) => r.counts.length))
+  const msW = Math.max(...rows.map((r) => r.ms.length))
+  return rows.map(
+    (r) =>
+      `${r.head}  ${r.id.padEnd(idW)}  ${r.counts.padEnd(countsW)}  ${r.ms.padStart(msW)}  $ ${r.command}`,
+  )
+}
+
 export async function lastCmd(args: readonly string[]): Promise<number> {
   const parsed = parseLastArgs(args)
   if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`)
@@ -269,14 +302,10 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         )
         return 0
       }
-      for (const inv of invocations) {
-        const verdict = inv.exitOk ? 'ok    ' : 'FAILED'
-        process.stdout.write(
-          `${verdict} ${fmtWhen(inv.startedAt)}  ${shortRunId(db, inv.runId)}  ` +
-            `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${hitsLine(inv)}` +
-            `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''} · ${fmtMs(inv.totalDurationMs)}  $ ${inv.command}\n`,
-        )
-      }
+      const lines = formatRunList(
+        invocations.map((inv) => ({ inv, id: shortRunId(db, inv.runId) })),
+      )
+      process.stdout.write(`${lines.join('\n')}\n`)
       return 0
     }
 

package/src/cli/lock.ts

@@ -20,7 +20,7 @@ import {
   type ProjectMeta,
 } from '../workspace/index.js'
 
-export interface LockArgs {
+interface LockArgs {
   check: boolean
   error?: string
 }
@@ -99,7 +99,7 @@ async function writeLock(root: string, metas: ConfiguredMeta[], bare: number): P
   await writeLockfile(root, lock)
   const n = metas.length
   process.stdout.write(
-    `vx: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}\n`,
+    `vx lock: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}\n`,
   )
   return 0
 }
@@ -199,6 +199,6 @@ async function checkLock(root: string, metas: ConfiguredMeta[], bare: number): P
   const n = metas.length
   const audited = `${n} project${n === 1 ? '' : 's'}`
   const skipped = bare === 0 ? '' : `; ${bare} without a vx.config not audited`
-  process.stdout.write(`vx: lock is up to date (${audited}${skipped})\n`)
+  process.stdout.write(`vx lock --check: up to date (${audited}${skipped})\n`)
   return 0
 }

package/src/cli/plan-format.ts

@@ -29,6 +29,7 @@ export function formatPlanText(plan: RunPlan): string {
   let miss = 0
   let nocache = 0
   let noop = 0
+  let idle = 0
   for (const t of real) {
     // `@noop`: the run succeeds it without running, whatever its key says.
     const skipped = t.executor === 'noop'
@@ -56,6 +57,7 @@ export function formatPlanText(plan: RunPlan): string {
     else if (t.cacheStatus === 'hit-remote') remote++
     else if (t.cacheStatus === 'miss') miss++
     else if (t.cacheStatus === 'no-cache') nocache++
+    else if (t.cacheStatus === 'not-started') idle++
   }
 
   const hitParts: string[] = []
@@ -67,6 +69,7 @@ export function formatPlanText(plan: RunPlan): string {
   if (miss > 0) summary.push(`${miss} would run`)
   if (nocache > 0) summary.push(`${nocache} no-cache`)
   if (noop > 0) summary.push(`${noop} noop`)
+  if (idle > 0) summary.push(`${idle} not started`)
   lines.push('')
   lines.push(summary.join(', ') + '.')
 
@@ -199,6 +202,8 @@ function symbolFor(s: CacheStatus): string {
       return '·'
     case 'group':
       return '○'
+    case 'not-started':
+      return '−'
   }
 }
 
@@ -214,6 +219,8 @@ function describe(s: CacheStatus): string {
       return 'no-cache (would exec)'
     case 'group':
       return 'group task'
+    case 'not-started':
+      return 'not started (unneeded)'
   }
 }
 
@@ -229,5 +236,7 @@ function dotColor(s: CacheStatus): string {
       return '#e5e7eb' // gray-200
     case 'group':
       return '#f5d0fe' // fuchsia-200
+    case 'not-started':
+      return '#ffffff'
   }
 }