@vzn/vx 0.0.631 → 0.0.632

package/src/cache/tar-stream.ts

@@ -187,30 +187,45 @@ class Source {
   }
 }
 
+/** What one header block means, decided by `TarDecoder.header`. */
+type HeaderStep =
+  /** A zero block: the first half of the end marker. */
+  | { kind: 'zero' }
+  /** The second zero block in a row: the archive is over. */
+  | { kind: 'end' }
+  /** An extended header (`x`, `L`) or a global one (`g`); its padded body follows. */
+  | { kind: 'extended'; type: 'x' | 'L' | 'g'; size: number; padded: number }
+  /** An entry; its padded body follows. */
+  | { kind: 'entry'; name: string; size: number; type: string; mtimeMs: number; padded: number }
+
+const ZERO: HeaderStep = { kind: 'zero' }
+const END: HeaderStep = { kind: 'end' }
+
 /**
- * Iterate a tar stream entry by entry. Each entry's `body` MUST be fully
- * consumed (or the iterator drains it) before the next entry is read.
+ * The dialect, decoded off whole blocks with no I/O: the one copy of the
+ * header rules both readers run — `tarEntries` over a stream (restore,
+ * ingest) and `tarEntriesSync` over a tar in memory (a save's own) — so
+ * a name a save indexes is the name a restore reads.
  */
-export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGenerator<TarEntry> {
-  const src = new Source(stream[Symbol.asyncIterator]())
-  let pendingPath: string | undefined
-  let pendingSize: number | undefined
-  let zeroBlocks = 0
-  for (;;) {
-    const h = await src.exact(BLOCK, 'a header')
-    if (h === null) {
-      if (zeroBlocks === 0) throw new TarFormatError('archive has no end-of-archive marker')
-      return
-    }
+class TarDecoder {
+  private pendingPath: string | undefined
+  private pendingSize: number | undefined
+  private zeroBlocks = 0
+
+  /** The bytes ended at a header boundary: clean only after a zero block. */
+  eof(): void {
+    if (this.zeroBlocks === 0) throw new TarFormatError('archive has no end-of-archive marker')
+  }
+
+  header(h: Uint8Array): HeaderStep {
     if (isZeroBlock(h)) {
-      zeroBlocks++
-      if (zeroBlocks >= 2) return
-      continue
+      this.zeroBlocks++
+      return this.zeroBlocks >= 2 ? END : ZERO
     }
-    zeroBlocks = 0
+    this.zeroBlocks = 0
     if (!checksumOk(h)) throw new TarFormatError('header checksum mismatch')
     const type = h[156] === 0 ? '0' : String.fromCharCode(h[156]!)
-    const size = pendingSize ?? octal(h, 124, 12)
+    const size = this.pendingSize ?? octal(h, 124, 12)
     const mtimeMs = octal(h, 136, 12) * 1000
     const padded = Math.ceil(size / BLOCK) * BLOCK
     // POSIX `ustar\0` only: old GNU's `ustar  ` keeps atime and ctime at
@@ -218,44 +233,67 @@ export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGene
     // `<atime>…/<name>`.
     const prefix = field(h, 257, 6) === 'ustar' ? field(h, 345, 155) : ''
     const rawName = field(h, 0, 100)
-    let name = pendingPath ?? (prefix ? `${prefix}/${rawName}` : rawName)
-    pendingPath = undefined
-    pendingSize = undefined
-
-    if ((type === 'x' || type === 'L' || type === 'g') && size > MAX_EXTENDED_HEADER) {
-      throw new TarFormatError(
-        `extended header of ${size} bytes, past ${MAX_EXTENDED_HEADER} (a hostile archive?)`,
-      )
+    const name = this.pendingPath ?? (prefix ? `${prefix}/${rawName}` : rawName)
+    this.pendingPath = undefined
+    this.pendingSize = undefined
+    if (type === 'x' || type === 'L' || type === 'g') {
+      if (size > MAX_EXTENDED_HEADER) {
+        throw new TarFormatError(
+          `extended header of ${size} bytes, past ${MAX_EXTENDED_HEADER} (a hostile archive?)`,
+        )
+      }
+      return { kind: 'extended', type, size, padded }
     }
-    if (type === 'x' || type === 'L') {
-      // Extended header: applies to the NEXT entry only.
-      const body = await src.exact(padded, 'an extended header')
-      if (body === null) throw new TarFormatError('archive ends inside an extended header')
-      if (type === 'x') {
-        const pax = parsePax(body.subarray(0, size))
-        const p = pax.get('path')
-        if (p !== undefined) pendingPath = p
-        const s = pax.get('size')
-        if (s !== undefined) {
-          // Digits only: `Number` reads `0.5` and `-1`, and a fractional
-          // size moved the reader to a fractional offset.
-          if (!/^[0-9]+$/.test(s) || !Number.isSafeInteger(Number(s))) {
-            throw new TarFormatError(`bad pax size: ${JSON.stringify(s)}`)
-          }
-          pendingSize = Number(s)
-        }
-      } else {
-        pendingPath = field(body, 0, size)
+    const trimmed = name.replace(/\/+$/, type === '5' ? '/' : '')
+    return { kind: 'entry', name: trimmed, size, type, mtimeMs, padded }
+  }
+
+  /** An `x` or `L` header's padded body: it applies to the NEXT entry only. */
+  extended(type: 'x' | 'L', body: Uint8Array, size: number): void {
+    if (type === 'L') {
+      this.pendingPath = field(body, 0, size)
+      return
+    }
+    const pax = parsePax(body.subarray(0, size))
+    const p = pax.get('path')
+    if (p !== undefined) this.pendingPath = p
+    const s = pax.get('size')
+    if (s !== undefined) {
+      // Digits only: `Number` reads `0.5` and `-1`, and a fractional
+      // size moved the reader to a fractional offset.
+      if (!/^[0-9]+$/.test(s) || !Number.isSafeInteger(Number(s))) {
+        throw new TarFormatError(`bad pax size: ${JSON.stringify(s)}`)
       }
-      continue
+      this.pendingSize = Number(s)
     }
-    if (type === 'g') {
-      // pax global header: not used by Bun.Archive; skip its body.
-      await src.exact(padded, 'a global header')
+  }
+}
+
+const extendedWhat = (type: 'x' | 'L' | 'g'): string =>
+  type === 'g' ? 'a global header' : 'an extended header'
+
+/**
+ * Iterate a tar stream entry by entry. Each entry's `body` MUST be fully
+ * consumed (or the iterator drains it) before the next entry is read.
+ */
+export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGenerator<TarEntry> {
+  const src = new Source(stream[Symbol.asyncIterator]())
+  const tar = new TarDecoder()
+  for (;;) {
+    const h = await src.exact(BLOCK, 'a header')
+    if (h === null) return tar.eof()
+    const step = tar.header(h)
+    if (step.kind === 'end') return
+    if (step.kind === 'zero') continue
+    if (step.kind === 'extended') {
+      const body = await src.exact(step.padded, extendedWhat(step.type))
+      // pax global header: not used by Bun.Archive; its body is skipped.
+      if (step.type === 'g') continue
+      if (body === null) throw new TarFormatError('archive ends inside an extended header')
+      tar.extended(step.type, body, step.size)
       continue
     }
-    name = name.replace(/\/+$/, type === '5' ? '/' : '')
-
+    const { name, size, padded } = step
     let drained = false
     const body = (async function* (): AsyncIterable<Uint8Array> {
       if (size > 0) for await (const c of src.take(size, `entry ${name}`)) yield c
@@ -265,7 +303,7 @@ export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGene
       }
       drained = true
     })()
-    yield { name, size, type, mtimeMs, body }
+    yield { name, size, type: step.type, mtimeMs: step.mtimeMs, body }
     if (!drained) {
       // The caller skipped this body: drain it so the next header lines up.
       for await (const _ of body) {
@@ -275,6 +313,77 @@ export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGene
   }
 }
 
+/** One entry of a tar in memory. `body()` is a view, checked against the tar's end when asked for. */
+interface TarBytesEntry {
+  name: string
+  size: number
+  type: string
+  mtimeMs: number
+  body(): Uint8Array
+}
+
+/**
+ * `tarEntries` over a tar already in memory, synchronously, through the
+ * same decoder. A body is checked against the tar's end when it is read,
+ * as the stream reader checks it when it is drained, so the two refuse
+ * a damaged archive with the same class at the same point.
+ */
+export function* tarEntriesSync(tar: Uint8Array): Generator<TarBytesEntry> {
+  const dec = new TarDecoder()
+  const len = tar.byteLength
+  let off = 0
+  for (;;) {
+    if (off === len) return dec.eof()
+    if (len - off < BLOCK) {
+      throw new TarFormatError(`archive ends inside a header (${len - off} of ${BLOCK} bytes)`)
+    }
+    const step = dec.header(tar.subarray(off, off + BLOCK))
+    off += BLOCK
+    if (step.kind === 'end') return
+    if (step.kind === 'zero') continue
+    if (step.kind === 'extended') {
+      const left = len - off
+      if (left < step.padded) {
+        if (left > 0) {
+          throw new TarFormatError(
+            `archive ends inside ${extendedWhat(step.type)} (${left} of ${step.padded} bytes)`,
+          )
+        }
+        // At the very end a global header's body is skipped as absent, and
+        // the end marker it lacks is what refuses the archive.
+        if (step.type === 'g') continue
+        throw new TarFormatError('archive ends inside an extended header')
+      }
+      if (step.type !== 'g')
+        dec.extended(step.type, tar.subarray(off, off + step.padded), step.size)
+      off += step.padded
+      continue
+    }
+    const { name, size, padded } = step
+    const at = off
+    // The stream reader's messages, word for word: the parity rows compare them.
+    const body = (): Uint8Array => {
+      const left = len - at
+      if (left < size) {
+        throw new TarFormatError(`archive ends inside entry ${name} (${left} of ${size} bytes)`)
+      }
+      if (left < padded) {
+        const pad = left - size
+        throw new TarFormatError(
+          pad === 0
+            ? `archive ends inside padding after ${name}`
+            : `archive ends inside padding after ${name} (${pad} of ${padded - size} bytes)`,
+        )
+      }
+      return tar.subarray(at, at + size)
+    }
+    yield { name, size, type: step.type, mtimeMs: step.mtimeMs, body }
+    // A body the caller skipped is still checked, as the stream drains it.
+    body()
+    off += padded
+  }
+}
+
 // ─── Writer ───────────────────────────────────────────────────────────
 
 /** One regular file to pack. `body` is read as it is written. */
@@ -379,6 +488,48 @@ export function tarSize(inputs: readonly TarInput[]): number {
   return size
 }
 
+/** An entry's blocks before its body: a pax `path` record when needed, then the ustar header. */
+function entryHead(input: TarInput): Uint8Array[] {
+  const mode = input.mode ?? 0o644
+  const mtime = input.mtime ?? 0
+  if (!needsPax(input.name)) return [header(input.name, input.size, '0', mode, mtime)]
+  // Under a pax record the ustar name is a courtesy for readers that
+  // ignore pax: its first 100 BYTES, never characters — a multibyte
+  // name sliced by characters can be over 100 bytes again.
+  const pax = paxRecord('path', input.name)
+  return [
+    header('PaxHeaders/entry', pax.byteLength, 'x', 0o644, mtime),
+    pax,
+    padding(pax.byteLength),
+    header(encoder.encode(input.name).subarray(0, 100), input.size, '0', mode, mtime),
+  ]
+}
+
+/**
+ * `tarPack` of in-memory bodies, written into one buffer on this thread:
+ * the same bytes, without a generator hop per block (the small-artifact
+ * save, `packArtifactBytes`). Returns the bytes written.
+ */
+export function tarPackInto(
+  inputs: readonly (TarInput & { body: Uint8Array | string })[],
+  out: Uint8Array,
+): number {
+  let off = 0
+  for (const input of inputs) {
+    for (const block of entryHead(input)) {
+      out.set(block, off)
+      off += block.byteLength
+    }
+    const bytes = typeof input.body === 'string' ? encoder.encode(input.body) : input.body
+    if (bytes.byteLength !== input.size)
+      throw new TarFormatError(`${input.name}: ${bytes.byteLength} bytes, ${input.size} declared`)
+    out.set(bytes, off)
+    // `out` is zeroed: padding and the end marker are a skip.
+    off += padded(input.size)
+  }
+  return off + BLOCK * 2
+}
+
 /**
  * Pack regular files as a tar stream: ustar with the name/prefix split,
  * a pax `path` record when a name fits neither field — exactly the
@@ -389,20 +540,7 @@ export async function* tarPack(
   inputs: AsyncIterable<TarInput> | Iterable<TarInput>,
 ): AsyncGenerator<Uint8Array> {
   for await (const input of inputs) {
-    const mode = input.mode ?? 0o644
-    const mtime = input.mtime ?? 0
-    // Under a pax record the ustar name is a courtesy for readers that
-    // ignore pax: its first 100 BYTES, never characters — a multibyte
-    // name sliced by characters can be over 100 bytes again.
-    let headerName: string | Uint8Array = input.name
-    if (needsPax(input.name)) {
-      const pax = paxRecord('path', input.name)
-      yield header('PaxHeaders/entry', pax.byteLength, 'x', 0o644, mtime)
-      yield pax
-      yield padding(pax.byteLength)
-      headerName = encoder.encode(input.name).subarray(0, 100)
-    }
-    yield header(headerName, input.size, '0', mode, mtime)
+    yield* entryHead(input)
     if (input.body instanceof Blob || isChunks(input.body)) {
       let n = 0
       const chunks = input.body instanceof Blob ? input.body.stream() : input.body

package/src/cache/zstd.ts

@@ -157,7 +157,7 @@ export const zstdEncoder = (): TransformStream<Uint8Array, Uint8Array> =>
   new CompressionStream('zstd') as unknown as TransformStream<Uint8Array, Uint8Array>
 
 /** Bytes in memory as a one-chunk stream, for a reader that takes a stream. */
-export const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
+const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
   new ReadableStream({
     start(c) {
       c.enqueue(bytes)

package/src/cli/cache.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { Cache } from '../cache/index.js'
-import { flagHint, formatValue, refusedWord, seeHelp } from './help.js'
-import { nearest, parseDuration, parseSize } from '../util/index.js'
+import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
+import { errorCode, nearest, parseDuration, parseSize } from '../util/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import {
@@ -56,15 +56,19 @@ export async function cacheCmd(args: readonly string[]): Promise<number> {
       return await pruneCmd(rest)
     case undefined:
       // A bare `vx cache prune` refuses too: the hint names a whole command.
-      process.stderr.write(
-        `vx cache: missing subcommand. Try \`vx cache prune --older-than 30d\` or \`vx cache prune --max-size 1G\`${seeHelp('cache')}\n`,
+      return refuse(
+        'cache',
+        args,
+        `missing subcommand. Try \`vx cache prune --older-than 30d\` or \`vx cache prune --max-size 1G\`${seeHelp('cache')}`,
+        'VX_E_USAGE',
       )
-      return 1
     default:
-      process.stderr.write(
-        `vx cache: unknown subcommand: ${sub}${cacheSubHint(sub)}${seeHelp('cache')}\n`,
+      return refuse(
+        'cache',
+        args,
+        `unknown subcommand: ${sub}${cacheSubHint(sub)}${seeHelp('cache')}`,
+        'VX_E_USAGE',
       )
-      return 1
   }
 }
 
@@ -153,17 +157,13 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
 
 async function pruneCmd(args: readonly string[]): Promise<number> {
   const parsed = parsePruneArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx cache prune: ${parsed.error}\n`)
-    return 1
-  }
+  if (parsed.error) return refuse('cache prune', args, parsed.error, 'VX_E_USAGE')
   const cwd = process.cwd()
   let root: string
   try {
     root = await findWorkspaceRoot(cwd)
   } catch (err) {
-    process.stderr.write(`vx cache prune: ${(err as Error).message}\n`)
-    return 1
+    return refuse('cache prune', args, (err as Error).message, errorCode(err))
   }
   // Honor `--cache-dir`, `defineWorkspace({ cacheDir: '...' })` and a
   // `config` plugin's edit of it — `vx run` and `vx cache prune` must

package/src/cli/foreign-flags.ts

@@ -361,7 +361,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['--json'],
     value: false,
     outcome: 'refuse',
-    vx: "use `--dry=json` for the plan, `--summarize[=<path>]` for the run's JSON record",
+    vx: "use `--format json` for the run's result on stdout, `--dry=json` for the plan",
   },
   {
     runner: 'turbo',

package/src/cli/help.ts

@@ -1,5 +1,5 @@
 import type { ColorSupport, paint as Paint } from '../orchestrator/index.js'
-import { CORE_VERBS, nearest } from '../util/index.js'
+import { CORE_VERBS, errorDocument, maskedLine, nearest, wantsJson } from '../util/index.js'
 
 export async function printHelp(
   pluginCommands: readonly string[] = [],
@@ -109,12 +109,12 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
     '  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 init [--dry] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
     '  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 last [RUNID] [--list[=N]] [--failed] [--format pretty|json] [--cache-dir <path>]',
+    '  vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
     '  vx version',
@@ -161,6 +161,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
     '',
     'Artifacts (for run):',
+    '      --format <fmt>        pretty (default) | json: print the --summarize document',
+    '                            on stdout when the run ends; every other line goes to stderr.',
     '      --summarize[=<path>]  Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
     '      --profile[=<path>]    Write Chrome-trace JSON (default profile.json).',
     '      --report[=markdown]   Print a markdown run report to stdout after the run.',
@@ -227,6 +229,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       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.',
+    "      --log <task>     That task's output in the run (latest that ran it): a failure's",
+    '                       or the cached log; none for an uncached pass.',
     '      --format <fmt>   pretty (default) | json.',
     '  info, why and last:',
     '      --cache-dir <path>  Read the cache a run with the same flag uses.',
@@ -235,14 +239,16 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
     '                       from package.json scripts. Unmappable settings become',
     '                       TODO(vx-migrate) comments. Beside turbo.json or nx.json:',
-    '                       only vx.workspace.ts, declaring turbo() or nx().',
+    '                       runs @vzn/vx-migrate, which asks native or keep.',
     '      --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.',
+    '      --native         Turbo or Nx: write a vx.config.ts per package (no question).',
+    '      --keep           Turbo or Nx: only vx.workspace.ts, declaring turbo() or nx().',
     '      --plugin <seam>  Instead: write plugins/<seam>.ts, a runnable plugin, and its',
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
-    '  From turbo.json or an Nx project graph: `bunx @vzn/vx-migrate` (its own package).',
+    '  From turbo.json or an Nx project graph: `vx init` runs `@vzn/vx-migrate` (its own package).',
     '',
     'Shell completions:',
     '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
@@ -353,6 +359,7 @@ export const WATCH_REFUSED_FLAGS: readonly string[] = [
   '--report',
   '--report-file',
   '--verbosity',
+  '--format',
 ]
 
 /**
@@ -380,3 +387,21 @@ export function acceptedFlags(verb: string): string[] {
 }
 
 export { CORE_VERBS } from '../util/index.js'
+
+/**
+ * A refusal a verb prints itself rather than throws: one line on stderr,
+ * exit 1, and under `--format json` / `--dry=json` the same as the error
+ * document on stdout that `bin.ts` prints for a thrown one (cli.md § Error
+ * codes), so an agent reads a code.
+ */
+export function refuse(
+  verb: string,
+  args: readonly string[],
+  message: string,
+  code: string,
+): number {
+  const line = `vx ${verb}: ${message}`
+  process.stderr.write(`${line}\n`)
+  if (wantsJson(args)) process.stdout.write(errorDocument(code, maskedLine(line)))
+  return 1
+}

package/src/cli/index.ts

@@ -4,7 +4,15 @@
 import { VERSION } from '../version.js'
 import { CORE_VERBS, flagHint, printHelp, refusedWord, seeHelp } from './help.js'
 import { FOREIGN_VERBS } from './foreign-flags.js'
-import { isUserError, MOVED_VERBS, nearest, UserError } from '../util/index.js'
+import {
+  errorDocument,
+  isUserError,
+  maskedLine,
+  MOVED_VERBS,
+  nearest,
+  UserError,
+  wantsJson,
+} from '../util/index.js'
 
 // Every verb is imported when invoked, `run` included, and so is the
 // plugin-verb lookup: each pulls in the orchestrator and the workspace
@@ -151,6 +159,14 @@ export async function run(argv: readonly string[]): Promise<number> {
       // 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.
+      // Every answer below is "no such verb here": under --format json the
+      // agent reads it as one code, as a verb's own refusal gives one.
+      const unknown = (text: string, code = 'VX_E_UNKNOWN_COMMAND'): number => {
+        process.stderr.write(text)
+        if (wantsJson(rest))
+          process.stdout.write(errorDocument(code, maskedLine(text.split('\n')[0]!)))
+        return 1
+      }
       const loadNote =
         resolved !== null && 'loadError' in resolved
           ? `\n  (plugin verbs could not be looked up: vx.workspace failed to load: ${resolved.loadError})`
@@ -160,8 +176,7 @@ export async function run(argv: readonly string[]): Promise<number> {
       // workspace that declares a plugin verb of that name keeps it.
       const moved = MOVED_VERBS[command] ?? FOREIGN_VERBS[command]
       if (moved !== undefined) {
-        process.stderr.write(`${moved}${loadNote}\n`)
-        return 1
+        return unknown(`${moved}${loadNote}\n`)
       }
       // A task typed where the verb goes (`turbo build`, `nx build app`),
       // `turbo dev` included: a repo's own `dev` task beats the no-service note.
@@ -176,8 +191,7 @@ export async function run(argv: readonly string[]): Promise<number> {
             ).taskVerbHint(command, rest, process.cwd(), guess === '' && !command.startsWith('-'))
           : null
       if (task !== null) {
-        process.stderr.write(`vx: ${task}\n`)
-        return 1
+        return unknown(`vx: ${task}\n`)
       }
       if (command === 'serve' || command === 'dev') {
         // vx core is only a task runner — it has no service layer of its
@@ -186,13 +200,12 @@ export async function run(argv: readonly string[]): Promise<number> {
         // 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(
+        return unknown(
           `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
       }
       // One line, as a verb's own unknown flag or subcommand gets; the full
       // help after a typo was a hundred lines past the hint that mattered.
@@ -208,16 +221,15 @@ export async function run(argv: readonly string[]): Promise<number> {
       if (command.startsWith('-')) {
         // `-v` / `-V` is another tool's version flag, far from both names.
         const flag = /^-v$/i.test(command) ? '--version' : nearest(command, ['--help', '--version'])
-        process.stderr.write(
+        return unknown(
           `vx: unknown flag: ${command}${flag === undefined ? '' : ` (did you mean ${flag}?)`}; a verb's flags follow the verb (see \`vx help\`)\n`,
+          'VX_E_USAGE',
         )
-        return 1
       }
-      process.stderr.write(
+      return unknown(
         `vx: unknown command: ${command}${guess}${loadNote} (see \`vx help\`)\n` +
           (guess === '' && loadNote === '' ? verbSourceNote(resolved, declaredVerbs) : ''),
       )
-      return 1
     }
   }
 }

package/src/cli/info.ts

@@ -4,8 +4,9 @@
 // from the orchestrator's `collectInfo` (doctor.ts), which `vx mcp` reads
 // too; this file parses the flags and renders the rows.
 
+import os from 'node:os'
 import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
-import { flagHint, formatValue, refusedWord, seeHelp } from './help.js'
+import { flagHint, formatValue, refuse, 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'
@@ -44,10 +45,7 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
 
 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
-  }
+  if (parsed.error) return refuse('info', args, parsed.error, 'VX_E_USAGE')
   // `collectInfo` takes a resolved directory from `vx mcp` too, where one
   // not made yet is a workspace that never ran; the flag is the user's,
   // and a directory it names that is not there is a typo (item 900).
@@ -75,7 +73,7 @@ export function renderInfo(f: InfoFacts): string {
     ],
     ['git', f.git ?? '(not found)'],
     ['git status cache', renderGitStatusCache(f.gitStatusCache)],
-    ['workspace root', f.workspaceRoot],
+    ['workspace root', tildePath(f.workspaceRoot)],
     ['projects', describeProjects(f)],
     // Only when a config did not load: the count above says "zero" for
     // it, and this row says which and why.
@@ -88,10 +86,16 @@ export function renderInfo(f: InfoFacts): string {
     ['plugins', describePlugins(f.plugins)],
     ['workers', describeWorkers(f.workers)],
     ['memory', describeMemory(f.memory)],
-    ['cache dir', f.cacheDir],
-    ['cache store', f.cacheStore ?? 'none: the cache dir holds the entries'],
+    ['cache dir', tildePath(f.cacheDir)],
+    [
+      'cache store',
+      f.cacheStore === null ? 'none: the cache dir holds the entries' : tildePath(f.cacheStore),
+    ],
     ['cache versions', `keys ${f.cacheVersion} · index schema ${f.schemaVersion}`],
-    ['cache entries', `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`],
+    ['cache entries', describeEntries(f)],
+    ...(f.cacheRetention !== null
+      ? ([['cache retention', describeRetention(f.cacheRetention)]] as [string, string][])
+      : []),
     // Only when there is something to say.
     ...(f.orphans.artifacts > 0
       ? ([
@@ -118,6 +122,31 @@ export function renderInfo(f: InfoFacts): string {
   return rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`).join('\n')
 }
 
+/** `812 (1.2 GB)`, or against `cacheRetention.maxSize`: `812 (1.2 GB of 10 GB, 12%)`. */
+function describeEntries(f: InfoFacts): string {
+  const max = f.cacheRetention?.maxBytes
+  const size =
+    max === undefined
+      ? formatBytes(f.cacheBytes)
+      : `${formatBytes(f.cacheBytes)} of ${formatBytes(max)}, ${Math.round((f.cacheBytes / max) * 100)}%`
+  return `${f.cacheEntries} (${size})`
+}
+
+/** What a run's end evicts: `entries unused for 30d, and the oldest entries past 10G`. */
+function describeRetention(r: NonNullable<InfoFacts['cacheRetention']>): string {
+  const parts = [
+    ...(r.olderThan !== undefined ? [`entries unused for ${r.olderThan}`] : []),
+    ...(r.maxSize !== undefined ? [`the oldest entries past ${r.maxSize}`] : []),
+  ]
+  return `each run evicts ${parts.join(', and ')}`
+}
+
+/** A path under the home directory as `~/…`: shorter, and no user name in a pasted report. */
+function tildePath(p: string): string {
+  const home = os.homedir()
+  return p === home ? '~' : p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p
+}
+
 /**
  * `available (3 tasks declare exec.sandbox)`, with `, untraced — <why>, so
  * the reads it denies go unreported` where no strace can trace, or