@vzn/vx 0.0.645 → 0.0.646

package/README.md

@@ -23,37 +23,19 @@ Task orchestration with a cache you can trust, on a core you can extend.
 Each task is one shell command with declared inputs and outputs; vx runs
 them in dependency order and replays results from a content-addressed cache.
 
-## Install
-
-```sh
-npm install -D @vzn/vx     # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
-```
-
-A prebuilt binary for Linux (glibc, not Alpine's musl) and macOS, x64 and arm64; no Bun needed. The
-[release](https://github.com/vznjs/vx/releases) binary needs no Node either.
-Windows: run vx inside WSL2.
-
 ## Quick start
 
 In a git repo:
 
 ```sh
-npx @vzn/vx init       # installs vx globally and in the repo; beside turbo.json or nx.json: migrates them; else a root vx.config.ts
-vx run build --all     # builds in dependency order and stores the results
-vx run build --all     # nothing changed: every task up-to-date
+bunx @vzn/vx init   # installs vx, writes an empty root vx.config.ts and the lockfile plugin
 ```
 
-Bun workspaces: `bun add -d @vzn/vx` and `bunx @vzn/vx` (npm refuses to run in
-a repo whose `devEngines` names Bun).
-
-Without Turbo or Nx, tasks run uncached until you declare what they read (below).
-
-`init` prints what it wrote and anything left to decide (a `TODO`). A miss you did not expect?
-`npx @vzn/vx why <task>` names the input that moved.
-
-### Without Turbo or Nx
+A prebuilt binary for Linux (glibc, not Alpine's musl) and macOS, x64 and
+arm64. Windows: run vx inside WSL2.
 
-`init` writes one task per package script, uncached. Cache one by saying what it reads and writes:
+A task runs its tool directly, never through a package script. Cache one by
+saying what it reads and writes:
 
 ```ts
 // packages/app/vx.config.ts
@@ -74,10 +56,10 @@ export default defineProject({
 ```
 
 ```sh
-npx @vzn/vx run build --all    # builds, in dependency order; stores the results
-npx @vzn/vx run build --all    # nothing changed: up-to-date, in milliseconds
+vx run build --all    # builds, in dependency order; stores the results
+vx run build --all    # nothing changed: up-to-date, in milliseconds
 rm -rf packages/*/dist
-npx @vzn/vx run build --all    # restored from the cache, not rebuilt
+vx run build --all    # restored from the cache, not rebuilt
 ```
 
 <img src="https://vznjs.github.io/vx/demo.svg" width="760" alt="vx run ci --all on examples/basic: cold, three tasks run; again, three up-to-date.">
@@ -86,7 +68,7 @@ npx @vzn/vx run build --all    # restored from the cache, not rebuilt
 
 `init` also writes `.vx/projects.lock.json`, every project's config as it evaluated.
 Commit it. Every run reads its configs from the lock, so run
-`npx @vzn/vx lock` and commit the lock again after you:
+`vx lock` and commit the lock again after you:
 
 - edit any `vx.config.ts` or `.vx/workspace.ts`,
 - update dependencies or plugins,
@@ -134,7 +116,7 @@ Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
 
 ## Coming from Turbo or Nx
 
-Beside `turbo.json` or `nx.json`, `npx @vzn/vx init` runs `@vzn/vx-migrate`:
+Beside `turbo.json` or `nx.json`, `bunx @vzn/vx init` runs `@vzn/vx-migrate`:
 it writes a `vx.config.ts` per package from `turbo.json` or the Nx graph,
 and you keep those and delete the old config. `vx init --keep` writes only
 a `.vx/workspace.ts` that maps the old config instead, and its lock: a temporary start,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.645",
+  "version": "0.0.646",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.645",
-    "@vzn/vx-linux-arm64": "0.0.645",
-    "@vzn/vx-darwin-x64": "0.0.645",
-    "@vzn/vx-darwin-arm64": "0.0.645"
+    "@vzn/vx-linux-x64": "0.0.646",
+    "@vzn/vx-linux-arm64": "0.0.646",
+    "@vzn/vx-darwin-x64": "0.0.646",
+    "@vzn/vx-darwin-arm64": "0.0.646"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/last.json

@@ -166,6 +166,9 @@
         "hash",
         "cpuMs",
         "peakRssBytes",
+        "peakCores",
+        "avgRssBytes",
+        "placement",
         "wallclockStartNs",
         "wallclockEndNs",
         "blockedBy",
@@ -199,6 +202,18 @@
         "hash": { "type": "string" },
         "cpuMs": { "type": ["number", "null"] },
         "peakRssBytes": { "type": ["integer", "null"] },
+        "peakCores": {
+          "type": ["number", "null"],
+          "description": "most cores one sampling interval burned; null when nothing sampled"
+        },
+        "avgRssBytes": {
+          "type": ["integer", "null"],
+          "description": "mean resident memory over the samples; null when nothing sampled"
+        },
+        "placement": {
+          "type": ["string", "null"],
+          "description": "where an executor ran it (small#1); null when here"
+        },
         "wallclockStartNs": {
           "type": ["string", "null"],
           "description": "decimal nanoseconds from the run's start"

package/skills/vx/SKILL.md

@@ -106,7 +106,7 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 
 ## Install
 
-`npx skills add vznjs/vx` installs this skill. To match the vx a workspace
+`bunx skills add vznjs/vx` installs this skill. To match the vx a workspace
 has installed, copy it from there instead:
 `cp node_modules/@vzn/vx/skills/vx/SKILL.md .claude/skills/vx/`.
 `vx upgrade` inside a workspace moves the project's `@vzn/vx` and the

package/src/bin.ts

@@ -39,7 +39,7 @@ async function main(): Promise<void> {
     // package, a workspace or project config — resolves to THIS core, not to
     // a second copy from node_modules (core-alias.ts says why and what it
     // costs). Registered before any verb runs; the façade loads on first use.
-    registerCoreAlias(() => import('./index.js') as Promise<Record<string, unknown>>)
+    registerCoreAlias(() => require('./index.js') as Record<string, unknown>)
     const code = await run(argv)
     // Not `process.exit` here: Bun drops what a pipe has not yet taken
     // when it follows a large write (300 KB written, 64 KiB delivered;

package/src/cache/cache.ts

@@ -165,6 +165,8 @@ const VX_CACHE_NAMES = new Set([
   'runs',
   'failures',
   'lockfile-claims',
+  // The workspace config's bytecode bundle (workspace/config-bytecode.ts).
+  'compiled',
 ])
 
 /**
@@ -324,7 +326,16 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
 //        is unchanged.
 //   v42: fold_memo — each task's last key by its fold up to the files and
 //        a token of their git records. The cache KEY is unchanged.
-export const SCHEMA_VERSION = 'v42'
+//   v43: runs.peak_cores / avg_rss_bytes — what a sampled run burned at
+//        its peak and held on average. The cache KEY is unchanged.
+//   v44: runs.placement — where an executor ran the task. The cache KEY
+//        is unchanged.
+//   v45: a 'remote' task_durations row also carries the task's measured
+//        cores, memory and saturation, for a run with no local history.
+//        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'
 
 /**
  * An entry's key components as its one `entry_inputs` row (v34): JSON
@@ -1699,6 +1710,10 @@ export class Cache implements CacheLayer {
     return this.guard(() => this.readEntry(hash))
   }
 
+  getSaved(hash: string): Promise<CacheEntry | null> {
+    return this.getIngested(hash)
+  }
+
   private async readEntry(hash: string): Promise<CacheEntry | null> {
     const row = this.selectEntry.get(hash) as EntryRow | null
     if (row === null) return null
@@ -1956,7 +1971,14 @@ export class Cache implements CacheLayer {
     )
   }
 
-  /** The copy-out: false, having written nothing, where it is not the case it serves. */
+  /**
+   * 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,
+   * and every directory on the way either is a real directory or is absent
+   * and made here. solid's build outputs `store/dist/**` beside the sources
+   * in `store/`; asking that each output's TOP be absent sent every such
+   * restore through the tar extractor, ~25 ms a task (2026-10-22).
+   */
   private async copyTree(
     tree: string,
     rows: readonly OutputFileRow[],
@@ -1964,22 +1986,49 @@ export class Cache implements CacheLayer {
     projectDir: string,
     accept: ((name: string) => boolean) | undefined,
   ): Promise<boolean> {
-    const tops = new Set<string>()
     for (const r of rows) {
       if (r.path.startsWith(WORKSPACE_OUTPUT_PREFIX) || r.mode === LINK_MODE) return false
       if (accept !== undefined && !r.path.endsWith('/') && !accept(`outputs/${r.path}`))
         return false
-      tops.add(r.path.split('/')[0]!)
-    }
-    const held = await Promise.all(
-      [...tops].map((t) =>
-        lstat(path.join(projectDir, t)).then(
-          () => true,
-          () => false,
-        ),
-      ),
+    }
+    // What stands at each path, asked once: a real directory, nothing, or
+    // anything else (a file, a link), which the extractor's rules decide.
+    const standing = new Map<string, Promise<'dir' | 'absent' | 'other'>>()
+    const at = (rel: string): Promise<'dir' | 'absent' | 'other'> => {
+      let known = standing.get(rel)
+      if (known === undefined) {
+        known = lstat(path.join(projectDir, rel)).then(
+          (st) => (st.isDirectory() ? 'dir' : 'other'),
+          (err: NodeJS.ErrnoException) => (err.code === 'ENOENT' ? 'absent' : 'other'),
+        )
+        standing.set(rel, known)
+      }
+      return known
+    }
+    // The topmost absent directories this copy makes, and the files it
+    // writes into a directory that stood: what a failure removes, and only that.
+    const made = new Set<string>()
+    const placed: string[] = []
+    const fits = await Promise.all(
+      rows.map(async (r) => {
+        const segs = r.path.replace(/\/$/, '').split('/')
+        for (let i = 1; i <= segs.length; i++) {
+          const rel = segs.slice(0, i).join('/')
+          const isLeaf = i === segs.length
+          const state = await at(rel)
+          if (state === 'absent') {
+            if (!isLeaf || r.path.endsWith('/')) made.add(rel)
+            else placed.push(rel)
+            return true
+          }
+          if (state === 'other' || (isLeaf && !r.path.endsWith('/'))) return false
+        }
+        return true
+      }),
     )
-    if (held.includes(true)) return false
+    if (fits.includes(false)) return false
+    // A directory made under another one made here is the outer one's.
+    const roots = [...made].filter((d) => ![...made].some((o) => d.startsWith(`${o}/`)))
     readUmask()
     const plain = restoredMode(0o666)
     try {
@@ -1999,9 +2048,10 @@ export class Cache implements CacheLayer {
         }),
       )
     } catch (err) {
-      await Promise.all(
-        [...tops].map((t) => rm(path.join(projectDir, t), { recursive: true, force: true })),
-      )
+      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 })),
+      ])
       throw err
     }
     return true

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 {
@@ -84,6 +87,7 @@ export {
 export {
   type ArtifactInfo,
   LayeredCache,
+  type LentAccess,
   type RemoteCacheLayer,
   type RemoteOpenContext,
 } from './layered-cache.js'

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

@@ -212,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
 }
 
 /**
@@ -384,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
@@ -593,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
@@ -651,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

@@ -104,6 +104,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 +147,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
@@ -367,6 +382,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
@@ -452,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.