@vzn/vx 0.0.644 → 0.0.646

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vx contributors
+Copyright (c) 2026 VZN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -12,7 +12,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@vzn/vx"><img src="https://img.shields.io/npm/v/@vzn/vx?color=7cb518" alt="npm"></a>
-  <a href="https://github.com/vznjs/vx/actions/workflows/ci.yml"><img src="https://github.com/vznjs/vx/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/vznjs/vx/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush"><img src="https://github.com/vznjs/vx/actions/workflows/ci.yml/badge.svg?branch=main&event=push" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
   <a href="https://vznjs.github.io/vx/"><img src="https://img.shields.io/badge/docs-vznjs.github.io%2Fvx-c6f84e" alt="Documentation"></a>
 </p>
@@ -23,38 +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 with a `package.json` workspace:
+In a git repo:
 
 ```sh
-npm install -D @vzn/vx         # the scope matters: npm's `vx` is an unrelated package
-npx @vzn/vx init               # beside turbo.json or nx.json: migrates them; else a vx.config.ts per package
-npx @vzn/vx run build --all    # builds in dependency order and stores the results
-npx @vzn/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).
+A prebuilt binary for Linux (glibc, not Alpine's musl) and macOS, x64 and
+arm64. Windows: run vx inside WSL2.
 
-`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
-
-`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
@@ -75,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.">
@@ -87,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,
@@ -135,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,
@@ -166,17 +147,17 @@ Every gap, and when another tool is the better pick:
 
 <!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
 
-| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx          | Turborepo | Nx         | Vite Task |
-| ---------------------------------------------------------- | ----------- | --------- | ---------- | --------- |
-| Nothing changed                                            | **856 ms**  | 855 ms    | 23.22 s    | 11.24 s   |
-| Nothing changed, outputs restored                          | **1.45 s**  | 1.50 s    | 21.64 s    | 11.21 s   |
-| Cold build                                                 | **7.73 s**  | 10.32 s   | 3 min 23 s | 9.44 s    |
-| Cold build: CPU the runner burns                           | **36.42 s** | 1 min 3 s | 5 min 35 s | 25.64 s   |
+| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx         | Turborepo | Nx         | Vite Task |
+| ---------------------------------------------------------- | ---------- | --------- | ---------- | --------- |
+| Nothing changed                                            | **757 ms** | 761 ms    | 22.63 s    | 12.26 s   |
+| Nothing changed, outputs restored                          | **1.27 s** | 1.76 s    | 22.16 s    | 11.66 s   |
+| Cold build                                                 | **6.13 s** | 8.87 s    | 3 min 20 s | 7.94 s    |
+| Cold build: CPU the runner burns                           | 30.06 s    | 1 min 8 s | 5 min 45 s | 23.91 s   |
 
 Time each tool adds over the ideal run; lower is better.
 
 Benchmark workload: a synthetic monorepo of 1,601 projects and 9,603 tasks in 30 dependency levels, five core libraries a quarter of the projects use; build 300 ms, test and typecheck 150 ms, lint 75 ms, publish 30 ms; real repos with uneven task times will differ.
-Run 2026-10-12 on linux x64, 4 cores: vx at commit 126d60a93, Turborepo 2.11.7, Nx 23.3.0, Vite Task (vite-plus) 1.1.0.
+Run 2026-10-20 on linux x64, 4 cores: vx at commit a88652b0b, Turborepo 2.11.9, Nx 23.3.0, Vite Task (vite-plus) 1.3.0.
 
 Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
 
@@ -188,17 +169,10 @@ Same graph, commands and concurrency: [how it is measured](https://vznjs.github.
 vx. The schema may still change; 1.0's promise:
 [versioning-1.0.md](packages/vx/docs/design/versioning-1.0.md).
 
-## Contributing
-
-```sh
-git clone https://github.com/vznjs/vx && cd vx
-bun install
-bun packages/vx/src/bin.ts run ci --all     # lint, test, docs build: every package
-```
+## Issues
 
-Needs Bun ≥ 1.4. Every dev task is a vx task; no `package.json`
-scripts. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and
-[STATUS.md](packages/vx/docs/STATUS.md).
+vx is maintained by VZN and takes issues, not pull requests: report a
+bug or ask for a feature in [issues](https://github.com/vznjs/vx/issues).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.644",
+  "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.644",
-    "@vzn/vx-linux-arm64": "0.0.644",
-    "@vzn/vx-darwin-x64": "0.0.644",
-    "@vzn/vx-darwin-arm64": "0.0.644"
+    "@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/init.json

@@ -52,6 +52,11 @@
     "next": {
       "type": ["string", "null"],
       "description": "the command to type after the real run; null where the plan names none"
+    },
+    "installs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "core's plan only: the install commands the real run runs (global, then the root devDependency)"
     }
   }
 }

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/archive.ts

@@ -163,8 +163,6 @@ class SumCheck {
   add(bytes: Uint8Array): void {
     this.sum.add(bytes)
   }
-  /** The checked sum's text, once `verify` passed. */
-  checked = ''
   verify(got: string): void {
     if (got !== this.sum.hex()) {
       throw new TarFormatError(
@@ -172,7 +170,6 @@ class SumCheck {
       )
     }
     this.seen = true
-    this.checked = got
   }
   done(): void {
     if (!this.seen) throw new TarFormatError('artifact carries no checksum')
@@ -478,14 +475,11 @@ function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
 /**
  * The tree form (`cache.store.decompress`, v47): an artifact's members
  * as plain files under one directory, `outputs/<rel>` and
- * `workspace-outputs/<rel>` as named in the tar, beside its sidecar and a
- * `.vx-sum` over them. stdout lives in the index. A restore copies (or
- * clones) each file out, so a hit decodes nothing; an upload packs the
- * tree back into the artifact a remote expects.
- */
-const TREE_SUM = SUM_ENTRY
-
-/**
+ * `workspace-outputs/<rel>` as named in the tar, beside its sidecar.
+ * stdout lives in the index. A restore copies (or clones) each file out,
+ * so a hit decodes nothing; an upload packs the tree back into the
+ * artifact a remote expects.
+ *
  * Write `plan`'s outputs into the empty `dir` as the tree form, each copied
  * by the kernel (`copy_file_range`, or a clone where the filesystem has one)
  * and given its sidecar mtime, and return what a scan of the plan's tar
@@ -515,24 +509,14 @@ export async function writeTree(plan: ArtifactPlan, dir: string): Promise<Artifa
     }),
   )
   await writeFile(path.join(dir, META_ENTRY), meta)
-  await writeFile(path.join(dir, TREE_SUM), await treeSum(dir, stdoutOf(plan)))
   return fold.result()
 }
 
-function stdoutOf(plan: ArtifactPlan): string {
-  return utf8.decode(plan.inputs.find((i) => i.name === STDOUT_ENTRY)!.body as Uint8Array)
-}
-
 /**
- * Write a scanned artifact's sidecar and sum into `dir`, whose outputs an
- * extract just wrote: an ingested remote hit kept as a tree.
+ * Write a scanned artifact's sidecar into `dir`, whose outputs an extract
+ * just wrote: an ingested remote hit kept as a tree.
  */
-export async function sealTree(
-  dir: string,
-  scan: ArtifactScan,
-  /** The archive's own sidecar text and checked sum (`extractArtifactStream`'s `onScan`). */
-  raw?: { meta: string; sum: string },
-): Promise<void> {
+export async function sealTree(dir: string, scan: ArtifactScan): Promise<void> {
   // An artifact with no outputs extracts nothing, so nothing made `dir`.
   await mkdir(dir, { recursive: true })
   const meta: MetaFile = { version: 1, files: {} }
@@ -543,20 +527,7 @@ export async function sealTree(
   if (scan.dirs.length > 0) meta.dirs = scan.dirs
   if (scan.links.length > 0) meta.links = Object.fromEntries(scan.links)
   if (scan.exec !== undefined) meta.exec = scan.exec
-  const text = JSON.stringify(meta)
-  await writeFile(path.join(dir, META_ENTRY), text)
-  // The tree packs back to the archive it came from when the sidecar is
-  // the same bytes and the entries came in its order (stdout first, the
-  // sidecar last): the sum the extract checked is then the tree's, and the
-  // tree is not read back to sum it.
-  const names = Object.keys(meta.files)
-  const same =
-    raw !== undefined &&
-    raw.meta === text &&
-    scan.entries[0]?.name === STDOUT_ENTRY &&
-    scan.entries.length === names.length + 1 &&
-    names.every((n, i) => scan.entries[i + 1]!.name === n)
-  await writeFile(path.join(dir, TREE_SUM), same ? raw.sum : await treeSum(dir, scan.stdout ?? ''))
+  await writeFile(path.join(dir, META_ENTRY), JSON.stringify(meta))
 }
 
 /** The plan that packs the tree in `dir` back into the artifact it holds. */
@@ -579,28 +550,6 @@ export function planOfTree(dir: string, stdout: string): ArtifactPlan {
   return { inputs, size: tarSize([...inputs, sumInput('0'.repeat(SUM_SIZE))]) }
 }
 
-/** The sum over the tree's members, as `SUM_ENTRY` defines it for the tar it packs to. */
-async function treeSum(dir: string, stdout: string): Promise<string> {
-  const sum = new EntrySum()
-  for (const i of planOfTree(dir, stdout).inputs) {
-    sum.entry(i.name)
-    if (i.body instanceof Blob && i.size > 1 << 20)
-      for await (const c of i.body.stream()) sum.add(c)
-    else if (i.body instanceof Blob) sum.add(await i.body.bytes())
-    else sum.add(i.body as Uint8Array)
-  }
-  return sum.hex()
-}
-
-/** Whether the tree's bytes still sum to what was stored (`cache.store.verify: 'hash'`). */
-export async function treeIntact(dir: string, stdout: string): Promise<boolean> {
-  try {
-    return (await treeSum(dir, stdout)) === readFileSync(path.join(dir, TREE_SUM), 'utf8')
-  } catch {
-    return false
-  }
-}
-
 /** What a scan of an artifact reads out of it. */
 interface ArtifactScan {
   entries: ArchiveEntry[]
@@ -794,12 +743,8 @@ export async function extractArtifactStream(
   accept?: (name: string) => boolean,
   /** The workspace root whose `.vx/tmp/` stages the entries; absent, each stages beside its target. */
   stageRoot?: string,
-  /**
-   * Handed what `scanArtifact` would read of the same bytes, once their sum
-   * has checked, with the sidecar's text and the sum when the sidecar came
-   * last: what `sealTree` may reuse rather than read the tree back.
-   */
-  onScan?: (scan: ArtifactScan, raw: { meta: string; sum: string } | undefined) => void,
+  /** Handed what `scanArtifact` would read of the same bytes, once their sum has checked. */
+  onScan?: (scan: ArtifactScan) => void,
 ): Promise<Set<string>> {
   // No `mkdir -p` of the destination here: `stage` creates each entry's
   // directory chain, the destination included, and the cache restores
@@ -813,20 +758,15 @@ export async function extractArtifactStream(
   let dirs: string[] = []
   let links: Array<[string, string]> = []
   const fold = onScan === undefined ? undefined : new ScanFold()
-  let metaText: string | undefined
-  let metaLast = false
   try {
     const check = new SumCheck()
     for await (const e of tarEntries(tar)) {
       if (e.type !== '0') continue
       const body = await check.body(e.name, e.body)
       if (body === null) continue
-      metaLast = false
       if (e.name === META_ENTRY) {
         const text = await textOf(body)
         fold?.sidecar(text)
-        metaText = text
-        metaLast = true
         const parsed = JSON.parse(text) as MetaFile
         meta = parsed.files ?? {}
         dirs = dirsOf(parsed)
@@ -855,11 +795,7 @@ export async function extractArtifactStream(
       await x.stage(e.name, dest.base, target, e.size <= SMALL_ENTRY ? await bytesOf(body) : body)
     }
     check.done()
-    if (fold !== undefined)
-      onScan!(
-        fold.result(),
-        metaLast && metaText !== undefined ? { meta: metaText, sum: check.checked } : undefined,
-      )
+    if (fold !== undefined) onScan!(fold.result())
     for (const name of dirs) {
       if (accept !== undefined && !accept(name)) {
         throw new ArchiveSecurityError(

package/src/cache/cache.ts

@@ -78,7 +78,6 @@ import {
   planArtifact,
   planOfTree,
   sealTree,
-  treeIntact,
   writeTree,
 } from './archive.js'
 import { readUmask, restoredMode } from './umask.js'
@@ -166,6 +165,8 @@ const VX_CACHE_NAMES = new Set([
   'runs',
   'failures',
   'lockfile-claims',
+  // The workspace config's bytecode bundle (workspace/config-bytecode.ts).
+  'compiled',
 ])
 
 /**
@@ -325,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
@@ -814,14 +824,11 @@ export interface StoreOptions {
   embeddings: number
   /** A file-backed entry is a `<hash>.tree` of plain files; off, one `<hash>.tar.zst`. */
   decompress: boolean
-  /** What a tree restore checks first: each file's size and mtime, every byte, or nothing. */
-  verify: 'stat' | 'hash' | 'none'
 }
 
 export const DEFAULT_STORE: StoreOptions = {
   embeddings: 32 * 1024,
   decompress: true,
-  verify: 'stat',
 }
 
 /** What a run's background uploads moved: totals over the ones that landed. */
@@ -859,6 +866,8 @@ export class Cache implements CacheLayer {
    * so the run can report them without a method on the layer seam.
    */
   readonly uploads: UploadTally = { count: 0, bytes: 0, ms: 0, failed: 0 }
+  /** The run's hits pulled from those remotes, and their bytes on the wire. */
+  readonly downloads: { count: number; bytes: number } = { count: 0, bytes: 0 }
   /** The same remotes' traffic per key, filled by the same `LayeredCache`. */
   readonly traffic: RemoteTraffic = { inFlight: 0, keys: new Map() }
 
@@ -1701,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
@@ -1924,9 +1937,8 @@ export class Cache implements CacheLayer {
   }
 
   /**
-   * Restore a tree-form entry: its files checked as `cache.store.verify`
-   * says, then copied (or cloned) out one by one where the outputs are
-   * absent, as on every restore after a clean. Anything else (a tree to
+   * Restore a tree-form entry: its files copied (or cloned) out one by
+   * one where the outputs are absent, as on every restore after a clean. Anything else (a tree to
    * restore into, a workspace output, a link) goes through the extractor
    * the tar form uses, fed the tree packed back into its tar.
    */
@@ -1948,21 +1960,6 @@ export class Cache implements CacheLayer {
         `its outputs hold ${formatBytes(bytes)}, past the ${formatBytes(this.artifactCeiling)} artifact ceiling`,
       )
     }
-    if (this.store.verify === 'stat') {
-      const changed = await Promise.all(
-        files.map((r) =>
-          stat(path.join(tree, treeName(r.path))).then(
-            (st) => st.size !== r.size || Math.floor(st.mtimeMs) !== r.mtimeMs,
-            () => true,
-          ),
-        ),
-      )
-      if (changed.includes(true)) {
-        throw new CorruptArtifactError(hash, 'a stored file changed since it was saved')
-      }
-    } else if (this.store.verify === 'hash' && !(await treeIntact(tree, this.stdoutText(hash)))) {
-      throw new CorruptArtifactError(hash, 'the stored files no longer sum to what was saved')
-    }
     if (await this.copyTree(tree, rows, files, projectDir, accept)) return
     await extractArtifactStream(
       packArtifactStream(planOfTree(tree, this.stdoutText(hash))),
@@ -1974,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[],
@@ -1982,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 {
@@ -2017,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
@@ -2699,7 +2731,6 @@ export class Cache implements CacheLayer {
         const dir = this.tempTreePath(hash)
         tree = dir
         let scan: Awaited<ReturnType<typeof scanArtifact>> | undefined
-        let raw: { meta: string; sum: string } | undefined
         await extractArtifactStream(
           await decodedTar(
             compressed instanceof Uint8Array ? compressed : Bun.file(tmpPath!),
@@ -2711,13 +2742,12 @@ export class Cache implements CacheLayer {
           undefined,
           undefined,
           undefined,
-          (s, r) => {
+          (s) => {
             scan = s
-            raw = r
           },
         )
         scanned = scan!
-        await sealTree(dir, scanned, raw)
+        await sealTree(dir, scanned)
       } else if (tar !== undefined) {
         // Our own tar, in memory: read in place, on this thread.
         scanned = scanTarBytes(tar)