@vzn/vx 0.0.18 → 0.0.21

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 nxt contributors
+Copyright (c) 2026 vx contributors
 
 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

@@ -3,15 +3,33 @@
 **The fastest way to build a monorepo.**
 
 vx runs your task graph, remembers every result, and never does the
-same work twice. Fully cached runs finish in milliseconds — 76 ms
-across 46 packages, 559 ms across a 1,090-package graph of 3,270 tasks,
-where Turborepo takes 760 ms and Nx 3.59 s on the identical workspace —
-and a cold build of that graph burns 34 s of CPU in vx, 73 s in Turborepo
-and 114 minutes in Nx.
-Measured, reproducible, on hardware you own
-([benchmarks](docs/benchmarks.md)).
-
-One binary. No daemon. No Node. Nothing to babysit.
+same work twice.
+
+<!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
+
+The runner adds seconds to a cold build where others add minutes. On a
+1,090-package graph of 3,270 tasks whose ideal schedule is 3m 38s,
+vx finishes in 3m 46s (+0:08), Turborepo in 5m 13s (+1:35) and Nx in
+34m 44s (+31:06) — 8 ms of overhead per package against 88 ms and
+1,712 ms, so the graph can grow and the runner stays in seconds. The cold build
+burns 35 s of CPU in vx, 73 s in Turborepo and 114 minutes in Nx; a
+fully cached run replays the graph in 510 ms.
+<!-- bench:end -->
+
+On a real Turbo monorepo (`solidjs/solid`, its own `turbo.json`, no
+config rewritten) vx replays a cached build in 51 ms where Turbo takes
+95, restores every output in 66 ms against 127, and builds cold in
+40.6 s against 45.5 s. Measured, reproducible, on hardware you own
+([benchmarks](packages/vx/docs/benchmarks.md)).
+
+One binary. No daemon, no cloud, no account, no paywall. Sandboxed
+tasks, a plugin at every stage, seconds of overhead at a thousand
+packages.
+
+vx does one thing — run and cache a task graph, correctly — and stops
+there. Remote caches, remote execution, telemetry, AI agents, learned
+scheduling and your own verbs are plugins on documented seams, not
+features inside: what Nx would be if it weren't a product.
 
 📖 **[Documentation site →](https://vznjs.github.io/vx/)** — guides,
 architecture, caching, and the full CLI / config reference.
@@ -78,16 +96,11 @@ skip extraction entirely when the tree already matches. In-process
 tar (no subprocess on the hot path). Atomic artifact publishes.
 Single-transaction metadata writes. Every optimization is recorded
 with the invariant that keeps it valid —
-[`docs/optimizations.md`](docs/optimizations.md) is the ledger, and
-[`bench/`](bench/) reproduces the numbers.
+[`packages/vx/docs/optimizations.md`](packages/vx/docs/optimizations.md) is the ledger, and
+[`packages/vx-bench/`](packages/vx-bench/) reproduces the numbers.
 
 ## Built for trust
 
-- **Provable cache correctness.** `vx run --verify` re-runs each
-  cacheable task and byte-compares outputs (determinism);
-  `--verify=inputs` sandboxes it against the declared inputs and fails
-  loud naming any undeclared read (completeness). No other runner can
-  prove a cache entry safe.
 - **Corruption can't go live.** A remote artifact is verified against
   its content digest and validated before it enters the store
   (zstd-bomb and oversize downloads refused); bad bytes degrade to a
@@ -97,7 +110,11 @@ with the invariant that keeps it valid —
 - **Readiness you can bound.** Persistent tasks gate downstream work
   on a `readyWhen` signal; `exec.timeout` bounds any task (with
   `--timeout` / workspace defaults), `exec.retries` + `--retry` absorb
-  flakes — and retried-then-passed tasks are flagged flaky.
+  flakes.
+- **Flaky tasks are found, not guessed.** The same inputs both passing
+  and failing is the definition, and vx holds every hash and outcome
+  locally: a run names them under its footer, `--summarize` types them
+  per task, `vx info` lists them. No service.
 - **Kernel-level sandboxing**, opt-in per task, that fails the build
   on violation instead of hiding it.
 
@@ -132,9 +149,9 @@ watch mode · `--dry` / `--graph` plans · persistent dev servers ·
 retries, timeouts, `--continue` modes · per-layer cache control
 (`--cache=local:r,remote:`) · `vx why` explains a re-run from the
 persisted input fingerprints · `vx last` replays a recorded run ·
-`vx prune` cuts a Docker-ready workspace subset · `vx info`,
+`vx info`,
 `--summarize`, `--profile` Chrome traces, `--report` · `vx cache prune`
-with TTL and size caps · `vx migrate` from turbo.json or an Nx graph.
+with TTL and size caps · `bunx @vzn/vx-migrate` from turbo.json or an Nx graph.
 
 ## A pipeline with seams — plugins decide what happens
 
@@ -155,37 +172,50 @@ declared in `vx.workspace.ts` hook each stage, Vite-style, on one
 | observe   | `telemetry(ctx)` / `setup` | receive every run record, or the raw event bus              |
 | cli       | `commands`                 | add verbs to `vx`                                           |
 
-Core applies **no plugin by default** — even its own local executor and
-cache are plugins your workspace declares, which is what makes "replace
-any part" real rather than promised. First-party plugins:
+Core applies **no plugin by default** and names none. Running here and
+caching here are its floor — the tail of every executor list and cache
+chain — so a workspace with no `vx.workspace.ts` runs and caches, and a
+plugin that declines a task hands it back to this machine. First-party
+plugins:
 [`@vzn/vx-reapi`](packages/vx-reapi) (Bazel Remote Execution API —
 remote cache and remote execution against NativeLink, BuildBuddy,
 Buildbarn or bazel-remote), [`@vzn/vx-otel`](packages/vx-otel)
 (OpenTelemetry traces + metrics + logs, zero SDK deps),
 [`@vzn/vx-github`](packages/vx-github) (Actions job summary + Checks
 API), [`@vzn/vx-mcp`](packages/vx-mcp) (`vx mcp` — a read-only Model
-Context Protocol server for AI coding agents, no SDK), and
-`@vzn/vx/plugins/schedule-history` (order by learned critical path). Nothing distributed ships in this repo; the seams are how you
-build it.
+Context Protocol server for AI coding agents, no SDK),
+[`@vzn/vx-migrate`](packages/vx-migrate) (adoption in one package:
+`turbo()` runs a Turbo repo under vx with nothing written, `bunx
+@vzn/vx-migrate` writes configs from `turbo.json` or an Nx graph, and
+`turboCache()` / `nxCache()` keep a remote cache speaking Turbo's
+`/v8/artifacts` API or Nx's self-hosted spec — the wire is theirs, the
+artifacts are vx's),
+[`@vzn/vx-lockfile`](packages/vx-lockfile) (`pnpm()`, `bun()`, `npm()`,
+`yarn()`: the lockfile keyed per project, so one install re-keys only the
+projects it reaches, and `--affected` follows), and [`@vzn/vx-schedule-history`](packages/vx-schedule-history)
+(order by learned critical path) and [`@vzn/vx-migrate`](packages/vx-migrate)
+(`bunx @vzn/vx-migrate`: turbo.json or an Nx graph → vx.config.ts, through
+core's migration seam). Core ships no plugin and reads no other runner's
+format; nothing
+distributed ships in this repo; the seams are how you build it.
 
 ## How it compares
 
-|                           | vx                                                                    | Turborepo                      | Nx               |
-| ------------------------- | --------------------------------------------------------------------- | ------------------------------ | ---------------- |
-| Fully cached, 100 pkgs¹   | **144 ms**                                                            | 279 ms                         | 583+ ms          |
-| Config                    | TypeScript, evaluated into the cache key                              | JSON (static)                  | JSON (static)    |
-| Output ownership          | **Strict** — wiped before exec AND restore                            | Additive (stale files survive) | Additive         |
-| Clean-tree hashing        | **Zero reads** (git index OIDs)                                       | git OIDs                       | re-hash / daemon |
-| Daemon required for speed | **No**                                                                | Optional                       | Yes              |
-| Per-task sandbox          | **Yes** — kernel-level, opt-in                                        | No                             | No               |
-| Provable cache safety     | **Yes** — `--verify` (determinism) + `--verify=inputs` (completeness) | No                             | No               |
-| Plugin API                | **Yes** — executor / cache / telemetry seams                          | No                             | Yes (TS-tied)    |
-| OTel CI/CD spans          | **Yes** — `otel()` plugin, zero OTel-SDK deps                         | No                             | Paid             |
-| Install                   | **Single binary** — npm or 1 curl line, no Node/Bun needed            | npm + Node                     | npm + Node       |
+|                           | vx                                                         | Turborepo                      | Nx               |
+| ------------------------- | ---------------------------------------------------------- | ------------------------------ | ---------------- |
+| Fully cached, 100 pkgs¹   | **144 ms**                                                 | 279 ms                         | 583+ ms          |
+| Config                    | TypeScript, evaluated into the cache key                   | JSON (static)                  | JSON (static)    |
+| Output ownership          | **Strict** — wiped before exec AND restore                 | Additive (stale files survive) | Additive         |
+| Clean-tree hashing        | **Zero reads** (git index OIDs)                            | git OIDs                       | re-hash / daemon |
+| Daemon required for speed | **No**                                                     | Optional                       | Yes              |
+| Per-task sandbox          | **Yes** — kernel-level, opt-in                             | No                             | No               |
+| Plugin API                | **Yes** — executor / cache / telemetry seams               | No                             | Yes (TS-tied)    |
+| OTel CI/CD spans          | **Yes** — `otel()` plugin, zero OTel-SDK deps              | No                             | Paid             |
+| Install                   | **Single binary** — npm or 1 curl line, no Node/Bun needed | npm + Node                     | npm + Node       |
 
 ¹ Wall-clock, direct binaries, same machine and workspace — full
 methodology and more scenarios in
-[`docs/benchmarks.md`](docs/benchmarks.md).
+[`packages/vx/docs/benchmarks.md`](packages/vx/docs/benchmarks.md).
 
 ## Switching from another runner
 
@@ -233,7 +263,9 @@ Differences to know:
 - Persistent tasks: `persistent: { readyWhen: 'regex' }` (Turbo uses just `persistent: true`).
 - Remote caching is a plugin, not a built-in — connect one and every `vx run` reads through it.
 
-Side-by-side feature matrix + every known gap: [`docs/comparison.md`](./docs/comparison.md).
+Side-by-side feature matrix + every known gap: [`packages/vx/docs/comparison.md`](packages/vx/docs/comparison.md).
+What a Turbo or Nx user relies on, spelled in vx and pinned by a test:
+[`packages/vx/docs/parity.md`](packages/vx/docs/parity.md).
 
 ## Architecture (one paragraph)
 
@@ -252,24 +284,24 @@ versioned telemetry contract (`TelemetryRecord` / `RunSummaryRecord`)
 them. Core never imports a plugin; the arrow only points plugin → core.
 Every module has a docs page; every interface is a swappable seam.
 
-Read [`docs/architecture.md`](./docs/architecture.md) for the module
-map; the design record lives under [`docs/design/`](./docs/design/).
+Read [`packages/vx/docs/architecture.md`](packages/vx/docs/architecture.md) for the module
+map; the design record lives under [`packages/vx/docs/design/`](packages/vx/docs/design/).
 
 ## Documentation
 
-Full technical docs live under [`docs/`](./docs/) and on the
+Full technical docs live under [`packages/vx/docs/`](packages/vx/docs/) and on the
 [documentation site](https://vznjs.github.io/vx/):
 
-- [`docs/architecture.md`](./docs/architecture.md) — module map + data flow
-- [`docs/schema.md`](./docs/schema.md) — every config field
-- [`docs/caching.md`](./docs/caching.md) — cache-key derivation + invalidation table
-- [`docs/execution.md`](./docs/execution.md) — `vx run` lifecycle
-- [`docs/cli.md`](./docs/cli.md) — every flag
-- [`docs/comparison.md`](./docs/comparison.md) — Turbo / Nx / vite-task feature matrix
-- [`docs/modules/`](./docs/modules/) — one reference page per source module
+- [`packages/vx/docs/architecture.md`](packages/vx/docs/architecture.md) — module map + data flow
+- [`packages/vx/docs/schema.md`](packages/vx/docs/schema.md) — every config field
+- [`packages/vx/docs/caching.md`](packages/vx/docs/caching.md) — cache-key derivation + invalidation table
+- [`packages/vx/docs/execution.md`](packages/vx/docs/execution.md) — `vx run` lifecycle
+- [`packages/vx/docs/cli.md`](packages/vx/docs/cli.md) — every flag
+- [`packages/vx/docs/comparison.md`](packages/vx/docs/comparison.md) — Turbo / Nx / vite-task feature matrix
+- [`packages/vx/docs/modules/`](packages/vx/docs/modules/) — one reference page per source module
 
-The design record lives under [`docs/design/`](./docs/design/); the
-maintainers' handoff is [`docs/STATUS.md`](./docs/STATUS.md).
+The design record lives under [`packages/vx/docs/design/`](packages/vx/docs/design/); the
+maintainers' handoff is [`packages/vx/docs/STATUS.md`](packages/vx/docs/STATUS.md).
 
 ## Status
 
@@ -280,19 +312,21 @@ the project dogfoods itself (`vx run ci`). Published on npm:
 binary).
 
 Production readiness for the **core task runner**: the semantics are
-solid; it is dogfooded continuously. The main operational rough edge
-is Windows (unsupported).
-
-| Surface                                          | Maturity             | Notes                                                                        |
-| ------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------- |
-| Core task runner + caching                       | **production-ready** | dogfooded continuously; ~2,500 core tests + the package suites, green        |
-| `vx run --verify` (provable cache correctness)   | **shippable**        | determinism + input-completeness proofs; CI-gate recipe in docs              |
-| Plugin pipeline (9 hooks, `commands` included)   | **shippable**        | crash-isolated, re-validated; core's own executor + cache are plugins        |
-| `vx init` / `vx migrate` (scripts, Turbo, Nx)    | **shippable**        | one config per package, TODOs where a source cannot say                      |
-| REAPI remote cache + execution (`@vzn/vx-reapi`) | **shippable**        | Bazel AC + CAS + Execute; NativeLink / BuildBuddy / Buildbarn / bazel-remote |
-| OTel export (`@vzn/vx-otel`)                     | **shippable**        | OTLP traces + metrics + logs, zero SDK deps                                  |
-| GitHub Actions (`@vzn/vx-github`)                | **shippable**        | job summary + Checks API run                                                 |
-| MCP server (`@vzn/vx-mcp`)                       | **shippable**        | `vx mcp` — read-only tools for AI agents, no SDK                             |
+solid; it is dogfooded continuously. Linux and macOS, x64 and arm64;
+Windows runs vx under WSL (POSIX shell is the API), with no native
+build.
+
+| Surface                                            | Maturity             | Notes                                                                                                                                                             |
+| -------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Core task runner + caching                         | **production-ready** | dogfooded continuously; ~2,500 core tests + the package suites, green                                                                                             |
+| Plugin pipeline (9 hooks, `commands` included)     | **shippable**        | crash-isolated, re-validated; the local executor + cache are the floor under every plugin                                                                         |
+| `vx init` / `@vzn/vx-migrate` (scripts; Turbo, Nx) | **shippable**        | one config per package, TODOs where a source cannot say                                                                                                           |
+| REAPI remote cache + execution (`@vzn/vx-reapi`)   | **shippable**        | Bazel AC + CAS + Execute; NativeLink / BuildBuddy / Buildbarn / bazel-remote                                                                                      |
+| OTel export (`@vzn/vx-otel`)                       | **shippable**        | OTLP traces + metrics + logs, zero SDK deps                                                                                                                       |
+| GitHub Actions (`@vzn/vx-github`)                  | **shippable**        | job summary + Checks API run                                                                                                                                      |
+| MCP server (`@vzn/vx-mcp`)                         | **shippable**        | `vx mcp` — read-only tools for AI agents, no SDK                                                                                                                  |
+| Adoption (`@vzn/vx-migrate`)                       | **shippable**        | `turbo()`: a `turbo.json` workspace runs with no `vx.config` written; `turboCache()` / `nxCache()`: any `/v8/artifacts` or Nx `/v1/cache` server; the migrate CLI |
+| Lockfile keys (`@vzn/vx-lockfile`)                 | **shippable**        | `pnpm()` `bun()` `npm()` `yarn()`: per-project dependency-closure keys; `--affected` follows                                                                      |
 
 ## Development
 
@@ -303,7 +337,7 @@ bun packages/vx/src/bin.ts run ci --all     # lint + test + docs build, every pa
 bun packages/vx/src/bin.ts run build --filter @vzn/vx   # cross-target binaries → packages/vx/dist/
 ```
 
-vx is self-hosted: every dev task routes through `bun packages/vx/src/bin.ts run <task>` per each package's own `vx.config.ts`. No `package.json` scripts; CI invokes vx directly. Start with [`docs/STATUS.md`](docs/STATUS.md) — the living handoff — and `CLAUDE.md`.
+vx is self-hosted: every dev task routes through `bun packages/vx/src/bin.ts run <task>` per each package's own `vx.config.ts`. No `package.json` scripts; CI invokes vx directly. Start with [`packages/vx/docs/STATUS.md`](packages/vx/docs/STATUS.md) — the living handoff — and `CLAUDE.md`.
 
 ## License
 

package/package.json

@@ -1,24 +1,12 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.18",
+  "version": "0.0.21",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "import": "./src/index.ts"
-    },
-    "./plugins/local-executor": {
-      "types": "./src/plugins/local-executor/index.ts",
-      "import": "./src/plugins/local-executor/index.ts"
-    },
-    "./plugins/local-cache": {
-      "types": "./src/plugins/local-cache/index.ts",
-      "import": "./src/plugins/local-cache/index.ts"
-    },
-    "./plugins/schedule-history": {
-      "types": "./src/plugins/schedule-history/index.ts",
-      "import": "./src/plugins/schedule-history/index.ts"
     }
   },
   "types": "./src/index.ts",
@@ -29,23 +17,25 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.18",
-    "@vzn/vx-linux-arm64": "0.0.18",
-    "@vzn/vx-darwin-x64": "0.0.18",
-    "@vzn/vx-darwin-arm64": "0.0.18"
+    "@vzn/vx-linux-x64": "0.0.21",
+    "@vzn/vx-linux-arm64": "0.0.21",
+    "@vzn/vx-darwin-x64": "0.0.21",
+    "@vzn/vx-darwin-arm64": "0.0.21"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.56"
+    "@anthropic-ai/sandbox-runtime": "^0.0.75"
   },
   "files": [
     "index.ts",
-    "plugins",
     "src",
     "launcher.mjs",
     "README.md",
     "LICENSE"
   ],
-  "repository": "https://github.com/vznjs/vx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git"
+  },
   "homepage": "https://github.com/vznjs/vx#readme",
   "bugs": "https://github.com/vznjs/vx/issues",
   "license": "MIT",

package/src/bin.ts

@@ -1,7 +1,13 @@
 #!/usr/bin/env bun
-import { run } from './cli/index.js'
+import { registerCoreAlias, run } from './cli/index.js'
 import { isUserError } from './util/index.js'
 
+// Every `import … from '@vzn/vx'` this process evaluates — a plugin
+// 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>>)
+
 // Wrapped in an explicit async main so `bun build --compile` accepts
 // the file. The compile target doesn't allow top-level await.
 async function main(): Promise<void> {
@@ -13,7 +19,11 @@ async function main(): Promise<void> {
     // on. Everything else gets the full stack so internal bugs are
     // debuggable.
     if (isUserError(err)) {
-      process.stderr.write(`vx: ${err.message}\n`)
+      // A message that already names the tool (`vx why: …`, thrown by a verb
+      // that wants its own name in the line) is printed as it is; prefixing
+      // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
+      const m = err.message
+      process.stderr.write(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
     } else {
       const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
       process.stderr.write(`vx: ${message}\n`)

package/src/cache/archive.ts

@@ -37,8 +37,10 @@
 // skipped — vx's outputs are regular files, and an artifact that claims
 // otherwise silently loses the claim rather than acting on it.
 
-import { mkdir, chmod, realpath, rename, rmdir, stat, unlink, utimes } from 'node:fs/promises'
+import { chmodSync, renameSync, statSync, utimesSync } from 'node:fs'
+import { mkdir, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
+import { UserError } from '../util/index.js'
 import { TarFormatError, type TarInput, tarEntries, tarPack, tarSize } from './tar-stream.js'
 
 /** Archive entry name carrying the per-output mode/mtime sidecar. */
@@ -58,6 +60,20 @@ interface MetaFile {
    *  container is versioned by CACHE_VERSION, which gates reads. */
   version: 1
   files: Record<string, [mode: number, mtimeMs: number]>
+  /**
+   * What the PRODUCING execution used (2026-09-12, additive: an artifact
+   * without it reads as before). Rides the artifact so a machine that
+   * never ran the task — a fresh CI runner on a remote hit — still learns
+   * what it needs; every wire ships the bytes verbatim, so no seam
+   * changes.
+   */
+  exec?: ExecUsage
+}
+
+/** CPU time and peak RSS of the execution that produced an artifact. */
+export interface ExecUsage {
+  cpuMs?: number
+  peakRssBytes?: number
 }
 
 /** One regular file in an artifact, with its restore metadata resolved. */
@@ -88,6 +104,8 @@ export class ArchiveSecurityError extends Error {
 export interface PackArgs {
   stdout: string
   outputs: ReadonlyMap<string, string>
+  /** The producing execution's usage, when the runner reported it. */
+  exec?: ExecUsage | undefined
 }
 
 /** A packed artifact's plan: its entries with their stats, and the tar's exact size. */
@@ -106,9 +124,28 @@ export interface ArtifactPlan {
  */
 export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const meta: MetaFile = { version: 1, files: {} }
+  const exec = usageOf(args.exec)
+  if (exec !== undefined) meta.exec = exec
   const files = await Promise.all(
     [...args.outputs].map(async ([name, abs]) => {
-      const st = await stat(abs)
+      // `stat` follows a symlink, so a link to a file is packed as that
+      // file's bytes and comes back as a regular file. A link to a
+      // directory, or a dangling one, has no bytes to pack: refuse loudly
+      // rather than store an entry that restores to nothing.
+      const shown = name.startsWith('outputs/') ? name.slice('outputs/'.length) : name
+      const st = await stat(abs).catch((err: NodeJS.ErrnoException) => {
+        if (err.code === 'ENOENT') {
+          throw new UserError(
+            `output ${shown} is a dangling symlink: vx stores regular files only — emit a file, or exclude it from cache.outputs`,
+          )
+        }
+        throw err
+      })
+      if (!st.isFile()) {
+        throw new UserError(
+          `output ${shown} is not a regular file (a symlink to a directory?): vx stores regular files only — emit a file, or exclude it from cache.outputs`,
+        )
+      }
       meta.files[name] = [st.mode & 0o777, Math.floor(st.mtimeMs)]
       return {
         name,
@@ -189,14 +226,19 @@ function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
  */
 export async function scanArtifact(
   tar: ReadableStream<Uint8Array>,
-): Promise<{ entries: ArchiveEntry[]; stdout: string | null }> {
+): Promise<{ entries: ArchiveEntry[]; stdout: string | null; exec: ExecUsage | undefined }> {
   const seen: Array<{ name: string; size: number; mtimeMs: number }> = []
   let meta: MetaFile['files'] = {}
+  let exec: ExecUsage | undefined
   let stdout: string | null = null
   for await (const e of tarEntries(tar)) {
     if (e.type !== '0') continue
     if (e.name === META_ENTRY) {
-      meta = (JSON.parse(await textOf(e.body)) as MetaFile).files ?? {}
+      const parsed = JSON.parse(await textOf(e.body)) as MetaFile
+      meta = parsed.files ?? {}
+      // The ingest side is the untrusted boundary: a foreign sidecar's
+      // usage is taken only when it is a plain non-negative number.
+      exec = usageOf(parsed.exec)
       continue
     }
     assertSafeName(e.name)
@@ -212,9 +254,21 @@ export async function scanArtifact(
       return { name: s.name, size: s.size, mode: m?.[0] ?? 0o644, mtimeMs: m?.[1] ?? s.mtimeMs }
     }),
     stdout,
+    exec,
   }
 }
 
+/** The usage worth carrying: each axis a finite non-negative number, or absent; nothing → undefined. */
+function usageOf(raw: unknown): ExecUsage | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const { cpuMs, peakRssBytes } = raw as { cpuMs?: unknown; peakRssBytes?: unknown }
+  const out: { cpuMs?: number; peakRssBytes?: number } = {}
+  if (typeof cpuMs === 'number' && Number.isFinite(cpuMs) && cpuMs >= 0) out.cpuMs = cpuMs
+  if (typeof peakRssBytes === 'number' && Number.isFinite(peakRssBytes) && peakRssBytes >= 0)
+    out.peakRssBytes = peakRssBytes
+  return out.cpuMs === undefined && out.peakRssBytes === undefined ? undefined : out
+}
+
 /**
  * Restore from `tar`, the DECOMPRESSED archive as a byte stream:
  * `outputs/<rel>` lands under `destDir/<rel>` and — when `workspaceDest`
@@ -314,6 +368,16 @@ class Extractor {
   private inflight: Promise<unknown>[] = []
   private inflightBytes = 0
   private readonly realBaseCache = new Map<string, string>()
+  // Per-directory memos. An artifact holds a few files per directory
+  // (payload's ui: 4,069 files in 535 directories), and the containment
+  // walk and the `mkdir -p` are properties of the directory, not the
+  // entry: doing both once per directory took the restore of that
+  // artifact from 220–300 µs per file to the write itself. The window
+  // this opens — a symlink planted at a validated directory between two
+  // of its entries — is the same one that already lies between an
+  // entry's own check and its write.
+  private readonly containedDirs = new Set<string>()
+  private readonly ensuredDirs = new Set<string>()
 
   constructor(
     private readonly destDir: string,
@@ -382,6 +446,18 @@ class Extractor {
     if (targetResolved !== baseResolved && !targetResolved.startsWith(baseResolved + path.sep)) {
       throw new ArchiveSecurityError(`archive entry escapes destDir (unsafe): ${name}`)
     }
+    const parentResolved = path.dirname(targetResolved)
+    if (this.containedDirs.has(parentResolved)) return
+    await this.assertParentContained(base, targetResolved, name)
+    this.containedDirs.add(parentResolved)
+  }
+
+  private async assertParentContained(
+    base: string,
+    targetResolved: string,
+    name: string,
+  ): Promise<void> {
+    const baseResolved = path.resolve(base)
     const realBase = await this.realBaseOf(base)
     // Only ancestors strictly BELOW the base are candidates — those are the
     // ones a poisoned entry could follow out of the tree. The walk must never
@@ -418,7 +494,12 @@ class Extractor {
     target: string,
     body: Uint8Array | AsyncIterable<Uint8Array>,
   ): Promise<void> {
-    const created = await mkdir(path.dirname(target), { recursive: true })
+    const dir = path.dirname(target)
+    let created: string | undefined
+    if (!this.ensuredDirs.has(dir)) {
+      created = await mkdir(dir, { recursive: true })
+      this.ensuredDirs.add(dir)
+    }
     // Write beside the target and RENAME into place. rename(2) replaces
     // the destination's directory ENTRY without following it, which is
     // what makes this both link-safe and concurrency-safe:
@@ -440,7 +521,14 @@ class Extractor {
     this.staged.push({ name, tmp, target, created })
     if (body instanceof Uint8Array) {
       this.inflightBytes += body.byteLength
-      const write = Bun.write(tmp, body)
+      // `writeFile`, not `Bun.write`: for a buffer this size `Bun.write`
+      // does the open, write and close on the calling thread and only
+      // its promise is asynchronous, so ten restores in flight wrote
+      // their 14,430 files one after another — a serial restore of
+      // payload took the same 6–7 s as one at concurrency 10, and a CPU
+      // profile put 6.7 of its 8.0 s inside `write` (2026-09-11). The
+      // thread-pool write lets the restores overlap their I/O.
+      const write = writeFile(tmp, body)
       // A write that fails before `commit` or `abort` awaits it must not
       // surface as an unhandled rejection; the awaiting `Promise.all` still
       // sees the error through the original promise.
@@ -464,20 +552,31 @@ class Extractor {
     await Promise.all(pending)
   }
 
-  /** Apply each entry's mode and mtime, then rename everything into place. */
+  /**
+   * Apply each entry's mode and mtime, then rename everything into place.
+   * Synchronous calls in batches: the three metadata calls per file are a
+   * few microseconds each on the calling thread and ~40 µs each as
+   * thread-pool round trips, and a large artifact has thousands of them
+   * (measured 2026-09-11 on payload's ui, 4,069 files: 892 ms → see the
+   * archive bench). A yield every `COMMIT_BATCH` files keeps the other
+   * restores' round trips flowing. The chmod is skipped when the mode is
+   * the one the temp file was created with — the common case.
+   */
   async commit(metaFor: (name: string) => [mode: number, mtimeMs: number]): Promise<void> {
     await this.drain()
-    await Promise.all(
-      this.staged.map(async (s) => {
-        const [mode, mtimeMs] = metaFor(s.name)
-        if (mode !== 0) await chmod(s.tmp, mode & 0o777)
-        if (mtimeMs > 0) {
-          const t = mtimeMs / 1000
-          await utimes(s.tmp, t, t)
-        }
-        await rename(s.tmp, s.target)
-      }),
-    )
+    const first = this.staged[0]
+    const createdMode = first === undefined ? -1 : statSync(first.tmp).mode & 0o777
+    let n = 0
+    for (const s of this.staged) {
+      const [mode, mtimeMs] = metaFor(s.name)
+      if (mode !== 0 && (mode & 0o777) !== createdMode) chmodSync(s.tmp, mode & 0o777)
+      if (mtimeMs > 0) {
+        const t = mtimeMs / 1000
+        utimesSync(s.tmp, t, t)
+      }
+      renameSync(s.tmp, s.target)
+      if (++n % COMMIT_BATCH === 0) await new Promise<void>((r) => setImmediate(r))
+    }
     this.staged.length = 0
   }
 
@@ -511,6 +610,9 @@ class Extractor {
   }
 }
 
+/** Files renamed into place between two yields of a commit. */
+const COMMIT_BATCH = 256
+
 /** Per-process counter for extract temp names; uniqueness only. */
 let tmpSeq = 0