@vzn/vx 0.0.645 → 0.0.648

package/src/cache/run-history.ts

@@ -6,18 +6,45 @@
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
 import { lazyStatement } from './schema.js'
 import type { InvocationRecord, RunRecord } from './layer.js'
+import { isMeasure } from '../util/index.js'
 
-const INSERT_RUNS = `
-      INSERT INTO runs(
-        hash, project, task, status, exit_code, duration_ms, forward_args,
-        started_at, ended_at,
-        run_id, cpu_ms, peak_rss_bytes, wallclock_start_ns, wallclock_end_ns,
-        cache_hit, attempts, cached,
-        blocked_by, timed_out, sandbox_violations, not_ready, restored, remote_error
-      )
-      VALUES `
-/** One `runs` row's placeholders: the 23 columns `bindRun` fills. */
-const RUN_TUPLE = `(${Array(23).fill('?').join(', ')})`
+/** The `runs` columns `bindRun` fills, in its order. */
+const RUN_COLUMNS = [
+  'hash',
+  'project',
+  'task',
+  'status',
+  'exit_code',
+  'duration_ms',
+  'forward_args',
+  'started_at',
+  'ended_at',
+  'run_id',
+  'cpu_ms',
+  'peak_rss_bytes',
+  'wallclock_start_ns',
+  'wallclock_end_ns',
+  'cache_hit',
+  'attempts',
+  'cached',
+  'blocked_by',
+  'timed_out',
+  'sandbox_violations',
+  'not_ready',
+  'restored',
+  'remote_error',
+  'peak_cores',
+  'avg_rss_bytes',
+  'placement',
+  'placement_cores',
+  'placement_memory',
+  'keyless_by',
+  'def',
+  'cpu_share',
+]
+
+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 {
@@ -25,14 +52,15 @@ function insertRunsSql(n: number): string {
 }
 
 /**
- * Rows per INSERT: 40 × 23 variables stays under 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).
+ * 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).
  */
-const RUNS_PER_INSERT = 40
+const RUNS_PER_INSERT = Math.floor(999 / RUN_COLUMNS.length)
 
-/** Rows per `task_durations` INSERT: 6 variables each, under 999. */
-const DURATIONS_PER_INSERT = 160
+/** Rows per `task_durations` INSERT: 7 variables each, under 999. */
+const DURATIONS_PER_INSERT = 140
 
 /** Rows per `task_outcomes` INSERT: 6 variables each, under 999. */
 const OUTCOMES_PER_INSERT = 160
@@ -62,6 +90,20 @@ const PASSED_HASHES = `
 /** A local run's `task_durations.source`: its branch, `''` when it had none. */
 export const branchSource = (branch: string | null): string => `branch:${branch ?? ''}`
 
+/**
+ * How long a run would have taken alone: on a crowded worker
+ * (`cpuShare` < 1) each runnable thread waited for a core. A task that
+ * kept `n` cores busy lost its CPU's wait spread over them, under one
+ * core all of it. vx-dte#test (20 s CPU in 75 s) took 81-102 s beside
+ * test shards and the plan, reading those, said 118 s for a 92 s run
+ * (main fd5c72e, 2026-10-23).
+ */
+function aloneMs(r: Pick<RunRecord, 'durationMs' | 'cpuMs' | 'cpuShare'>): number {
+  const { durationMs: d, cpuMs: c, cpuShare: s } = r
+  if (c === undefined || s === undefined || !(s > 0 && s < 1) || !(d > 0)) return d
+  return Math.round(d - (c / s - c) / Math.max(1, c / (d * s)))
+}
+
 export class RunHistory {
   private readonly insertInvocation: ReturnType<Database['prepare']>
 
@@ -105,16 +147,19 @@ export class RunHistory {
       .immediate()
   }
 
-  /** One `task_durations` row per executed success: what a forecast reads. */
+  /** One `task_durations` row per executed success, as if run alone: what a forecast reads. */
   private insertDurations(runs: readonly RunRecord[], source: string, sha: string | null): void {
-    const done = runs.filter((r) => r.status === 'success' && r.cacheHit !== true)
+    const done = runs.filter(
+      (r) => r.status === 'success' && r.cacheHit !== true && isMeasure(aloneMs(r)),
+    )
     for (let i = 0; i < done.length; i += DURATIONS_PER_INSERT) {
       const block = done.slice(i, i + DURATIONS_PER_INSERT)
       const params: SQLQueryBindings[] = []
-      for (const r of block) params.push(r.project, r.task, source, sha, r.durationMs, r.endedAt)
+      for (const r of block)
+        params.push(r.project, r.task, source, sha, aloneMs(r), r.endedAt, r.def ?? null)
       this.db
         .query(
-          `INSERT INTO task_durations(project, task, source, sha, duration_ms, recorded_at) VALUES ${Array(block.length).fill('(?, ?, ?, ?, ?, ?)').join(', ')}`,
+          `INSERT INTO task_durations(project, task, source, sha, duration_ms, recorded_at, def) VALUES ${Array(block.length).fill('(?, ?, ?, ?, ?, ?, ?)').join(', ')}`,
         )
         .run(...params)
     }
@@ -170,7 +215,7 @@ export class RunHistory {
     for (let i = 0; i < runs.length; i += RUNS_PER_INSERT) {
       const block = runs.slice(i, i + RUNS_PER_INSERT)
       const params: SQLQueryBindings[] = []
-      for (const r of block) params.push(...bindRun(r, digest))
+      for (const r of block) for (const v of bindRun(r, digest)) params.push(v)
       // `query` caches by text: one statement for every full block.
       this.db.query(insertRunsSql(block.length)).run(...params)
     }
@@ -233,10 +278,11 @@ export class RunHistory {
     this.db.prepare('DELETE FROM task_durations WHERE recorded_at < ?').run(cutoff)
     this.db.prepare('DELETE FROM task_outcomes WHERE recorded_at < ?').run(cutoff)
     this.db.prepare('DELETE FROM plugin_blobs WHERE at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM remote_hits WHERE seen_at < ?').run(cutoff)
   }
 }
 
-/** Bind a RunRecord to one `RUN_TUPLE`'s 23 positional parameters. */
+/** Bind a RunRecord to one `RUN_TUPLE`'s 29 positional parameters. */
 function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
   return [
     // The ONE place the no-key sentinel is applied, so the column's
@@ -267,6 +313,14 @@ function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBi
     run.notReady ?? null,
     run.restored === undefined ? null : run.restored ? 1 : 0,
     run.remoteError ?? null,
+    run.peakCores ?? null,
+    run.avgRssBytes ?? null,
+    run.placement ?? null,
+    run.placementCores ?? null,
+    run.placementMemoryBytes ?? null,
+    run.keylessBy ?? null,
+    run.def ?? null,
+    run.cpuShare ?? null,
   ]
 }
 

package/src/cache/run-store.ts

@@ -1,4 +1,4 @@
-// What core keeps of a run that writes a remote (owner 2026-10-15): a failed
+// What core keeps of a run that writes a remote (2026-10-15): a failed
 // task's log and the files its outputs left, an uncached task's log. Names
 // come from the run id and task (`run/<id>/<task>/log`); each key is derived
 // in a namespace no task key or plugin entry shares. Remote only: locally
@@ -6,7 +6,7 @@
 // the cache is free). Plugins read them by name (`ctx.cache.getRun`).
 
 import { xxh3hex } from '../util/index.js'
-import type { ResolvedRemote } from './remote-lane.js'
+import { sayRemoteFault, type ResolvedRemote } from './remote-lane.js'
 import { scopedKey } from './scoped-cache.js'
 import { tarPackInto, tarSize } from './tar-stream.js'
 
@@ -30,8 +30,8 @@ export function writesRunStore(remotes: readonly ResolvedRemote[]): boolean {
 
 /**
  * Store `bytes` under `name` in every remote the policy writes. An entry is
- * written once; a remote's failure leaves the others theirs, silently: what
- * a run keeps here is a record, never its verdict.
+ * written once; a remote's failure is said and leaves the others theirs:
+ * what a run keeps here is a record, never its verdict.
  */
 export async function putRunEntry(
   remotes: readonly ResolvedRemote[],
@@ -41,16 +41,17 @@ export async function putRunEntry(
 ): Promise<boolean> {
   const key = scope === undefined ? runKey(name) : scopedKey(scope, runKey(name))
   let kept = false
-  for (const { remote, write } of remotes) {
-    if (!write) continue
+  for (const r of remotes) {
+    if (!r.write) continue
     try {
-      await remote.put(key, new Blob([bytes]), {
+      const put = await r.remote.put(key, new Blob([bytes]), {
         durationMs: 0,
         ...(scope === undefined ? {} : { scope }),
       })
-      kept = true
-    } catch {
-      // the other remotes still keep it
+      // `false`: the remote sent nothing, so nothing is kept there.
+      if (put !== false) kept = true
+    } catch (err) {
+      sayRemoteFault(r, err instanceof Error ? err : new Error(String(err)))
     }
   }
   return kept

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
@@ -101,7 +102,24 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       restored            INTEGER,
       -- v40: each remote read or write of the key that failed, as
       -- 'upload: <message>', '; '-joined; NULL when none did.
-      remote_error        TEXT
+      remote_error        TEXT,
+      -- v43: the most cores one sampling interval burned and the mean
+      -- resident memory over the looks; NULL when nothing sampled.
+      peak_cores          REAL,
+      avg_rss_bytes       INTEGER,
+      -- v44: where an executor ran it (ExecuteResult.where) and that
+      -- machine's cores and memory; NULL = here.
+      placement           TEXT,
+      placement_cores     INTEGER,
+      placement_memory    INTEGER,
+      -- v46: the task with no inputs its key folded (TaskOutcome.keylessBy).
+      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
@@ -152,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,
@@ -269,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.
@@ -280,7 +298,15 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       source      TEXT NOT NULL,
       sha         TEXT,
       duration_ms INTEGER NOT NULL,
-      recorded_at INTEGER NOT NULL
+      recorded_at INTEGER NOT NULL,
+      -- v45: a 'remote' row's measured need (TaskResources); NULL on the
+      -- rest, whose need the run history holds.
+      cpu_parallelism        REAL,
+      peak_rss_bytes         INTEGER,
+      saturated_cores        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);
@@ -292,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.
@@ -314,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/core-alias.ts

@@ -14,12 +14,15 @@
  * 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
  * anyway; the alias makes that a guarantee rather than a layout fact.
+ * The loader is synchronous: the workspace config's bytecode bundle
+ * (workspace/config-bytecode.ts) is CommonJS, and `require` refuses a
+ * module whose loader is async.
  */
-export function registerCoreAlias(load: () => Promise<Record<string, unknown>>): void {
+export function registerCoreAlias(load: () => Record<string, unknown>): void {
   Bun.plugin({
     name: 'vx-core-alias',
     setup(build) {
-      build.module('@vzn/vx', async () => ({ exports: await load(), loader: 'object' }))
+      build.module('@vzn/vx', () => ({ exports: load(), loader: 'object' }))
     },
   })
 }