@vzn/vx 0.0.644 → 0.0.646

package/src/cache/git-inputs.ts

@@ -204,7 +204,8 @@ function configObjectFormat(config: string): 'sha1' | 'sha256' | undefined {
 interface PartitionDigest {
   snapshot: readonly string[]
   oids: OidSlot | undefined
-  digest: string
+  /** Built on first read: a partition with untrusted files stats them then. */
+  digest: () => string | undefined
 }
 
 /**
@@ -515,11 +516,20 @@ export class GitFilesCache extends Map<string, readonly string[]> {
     const d = this.digests.get(projectDir)
     if (d === undefined || d.snapshot !== snapshot || this.get(projectDir) !== snapshot) return
     if (this.oids.get(projectDir) !== d.oids || this.changed.has(projectDir)) return
-    return d.digest
-  }
-
-  noteFilesDigest(projectDir: string, snapshot: readonly string[], digest: string): void {
-    this.digests.set(projectDir, { snapshot, oids: this.oids.get(projectDir), digest })
+    return d.digest()
+  }
+
+  noteFilesDigest(
+    projectDir: string,
+    snapshot: readonly string[],
+    digest: () => string | undefined,
+  ): void {
+    let memo: { value: string | undefined } | undefined
+    this.digests.set(projectDir, {
+      snapshot,
+      oids: this.oids.get(projectDir),
+      digest: () => (memo ??= { value: digest() }).value,
+    })
   }
 
   /** Trusted index OIDs for a project (abs path → oid), if any survive. */
@@ -1908,6 +1918,30 @@ export function lazyGitEnumeration(workspaceRoot: string): LazyGitEnumeration {
   }
 }
 
+/**
+ * Each loose file's stat identity, `hashFile`'s memo key: mode, size,
+ * mtime, ctime and inode. Undefined for a symlink (what it points to
+ * folds too, and its stat does not move with that), a file gone, or one
+ * changed within the racy window, where the memo trusts no stat either.
+ */
+function statRecords(
+  rels: readonly string[],
+  abs: (rel: string) => string,
+  prefixLength: number,
+): string | undefined {
+  if (rels.length === 0) return ''
+  const now = Date.now()
+  let out = ''
+  for (const rel of rels) {
+    const st = lstatSync(abs(rel), { throwIfNoEntry: false })
+    if (st === undefined || !st.isFile()) return undefined
+    if (now - Math.floor(st.ctimeMs) < racyWindowMs(st.ctimeMs, FILE_HASH_RACY_MS)) return
+    const mode = (st.mode & 0o100) !== 0 ? '100755' : '100644'
+    out += `${rel.slice(prefixLength)}\0stat:${mode}:${st.size}:${Math.floor(st.mtimeMs)}:${Math.floor(st.ctimeMs)}:${Number(st.ino)}\n`
+  }
+  return out
+}
+
 /** The partition half of `populateGitFilesCache`: store per-project slices of one enumeration. */
 export async function applyGitEnumeration(
   enumeration: GitEnumeration,
@@ -2006,15 +2040,20 @@ export async function applyGitEnumeration(
     }
     // One hash of the records joined: one per record was ~25 ms of 125,000.
     let records: string | undefined = ''
+    // A file git vouches for no OID (untracked, or changed since the
+    // index) is named by its stat instead, the identity `hashFile`'s memo
+    // trusts: a just-added config or an edited file turned the fold memo
+    // off for its whole project (+3-5 ms of solid's warm run, 2026-10-22).
+    const loose: string[] = []
     for (let i = start; i < end; i++) {
       const rel = sorted[i]!
       const own = rel.slice(prefix.length)
       matches.push(own)
       if (records === undefined) continue
       const oid = trusted.get(rel)
-      if (oid === undefined || oid.startsWith('120000:') || undecodable?.has(rel) === true) {
-        records = undefined
-      } else records += `${own}\0${oid}\n`
+      if (undecodable?.has(rel) === true || oid?.startsWith('120000:') === true) records = undefined
+      else if (oid === undefined) loose.push(rel)
+      else records += `${own}\0${oid}\n`
     }
     // 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
@@ -2033,7 +2072,13 @@ export async function applyGitEnumeration(
     // setLazyOids AFTER set — set() drops the project's OID slot.
     cache.set(projectDir, matches)
     cache.setLazyOids(projectDir, projOids)
-    if (records !== undefined) cache.noteFilesDigest(projectDir, matches, xxh3hex(records))
+    if (records !== undefined) {
+      const known = records
+      cache.noteFilesDigest(projectDir, matches, () => {
+        const statted = statRecords(loose, projAbs, prefix.length)
+        return statted === undefined ? undefined : xxh3hex(`${known}\0${statted}`)
+      })
+    }
   }
   if (workspaceWide) {
     cache.set(workspaceRoot, all)

package/src/cache/index.ts

@@ -29,6 +29,7 @@ export {
   WORKSPACE_OUTPUT_PREFIX,
   type OutputDirRow,
   OUTPUT_DIRS_CAP,
+  OUTPUT_DIRS_OVER_CAP,
   FILE_HASH_RACY_MS,
   OUTPUT_DIRS_RACY_MS,
   racyWindowMs,
@@ -54,6 +55,7 @@ export {
   type ResolveInputsArgs,
   resolveOutputTree,
   resolveOutputs,
+  outputWalkTakes,
   resolveWorkspaceOutputs,
   sweepRestoreTemps,
   sweepStaging,
@@ -66,6 +68,7 @@ export {
   stampOutputs,
   stampWorkspaceOutputs,
   stopRuntimeProbes,
+  answerRuntime,
   type OutputStamp,
 } from './inputs.js'
 export {
@@ -82,14 +85,14 @@ export {
   type BlobSizeMemo,
 } from './git-inputs.js'
 export {
+  type ArtifactInfo,
   LayeredCache,
+  type LentAccess,
   type RemoteCacheLayer,
-  type RemoteKey,
   type RemoteOpenContext,
 } from './layered-cache.js'
 export { networkConcurrency } from './remote-lane.js'
 export type { ResolvedRemote } from './remote-lane.js'
-export { BranchScope } from './scoped-cache.js'
 export {
   absentPluginCache,
   pluginCache,

package/src/cache/inputs.ts

@@ -31,6 +31,7 @@ import {
   outputNever,
   realpathOf,
   relPosix,
+  restorableOutput,
   shellArgv,
   slashBraceExpansions,
   braceAlternatives,
@@ -530,6 +531,28 @@ function projectBinDirs(projectDir: string, workspaceRoot: string): string[] {
   return own === root ? [own] : [own, root]
 }
 
+/**
+ * One runtime probe answered on this machine as a key folds it: an
+ * `inputs.runtime` command run in `projectDir`, or with `workspace` a
+ * `workspaceRuntime` one run in `workspaceRoot`. For an executor that
+ * checks a task's probes where it runs it (`TaskExecutor.runtime`).
+ */
+export function answerRuntime(
+  command: string,
+  projectDir: string,
+  workspaceRoot: string,
+  workspace = false,
+): Promise<string> {
+  return workspace
+    ? runRuntimeCommand(
+        command,
+        workspaceRoot,
+        [path.join(workspaceRoot, 'node_modules', '.bin')],
+        undefined,
+      )
+    : runRuntimeCommand(command, projectDir, projectBinDirs(projectDir, workspaceRoot), undefined)
+}
+
 function resolveEnvValues(
   names: readonly string[],
   source: NodeJS.ProcessEnv,
@@ -748,6 +771,21 @@ export async function resolveOutputs(args: {
   return (await scanOutputs(args)).files
 }
 
+/**
+ * Whether `resolveOutputs` takes the project-relative file `rel`, decided
+ * without the walk: a directory snapshot's file list is held to the
+ * entry's rows through it.
+ */
+export function outputWalkTakes(
+  projectDir: string,
+  outputs: readonly string[],
+  nestedProjectDirs: string[],
+): (rel: string) => boolean {
+  const restorable = restorableOutput(outputs)
+  const nested = inNestedProject(projectDir, nestedProjectDirs)
+  return (rel) => restorable(rel) && !nested(rel)
+}
+
 /**
  * `resolveOutputs`, plus the empty directories the globs match: a save
  * keeps them, so a hit leaves the tree a miss left (Turbo and Nx restore
@@ -2103,21 +2141,31 @@ async function scanUnion(
   emptyDirs?: Set<string>,
 ): Promise<Set<string>> {
   const matches = new Set<string>()
+  const take = (rel: string): void => {
+    if (nested(rel) || excludeGlobs.some((g) => g.match(rel))) return
+    const abs = path.resolve(cwd, rel)
+    const st = lstatSync(abs, { throwIfNoEntry: false })
+    if (st !== undefined && (st.isFile() || st.isSymbolicLink())) matches.add(abs)
+    else if (emptyDirs !== undefined && st?.isDirectory() === true) {
+      if (readdirSync(abs).length === 0) emptyDirs.add(abs)
+    } else if (st === undefined && rel.includes('\ufffd')) refuseUndecodableOutput(abs)
+  }
+  const opts = { cwd, onlyFiles: false, followSymlinks: false, dot: true }
   // `Bun.Glob`'s scan finds nothing for a brace whose alternatives hold a
   // `/`: `{dist,lib/esm}/**` saved an empty artifact, and a hit restored
   // nothing over a cleaned tree (A-10). Expanded here, as discovery does.
-  for (const pattern of positive.flatMap(slashBraceExpansions)) {
+  const patterns = positive.flatMap(slashBraceExpansions)
+  // A leading `**` walks the whole project whatever else is listed, so the
+  // list is one walk: Turbo's `dist/**`, `**/dist/**`, `**/dist` was three,
+  // ~2 ms of a warm hit on solid.
+  if (patterns.length > 1 && patterns.some((p) => p.startsWith('**'))) {
+    const any = anyTaskGlob(patterns)
+    for (const rel of WHOLE_TREE.scanSync(opts)) if (any(rel)) take(rel)
+    return matches
+  }
+  for (const pattern of patterns) {
     if (absentPrefix(cwd, pattern)) continue
-    const glob = globFor(pattern)
-    for (const rel of glob.scanSync({ cwd, onlyFiles: false, followSymlinks: false, dot: true })) {
-      if (nested(rel) || excludeGlobs.some((g) => g.match(rel))) continue
-      const abs = path.resolve(cwd, rel)
-      const st = lstatSync(abs, { throwIfNoEntry: false })
-      if (st !== undefined && (st.isFile() || st.isSymbolicLink())) matches.add(abs)
-      else if (emptyDirs !== undefined && st?.isDirectory() === true) {
-        if (readdirSync(abs).length === 0) emptyDirs.add(abs)
-      } else if (st === undefined && rel.includes('\ufffd')) refuseUndecodableOutput(abs)
-    }
+    for (const rel of globFor(pattern).scanSync(opts)) take(rel)
   }
   return matches
 }
@@ -2139,6 +2187,8 @@ function absentPrefix(cwd: string, pattern: string): boolean {
   }
 }
 
+const WHOLE_TREE = new Bun.Glob('**')
+
 // Compiled once per pattern string for the life of the process: a `Bun.Glob`
 // is immutable, and the same handful of declared globs are compiled again
 // for every task otherwise (three sites, up to thousands of times per run).

package/src/cache/layer.ts

@@ -5,6 +5,7 @@
 // reference to `Cache` below is a type (the local handle a layer may wrap).
 
 import type { Cache } from './cache.js'
+import type { ArtifactInfo } from './layered-cache.js'
 import { fsClockLag, stampGrainMs } from './fs-clock.js'
 
 export interface CacheKeyInput {
@@ -211,6 +212,16 @@ 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
+  /** That machine's cores and memory (v44). */
+  placementCores?: number
+  placementMemoryBytes?: number
 }
 
 /**
@@ -383,6 +394,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
@@ -550,12 +568,12 @@ export interface CacheLayer {
    */
   readonly hasRemote?: boolean
   /**
-   * Batch existence probe over the remote — the subset of `hashes` stored
-   * remotely, in ONE round-trip, or `null` for "no batch info; use
-   * per-hash". Only meaningful with `hasRemote`; a remote layer that can't
+   * Batch existence probe over the remote — the `hashes` stored remotely
+   * and what the first remote holding each knows of it (`ArtifactInfo`), in
+   * ONE round-trip, or `null` for "no batch info; use per-hash". Only meaningful with `hasRemote`; a remote layer that can't
    * batch omits it and the prefetch pass falls back to per-hash GETs.
    */
-  remoteHasMany?(hashes: readonly string[]): Promise<Set<string> | null>
+  remoteHasMany?(hashes: readonly string[]): 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
@@ -581,8 +599,6 @@ export interface CacheLayer {
    * about to call absent. Only meaningful with `hasRemote`.
    */
   probeFirst?(started: Promise<void>): void
-  /** `taskId`'s key is `hash`: a scoped run picks each remote key by its task (`BranchScope`). */
-  noteKey?(taskId: string, hash: string): void
   /**
    * Resolve once every background write-through upload settles. The
    * orchestrator awaits it before `close()` — an upload reading layer state
@@ -594,6 +610,12 @@ 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>
   /**
    * Optional batched `get` (same answers, fewer round trips). The
    * short-circuit probe uses it when a layer offers one; a layer without it
@@ -652,8 +674,8 @@ export interface CacheLayer {
   /**
    * 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

package/src/cache/layered-cache.ts

@@ -36,7 +36,6 @@ import type {
 } from './cache.js'
 import type { OutputDirRow } from './cache.js'
 import { RemoteLane, type ResolvedRemote } from './remote-lane.js'
-import type { BranchScope } from './scoped-cache.js'
 import type { PluginSecrets } from '../util/index.js'
 
 const STOPPED: unique symbol = Symbol('stopped')
@@ -46,7 +45,11 @@ const STOPPED: unique symbol = Symbol('stopped')
  * fails at once, removes its temp, and releases the connection; the cache
  * then closes under no write.
  */
-function endsOnStop(body: Blob | Response, stopped: Promise<typeof STOPPED>): Blob | Response {
+function endsOnStop(
+  body: Blob | Response,
+  stopped: Promise<typeof STOPPED>,
+  onChunk: (bytes: number) => void = () => {},
+): Blob | Response {
   if (body instanceof Blob || body.body === null) return body
   const reader = body.body.getReader()
   let stop = false
@@ -61,13 +64,28 @@ function endsOnStop(body: Blob | Response, stopped: Promise<typeof STOPPED>): Bl
       const next = await reader.read()
       if (stop) controller.error(new Error('the run was stopped'))
       else if (next.done) controller.close()
-      else controller.enqueue(next.value)
+      else {
+        onChunk(next.value.byteLength)
+        controller.enqueue(next.value)
+      }
     },
     cancel: (reason) => reader.cancel(reason),
   })
   return new Response(stream, { headers: body.headers })
 }
 
+const judged = (i: ArtifactInfo): i is { size: number; durationMs: number } =>
+  i.size !== undefined && i.durationMs !== undefined
+
+/** How often a task waiting on its download weighs running instead. */
+const JUDGE_EVERY_MS = 25
+
+interface Download {
+  readonly start: number
+  received: number
+  abandon(): void
+}
+
 /** What a remote's `open` is handed: the run's CI verdict and its plugin's keychain. */
 export interface RemoteOpenContext extends PluginSecrets {
   /** The run is on CI: nobody may be asked. */
@@ -77,13 +95,20 @@ export interface RemoteOpenContext extends PluginSecrets {
 }
 
 /**
- * Where a remote call's key lives: `scope` names the branch scope a scoped
- * key was derived in (`scopedKey`), absent for a task's own key. The key
- * alone is enough; a backend that keeps one store per scope may use it to
- * go straight to that store. turboCache(), nxCache() and vx-reapi ignore it.
+ * What a remote knows of an artifact it holds, before it is downloaded:
+ * the body's size in bytes and the producing task's duration, each when
+ * the wire carries it (Turbo's batch query and `HEAD` do).
  */
-export interface RemoteKey {
-  readonly scope?: string
+export interface ArtifactInfo {
+  readonly size?: number
+  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
 }
 
 /**
@@ -122,17 +147,29 @@ export interface RemoteCacheLayer {
    * plugin's keychain and may ask on the terminal.
    */
   open?(ctx: RemoteOpenContext): Promise<void>
-  /** Existence probe: `--dry` and `--force` ask it per key when the remote cannot batch. */
-  has(hash: string, at?: RemoteKey): Promise<boolean>
   /**
-   * Optional batch existence probe: given N hashes, return the subset stored
-   * remotely in ONE round-trip. Its presence says the wire can batch: a run
-   * asks it once for its keys, `--dry` before its per-key answers, and
-   * `--force` in the background to skip uploads of held keys. Without it a
-   * run GETs each key directly (no `has`). Never throws for control flow:
-   * `null` means "no batch info; use per-hash". `at[i]` is `hashes[i]`'s.
+   * 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`.
    */
-  hasMany?(hashes: readonly string[], at?: readonly RemoteKey[]): Promise<Set<string> | null>
+  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
+   * remote cannot batch.
+   */
+  has(hash: string): Promise<ArtifactInfo | null>
+  /**
+   * Optional batch existence probe: given N hashes, the stored ones and what
+   * the remote knows of each, in ONE round-trip. Its presence says the wire
+   * can batch: a run asks it once for its keys, `--dry` before its per-key
+   * answers, and `--force` in the background to skip uploads of held keys.
+   * Without it a run GETs each key directly (no `has`). Never throws for
+   * control flow: `null` means "no batch info; use per-hash".
+   */
+  hasMany?(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null>
   /**
    * Fetch an artifact; `null` = miss. `body` is read once, by core,
    * straight into the local cache — an HTTP wire returns its `fetch`
@@ -142,10 +179,7 @@ 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,
-    at?: RemoteKey,
-  ): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
+  get(hash: string): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
   /**
    * Store an artifact (fire-and-forget from LayeredCache's perspective).
    * `body` is file-backed (`Bun.file`) when the local store holds the
@@ -154,7 +188,7 @@ export interface RemoteCacheLayer {
    * key the remote holds keeps the stored bytes. Core never asks `has`
    * first; a wire that would overwrite checks inside.
    */
-  put(hash: string, body: Blob, meta: { durationMs: number } & RemoteKey): Promise<void>
+  put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void>
 }
 
 export class LayeredCache implements CacheLayer {
@@ -196,23 +230,18 @@ export class LayeredCache implements CacheLayer {
    * its download and ingest took.
    */
   private readonly remoteSourced = new Map<string, number>()
+  /** What the batch probe said of each held key: its size and stored duration. */
+  private readonly infos = new Map<string, ArtifactInfo>()
+  /** Bodies being read now, by key: how far along, and how to give one up. */
+  private readonly downloads = new Map<string, Download>()
 
   /** Remotes in declared order: the first readable one holding a hash answers it. */
   constructor(
     readonly local: Cache,
     remotes: readonly ResolvedRemote[],
-    /** The run's branch scope: it picks each remote key; the local store never sees it. */
-    private readonly branch?: BranchScope,
     uploadConcurrency?: number,
   ) {
-    this.lanes = remotes.map(
-      (r) =>
-        new RemoteLane(r, local.traffic, branch?.remote(r.remote) ?? r.remote, uploadConcurrency),
-    )
-  }
-
-  noteKey(taskId: string, hash: string): void {
-    this.branch?.noteKey(taskId, hash)
+    this.lanes = remotes.map((r) => new RemoteLane(r, local.traffic, uploadConcurrency))
   }
 
   // Asked, not kept: a remote whose `open` failed leaves the run after this is built.
@@ -249,9 +278,12 @@ export class LayeredCache implements CacheLayer {
    * absences either way, so a hash only a sibling holds costs it no GET.
    * Never throws.
    */
-  async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
+  async remoteHasMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
     if (this.readable.length === 0) return null
-    const answer = this.probeMany(hashes)
+    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(
@@ -271,12 +303,12 @@ export class LayeredCache implements CacheLayer {
     return answer
   }
 
-  private async probeMany(hashes: readonly string[]): Promise<Set<string> | null> {
-    let out: Set<string> | null = new Set()
+  private async probeMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
+    let out: Map<string, ArtifactInfo> | null = new Map()
     for (const lane of this.readable) {
       const found = await lane.hasMany(hashes)
       if (found === null) out = null
-      else if (out !== null) for (const h of found) out.add(h)
+      else if (out !== null) for (const [h, info] of found) if (!out.has(h)) out.set(h, info)
     }
     return out
   }
@@ -328,7 +360,7 @@ 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.
-    const ingested = await this.pullFromRemote(hash, ctx)
+    const ingested = await this.awaitOrRun(hash, this.pullFromRemote(hash, ctx))
     if (!ingested) return null
 
     // Read past the local READ gate: `ingest` is deliberately ungated, so
@@ -350,6 +382,49 @@ 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
+   * the save a run adds): the task then runs here, a miss. Only a key the
+   * batch probe sized and timed is judged, from its own body's pace so far.
+   * The facts are read each tick: the probe can answer after the task asks.
+   */
+  private async awaitOrRun(hash: string, pull: Promise<boolean>): Promise<boolean> {
+    if (this.infos.has(hash) && !judged(this.infos.get(hash)!)) return pull
+    for (;;) {
+      const done = await Promise.race([pull, Bun.sleep(JUDGE_EVERY_MS).then(() => undefined)])
+      if (done !== undefined) return done
+      const info = this.infos.get(hash)
+      if (info === undefined) continue
+      if (!judged(info)) return pull
+      const budget = info.durationMs * 2
+      const dl = this.downloads.get(hash)
+      if (dl === undefined) continue
+      const elapsed = performance.now() - dl.start
+      const left =
+        dl.received === 0
+          ? elapsed > budget
+            ? Infinity
+            : 0
+          : ((info.size - dl.received) * elapsed) / dl.received
+      if (left > budget) {
+        dl.abandon()
+        await pull
+        return false
+      }
+    }
+  }
+
   private asRemote(hash: string, entry: CacheEntry): CacheEntry {
     const fetchMs = this.remoteSourced.get(hash)
     return fetchMs === undefined ? entry : { ...entry, source: 'remote', fetchMs }
@@ -360,7 +435,7 @@ export class LayeredCache implements CacheLayer {
   // a remote cache. Remote errors degrade to a miss (never throw).
   async has(hash: string): Promise<'local' | 'remote' | null> {
     if ((await this.local.has(hash)) === 'local') return 'local'
-    for (const lane of this.readable) if (await lane.has(hash)) return 'remote'
+    for (const lane of this.readable) if ((await lane.has(hash)) !== null) return 'remote'
     return null
   }
 
@@ -402,13 +477,18 @@ export class LayeredCache implements CacheLayer {
     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> {
     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
     // 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.
@@ -434,10 +514,19 @@ export class LayeredCache implements CacheLayer {
       durationMs: durationOf(remoteBody.durationMs),
       ...(ctx?.outputs !== undefined ? { outputs: ctx.outputs } : {}),
     }
+    let abandon = (): void => {}
+    const abandoned = new Promise<typeof STOPPED>((resolve) => (abandon = () => resolve(STOPPED)))
+    const dl: Download = { start: performance.now(), received: 0, abandon }
+    this.downloads.set(hash, dl)
+    const ends = Promise.race([stopped, abandoned])
     try {
-      const ingest = this.local.ingest(hash, endsOnStop(remoteBody.body, stopped), meta)
+      const ingest = this.local.ingest(
+        hash,
+        endsOnStop(remoteBody.body, ends, (n) => (dl.received += n)),
+        meta,
+      )
       ingest.catch(() => undefined)
-      if ((await Promise.race([ingest, stopped])) === STOPPED) return false
+      if ((await Promise.race([ingest, ends])) === STOPPED) return false
     } catch (err) {
       // The bytes came off the network — a corrupt/truncated remote
       // artifact must degrade to a cache miss (task re-executes), not
@@ -445,8 +534,13 @@ export class LayeredCache implements CacheLayer {
       // down: `Cache.restoreOutputs` drops it (A-52).
       lane.report('download', hash, err)
       return false
+    } finally {
+      this.downloads.delete(hash)
     }
     this.remoteSourced.set(hash, Math.round(performance.now() - fetchStart))
+    this.local.downloads.count++
+    this.local.downloads.bytes +=
+      remoteBody.body instanceof Blob ? remoteBody.body.size : dl.received
     return true
   }