@vzn/vx 0.0.652 → 0.0.653

package/src/cache/run-history.ts

@@ -8,7 +8,7 @@ import { lazyStatement } from './schema.js'
 import type { InvocationRecord, RunRecord } from './layer.js'
 import { isMeasure } from '../util/index.js'
 
-/** The `runs` columns `bindRun` fills, in its order. */
+/** The `main.runs` columns `bindRun` fills, in its order. */
 const RUN_COLUMNS = [
   'hash',
   'project',
@@ -19,7 +19,7 @@ const RUN_COLUMNS = [
   'forward_args',
   'started_at',
   'ended_at',
-  'run_id',
+  'run',
   'cpu_ms',
   'peak_rss_bytes',
   'wallclock_start_ns',
@@ -55,7 +55,7 @@ const RUN_COLUMNS = [
  */
 function insertRunsSql(kept: readonly number[], n: number): string {
   const tuple = `(${kept.map(() => '?').join(', ')})`
-  return `INSERT INTO runs(${kept.map((i) => RUN_COLUMNS[i]).join(', ')}) VALUES ${Array(n).fill(tuple).join(', ')}`
+  return `INSERT INTO main.runs(${kept.map((i) => RUN_COLUMNS[i]).join(', ')}) VALUES ${Array(n).fill(tuple).join(', ')}`
 }
 
 /**
@@ -93,6 +93,10 @@ const PASSED_HASHES = `
       SELECT j.value AS hash FROM json_each(?) AS j
       WHERE EXISTS (SELECT 1 FROM task_outcomes AS o WHERE o.hash = j.value AND o.status <> 'failed')`
 
+/** The commit a run ran on, as `task_durations` files its timings. */
+type RunHead = Pick<InvocationRecord, 'branch' | 'commitSha'>
+const NO_HEAD: RunHead = { branch: null, commitSha: null }
+
 /** A local run's `task_durations.source`: its branch, `''` when it had none. */
 export const branchSource = (branch: string | null): string => `branch:${branch ?? ''}`
 
@@ -140,14 +144,19 @@ export class RunHistory {
     this.recordRuns([run])
   }
 
-  recordRuns(runs: readonly RunRecord[]): void {
+  /**
+   * Rows with no `invocations` header (a stopped run, item 854). `head` is
+   * the commit the run ran on: its timings file under that branch, as a
+   * finished run's do, or the branch's forecast never reads them.
+   */
+  recordRuns(runs: readonly RunRecord[], head: RunHead = NO_HEAD): void {
     if (runs.length === 0) return
     // One transaction, one fsync: for a 200-task run, one instead of 200.
     // IMMEDIATE, as `recordRunBundle` explains.
     this.db
       .transaction(() => {
         this.insertRuns(runs)
-        this.insertDurations(runs, branchSource(null), null)
+        this.insertDurations(runs, branchSource(head.branch), head.commitSha)
         this.insertOutcomes(runs)
       })
       .immediate()
@@ -239,7 +248,13 @@ export class RunHistory {
       if (d === undefined) digests.set(value, (d = this.digestValue(value)))
       return d
     }
-    const bound = runs.map((r) => bindRun(r, digest))
+    const keys = new Map<string, number>()
+    const key = (runId: string): number => {
+      let k = keys.get(runId)
+      if (k === undefined) keys.set(runId, (k = this.runKey(runId)))
+      return k
+    }
+    const bound = runs.map((r) => bindRun(r, digest, key))
     const filled = RUN_COLUMNS.map(() => false)
     for (const row of bound)
       for (let c = 0; c < row.length; c++) if (row[c] !== null) filled[c] = true
@@ -255,6 +270,19 @@ export class RunHistory {
     }
   }
 
+  /** A run's row in `run_ids`, made on its first rows; inside their transaction. */
+  private runKey(runId: string): number {
+    const found = this.db.query('SELECT id FROM run_ids WHERE run_id = ?').get(runId) as {
+      id: number
+    } | null
+    return (
+      found ??
+      (this.db.query('INSERT INTO run_ids(run_id) VALUES (?) RETURNING id').get(runId) as {
+        id: number
+      })
+    ).id
+  }
+
   recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void {
     // Whole run records atomically — one transaction, one fsync: the
     // per-task `runs` rows and the one `invocations` header. The
@@ -291,7 +319,9 @@ export class RunHistory {
     runId: string,
     errors: readonly (readonly [hash: string, text: string])[],
   ): void {
-    const update = this.db.prepare('UPDATE runs SET remote_error = ? WHERE run_id = ? AND hash = ?')
+    const update = this.db.prepare(
+      'UPDATE main.runs SET remote_error = ? WHERE run = (SELECT id FROM run_ids WHERE run_id = ?) AND hash = ?',
+    )
     this.db
       .transaction(() => {
         for (const [hash, text] of errors) update.run(text, runId, hash)
@@ -307,7 +337,13 @@ export class RunHistory {
    * outlive its rows and `vx last` would list a run whose detail is gone.
    */
   pruneOlderThan(cutoff: number): void {
-    this.db.prepare('DELETE FROM runs WHERE started_at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM main.runs WHERE started_at < ?').run(cutoff)
+    // A run's id goes with its last row; ids only grow, so the oldest kept row bounds them.
+    this.db
+      .prepare(
+        'DELETE FROM run_ids WHERE id < COALESCE((SELECT MIN(run) FROM main.runs), (SELECT MAX(id) + 1 FROM run_ids))',
+      )
+      .run()
     this.db.prepare('DELETE FROM invocations WHERE started_at < ?').run(cutoff)
     this.db.prepare('DELETE FROM task_durations WHERE recorded_at < ?').run(cutoff)
     this.db.prepare('DELETE FROM task_outcomes WHERE recorded_at < ?').run(cutoff)
@@ -317,7 +353,11 @@ export class RunHistory {
 }
 
 /** A RunRecord as one value per `RUN_COLUMNS` entry, in its order. */
-function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
+function bindRun(
+  run: RunRecord,
+  digestValue: (v: string) => string,
+  runKey: (runId: string) => number,
+): SQLQueryBindings[] {
   return [
     // The ONE place the no-key sentinel is applied, so the column's
     // NOT NULL invariant can't be violated from a call site.
@@ -333,7 +373,7 @@ function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBi
     run.forwardArgs ? digestValue(JSON.stringify(run.forwardArgs)) : null,
     run.startedAt,
     run.endedAt,
-    run.runId ?? null,
+    run.runId === undefined ? null : runKey(run.runId),
     run.cpuMs ?? null,
     run.peakRssBytes ?? null,
     run.wallclockStartNs !== undefined ? run.wallclockStartNs : null,

package/src/cache/schema.ts

@@ -23,6 +23,24 @@ export function lazyStatement(db: Database, sql: string): ReturnType<Database['p
   } as unknown as ReturnType<Database['prepare']>
 }
 
+/**
+ * What every reader and `vx last --sql` means by `runs`: the rows with
+ * their run_id, in the columns' old order. TEMP, so no other vx meets it: a
+ * persistent view would fail an older vx's `DROP TABLE runs` when it resets
+ * the index. It shadows main.runs, which only the writers name, so a
+ * VACUUM drops it first: rebuilding `runs_run ON runs(run)` resolves `runs`
+ * to the view and fails ("views may not be indexed").
+ */
+export const RUNS_VIEW = `CREATE TEMP VIEW IF NOT EXISTS runs AS
+  SELECT r.id, r.hash, r.project, r.task, r.status, r.exit_code, r.duration_ms,
+    r.forward_args, r.started_at, r.ended_at, k.run_id, r.cpu_ms, r.peak_rss_bytes,
+    r.wallclock_start_ns, r.wallclock_end_ns, r.cache_hit, r.attempts, r.cached,
+    r.blocked_by, r.timed_out, r.sandbox_violations, r.not_ready, r.restored,
+    r.remote_error, r.peak_cores, r.avg_rss_bytes, r.placement, r.placement_cores,
+    r.placement_memory, r.keyless_by, r.def, r.cpu_share, r.queued_ms,
+    r.output_bytes, r.blocks, r.flaky_passes, r.flaky_failures
+  FROM main.runs r LEFT JOIN main.run_ids k ON k.id = r.run;`
+
 /**
  * Create every table. `store` names the schema holding the ENTRY tables
  * (`entries`, `entry_stdout`, `output_files`, `entry_inputs`, `store_meta`)
@@ -51,15 +69,21 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       accessed_at  INTEGER NOT NULL,
       -- v26: the producing execution's usage, from the artifact's sidecar.
       cpu_ms         INTEGER,
-      peak_rss_bytes INTEGER
+      peak_rss_bytes INTEGER,
+      -- v54: the run whose save or download wrote the entry as it stands
+      -- (created_at is when): \`vx last --log\` shows a run's log from the
+      -- entry only when it holds that run's output.
+      run_id         TEXT
     );
     -- v29: an entry's stdout, which the <hash>.tar.zst artifact also
     -- carries so it survives a remote round trip; a local hit replays it
     -- from here. Its own table: an UPDATE rewrites a whole record, and the
     -- accessed_at bump rewrote up to 16 MB a hit. No row: empty stdout.
+    -- v52: a zstd frame of the UTF-8 (storedLog); as text, logs were most
+    -- of a store's bytes.
     CREATE TABLE IF NOT EXISTS ${store}.entry_stdout (
       hash   TEXT PRIMARY KEY,
-      stdout TEXT NOT NULL,
+      stdout BLOB NOT NULL,
       FOREIGN KEY (hash) REFERENCES entries(hash) ON DELETE CASCADE
     );
     CREATE TABLE IF NOT EXISTS main.runs (
@@ -75,10 +99,10 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       forward_args        TEXT,
       started_at          INTEGER NOT NULL,
       ended_at            INTEGER NOT NULL,
-      -- v11 analytics columns. Nullable until the runner / orchestrator
-      -- PRs populate them. Storing them now means we can swap on the
-      -- producer side without touching the schema again.
-      run_id              TEXT,
+      -- v53: the run's row in run_ids, not its 36-char id: the text
+      -- and its index were a third of what an all-hit run added. The
+      -- \`runs\` view below shows it as run_id again.
+      run                 INTEGER,
       cpu_ms              INTEGER,
       peak_rss_bytes      INTEGER,
       wallclock_start_ns  INTEGER,
@@ -135,7 +159,7 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       flaky_failures      INTEGER
     );
     -- 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
+    -- same run and a started_at newer than everything before it, so
     -- 1,000 inserts touch a handful of leaf pages. The dropped ones did
     -- not — the DROPs shed them from existing databases (a schema-meta
     -- bump is for stored shapes, and an index is not one):
@@ -156,7 +180,13 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     DROP INDEX IF EXISTS main.runs_ended;
     DROP INDEX IF EXISTS main.runs_failed;
     CREATE INDEX IF NOT EXISTS main.runs_started_at ON runs(started_at);
-    CREATE INDEX IF NOT EXISTS main.runs_run_id     ON runs(run_id);
+    CREATE INDEX IF NOT EXISTS main.runs_run        ON runs(run);
+    -- v53: each run's id once; a runs row names it by this rowid.
+    CREATE TABLE IF NOT EXISTS main.run_ids (
+      id     INTEGER PRIMARY KEY,
+      run_id TEXT NOT NULL UNIQUE
+    );
+    ${RUNS_VIEW}
     -- Per-file (mtime, size, content_hash) cache. Lets Cache.key()
     -- skip the content-hash on inputs whose stat hasn't changed
     -- since the last run. Pure performance optimization; the stored
@@ -215,7 +245,9 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
     );
     -- v28, its own table since v32: the inode and ctime THIS workspace saw
-    -- after the save or restore that left the file equal to the entry. No
+    -- after the save or restore that left the file equal to the entry, and
+    -- since v55 its mtime: a restore dates a file it writes now, not with
+    -- the entry's saved mtime, so the row's is not the file's. No
     -- row: never current. Apart from output_files because the entry is
     -- shared and the disk is not: two worktrees on one store overwrote each
     -- other's stamps, and every switch between them restored. No foreign
@@ -226,6 +258,7 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       path        TEXT NOT NULL,
       ino         INTEGER NOT NULL,
       ctime_ms    INTEGER NOT NULL,
+      mtime_ms    INTEGER NOT NULL,
       PRIMARY KEY (entry_hash, path)
     );
     -- Every directory under a whole-subtree output glob, with its mtime

package/src/cli/cache.ts

@@ -1,7 +1,15 @@
-import { existsSync, lstatSync, readdirSync, rmSync } from 'node:fs'
+import {
+  accessSync,
+  constants,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+} from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
-import { Cache, vxCacheEntries } from '../cache/index.js'
+import { Cache, holdCacheDir, holdStore, vxCacheEntries } from '../cache/index.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 import {
   errorCode,
@@ -9,12 +17,13 @@ import {
   nearest,
   parseDuration,
   parseSize,
+  refuseForeignCacheDir,
   relPosix,
   treeBytes,
 } from '../util/index.js'
 import * as ui from '../ui/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
-import { findWorkspaceRoot } from '../workspace/index.js'
+import { findWorkspaceRoot, repoIdsOf } from '../workspace/index.js'
 import {
   cliCacheDir,
   loadCliWorkspace,
@@ -233,16 +242,6 @@ async function cleanCmd(args: readonly string[]): Promise<number> {
     printPruned({ evicted: 0, bytesFreed: 0, orphans: 0, orphanBytes: 0 }, dry, json)
     return 0
   }
-  const cache =
-    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
-  // refused up front with the directory named, as a run refuses it, rather
-  // 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.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
@@ -251,13 +250,37 @@ async function cleanCmd(args: readonly string[]): Promise<number> {
     ? async (): Promise<void> => {}
     : await acquireRunLock(root, { log: warnToStderr })
   try {
-    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.dry) opts.dry = true
-    printPruned(await cache.prune(opts), dry, json)
+    // A run in another checkout of the repository holds no lock of this
+    // one's, and shares the store: the prune waits for every process that
+    // has the store open, then opens its own handle on it. A cache
+    // directory with no store may be another workspace's: the prune holds
+    // it until done, as its runs do.
+    if (!parsed.dry && storeRoot !== null) (await holdStore(storeRoot, warnToStderr))()
+    const releaseDir =
+      !parsed.dry && storeRoot === null
+        ? await holdCacheDir(dir, 'exclusive', warnToStderr)
+        : () => {}
+    const cache =
+      parsed.dry === true
+        ? new Cache(dir, undefined, undefined, undefined, 'preview', storeRoot)
+        : new Cache(dir, undefined, root, undefined, 'open', storeRoot)
+    try {
+      // A prune deletes rows and artifacts; a cache this user cannot write is
+      // refused up front with the directory named, as a run refuses it, rather
+      // 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.dry) cache.assertWritable()
+      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.dry) opts.dry = true
+      printPruned(await cache.prune(opts), dry, json)
+    } finally {
+      cache.close()
+      releaseDir()
+    }
   } finally {
-    cache.close()
     await releaseRunLock()
   }
   return 0
@@ -325,28 +348,36 @@ async function clear(
   const release =
     parsed.dry === true ? async () => {} : await acquireRunLock(root, { log: warnToStderr })
   try {
-    return clearHeld(args, root, dir, storeRoot, parsed)
+    return await clearHeld(args, root, dir, storeRoot, parsed)
   } finally {
     await release()
   }
 }
 
-function clearHeld(
+async function clearHeld(
   args: readonly string[],
   root: string,
   dir: string,
   storeRoot: string | null,
   parsed: PruneArgs,
-): number {
+): Promise<number> {
   // 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[] = []
+  try {
+    refuseForeignCacheDir(dir, root)
+  } catch (err) {
+    if (!isUserError(err)) throw err
+    return refuse('cache clean', args, err.message, errorCode(err))
+  }
   if (existsSync(path.join(dir, 'cache.db'))) {
     // 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)
+      // No store root: given today's, the index answers with it, never
+      // the store it recorded.
+      const cache = new Cache(dir, undefined, undefined, undefined, 'preview')
       store = cache.storeDir
       cache.close()
     } catch (err) {
@@ -354,8 +385,12 @@ function clearHeld(
     }
     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)
+    // cache): the store it names is deleted only when it is one, and this
+    // workspace's: an index copied from another named that one's store.
+    if (store !== undefined && store !== storeRoot && isStore(store)) {
+      const id = path.basename(path.dirname(path.resolve(store)))
+      if ((await repoIdsOf(root)).includes(id)) 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)
@@ -363,13 +398,18 @@ function clearHeld(
   if (parsed.global === true) {
     const vxHome = path.join(process.env['HOME'] || homedir(), '.vx')
     const ids = existsSync(vxHome) ? readdirSync(vxHome) : []
-    for (const id of ids) targets.push(path.join(vxHome, id, 'cache'))
+    // `~/.vx` is not vx's alone to fill: a `cache` directory with no
+    // store.db is someone else's and stays.
+    for (const id of ids) {
+      const store = path.join(vxHome, id, 'cache')
+      if (isStore(store)) targets.push(store)
+    }
   }
   // `cache.dir: '.vx'` (or the root) would take the workspace config and
   // the lock with it.
   const dotVx = path.join(root, '.vx')
-  const doomed = [...new Set(targets.map((t) => path.resolve(t)))].filter((t) => existsSync(t))
-  const unsafe = doomed.find((t) => t === dotVx || !path.relative(t, dotVx).startsWith('..'))
+  const found = [...new Set(targets.map((t) => path.resolve(t)))].filter((t) => existsSync(t))
+  const unsafe = found.find((t) => t === dotVx || !path.relative(t, dotVx).startsWith('..'))
   if (unsafe !== undefined) {
     return refuse(
       'cache clean',
@@ -381,23 +421,69 @@ function clearHeld(
   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.
-  // 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.
+  // A `.vx/cache` linked to a volume (a CI cache mount) is cleared through
+  // the link: removing the link alone left the cache where it points. Only
+  // vx's entries there: emptying it took whatever else the target held.
   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()
+  // Every target is asked before the first delete: a store another user
+  // owns (one `sudo vx run`) failed the clear after `.vx/cache` was gone.
+  // Such a store is left, as runs leave it for `.vx/cache`; a cache
+  // directory this user cannot remove refuses the clear whole.
+  const doomed: string[] = []
+  for (const t of found) {
+    const why = removeBlocked(t, t !== named && !(linked && t === own))
+    if (why === null) doomed.push(t)
+    else if (t !== path.resolve(dir))
+      warnToStderr(`cache store ${t} left as is: this user cannot remove it (${why})`)
+    else
+      return refuse(
+        'cache clean',
+        args,
+        `cache directory ${t} cannot be removed by this user (${why}); nothing was deleted`,
+        'VX_E_FS',
+      )
+  }
   const entries = (t: string): string[] =>
     t === named
       ? vxCacheEntries(t).map((e) => path.join(t, e))
       : linked && t === own
-        ? readdirSync(t).map((e) => path.join(t, e))
+        ? [...vxCacheEntries(t), 'compiled']
+            .map((e) => path.join(t, e))
+            .filter((e) => existsSync(e))
         : [t]
   const bytes = doomed.reduce((n, t) => n + entries(t).reduce((m, e) => m + treeBytes(e), 0), 0)
   if (!dry) {
-    for (const t of doomed) {
-      for (const e of entries(t)) rmSync(e, { recursive: true, force: true })
-      if (t === named && readdirSync(t).length === 0) rmSync(t, { recursive: true })
+    // A run in another checkout of the repository holds no lock of this
+    // one's: each store is deleted once no process has it open, and held
+    // until then; so is a cache directory with no store, which another
+    // workspace's runs may share. In path order, so two clears never wait
+    // on each other.
+    const shared = storeRoot === null ? path.resolve(dir) : undefined
+    const holds: (() => void)[] = []
+    const asides: string[] = []
+    try {
+      for (const t of [...doomed].sort()) {
+        holds.push(await holdStore(t, warnToStderr))
+        if (t === shared) holds.push(await holdCacheDir(t, 'exclusive', warnToStderr))
+      }
+      for (const t of doomed) {
+        for (const e of entries(t)) {
+          // A store leaves its name at once, under the hold, and is deleted
+          // after it. Deleted where it stood, a run in another checkout
+          // opening it mid-delete made a store.db there that the delete then
+          // took, with the entry the run saved.
+          const aside = e === t && t !== path.resolve(dir) ? moveAside(t) : undefined
+          if (aside !== undefined) asides.push(aside)
+          else rmSync(e, { recursive: true, force: true })
+        }
+        if (t === named && readdirSync(t).length === 0) rmSync(t, { recursive: true })
+      }
+    } finally {
+      for (const release of holds) release()
     }
+    for (const aside of asides) rmSync(aside, { recursive: true, force: true })
   }
   const shown = doomed.map((t) => (path.relative(root, t).startsWith('..') ? t : relPosix(root, t)))
   if (parsed.format === 'json') {
@@ -408,10 +494,37 @@ function clearHeld(
       'out',
       freedStatus(dry, bytes, shown.length > 0),
       ...(shown.length > 0 ? [ui.text(...shown)] : []),
+      // The index holds the run history: said where the user decides.
+      ...(doomed.includes(path.resolve(dir))
+        ? [ui.text(`run history ${dry ? 'goes' : 'cleared'} too: vx last and vx why start over`)]
+        : []),
     )
   return 0
 }
 
+/** `dir` renamed beside itself, over a crashed clean's leftover, or undefined where it cannot be. */
+function moveAside(dir: string): string | undefined {
+  const aside = `${dir}.removing`
+  try {
+    rmSync(aside, { recursive: true, force: true })
+    renameSync(dir, aside)
+    return aside
+  } catch {
+    return undefined
+  }
+}
+
+/** Why this user cannot remove `t` (`whole`) or empty it, or null. */
+function removeBlocked(t: string, whole: boolean): string | null {
+  try {
+    accessSync(t, constants.R_OK | constants.W_OK | constants.X_OK)
+    if (whole) accessSync(path.dirname(t), constants.W_OK | constants.X_OK)
+    return null
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code ?? String(err)
+  }
+}
+
 /** A store's shape: `<home>/.vx/<id>/cache` holding its `store.db`. */
 function isStore(stored: string): boolean {
   const dir = path.resolve(stored)

package/src/cli/completions.ts

@@ -48,7 +48,7 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
     verb: v,
     // A plugin verb owns its own arguments; only `--help` is known here.
     words: [
-      ...(VERB_WORDS[v] ?? []),
+      ...(v === 'help' ? verbs.filter((w) => w !== 'help') : (VERB_WORDS[v] ?? [])),
       ...((CORE_VERBS as readonly string[]).includes(v) ? verbFlags(v) : ['--help']),
     ],
   }))
@@ -155,7 +155,7 @@ export async function completionsCmd(
         'VX_E_USAGE',
       )
     }
-    const one = shell !== undefined && args.length === 1
+    const one = shell !== undefined && shell !== '' && args.length === 1
     // One edit: shell names are three or four letters, so two edits took
     // `tcsh` to `bash`, a different shell.
     const best = one ? nearest(shell, SHELLS, 1) : undefined

package/src/cli/core-alias.ts

@@ -9,7 +9,10 @@
  * and two module states — two `definePlugin` memos, two of everything
  * keyed by identity rather than by registry symbol.
  *
- * The alias is a Bun virtual module for the exact specifier `@vzn/vx`,
+ * The alias is a Bun virtual module for the exact specifiers `@vzn/vx`
+ * and `@vzn/vx/config` (the second for `import { defineProject }` in a
+ * config: with a node_modules and no `@vzn/vx` in it, the import failed
+ * though the page says vx runs a config without it),
  * served from the host's own façade, loaded lazily on the first import
  * so a verb that never loads a plugin never loads the façade. The
  * source form (`bun src/bin.ts`) resolves the specifier to the same file
@@ -18,11 +21,15 @@
  * (workspace/config-bytecode.ts) is CommonJS, and `require` refuses a
  * module whose loader is async.
  */
-export function registerCoreAlias(load: () => Record<string, unknown>): void {
+export function registerCoreAlias(
+  load: () => Record<string, unknown>,
+  loadConfig: () => Record<string, unknown>,
+): void {
   Bun.plugin({
     name: 'vx-core-alias',
     setup(build) {
       build.module('@vzn/vx', () => ({ exports: load(), loader: 'object' }))
+      build.module('@vzn/vx/config', () => ({ exports: loadConfig(), loader: 'object' }))
     },
   })
 }

package/src/cli/docs.ts

@@ -31,10 +31,12 @@ export 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)
-      if (v === undefined || v === '') {
+      // The space form took the next flag as the count and refused it as one.
+      const flag = a === '--limit' && v !== undefined && /^-\D/.test(v) ? ` (got flag ${v})` : ''
+      if (v === undefined || v === '' || flag !== '') {
         return {
           ...out,
-          error: `--limit requires a value: a whole number above 0${seeHelp('docs')}`,
+          error: `--limit requires a value: a whole number above 0${flag}${seeHelp('docs')}`,
         }
       }
       const n = parseDecimalInt(v)

package/src/cli/help.ts

@@ -90,12 +90,33 @@ export function verbHelpText(verb: string): string {
       if (own.length > 0) kept.push(['Usage:', ...own].join('\n'))
       continue
     }
-    if (lines.some(names)) kept.push(block)
+    if (lines.some(names)) kept.push(own(lines, names, quoted))
   }
   if (kept.length === 0) return helpText()
   return [title, ...kept, 'Full reference: vx help', ''].join('\n\n')
 }
 
+/**
+ * A section's entries for one verb, when the section holds several verbs'
+ * entries (Introspection): an entry is a two-space line and the deeper
+ * lines under it; a shared one (`info, why and last:`) stays if it names
+ * the verb. A one-verb or `(for <verb>)` section stays whole.
+ */
+function own(lines: string[], names: (line: string) => boolean, quoted: string): string {
+  const entries: string[][] = []
+  for (const line of lines.slice(1)) {
+    if (/^ {2}\S/.test(line) || entries.length === 0) entries.push([line])
+    else entries.at(-1)!.push(line)
+  }
+  const verbs = new Set(entries.map((e) => /^ {2}vx ([\w-]+)/.exec(e[0]!)?.[1]).filter(Boolean))
+  if (verbs.size < 2) return lines.join('\n')
+  const word = new RegExp(`\\b${quoted}\\b`)
+  const mine = entries.filter(
+    (e) => names(e[0]!) || (!e[0]!.startsWith('  vx ') && word.test(e[0]!)),
+  )
+  return [lines[0]!, ...mine.flat()].join('\n')
+}
+
 export function helpText(pluginCommands: readonly string[] = []): string {
   return [
     'vx — task orchestration you own',
@@ -141,7 +162,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --no-cache                  No cache reads or writes; outputs are left',
     '                                  alone.',
     '      --force                     Skip cache reads but still write: every task',
-    '                                  runs and refreshes its entry.',
+    '                                  runs; a key already stored is kept.',
     '      --cache-policy <spec>       Per-layer read/write: a comma list of',
     '                                  <layer>:<flags> (layer local or remote, flags',
     '                                  from rw). A named layer is set to exactly its',
@@ -366,6 +387,8 @@ 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?)'
+  // pnpm's and Turbo's short `--filter`.
+  if (name === '-F') return flags.includes('--filter') ? ' (did you mean --filter?)' : ''
   // `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'))