@vzn/vx 0.0.640 → 0.0.642

package/src/cache/archive.ts

@@ -20,11 +20,13 @@
 // holding more than a chunk. `Bun.Archive` used to do all three and
 // needed the whole tar in memory on every side — restoring a 150 MiB
 // artifact peaked at 3.2× its size, saving one at 4.7× (measured
-// 2026-09-03). Every regular entry is written beside its target under a
-// `.vx-tmp-*` name and renamed into place only once the WHOLE archive has
-// been read and every name proven safe, so a poisoned entry anywhere —
-// even the last one — leaves nothing behind but the empty directories it
-// needed, which are pruned too.
+// 2026-09-03). Every regular entry is written to the workspace's staging
+// directory (`.vx/tmp/<pid>-0/`, vx's own, never an output folder) and
+// renamed over its target only once the WHOLE archive has been read and
+// every name proven safe, so a poisoned entry anywhere — even the last
+// one — leaves nothing behind but the empty directories it needed, which
+// are pruned too, and a killed restore leaves its temps where the next
+// run sweeps them (`sweepStaging`).
 //
 // What stays here is the part no tar reader can decide for us: WHERE an
 // entry may land on disk. Every name is validated and every destination
@@ -32,21 +34,44 @@
 // cache artifact is attacker-reachable (a poisoned remote, a tampered
 // local entry) and "zip slip" is the class.
 //
-// Entries that are not regular files (symlinks, hardlinks, devices,
+// Tar entries that are not regular files (symlinks, hardlinks, devices,
 // FIFOs) are never materialised — the reader reports them only to be
-// skipped — vx's outputs are regular files, and an artifact that claims
-// otherwise silently loses the claim rather than acting on it.
+// skipped. An output symlink rides the sidecar instead (`links`), its
+// target held to the workspace on both sides.
 
 import {
   chmodSync,
+  chownSync,
+  closeSync,
+  constants,
+  existsSync,
+  fchmodSync,
+  fstatSync,
+  futimesSync,
   lstatSync,
+  openSync,
   readFileSync,
+  readlinkSync,
   realpathSync,
-  renameSync,
   statSync,
   utimesSync,
+  writeFileSync,
 } from 'node:fs'
-import { lstat, mkdir, readlink, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import type { Stats } from 'node:fs'
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  readlink,
+  realpath,
+  rename,
+  rm,
+  rmdir,
+  stat,
+  symlink,
+  unlink,
+  writeFile,
+} from 'node:fs/promises'
 import path from 'node:path'
 import { UserError } from '../util/index.js'
 import { WORKSPACE_OUTPUT_PREFIX } from './layer.js'
@@ -60,6 +85,7 @@ import {
   tarSize,
 } from './tar-stream.js'
 import { ON_THREAD_MAX } from './zstd.js'
+import { readUmask, restoredMode } from './umask.js'
 
 /** Archive entry name carrying the per-output mode/mtime sidecar. */
 const META_ENTRY = '.vx-meta.json'
@@ -174,6 +200,18 @@ interface MetaFile {
    */
   key?: string
   files: Record<string, [mode: number, mtimeMs: number]>
+  /**
+   * The empty directories under the outputs, as entry names
+   * (`outputs/dist/empty`): a tar of regular files cannot hold them, and
+   * a hit that dropped them left another tree than the miss (v44).
+   */
+  dirs?: string[]
+  /**
+   * The symlinks under the outputs, entry name → the link's target as
+   * written (relative, inside the workspace): a hit makes the link, as
+   * Turbo and Nx do, where it once packed a copy of the target (v45).
+   */
+  links?: Record<string, string>
   /**
    * What the PRODUCING execution used (2026-09-12, additive: an artifact
    * without it reads as before). Rides the artifact so a machine that
@@ -220,22 +258,12 @@ interface PackArgs {
   key?: string
   stdout: string
   outputs: ReadonlyMap<string, string>
+  /** Entry names of the empty directories under the outputs. */
+  dirs?: readonly string[] | undefined
   /** The producing execution's usage, when the runner reported it. */
   exec?: ExecUsage | undefined
-  /**
-   * The project directory a symlinked output must resolve inside. vx reads
-   * outputs outside the task's sandbox, so a link a sandboxed task planted
-   * to a file it could not read (another project's, the user's home) packed
-   * that file into the artifact and the remote (L-23). A link to another
-   * output of the same artifact is packed wherever it is.
-   */
-  within?: string
-  /**
-   * For a sandboxed task: whether it could read this canonical path. A
-   * symlinked output inside `within` whose target it could not read is
-   * refused like one outside it.
-   */
-  readable?: ((real: string) => boolean) | undefined
+  /** The workspace root an output symlink's target must stay inside; absent, every link is refused. */
+  root?: string
 }
 
 /** The largest second count ustar's 12-byte mtime field holds: 11 octal digits. */
@@ -255,8 +283,7 @@ export interface ArtifactPlan {
  * mtime) and lay out the tar — stdout first, the outputs, the sidecar
  * last — with its exact size, so the caller can choose the one-call pack
  * for a small artifact and the streamed one for a large one before a
- * byte is read. A symlinked output is stored as its target's content,
- * when that target is inside `within`.
+ * byte is read. A symlinked output is stored as its link (`links`).
  */
 export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const meta: MetaFile = { version: 1, files: {} }
@@ -264,29 +291,13 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   // cost more than the stat. Many go to the pool together, as before.
   const few = args.outputs.size <= ON_THREAD_STATS
   const lstatOf = few ? async (p: string) => lstatSync(p) : lstat
-  const statOf = few ? async (p: string) => statSync(p) : stat
-  const realpathOf = (p: string) => realOf(p, few)
-  let withinReal: Promise<string> | undefined
-  // Where this artifact's own non-link outputs really are: a link to one of
-  // them packs bytes the task wrote itself. A root-anchored output tree is
-  // outside every project, so `gen/latest -> v2.txt` there was refused and
-  // the task never cached (J's lead).
-  let ownReal: Promise<Set<string>> | undefined
-  const ownOutputs = (): Promise<Set<string>> =>
-    (ownReal ??= Promise.all(
-      [...args.outputs.values()].map(async (abs) =>
-        (await lstatOf(abs)).isSymbolicLink() ? null : realpathOf(abs),
-      ),
-    ).then((all) => new Set(all.filter((p): p is string => p !== null))))
+  const readlinkOf = few ? async (p: string) => readlinkSync(p) : readlink
   if (args.key !== undefined) meta.key = args.key
+  if (args.dirs !== undefined && args.dirs.length > 0) meta.dirs = [...args.dirs]
   const exec = usageOf(args.exec)
   if (exec !== undefined) meta.exec = exec
   const files = await Promise.all(
     [...args.outputs].map(async ([name, 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.
       // The path as the config spells it: a root-anchored output's entry
       // name is vx's own `workspace-outputs/…` (M-66).
       const shown = name.startsWith('outputs/')
@@ -304,45 +315,33 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
           `${shown} is under workspace-outputs/, a name vx's artifacts reserve for outputs.workspaceFiles — write the task's files to another directory, or take them back with a '!' entry`,
         )
       }
-      const dangling = (err: NodeJS.ErrnoException): never => {
-        if (err.code === 'ENOENT') {
+      const st = await lstatOf(abs)
+      if (st.isSymbolicLink()) {
+        // Kept as the link, never read through: no byte of its target
+        // enters the artifact, so a link to a file the task could not
+        // read packs nothing of it (L-23).
+        const to = await readlinkOf(abs)
+        if (path.isAbsolute(to)) {
           throw new UserError(
-            `${shown} is a dangling symlink: vx stores regular files only — emit a file there, or narrow cache.outputs.files to the files the task produces, or take it back with a '!' entry`,
+            `${shown} is a symlink to an absolute path (${to}): vx restores a link as written, and an absolute one names this machine's checkout — make it relative, or take it back with a '!' entry`,
           )
         }
-        throw err
-      }
-      // lstat, so a regular file costs no second call; only a link is
-      // resolved, and its body is read from the path this check resolved.
-      let src = abs
-      let st = await lstatOf(abs)
-      if (st.isSymbolicLink()) {
-        src = await realpathOf(abs).catch(dangling)
-        if (args.within !== undefined) {
-          withinReal ??= realpathOf(args.within)
-          const root = await withinReal
-          if (!src.startsWith(root + path.sep) && !(await ownOutputs()).has(src)) {
-            throw new UserError(
-              `${shown} is a symlink to ${src}, outside the project: vx packs a symlinked output as its target's bytes, and a project's outputs come from its own directory — emit a file there, or take it back with a '!' entry`,
-            )
-          }
-        }
-        if (args.readable !== undefined && !args.readable(src) && !(await ownOutputs()).has(src)) {
+        if (args.root === undefined || !inside(path.resolve(path.dirname(abs), to), args.root)) {
           throw new UserError(
-            `${shown} is a symlink to ${src}, which the task's sandbox does not let it read: vx packs a symlinked output as its target's bytes — emit a file there, grant the target in exec.sandbox.allow.read, or take it back with a '!' entry`,
+            `${shown} is a symlink to ${to}, outside the workspace: vx restores a link as written, and a project's outputs stay in its workspace — emit a file there, or take it back with a '!' entry`,
           )
         }
-        st = await statOf(src).catch(dangling)
+        return { name, link: to }
       }
       if (!st.isFile()) {
         throw new UserError(
-          `${shown} is not a regular file (a symlink to a directory?): vx stores regular files only — emit a file there, or narrow cache.outputs.files to the files the task produces, or take it back with a '!' entry`,
+          `${shown} is not a regular file: vx stores regular files and symlinks only — emit a file there, or narrow cache.outputs.files to the files the task produces, or take it back with a '!' entry`,
         )
       }
       const mode = st.mode & 0o777
       return {
         name,
-        abs: src,
+        abs,
         size: st.size,
         mode,
         mtimeMs: Math.floor(st.mtimeMs),
@@ -354,12 +353,19 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
     }),
   )
   // In the outputs' order, not as each stat settled: one tree, one artifact.
-  for (const f of files) meta.files[f.name] = [f.mode, f.mtimeMs]
+  const regular: Array<Exclude<(typeof files)[number], { link: string }>> = []
+  for (const f of files) {
+    if ('link' in f) (meta.links ??= {})[f.name] = f.link
+    else {
+      meta.files[f.name] = [f.mode, f.mtimeMs]
+      regular.push(f)
+    }
+  }
   const stdout = new TextEncoder().encode(args.stdout)
   const metaBytes = new TextEncoder().encode(JSON.stringify(meta))
   const inputs: TarInput[] = [
     { name: STDOUT_ENTRY, size: stdout.byteLength, body: stdout },
-    ...files.map((f) => ({
+    ...regular.map((f) => ({
       name: f.name,
       size: f.size,
       mode: f.mode,
@@ -468,6 +474,10 @@ function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
 /** What a scan of an artifact reads out of it. */
 interface ArtifactScan {
   entries: ArchiveEntry[]
+  /** The sidecar's empty directories, each name proven safe. */
+  dirs: string[]
+  /** The sidecar's symlinks, `[name, target]`, each name and target proven safe. */
+  links: Array<[name: string, target: string]>
   stdout: string | null
   exec: ExecUsage | undefined
   key: string | undefined
@@ -477,6 +487,8 @@ interface ArtifactScan {
 class ScanFold {
   private readonly seen: Array<{ name: string; size: number; mtimeMs: number }> = []
   private files: MetaFile['files'] = {}
+  private dirs: string[] = []
+  private links: Array<[string, string]> = []
   private exec: ExecUsage | undefined
   private key: string | undefined
   stdout: string | null = null
@@ -484,6 +496,8 @@ class ScanFold {
   sidecar(text: string): void {
     const parsed = JSON.parse(text) as MetaFile
     this.files = parsed.files ?? {}
+    this.dirs = dirsOf(parsed)
+    this.links = linksOf(parsed)
     // The ingest side is the untrusted boundary: a foreign sidecar's
     // usage is taken only when it is a plain non-negative number.
     this.exec = usageOf(parsed.exec)
@@ -503,6 +517,8 @@ class ScanFold {
         // sidecar is metadata, never the authority on whether bytes exist.
         return { name: s.name, size: s.size, mode: m?.[0] ?? 0o644, mtimeMs: m?.[1] ?? s.mtimeMs }
       }),
+      dirs: this.dirs,
+      links: this.links,
       stdout: this.stdout,
       exec: this.exec,
       key: this.key,
@@ -568,6 +584,56 @@ export function scanTarBytes(tar: Uint8Array): ArtifactScan {
   return fold.result()
 }
 
+/**
+ * The sidecar's directory names, each held to the rules a file entry's
+ * name is (the sidecar is as attacker-reachable as the tar), and only
+ * under an output namespace.
+ */
+function dirsOf(meta: MetaFile): string[] {
+  const raw: unknown = meta.dirs
+  if (raw === undefined) return []
+  if (!Array.isArray(raw)) throw new ArchiveSecurityError('archive sidecar dirs is not a list')
+  return raw.map((name: unknown) => {
+    if (
+      typeof name !== 'string' ||
+      !(name.startsWith('outputs/') || name.startsWith(WORKSPACE_PREFIX))
+    ) {
+      throw new ArchiveSecurityError(`archive directory is not an output: ${String(name)}`)
+    }
+    assertSafeName(name)
+    return name
+  })
+}
+
+/**
+ * The sidecar's links, each name held to a file entry's rules and each
+ * target to a relative path with no NUL: where it may point is decided at
+ * the restore, which knows the workspace.
+ */
+function linksOf(meta: MetaFile): Array<[string, string]> {
+  const raw: unknown = meta.links
+  if (raw === undefined) return []
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new ArchiveSecurityError('archive sidecar links is not a map')
+  }
+  return Object.entries(raw as Record<string, unknown>).map(([name, to]) => {
+    if (!(name.startsWith('outputs/') || name.startsWith(WORKSPACE_PREFIX))) {
+      throw new ArchiveSecurityError(`archive link is not an output: ${name}`)
+    }
+    assertSafeName(name)
+    if (typeof to !== 'string' || to.length === 0 || to.includes('\0') || path.isAbsolute(to)) {
+      throw new ArchiveSecurityError(`archive link ${name} has an unsafe target: ${String(to)}`)
+    }
+    return [name, to]
+  })
+}
+
+/** `p` is `root` or under it, lexically. */
+const inside = (p: string, root: string): boolean => {
+  const r = path.resolve(root)
+  return p === r || p.startsWith(r + path.sep)
+}
+
 /** 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
@@ -595,15 +661,21 @@ export async function extractArtifactStream(
   destDir: string,
   workspaceDest: string | undefined,
   verify?: (provided: ReadonlySet<string>) => void,
+  accept?: (name: string) => boolean,
+  /** The workspace root whose `.vx/tmp/` stages the entries; absent, each stages beside its target. */
+  stageRoot?: string,
 ): Promise<Set<string>> {
   // No `mkdir -p` of the destination here: `stage` creates each entry's
   // directory chain, the destination included, and the cache restores
   // into a project directory that exists. The eager one cost every
   // restore a thread-pool round trip for an EEXIST and a stat (item 627).
-  const x = new Extractor(destDir, workspaceDest)
+  readUmask()
+  const x = new Extractor(destDir, workspaceDest, stageRoot)
   const provided = new Set<string>()
   const headerMtime = new Map<string, number>()
   let meta: MetaFile['files'] = {}
+  let dirs: string[] = []
+  let links: Array<[string, string]> = []
   try {
     const check = new SumCheck()
     for await (const e of tarEntries(tar)) {
@@ -611,10 +683,20 @@ export async function extractArtifactStream(
       const body = await check.body(e.name, e.body)
       if (body === null) continue
       if (e.name === META_ENTRY) {
-        meta = (JSON.parse(await textOf(body)) as MetaFile).files ?? {}
+        const parsed = JSON.parse(await textOf(body)) as MetaFile
+        meta = parsed.files ?? {}
+        dirs = dirsOf(parsed)
+        links = linksOf(parsed)
         continue
       }
       assertSafeName(e.name)
+      // Before anything is staged: an entry the task never declared is not
+      // this task's save, and none of the archive lands.
+      if (accept !== undefined && !accept(e.name)) {
+        throw new ArchiveSecurityError(
+          `archive entry is not one of the task's declared outputs: ${e.name}`,
+        )
+      }
       const dest = x.destFor(e.name)
       if (dest === null || dest.rel.length === 0) {
         await drain(body)
@@ -627,6 +709,38 @@ export async function extractArtifactStream(
       await x.stage(e.name, dest.base, target, e.size <= SMALL_ENTRY ? await bytesOf(body) : body)
     }
     check.done()
+    for (const name of dirs) {
+      if (accept !== undefined && !accept(name)) {
+        throw new ArchiveSecurityError(
+          `archive directory is not one of the task's declared outputs: ${name}`,
+        )
+      }
+      const dest = x.destFor(name)
+      if (dest === null || dest.rel.length === 0) continue
+      const target = path.join(dest.base, dest.rel)
+      await x.assertContained(dest.base, target, name)
+      await x.makeDir(dest.base, target)
+      // The index rows name a directory with a trailing slash.
+      provided.add(`${name}/`)
+    }
+    // A link may point only inside the workspace (the project, without one).
+    const bound = stageRoot ?? workspaceDest ?? destDir
+    for (const [name, to] of links) {
+      if (accept !== undefined && !accept(name)) {
+        throw new ArchiveSecurityError(
+          `archive link is not one of the task's declared outputs: ${name}`,
+        )
+      }
+      const dest = x.destFor(name)
+      if (dest === null || dest.rel.length === 0) continue
+      const target = path.join(dest.base, dest.rel)
+      await x.assertContained(dest.base, target, name)
+      if (!inside(path.resolve(path.dirname(target), to), bound)) {
+        throw new ArchiveSecurityError(`archive link ${name} points out of the workspace: ${to}`)
+      }
+      await x.stageLink(name, dest.base, target, to)
+      provided.add(name)
+    }
     verify?.(provided)
     // The sidecar's stat is the truth, a mode of 000 and an mtime at or
     // before the epoch included (`SOURCE_DATE_EPOCH=0`). Without one, a
@@ -644,6 +758,9 @@ export async function extractArtifactStream(
   return provided
 }
 
+/** BSD gives every new file its directory's group, setgid or not. */
+const INHERITS_GROUP = process.platform === 'darwin'
+
 /**
  * Entries up to this size are buffered and written without waiting, so a
  * thousand tiny outputs restore in parallel; larger ones stream chunk by
@@ -674,8 +791,32 @@ async function bytesOf(body: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
 const textOf = async (body: AsyncIterable<Uint8Array>): Promise<string> =>
   utf8.decode(await bytesOf(body))
 
+/**
+ * Bring a target that already held the entry's bytes to its mode and
+ * mtime, through a descriptor opened without following a link: one
+ * planted since the compare is refused, never written through.
+ */
+function keep(s: Staged, ino: number, mode: number, mtimeMs: number | undefined): void {
+  const fd = openSync(s.target, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const st = fstatSync(fd)
+    if (st.ino !== ino || st.nlink !== 1) {
+      throw new Error(`${s.target} changed while it was restored`)
+    }
+    if ((st.mode & 0o7777) !== restoredMode(mode)) fchmodSync(fd, restoredMode(mode))
+    if (mtimeMs !== undefined && Math.floor(st.mtimeMs) !== mtimeMs) {
+      const t = new Date(mtimeMs)
+      futimesSync(fd, t, t)
+    }
+  } finally {
+    closeSync(fd)
+  }
+}
+
 /** One staged entry: written at `tmp`, renamed to `target` on commit. */
 interface Staged {
+  /** `tmp` is in the staging directory, not beside `target`. */
+  staged: boolean
   name: string
   tmp: string
   target: string
@@ -683,6 +824,24 @@ interface Staged {
   created: string | undefined
   /** Written by Bun's file writer, which creates with 0664 where `writeFile` uses 0666 (before the umask). */
   streamed: boolean
+  /** The destination it is contained in. */
+  base: string
+  /** The target already holds the entry's bytes: nothing was written, and only its mode and mtime may change. */
+  same?: number
+  /** `tmp` was copied beside `target`, which is on another filesystem than the staging (`crossOver`). */
+  beside?: true
+  /** A symlink to this target, made at `tmp`: no mode, no mtime. */
+  link?: string
+  /** `tmp` is inside the staged copy of this missing directory, which commit renames whole. */
+  tree?: string
+}
+
+/** A directory missing in the tree, built in the staging directory and renamed in whole. */
+interface Tree {
+  at: string
+  base: string
+  /** The empty directories under it the entry holds. */
+  dirs: string[]
 }
 
 /**
@@ -692,6 +851,8 @@ interface Staged {
  */
 class Extractor {
   private readonly staged: Staged[] = []
+  /** Empty output directories made, with the top of each chain created. */
+  private readonly madeDirs: Array<{ dir: string; created: string }> = []
   private inflight: Promise<unknown>[] = []
   private inflightBytes = 0
   private readonly realBaseCache = new Map<string, string>()
@@ -705,10 +866,16 @@ class Extractor {
   // entry's own check and its write.
   private readonly containedDirs = new Set<string>()
   private readonly ensuredDirs = new Set<string>()
+  private readonly trees = new Map<string, Tree>()
+  // Directories the containment walk found missing, which `treeFor` would
+  // otherwise probe again. A directory made since fails the tree's rename,
+  // and the entries then go in one by one.
+  private readonly seenAbsent = new Set<string>()
 
   constructor(
     private readonly destDir: string,
     private readonly workspaceDest: string | undefined,
+    private readonly stageRoot: string | undefined,
   ) {}
 
   /** Each namespace anchors at its own destination dir. */
@@ -797,6 +964,7 @@ class Extractor {
       // trip and error (X-163). A dangling link is there and falls through,
       // as does an lstat that fails otherwise: the realpath decides.
       if (absent(probe)) {
+        this.seenAbsent.add(probe)
         probe = path.dirname(probe)
         continue
       }
@@ -844,6 +1012,82 @@ class Extractor {
     return mkdir(real, { recursive: true })
   }
 
+  /**
+   * Where an entry in `dir` is written when a directory on the way to it is
+   * missing: inside a copy of the topmost missing one, built in the staging
+   * directory and renamed into place whole on commit. One rename per
+   * missing directory, not one per file: every file of a restore into a
+   * cleaned tree renamed across directories, all out of one staging
+   * directory, and the kernel time of a 5,000-artifact restore doubled
+   * (2026-10-17). A reader sees the directory complete or not at all.
+   * Undefined where the group or filesystem would differ from a write in
+   * place: the entry is then staged and renamed alone.
+   */
+  private async treeFor(base: string, dir: string): Promise<string | undefined> {
+    if (this.stageRoot === undefined) return undefined
+    const abs = path.resolve(dir)
+    for (const [top, t] of this.trees) {
+      if (abs === top || abs.startsWith(top + path.sep)) return t.at + abs.slice(top.length)
+    }
+    const baseResolved = path.resolve(base)
+    let top: string | undefined
+    let probe = abs
+    while (
+      probe.startsWith(baseResolved + path.sep) &&
+      (this.seenAbsent.has(probe) || absent(probe))
+    ) {
+      top = probe
+      probe = path.dirname(probe)
+    }
+    if (top === undefined) return undefined
+    const staging = await stagingDir(this.stageRoot)
+    const st = statSync(staging)
+    const parent = statSync(probe, { throwIfNoEntry: false })
+    if (
+      parent === undefined ||
+      !parent.isDirectory() ||
+      parent.dev !== st.dev ||
+      ((parent.mode | st.mode) & 0o2000) !== 0 ||
+      (INHERITS_GROUP && parent.gid !== st.gid)
+    ) {
+      return undefined
+    }
+    const at = path.join(staging, (tmpSeq++).toString(36))
+    this.trees.set(top, { at, base, dirs: [] })
+    return at + abs.slice(top.length)
+  }
+
+  /** `dir` made, once per extraction. */
+  private async ensure(dir: string): Promise<void> {
+    if (this.ensuredDirs.has(dir)) return
+    await mkdir(dir, { recursive: true })
+    this.ensuredDirs.add(dir)
+  }
+
+  /** The tree `target` is staged in. */
+  private treeOf(target: string): string | undefined {
+    for (const top of this.trees.keys()) if (target.startsWith(top + path.sep)) return top
+    return undefined
+  }
+
+  /** An empty output directory: made now, pruned by `abort` if it was not there. */
+  async makeDir(base: string, dir: string): Promise<void> {
+    const staged = await this.treeFor(base, dir)
+    if (staged !== undefined) {
+      await this.ensure(staged)
+      this.trees.get(this.treeOf(dir + path.sep)!)!.dirs.push(dir)
+      return
+    }
+    let created: string | undefined
+    try {
+      created = await mkdir(dir, { recursive: true })
+    } catch (err) {
+      created = await this.mkdirThroughLink(base, dir, err as NodeJS.ErrnoException)
+    }
+    this.ensuredDirs.add(dir)
+    if (created !== undefined) this.madeDirs.push({ dir, created })
+  }
+
   /**
    * Write the entry beside its target. A buffer is written without
    * waiting, bounded by `INFLIGHT_BYTES`; a chunk stream goes to a file
@@ -856,6 +1100,25 @@ class Extractor {
     body: Uint8Array | AsyncIterable<Uint8Array>,
   ): Promise<void> {
     const dir = path.dirname(target)
+    const inTree = await this.treeFor(base, dir)
+    if (inTree !== undefined) {
+      await this.ensure(inTree)
+      const tmp = path.join(inTree, path.basename(target))
+      const streamed = !(body instanceof Uint8Array)
+      const tree = this.treeOf(target)!
+      this.staged.push({
+        staged: true,
+        name,
+        tmp,
+        target,
+        created: undefined,
+        streamed,
+        base,
+        tree,
+      })
+      await this.write(tmp, body)
+      return
+    }
     let created: string | undefined
     if (!this.ensuredDirs.has(dir)) {
       try {
@@ -865,7 +1128,33 @@ class Extractor {
       }
       this.ensuredDirs.add(dir)
     }
-    // Write beside the target and RENAME into place. rename(2) replaces
+    // A target that already holds these bytes stays: renaming over a live
+    // file costs ~0.4 ms on ext4 (auto_da_alloc), and a hit that changed
+    // one of 2,000 outputs paid it 2,000 times. Bytes, not a stat stamp: a
+    // reproducible build gives every output one mtime (item 886).
+    if (body instanceof Uint8Array && created === undefined) {
+      const st = lstatSync(target, { throwIfNoEntry: false })
+      if (
+        st !== undefined &&
+        st.isFile() &&
+        st.nlink === 1 &&
+        st.size === body.byteLength &&
+        readFileSync(target).equals(body)
+      ) {
+        this.staged.push({
+          staged: false,
+          name,
+          tmp: '',
+          target,
+          created,
+          streamed: false,
+          base,
+          same: st.ino,
+        })
+        return
+      }
+    }
+    // Write apart from 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:
     //
@@ -882,15 +1171,19 @@ class Extractor {
     //
     // A directory at the target makes the rename fail — the same
     // fail-closed outcome the plain write had.
-    // The temp is a sibling with its own short name, never `<target>.suffix`:
-    // a suffix pushed a legal name of 242–255 bytes past NAME_MAX, and the
-    // restore of a valid artifact failed with ENAMETOOLONG (item 666).
-    const tmp = path.join(
-      path.dirname(target),
-      `.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`,
-    )
+    // Staged under `.vx/tmp/`, so no output folder ever holds a temp: a
+    // reader or a key taken meanwhile saw `.vx-tmp-*` files beside the
+    // outputs, and a killed restore left them there (M, 2026-10-16).
+    const staged = this.stageRoot !== undefined
+    const tmp = staged
+      ? path.join(await stagingDir(this.stageRoot!), (tmpSeq++).toString(36))
+      : siblingTemp(target)
     const streamed = !(body instanceof Uint8Array)
-    this.staged.push({ name, tmp, target, created, streamed })
+    this.staged.push({ staged, name, tmp, target, created, streamed, base })
+    await this.write(tmp, body)
+  }
+
+  private async write(tmp: string, body: Uint8Array | AsyncIterable<Uint8Array>): Promise<void> {
     if (body instanceof Uint8Array) {
       this.inflightBytes += body.byteLength
       // `writeFile`, not `Bun.write`: for a buffer this size `Bun.write`
@@ -917,6 +1210,49 @@ class Extractor {
     }
   }
 
+  /** A symlink: made apart from the target like a file, renamed over it on commit. */
+  async stageLink(name: string, base: string, target: string, to: string): Promise<void> {
+    const dir = path.dirname(target)
+    const inTree = await this.treeFor(base, dir)
+    if (inTree !== undefined) {
+      await this.ensure(inTree)
+      const tmp = path.join(inTree, path.basename(target))
+      const tree = this.treeOf(target)!
+      this.staged.push({
+        staged: true,
+        name,
+        tmp,
+        target,
+        created: undefined,
+        streamed: false,
+        base,
+        link: to,
+        tree,
+      })
+      await symlink(to, tmp)
+      return
+    }
+    let created: string | undefined
+    if (!this.ensuredDirs.has(dir)) {
+      try {
+        created = await mkdir(dir, { recursive: true })
+      } catch (err) {
+        created = await this.mkdirThroughLink(base, dir, err as NodeJS.ErrnoException)
+      }
+      this.ensuredDirs.add(dir)
+    }
+    if (created === undefined) {
+      const st = lstatSync(target, { throwIfNoEntry: false })
+      if (st?.isSymbolicLink() === true && readlinkSync(target) === to) return
+    }
+    const staged = this.stageRoot !== undefined
+    const tmp = staged
+      ? path.join(await stagingDir(this.stageRoot!), (tmpSeq++).toString(36))
+      : siblingTemp(target)
+    this.staged.push({ staged, name, tmp, target, created, streamed: false, base, link: to })
+    await symlink(to, tmp)
+  }
+
   private async drain(): Promise<void> {
     const pending = this.inflight
     this.inflight = []
@@ -926,12 +1262,11 @@ class Extractor {
 
   /**
    * 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 metadata calls are synchronous: 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). The renames go to the
+   * pool, `RENAME_BATCH` at a time: each replaces a live file. The chmod is skipped when the mode is
    * the one the temp file was created with — the common case. The two
    * writers create with different modes (under umask 000: 0666 and 0664),
    * so each is stat'ed once.
@@ -940,38 +1275,256 @@ class Extractor {
     metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
   ): Promise<void> {
     await this.drain()
-    const createdModes = new Map<boolean, number>()
-    let n = 0
-    for (const s of this.staged) {
-      const [mode, mtimeMs] = metaFor(s.name)
-      let createdMode = createdModes.get(s.streamed)
-      if (createdMode === undefined) {
-        createdMode = statSync(s.tmp).mode & 0o777
-        createdModes.set(s.streamed, createdMode)
+    // One stat per directory, shared by the filesystem check and the group.
+    const dirStats = new Map<string, Stats>()
+    const statDir = (dir: string): Stats => {
+      let st = dirStats.get(dir)
+      if (st === undefined) {
+        st = statSync(dir)
+        dirStats.set(dir, st)
       }
-      if ((mode & 0o777) !== createdMode) chmodSync(s.tmp, mode & 0o777)
-      if (mtimeMs !== undefined) {
+      return st
+    }
+    await this.crossOver(statDir)
+    const created = new Map<boolean, { mode: number; uid: number; gid: number }>()
+    // The group a file written in place would take, by directory: a setgid
+    // directory's on Linux, every directory's on BSD/macOS. A file staged
+    // elsewhere took the staging directory's.
+    const setgid = new Map<string, number | null>()
+    let n = 0
+    let renames: Promise<void>[] = []
+    const checked = new Set<string>()
+    try {
+      for (const s of this.staged) {
+        if (s.tree === undefined)
+          await this.assertStillContained(s.base, path.dirname(s.target), checked)
+        const [mode, mtimeMs] = metaFor(s.name)
+        if (s.same !== undefined) {
+          keep(s, s.same, mode, mtimeMs)
+          continue
+        }
+        if (s.link !== undefined) {
+          if (s.tree !== undefined) continue
+          renames.push(handled(this.place(s, mode, undefined)))
+          if (++n % RENAME_BATCH === 0) {
+            await settle(renames)
+            renames = []
+          }
+          continue
+        }
+        if (s.beside === true) {
+          chmodSync(s.tmp, restoredMode(mode))
+          if (mtimeMs !== undefined) utimesSync(s.tmp, new Date(mtimeMs), new Date(mtimeMs))
+          renames.push(handled(this.place(s, mode, undefined)))
+          if (++n % RENAME_BATCH === 0) {
+            await settle(renames)
+            renames = []
+          }
+          continue
+        }
+        let made = created.get(s.streamed)
+        if (made === undefined) {
+          const st = statSync(s.tmp)
+          made = { mode: st.mode & 0o777, uid: st.uid, gid: st.gid }
+          created.set(s.streamed, made)
+        }
+        if (restoredMode(mode) !== made.mode) chmodSync(s.tmp, restoredMode(mode))
         // A Date, not seconds: Bun reads a negative number of seconds as
         // "now", and a Date before 1970 as itself (Bun 1.4.2).
-        const t = new Date(mtimeMs)
-        utimesSync(s.tmp, t, t)
+        const t = mtimeMs === undefined ? undefined : new Date(mtimeMs)
+        if (t !== undefined) utimesSync(s.tmp, t, t)
+        if (s.tree !== undefined) continue
+        if (s.staged) {
+          const dir = path.dirname(s.target)
+          let gid = setgid.get(dir)
+          if (gid === undefined) {
+            const st = statDir(dir)
+            gid = INHERITS_GROUP || (st.mode & 0o2000) !== 0 ? st.gid : null
+            setgid.set(dir, gid)
+          }
+          if (gid !== null && gid !== made.gid) chownSync(s.tmp, made.uid, gid)
+        }
+        renames.push(handled(this.place(s, mode, t)))
+        if (++n % RENAME_BATCH === 0) {
+          await settle(renames)
+          renames = []
+        }
       }
-      renameSync(s.tmp, s.target)
-      if (++n % COMMIT_BATCH === 0) await new Promise<void>((r) => setImmediate(r))
+    } catch (err) {
+      // Every rename in flight lands or fails before `abort` cleans up
+      // (a fuzz run on macOS, 2026-10-17).
+      await Promise.allSettled(renames)
+      throw err
     }
+    await settle(renames)
+    for (const [top, t] of this.trees) await this.placeTree(top, t, checked)
+    await this.assertLandedInside()
+    this.trees.clear()
     this.staged.length = 0
   }
 
   /**
-   * Never leave a stray `.vx-tmp-*` behind: the declared output globs would
-   * sweep it into the next artifact. Directories this extraction created
+   * Rename a staged tree to the directory it stands for. Something made
+   * there since staging (another restore of the same outputs) takes the
+   * tree's entries one by one instead, each renamed over its target.
+   */
+  private async placeTree(top: string, t: Tree, checked: Set<string>): Promise<void> {
+    await this.assertStillContained(t.base, path.dirname(top), checked)
+    try {
+      await rename(t.at, top)
+      return
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code
+      if (code !== 'EEXIST' && code !== 'ENOTEMPTY' && code !== 'ENOTDIR' && code !== 'EISDIR') {
+        throw err
+      }
+    }
+    for (const dir of t.dirs) await this.makeDirIn(t.base, dir)
+    for (const s of this.staged) {
+      if (s.tree !== top) continue
+      const dir = path.dirname(s.target)
+      await this.makeDirIn(t.base, dir)
+      await this.assertStillContained(t.base, dir, checked)
+      await rename(s.tmp, s.target)
+    }
+    await rm(t.at, { recursive: true, force: true })
+  }
+
+  private async makeDirIn(base: string, dir: string): Promise<void> {
+    try {
+      await mkdir(dir, { recursive: true })
+    } catch (err) {
+      await this.mkdirThroughLink(base, dir, err as NodeJS.ErrnoException)
+    }
+  }
+
+  /**
+   * Copy every staged entry whose target is on another filesystem than
+   * `.vx/tmp/` to a temp beside its target, before any rename: a rename
+   * there would fail EXDEV, and copying at the rename, one file at a time,
+   * left the files renamed before a failed copy (ENOSPC) new and the rest
+   * old (Growth's parity run, 2026-10-16). A failed copy throws with
+   * nothing renamed, and `abort` removes the temps made so far.
+   */
+  private async crossOver(statDir: (dir: string) => Stats): Promise<void> {
+    const dev = (dir: string): number => statDir(dir).dev
+    const cross = this.staged.filter(
+      (s) =>
+        s.staged &&
+        s.same === undefined &&
+        s.tree === undefined &&
+        dev(path.dirname(s.tmp)) !== dev(path.dirname(s.target)),
+    )
+    for (let i = 0; i < cross.length; i += RENAME_BATCH) {
+      await settle(
+        cross.slice(i, i + RENAME_BATCH).map(async (s) => {
+          const side = siblingTemp(s.target)
+          try {
+            if (s.link !== undefined) await symlink(s.link, side)
+            else await copyFile(s.tmp, side)
+          } catch (err) {
+            await unlink(side).catch(() => undefined)
+            throw err
+          }
+          const staged = s.tmp
+          s.tmp = side
+          s.beside = true
+          await unlink(staged).catch(() => undefined)
+        }),
+      )
+    }
+  }
+
+  /**
+   * Rename `s` over its target. A target on another filesystem than
+   * `.vx/tmp/` (EXDEV) is reached through a temp beside it, for that file
+   * only: the rename that replaces the live file stays atomic.
+   */
+  private async place(s: Staged, mode: number, t: Date | undefined): Promise<void> {
+    try {
+      await rename(s.tmp, s.target)
+    } catch (err) {
+      if (!s.staged || (err as NodeJS.ErrnoException).code !== 'EXDEV') throw err
+      const side = siblingTemp(s.target)
+      try {
+        if (s.link !== undefined) await symlink(s.link, side)
+        else {
+          await copyFile(s.tmp, side)
+          chmodSync(side, restoredMode(mode))
+          if (t !== undefined) utimesSync(side, t, t)
+        }
+        await rename(side, s.target)
+      } catch (e) {
+        await unlink(side).catch(() => undefined)
+        throw e
+      }
+      await unlink(s.tmp).catch(() => undefined)
+    }
+  }
+
+  /**
+   * The staging check, again at the rename: a directory on the way swapped
+   * for a link out of the base since then would carry the rename with it.
+   * Bun has no `renameat` against a held directory fd, so this is by path,
+   * once per directory per commit.
+   */
+  private async assertStillContained(
+    base: string,
+    dir: string,
+    checked: Set<string>,
+  ): Promise<void> {
+    if (checked.has(dir)) return
+    checked.add(dir)
+    const realBase = await this.realBaseOf(base)
+    const real = await realOf(dir, true)
+    if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+      throw await linkOutError(path.resolve(base), dir, realBase)
+    }
+  }
+
+  /**
+   * The check before each rename, once more after all landed: the rename
+   * runs on the thread pool, and a directory swapped for a link out in that
+   * gap carried the entry with it (restore-link-swap-rename.test.ts). An
+   * entry that landed outside is removed from there and the restore fails.
+   */
+  private async assertLandedInside(): Promise<void> {
+    const landed = new Map<string, { base: string; placed: string[] }>()
+    const add = (base: string, dir: string, placed: string): void => {
+      const at = landed.get(dir)
+      if (at === undefined) landed.set(dir, { base, placed: [placed] })
+      else at.placed.push(placed)
+    }
+    for (const s of this.staged) {
+      if (s.same === undefined && s.tree === undefined)
+        add(s.base, path.dirname(s.target), s.target)
+    }
+    for (const [top, t] of this.trees) add(t.base, path.dirname(top), top)
+    for (const [dir, { base, placed }] of landed) {
+      const realBase = await this.realBaseOf(base)
+      const real = await realOf(dir, true).catch(() => null)
+      if (real === null || real === realBase || real.startsWith(realBase + path.sep)) continue
+      await Promise.allSettled(placed.map((p) => rm(p, { recursive: true, force: true })))
+      throw await linkOutError(path.resolve(base), dir, realBase)
+    }
+  }
+
+  /**
+   * Never leave a temp behind: beside a target, the declared output globs
+   * would sweep it into the next artifact. Directories this extraction created
    * are removed bottom-up while empty; one a concurrent writer has since
    * filled is left alone.
    */
   async abort(): Promise<void> {
     await Promise.allSettled(this.inflight)
     this.inflight = []
-    await Promise.all(this.staged.map((s) => unlink(s.tmp).catch(() => undefined)))
+    await Promise.all(
+      this.staged.map((s) =>
+        s.same === undefined ? unlink(s.tmp).catch(() => undefined) : undefined,
+      ),
+    )
+    for (const t of this.trees.values()) await rm(t.at, { recursive: true, force: true })
+    this.trees.clear()
     // Newest first: a later entry's chain can sit inside an earlier one's
     // (`dist/` then `dist/sub/`), never the reverse.
     for (const s of this.staged.toReversed()) {
@@ -993,16 +1546,91 @@ class Extractor {
         dir = path.dirname(dir)
       }
     }
+    for (const { dir: made, created } of this.madeDirs.toReversed()) {
+      const top = path.resolve(created)
+      let dir = made.startsWith(top) ? made : await realOf(made).catch(() => made)
+      while (
+        dir.startsWith(top) &&
+        (await rmdir(dir).then(
+          () => true,
+          () => false,
+        ))
+      ) {
+        if (dir === top) break
+        dir = path.dirname(dir)
+      }
+    }
+    this.madeDirs.length = 0
     this.staged.length = 0
   }
 }
 
-/** Files renamed into place between two yields of a commit. */
-const COMMIT_BATCH = 256
+/**
+ * Renames in flight at once. A rename over a live file is not the few
+ * microseconds of one into an empty directory: on ext4 replacing a file
+ * starts writeback of the new one's data (`auto_da_alloc`), ~250 µs each,
+ * and synchronous ones stalled the main thread. 300 one-file restores
+ * took 25% longer than delete-then-restore (2026-10-16); on the thread
+ * pool they tie it, and 2,000 files in one restore are faster.
+ */
+const RENAME_BATCH = 64
+
+/**
+ * `p`, its failure marked handled at once: `settle` reads it later, and a
+ * rename that fails while the commit awaits something else is not an
+ * unhandled rejection that fails the process.
+ */
+function handled(p: Promise<void>): Promise<void> {
+  p.catch(() => undefined)
+  return p
+}
+
+/** Wait for every rename, then throw the first failure: none is left in flight for `abort`. */
+async function settle(renames: readonly Promise<void>[]): Promise<void> {
+  for (const r of await Promise.allSettled(renames)) if (r.status === 'rejected') throw r.reason
+}
 
 /** Per-process counter for extract temp names; uniqueness only. */
 let tmpSeq = 0
 
+/** `.vx/<STAGING>/`: where restores stage, each process in its own `<pid>-0` directory. */
+export const STAGING = 'tmp'
+
+const stagingMade = new Set<string>()
+
+/**
+ * This process's staging directory under `root`'s `.vx/tmp/`, made on its
+ * first restore and again only if something removed it: one per restore
+ * cost 300 restores 12% (2026-10-16). Every restore's renames empty it;
+ * the next run's `sweepStaging` removes it once this process is gone.
+ */
+async function stagingDir(root: string): Promise<string> {
+  const top = path.join(root, '.vx', STAGING)
+  const own = path.join(top, `${process.pid.toString(36)}-0`)
+  if (stagingMade.has(own) && existsSync(own)) return own
+  await mkdir(own, { recursive: true })
+  // Ignored by git whatever `.vx/.gitignore` an older init committed.
+  try {
+    writeFileSync(path.join(top, '.gitignore'), '*\n', { flag: 'wx' })
+  } catch {
+    // there already, or the restore fails on its first write anyway
+  }
+  stagingMade.add(own)
+  return own
+}
+
+/**
+ * A temp beside `target`, with its own short name, never `<target>.suffix`:
+ * a suffix pushed a legal name of 242–255 bytes past NAME_MAX, and the
+ * restore of a valid artifact failed with ENAMETOOLONG (item 666).
+ */
+function siblingTemp(target: string): string {
+  return path.join(
+    path.dirname(target),
+    `.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`,
+  )
+}
+
 const WORKSPACE_PREFIX = 'workspace-outputs/'
 
 /**