@vzn/vx 0.0.594 → 0.0.595

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.594",
+  "version": "0.0.595",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.594",
-    "@vzn/vx-linux-arm64": "0.0.594",
-    "@vzn/vx-darwin-x64": "0.0.594",
-    "@vzn/vx-darwin-arm64": "0.0.594"
+    "@vzn/vx-linux-x64": "0.0.595",
+    "@vzn/vx-linux-arm64": "0.0.595",
+    "@vzn/vx-darwin-x64": "0.0.595",
+    "@vzn/vx-darwin-arm64": "0.0.595"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/bin.ts

@@ -24,17 +24,10 @@ async function main(): Promise<void> {
     // costs). Registered before any verb runs; the façade loads on first use.
     registerCoreAlias(() => import('./index.js') as Promise<Record<string, unknown>>)
     const code = await run(argv)
-    // NOTHING calls `process.exit` here, and that is the fix rather than a
-    // simplification. Bun drops what a pipe has not yet taken when
-    // `process.exit` follows a large write: 300 KB written then exit
-    // delivered 64 KiB (128 KiB after a tick), and `vx history --format
-    // json` on a 300-project workspace was cut mid-string (2026-09-15).
-    // `stdout.end(cb)` fixed that on 1.4.2 — and on 1.3.11 the callback
-    // still fires early: 2 MiB written, 214 KB delivered (2026-09-20).
-    // Setting the code and letting the loop drain is the one form that
-    // does not depend on when a runtime decides a pipe is flushed; it
-    // costs a hang if a verb leaves a handle open, which the suite's
-    // several hundred spawns of this binary would show at once.
+    // Not `process.exit` here: Bun drops what a pipe has not yet taken
+    // when it follows a large write (300 KB written, 64 KiB delivered;
+    // `vx history --format json` was cut mid-string, 2026-09-15). The code
+    // is set, and `exitOnceFlushed` exits after both streams have ended.
     process.exitCode = code
   } catch (err) {
     const { fsRefusalHint, isFsRefusal, isOutOfFds, isUserError, OUT_OF_FDS_HINT } =
@@ -65,6 +58,28 @@ async function main(): Promise<void> {
     process.exitCode = 1
   }
   settled = true
+  await exitOnceFlushed()
+}
+
+/**
+ * Exit once stdout and stderr have ended, with the code the verb set. A
+ * config can leave a timer behind (a top-level `setInterval`, an await that
+ * hit its evaluation budget), and the loop it holds never drained: vx
+ * printed its verdict and hung for good. Only after `main` has settled, so
+ * `vx watch`, `vx mcp` and a run's kept-alive tasks end when their verb
+ * does. `end(cb)` delivers a large write whole on Bun 1.4.2 (4 MiB under a
+ * slow reader; `write('', cb)` delivered 450 KB), the floor `engines.bun`
+ * holds. A stream whose end never calls back leaves the loop to drain. A
+ * signal's handler exits by itself, with the signal's code.
+ */
+async function exitOnceFlushed(): Promise<void> {
+  if ((await import('./util/index.js')).exitClaimedBySignal()) return
+  let open = 2
+  const ended = (): void => {
+    if (--open === 0) process.exit()
+  }
+  process.stdout.end(ended)
+  process.stderr.end(ended)
 }
 
 // The loop drained while the verb was still pending: something it awaits

package/src/cache/archive.ts

@@ -168,7 +168,7 @@ export interface ExecUsage {
 }
 
 /** One regular file in an artifact, with its restore metadata resolved. */
-export interface ArchiveEntry {
+interface ArchiveEntry {
   /** Full archive-relative name, e.g. `outputs/dist/index.js`. */
   name: string
   size: number
@@ -192,7 +192,7 @@ export class ArchiveSecurityError extends Error {
 }
 
 /** What `packArtifactStream` packs: stdout plus archive name → absolute source path. */
-export interface PackArgs {
+interface PackArgs {
   /** The cache key, recorded in the sidecar (item 943); ingest refuses an artifact without it. */
   key?: string
   stdout: string

package/src/cache/cache.ts

@@ -44,6 +44,7 @@ import {
   openSync,
   readdirSync,
   renameSync,
+  utimesSync,
   writeFileSync,
 } from 'node:fs'
 import { readdir, rm, stat, unlink, writeFile } from 'node:fs/promises'
@@ -242,6 +243,30 @@ export const SCHEMA_VERSION = 'v32'
 /** The tables a store holds: dropped from a workspace index that held them itself. */
 const STORE_TABLES = ['entry_inputs', 'output_files', 'entry_stdout', 'store_meta', 'entries']
 
+/**
+ * An index that records a schema other than this vx's: the one an opener
+ * that writes resets. Reads the recorded version alone and touches
+ * nothing; an unreadable file is left to the open to refuse.
+ */
+function indexOfAnotherSchema(dbFile: string): boolean {
+  let found: string | undefined
+  try {
+    const db = new Database(dbFile, { readonly: true })
+    try {
+      found = (
+        db.query("SELECT value FROM schema_meta WHERE key = 'version'").get() as {
+          value: string
+        } | null
+      )?.value
+    } finally {
+      closeDb(db)
+    }
+  } catch {
+    return false
+  }
+  return found !== undefined && found !== SCHEMA_VERSION
+}
+
 /** An entry row with its stdout, which lives apart (v29); none stored reads as ''. */
 const SELECT_ENTRY =
   "SELECT e.*, COALESCE(s.stdout, '') AS stdout FROM entries e LEFT JOIN entry_stdout s ON s.hash = e.hash"
@@ -608,41 +633,6 @@ export class Cache implements CacheLayer {
     return new Cache(cacheDir, undefined, undefined, undefined, 'inspect')
   }
 
-  /**
-   * What a real prune reaps from an index of an EARLIER schema, which it
-   * resets first, leaving every aged artifact row-less: a dry run that
-   * refused it could not preview the biggest prune there is, the one
-   * after an upgrade (item 1083). Reads the recorded version alone and
-   * touches nothing. Null for an absent, current, newer or unreadable
-   * index; `Cache.inspect` answers those.
-   */
-  static async orphansBeforeReset(
-    cacheDir: string,
-  ): Promise<{ found: string; orphans: number; orphanBytes: number } | null> {
-    const dbFile = path.join(cacheDir, 'cache.db')
-    if (!existsSync(dbFile)) return null
-    let found: string | undefined
-    try {
-      const db = new Database(dbFile, { readonly: true })
-      try {
-        found = (
-          db.prepare("SELECT value FROM schema_meta WHERE key = 'version'").get() as {
-            value: string
-          } | null
-        )?.value
-      } finally {
-        closeDb(db)
-      }
-    } catch {
-      return null
-    }
-    if (found === undefined || found === SCHEMA_VERSION) return null
-    const aged = await scanOrphanFiles(cacheDir, () => new Set())
-    let orphanBytes = 0
-    for (const o of aged) orphanBytes += o.size
-    return { found, orphans: aged.length, orphanBytes }
-  }
-
   constructor(
     private readonly cacheDir: string,
     localPolicy: { read: boolean; write: boolean } = { read: true, write: true },
@@ -655,23 +645,25 @@ export class Cache implements CacheLayer {
      */
     private readonly artifactCeiling: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
     /**
-     * `'inspect'`: a reading verb (`why`, `last`, `info`, a dry prune). It
-     * never resets the index: a schema it cannot read is refused, named,
-     * and left as it was.
+     * `'inspect'`: a reading verb (`why`, `last`, `info`). It never resets
+     * the index: a schema it cannot read is refused, named, and left as it
+     * was. `'preview'`: a dry prune, which reads such an index as the reset
+     * the real prune does first leaves it, empty, with the store still
+     * reached, so it names what that prune takes (item 1083).
      */
-    mode: 'open' | 'inspect' = 'open',
+    mode: 'open' | 'inspect' | 'preview' = 'open',
     /**
      * The shared store's directory, unversioned: every key is seeded with
      * `CACHE_VERSION`, so two vx versions never read each other's entries,
      * and the store's own schema is `store_meta.schema` (`matchStoreSchema`). Or
      * `null` for an index that holds its entries itself (a `cacheDir`).
      * Undefined follows the layout the index records: a reading verb, a
-     * plugin's handle. An `'inspect'` open reads it only where the index
+     * plugin's handle. A reading open reads it only where the index
      * records none (deleted, or never written beside a run's store).
      */
     storeRoot?: string | null,
   ) {
-    this.inspecting = mode === 'inspect'
+    this.inspecting = mode !== 'open'
     this.read = localPolicy.read
     // The directory exists before the DB opens — bun:sqlite won't create
     // parent dirs for us. A directory this user cannot write into is a
@@ -687,7 +679,9 @@ export class Cache implements CacheLayer {
     // said "no recorded runs yet" (item 900).
     const dbFile = path.join(cacheDir, 'cache.db')
     this.dbFile = dbFile
-    const absent = mode === 'inspect' && !existsSync(dbFile)
+    const absent =
+      mode !== 'open' &&
+      (!existsSync(dbFile) || (mode === 'preview' && indexOfAnotherSchema(dbFile)))
     this.writeBlocked = absent ? 'no index there yet' : openCacheDir(cacheDir, repoDir)
     this.write = localPolicy.write && this.writeBlocked === null
     try {
@@ -779,7 +773,7 @@ export class Cache implements CacheLayer {
     // 2026-10-06; a newer one used to be refused, item 896). A reading verb
     // leaves it as it was.
     const refuseUnreadable = (found: string): void => {
-      if (mode === 'inspect') {
+      if (mode !== 'open') {
         throw new UserError(
           `the cache at ${cacheDir} holds index schema ${found} from another vx version; this vx reads ${SCHEMA_VERSION}, so nothing in it is readable here, and this verb leaves it untouched. The next \`vx run\` resets it`,
         )
@@ -833,7 +827,7 @@ export class Cache implements CacheLayer {
         )?.value,
     )
     let storeDir =
-      mode === 'inspect'
+      mode !== 'open'
         ? (recorded ?? (typeof storeRoot === 'string' ? storeRoot : undefined))
         : storeRoot === undefined
           ? recorded
@@ -877,17 +871,10 @@ export class Cache implements CacheLayer {
     this.storeDir = storeDir
     this.artifactDir = storeDir ?? cacheDir
     if (storeDir !== undefined) {
-      this.attachStore(storeDir, mode === 'inspect')
+      this.attachStore(storeDir, mode !== 'open')
       this.storeReset = this.matchStoreSchema(mode === 'open' && this.writeBlocked === null)
-    }
-
-    createTables(this.db, storeDir === undefined ? 'main' : 'store')
-    if (storeDir !== undefined && mode === 'open' && this.writeBlocked === null) {
-      this.db
-        .prepare(
-          "INSERT INTO store.store_meta(key, value) VALUES ('schema', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
-        )
-        .run(SCHEMA_VERSION)
+    } else {
+      createTables(this.db, 'main')
     }
     if (mode === 'open' && this.writeBlocked === null && storeDir !== recorded) {
       if (storeDir === undefined)
@@ -1018,50 +1005,63 @@ export class Cache implements CacheLayer {
    * reads it: a store another `SCHEMA_VERSION` wrote has its tables dropped
    * (owner, 2026-10-06), the artifacts kept. Each is indexed again from its
    * own bytes on its next hit (`adopt`). A reading verb reads such a store
-   * as empty and changes nothing.
+   * as empty and changes nothing. Creates the store's tables either way.
    */
   private matchStoreSchema(writable: boolean): SchemaReset | null {
-    const tables = new Set(
-      (
-        this.db
-          .prepare("SELECT name FROM store.sqlite_master WHERE type = 'table'")
-          .all() as Array<{
-          name: string
-        }>
-      ).map((r) => r.name),
-    )
-    if (!tables.has('entries')) return null
-    const found = tables.has('store_meta')
-      ? (
-          this.db.prepare("SELECT value FROM store.store_meta WHERE key = 'schema'").get() as {
-            value: string
-          } | null
-        )?.value
-      : undefined
-    if (found === SCHEMA_VERSION) return null
+    const read = (): { has: boolean; found: string | undefined } => {
+      const tables = new Set(
+        (
+          this.db
+            .prepare("SELECT name FROM store.sqlite_master WHERE type = 'table'")
+            .all() as Array<{
+            name: string
+          }>
+        ).map((r) => r.name),
+      )
+      const found = tables.has('store_meta')
+        ? (
+            this.db.prepare("SELECT value FROM store.store_meta WHERE key = 'schema'").get() as {
+              value: string
+            } | null
+          )?.value
+        : undefined
+      return { has: tables.has('entries'), found }
+    }
+    const seen = read()
+    if (seen.has && seen.found === SCHEMA_VERSION) {
+      createTables(this.db, 'store')
+      return null
+    }
     if (!writable) {
-      this.db.exec('DETACH DATABASE store')
-      this.db.prepare('ATTACH DATABASE ? AS store').run(':memory:')
+      if (seen.has) {
+        this.db.exec('DETACH DATABASE store')
+        this.db.prepare('ATTACH DATABASE ? AS store').run(':memory:')
+      }
+      createTables(this.db, 'store')
       return null
     }
-    let reset: SchemaReset | null = null
-    this.db
-      .transaction(() => {
-        // Re-read under the write lock: another workspace's open may have
-        // reset it first.
-        const now = (
-          this.db.prepare("SELECT value FROM store.store_meta WHERE key = 'schema'").get() as {
-            value: string
-          } | null
-        )?.value
-        if (now === SCHEMA_VERSION) return
-        for (const t of STORE_TABLES) {
-          if (t !== 'store_meta') this.db.exec(`DROP TABLE IF EXISTS store.${t}`)
+    // Re-read, drop, create and stamp under one write lock: as separate
+    // transactions, another vx's open landing after the drop made its own
+    // tables, and this one's `CREATE IF NOT EXISTS` kept them under its stamp.
+    return this.db
+      .transaction((): SchemaReset | null => {
+        const now = read()
+        let reset: SchemaReset | null = null
+        if (now.has && now.found !== SCHEMA_VERSION) {
+          for (const t of STORE_TABLES) {
+            if (t !== 'store_meta') this.db.exec(`DROP TABLE IF EXISTS store.${t}`)
+          }
+          reset = { from: now.found ?? 'an earlier schema', to: SCHEMA_VERSION }
         }
-        reset = { from: found ?? 'an earlier schema', to: SCHEMA_VERSION }
+        createTables(this.db, 'store')
+        this.db
+          .prepare(
+            "INSERT INTO store.store_meta(key, value) VALUES ('schema', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+          )
+          .run(SCHEMA_VERSION)
+        return reset
       })
       .immediate()
-    return reset
   }
 
   // --- config evaluations: `ConfigEvalStore`, delegated to `ConfigEvalTable` ---
@@ -1222,6 +1222,12 @@ export class Cache implements CacheLayer {
       // A second name for the same bytes: the index step renames it over
       // the artifact inside its write transaction, as for a save.
       linkSync(finalPath, tmpPath)
+      // The link shares the artifact's inode and so its mtime, which an
+      // artifact that needs adopting has had for hours: another process's
+      // orphan sweep read the temp as a crashed save's and took it, and the
+      // artifact with it, while this adopt was scanning them.
+      const now = new Date()
+      utimesSync(tmpPath, now, now)
     } catch {
       return false
     }

package/src/cache/config-evals.ts

@@ -6,6 +6,9 @@
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
 import { lazyStatement } from './schema.js'
 
+const CONFIG_EVALS_SWEPT_AT = 'config_evals_swept_at'
+const DAY_MS = 24 * 60 * 60 * 1000
+
 export class ConfigEvalTable {
   private readonly selectConfigEval: ReturnType<Database['prepare']>
   private readonly insertConfigEval: ReturnType<Database['prepare']>
@@ -106,10 +109,22 @@ export class ConfigEvalTable {
   /**
    * Retention: a row not WRITTEN since `cutoff`. A hit does not refresh it
    * (that would be a write per config on every warm run), so a config that
-   * hit for thirty days is evaluated once more and stored again.
+   * hit for thirty days is evaluated once more and stored again. No index
+   * covers `created_at`, so each sweep reads every row with its JSON (1–6 ms
+   * at 8,000 rows, 2 MB); it runs once a day, on its own clock in
+   * `schema_meta`, as the file-hash sweep does.
    */
-  pruneOlderThan(cutoff: number): void {
-    this.db.prepare('DELETE FROM config_evals WHERE created_at < ?').run(cutoff)
-    this.db.prepare('DELETE FROM config_closures WHERE created_at < ?').run(cutoff)
+  pruneOlderThan(cutoff: number, now: number = Date.now()): void {
+    const last = this.db
+      .prepare('SELECT value FROM schema_meta WHERE key = ?')
+      .get(CONFIG_EVALS_SWEPT_AT) as { value: string } | null
+    if (last !== null && now - Number(last.value) < DAY_MS) return
+    this.db.transaction(() => {
+      this.db.prepare('DELETE FROM config_evals WHERE created_at < ?').run(cutoff)
+      this.db.prepare('DELETE FROM config_closures WHERE created_at < ?').run(cutoff)
+      this.db
+        .prepare('INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)')
+        .run(CONFIG_EVALS_SWEPT_AT, String(now))
+    })()
   }
 }

package/src/cache/git-inputs.ts

@@ -1304,8 +1304,11 @@ export async function startGitEnumeration(
   const facts = repoFacts(workspaceRoot)
   // The blob-size check's verdict is a function of the index's entries, so
   // the index file's bytes key it: one read, where `ls-files --debug` and a
-  // lookup per entry cost 550 ms at 100,000 files (A-60).
-  const pathspecKey = xxh3hex(pathspecs.join('\0'))
+  // lookup per entry cost 550 ms at 100,000 files (A-60). The verdict's
+  // paths are workspace-relative, so the repo→workspace prefix keys it too:
+  // a nested workspace sharing the cache read the outer one's verdict and
+  // trusted a resized blob.
+  const pathspecKey = xxh3hex([facts?.prefix ?? '', ...pathspecs].join('\0'))
   const indexFile =
     facts === null || facts.indexFile === ''
       ? undefined
@@ -1521,9 +1524,10 @@ export async function applyGitEnumeration(
   // Sort once, then each project's files are a contiguous range found
   // by binary search on its `dir/` prefix — O((F+P) log F) instead of
   // the O(P·F) per-project startsWith scan (54 ms at 1090 projects ×
-  // ~9k files; ~5 ms this way). '/' sorts below most filename chars,
-  // so the range [prefix, prefix+'\xff…') is contiguous in the sorted
-  // array; lowerBound on `prefix` and on `prefix + '￿'` bracket it.
+  // ~9k files; ~5 ms this way). Every path under `dir/` sorts in
+  // [`dir/`, `dir0`): '0' is the code unit after '/'. An upper bound of
+  // `dir/` + U+FFFF left out a file whose name starts with U+FFFF, and
+  // it never entered the key.
   // Git lists in order; a list that already is skips the sort.
   let inOrder = true
   for (let i = 1; i < all.length; i++) {
@@ -1557,10 +1561,15 @@ export async function applyGitEnumeration(
     return lo
   }
   for (const projectDir of projectDirs) {
-    const relPrefix =
+    const spelled =
       base !== undefined && projectDir.startsWith(base) && path.normalize(projectDir) === projectDir
         ? projectDir.slice(base.length).replace(/\/$/, '')
         : relPosix(workspaceRoot, projectDir)
+    // macOS git reports paths NFC (core.precomposeunicode) while a dir
+    // discovered by readdir keeps the spelling it was created with: match
+    // NFC, and key the OIDs by the project's spelling, which is how
+    // `resolveFiles` looks them up.
+    const relPrefix = spelled.normalize('NFC')
     if (relPrefix === '' || relPrefix === '.') {
       cache.set(projectDir, all)
       const rootOids = new Map<string, string>()
@@ -1570,14 +1579,16 @@ export async function applyGitEnumeration(
     }
     const prefix = `${relPrefix}/`
     const start = lowerBound(prefix)
-    const end = lowerBound(`${prefix}￿`)
+    const end = lowerBound(`${relPrefix}0`)
     const matches: string[] = []
     const projOids = new Map<string, string>()
+    const projAbs =
+      relPrefix === spelled ? abs : (rel: string) => path.join(projectDir, rel.slice(prefix.length))
     for (let i = start; i < end; i++) {
       const rel = sorted[i]!
       matches.push(rel.slice(prefix.length))
       const oid = trusted.get(rel)
-      if (oid !== undefined) projOids.set(abs(rel), oid)
+      if (oid !== undefined) projOids.set(projAbs(rel), oid)
     }
     // An empty slice is a directory git did not see, not an empty project:
     // a project has at least its package.json, tracked or untracked. A