@vzn/vx 0.0.646 → 0.0.648

package/src/cache/schema.ts

@@ -24,7 +24,8 @@ export function lazyStatement(db: Database, sql: string): ReturnType<Database['p
  * Create every table. `store` names the schema holding the ENTRY tables
  * (`entries`, `entry_stdout`, `output_files`, `entry_inputs`, `store_meta`)
  * the task timings (`task_durations`), the flaky record (`task_outcomes`),
- * the blob sizes (`blob_sizes`) and the plugins' blobs (`plugin_blobs`):
+ * the blob sizes (`blob_sizes`), the plugins' blobs (`plugin_blobs`) and
+ * the remotes' hits (`remote_hits`):
  * `main` when one `cache.db` holds everything (a `cacheDir`), `store` when
  * they live in the shared store attached beside it (v32). The rest is the
  * workspace's own: its history, its memos, and what its disk looked like
@@ -112,7 +113,13 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       placement_cores     INTEGER,
       placement_memory    INTEGER,
       -- v46: the task with no inputs its key folded (TaskOutcome.keylessBy).
-      keyless_by          TEXT
+      keyless_by          TEXT,
+      -- v48: the task's definition (taskDefinition): a history reader
+      -- counts only the rows of the task as it is now.
+      def                 TEXT,
+      -- v49: the share of a core each runnable thread got where it ran
+      -- (ExecuteResult.machine.cpuShare); NULL = all it wanted.
+      cpu_share           REAL
     );
     -- Two whole-table indexes only, and both APPEND: every row of a run carries the
     -- same run_id and a started_at newer than everything before it, so
@@ -163,7 +170,7 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     -- worktree size git recorded (A-60). Fixed for its OID, so a warm
     -- run asks git for none; swept with file_hashes by seen_at, the
     -- time the row was written. v38: in the store, so a worktree reads
-    -- what another learned (owner, 2026-10-14).
+    -- what another learned (2026-10-14).
     CREATE TABLE IF NOT EXISTS ${store}.blob_sizes (
       oid     TEXT PRIMARY KEY,
       size    INTEGER NOT NULL,
@@ -280,7 +287,7 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     );
     -- What a duration forecast reads (orchestrator/history.ts), one row per
     -- executed success, shared by every worktree of the repo so a new one
-    -- forecasts on its first run (owner, 2026-10-14). Append-only: never
+    -- forecasts on its first run (2026-10-14). Append-only: never
     -- updated, pruned by age with the run history. \`source\` tags a local
     -- run 'branch:<name>' ('branch:' detached or outside git); \`sha\` is its
     -- commit. A forecast reads a task's newest rows of one source.
@@ -297,7 +304,9 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       cpu_parallelism        REAL,
       peak_rss_bytes         INTEGER,
       saturated_cores        INTEGER,
-      saturated_memory_bytes INTEGER
+      saturated_memory_bytes INTEGER,
+      -- v48: the task's definition (taskDefinition), as on \`runs\`.
+      def                    TEXT
     );
     CREATE INDEX IF NOT EXISTS ${store}.task_durations_task
       ON task_durations(project, task, source, id);
@@ -309,7 +318,7 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     -- v38: the flaky record (orchestrator/failure-mode.ts): each keyed,
     -- cached, unblocked outcome that observed its key, shared by every
     -- worktree so a key that passed in one and failed in another is flaky
-    -- in both (owner, 2026-10-14). Every executed success or failure, and
+    -- in both (2026-10-14). Every executed success or failure, and
     -- a key's first hit (run-history.ts): a later hit replays a pass the
     -- record holds, so a warm run on keys that passed writes no row.
     -- Append-only, ordered by id, pruned by age with the run history.
@@ -331,6 +340,16 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       bytes BLOB NOT NULL,
       at    INTEGER NOT NULL
     );
+    -- What a remote's has-many said it holds (remote-hits.ts), shared by
+    -- every worktree: a key here is a hit until a has-many or a GET says it
+    -- is gone, and a key not here is a miss. Only hits are kept. Pruned by
+    -- \`seen_at\` with the run history.
+    CREATE TABLE IF NOT EXISTS ${store}.remote_hits (
+      hash        TEXT PRIMARY KEY,
+      size        INTEGER,
+      duration_ms INTEGER,
+      seen_at     INTEGER NOT NULL
+    );
     ${artifactTables(store)}
   `)
 }

package/src/cache/tar-stream.ts

@@ -38,6 +38,8 @@ const BLOCK = 512
  * numbers; a MiB is far past any writer's.
  */
 const MAX_EXTENDED_HEADER = 1024 * 1024
+/** The largest millisecond count a Date holds (ECMA-262 §21.4.1.1). */
+const DATE_MAX_MS = 8.64e15
 // `ignoreBOM`: a default decoder drops a leading U+FEFF, and a name or
 // prefix field that began with one read back without it.
 const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
@@ -232,6 +234,9 @@ class TarDecoder {
     const type = h[156] === 0 ? '0' : String.fromCharCode(h[156]!)
     const size = this.pendingSize ?? octal(h, 124, 12)
     const mtimeMs = octal(h, 136, 12) * 1000
+    // Only GNU base-256 reaches past it, and a restore's utimes threw on
+    // such a Date after the renames before it had landed.
+    if (mtimeMs > DATE_MAX_MS) throw new TarFormatError(`header mtime past what a Date holds`)
     const padded = Math.ceil(size / BLOCK) * BLOCK
     // POSIX `ustar\0` only: old GNU's `ustar  ` keeps atime and ctime at
     // 345, and `-G` fills them, so a prefix read there named every entry

package/src/cache/umask.ts

@@ -1,8 +1,7 @@
 // The process umask, read when a restore starts: Bun reads it by setting 0
 // and putting it back in one synchronous call (project-loader.ts
 // `currentUmask`), so no spawn on this thread sees the 0, and a run
-// evaluates no config in a worker. Through globalThis: the playground's
-// shim has no umask.
+// evaluates no config in a worker.
 const proc = globalThis.process as { umask?: () => number } | undefined
 let umask = 0
 

package/src/cli/cache.ts

@@ -1,10 +1,11 @@
-import { existsSync, readdirSync, rmSync } from 'node:fs'
+import { existsSync, lstatSync, readdirSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
 import { Cache, vxCacheEntries } from '../cache/index.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 import {
   errorCode,
+  isUserError,
   nearest,
   parseDuration,
   parseSize,
@@ -57,11 +58,11 @@ const CACHE_ELSEWHERE: Record<string, string> = {
 }
 
 function cacheSubHint(sub: string): string {
-  const elsewhere = CACHE_ELSEWHERE[sub]
-  if (elsewhere !== undefined) return ` — ${elsewhere}`
+  // Own keys only: `vx cache constructor` printed `Object`'s source.
+  if (Object.hasOwn(CACHE_ELSEWHERE, sub)) return ` — ${CACHE_ELSEWHERE[sub]}`
   const best = nearest(sub, ['clean'])
   // `clean` is the one subcommand: name it when nothing is near (M-58).
-  return best === undefined ? '. The subcommand is clean' : `. Did you mean ${best}?`
+  return best === undefined ? '. Its one subcommand is `vx cache clean`' : `. Did you mean ${best}?`
 }
 
 export async function cacheCmd(args: readonly string[]): Promise<number> {
@@ -78,6 +79,16 @@ export async function cacheCmd(args: readonly string[]): Promise<number> {
         'VX_E_USAGE',
       )
     default:
+      // `vx cache --older-than 30d` dropped the verb, not misspelled it:
+      // name the clean command those flags make, when they parse as one.
+      if (sub.startsWith('-') && parsePruneArgs(args).error === undefined) {
+        return refuse(
+          'cache',
+          args,
+          `missing subcommand before ${sub}. Did you mean \`vx cache clean ${args.join(' ')}\`?${seeHelp('cache')}`,
+          'VX_E_USAGE',
+        )
+      }
       return refuse(
         'cache',
         args,
@@ -90,7 +101,7 @@ export async function cacheCmd(args: readonly string[]): Promise<number> {
 interface PruneArgs {
   olderThanMs?: number
   maxBytes?: number
-  dryRun?: boolean
+  dry?: boolean
   format?: 'pretty' | 'json'
   /** `--cache-dir`: prune the cache a run with the same flag uses. */
   cacheDir?: string
@@ -149,8 +160,8 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
         }
       }
       out.maxBytes = bytes
-    } else if (a === '--dry-run') {
-      out.dryRun = true
+    } else if (a === '--dry') {
+      out.dry = true
     } else if (a === '--global') {
       out.global = true
     } else if (a === '--format' || a?.startsWith('--format=')) {
@@ -205,7 +216,7 @@ async function cleanCmd(args: readonly string[]): Promise<number> {
   else {
     const ws = await loadCliWorkspace(root)
     dir = ws.cacheDir
-    storeRoot = await ws.storeRoot
+    storeRoot = await ws.storeRoot()
   }
   if (parsed.olderThanMs === undefined && parsed.maxBytes === undefined) {
     return clear(args, root, dir, storeRoot, parsed)
@@ -213,15 +224,17 @@ async function cleanCmd(args: readonly string[]): Promise<number> {
   // A workspace that never ran has nothing to prune, and opening the cache
   // to find that out made it: `.vx/cache` with a database and a
   // `.gitignore`, where item 900 had held the dry run to making nothing
-  // (and a read-only checkout was refused as unwritable instead).
-  const dry = parsed.dryRun === true
+  // (and a read-only checkout was refused as unwritable instead). So has a
+  // directory holding nothing vx wrote (`--cache-dir build`): opened, it got
+  // an index and a `*` .gitignore that hid the user's files from git.
+  const dry = parsed.dry === true
   const json = parsed.format === 'json'
-  if (!existsSync(dir) && (storeRoot === null || !existsSync(storeRoot))) {
+  if (vxCacheEntries(dir).length === 0 && (storeRoot === null || !existsSync(storeRoot))) {
     printPruned({ evicted: 0, bytesFreed: 0, orphans: 0, orphanBytes: 0 }, dry, json)
     return 0
   }
   const cache =
-    parsed.dryRun === true
+    parsed.dry === true
       ? 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
@@ -229,19 +242,19 @@ async function cleanCmd(args: readonly string[]): Promise<number> {
   // than dying in the first DELETE with SQLite's "readonly database" and a
   // stack (an unprivileged user on a root-owned `.vx`, 2026-09-16). A dry
   // run only reads, and reads a read-only cache fine.
-  if (!parsed.dryRun) cache.assertWritable()
+  if (!parsed.dry) cache.assertWritable()
   // A prune beside a run on this workspace evicts what the run has just
   // probed as hits, whose `accessed_at` bumps it has not flushed yet; the
   // run then re-runs those tasks (upstream survey, nx#36688). So a prune
   // takes the run's lock and waits its turn. A dry run deletes nothing.
-  const releaseRunLock = parsed.dryRun
+  const releaseRunLock = parsed.dry
     ? async (): Promise<void> => {}
     : await acquireRunLock(root, { log: warnToStderr })
   try {
-    const opts: { olderThanMs?: number; maxBytes?: number; dryRun?: boolean } = {}
+    const opts: { olderThanMs?: number; maxBytes?: number; dry?: boolean } = {}
     if (parsed.olderThanMs !== undefined) opts.olderThanMs = parsed.olderThanMs
     if (parsed.maxBytes !== undefined) opts.maxBytes = parsed.maxBytes
-    if (parsed.dryRun) opts.dryRun = true
+    if (parsed.dry) opts.dry = true
     printPruned(await cache.prune(opts), dry, json)
   } finally {
     cache.close()
@@ -258,7 +271,7 @@ function printPruned(
   if (json) {
     const { evicted, bytesFreed, orphans, orphanBytes } = result
     process.stdout.write(
-      `${JSON.stringify({ dryRun: dry, evicted, bytesFreed, orphans, orphanBytes })}\n`,
+      `${JSON.stringify({ dry: dry, evicted, bytesFreed, orphans, orphanBytes })}\n`,
     )
     return
   }
@@ -286,7 +299,7 @@ function freedStatus(dry: boolean, bytes: number, any: boolean): ui.Block {
 
 /** `vx cache clean --format json` with no bound (schemas/cache.json `clear`). */
 export interface ClearResult {
-  dryRun: boolean
+  dry: boolean
   /** Workspace-relative inside the workspace, else absolute. */
   cleared: string[]
   bytesFreed: number
@@ -308,17 +321,27 @@ async function clear(
   storeRoot: string | null,
   parsed: PruneArgs,
 ): Promise<number> {
-  // The store the index recorded wins over today's (a changed HOME), as a
-  // run reads it; a directory with no index is not a vx cache to delete.
+  // The store the index recorded and today's (a changed HOME, an origin
+  // added) both go; a directory with no index is not a vx cache to delete.
   const targets: string[] = []
   if (existsSync(path.join(dir, 'cache.db'))) {
-    const cache = new Cache(dir, undefined, undefined, undefined, 'preview', storeRoot)
-    const store = cache.storeDir
-    cache.close()
+    // An index SQLite cannot read is what its own refusal sends here to
+    // clear: today's store stands in for the one it recorded.
+    let store: string | undefined = storeRoot ?? undefined
+    try {
+      const cache = new Cache(dir, undefined, undefined, undefined, 'preview', storeRoot)
+      store = cache.storeDir
+      cache.close()
+    } catch (err) {
+      if (!isUserError(err)) throw err
+    }
     targets.push(dir)
     // The index is a file in the checkout (committed, or restored from a CI
     // cache): the store it names is deleted only when it is one.
     if (store !== undefined && isStore(store)) targets.push(store)
+    // Today's store too: the next run reads it, whichever store the index
+    // last recorded (a moved HOME, an origin added).
+    if (storeRoot !== null) targets.push(storeRoot)
   } else if (storeRoot !== null) targets.push(storeRoot)
   if (parsed.global === true) {
     const vxHome = path.join(process.env['HOME'] || homedir(), '.vx')
@@ -338,12 +361,20 @@ async function clear(
       'VX_E_CONFIG',
     )
   }
-  const dry = parsed.dryRun === true
+  const dry = parsed.dry === true
   // `.vx/cache` and the stores are vx's own; any other directory is the
   // user's, cleared entry by entry and removed only if that empties it.
-  const named = path.resolve(dir) === path.join(dotVx, 'cache') ? undefined : path.resolve(dir)
+  // A `.vx/cache` linked to a volume (a CI cache mount) is emptied through
+  // the link: removing the link alone left the cache where it points.
+  const own = path.join(dotVx, 'cache')
+  const named = path.resolve(dir) === own ? undefined : path.resolve(dir)
+  const linked = named === undefined && existsSync(own) && lstatSync(own).isSymbolicLink()
   const entries = (t: string): string[] =>
-    t === named ? vxCacheEntries(t).map((e) => path.join(t, e)) : [t]
+    t === named
+      ? vxCacheEntries(t).map((e) => path.join(t, e))
+      : linked && t === own
+        ? readdirSync(t).map((e) => path.join(t, e))
+        : [t]
   const bytes = doomed.reduce((n, t) => n + entries(t).reduce((m, e) => m + treeBytes(e), 0), 0)
   if (!dry && doomed.length > 0) {
     // A clear beside a run deletes what the run is restoring or saving; it
@@ -360,7 +391,7 @@ async function clear(
   }
   const shown = doomed.map((t) => (path.relative(root, t).startsWith('..') ? t : relPosix(root, t)))
   if (parsed.format === 'json') {
-    const result: ClearResult = { dryRun: dry, cleared: shown, bytesFreed: bytes }
+    const result: ClearResult = { dry: dry, cleared: shown, bytesFreed: bytes }
     process.stdout.write(`${JSON.stringify(result)}\n`)
   } else
     ui.print(

package/src/cli/completions.ts

@@ -5,14 +5,21 @@
 // project names are not (a completion that evaluates configs on every
 // Tab is the wrong price).
 
-import { acceptedFlags, CORE_VERBS, flagHint, seeHelp } from './help.js'
+import { acceptedFlags, CORE_VERBS, flagHint, refuse, seeHelp } from './help.js'
 import { nearest, sayNotice } from '../util/index.js'
+import { setting } from '../settings.js'
+
+function enumValues(path: string): readonly string[] {
+  const kind = setting(path).kind
+  return kind.type === 'enum' ? kind.values : []
+}
 
 /** 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'],
   '--cache-download': ['all', 'toplevel', 'none'],
+  '--schedule': enumValues('run.schedule'),
 }
 
 export type CompletionShell = 'bash' | 'zsh' | 'fish'
@@ -139,12 +146,12 @@ export async function completionsCmd(
   if (args.length !== 1 || !(SHELLS as readonly string[]).includes(shell ?? '')) {
     const flag = args.find((a) => a.startsWith('-'))
     if (flag !== undefined) {
-      sayNotice(
-        'error',
-        'vx completions',
+      return refuse(
+        'completions',
+        args,
         `unknown flag: ${flag}${flagHint('completions', flag)}${seeHelp('completions')}`,
+        'VX_E_USAGE',
       )
-      return 1
     }
     const one = shell !== undefined && args.length === 1
     // One edit: shell names are three or four letters, so two edits took

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,7 +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/',
+    '  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",
@@ -215,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`.',
@@ -253,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.',
@@ -268,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).',
     '',
@@ -298,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')
@@ -317,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,
@@ -337,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`.
  */
@@ -354,9 +381,21 @@ export function flagHint(verb: string, arg: string): string {
   // 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)'
-  // 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}-`))
+  // 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(