@vzn/vx 0.0.16 → 0.0.21

package/src/cli/index.ts

@@ -4,25 +4,36 @@
 
 import { VERSION } from '../version.js'
 import { runCmd } from './run.js'
-import { watchCmd } from './watch.js'
-import { cacheCmd } from './cache.js'
-import { lockCmd } from './lock.js'
-import { migrateCmd } from './migrate.js'
-import { upgradeCmd } from './upgrade.js'
-import { showCmd } from './show.js'
-import { infoCmd } from './info.js'
-import { mcpCmd } from './mcp.js'
-import { printHelp } from './help.js'
+import { CORE_VERBS, printHelp } from './help.js'
+import { pluginCommandHelp, resolvePluginCommand, pluginVerbs } from './plugin-commands.js'
+import { MOVED_VERBS, nearest, UserError } from '../util/index.js'
+
+// Every verb but `run` is imported when invoked. `vx run` is the hot path
+// and nearly every invocation; the other verbs' modules are code that
+// process never calls. Measured 2026-09-03: `--version` is 25 ms either
+// way (module loading is not where start-up goes), so this is hygiene, not
+// a speed-up. The specifiers are string literals, so `bun build --compile`
+// still embeds them.
 
 export async function run(argv: readonly string[]): Promise<number> {
   const [command, ...rest] = argv
 
+  // `vx <verb> --help` is the universal reflex, and every verb answered
+  // `unknown flag: --help` and exited 1 (walkthrough, 2026-09-04). Only args
+  // BEFORE a `--` count: `vx run build -- --help` forwards it to the task,
+  // which is the one place `--help` is not being asked of vx. Core verbs
+  // only — a plugin verb owns its own arguments, `--help` included.
+  if (command !== undefined && wantsHelp(command, rest)) {
+    printHelp(await pluginCommandHelp(), command)
+    return 0
+  }
+
   switch (command) {
     case undefined:
     case '--help':
     case '-h':
     case 'help':
-      printHelp()
+      printHelp(await pluginCommandHelp())
       return 0
     case '--version':
     case 'version':
@@ -31,55 +42,114 @@ export async function run(argv: readonly string[]): Promise<number> {
     case 'run':
       return await runCmd(rest)
     case 'watch':
-      return await watchCmd(rest)
+      return await (await import('./watch.js')).watchCmd(rest)
     case 'cache':
-      return await cacheCmd(rest)
+      return await (await import('./cache.js')).cacheCmd(rest)
     case 'lock':
-      return await lockCmd(rest)
-    case 'migrate':
-      return await migrateCmd(rest)
+      return await (await import('./lock.js')).lockCmd(rest)
+    case 'init':
+      return await (await import('./init.js')).initCmd(rest)
     case 'upgrade':
-      return await upgradeCmd(rest)
+      return await (await import('./upgrade.js')).upgradeCmd(rest)
     case 'show':
-      return await showCmd(rest)
+      return await (await import('./show.js')).showCmd(rest)
     case 'info':
     case 'stats': // deprecated alias — `vx info` absorbed `vx stats`
-      return await infoCmd(rest)
-    case 'mcp':
-      return await mcpCmd(rest)
-    case 'serve':
-    case 'dev':
-      // vx core is only a task runner — it has no service layer of its own.
-      // A dashboard, remote cache, distributed execution, etc. are provided
-      // by PLUGINS (declared in vx.workspace.ts), never by core. We keep this
-      // neutral hint for the common muscle-memory verbs, but core names no
-      // specific plugin package: any package can provide these.
-      process.stderr.write(
-        `vx: '${command}' is not a vx core command.\n` +
-          `  vx core runs tasks in-process. A dashboard, remote cache, and\n` +
-          `  distributed execution come from plugins — not core. See the plugin\n` +
-          `  guide: https://vznjs.github.io/vx/guides/plugins/\n`,
-      )
-      return 1
-    default:
-      process.stderr.write(`vx: unknown command: ${command}\n`)
+      return await (await import('./info.js')).infoCmd(rest)
+    case 'why':
+      return await (await import('./why.js')).whyCmd(rest)
+    case 'last':
+      return await (await import('./last.js')).lastCmd(rest)
+    case 'completions':
+      return await (await import('./completions.js')).completionsCmd(rest, await pluginVerbs())
+    default: {
+      // Not a core verb: a plugin declared in the workspace around the cwd
+      // may own it (`VxPlugin.commands`). Core verbs were matched above, so
+      // nothing here can shadow them.
+      const resolved = await resolvePluginCommand(command)
+      if (resolved !== null && !('loadError' in resolved)) {
+        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)) {
+          throw new UserError(
+            `plugin '${resolved.plugin.name}': command '${command}' resolved ${JSON.stringify(code)} instead of an exit code`,
+          )
+        }
+        return code
+      }
+      // A broken workspace file cannot say whether the verb exists. Say
+      // both things: the verb is unknown HERE, and why the lookup could not
+      // finish — a typo still reads as a typo, and a real plugin verb still
+      // points at the file that broke it.
+      const loadNote =
+        resolved !== null && 'loadError' in resolved
+          ? `\n  (plugin verbs could not be looked up: vx.workspace failed to load: ${resolved.loadError})`
+          : ''
+      // A verb core owned once (`migrate`, `prune`) and a package owns now:
+      // the pointer, but only after the plugins had their chance — a
+      // workspace that declares a plugin verb of that name keeps it.
+      const moved = MOVED_VERBS[command]
+      if (moved !== undefined) {
+        process.stderr.write(`${moved}${loadNote}\n`)
+        return 1
+      }
+      if (command === 'serve' || command === 'dev') {
+        // vx core is only a task runner — it has no service layer of its
+        // own. A dashboard, remote cache, distributed execution, etc. are
+        // provided by PLUGINS (declared in vx.workspace.ts), never by core.
+        // We keep this neutral hint for the common muscle-memory verbs, but
+        // core names no specific plugin package: any package can provide
+        // these.
+        process.stderr.write(
+          `vx: '${command}' is not a vx core command.\n` +
+            `  vx core runs tasks in-process. A dashboard, remote cache, and\n` +
+            `  distributed execution come from plugins — not core. See the plugin\n` +
+            `  guide: https://vznjs.github.io/vx/guides/plugins/\n`,
+        )
+        return 1
+      }
+      process.stderr.write(`vx: unknown command: ${command}${didYouMeanVerb(command)}${loadNote}\n`)
       printHelp()
       return 1
+    }
   }
 }
 
 // Re-exports for tests + programmatic embedders.
-export { detectFlow, parseRunArgs, type RunArgs } from './run.js'
+export {
+  detectFlow,
+  parseConcurrency,
+  parseRunArgs,
+  resolveRunOptions,
+  type RunArgs,
+} from './run.js'
 export { parsePruneArgs, parseDuration, parseSize } from './cache.js'
 export { parseLockArgs, type LockArgs } from './lock.js'
-export { parseMigrateArgs, type MigrateArgs } from './migrate.js'
+export { parseInitArgs, type InitArgs } from './init.js'
 export { parseShowArgs, type ShowArgs } from './show.js'
-export { parseMcpArgs, type McpArgs } from './mcp.js'
-export {
-  handleMcpRequest,
-  listMcpTools,
-  setMcpContext,
-  type McpContext,
-  type McpToolDef,
-} from './mcp-rpc.js'
+export { parseWhyArgs } from './why.js'
+export { parseLastArgs } from './last.js'
 export { formatBytes } from './format.js'
+export { registerCoreAlias } from './core-alias.js'
+
+/**
+ * Is this invocation asking for help rather than work? See the call site for
+ * why the scan stops at `--`, and why plugin verbs are excluded.
+ */
+function wantsHelp(command: string, rest: readonly string[]): boolean {
+  if (!(CORE_VERBS as readonly string[]).includes(command)) return false
+  const sep = rest.indexOf('--')
+  const own = sep === -1 ? rest : rest.slice(0, sep)
+  return own.includes('--help') || own.includes('-h')
+}
+
+/** ` Did you mean run?` for a verb within two edits of a core one — the same
+ *  hint a task or flag typo gets. Plugin verbs are not listed: resolving
+ *  them loads the workspace, and this path is reached only when that
+ *  lookup found nothing. */
+function didYouMeanVerb(verb: string): string {
+  const best = nearest(verb, CORE_VERBS)
+  return best === undefined ? '' : `. Did you mean ${best}?`
+}

package/src/cli/info.ts

@@ -1,80 +1,139 @@
 // `vx info` — workspace doctor printout. One screen of environment +
 // workspace + cache facts for bug reports and quick sanity checks.
-// `vx stats` is a deprecated alias (info absorbed it).
+// `vx stats` is a deprecated alias (info absorbed it). The facts come
+// from the orchestrator's `collectInfo` (doctor.ts), which `vx mcp` reads
+// too; this file parses the flags and renders the rows.
 
-import { Cache } from '../cache/index.js'
-import { VERSION } from '../version.js'
-import {
-  findWorkspaceRoot,
-  listProjects,
-  loadProjectConfig,
-  loadWorkspace,
-  loadWorkspaceConfig,
-  lockfilePath,
-  resolveCacheDir,
-} from '../workspace/index.js'
+import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
+import { seeHelp } from './help.js'
+import { parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 
-export async function infoCmd(args: readonly string[]): Promise<number> {
-  if (args.length > 0) {
-    process.stderr.write(`vx info: unknown argument: ${args[0]}\n`)
-    return 1
-  }
-  const root = await findWorkspaceRoot(process.cwd())
-  const metas = await listProjects(await loadWorkspace(root))
+export interface InfoArgs {
+  format: 'pretty' | 'json'
+  /** `--cache-dir`: report on the cache a run with the same flag uses. */
+  cacheDir?: string
+  error?: string
+}
 
-  let taskCount = 0
-  await Promise.all(
-    metas.map(async (meta) => {
-      if (meta.configPath === null) return
-      // A broken config must not take the doctor down with it — it
-      // just contributes zero tasks to the count.
-      try {
-        const config = await loadProjectConfig(meta.configPath)
-        taskCount += Object.keys(config.tasks ?? {}).length
-      } catch {
-        // counted as zero
+export function parseInfoArgs(args: readonly string[]): InfoArgs {
+  const out: InfoArgs = { format: 'pretty' }
+  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 cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
-  const cache = new Cache(cacheDir)
-  let stats
-  try {
-    stats = cache.stats()
-  } finally {
-    cache.close()
+      out.format = v
+      continue
+    }
+    const cd = parseCacheDirFlag(args, i)
+    if (cd !== null) {
+      if ('error' in cd) return { ...out, error: cd.error }
+      out.cacheDir = cd.cacheDir
+      i = cd.next
+      continue
+    }
+    return { ...out, error: `unknown argument: ${a}${seeHelp('info')}` }
   }
+  return out
+}
 
-  const lockPresent = await Bun.file(lockfilePath(root)).exists()
+export async function infoCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseInfoArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx info: ${parsed.error}\n`)
+    return 1
+  }
+  const facts = await collectInfo(process.cwd(), {
+    ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+    warn: warnToStderr,
+  })
+  process.stdout.write(
+    parsed.format === 'json' ? `${JSON.stringify(facts, null, 2)}\n` : `${renderInfo(facts)}\n`,
+  )
+  return 0
+}
 
+export function renderInfo(f: InfoFacts): string {
   const rows: [string, string][] = [
-    ['vx', VERSION],
-    ['bun', Bun.version],
-    ['git', gitVersion()],
-    ['workspace root', root],
-    ['projects', `${metas.length} (${taskCount} task${taskCount === 1 ? '' : 's'})`],
-    ['cache dir', cacheDir],
-    ['cache entries', `${stats.entryCount} (${formatBytes(stats.totalBytes)})`],
-    ['runs (24h)', `${stats.runCountLast24h} (${stats.hitCountLast24h} cache hits)`],
-    ['vx-lock.json', lockPresent ? 'yes' : 'no'],
+    ['vx', f.vx],
+    ['bun', f.bun],
+    ['git', f.git ?? '(not found)'],
+    ['git status cache', renderGitStatusCache(f.gitStatusCache)],
+    ['workspace root', f.workspaceRoot],
+    ['projects', `${f.projects} (${f.tasks} task${f.tasks === 1 ? '' : 's'})`],
+    ['plugins', describePlugins(f.plugins)],
+    ['workers', describeWorkers(f.workers)],
+    ['memory', describeMemory(f.memory)],
+    ['cache dir', f.cacheDir],
+    ['cache versions', `keys ${f.cacheVersion} · index schema ${f.schemaVersion}`],
+    ['cache entries', `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`],
+    // Only when there is something to say.
+    ...(f.orphans.artifacts > 0
+      ? ([
+          [
+            'orphans',
+            `${f.orphans.artifacts} artifact${f.orphans.artifacts === 1 ? '' : 's'} (${formatBytes(f.orphans.bytes)}) the index does not know — \`vx cache prune\` reaps them`,
+          ],
+        ] as [string, string][])
+      : []),
+    ['runs (24h)', `${f.runs24h} (${f.hits24h} cache hits)`],
+    ['flaky tasks', describeFlakyTasks(f.flakyTasks)],
+    ['vx-lock.json', f.lockfile ? 'yes' : 'no'],
   ]
   const labelW = Math.max(...rows.map(([label]) => label.length))
-  const lines = rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`)
-  process.stdout.write(`${lines.join('\n')}\n`)
-  return 0
+  return rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`).join('\n')
 }
 
-function gitVersion(): string {
-  try {
-    const p = Bun.spawnSync({ cmd: ['git', '--version'], stdout: 'pipe', stderr: 'pipe' })
-    if (p.exitCode !== 0) return '(not found)'
-    return new TextDecoder()
-      .decode(p.stdout)
-      .trim()
-      .replace(/^git version /, '')
-  } catch {
-    return '(not found)'
+/** `4 — the CPU count`, `2 — cgroup CPU quota 2 of 8 cores`, `8 — vx.workspace.ts (4 cores)`. */
+export function describeWorkers(w: InfoFacts['workers']): string {
+  const quota = w.cpuQuota === null ? '' : `, cgroup CPU quota ${trimCores(w.cpuQuota)}`
+  if (w.source === 'workspace') return `${w.count} — vx.workspace.ts (${w.cores} cores${quota})`
+  if (w.source === 'cgroup')
+    return `${w.count} — cgroup CPU quota ${trimCores(w.cpuQuota ?? w.count)} of ${w.cores} cores`
+  return `${w.count} — the CPU count${quota}`
+}
+
+/** `13 GB usable — cgroup limit; the machine has 16 GB`, or `16 GB`. */
+export function describeMemory(m: InfoFacts['memory']): string {
+  if (m.cgroupLimitBytes !== null && m.usableBytes < m.totalBytes) {
+    return `${formatBytes(m.usableBytes)} usable — cgroup limit; the machine has ${formatBytes(m.totalBytes)}`
   }
+  return formatBytes(m.totalBytes)
+}
+
+function trimCores(n: number): string {
+  return Number.isInteger(n) ? String(n) : n.toFixed(2).replace(/0+$/, '')
+}
+
+/** `2 — app#test (3 of 7 runs failed on unchanged inputs); api#e2e (1 of 4)`, or `none`. */
+export function describeFlakyTasks(tasks: readonly FlakyTask[]): string {
+  if (tasks.length === 0) return 'none'
+  const parts = tasks.map(
+    (t, i) =>
+      `${t.taskId} (${t.failures} of ${t.passes + t.failures} runs failed${i === 0 ? ' on unchanged inputs' : ''})`,
+  )
+  return `${tasks.length} — ${parts.join('; ')}`
+}
+
+export function describePlugins(
+  plugins: ReadonlyArray<{ name: string; seams: readonly string[] }>,
+): string {
+  if (plugins.length === 0) return 'none'
+  const parts = plugins.map(
+    (p) => `${p.name} (${p.seams.length === 0 ? 'no seams' : p.seams.join(', ')})`,
+  )
+  return `${plugins.length} — ${parts.join('; ')}`
+}
+
+function renderGitStatusCache(c: InfoFacts['gitStatusCache']): string {
+  if (c === null) return '(unknown)'
+  if (c.fsmonitor && c.untrackedCache) return 'fsmonitor + untrackedCache on'
+  const missing = [
+    ...(c.fsmonitor ? [] : ['core.fsmonitor']),
+    ...(c.untrackedCache ? [] : ['core.untrackedCache']),
+  ]
+  return `${missing.join(', ')} off`
 }

package/src/cli/init.ts

@@ -0,0 +1,75 @@
+// `vx init [--dry] [--force] [--mjs]` — a workspace from nowhere: one vx.config.ts
+// per package from its package.json scripts, and the workspace file every
+// run needs. Turbo and Nx are not read here; a runner's own config beside
+// the scripts is the richer source, and `@vzn/vx-migrate` maps it.
+
+import path from 'node:path'
+import { seeHelp } from './help.js'
+import {
+  applyMigration,
+  findWorkspaceRoot,
+  listProjects,
+  loadWorkspace,
+  migrateScripts,
+} from '../workspace/index.js'
+
+export interface InitArgs {
+  dry: boolean
+  force: boolean
+  /** `vx.config.mjs` instead of `.ts` — see `ApplyMigrationArgs.format`. */
+  mjs: boolean
+  error?: string
+}
+
+export function parseInitArgs(args: readonly string[]): InitArgs {
+  const out: InitArgs = { dry: false, force: false, mjs: false }
+  for (const a of args) {
+    if (a === '--dry') out.dry = true
+    else if (a === '--force') out.force = true
+    else if (a === '--mjs') out.mjs = true
+    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('init')}` }
+    else return { ...out, error: `unexpected argument: ${a}` }
+  }
+  return out
+}
+
+export async function initCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseInitArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx init: ${parsed.error}\n`)
+    return 1
+  }
+  const root = await findWorkspaceRoot(process.cwd())
+  const metas = await listProjects(await loadWorkspace(root))
+  // `init` reads scripts only; a runner's own config beside them is the
+  // richer source (dependsOn, inputs, outputs) and was ignored without a
+  // word — the walkthrough on a Turbo repo (2026-09-09) got the scripts'
+  // TODOs and none of the edges turbo.json already declared.
+  const notes: string[] = []
+  if (await Bun.file(path.join(root, 'turbo.json')).exists()) {
+    notes.push(
+      'turbo.json found and not read — `bunx @vzn/vx-migrate` maps it (dependsOn, inputs, ' +
+        'outputs), or `plugins: [turbo()]` from @vzn/vx-migrate runs it with nothing written',
+    )
+  } else if (
+    (await Bun.file(path.join(root, 'nx.json')).exists()) ||
+    (await Bun.file(path.join(root, '.nx', 'workspace-data', 'project-graph.json')).exists())
+  ) {
+    notes.push(
+      'an Nx workspace found and not read — `bunx @vzn/vx-migrate --from nx` maps its ' +
+        'exported project graph',
+    )
+  }
+  return applyMigration({
+    root,
+    metas,
+    plan: migrateScripts(metas),
+    source: 'package.json scripts',
+    verb: 'vx init',
+    dry: parsed.dry,
+    force: parsed.force,
+    init: true,
+    notes,
+    format: parsed.mjs ? 'mjs' : 'ts',
+  })
+}

package/src/cli/last.ts

@@ -0,0 +1,172 @@
+// `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.
+// Read-only — no config evaluation, no re-hash, no cache probe.
+
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { formatBytes } from './format.js'
+import { seeHelp } from './help.js'
+import { getInvocation, getRun, listInvocations } from '../orchestrator/index.js'
+import { UserError } from '../util/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
+import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
+
+interface LastArgs {
+  runId?: string
+  list?: number
+  format: 'pretty' | 'json'
+  /** `--cache-dir`: read the history a run with the same flag wrote. */
+  cacheDir?: string
+  error?: string
+}
+
+export function parseLastArgs(args: readonly string[]): LastArgs {
+  const out: LastArgs = { format: 'pretty' }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (a === '--list' || a.startsWith('--list=')) {
+      const lv = a === '--list' ? '10' : a.slice(7)
+      const n = Number(lv)
+      if (!Number.isInteger(n) || n < 1 || n > 500) {
+        return { ...out, error: `invalid --list: ${lv} (expected 1..500)` }
+      }
+      out.list = n
+      continue
+    }
+    if (a === '--format' || a.startsWith('--format=')) {
+      const fv = a === '--format' ? args[++i] : a.slice(9)
+      if (fv !== 'pretty' && fv !== 'json') {
+        return { ...out, error: `invalid --format: ${fv ?? ''} (expected pretty | json)` }
+      }
+      out.format = fv
+      continue
+    }
+    const cd = parseCacheDirFlag(args, i)
+    if (cd !== null) {
+      if ('error' in cd) return { ...out, error: cd.error }
+      out.cacheDir = cd.cacheDir
+      i = cd.next
+      continue
+    }
+    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('last')}` }
+    if (out.runId !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    out.runId = a
+  }
+  return out
+}
+
+const fmtWhen = (ms: number): string => new Date(ms).toISOString()
+
+function fmtMs(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  if (ms < 60_000) return `${(ms / 1000).toFixed(2)}s`
+  const m = Math.floor(ms / 60_000)
+  return `${m}m ${Math.round((ms - m * 60_000) / 1000)}s`
+}
+
+/**
+ * What an executed task used — its peak RSS and its CPU parallelism (CPU
+ * time over wall time) — as the runner recorded them. This is the number
+ * `@vzn/vx-schedule-history` reserves from, so the replay shows it where
+ * a developer can read it; a hit spent nothing and shows nothing.
+ */
+function fmtUsage(t: {
+  cpuMs: number | null
+  peakRssBytes: number | null
+  durationMs: number
+}): string {
+  const parts: string[] = []
+  if (t.peakRssBytes !== null) parts.push(formatBytes(t.peakRssBytes))
+  if (t.cpuMs !== null && t.durationMs > 0)
+    parts.push(`${(t.cpuMs / t.durationMs).toFixed(1)}× cpu`)
+  return parts.length > 0 ? `  ${parts.join(' · ')}` : ''
+}
+
+export async function lastCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseLastArgs(args)
+  if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`)
+
+  const root = await findWorkspaceRoot(process.cwd())
+  const cache = new Cache(await cliCacheDir(root, parsed.cacheDir))
+  noteSchemaReset(cache, warnToStderr)
+  try {
+    const db = cache.dbHandle()
+
+    if (parsed.list !== undefined) {
+      const invocations = listInvocations(db, { limit: parsed.list })
+      if (parsed.format === 'json') {
+        process.stdout.write(`${JSON.stringify(invocations)}\n`)
+        return 0
+      }
+      if (invocations.length === 0) {
+        process.stdout.write('no recorded runs\n')
+        return 0
+      }
+      for (const inv of invocations) {
+        const verdict = inv.exitOk ? 'ok    ' : 'FAILED'
+        process.stdout.write(
+          `${verdict} ${fmtWhen(inv.startedAt)}  ${inv.runId}  ` +
+            `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${inv.hitCount} hit${inv.hitCount === 1 ? '' : 's'}` +
+            `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''} · ${fmtMs(inv.totalDurationMs)}  $ ${inv.command}\n`,
+        )
+      }
+      return 0
+    }
+
+    const inv =
+      parsed.runId !== undefined
+        ? getInvocation(db, parsed.runId)
+        : (listInvocations(db, { limit: 1 })[0] ?? null)
+    if (inv === null || inv === undefined) {
+      throw new UserError(
+        parsed.runId !== undefined
+          ? `vx last: no recorded run ${parsed.runId} (vx last --list shows recent runs)`
+          : 'vx last: no recorded runs yet — run something first',
+      )
+    }
+    const detail = getRun(db, inv.runId)
+
+    if (parsed.format === 'json') {
+      process.stdout.write(`${JSON.stringify({ invocation: inv, tasks: detail?.tasks ?? [] })}\n`)
+      return 0
+    }
+
+    const lines: string[] = []
+    lines.push(`run ${inv.runId} — ${inv.exitOk ? 'ok' : 'FAILED'}`)
+    lines.push(`  $ ${inv.command}`)
+    lines.push(
+      `  ${fmtWhen(inv.startedAt)} · ${fmtMs(inv.totalDurationMs)}` +
+        `${inv.branch !== null ? ` · ${inv.branch}` : ''}` +
+        `${inv.commitSha !== null ? ` @ ${inv.commitSha.slice(0, 8)}${inv.dirty === true ? '+dirty' : ''}` : ''}` +
+        `${inv.ci ? ` · CI${inv.ciProvider !== null ? ` (${inv.ciProvider})` : ''}` : ''}`,
+    )
+    lines.push(
+      `  ${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${inv.hitCount} hit${inv.hitCount === 1 ? '' : 's'}` +
+        ` (${inv.hitLocalCount} local, ${inv.hitRemoteCount} remote)` +
+        `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''}`,
+    )
+    const tasks = detail?.tasks ?? []
+    if (tasks.length > 0) {
+      lines.push('')
+      const failedFirst = [
+        ...tasks.filter((t) => t.status === 'failed'),
+        ...tasks.filter((t) => t.status !== 'failed'),
+      ]
+      const idW = Math.max(...tasks.map((t) => `${t.project}#${t.task}`.length), 4)
+      for (const t of failedFirst) {
+        const id = `${t.project}#${t.task}`
+        // The terminal summary's own word for a task that runs every time
+        // by design; a reader must not take its row for a miss.
+        lines.push(
+          `  ${t.status.padEnd(17)} ${id.padEnd(idW)}  ${fmtMs(t.durationMs).padStart(8)}` +
+            `${t.hash !== '' ? `  ${t.hash}` : ''}${t.cached === false ? '  no-cache' : ''}${fmtUsage(t)}`,
+        )
+      }
+    }
+    process.stdout.write(`${lines.join('\n')}\n`)
+    return 0
+  } finally {
+    cache.close()
+  }
+}

package/src/cli/lock.ts

@@ -3,6 +3,7 @@
 // current environment. Design: docs/design/config-lock-2026-06.md.
 
 import type { ProjectConfig } from '../config.js'
+import { seeHelp } from './help.js'
 import { relPosix, xxh3hex } from '../util/index.js'
 import {
   findWorkspaceRoot,
@@ -27,7 +28,7 @@ export function parseLockArgs(args: readonly string[]): LockArgs {
   const out: LockArgs = { check: false }
   for (const a of args) {
     if (a === '--check') out.check = true
-    else return { check: false, error: `unknown argument: ${a}` }
+    else return { check: false, error: `unknown argument: ${a}${seeHelp('lock')}` }
   }
   return out
 }