@vzn/vx 0.0.645 → 0.0.648

package/src/cache/key-fold.ts

@@ -1,9 +1,7 @@
 // The cache key, derived: `foldKey` is the whole of what `Cache.key` computes,
 // with the two things it read off the class (the file hasher and the
 // workspace-relative path) passed in. Nothing here touches a store, so the
-// fold runs wherever xxh3 does: the CLI, a remote layer, and the site's
-// playground, which bundles this file to derive the keys the CLI would
-// (design/playground-spike-2026-09.md, P1; item 691).
+// fold runs wherever xxh3 does: the CLI and a remote layer (item 691).
 
 import { xxh3, xxh3hex } from '../util/index.js'
 import type { CacheKeyInput } from './layer.js'
@@ -113,14 +111,21 @@ import type { CacheKeyInput } from './layer.js'
 // v44: the sidecar lists the empty directories under the outputs; a v43
 // artifact holds none and a hit left them out (Growth's parity, 2026-10-16).
 // v45: the sidecar lists the symlinks under the outputs and a hit makes
-// them; a v44 artifact holds a link as a copy of its target (M, 2026-10-16).
+// them; a v44 artifact holds a link as a copy of its target (2026-10-16).
 // v46: vx's names are reserved only at the project root; a v45 artifact
 // left out a build's own `dist/.git/**`, `dist/.vx/**` and nested
 // `vx.lock.json` (Growth's parity, 2026-10-17).
 // v47: the local store keeps plain files (`cache.store`).
-// v48: a task glob is standard again (M, 2026-10-18): `app/[id]/page.js` is
+// v48: a task glob is standard again (2026-10-18): `app/[id]/page.js` is
 // a class, and a v47 entry under its unchanged key holds the literal route.
-export const CACHE_VERSION = 'vx-cache-v48'
+// v49: each brace alternative is read alone (2026-10-28): a v48 entry for
+// `outputs: ['{dist,lib}']` under its unchanged key holds nothing.
+// v49, on another branch at once: the sidecar keeps the mode of an output
+// directory that withholds a permission 0755 grants, and a hit makes it so;
+// 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'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its
@@ -321,5 +326,9 @@ export function foldHead(
       for (const [n, v] of pluginParts) cap.push({ kind: 'plugin', name: n, hash: digestValue(v) })
     }
   }
+  if (input.platform !== undefined) {
+    h = xxh3(`platform:${input.platform}`, h)
+    if (cap) cap.push({ kind: 'platform', name: 'platform', hash: input.platform })
+  }
   return h
 }

package/src/cache/layer.ts

@@ -89,6 +89,12 @@ export interface CacheKeyInput {
    * derives exactly the key it always did.
    */
   pluginParts?: ReadonlyArray<readonly [name: string, value: string]>
+  /**
+   * The platform a task that declares `exec.platforms` runs on: its
+   * outputs are that platform's. Folded only when set, so a task that
+   * declares none derives the key it always did.
+   */
+  platform?: string
   /**
    * When set, `key()` pushes each component (kind, name, hash) it folds
    * — at the same fold sites, in fold order. Pure SIDE-CHANNEL: it does
@@ -212,6 +218,20 @@ export interface RunRecord {
   notReady?: 'timeout' | 'exited' | 'spawn'
   /** Each remote read or write of its key that failed, `upload: <message>`, `; `-joined (v40). */
   remoteError?: string
+  /** The sampled peak cores and mean resident memory of the run (v43). */
+  peakCores?: number
+  avgRssBytes?: number
+  /** Where an executor ran it (`small#1`); absent = here (v44). */
+  placement?: string
+  /** The task with no `inputs` its key folded, so it never read or saved (v46). */
+  keylessBy?: string
+  /** The task's definition (`taskDefinition`): what its history is kept under (v48). */
+  def?: string
+  /** That machine's cores and memory (v44). */
+  placementCores?: number
+  placementMemoryBytes?: number
+  /** The share of a core each runnable thread got there (`ExecuteResult.machine.cpuShare`, v49). */
+  cpuShare?: number
 }
 
 /**
@@ -307,7 +327,7 @@ export interface PruneOptions {
    * Pick the victims and count the orphans, delete nothing: the result
    * says what a real prune with the same policy would reap right now.
    */
-  dryRun?: boolean
+  dry?: boolean
 }
 
 export interface PruneResult {
@@ -384,6 +404,13 @@ export interface OutputDirRow {
  */
 export const OUTPUT_DIRS_CAP = 8192
 
+/**
+ * `mtime_ms` of the one row a snapshot over `OUTPUT_DIRS_CAP` leaves: never
+ * current, so the hit walks, and it tells the hit not to snapshot again.
+ * Cleared rows sent every hit through the walk AND a capped snapshot.
+ */
+export const OUTPUT_DIRS_OVER_CAP = -3
+
 /**
  * A directory whose mtime lies within this many ms of the snapshot is RACY
  * and the whole snapshot is dropped. File timestamps are coarse on Linux
@@ -557,12 +584,28 @@ export interface CacheLayer {
    * batch omits it and the prefetch pass falls back to per-hash GETs.
    */
   remoteHasMany?(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null>
+  /**
+   * `remoteHasMany`, with a remote that answers no batch query asked each
+   * key, `concurrency` at a time: a complete answer or `null`. For a run
+   * that plans on the answer (an executor's demand); others pull instead.
+   */
+  remoteHasEach?(
+    hashes: readonly string[],
+    concurrency: number,
+  ): Promise<Map<string, ArtifactInfo> | null>
   /**
    * The subset of `hashes` the local store already holds. The prefetch
    * pass probes the remote only for the rest, so a run the local cache
    * answers makes no remote call. Absent reads as "none held".
    */
   localHasMany?(hashes: readonly string[]): Promise<Set<string>>
+  /**
+   * The subset of `hashes` a remote said it holds, as the local index
+   * keeps it across runs and processes: trusted now, with no round-trip.
+   * A pull of one starts at once, waiting on no batch probe. Absent, a
+   * run learns its remote hits from `remoteHasMany` alone.
+   */
+  remoteKnown?(hashes: readonly string[]): Map<string, ArtifactInfo>
   /**
    * Record that the remote has NO artifact for each of `hashes` (from a
    * batch probe), so a later `get`/`prefetch` short-circuits to a miss with
@@ -576,12 +619,6 @@ export interface CacheLayer {
    * `hasRemote`.
    */
   probeBeforeUpload?(hashes: Promise<readonly string[]>): void
-  /**
-   * The run's batch probe starts when `started` settles: until then a pull
-   * waits, so a lookup that lands first does not GET a key the probe is
-   * about to call absent. Only meaningful with `hasRemote`.
-   */
-  probeFirst?(started: Promise<void>): void
   /**
    * Resolve once every background write-through upload settles. The
    * orchestrator awaits it before `close()` — an upload reading layer state
@@ -593,6 +630,28 @@ export interface CacheLayer {
   stopUploads?(): void
   key(input: CacheKeyInput): Promise<string>
   get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
+  /**
+   * `get` past the run's read policy: an entry a machine running a task
+   * for this run saved is the run's own work, not a hit (`TaskArtifacts`).
+   * A layer without it is read through `get`.
+   */
+  getSaved?(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
+  /**
+   * True once a remote the run reads holds entry `hash`, the local entry
+   * uploaded to those it writes when none does (`TaskArtifacts.share`). A
+   * layer without it shares nothing.
+   */
+  share?(hash: string): Promise<boolean>
+  /**
+   * The local entry uploaded over each written remote's copy, which another
+   * machine found corrupt (`TaskArtifacts.resend`). True when one took it.
+   */
+  resend?(hash: string): Promise<boolean>
+  /**
+   * Whether a remote this run writes took entry `hash` when `save` uploaded
+   * it, or already held it; undefined when this run sent it to none.
+   */
+  uploaded?(hash: string): Promise<boolean | undefined>
   /**
    * Optional batched `get` (same answers, fewer round trips). The
    * short-circuit probe uses it when a layer offers one; a layer without it
@@ -647,12 +706,12 @@ export interface CacheLayer {
    * out-of-band file edits or deletions and falls through to a real
    * restore.
    */
-  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean>
+  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): boolean
   /**
    * The directory-mtime short-circuit behind a warm hit (optional — a layer
    * without it keeps the output walk). `recordOutputDirs` snapshots every
-   * directory under each of `prefixes` (project-relative, whole-subtree
-   * globs only — see `wholeSubtreePrefixes`) after a save or restore;
+   * directory under each of `prefixes` (project-relative, `''` the project
+   * itself — see `outputDirPrefixes`) after a save or restore;
    * `loadOutputDirsBatch` reads them back; `outputDirsCurrent` is true iff
    * every recorded directory still carries its recorded mtime, which proves
    * no file was added or removed anywhere the glob could see. Machine-local
@@ -676,7 +735,7 @@ export interface CacheLayer {
    */
   recordOutputStamps?(hash: string, projectDir: string, workspaceRoot: string): void
   loadOutputDirsBatch?(hashes: readonly string[]): Map<string, OutputDirRow[]>
-  outputDirsCurrent?(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean>
+  outputDirsCurrent?(projectDir: string, rows: readonly OutputDirRow[]): boolean
   /**
    * Extract the artifact's `outputs/` entries into `projectDir` and —
    * when `workspaceRoot` is given — its `workspace-outputs/` entries
@@ -713,6 +772,8 @@ export interface CacheLayer {
      * format.
      */
     workspaceOutputFiles?: string[]
+    /** The empty directories under `workspaceOutputFiles`' globs (absolute). */
+    workspaceOutputDirs?: string[]
     workspaceRoot?: string
     /**
      * Cache-key components for this entry (the Tier-3 input
@@ -722,6 +783,8 @@ export interface CacheLayer {
      * Only computed on the miss/save path — never on a hit.
      */
     inputComponents?: readonly TaskInputRow[]
+    /** No remote held `hash` when the run asked: an upload asks none first. */
+    absent?: boolean
   }): Promise<void>
   /**
    * Adopt an artifact produced elsewhere — the remote-hit path. Streams

package/src/cache/layered-cache.ts

@@ -35,6 +35,7 @@ import type {
   SaveArgs,
 } from './cache.js'
 import type { OutputDirRow } from './cache.js'
+import { CorruptArtifactError } from './layer.js'
 import { RemoteLane, type ResolvedRemote } from './remote-lane.js'
 import type { PluginSecrets } from '../util/index.js'
 
@@ -57,6 +58,7 @@ function endsOnStop(
   // which the flag turns into an error rather than a short body.
   void stopped.then(() => {
     stop = true
+    // quiet: stopping: a reader already done has nothing to cancel
     void reader.cancel().catch(() => undefined)
   })
   const stream = new ReadableStream<Uint8Array>({
@@ -80,6 +82,15 @@ const judged = (i: ArtifactInfo): i is { size: number; durationMs: number } =>
 /** How often a task waiting on its download weighs running instead. */
 const JUDGE_EVERY_MS = 25
 
+/**
+ * The least a download is given against running its task. A stored
+ * duration is the command's alone, in whole ms (Turbo's wire sends 0 for
+ * a sub-ms task), and a budget under one weighing is none: a duration of
+ * 0 gave up every body not in by the first, 99% in or not, and ran the
+ * task beside the bytes already here.
+ */
+const LEAST_BUDGET_MS = JUDGE_EVERY_MS
+
 interface Download {
   readonly start: number
   received: number
@@ -104,6 +115,13 @@ export interface ArtifactInfo {
   readonly durationMs?: number
 }
 
+/** A run's access to a remote, lent to a machine that runs its tasks (`RemoteCacheLayer.lend`). */
+export interface LentAccess {
+  readonly token: string
+  /** Epoch ms; asked again before it. */
+  readonly expiresAt?: number
+}
+
 /**
  * What a remote cache layer must provide — THE plugin seam for remote
  * caching. Core ships no wire client; a plugin's `cache` hook returns one
@@ -140,6 +158,14 @@ export interface RemoteCacheLayer {
    * plugin's keychain and may ask on the terminal.
    */
   open?(ctx: RemoteOpenContext): Promise<void>
+  /**
+   * Optional: this run's access, for a machine that runs its tasks
+   * elsewhere (`ExecutorContext.cacheFacts`); that machine's plugin reads
+   * it as `CacheContext.lent`. Only access made for this run (an OIDC
+   * exchange's), never a stored secret: the server's token decides what
+   * it may write. Asked after `open`.
+   */
+  lend?(): Promise<LentAccess | undefined>
   /**
    * Existence probe: what the remote knows of the stored artifact, or null
    * when it holds none. `--dry` and `--force` ask it per key when the
@@ -171,9 +197,16 @@ export interface RemoteCacheLayer {
    * artifact, so a plugin that streams it never holds it whole, and every
    * 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.
+   * first; a wire that would overwrite checks inside, unless told `missing`.
+   * `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>
+  put(hash: string, body: Blob, meta: { durationMs: number }): 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.
+   */
+  missing?(hash: string): void
 }
 
 export class LayeredCache implements CacheLayer {
@@ -181,6 +214,8 @@ export class LayeredCache implements CacheLayer {
   readonly hasRemote = true
 
   private readonly lanes: readonly RemoteLane[]
+  /** Each key `save` uploaded: whether a remote took it (`uploaded`). */
+  private readonly sent = new Map<string, Promise<boolean>>()
 
   /**
    * In-flight remote pulls keyed by hash. `prefetch` and `get` both go
@@ -194,17 +229,6 @@ export class LayeredCache implements CacheLayer {
    */
   private readonly inflight = new Map<string, Promise<boolean>>()
 
-  /**
-   * Hashes a batch probe is asking about, each resolving whether a pull may
-   * still find it (false: no remote holds it). A `get` that lands while the
-   * probe is out waits for its answer instead of spending a GET on a key
-   * the probe is about to call absent.
-   */
-  private readonly probing = new Map<string, Promise<boolean>>()
-
-  /** Settles once the run's batch probe has started (`probeFirst`); a pull waits on it. */
-  private probeStarted: Promise<void> | null = null
-
   /**
    * Hashes whose local artifact was materialized FROM a remote this run
    * (by `prefetch` or `get`'s read-through). A later `get` finds them as
@@ -252,6 +276,13 @@ export class LayeredCache implements CacheLayer {
     return this.local.localHasMany(hashes)
   }
 
+  remoteKnown(hashes: readonly string[]): Map<string, ArtifactInfo> {
+    if (this.readable.length === 0) return new Map()
+    const known = this.local.remoteHits.get(hashes)
+    for (const [h, info] of known) if (!this.infos.has(h)) this.infos.set(h, info)
+    return known
+  }
+
   /**
    * Batch existence probe over the readable remotes — the subset of
    * `hashes` some remote holds, one round-trip each, or `null` when any
@@ -265,27 +296,34 @@ export class LayeredCache implements CacheLayer {
    */
   async remoteHasMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
     if (this.readable.length === 0) return null
-    const answer = this.probeMany(hashes).then((found) => {
-      if (found !== null) for (const [h, info] of found) this.infos.set(h, info)
-      return found
-    })
-    const waiting = hashes.filter((h) => !this.inflight.has(h) && !this.probing.has(h))
-    for (const h of waiting) {
-      this.probing.set(
-        h,
-        answer.then(
-          (found) => {
-            this.probing.delete(h)
-            return found === null || found.has(h)
-          },
-          () => {
-            this.probing.delete(h)
-            return true
-          },
-        ),
-      )
+    const found = await this.probeMany(hashes)
+    if (found !== null) {
+      for (const [h, info] of found) this.infos.set(h, info)
+      // The whole answer, kept for the next run and the next process.
+      this.local.remoteHits.record(hashes, found)
+    }
+    return found
+  }
+
+  /**
+   * Each readable remote asked key by key (`RemoteLane.hasEach`), a key
+   * its batch answer already covered not asked again: a complete answer,
+   * for a run that plans on it. Null when a probe failed or none may be read.
+   */
+  async remoteHasEach(
+    hashes: readonly string[],
+    concurrency: number,
+  ): Promise<Map<string, ArtifactInfo> | null> {
+    if (this.readable.length === 0) return null
+    const out = new Map<string, ArtifactInfo>()
+    for (const lane of this.readable) {
+      const found = await lane.hasEach(hashes, concurrency)
+      if (found === null) return null
+      for (const [h, info] of found) if (!out.has(h)) out.set(h, info)
     }
-    return answer
+    for (const [h, info] of out) this.infos.set(h, info)
+    this.local.remoteHits.record(hashes, out)
+    return out
   }
 
   private async probeMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
@@ -312,17 +350,6 @@ export class LayeredCache implements CacheLayer {
     }
   }
 
-  probeFirst(started: Promise<void>): void {
-    const gate = started.then(
-      () => {},
-      () => {},
-    )
-    this.probeStarted = gate
-    void gate.then(() => {
-      if (this.probeStarted === gate) this.probeStarted = null
-    })
-  }
-
   probeBeforeUpload(hashes: Promise<readonly string[]>): void {
     for (const lane of this.lanes) lane.probeBeforeUpload(hashes)
   }
@@ -332,7 +359,9 @@ export class LayeredCache implements CacheLayer {
     if (localHit) {
       // A prefetch this run may have materialized this entry FROM
       // remote; the local row exists now, but the work was saved by
-      // the remote cache, so the provenance stays 'remote'.
+      // the remote cache, so the provenance stays 'remote'. Its row lands
+      // a tick before the pull settles and says so: wait for that.
+      await this.inflight.get(hash)
       return this.asRemote(hash, localHit)
     }
 
@@ -345,6 +374,9 @@ export class LayeredCache implements CacheLayer {
     // remote walk per key: a settled `false` means no remote had it
     // (no second probe), and a settled/in-flight `true` means the
     // artifact was/will-be ingested locally — re-read below.
+    // A lookup never waits on the run's batch probe: a hit then paid two
+    // round-trips before its first byte (the probe, then the GET), ~300 ms
+    // an up-to-date task on CI. A GET answers a miss as fast as the probe.
     const ingested = await this.awaitOrRun(hash, this.pullFromRemote(hash, ctx))
     if (!ingested) return null
 
@@ -367,6 +399,16 @@ export class LayeredCache implements CacheLayer {
     return this.asRemote(hash, materialized)
   }
 
+  async getSaved(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null> {
+    const here = await this.local.getIngested(hash)
+    if (here) return here
+    // Every remote, read or not, and past a probe's absence: the probe ran
+    // before the agent saved it.
+    for (const lane of this.lanes)
+      if (await this.pullFrom(lane, hash, ctx, true)) return this.local.getIngested(hash)
+    return null
+  }
+
   /**
    * A pull the task now waits on, given up when the rest of its body would
    * take longer than running the task (its stored duration, doubled for
@@ -382,7 +424,7 @@ export class LayeredCache implements CacheLayer {
       const info = this.infos.get(hash)
       if (info === undefined) continue
       if (!judged(info)) return pull
-      const budget = info.durationMs * 2
+      const budget = Math.max(info.durationMs * 2, LEAST_BUDGET_MS)
       const dl = this.downloads.get(hash)
       if (dl === undefined) continue
       const elapsed = performance.now() - dl.start
@@ -426,11 +468,6 @@ export class LayeredCache implements CacheLayer {
   private pullFromRemote(hash: string, ctx?: CacheGetContext): Promise<boolean> {
     const existing = this.inflight.get(hash)
     if (existing) return existing
-    const probed = this.probing.get(hash)
-    if (probed !== undefined)
-      return probed.then((found) => (found ? this.pullFromRemote(hash, ctx) : false))
-    if (this.probeStarted !== null)
-      return this.probeStarted.then(() => this.pullFromRemote(hash, ctx))
     const p = this.doPullFromRemote(hash, ctx)
     this.inflight.set(hash, p)
     return p
@@ -446,26 +483,38 @@ export class LayeredCache implements CacheLayer {
     // caller re-reads it, keeping whatever provenance it already had (local,
     // or remote if a concurrent prefetch set it).
     if ((await this.local.has(hash)) === 'local') return true
+    let absent = true
     for (const lane of this.readable) {
-      if (await this.pullFrom(lane, hash, ctx)) return true
+      const got = await this.pullFrom(lane, hash, ctx)
+      if (got === true) return true
+      if (got === false) absent = false
     }
+    // Every remote answered it holds none: a hit the index kept is gone.
+    if (absent) this.local.remoteHits.forget(hash)
     return false
   }
 
-  private async pullFrom(lane: RemoteLane, hash: string, ctx?: CacheGetContext): Promise<boolean> {
+  private async pullFrom(
+    lane: RemoteLane,
+    hash: string,
+    ctx?: CacheGetContext,
+    fresh = false,
+  ): Promise<boolean | null> {
     const fetchStart = performance.now()
     // A stopped run waits on no read, as on no upload: a lookup or download
-    // in flight held a Ctrl-C until its last byte (M, 2026-10-17). The
+    // in flight held a Ctrl-C until its last byte (2026-10-17). The
     // plugin's request is left to the exit, and its body is cancelled.
     const stopped = lane.whenStopped.then((): typeof STOPPED => STOPPED)
-    const pending = lane.get(hash)
+    const pending = lane.get(hash, fresh)
     const remoteBody = await Promise.race([pending, stopped])
     if (remoteBody === STOPPED) {
       // A late answer's body would hold its connection to the exit.
       void pending.then((r) => (r?.body instanceof Response ? r.body.body?.cancel() : undefined))
       return false
     }
-    if (remoteBody === null) return false
+    // The remote holds none: the one answer that says the key is gone.
+    if (remoteBody === null) return null
+    if (remoteBody === undefined) return false
 
     // Ingest the remote body into local using the caller-supplied
     // taskId/command plus the remote-reported durationMs, which `get`
@@ -495,6 +544,7 @@ export class LayeredCache implements CacheLayer {
         endsOnStop(remoteBody.body, ends, (n) => (dl.received += n)),
         meta,
       )
+      // quiet: raced and awaited below, where its error is reported
       ingest.catch(() => undefined)
       if ((await Promise.race([ingest, ends])) === STOPPED) return false
     } catch (err) {
@@ -503,6 +553,9 @@ export class LayeredCache implements CacheLayer {
       // crash the run. A corrupt LOCAL artifact is a miss too, one level
       // down: `Cache.restoreOutputs` drops it (A-52).
       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)
       return false
     } finally {
       this.downloads.delete(hash)
@@ -568,6 +621,7 @@ export class LayeredCache implements CacheLayer {
         packed = await this.local.packArtifactBytes(args)
       } catch (err) {
         for (const lane of writable) lane.report('upload', hash, err)
+        this.sent.set(hash, Promise.resolve(false))
         return
       }
     }
@@ -575,7 +629,48 @@ export class LayeredCache implements CacheLayer {
       packed !== undefined
         ? Promise.resolve({ body: new Blob([packed]) })
         : this.local.pinArtifact(hash)
-    for (const lane of writable) lane.upload(hash, durationMs, body, this.local.uploads)
+    const sent = writable.map((lane) =>
+      lane.upload(hash, durationMs, body, this.local.uploads, args.absent === true),
+    )
+    this.sent.set(
+      hash,
+      Promise.all(sent).then((held) => held.includes(true)),
+    )
+  }
+
+  uploaded(hash: string): Promise<boolean | undefined> {
+    return this.sent.get(hash) ?? Promise.resolve(undefined)
+  }
+
+  /**
+   * True once a remote this run reads holds entry `hash`, uploading the
+   * local entry to each one it also writes when none does. Another machine
+   * of the run (a DTE worker) restores from the remotes alone: a hit only
+   * this cache held, the remote having evicted it, failed its dependant
+   * there.
+   */
+  async share(hash: string): Promise<boolean> {
+    for (const lane of this.readable) if ((await lane.has(hash)) !== null) return true
+    return this.upload(hash, false)
+  }
+
+  /** `share`, over a remote copy another machine of the run found corrupt. */
+  resend(hash: string): Promise<boolean> {
+    return this.upload(hash, true)
+  }
+
+  private async upload(hash: string, over: boolean): Promise<boolean> {
+    const lanes = this.readable.filter((l) => l.write)
+    if (lanes.length === 0) return false
+    const entry = await this.local.getIngested(hash)
+    if (entry === null) return false
+    if (over) for (const lane of lanes) lane.distrust(hash)
+    const held = await Promise.all(
+      lanes.map((l) =>
+        l.upload(hash, entry.durationMs, () => this.local.pinArtifact(hash), this.local.uploads),
+      ),
+    )
+    return held.includes(true)
   }
 
   /**
@@ -602,7 +697,7 @@ export class LayeredCache implements CacheLayer {
     return this.local.loadOutputFilesBatch(hashes)
   }
 
-  async isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean> {
+  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): boolean {
     return this.local.isOutputsCurrent(projectDir, expected)
   }
 
@@ -622,7 +717,7 @@ export class LayeredCache implements CacheLayer {
     return this.local.loadOutputDirsBatch(hashes)
   }
 
-  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
+  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): boolean {
     return this.local.outputDirsCurrent(projectDir, rows)
   }
 

package/src/cache/linked-inputs.ts

@@ -1,5 +1,5 @@
 // A symlinked input keys the content behind it, as Nx reads a linked file
-// where it points (owner, 2026-10-16: "Do like nx"). Its own fold stays the
+// where it points (2026-10-16: "Do like nx"). Its own fold stays the
 // blob of its target STRING (file-hashes.ts), so a retarget to equal bytes
 // moves the key; this is what follows it. The target string alone let an
 // edit behind the link replay the old output (Growth, 2026-10-16), wherever