@vzn/vx 0.0.646 → 0.0.648

package/src/cache/cache.ts

@@ -55,6 +55,7 @@ import { createArtifactTables, createTables, inHashes, lazyStatement } from './s
 import {
   UserError,
   DOT_VX_GITIGNORE,
+  IGNORE_ALL,
   formatBytes,
   isDiskFull,
   isFsRefusal,
@@ -113,10 +114,11 @@ import {
   zstdEncoder,
 } from './zstd.js'
 import { FileHashStore } from './file-hashes.js'
-import { LINK_MODE, OutputIndex } from './output-index.js'
+import { DIR_MODE, LINK_MODE, OutputIndex } from './output-index.js'
 import { RunHistory } from './run-history.js'
 import { CACHE_VERSION, foldKey } from './key-fold.js'
 import { FoldMemo } from './fold-memo.js'
+import { RemoteHits } from './remote-hits.js'
 import { behindLink } from './linked-inputs.js'
 
 /**
@@ -143,7 +145,7 @@ const ADOPT_STATS = 64
  * close, ~30 ms of it. So `accessed_at` trails the last use by at most
  * this much, and the prune policy reads it plus this as the last use:
  * an entry used within the limit is never pruned, and one may stay up to
- * this long past it (owner, 2026-10-08).
+ * this long past it (2026-10-08).
  */
 const ACCESS_REFRESH_MS = 60 * 60 * 1000
 
@@ -162,11 +164,13 @@ const VX_CACHE_NAMES = new Set([
   'cache.db-wal',
   'cache.db-shm',
   'cache.db-journal',
-  'runs',
+  // run-failures.ts, run-steps.ts, orchestrator/lockfile-claim.ts. Run
+  // history lives in cache.db and the config bundle always in
+  // `.vx/cache/compiled`, so a `runs` or `compiled` here is the user's.
   'failures',
+  'steps',
+  'warnings',
   'lockfile-claims',
-  // The workspace config's bytecode bundle (workspace/config-bytecode.ts).
-  'compiled',
 ])
 
 /**
@@ -219,20 +223,28 @@ function unreadableIndexError(dbFile: string, err: unknown): UserError {
  * SQLite reports a descriptor it could not get as `SQLITE_CANTOPEN`, never
  * `EMFILE`, so an open under a low `ulimit -n` reached the user as a bare
  * `vx: SQLiteError: unable to open database file` (D's lead, A-56). One
- * open of a file that exists says which it was.
+ * open of a file that exists says which it was. Any other `CANTOPEN` is
+ * the path itself.
  */
-function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
+function cantOpenIndex(dbFile: string, err: unknown): UserError | undefined {
   const code = (err as { code?: unknown } | null)?.code
   if (typeof code !== 'string' || !code.startsWith('SQLITE_CANTOPEN')) return undefined
   try {
     closeSync(openSync(process.execPath, 'r'))
-    return undefined
   } catch (probe) {
     if (!isOutOfFds(probe)) return undefined
     return new UserError(
       `the cache index ${dbFile} could not be opened (${(err as Error).message}) — ${OUT_OF_FDS_HINT}`,
+      'VX_E_FDS',
     )
   }
+  // Any other: a directory, or a file this user may not open, where the
+  // index goes. It reached every verb as a stack (2026-10-28).
+  return new UserError(
+    `the cache index ${dbFile} could not be opened (${(err as Error).message}) — ` +
+      'it is not a file this user can open; move it away and re-run (vx rebuilds the index)',
+    'VX_E_FS',
+  )
 }
 
 // SCHEMA history (drop+recreate on mismatch; pre-alpha, no migrations):
@@ -335,7 +347,17 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
 //        The cache KEY is unchanged.
 //   v46: runs.keyless_by — the task with no inputs a key folded, so
 //        `vx why` names it. The cache KEY is unchanged.
-export const SCHEMA_VERSION = 'v46'
+//   v47: the store's remote_hits — what a remote's hasMany said it holds,
+//        hits only, so another process trusts it. The cache KEY is
+//        unchanged.
+//   v48: runs.def and task_durations.def — the task's definition
+//        (taskDefinition), so a task whose command changed under the same
+//        name reads none of the old one's timings. The cache KEY is
+//        unchanged.
+//   v49: runs.cpu_share — the share of a core each runnable thread got
+//        where the task ran, so a crowded run's CPU reads as need. The
+//        cache KEY is unchanged.
+export const SCHEMA_VERSION = 'v49'
 
 /**
  * An entry's key components as its one `entry_inputs` row (v34): JSON
@@ -366,6 +388,7 @@ const STORE_TABLES = [
   'task_outcomes',
   'blob_sizes',
   'plugin_blobs',
+  'remote_hits',
   'store_meta',
   'entries',
 ]
@@ -689,7 +712,7 @@ function ensurePrivateDir(dir: string): string | null {
   if ((st.mode & 0o022) !== 0) return `${dir} is writable by other users`
   // The user's own directory open to others (a `~/.vx` made at the
   // default umask, 0755) is vx's to close: refusing it left the store
-  // unused on a stock macOS home (owner, 2026-10-06: "you should own it").
+  // unused on a stock macOS home (2026-10-06: "you should own it").
   if ((st.mode & 0o077) !== 0) {
     try {
       chmodSync(dir, 0o700)
@@ -708,12 +731,11 @@ function ensurePrivateDir(dir: string): string | null {
 // ignored directory is skipped by the walk entirely. Only written when
 // absent, so a user's own file wins.
 const utf8 = new TextEncoder()
-const IGNORE_ALL = '*\n'
 
 /**
  * The ignore file that keeps `cacheDir` out of git, and its text. The
  * default `.vx/cache` is named by `.vx/.gitignore` (`/cache`), committed
- * beside the workspace config and the lock (owner, 2026-10-14); any other
+ * beside the workspace config and the lock (2026-10-14); any other
  * cache directory holds a `*` one of its own. Written only when missing:
  * an existing file is the user's.
  */
@@ -794,15 +816,40 @@ function makeCacheDir(cacheDir: string): void {
   try {
     mkdirSync(cacheDir, { recursive: true })
   } catch (err) {
+    const where = 'set `cache.dir` in .vx/workspace.ts, or pass --cache-dir <path>'
+    const code = (err as NodeJS.ErrnoException).code
+    // A file at the path or at a parent of it: "make the workspace
+    // writable" sent the user to chmod a tree that was writable.
+    if (code === 'EEXIST' || code === 'ENOTDIR') {
+      const file = inTheWay(cacheDir)
+      throw new UserError(
+        `cannot create cache directory ${cacheDir}: ${file} is a file, not a directory — move it away, ${where}`,
+        'VX_E_FS',
+      )
+    }
     // A read-only checkout with no cache yet: every verb opens the cache,
     // so this is the first thing any of them says there.
+    const fix = isDiskFull(err) ? 'free space on that disk' : 'make the workspace writable'
     throw new UserError(
-      `cannot create cache directory ${cacheDir} (${errorText(err)}) — vx keeps its cache there; make ` +
-        `the workspace writable, set \`cache.dir\` in .vx/workspace.ts, or pass --cache-dir <path>`,
+      `cannot create cache directory ${cacheDir} (${errorText(err)}) — vx keeps its cache there; ${fix}, ${where}`,
+      'VX_E_FS',
     )
   }
 }
 
+/** The nearest of `dir` and its parents that exists, as itself (a link is not followed). */
+function inTheWay(dir: string): string {
+  for (let at = dir; ; at = path.dirname(at)) {
+    try {
+      lstatSync(at)
+      return at
+    } catch {
+      // quiet: a missing level is the walk's question, not a fault
+      if (path.dirname(at) === at) return dir
+    }
+  }
+}
+
 function errorText(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }
@@ -903,6 +950,8 @@ export class Cache implements CacheLayer {
   private readonly outputs: OutputIndex
   private readonly folds: FoldMemo
   private readonly history: RunHistory
+  /** What the remotes said they hold, across runs (remote-hits.ts). */
+  readonly remoteHits: RemoteHits
 
   /**
    * Local-layer read/write gates for the task ARTIFACT path only.
@@ -930,7 +979,7 @@ export class Cache implements CacheLayer {
    * Set when THIS open found an index written by another `SCHEMA_VERSION`
    * and dropped every table. The next open sees the current version and
    * reports null. vx prints nothing for it: the cache is vx's to keep
-   * (owner, 2026-10-06).
+   * (2026-10-06).
    */
   readonly schemaReset: SchemaReset | null = null
 
@@ -1016,7 +1065,7 @@ export class Cache implements CacheLayer {
     try {
       this.db = new Database(memory ? ':memory:' : dbFile, { create: true })
     } catch (err) {
-      throw outOfFdsAtOpen(dbFile, err) ?? err
+      throw cantOpenIndex(dbFile, err) ?? err
     }
     // busy_timeout makes concurrent writers wait for the lock instead of
     // failing immediately with SQLITE_BUSY. Two parallel `vx run`
@@ -1035,7 +1084,7 @@ export class Cache implements CacheLayer {
         return read()
       } catch (err) {
         if (!unreadableIndex(err)) {
-          const fds = outOfFdsAtOpen(dbFile, err)
+          const fds = cantOpenIndex(dbFile, err)
           if (fds === undefined) throw err
           try {
             closeDb(this.db)
@@ -1098,8 +1147,8 @@ export class Cache implements CacheLayer {
           | undefined
       )?.value
     // Any other schema is reset by an opener that may write it: the index is
-    // an inventory the artifacts rebuild, whichever vx wrote it (owner,
-    // 2026-10-06; a newer one used to be refused, item 896). A reading verb
+    // an inventory the artifacts rebuild, whichever vx wrote it
+    // (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 !== 'open') {
@@ -1123,7 +1172,7 @@ export class Cache implements CacheLayer {
             // keeps it so).
             if (found !== undefined) {
               this.db.exec(
-                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.task_durations; DROP TABLE IF EXISTS main.plugin_blobs; DROP TABLE IF EXISTS main.task_outcomes; DROP TABLE IF EXISTS main.store_meta; DROP TABLE IF EXISTS main.fold_memo;',
+                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.task_durations; DROP TABLE IF EXISTS main.plugin_blobs; DROP TABLE IF EXISTS main.task_outcomes; DROP TABLE IF EXISTS main.store_meta; DROP TABLE IF EXISTS main.fold_memo; DROP TABLE IF EXISTS main.remote_hits;',
               )
             }
             // The tables land under the same write lock as the stamp: made
@@ -1166,8 +1215,10 @@ export class Cache implements CacheLayer {
           } | null
         )?.value,
     )
+    // A dry prune names what the real one takes, so it reads the store a
+    // run opens (today's), not the one the index last recorded.
     let storeDir =
-      mode !== 'open'
+      mode === 'inspect'
         ? (recorded ?? (typeof storeRoot === 'string' ? storeRoot : undefined))
         : storeRoot === undefined
           ? recorded
@@ -1284,9 +1335,10 @@ export class Cache implements CacheLayer {
     // The slices: each owns its statements over this handle and its table(s);
     // the schema above is the one place every table is declared.
     this.files = new FileHashStore(this.db, cacheDir, this.write, repoDir)
-    this.outputs = new OutputIndex(this.db)
+    this.outputs = new OutputIndex(this.db, this.writeBlocked === null && !this.inspecting)
     this.folds = new FoldMemo(this.db, this.write && !this.inspecting)
     this.history = new RunHistory(this.db, (v) => this.digestValue(v))
+    this.remoteHits = new RemoteHits(this.db, this.writeBlocked === null && !this.inspecting)
 
     // A CACHE_VERSION bump keeps the index but moves every key, so the run
     // after an upgrade misses everything. Roadmap 3.3: that is announced,
@@ -1318,7 +1370,7 @@ export class Cache implements CacheLayer {
    */
   private guard<T>(op: () => T): T {
     const refuse = (err: unknown): never => {
-      throw unreadableIndex(err) ? unreadableIndexError(this.dbFile, err) : err
+      throw unreadableIndex(err) ? unreadableIndexError(this.unreadableFile(), err) : err
     }
     try {
       const out = op()
@@ -1328,6 +1380,24 @@ export class Cache implements CacheLayer {
     }
   }
 
+  /**
+   * Which file a "not a database" answer came from: SQLite does not say,
+   * and the entries live in the attached store, so naming the index alone
+   * sent the user to remove a sound file. Asked only on that refusal.
+   */
+  private unreadableFile(): string {
+    if (this.storeDir === undefined) return this.dbFile
+    const storeFile = path.join(this.storeDir, 'store.db')
+    try {
+      const row = this.db.prepare('PRAGMA store.quick_check(1)').get() as {
+        quick_check?: unknown
+      } | null
+      return row?.quick_check === 'ok' ? this.dbFile : storeFile
+    } catch {
+      return storeFile
+    }
+  }
+
   /**
    * Attach the shared store as `store`, with the pragmas the index takes:
    * WAL for both, so a workspace's run and another's share the store as
@@ -1363,14 +1433,14 @@ export class Cache implements CacheLayer {
       }
       throw unreadableIndex(err)
         ? unreadableIndexError(storeFile, err)
-        : (outOfFdsAtOpen(storeFile, err) ?? err)
+        : (cantOpenIndex(storeFile, err) ?? err)
     }
   }
 
   /**
    * The store is an inventory of the artifacts beside it, and only this vx
    * 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
+   * (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. Creates the store's tables either way.
    */
@@ -1624,8 +1694,8 @@ export class Cache implements CacheLayer {
 
   /**
    * Index an artifact the index does not know, from its own bytes: the
-   * artifact is the record, the index only an inventory of it (owner,
-   * 2026-10-06). A reset index (a `SCHEMA_VERSION` change, a `cache.db` or
+   * artifact is the record, the index only an inventory of it
+   * (2026-10-06). A reset index (a `SCHEMA_VERSION` change, a `cache.db` or
    * `store.db` deleted) loses nothing a task asks for again. The artifact
    * is checked as an ingest checks a remote's (its recorded key, its names
    * against the declared outputs); one that fails is a miss, and the run
@@ -1844,7 +1914,7 @@ export class Cache implements CacheLayer {
 
   /**
    * The subset of `hashes` this store holds, `has` for each: the prefetch
-   * pass asks the remote only about the rest (M, 2026-10-15).
+   * pass asks the remote only about the rest (2026-10-15).
    */
   async localHasMany(hashes: readonly string[]): Promise<Set<string>> {
     const out = new Set<string>()
@@ -1879,7 +1949,7 @@ export class Cache implements CacheLayer {
   loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]> {
     return this.guard(() => this.outputs.loadOutputFilesBatch(hashes))
   }
-  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean> {
+  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): boolean {
     return this.outputs.isOutputsCurrent(projectDir, expected)
   }
   outputsPath(hash: string): string {
@@ -1910,7 +1980,7 @@ export class Cache implements CacheLayer {
   loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
     return this.guard(() => this.outputs.loadOutputDirsBatch(hashes))
   }
-  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
+  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): boolean {
     return this.outputs.outputDirsCurrent(projectDir, rows)
   }
   async restoreOutputs(
@@ -1960,9 +2030,9 @@ export class Cache implements CacheLayer {
         `its outputs hold ${formatBytes(bytes)}, past the ${formatBytes(this.artifactCeiling)} artifact ceiling`,
       )
     }
-    if (await this.copyTree(tree, rows, files, projectDir, accept)) return
+    if (await this.copyTree(hash, tree, rows, files, projectDir, accept)) return
     await extractArtifactStream(
-      packArtifactStream(planOfTree(tree, this.stdoutText(hash))),
+      packArtifactStream(this.treePlan(hash, tree, rows)),
       projectDir,
       workspaceRoot,
       verify,
@@ -1971,6 +2041,23 @@ export class Cache implements CacheLayer {
     )
   }
 
+  /**
+   * The tree packed back into its tar, each file held to its row's size:
+   * the tree form keeps no checksum, and a file cut short at rest (a crash
+   * after its rename, before its data reached the disk) was restored, and
+   * uploaded under a fresh sum.
+   */
+  private treePlan(hash: string, tree: string, rows: readonly OutputFileRow[]): ArtifactPlan {
+    const plan = planOfTree(tree, this.stdoutText(hash))
+    const size = new Map(rows.map((r) => [treeName(r.path), r.size]))
+    for (const i of plan.inputs) {
+      const want = size.get(i.name)
+      if (want !== undefined && want !== i.size)
+        throw new CorruptArtifactError(hash, `${i.name} holds ${i.size} bytes, recorded ${want}`)
+    }
+    return plan
+  }
+
   /**
    * The copy-out: false, having written nothing, where it is not the case it
    * serves. It writes only where nothing stands: each file's place is absent,
@@ -1980,6 +2067,7 @@ export class Cache implements CacheLayer {
    * restore through the tar extractor, ~25 ms a task (2026-10-22).
    */
   private async copyTree(
+    hash: string,
     tree: string,
     rows: readonly OutputFileRow[],
     files: readonly OutputFileRow[],
@@ -2031,6 +2119,34 @@ export class Cache implements CacheLayer {
     const roots = [...made].filter((d) => ![...made].some((o) => d.startsWith(`${o}/`)))
     readUmask()
     const plain = restoredMode(0o666)
+    // Another process's re-save of this key renames the tree aside and a
+    // new one in mid-copy: the files copied after came from another build.
+    // A changed inode is that race, a miss (the task runs), and the entry
+    // the other process saved is kept.
+    const ino = lstatSync(tree).ino
+    const swapped = (): boolean => lstatSync(tree, { throwIfNoEntry: false })?.ino !== ino
+    // A standing directory of this user's that withholds its own write (a
+    // task's `chmod 555 dist/ro`) gets owner write and search for the copy
+    // and its mode back after, as the extractor's rename does: else only
+    // root could restore a file into it, and the hit failed EACCES.
+    const reopened = new Map<string, number>()
+    const reopen = (dir: string): boolean => {
+      if (reopened.has(dir)) return true
+      const st = lstatSync(dir, { throwIfNoEntry: false })
+      if (st?.isDirectory() !== true || st.uid !== process.getuid?.()) return false
+      if ((st.mode & 0o300) === 0o300) return false
+      reopened.set(dir, st.mode & 0o7777)
+      chmodSync(dir, (st.mode & 0o7777) | 0o300)
+      return true
+    }
+    const copy = async (to: string, from: string): Promise<number> => {
+      try {
+        return await Bun.write(to, Bun.file(from), { createPath: false })
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== 'EACCES' || !reopen(path.dirname(to))) throw err
+        return await Bun.write(to, Bun.file(from), { createPath: false })
+      }
+    }
     try {
       const dirs = new Set<string>()
       for (const r of rows) {
@@ -2040,19 +2156,32 @@ export class Cache implements CacheLayer {
       await Promise.all(
         files.map(async (r) => {
           const to = path.join(projectDir, r.path)
-          await Bun.write(to, Bun.file(path.join(tree, treeName(r.path))), { createPath: false })
+          const n = await copy(to, path.join(tree, treeName(r.path)))
+          if (n !== r.size)
+            throw new CorruptArtifactError(hash, `${r.path} holds ${n} bytes, recorded ${r.size}`)
           const mode = restoredMode(r.mode)
           if (mode !== plain) await chmod(to, mode)
           const at = new Date(r.mtimeMs)
           await utimes(to, at, at)
         }),
       )
+      if (swapped()) throw new ArtifactVanishedError(hash)
     } catch (err) {
       await Promise.all([
         ...roots.map((d) => rm(path.join(projectDir, d), { recursive: true, force: true })),
         ...placed.map((f) => rm(path.join(projectDir, f), { force: true })),
       ])
+      if (!(err instanceof ArtifactVanishedError) && swapped())
+        throw new ArtifactVanishedError(hash)
       throw err
+    } finally {
+      for (const [dir, mode] of reopened) {
+        try {
+          chmodSync(dir, mode)
+        } catch {
+          // gone with the task's own cleanup since
+        }
+      }
     }
     return true
   }
@@ -2147,6 +2276,7 @@ export class Cache implements CacheLayer {
       .filter((r) => workspaceRoot !== undefined || !r.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
       .map((r) => (r.path.startsWith(WORKSPACE_OUTPUT_PREFIX) ? r.path : `outputs/${r.path}`))
     endRows()
+    const moded = absentModedDirs(rows, projectDir, workspaceRoot)
     const verify = (provided: ReadonlySet<string>): void => {
       const missing = expected.filter((name) => !provided.has(name))
       if (missing.length > 0) {
@@ -2182,10 +2312,16 @@ export class Cache implements CacheLayer {
         const tar = await decodedTar(inline ?? Bun.file(src), hash, this.artifactCeiling)
         await extractArtifactStream(tar, projectDir, workspaceRoot, verify, accept, workspaceRoot)
       }
+      for (const [dir, mode] of moded) await chmod(dir, restoredMode(mode))
     } catch (err) {
       // A UserError here is the extractor naming the tree's fault (an
       // output directory that links out of the project).
-      if (err instanceof CorruptArtifactError || err instanceof UserError) throw err
+      if (
+        err instanceof CorruptArtifactError ||
+        err instanceof UserError ||
+        err instanceof ArtifactVanishedError
+      )
+        throw err
       // The save and the ingest proved every name safe, so one that reads
       // unsafe now is damaged or tampered bytes: a long name's pax record
       // has no header checksum, and the name is judged before the CRC at
@@ -2264,6 +2400,15 @@ export class Cache implements CacheLayer {
       if (code === 'ENOENT' && (err as NodeJS.ErrnoException).path === src) {
         throw new ArtifactVanishedError(hash)
       }
+      // So is a tree file: a prune or another process's re-save moved the
+      // tree aside mid-copy.
+      if (
+        code === 'ENOENT' &&
+        tree !== undefined &&
+        inTree((err as NodeJS.ErrnoException).path, tree)
+      ) {
+        throw new ArtifactVanishedError(hash)
+      }
       // A staged file the restore itself just wrote is gone before its
       // commit: another process cleaned the same outputs under us (two runs
       // on one workspace, a `vx watch` beside a `vx run` — a clean landing
@@ -2300,7 +2445,7 @@ export class Cache implements CacheLayer {
 
   /**
    * A run over a cache directory it cannot write: one holding entries
-   * serves its hits and saves nothing (M, 2026-10-16), and the line this
+   * serves its hits and saves nothing (2026-10-16), and the line this
    * returns says so; an empty one has nothing to serve and refuses.
    */
   readOnlyNotice(): string | null {
@@ -2320,6 +2465,7 @@ export class Cache implements CacheLayer {
     outputFiles: string[]
     outputDirs?: string[]
     workspaceOutputFiles?: string[]
+    workspaceOutputDirs?: string[]
     workspaceRoot?: string
     inputComponents?: readonly TaskInputRow[]
     /** See `CacheLayer.save`. */
@@ -2410,12 +2556,17 @@ export class Cache implements CacheLayer {
     const pinned = this.tempPath(hash)
     try {
       linkSync(this.tarPath(hash), pinned)
+      // The link shares the artifact's mtime, as adopt's does: an artifact
+      // saved over an hour ago made the pin a crashed save's temp to another
+      // process's orphan sweep, which took it mid-upload.
+      const now = new Date()
+      utimesSync(pinned, now, now)
     } catch (err) {
       const tree = this.treePath(hash)
       if ((err as NodeJS.ErrnoException).code !== 'ENOENT' || !existsSync(tree)) throw err
       // A tree is packed into the artifact a remote expects here, in the
       // upload queue, off the save; a small one in memory.
-      const plan = planOfTree(tree, this.stdoutText(hash))
+      const plan = this.treePlan(hash, tree, this.outputs.rowsOf(hash))
       if (plan.size <= STREAM_DECODE_FROM) {
         const bytes = await zstdCompress(await packArtifactBytes(plan))
         return { body: new Blob([bytes]), release: async () => {} }
@@ -2513,6 +2664,7 @@ export class Cache implements CacheLayer {
     outputFiles: string[]
     outputDirs?: string[]
     workspaceOutputFiles?: string[]
+    workspaceOutputDirs?: string[]
     workspaceRoot?: string
   }): Map<string, string> {
     const outputs = new Map<string, string>()
@@ -2546,6 +2698,7 @@ export class Cache implements CacheLayer {
     outputFiles: string[]
     outputDirs?: string[]
     workspaceOutputFiles?: string[]
+    workspaceOutputDirs?: string[]
     workspaceRoot?: string
   }): Promise<Uint8Array> {
     // stdout is ALWAYS present in the artifact, even if empty, so the
@@ -2568,9 +2721,15 @@ export class Cache implements CacheLayer {
       key: args.hash,
       stdout: args.entry.stdout ?? '',
       outputs: this.outputsOf(args),
-      dirs: args.outputDirs?.map((d) => `outputs/${relPosix(args.projectDir, d)}`),
+      dirs: [
+        ...(args.outputDirs ?? []).map((d) => `outputs/${relPosix(args.projectDir, d)}`),
+        ...(args.workspaceOutputDirs ?? []).map(
+          (d) => `${WORKSPACE_OUTPUT_PREFIX}${relPosix(args.workspaceRoot!, d)}`,
+        ),
+      ],
       exec: usageOfEntry(args.entry),
       root: args.workspaceRoot ?? args.projectDir,
+      projectDir: args.projectDir,
     })
     if (plan.size > this.artifactCeiling) {
       throw new Error(
@@ -2786,7 +2945,7 @@ export class Cache implements CacheLayer {
       throw new CorruptArtifactError(hash, 'artifact is not a readable archive', err)
     }
     const { entries } = scanned
-    const totalBytes =
+    let totalBytes =
       saved !== undefined
         ? saved.bytes
         : compressed instanceof Uint8Array
@@ -2820,6 +2979,12 @@ export class Cache implements CacheLayer {
       tmpPath = undefined
       tree = dir
     }
+    // A tree keeps its files as they are: counted as a saved tree counts
+    // them, not as the archive it was unpacked from (`--max-size`, stats).
+    if (tree !== undefined && saved === undefined) {
+      totalBytes = 0
+      for (const e of entries) totalBytes += e.size
+    }
     const outputFileRows: Array<[string, number, number, number]> = []
     // Per-output-file fingerprint rows feed the skip-restore check.
     // Row paths: project entries store the bare rel (`outputs/`
@@ -2845,15 +3010,21 @@ export class Cache implements CacheLayer {
       outputFileRows.push([rowPath, e.size, e.mode & 0o777, Math.floor(e.mtimeMs)])
     }
     // An empty directory's row is its rel with a trailing slash: the hit's
-    // check asks only that a directory stands there.
-    for (const d of scanned.dirs) {
+    // check asks only that a directory stands there. So is a directory with
+    // a mode to restore, which carries it beside `DIR_MODE`.
+    const dirModes = new Map(scanned.dirModes)
+    const dirRow = (d: string): void => {
+      const mode = dirModes.get(d)
+      dirModes.delete(d)
       outputFileRows.push([
         `${d.startsWith('outputs/') ? d.slice('outputs/'.length) : d}/`,
         0,
-        0,
+        mode === undefined ? 0 : DIR_MODE | mode,
         0,
       ])
     }
+    for (const d of scanned.dirs) dirRow(d)
+    for (const d of [...dirModes.keys()]) dirRow(d)
     // A link's row: its rel, the target's length and CRC-32 where a file
     // has its size and mtime, and the link type in the mode, so the hit's
     // check compares the target and never follows it.
@@ -2931,7 +3102,7 @@ export class Cache implements CacheLayer {
       }
       return moved
     }
-    const tx = this.db.transaction(() => {
+    const index = () => {
       if (inline !== null) {
         aside = moveAside()
         upsertBlob.run(hash, now, inline)
@@ -2977,10 +3148,13 @@ export class Cache implements CacheLayer {
       if (inputComponents !== undefined && inputComponents.length > 0) {
         insertEntryInput.run(hash, encodeEntryInputs(inputComponents))
       }
-    })
+    }
     const endTx = span('save: index tx')
     try {
-      tx.immediate()
+      // Built inside the try: on a database a stopping run closed while a
+      // download streamed in, building it throws, and the temp or tree
+      // the body went to stayed behind.
+      this.db.transaction(index).immediate()
     } catch (err) {
       endTx()
       const left = renamed ?? tree ?? tmpPath
@@ -3063,6 +3237,7 @@ export class Cache implements CacheLayer {
     return this.guard(() => this.history.recordRunBundle(bundle))
   }
   recordRemoteErrors(runId: string, errors: readonly (readonly [string, string])[]): void {
+    if (this.writeBlocked !== null) return
     return this.guard(() => this.history.recordRemoteErrors(runId, errors))
   }
   stats(opts: CacheStatsOptions = {}): CacheStats {
@@ -3110,7 +3285,7 @@ export class Cache implements CacheLayer {
     // orphan rows in either order: landed first, the cascade takes them;
     // landed after, the flush's own entry check drops them (item 628).
     this.outputs.flushOutputDirs()
-    const { olderThanMs, maxBytes, dryRun = false } = options
+    const { olderThanMs, maxBytes, dry = false } = options
     if (olderThanMs === undefined && maxBytes === undefined) {
       throw new Error('prune: pass at least one of `olderThanMs` or `maxBytes`')
     }
@@ -3140,7 +3315,7 @@ export class Cache implements CacheLayer {
     // Promise.all over the unlinks. The hash list binds as one `json_each`
     // parameter, so a huge eviction stays under any build's bound-parameter
     // ceiling.
-    if (dryRun) {
+    if (dry) {
       return { evicted: victims.size, bytesFreed, orphans: picked.files.length, orphanBytes }
     }
     if (victims.size > 0 || stale.length > 0) {
@@ -3181,17 +3356,35 @@ export class Cache implements CacheLayer {
       if (!isIndexFull(err)) throw err
     }
     // History and memo rows a month old go with a prune, never a run's
-    // close: five DELETEs on every run's exit was its slowest step (owner,
-    // 2026-10-18). `invocations` shares the window with `runs`, or `vx last`
+    // close: five DELETEs on every run's exit was its slowest step
+    // (2026-10-18). `invocations` shares the window with `runs`, or `vx last`
     // would list a run whose task rows are gone.
     const cutoff = now - HISTORY_RETENTION_MS
     this.history.pruneOlderThan(cutoff)
     this.files.pruneOlderThan(cutoff)
     this.folds.prune(cutoff)
     const orphans = await this.reapOrphans(picked.files)
+    // An inline artifact's deleted pages go to SQLite's free list and the
+    // file keeps its size: give them back, or the bytes said freed are not.
+    if ([...victims].some((h) => inline.has(h))) this.releaseFreePages()
     return { evicted: victims.size, bytesFreed, ...orphans }
   }
 
+  /** VACUUM the schema holding inline artifacts; busy or no room to rewrite keeps the pages for reuse. */
+  private releaseFreePages(): void {
+    const schema = this.storeDir === undefined ? 'main' : 'store'
+    try {
+      const { freelist_count: free } = this.db.prepare(`PRAGMA ${schema}.freelist_count`).get() as {
+        freelist_count: number
+      }
+      if (free === 0) return
+      this.db.exec(`VACUUM ${schema}`)
+      this.db.exec(`PRAGMA ${schema}.wal_checkpoint(TRUNCATE)`)
+    } catch {
+      // Another process holds the database, or the disk has no room for the copy.
+    }
+  }
+
   /**
    * Unlink the row-less files `pickVictims` took: a `<hash>.tar.zst` with
    * no `entries` row (another vx version's open dropped it, a `cache.db`
@@ -3370,11 +3563,7 @@ export class Cache implements CacheLayer {
   }
 }
 
-/**
- * SQLite's file-control opcode (sqlite3.h). Spelled here, not imported from
- * `bun:sqlite`'s `constants`: the playground bundles this file against a
- * shim that exports only `Database`.
- */
+/** SQLite's file-control opcode (sqlite3.h). */
 const SQLITE_FCNTL_PERSIST_WAL = 10
 
 /**
@@ -3440,6 +3629,32 @@ function assertArtifactNames(
   }
 }
 
+/**
+ * The directories with a mode to restore (`DIR_MODE` rows) that are absent
+ * before the restore, deepest first: the restore makes them with mkdir's
+ * default, and each is then given the mode the miss left, minus the umask
+ * as a file's is. One that stands is the tree's, left as it is. A mode
+ * only ever narrows mkdir's default, whatever an artifact says.
+ */
+function absentModedDirs(
+  rows: readonly OutputFileRow[],
+  projectDir: string,
+  workspaceRoot: string | undefined,
+): Array<[string, number]> {
+  const out: Array<[string, number]> = []
+  for (const r of rows) {
+    if ((r.mode & 0o170000) !== DIR_MODE || !r.path.endsWith('/')) continue
+    const rel = r.path.slice(0, -1)
+    const ws = rel.startsWith(WORKSPACE_OUTPUT_PREFIX)
+    if (ws && workspaceRoot === undefined) continue
+    const dir = ws
+      ? path.join(workspaceRoot!, rel.slice(WORKSPACE_OUTPUT_PREFIX.length))
+      : path.join(projectDir, rel)
+    if (lstatSync(dir, { throwIfNoEntry: false }) === undefined) out.push([dir, r.mode & 0o777])
+  }
+  return out.sort((a, b) => b[0].length - a[0].length)
+}
+
 /** A row's path as the tree names its file. */
 function treeName(rowPath: string): string {
   return rowPath.startsWith(WORKSPACE_OUTPUT_PREFIX) ? rowPath : `outputs/${rowPath}`