@vzn/vx 0.0.651 → 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',
@@ -48,21 +48,22 @@ const RUN_COLUMNS = [
   'flaky_failures',
 ]
 
-const INSERT_RUNS = `INSERT INTO runs(${RUN_COLUMNS.join(', ')}) VALUES `
-const RUN_TUPLE = `(${RUN_COLUMNS.map(() => '?').join(', ')})`
-
-/** An INSERT of `n` `runs` rows. */
-function insertRunsSql(n: number): string {
-  return INSERT_RUNS + Array(n).fill(RUN_TUPLE).join(', ')
+/**
+ * An INSERT of `n` `runs` rows over the columns `kept` names (indexes into
+ * `RUN_COLUMNS`); a column it leaves out is NULL, as no `runs` column has
+ * a default.
+ */
+function insertRunsSql(kept: readonly number[], n: number): string {
+  const tuple = `(${kept.map(() => '?').join(', ')})`
+  return `INSERT INTO main.runs(${kept.map((i) => RUN_COLUMNS[i]).join(', ')}) VALUES ${Array(n).fill(tuple).join(', ')}`
 }
 
 /**
- * Rows per INSERT: as many as stay within 999 bound variables, the oldest
- * default ceiling, read off the column count (33 rows were sized for 30
- * columns and bound 1,023 at 31). A statement per row was 8.7 ms of 1,000
- * rows, 40 at a time 6.4 (2026-10-03).
+ * Bound variables per INSERT: within 999, the oldest default ceiling. A
+ * statement per row was 8.7 ms of 1,000 rows, 40 at a time 6.4
+ * (2026-10-03).
  */
-const RUNS_PER_INSERT = Math.floor(999 / RUN_COLUMNS.length)
+const VARIABLES_PER_INSERT = 999
 
 /** Rows per `task_durations` INSERT: 7 variables each, under 999. */
 const DURATIONS_PER_INSERT = 140
@@ -92,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 ?? ''}`
 
@@ -139,14 +144,34 @@ 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()
+  }
+
+  /**
+   * Hits written while the run goes on (history-stream.ts): their rows and
+   * the flaky record's first hit of a key. A hit times nothing, so it
+   * leaves no `task_durations` row; IMMEDIATE, as `recordRunBundle` says.
+   */
+  recordHits(runs: readonly RunRecord[]): void {
+    if (runs.length === 0) return
+    this.db
+      .transaction(() => {
+        this.insertRuns(runs)
         this.insertOutcomes(runs)
       })
       .immediate()
@@ -209,7 +234,13 @@ export class RunHistory {
     }
   }
 
-  /** `runs` as few INSERTs; each distinct forward-args list digested once. */
+  /**
+   * `runs` as few INSERTs; each distinct forward-args list digested once.
+   * Only the columns some row fills are bound: a hit leaves half of them
+   * NULL, and binding 18 of 36 took the 8,002 rows of a warm run from
+   * 31.7 to 24.0 ms alone, the whole record stage 86.8 to 83.3 ms (median
+   * of 15 interleaved runs, 2026-11-06).
+   */
   private insertRuns(runs: readonly RunRecord[]): void {
     const digests = new Map<string, string>()
     const digest = (value: string): string => {
@@ -217,15 +248,41 @@ export class RunHistory {
       if (d === undefined) digests.set(value, (d = this.digestValue(value)))
       return d
     }
-    for (let i = 0; i < runs.length; i += RUNS_PER_INSERT) {
-      const block = runs.slice(i, i + RUNS_PER_INSERT)
+    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
+    const kept: number[] = []
+    for (let c = 0; c < filled.length; c++) if (filled[c]) kept.push(c)
+    const perInsert = Math.floor(VARIABLES_PER_INSERT / kept.length)
+    for (let i = 0; i < bound.length; i += perInsert) {
+      const block = bound.slice(i, i + perInsert)
       const params: SQLQueryBindings[] = []
-      for (const r of block) for (const v of bindRun(r, digest)) params.push(v)
+      for (const row of block) for (const c of kept) params.push(row[c] as SQLQueryBindings)
       // `query` caches by text: one statement for every full block.
-      this.db.query(insertRunsSql(block.length)).run(...params)
+      this.db.query(insertRunsSql(kept, block.length)).run(...params)
     }
   }
 
+  /** 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
@@ -262,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)
@@ -278,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)
@@ -287,8 +352,12 @@ export class RunHistory {
   }
 }
 
-/** Bind a RunRecord to one `RUN_TUPLE`'s positional parameters, in `RUN_COLUMNS` order. */
-function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
+/** A RunRecord as one value per `RUN_COLUMNS` entry, in its order. */
+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.
@@ -304,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

@@ -6,6 +6,9 @@
 
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
 
+/** SQLite's file-control opcode (sqlite3.h). */
+export const SQLITE_FCNTL_PERSIST_WAL = 10
+
 /**
  * A statement prepared on its first `run` or `get`. A warm run executes few
  * of the index's statements, and preparing every one at the open cost each
@@ -20,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`)
@@ -48,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 (
@@ -72,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,
@@ -84,7 +111,7 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       -- v23: attempts a retried task took (>1); NULL for a once-run task.
       -- The direct within-run flaky signal.
       attempts            INTEGER,
-      -- v25: 1 when the task declared a cache block, 0 when it runs every
+      -- v25: 1 when the task declared cache: true, 0 when it runs every
       -- time by design; NULL on rows older than the column.
       cached              INTEGER,
       -- v27: why a task failed or was skipped, as the run's own footer
@@ -132,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):
@@ -153,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
@@ -212,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
@@ -223,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,
@@ -105,7 +114,7 @@ interface PruneArgs {
   format?: 'pretty' | 'json'
   /** `--cache-dir`: prune the cache a run with the same flag uses. */
   cacheDir?: string
-  /** `--global`: clear every repository's store under `~/.vx`. */
+  /** `--global`: clear every workspace's store under `~/.vx`. */
   global?: boolean
   error?: string
 }
@@ -181,7 +190,7 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
   }
   if (out.global === true && (out.olderThanMs !== undefined || out.maxBytes !== undefined)) {
     return {
-      error: `--global clears every repository's store and takes no --older-than or --max-size${seeHelp('cache')}`,
+      error: `--global clears every workspace's store and takes no --older-than or --max-size${seeHelp('cache')}`,
     }
   }
   if (out.global === true && out.cacheDir !== undefined) {
@@ -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