@vzn/vx 0.0.651 → 0.0.653

package/src/cache/key-fold.ts

@@ -125,7 +125,7 @@ import type { CacheKeyInput } from './layer.js'
 // a v48 artifact keeps none, and a hit gave `chmod 700 dist/keys` back as 0755.
 // v50: both v49 changes in one build (2026-10-29): a v49 entry was written
 // by a vx that had only one of them.
-export const CACHE_VERSION = 'vx-cache-v51'
+export const CACHE_VERSION = 'vx-cache-v52'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its

package/src/cache/layer.ts

@@ -142,7 +142,8 @@ export interface CacheEntry {
   outputDirRows?: OutputDirRow[]
   /**
    * The task's output log, always present (may be empty): both streams in
-   * the order the run printed them (`orchestrator/output-log.ts`).
+   * the order the run printed them (`orchestrator/output-log.ts`). A local
+   * entry's is a getter that reads it on each access: read it once.
    */
   stdout: string
   storedAt: string
@@ -199,7 +200,7 @@ export interface RunRecord {
   restored?: boolean
   attempts?: number // >1 when the task retried; the direct within-run flaky signal
   /**
-   * Whether the task declared a `cache` block. An uncached task executes
+   * Whether the task declared `cache: true`. An uncached task executes
    * on every run and its key exists only for dependents to fold, so a
    * reader (`vx why`, `vx last`) must not present its re-run as a cache
    * decision. Absent on rows written before the column existed.
@@ -358,7 +359,7 @@ export interface PruneResult {
 
 /**
  * Artifact + `output_files` namespace prefix for workspace-root-
- * anchored outputs (`cache.outputs.workspaceFiles`). Project outputs
+ * anchored outputs (`outputs.workspaceFiles`). Project outputs
  * keep their bare project-relative `path` rows; workspace rows store
  * the full `workspace-outputs/<rel-to-root>` tar entry name as the
  * discriminator — least-invasive row format, no schema change. A
@@ -467,7 +468,7 @@ export interface CacheGetContext {
   taskId: string
   command: string
   /**
-   * The task's declared `cache.outputs`. A remote artifact is ingested
+   * The task's declared `outputs`. A remote artifact is ingested
    * only when every file it carries is one of them: bytes off the network
    * named `outputs/src/in.txt` or `workspace-outputs/.git/hooks/…` wrote
    * an input and a git hook on a green `cache-hit-remote` (item 942).
@@ -511,11 +512,12 @@ export function isIndexFull(err: unknown): boolean {
 }
 
 /**
- * The supplied artifact bytes don't decompress/parse as a vx artifact.
- * Thrown by `save`/`ingest` BEFORE anything reaches the final cache
- * path — a rejected artifact leaves no `<hash>.tar.zst` and no SQL row.
- * The LayeredCache treats this as a remote fault on the remote-hit
- * path (degrades to a cache miss).
+ * Bytes that are not the artifact their key names. Core's ingest throws
+ * it for bytes that do not decompress or parse, before anything is
+ * stored; a remote layer that checks its bytes as they pass (a digest, a
+ * signature) errors its `get` body with it to say they are wrong there,
+ * not cut short. Either way the hit is a miss, and the re-run's save is
+ * sent over that remote's copy.
  */
 export class CorruptArtifactError extends Error {
   constructor(
@@ -528,10 +530,15 @@ export class CorruptArtifactError extends Error {
   }
 }
 
+/** A `CorruptArtifactError` by name: a plugin may load its own copy of core. */
+export function isCorruptArtifact(err: unknown): boolean {
+  return err instanceof Error && err.name === 'CorruptArtifactError'
+}
+
 /**
- * `restoreOutputs` found no artifact where the probe found one: it was
- * removed in between — a `vx cache clean` in another shell, or one for
- * another workspace sharing the cache directory. The
+ * `restoreOutputs` found no artifact where the probe found one: another
+ * process removed or replaced it in between — a prune or a clean for a
+ * workspace sharing the cache directory, a re-save of the key. The
  * bytes are not wrong, they are gone, so the entry is a MISS and the task
  * runs (execute-task.ts); nothing about the cache needs throwing away.
  * Also thrown, with its `reason`, for an artifact whose bytes ARE wrong
@@ -547,7 +554,8 @@ export class ArtifactVanishedError extends Error {
     cause?: unknown,
   ) {
     super(
-      reason ?? `its cache artifact ${hash} vanished before the restore (a vx cache clean)`,
+      reason ??
+        `its cache artifact ${hash} vanished before the restore (another process removed or replaced it)`,
       cause === undefined ? undefined : { cause },
     )
     this.name = 'ArtifactVanishedError'
@@ -804,9 +812,9 @@ export interface CacheLayer {
    */
   ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void>
   /**
-   * The ONE run-history write: a whole `vx run` atomically, the per-task
-   * `runs` rows and the one `invocations` header row — in a SINGLE
-   * transaction (one fsync). Input-fingerprint rows are NOT written here — they
+   * The run-history write at a run's end, atomically: the per-task `runs`
+   * rows (less the hits a `HistoryStream` already wrote) and the one
+   * `invocations` header row — in a SINGLE transaction (one fsync). Input-fingerprint rows are NOT written here — they
    * ride the entry-save transaction (`save`/`ingest`) so a warm
    * all-cache-hit run writes nothing.
    */
@@ -834,6 +842,11 @@ export interface CacheLayer {
   artifactSize?(hash: string): number | undefined
   /** The output files' bytes, uncompressed, of the entry this process just saved; asked once. */
   outputBytes?(hash: string): number | undefined
+  /**
+   * True when the last `save` of `hash` found the key stored and kept that
+   * entry (a `--force` run): nothing of this run's was saved; asked once.
+   */
+  kept?(hash: string): boolean
   prune(options: PruneOptions): Promise<PruneResult>
   close(): void
 }

package/src/cache/layered-cache.ts

@@ -35,7 +35,8 @@ import type {
   SaveArgs,
 } from './cache.js'
 import type { OutputDirRow } from './cache.js'
-import { CorruptArtifactError } from './layer.js'
+import { shareSeenHasher } from './cache.js'
+import { isCorruptArtifact } from './layer.js'
 import { RemoteLane, type ResolvedRemote } from './remote-lane.js'
 import type { PluginSecrets } from '../util/index.js'
 
@@ -182,7 +183,9 @@ export interface RemoteCacheLayer {
    */
   hasMany?(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null>
   /**
-   * Fetch an artifact; `null` = miss. `body` is read once, by core,
+   * Fetch an artifact; `null` = miss, `undefined` = no answer (the layer
+   * is off, its refusal already said): a miss that keeps the hits the
+   * index holds. `body` is read once, by core,
    * straight into the local cache — an HTTP wire returns its `fetch`
    * `Response`, a chunked wire `new Response(stream)`, bytes in hand
    * `new Blob([bytes])`. `durationMs` is the producing task's duration
@@ -190,7 +193,9 @@ export interface RemoteCacheLayer {
    * nothing and the read is a miss, so a layer can check bytes as they pass
    * (a digest, a signature) and refuse at the end.
    */
-  get(hash: string): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
+  get(
+    hash: string,
+  ): Promise<{ body: Blob | Response; durationMs: number | undefined } | null | undefined>
   /**
    * Store an artifact (fire-and-forget from LayeredCache's perspective).
    * `body` is file-backed (`Bun.file`) when the local store holds the
@@ -198,10 +203,14 @@ export interface RemoteCacheLayer {
    * read of it sees the same bytes. An entry is immutable: a `put` of a
    * key the remote holds keeps the stored bytes. Core never asks `has`
    * first; a wire that would overwrite checks inside, unless told `missing`.
+   * `replace`: the remote's copy of `hash` did not read back (a
+   * `CorruptArtifactError`, here or on another machine of the run), so
+   * these bytes go over it; a wire that cannot write over a held key
+   * returns `false`, or the run counts the bad copy fixed.
    * `false`: nothing was sent and nothing failed (a layer that writes
    * nothing this run, such as one with no token), so no upload is counted.
    */
-  put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void | false>
+  put(hash: string, body: Blob, meta: { durationMs: number; replace?: true }): Promise<void | false>
   /**
    * The run found `hash` in no remote, and a `put` of it follows: a wire
    * that checks before it overwrites can skip that request.
@@ -216,6 +225,8 @@ export class LayeredCache implements CacheLayer {
   private readonly lanes: readonly RemoteLane[]
   /** Each key `save` uploaded: whether a remote took it (`uploaded`). */
   private readonly sent = new Map<string, Promise<boolean>>()
+  /** Each key whose stored entry `save` kept, until `kept` answers for it. */
+  private readonly keptHere = new Set<string>()
 
   /**
    * In-flight remote pulls keyed by hash. `prefetch` and `get` both go
@@ -251,6 +262,7 @@ export class LayeredCache implements CacheLayer {
     uploadConcurrency?: number,
   ) {
     this.lanes = remotes.map((r) => new RemoteLane(r, local.traffic, uploadConcurrency))
+    shareSeenHasher(local, this)
   }
 
   // Asked, not kept: a remote whose `open` failed leaves the run after this is built.
@@ -555,7 +567,8 @@ export class LayeredCache implements CacheLayer {
       lane.report('download', hash, err)
       // Bad bytes there: the re-run's save sends good ones over them, or
       // every machine rebuilt the task and none repaired it (2026-10-24).
-      if (err instanceof CorruptArtifactError) lane.distrust(hash)
+      // Core's ingest says so, or the layer's own check of its body does.
+      if (isCorruptArtifact(err)) lane.distrust(hash)
       return false
     } finally {
       this.downloads.delete(hash)
@@ -579,6 +592,10 @@ export class LayeredCache implements CacheLayer {
     return this.local.outputBytes(hash)
   }
 
+  kept(hash: string): boolean {
+    return this.keptHere.delete(hash) || this.local.kept(hash)
+  }
+
   hashFile(filePath: string): Promise<string> {
     return this.local.hashFile(filePath)
   }
@@ -596,6 +613,8 @@ export class LayeredCache implements CacheLayer {
     // Local write honors its own gates inside Cache.save (no-op when local
     // writes are disabled).
     await this.local.save(args)
+    const kept = this.local.kept(args.hash)
+    if (kept) this.keptHere.add(args.hash)
     const writable = this.lanes.filter((l) => l.write)
     if (writable.length === 0) return
     // Write-through upload, OFF the task's critical path: each PUT runs in
@@ -618,9 +637,11 @@ export class LayeredCache implements CacheLayer {
     // while this task's output files are still on disk. Deferring THIS
     // read would pack whatever the tree happens to hold when the job
     // runs. Such a run keeps the old memory profile by necessity — the
-    // bytes exist nowhere else.
+    // bytes exist nowhere else. So with an entry the save kept (`--force`):
+    // its artifact is an older run's, maybe the corrupt one `--force` was
+    // run to replace, and a remote holding none took it for good.
     let packed: Uint8Array | undefined
-    if (!this.local.localWritesEnabled) {
+    if (!this.local.localWritesEnabled || kept) {
       try {
         packed = await this.local.packArtifactBytes(args)
       } catch (err) {

package/src/cache/lockfile-memo.ts

@@ -11,7 +11,8 @@
 import { Database } from 'bun:sqlite'
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { closeDb, SCHEMA_VERSION, SQLITE_FCNTL_PERSIST_WAL } from './cache.js'
+import { closeDb, SCHEMA_VERSION } from './cache.js'
+import { SQLITE_FCNTL_PERSIST_WAL } from './schema.js'
 
 /** One claimant's parse of one lockfile's content. */
 export interface LockfileMemo {

package/src/cache/output-index.ts

@@ -18,6 +18,7 @@ const FILE_PREFIX_MTIME = -2
 import type { Database } from 'bun:sqlite'
 import { inHashes, lazyStatement } from './schema.js'
 import { modeMatches } from './umask.js'
+import { stampGrainMs } from './fs-clock.js'
 import { lstatSync, readdirSync, readlinkSync, statSync } from 'node:fs'
 import path from 'node:path'
 import {
@@ -43,6 +44,15 @@ export const LINK_MODE = 0o120000
  */
 export const DIR_MODE = 0o040000
 
+/**
+ * A file system that keeps whole (or FAT's even) seconds stored a restore's
+ * millisecond "now" as the second it falls in: that stamp, not a write.
+ */
+function secondOf(statMs: number, datedMs: number): boolean {
+  const grain = stampGrainMs(statMs)
+  return grain > 0 && datedMs >= statMs && datedMs - statMs < grain
+}
+
 /** A link row is current while a link with that target stands there; never followed. */
 function linkCurrent(abs: string, e: { size: number; mtimeMs: number }): boolean {
   if (!lstatSync(abs).isSymbolicLink()) return false
@@ -50,6 +60,22 @@ function linkCurrent(abs: string, e: { size: number; mtimeMs: number }): boolean
   return to.byteLength === e.size && Bun.hash.crc32(to) === e.mtimeMs
 }
 
+const FILES_SELECT =
+  'SELECT f.entry_hash, f.path, f.size_bytes, f.mode, f.mtime_ms, s.ino, s.ctime_ms, s.mtime_ms AS stamp_mtime_ms'
+const FILES_STAMPS = 'LEFT JOIN output_stamps s ON s.entry_hash = f.entry_hash AND s.path = f.path'
+const FILES_JOINED = `${FILES_SELECT} FROM json_each(?) q JOIN output_files f ON f.entry_hash = q.value ${FILES_STAMPS}`
+/**
+ * A row as this index loads it: with its stamp, the mtime the file carried
+ * when stamped, which a restore that wrote the file dated now and so is
+ * not the row's saved one.
+ */
+interface StampedRow extends OutputFileRow {
+  stampMtimeMs?: number
+}
+
+const DIRS_JOINED =
+  'SELECT d.entry_hash, d.path, d.mtime_ms FROM json_each(?) q JOIN output_dirs d ON d.entry_hash = q.value'
+
 export class OutputIndex {
   private readonly insertOutputFile: ReturnType<Database['prepare']>
   private readonly deleteOutputFiles: ReturnType<Database['prepare']>
@@ -67,8 +93,12 @@ export class OutputIndex {
    * stage, 47–72 ms at run end (item 622).
    */
   private readonly pendingDirs = new Map<string, Array<[string, number]> | null>()
-  /** Stamps taken and not yet written, flushed with the directory snapshots. */
-  private readonly pendingStamps = new Map<string, Array<[string, number, number]>>()
+  /**
+   * Stamps taken and not yet written, flushed with the directory snapshots:
+   * inode and ctime by path, so a batch read finds a row's stamp without
+   * scanning them all (rows × stamps was ~7 s for a 40,000-file output).
+   */
+  private readonly pendingStamps = new Map<string, Map<string, [number, number, number]>>()
   /**
    * The rows the last batched probe loaded, by hash: a hit's restore and
    * the stamps after it read their rows here instead of the index, twice
@@ -110,7 +140,7 @@ export class OutputIndex {
     this.entryExists = lazyStatement(this.db, 'SELECT 1 FROM entries WHERE hash = ?')
     this.stampOutputFile = lazyStatement(
       this.db,
-      'INSERT INTO output_stamps(entry_hash, path, ino, ctime_ms) VALUES (?, ?, ?, ?) ON CONFLICT(entry_hash, path) DO UPDATE SET ino = excluded.ino, ctime_ms = excluded.ctime_ms',
+      'INSERT INTO output_stamps(entry_hash, path, ino, ctime_ms, mtime_ms) VALUES (?, ?, ?, ?, ?) ON CONFLICT(entry_hash, path) DO UPDATE SET ino = excluded.ino, ctime_ms = excluded.ctime_ms, mtime_ms = excluded.mtime_ms',
     )
     this.deleteStamps = lazyStatement(this.db, 'DELETE FROM output_stamps WHERE entry_hash = ?')
   }
@@ -165,12 +195,24 @@ export class OutputIndex {
     for (const [hash, list] of rows) this.held.set(hash, list)
   }
 
+  /** The probe's rows of `hash` when held: no read. */
+  heldRowsOf(hash: string): readonly OutputFileRow[] | undefined {
+    return this.held.get(hash)
+  }
+
   /** `hash`'s rows: the probe's when held, else read. Path, size, mode and mtime only. */
   rowsOf(hash: string): readonly OutputFileRow[] {
     return this.held.get(hash) ?? this.loadOutputFilesBatch([hash]).get(hash) ?? []
   }
 
-  loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]> {
+  /**
+   * `distinct`: `hashes` as a JSON array with no hash twice, which the probe
+   * has to hand. The rows are then joined from it, not filtered by an `IN`
+   * that builds a lookup of every hash first: ~1.5 ms of 8,002 hits, and as
+   * much again for `loadOutputDirsBatch` (2026-11-07). A repeated hash
+   * would repeat its rows, hence the caller's promise.
+   */
+  loadOutputFilesBatch(hashes: readonly string[], distinct?: string): Map<string, OutputFileRow[]> {
     const out = new Map<string, OutputFileRow[]>()
     if (hashes.length === 0) return out
     // `db.query` (not `db.prepare`) caches the compiled statement keyed by
@@ -180,11 +222,14 @@ export class OutputIndex {
     // the stamps taken, not only the ones flushed: overlaid below from
     // memory. A flush here committed a transaction per read, and a restore
     // reads its rows twice.
-    const { test, params } = inHashes(hashes)
-    const stmt = this.db.query(
-      `SELECT f.entry_hash, f.path, f.size_bytes, f.mode, f.mtime_ms, s.ino, s.ctime_ms FROM output_files f LEFT JOIN output_stamps s ON s.entry_hash = f.entry_hash AND s.path = f.path WHERE f.entry_hash ${test}`,
-    )
-    const rows = stmt.all(...params) as Array<{
+    let sql = FILES_JOINED
+    let params = [distinct!]
+    if (distinct === undefined || hashes.length === 1) {
+      const where = inHashes(hashes)
+      sql = `${FILES_SELECT} FROM output_files f ${FILES_STAMPS} WHERE f.entry_hash ${where.test}`
+      params = where.params
+    }
+    const rows = this.db.query(sql).all(...params) as Array<{
       entry_hash: string
       path: string
       size_bytes: number
@@ -192,6 +237,7 @@ export class OutputIndex {
       mtime_ms: number
       ino: number | null
       ctime_ms: number | null
+      stamp_mtime_ms: number | null
     }>
     for (const r of rows) {
       let list = out.get(r.entry_hash)
@@ -199,31 +245,29 @@ export class OutputIndex {
         list = []
         out.set(r.entry_hash, list)
       }
-      const row: OutputFileRow = {
+      const row: StampedRow = {
         path: r.path,
         size: r.size_bytes,
         mode: r.mode,
         mtimeMs: r.mtime_ms,
       }
-      if (r.ino !== null && r.ctime_ms !== null) {
+      if (r.ino !== null && r.ctime_ms !== null && r.stamp_mtime_ms !== null) {
         row.ino = r.ino
         row.ctimeMs = r.ctime_ms
+        row.stampMtimeMs = r.stamp_mtime_ms
       }
-      const pending = this.pendingStamps.get(r.entry_hash)
-      if (pending !== undefined) {
-        for (const [rel, ino, ctime] of pending) {
-          if (rel !== r.path) continue
-          row.ino = ino
-          row.ctimeMs = ctime
-          break
-        }
+      const stamp = this.pendingStamps.get(r.entry_hash)?.get(r.path)
+      if (stamp !== undefined) {
+        row.ino = stamp[0]
+        row.ctimeMs = stamp[1]
+        row.stampMtimeMs = stamp[2]
       }
       list.push(row)
     }
     return out
   }
 
-  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): boolean {
+  isOutputsCurrent(projectDir: string, expected: readonly StampedRow[]): boolean {
     // Empty manifest case (a task produced no outputs) → trivially
     // current; the on-disk tree under projectDir is whatever it was,
     // and nothing was supposed to land there.
@@ -239,17 +283,20 @@ export class OutputIndex {
       try {
         if (e.mode === LINK_MODE) return linkCurrent(path.join(projectDir, e.path), e)
         const s = statSync(path.join(projectDir, e.path))
-        // An empty output directory: current while a directory stands there.
-        if (e.path.endsWith('/')) return s.isDirectory()
+        // An empty output directory: current while a directory stands there,
+        // with the mode its row records if it records one.
+        if (e.path.endsWith('/'))
+          return (
+            s.isDirectory() && ((e.mode & 0o170000) !== DIR_MODE || modeMatches(s.mode, e.mode))
+          )
         return (
           s.size === e.size &&
           modeMatches(s.mode, e.mode) &&
           // MILLISECOND comparison (sub-ms tolerance for the float
-          // round-trip through utimes). Save rows carry stat-ms and
-          // restoreOutputs re-syncs restored files to the row value,
-          // so equality holds exactly in steady state; legacy
-          // second-precision rows converge on their first restore.
-          Math.abs(s.mtimeMs - e.mtimeMs) < 1 &&
+          // round-trip through utimes), against the mtime the file carried
+          // when stamped: the row's after a save; after a restore, now for
+          // a file it wrote and the file's own where its bytes stood.
+          Math.abs(s.mtimeMs - (e.stampMtimeMs ?? e.mtimeMs)) < 1 &&
           // And the file is the one THIS machine last saw under this
           // entry: two entries whose outputs carry one fixed mtime (a
           // `tar -x`, `cp -p`, SOURCE_DATE_EPOCH) and one size matched
@@ -260,7 +307,8 @@ export class OutputIndex {
           // (an ingest, a changed file at stamping) is never current. The
           // residual: a same-size rewrite, in place or as a new file on the
           // same inode, inside the coarse clock tick of the stamp, with the
-          // mtime forged back.
+          // mtime forged back or written in that tick (a save's or a
+          // restore's file is dated in it).
           e.ino !== undefined &&
           s.ino === e.ino &&
           Math.floor(s.ctimeMs) === e.ctimeMs
@@ -363,16 +411,23 @@ export class OutputIndex {
   }
 
   /**
-   * Stamp `hash`'s rows with each file's inode and ctime, once a save or
-   * a restore has left the tree equal to the entry. A file whose size,
-   * mode or mtime no longer matches its row is left unstamped, so a
-   * write that landed since is never vouched for; the next hit restores.
-   * Written with the directory snapshots, in one transaction.
+   * Stamp `hash`'s rows with each file's inode, ctime and mtime, once a
+   * save or a restore has left the tree equal to the entry. `dated` holds
+   * the mtime a restore left each file with, by row path (now for one it
+   * wrote); any other file is held to its row's. A file whose size, mode or mtime no
+   * longer matches is left unstamped, so a write that landed since is
+   * never vouched for; the next hit restores. Written with the directory
+   * snapshots, in one transaction.
    */
-  recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void {
+  recordOutputStamps(
+    hash: string,
+    projectDir: string,
+    workspaceRoot: string,
+    dated?: ReadonlyMap<string, number>,
+  ): void {
     if (!this.memo) return
     const rows = this.rowsOf(hash)
-    const stamps: Array<[string, number, number]> = []
+    const stamps = new Map<string, [number, number, number]>()
     for (const e of rows) {
       if (e.path.endsWith('/') || e.mode === LINK_MODE) continue
       const ws = e.path.startsWith(WORKSPACE_OUTPUT_PREFIX)
@@ -381,18 +436,19 @@ export class OutputIndex {
         : path.join(projectDir, e.path)
       try {
         const s = statSync(abs)
+        const at = dated?.get(e.path) ?? e.mtimeMs
         if (
           s.size === e.size &&
           modeMatches(s.mode, e.mode) &&
-          Math.abs(s.mtimeMs - e.mtimeMs) < 1
+          (Math.abs(s.mtimeMs - at) < 1 || secondOf(s.mtimeMs, at))
         ) {
-          stamps.push([e.path, s.ino, Math.floor(s.ctimeMs)])
+          stamps.set(e.path, [s.ino, Math.floor(s.ctimeMs), Math.floor(s.mtimeMs)])
         }
       } catch {
         // gone: left unstamped
       }
     }
-    if (stamps.length > 0) this.pendingStamps.set(hash, stamps)
+    if (stamps.size > 0) this.pendingStamps.set(hash, stamps)
   }
 
   /** Land every pending stamp and snapshot in one transaction each; a null snapshot clears its rows. */
@@ -418,7 +474,8 @@ export class OutputIndex {
           for (const [hash, rows] of stamps) {
             // A stamp outlives nothing: an entry pruned since has no rows to vouch for.
             if (this.entryExists.get(hash) === null) continue
-            for (const [rel, ino, ctime] of rows) this.stampOutputFile.run(hash, rel, ino, ctime)
+            for (const [rel, [ino, ctime, mtime]] of rows)
+              this.stampOutputFile.run(hash, rel, ino, ctime, mtime)
           }
         })
         .immediate()
@@ -437,16 +494,21 @@ export class OutputIndex {
     })()
   }
 
-  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
+  /** `distinct` as `loadOutputFilesBatch` takes it. */
+  loadOutputDirsBatch(hashes: readonly string[], distinct?: string): Map<string, OutputDirRow[]> {
     const out = new Map<string, OutputDirRow[]>()
     if (hashes.length === 0) return out
     // A reader in the same process (`vx watch`'s next cycle, a test) sees
     // what was snapshotted, not what was flushed.
     this.flushOutputDirs()
-    const { test, params } = inHashes(hashes)
-    const rows = this.db
-      .query(`SELECT entry_hash, path, mtime_ms FROM output_dirs WHERE entry_hash ${test}`)
-      .all(...params) as Array<{
+    let sql = DIRS_JOINED
+    let params = [distinct!]
+    if (distinct === undefined || hashes.length === 1) {
+      const where = inHashes(hashes)
+      sql = `SELECT entry_hash, path, mtime_ms FROM output_dirs WHERE entry_hash ${where.test}`
+      params = where.params
+    }
+    const rows = this.db.query(sql).all(...params) as Array<{
       entry_hash: string
       path: string
       mtime_ms: number

package/src/cache/plugin-cache.ts

@@ -172,7 +172,7 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
       for (const r of readers) {
         try {
           const got = await r.remote.get(key)
-          if (got === null) continue
+          if (got == null) continue
           const bytes = await capped(got.body)
           if (bytes === null) continue
           if (policy.localWrite) localPut(local, bytes)
@@ -245,7 +245,7 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
         for (const key of runReadKeys(name, scope)) {
           try {
             const got = await r.remote.get(key)
-            if (got === null) continue
+            if (got == null) continue
             const bytes = await capped(got.body, Infinity)
             if (bytes !== null) return bytes
           } catch (err) {

package/src/cache/policy.ts

@@ -1,7 +1,7 @@
 // The run-level cache policy: four axes (local/remote × read/write) and
 // the `--cache-policy=<spec>` grammar that sets them. Pure data + parsing; no I/O.
 
-import { UserError } from '../util/index.js'
+import { nearest, UserError } from '../util/index.js'
 
 /**
  * Independent read/write control over the two cache layers (local +
@@ -63,7 +63,11 @@ export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_PO
     const layer = seg.slice(0, colon)
     const flags = seg.slice(colon + 1)
     if (layer !== 'local' && layer !== 'remote') {
-      throw new UserError(`invalid layer '${layer}': expected 'local' or 'remote'`)
+      const near = nearest(layer, ['local', 'remote'])
+      throw new UserError(
+        `invalid layer '${layer}': expected 'local' or 'remote'` +
+          (near === undefined ? '' : ` — did you mean '${near}'?`),
+      )
     }
     if (seen.has(layer)) {
       throw new UserError(`layer '${layer}' specified twice`)

package/src/cache/remote-lane.ts

@@ -296,6 +296,7 @@ export class RemoteLane {
       this.report('download', hash, err)
       return undefined
     }
+    if (result === undefined) return undefined
     if (!result) {
       // Gone, whatever a probe said: the re-run's save uploads it.
       this.held.delete(hash)
@@ -387,7 +388,8 @@ export class RemoteLane {
         const got = await body()
         release = got.release
         if (known) this.remote.missing?.(hash)
-        if ((await this.remote.put(hash, got.body, { durationMs })) === false) return
+        const meta = distrusted ? { durationMs, replace: true as const } : { durationMs }
+        if ((await this.remote.put(hash, got.body, meta)) === false) return
         holds = true
         tally.count++
         tally.bytes += got.body.size