@vzn/vx 0.0.645 → 0.0.648

package/src/cli/docs.ts

@@ -1,10 +1,11 @@
 // `vx docs <query> [--limit N] [--format pretty|json]` — search vx's
 // reference as this version wrote it: packages/vx/docs at its git tag on
-// GitHub, read online (M, 2026-10-17: nothing is embedded). Each page is
+// GitHub, read online (2026-10-17: nothing is embedded). Each page is
 // cut at its headings, and the sections holding every query word print
 // whole, best first.
 
 import { VERSION } from '../version.js'
+import { detectColors, paint, parseDecimalInt, ui } from '../util/index.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 
 const SITE = 'https://vznjs.github.io/vx/'
@@ -19,7 +20,7 @@ interface DocsArgs {
   error?: string
 }
 
-function parseDocsArgs(args: readonly string[]): DocsArgs {
+export function parseDocsArgs(args: readonly string[]): DocsArgs {
   const out: DocsArgs = { terms: [], limit: DEFAULT_LIMIT, json: false }
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!
@@ -29,11 +30,17 @@ function parseDocsArgs(args: readonly string[]): DocsArgs {
       out.json = fv === 'json'
     } else if (a === '--limit' || a.startsWith('--limit=')) {
       const v = a === '--limit' ? args[++i] : a.slice('--limit='.length)
-      const n = Number(v)
-      if (!Number.isInteger(n) || n < 1) {
+      if (v === undefined || v === '') {
         return {
           ...out,
-          error: `--limit takes a whole number above 0 (got ${v ?? 'nothing'})${seeHelp('docs')}`,
+          error: `--limit requires a value: a whole number above 0${seeHelp('docs')}`,
+        }
+      }
+      const n = parseDecimalInt(v)
+      if (n === null || n < 1) {
+        return {
+          ...out,
+          error: `--limit takes a whole number above 0 (got ${v})${seeHelp('docs')}`,
         }
       }
       out.limit = n
@@ -52,7 +59,7 @@ export interface DocsHit {
 }
 
 function words(s: string): string[] {
-  return s.toLowerCase().match(/[a-z0-9][a-z0-9_.-]*/g) ?? []
+  return s.toLowerCase().match(/[\p{L}\p{N}][\p{L}\p{N}_.-]*/gu) ?? []
 }
 
 /** GitHub's heading anchor, which Starlight shares: lowercase, punctuation dropped, spaces to `-`. */
@@ -63,7 +70,7 @@ function anchor(heading: string): string {
     .replace(/ /g, '-')
 }
 
-/** A page's URL on the site, as packages/vx-docs/scripts/import-docs.ts serves it. */
+/** A page's URL on the site, as private/vx-docs/scripts/import-docs.ts serves it. */
 function pageUrl(page: string): string {
   const served: Record<string, string> = {
     README: 'overview',
@@ -117,6 +124,8 @@ export async function loadPages(
 interface Section {
   page: string
   heading: string
+  /** The heading's id on the site; absent for the page's opening. */
+  id?: string
   text: string
 }
 
@@ -124,18 +133,31 @@ interface Section {
 function sections(page: string, md: string): Section[] {
   const out: Section[] = []
   let heading = ''
+  let id: string | undefined
   let lines: string[] = []
   let fence = false
+  // The site numbers a repeated id (`usage`, `usage-1`) over every `##` to
+  // `######` heading of the page, as import-docs.ts's `headingIds` does:
+  // cli.md repeats Usage per verb, and each linked the first.
+  const seen = new Map<string, number>()
   const flush = () => {
     const text = lines.join('\n').trim()
-    if (text !== '') out.push({ page, heading, text })
+    if (text !== '') out.push({ page, heading, ...(id !== undefined ? { id } : {}), text })
   }
   for (const line of md.split('\n')) {
     if (/^\s*(```|~~~)/.test(line)) fence = !fence
-    const h = fence ? null : /^#{1,4} (.+)$/.exec(line)
-    if (h !== null) {
+    const h = fence ? null : /^(#{1,6}) (.+)$/.exec(line)
+    let slug: string | undefined
+    if (h !== null && h[1]!.length > 1) {
+      const base = anchor(h[2]!.replace(/`/g, '').trim())
+      const n = seen.get(base) ?? 0
+      seen.set(base, n + 1)
+      slug = n === 0 ? base : `${base}-${n}`
+    }
+    if (h !== null && h[1]!.length <= 4) {
       flush()
-      heading = h[1]!.replace(/`/g, '').trim()
+      heading = h[2]!.replace(/`/g, '').trim()
+      id = slug ?? anchor(heading)
       lines = [line]
     } else lines.push(line)
   }
@@ -182,7 +204,7 @@ export function searchDocs(
   return (exact.length > 0 ? exact : scored).slice(0, limit).map(({ s }) => ({
     page: s.page,
     heading: s.heading,
-    url: s.heading === '' ? pageUrl(s.page) : `${pageUrl(s.page)}#${anchor(s.heading)}`,
+    url: s.id === undefined ? pageUrl(s.page) : `${pageUrl(s.page)}#${s.id}`,
     text: s.text,
   }))
 }
@@ -220,16 +242,20 @@ export async function docsCmd(
     return 0
   }
   if (hits.length === 0) {
-    process.stdout.write(
+    ui.say(
+      'warn',
       `vx docs: no section of the docs at ${ref} holds every word of "${query}"; try fewer words, or ${SITE}llms.txt\n`,
+      'out',
     )
     return 0
   }
+  const c = detectColors(process.stdout)
   process.stdout.write(
     hits
-      .map(
-        (h) =>
-          `── ${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`} · ${h.url}\n\n${h.text}\n`,
+      .map((h) =>
+        c.enabled
+          ? `${ui.render([ui.excerpt(`${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`}`, h.text)], c)}${paint('', h.url, c, { dim: true })}\n`
+          : `── ${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`} · ${h.url}\n\n${h.text}\n`,
       )
       .join('\n'),
   )

package/src/cli/help.ts

@@ -114,14 +114,14 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Usage:',
     '  vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]',
     '  vx watch [OPTIONS] [--poll] TASK [-- forwarded-args...]',
-    '  vx cache clean [--older-than <duration>] [--max-size <size>] [--global] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
+    '  vx cache clean [--older-than <duration>] [--max-size <size>] [--global] [--dry] [--format pretty|json] [--cache-dir <path>]',
     '  vx lock [--check] [--format pretty|json]',
-    '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
+    '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <hook>]',
     '  vx upgrade [TAG] [-g|--global]',
     '  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] [--log <task>] [--stats [<task>] [--branch <name>]] [--format pretty|json] [--cache-dir <path>]',
+    '  vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--stats [<task>] [--branch <name>]] [--sql <query>] [--live [--follow]] [--format pretty|json] [--cache-dir <path>]',
     '  vx docs <query> [--limit N] [--format pretty|json]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
@@ -186,7 +186,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                                  summary table after the run.',
     '',
     'Planning (for run — skips execution):',
-    "      --dry[=text|json]    Print the task graph and each task's predicted hit",
+    "      --dry[=pretty|json]  Print the task graph and each task's predicted hit",
     '                           or miss.',
     '',
     'Artifacts (for run):',
@@ -197,13 +197,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  cache, distributed execution, and telemetry export are provided by',
     '  PLUGINS declared in .vx/workspace.ts — first-party or your own. Core',
     '  depends on none of them; a plain `vx run` never requires a plugin.',
-    '  See the plugin guide: https://vznjs.github.io/vx/guides/plugins/',
-    '',
-    'Turbo and Nx spellings (for run):',
-    '  What turbo run / nx run-many / nx affected take works here, or is refused',
-    '  naming the vx spelling: -t build,test, -p app, --exclude docs, --parallel 4,',
-    '  and --base main, --dry-run, --skip-nx-cache. `vx build` names `vx run build`.',
-    '  Every flag: https://vznjs.github.io/vx/cli/#turbo-and-nx-flags',
+    '  See the plugin guide: https://vznjs.github.io/vx/docs/plugins/',
     '',
     'Argument forwarding (for run):',
     "  Anything after `--` is forwarded (shell-quoted) to the task's exec",
@@ -221,11 +215,13 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Cache management:',
     '  vx cache clean --older-than 30d     Evict entries last accessed > 30 days ago.',
     '  vx cache clean --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
-    "  vx cache clean                      Clear .vx/cache and this repo's store ~/.vx/<id>/cache.",
+    "  vx cache clean                      Clear .vx/cache and this repo's store",
+    '                                      ~/.vx/<id>/cache.',
     "      --global                        Clear every repo's store under ~/.vx.",
-    '      --dry-run                       Say what the policy would reap; delete nothing.',
+    '      --dry                           Say what the policy would reap; delete nothing.',
     '      --format <fmt>                  pretty (default) | json.',
-    '      --cache-dir <path>              The cache a run with the same flag uses (why, last, info too).',
+    '      --cache-dir <path>              The cache a run with the same flag uses (why,',
+    '                                      last, info too).',
     '',
     '  Duration units: ms, s, m, h, d. Size units: K, M, G, T (powers of 1024).',
     '  Cache statistics — directory, entry count, size — are part of `vx info`.',
@@ -259,6 +255,10 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --stats [<task>] Per-task p50/p99, pass and hit rate, failure mode, peak',
     '                       RSS and CPU over the last 50 runs; a task id or name narrows.',
     "      --branch <name>  The branch --stats' p50 forecasts from (default: the run's).",
+    '      --sql <query>    One read-only SELECT over the history (runs, invocations,',
+    '                       entries, task_outcomes, ...): filter, group, trend.',
+    '      --live           The run in progress: running, ended, waiting tasks, warnings.',
+    "      --follow         With --live, the run's output and events until it ends.",
     '      --format <fmt>   pretty (default) | json.',
     '  info, why and last:',
     '      --cache-dir <path>  Read the cache a run with the same flag uses.',
@@ -274,7 +274,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --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',
+    '      --plugin <hook>  Instead: write plugins/<hook>.ts, a runnable plugin, and its',
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
     '',
@@ -304,11 +304,11 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       into .vx/projects.lock.json, the only place a run reads configs',
     '                       from. A run never evaluates one, never checks the rules',
     '                       and never writes the lock: with none it fails.',
-    '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
-    '                       re-evaluation compared against the frozen objects, and the',
-    '                       graph rules. Exits 1 on drift (e.g. configs that read env',
-    '                       vars). Run it before the run in CI. With --format json it prints',
-    '                       {upToDate, audited, notAudited, problems}.',
+    '  vx lock --check      Audit the lock: re-evaluate every config here and compare',
+    '                       it with the frozen object, find a config added or gone, and',
+    '                       check the graph rules. Exits 1 on drift (e.g. configs that',
+    '                       read env vars). Run it before the run in CI. With --format json',
+    '                       it prints {upToDate, audited, notAudited, problems}.',
     '',
     ...(pluginCommands.length > 0 ? ['Plugin commands:', ...pluginCommands, ''] : []),
   ].join('\n')
@@ -323,6 +323,27 @@ export function seeHelp(verb: string): string {
   return ` (see \`vx ${verb} --help\`)`
 }
 
+/**
+ * The refusal for a `project#task` spec with an empty half, or undefined.
+ * An empty task wins over an empty project: `#` names no task to run in
+ * every project, so `bare(task)` would print a hint with no task in it.
+ */
+export function anchoredSpecError(
+  spec: string,
+  bare: (task: string) => string,
+): string | undefined {
+  const idx = spec.indexOf('#')
+  if (idx < 0) return undefined
+  const project = spec.slice(0, idx)
+  const task = spec.slice(idx + 1)
+  if (!task) {
+    const list = project ? `vx show ${project}` : 'vx show'
+    return `missing task name after '#' in "${spec}" (${list} lists the tasks)`
+  }
+  if (!project) return `missing project name before '#' in "${spec}" (${bare(task)})`
+  return undefined
+}
+
 /** `--format`'s value, or the one refusal every verb gives for a bad one. */
 export function formatValue(
   v: string | undefined,
@@ -343,8 +364,8 @@ export function refusedWord(arg: string): string {
 }
 
 /**
- * `(did you mean --concurrency?)` for a flag within two edits of one `verb`
- * accepts; empty for anything else (a positional included). A third edit
+ * `(did you mean --concurrency?)` for a flag within two edits (one, for a
+ * name of four letters or fewer) of one `verb` accepts; empty for anything else (a positional included). A third edit
  * is allowed only between flags that share their first five characters,
  * so `--timeouts` reaches `--timeout` while `--zzz` does not reach `--all`.
  */
@@ -356,9 +377,25 @@ export function flagHint(verb: string, arg: string): string {
   // `--json` is gh's and Nx's spelling; a verb with `--format` reads it
   // there, and no edit budget reaches `--format json` from `--json`.
   if (name === '--json' && flags.includes('--format')) return ' (did you mean --format json?)'
-  // A flag cut short at a word (`--dry` for prune's `--dry-run`, which
-  // `vx run` spells `--dry`) is too many edits away for either budget.
-  const cut = flags.filter((f) => f.startsWith(`${name}-`))
+  // `vx run` prints no JSON of its own, and edit distance reached `--force`
+  // from `--format`: a run with its cache reads turned off.
+  if ((name === '--format' || name === '--json') && flags.includes('--dry'))
+    return ' (the run as JSON is `vx last --format json` after it; the plan is --dry=json)'
+  // Watch takes run's flags but --dry, so the branch above missed it.
+  if ((name === '--format' || name === '--json') && verb === 'watch')
+    return " (vx watch prints no JSON; each cycle's run is `vx last --format json` after it)"
+  // A bare flag handed a value (`--check=yes`) is no edit from itself.
+  if (name !== arg && flags.includes(name)) return ` (did you mean ${name}?)`
+  // Another verb's own flag is no typo: `vx run --poll` was told "did you
+  // mean --all?". Named only when one other verb takes it.
+  const owners = CORE_VERBS.filter(
+    (v) => v !== verb.split(' ')[0] && acceptedFlags(v).includes(name),
+  )
+  if (owners.length === 1)
+    return `. \`vx ${owners[0] === 'cache' ? 'cache clean' : owners[0]}\` takes it`
+  // A flag one word too long (`--dry-run` for `--dry`) is too many edits
+  // away for either budget, and so is one cut short at a word.
+  const cut = flags.filter((f) => f.startsWith(`${name}-`) || name.startsWith(`${f}-`))
   const best =
     nearest(name, flags) ??
     nearest(

package/src/cli/index.ts

@@ -3,9 +3,9 @@
 
 import { VERSION } from '../version.js'
 import { checkSettingsEnv } from '../settings.js'
-import { CORE_VERBS, flagHint, printHelp, refusedWord, seeHelp } from './help.js'
-import { FOREIGN_VERBS } from './foreign-flags.js'
+import { CORE_VERBS, flagHint, printHelp, refuse, refusedWord, seeHelp } from './help.js'
 import {
+  detectColors,
   errorDocument,
   hideEnvFromTasks,
   sayNotice,
@@ -15,6 +15,7 @@ import {
   maskedLine,
   nearest,
   refusalNotice,
+  thrownMessage,
   ui,
   UserError,
   wantsJson,
@@ -29,6 +30,7 @@ import {
 const plugins = () => import('./plugin-commands.js')
 
 export async function run(argv: readonly string[]): Promise<number> {
+  refuseLossyArgs(argv)
   const [command, ...rest] = argv
   await hideEnvFromTasks()
 
@@ -42,8 +44,11 @@ export async function run(argv: readonly string[]): Promise<number> {
     return 0
   }
   // Each setting's variable once, before any verb: a renamed one is named,
-  // and a deep reader trusts what it reads.
-  checkSettingsEnv()
+  // and a deep reader trusts what it reads. Not for help, as `vx run
+  // --help` above is not: help is where a setting's values are read. Nor
+  // for `vx info`, which reports a refused one (doctor.ts).
+  if (command !== 'help' && command !== '--help' && command !== '-h' && command !== 'info')
+    checkSettingsEnv()
 
   try {
     return await dispatch(command, rest)
@@ -52,9 +57,23 @@ export async function run(argv: readonly string[]): Promise<number> {
   }
 }
 
+/**
+ * Bun decodes argv as lossy UTF-8 and exposes no raw bytes on macOS, so
+ * `-- $'a\xfe'` and `-- $'a\xff'` both became `a` U+FFFD: the task got
+ * bytes nobody typed and the two runs shared a key (a stale hit). A real
+ * U+FFFD cannot be told from a replaced byte, so any arg holding one is refused.
+ */
+function refuseLossyArgs(argv: readonly string[]): void {
+  const at = argv.findIndex((a) => a.includes('�'))
+  if (at === -1) return
+  throw new UserError(
+    `argument ${at + 1} (${JSON.stringify(argv[at])}) is not valid UTF-8, or holds U+FFFD; vx cannot pass it on byte for byte`,
+  )
+}
+
 /**
  * A crash from a hand-broken lock entry is that entry's fault: runs validate
- * no entry, so it surfaced as a raw TypeError (M, 2026-10-14). The lock is
+ * no entry, so it surfaced as a raw TypeError (2026-10-14). The lock is
  * read only on the crash path, so a normal run pays nothing.
  */
 async function brokenLockNamed(err: unknown): Promise<unknown> {
@@ -62,7 +81,8 @@ async function brokenLockNamed(err: unknown): Promise<unknown> {
   try {
     const { findWorkspaceRoot, LOCK_INVALID, lockEntryBroken } =
       await import('../workspace/index.js')
-    if (lockEntryBroken(await findWorkspaceRoot(process.cwd()))) return new UserError(LOCK_INVALID)
+    if (lockEntryBroken(await findWorkspaceRoot(process.cwd())))
+      return new UserError(LOCK_INVALID, 'VX_E_LOCK')
   } catch {}
   return err
 }
@@ -86,41 +106,45 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
     }
     case '--help':
     case '-h':
+      if (rest.length > 0) return dispatch('help', rest)
       await printHelp(await (await plugins()).pluginCommandHelp())
       return 0
     case 'help': {
-      // `vx help run` is the same question as `vx run --help`. A plugin verb
-      // owns its own help, so anything but a core verb gets the whole
-      // reference, which lists the plugin verbs.
-      const verb = rest[0]
+      // `vx help run` is the same question as `vx run --help`, and so is
+      // `vx help <plugin verb>`: a plugin verb owns its own help.
+      const [verb, extra] = rest
+      if (extra !== undefined) {
+        return refuse(
+          'help',
+          rest,
+          `${refusedWord(extra)}: ${extra}${flagHint('help', extra)} (see \`vx help\`)`,
+          'VX_E_USAGE',
+        )
+      }
       const core = verb !== undefined && (CORE_VERBS as readonly string[]).includes(verb)
       if (verb !== undefined && !core) {
         // A name that is no verb here is the typo `vx rnu` is, not a request
         // for the whole reference: it printed 145 lines and no hint.
         const resolved = await (await plugins()).resolvePluginCommand(verb)
         const unknown = resolved === null || 'declaredVerbs' in resolved
-        const pointer = FOREIGN_VERBS[verb]
-        if (unknown && pointer !== undefined) {
-          sayNotice('info', 'vx', pointer)
-          return 1
-        }
         if (unknown && verb.startsWith('-')) {
-          sayNotice(
-            'error',
-            'vx help',
+          return refuse(
+            'help',
+            rest,
             `unknown flag: ${verb}${flagHint('help', verb)} (see \`vx help\`)`,
+            'VX_E_USAGE',
           )
-          return 1
         }
         if (unknown) {
           const declared = resolved === null ? [] : resolved.declaredVerbs
-          sayNotice(
-            'error',
-            'vx help',
+          return refuse(
+            'help',
+            rest,
             `unknown command: ${verb}${didYouMeanVerb(verb, declared)} (see \`vx help\`)`,
+            'VX_E_UNKNOWN_COMMAND',
           )
-          return 1
         }
+        if (resolved !== null && !('loadError' in resolved)) return dispatch(verb, ['--help'])
       }
       await printHelp(await (await plugins()).pluginCommandHelp(), core ? verb : undefined)
       return 0
@@ -131,14 +155,17 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
       // takes no more of is refused, as every other verb refuses one.
       const extra = rest[0]
       if (extra !== undefined) {
-        sayNotice(
-          'error',
-          'vx version',
+        return refuse(
+          'version',
+          rest,
           `${refusedWord(extra)}: ${extra}${flagHint('version', extra)}${seeHelp('version')}`,
+          'VX_E_USAGE',
         )
-        return 1
       }
-      process.stdout.write(`vx ${VERSION}\n`)
+      // Painted, and the same words piped: a script reads `vx <version>`.
+      process.stdout.write(
+        `${ui.inline([ui.cmd('vx'), ' ', ui.tone('info', VERSION)], detectColors(process.stdout))}\n`,
+      )
       return 0
     }
     case 'run':
@@ -180,7 +207,7 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
           // A verb's own refusal is its one line; anything else is the
           // plugin's crash, named as every other stage names one.
           if (isUserError(err)) throw err
-          const message = err instanceof Error ? err.message : String(err)
+          const message = thrownMessage(err)
           throw new UserError(
             `plugin '${resolved.plugin.name}' failed in command '${command}': ${message}`,
           )
@@ -207,22 +234,18 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         text: string,
         code = 'VX_E_UNKNOWN_COMMAND',
         tone: 'error' | 'info' = 'error',
+        json = text.split('\n')[0]!,
       ): number => {
         sayNotice(tone, 'vx', text.replace(/^vx: /, '').trimEnd())
-        if (wantsJson(rest))
-          process.stdout.write(errorDocument(code, maskedLine(text.split('\n')[0]!)))
+        // `vx --format json` puts the flag where the verb goes.
+        if (wantsJson([command, ...rest]))
+          process.stdout.write(errorDocument(code, maskedLine(json)))
         return 1
       }
       const loadNote =
         resolved !== null && 'loadError' in resolved
           ? `\n  (plugin verbs could not be looked up: .vx/workspace failed to load: ${resolved.loadError})`
           : ''
-      // Another tool's verb: the pointer, but only after the plugins had
-      // their chance — a workspace that declares a plugin verb of that name keeps it.
-      const moved = FOREIGN_VERBS[command]
-      if (moved !== undefined) {
-        return unknown(`${moved}${loadNote}\n`, undefined, 'info')
-      }
       // 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.
       const declaredVerbs =
@@ -244,12 +267,13 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         // 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.
+        // these. The notice prints a line per fact, so each line is a
+        // whole sentence.
         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`,
+          `vx: \`${command}\` is not a vx core command.\n` +
+            `  vx core runs tasks in-process.\n` +
+            `  A dashboard, remote cache and distributed execution come from plugins, not core.\n` +
+            `  See the plugin guide: https://vznjs.github.io/vx/docs/plugins/\n`,
         )
       }
       // One line, as a verb's own unknown flag or subcommand gets; the full
@@ -271,9 +295,19 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
           'VX_E_USAGE',
         )
       }
+      // A workspace that does not load is the refusal to fix first: the
+      // verb may be its own plugin's.
+      if (resolved !== null && 'loadError' in resolved) {
+        return unknown(
+          `vx: unknown command: ${command}${guess}${loadNote} (see \`vx help\`)\n`,
+          'VX_E_CONFIG',
+          'error',
+          `vx: unknown command: ${command}; .vx/workspace failed to load: ${resolved.loadError}`,
+        )
+      }
       return unknown(
-        `vx: unknown command: ${command}${guess}${loadNote} (see \`vx help\`)\n` +
-          (guess === '' && loadNote === '' ? verbSourceNote(resolved, declaredVerbs) : ''),
+        `vx: unknown command: ${command}${guess} (see \`vx help\`)\n` +
+          (guess === '' ? verbSourceNote(resolved, declaredVerbs) : ''),
       )
     }
   }
@@ -310,6 +344,6 @@ function verbSourceNote(resolved: unknown, declaredVerbs: readonly string[]): st
   if (declaredVerbs.length > 0) {
     return `  This workspace's plugins declare: ${[...declaredVerbs].sort().join(', ')}.\n`
   }
-  const here = resolved === null ? 'there is no workspace here' : 'this workspace declares none'
+  const here = resolved === null ? 'there is no workspace here' : 'no plugin here adds one'
   return `  A plugin declared in .vx/workspace.ts can add verbs; ${here}.\n`
 }

package/src/cli/info.ts

@@ -113,20 +113,24 @@ export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false
     // the hits are a share of.
     [
       'task runs (24h)',
-      `${f.runs24h} (${f.hits24h} cache hits` +
+      `${f.runs24h} (${f.hits24h} cache hit${f.hits24h === 1 ? '' : 's'}` +
         (f.hits24h > 0
           ? `: ${f.hits24h - f.restored24h} up-to-date, ${f.restored24h} restored)`
           : ')'),
     ],
     ['flaky tasks', describeFlakyTasks(f.flakyTasks)],
     ['sandbox', describeSandbox(f.sandbox)],
-    ['projects lock', f.lockfile ? 'yes' : 'no'],
+    [
+      'projects lock',
+      typeof f.lockError === 'string' ? `refused: ${f.lockError}` : f.lockfile ? 'yes' : 'no',
+    ],
   ]
   return ui.report('vx info', rows).lines(colors).join('\n')
 }
 
-/** `812 (1.2 GB)`. */
+/** `812 (1.2 GB)`, or why the index cannot be read and its fix. */
 function describeEntries(f: InfoFacts): string {
+  if (f.cacheIndexError !== null) return `unreadable: ${f.cacheIndexError}`
   return `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`
 }
 
@@ -139,7 +143,7 @@ function describeSettings(settings: InfoFacts['settings']): string {
     .filter(([, s]) => s.source !== 'default')
     .map(
       ([path, s]) =>
-        `${path} ${String(s.value)} (${s.source === 'env' ? envName(path) : '.vx/workspace'})`,
+        `${path} ${String(s.value)} (${s.source === 'env' ? envName(path) : '.vx/workspace'}${s.refused === undefined ? '' : `, refused: ${s.refused}`})`,
     )
     .join(', ')
 }
@@ -169,9 +173,11 @@ function describeSandbox(s: InfoFacts['sandbox']): string {
 /** `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})`
+  const cores = `${w.cores} core${w.cores === 1 ? '' : 's'}`
+  if (w.source === 'workspace') return `${w.count} — .vx/workspace.ts (${cores}${quota})`
+  if (w.source === 'env') return `${w.count} — ${envName('run.concurrency')} (${cores}${quota})`
   if (w.source === 'cgroup')
-    return `${w.count} — cgroup CPU quota ${trimCores(w.cpuQuota ?? w.count)} of ${w.cores} cores`
+    return `${w.count} — cgroup CPU quota ${trimCores(w.cpuQuota ?? w.count)} of ${cores}`
   return `${w.count} — the CPU count${quota}`
 }