@vzn/vx 0.0.641 → 0.0.643

package/src/cache/archive.ts

@@ -34,10 +34,10 @@
 // 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,
@@ -51,11 +51,13 @@ import {
   lstatSync,
   openSync,
   readFileSync,
+  readlinkSync,
   realpathSync,
   statSync,
   utimesSync,
   writeFileSync,
 } from 'node:fs'
+import type { Stats } from 'node:fs'
 import {
   copyFile,
   lstat,
@@ -63,8 +65,10 @@ import {
   readlink,
   realpath,
   rename,
+  rm,
   rmdir,
   stat,
+  symlink,
   unlink,
   writeFile,
 } from 'node:fs/promises'
@@ -81,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'
@@ -195,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
@@ -241,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. */
@@ -276,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: {} }
@@ -285,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/')
@@ -325,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),
@@ -375,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,
@@ -489,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
@@ -498,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
@@ -505,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)
@@ -524,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,
@@ -589,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
@@ -624,10 +669,13 @@ export async function extractArtifactStream(
   // 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).
+  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)) {
@@ -635,7 +683,10 @@ 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)
@@ -658,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
@@ -720,7 +803,7 @@ function keep(s: Staged, ino: number, mode: number, mtimeMs: number | undefined)
     if (st.ino !== ino || st.nlink !== 1) {
       throw new Error(`${s.target} changed while it was restored`)
     }
-    if ((st.mode & 0o7777) !== (mode & 0o777)) fchmodSync(fd, mode & 0o777)
+    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)
@@ -745,6 +828,20 @@ interface Staged {
   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[]
 }
 
 /**
@@ -754,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>()
@@ -767,6 +866,11 @@ 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,
@@ -860,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
       }
@@ -907,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
@@ -919,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 {
@@ -980,6 +1180,10 @@ class Extractor {
       : siblingTemp(target)
     const streamed = !(body instanceof Uint8Array)
     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`
@@ -1006,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 = []
@@ -1028,6 +1275,17 @@ class Extractor {
     metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
   ): Promise<void> {
     await this.drain()
+    // 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)
+      }
+      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
@@ -1036,44 +1294,147 @@ class Extractor {
     let n = 0
     let renames: Promise<void>[] = []
     const checked = new Set<string>()
-    for (const s of this.staged) {
-      await this.assertStillContained(s, checked)
-      const [mode, mtimeMs] = metaFor(s.name)
-      if (s.same !== undefined) {
-        keep(s, s.same, mode, mtimeMs)
-        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 ((mode & 0o777) !== made.mode) chmodSync(s.tmp, mode & 0o777)
-      // 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 = mtimeMs === undefined ? undefined : new Date(mtimeMs)
-      if (t !== undefined) utimesSync(s.tmp, t, t)
-      if (s.staged) {
-        const dir = path.dirname(s.target)
-        let gid = setgid.get(dir)
-        if (gid === undefined) {
-          const st = statSync(dir)
-          gid = INHERITS_GROUP || (st.mode & 0o2000) !== 0 ? st.gid : null
-          setgid.set(dir, gid)
+    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 = 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 = []
         }
-        if (gid !== null && gid !== made.gid) chownSync(s.tmp, made.uid, gid)
-      }
-      renames.push(this.place(s, mode, t))
-      if (++n % RENAME_BATCH === 0) {
-        await settle(renames)
-        renames = []
       }
+    } 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
   }
 
+  /**
+   * 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
@@ -1086,9 +1447,12 @@ class Extractor {
       if (!s.staged || (err as NodeJS.ErrnoException).code !== 'EXDEV') throw err
       const side = siblingTemp(s.target)
       try {
-        await copyFile(s.tmp, side)
-        chmodSync(side, mode & 0o777)
-        if (t !== undefined) utimesSync(side, t, t)
+        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)
@@ -1104,14 +1468,44 @@ class Extractor {
    * Bun has no `renameat` against a held directory fd, so this is by path,
    * once per directory per commit.
    */
-  private async assertStillContained(s: Staged, checked: Set<string>): Promise<void> {
-    const dir = path.dirname(s.target)
+  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(s.base)
+    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(s.base), dir, realBase)
+      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)
     }
   }
 
@@ -1129,6 +1523,8 @@ class Extractor {
         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()) {
@@ -1150,6 +1546,21 @@ 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
   }
 }
@@ -1164,6 +1575,16 @@ class Extractor {
  */
 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