@vzn/vx 0.0.646 → 0.0.649

package/src/cache/archive.ts

@@ -55,7 +55,6 @@ import {
   realpathSync,
   statSync,
   utimesSync,
-  writeFileSync,
 } from 'node:fs'
 import type { Stats } from 'node:fs'
 import {
@@ -74,7 +73,7 @@ import {
   writeFile,
 } from 'node:fs/promises'
 import path from 'node:path'
-import { UserError } from '../util/index.js'
+import { ignoreDir, UserError, writableUnder } from '../util/index.js'
 import { WORKSPACE_OUTPUT_PREFIX } from './layer.js'
 import {
   TarFormatError,
@@ -140,6 +139,7 @@ class EntrySum {
  */
 class SumCheck {
   private readonly sum = new EntrySum()
+  private readonly names = new Set<string>()
   private seen: boolean = false
   /** The entry's body, hashed as the caller reads it; null for the sum entry itself (checked here). */
   async body(
@@ -157,6 +157,10 @@ class SumCheck {
   enter(name: string): boolean {
     if (this.seen) throw new TarFormatError(`entry ${name} follows the artifact's checksum`)
     if (name === SUM_ENTRY) return true
+    // vx never packs a name twice, and a restore staged both: their renames
+    // ran together, so which body landed was a race the index never saw.
+    if (this.names.has(name)) throw new ArchiveSecurityError(`archive holds ${name} twice`)
+    this.names.add(name)
     this.sum.entry(name)
     return false
   }
@@ -213,6 +217,14 @@ interface MetaFile {
    * Turbo and Nx do, where it once packed a copy of the target (v45).
    */
   links?: Record<string, string>
+  /**
+   * The directories under the outputs whose mode withholds a permission
+   * 0755 grants (`chmod 700 dist/keys`), entry name → permission bits
+   * (v49): a hit made each missing directory with mkdir's default, so a
+   * directory that kept its files to their owner came back readable by
+   * every user.
+   */
+  dirModes?: Record<string, number>
   /**
    * What the PRODUCING execution used (2026-09-12, additive: an artifact
    * without it reads as before). Rides the artifact so a machine that
@@ -265,6 +277,8 @@ interface PackArgs {
   exec?: ExecUsage | undefined
   /** The workspace root an output symlink's target must stay inside; absent, every link is refused. */
   root?: string
+  /** Where `outputs/` names lie, for the directory modes (`dirModes`); absent, none is recorded. */
+  projectDir?: string
 }
 
 /** The largest second count ustar's 12-byte mtime field holds: 11 octal digits. */
@@ -332,7 +346,7 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
             `${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`,
           )
         }
-        return { name, link: to }
+        return { name, link: to, abs, shown }
       }
       if (!st.isFile()) {
         throw new UserError(
@@ -353,6 +367,19 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       }
     }),
   )
+  const linked = new Map<string, string>()
+  const symlinks = files.filter(
+    (f): f is Extract<(typeof files)[number], { link: string }> => 'link' in f,
+  )
+  for (const f of symlinks) linked.set(f.abs, f.shown)
+  for (const f of symlinks) {
+    const via = throughLink(path.dirname(f.abs), f.link, linked)
+    if (via !== undefined) {
+      throw new UserError(
+        `${f.shown} is a symlink to ${f.link} through ${linked.get(via)}, another link: vx restores each link as written and checks where it points alone — point it at the target directly, or take it back with a '!' entry`,
+      )
+    }
+  }
   // In the outputs' order, not as each stat settled: one tree, one artifact.
   const regular: Array<Exclude<(typeof files)[number], { link: string }>> = []
   for (const f of files) {
@@ -362,6 +389,17 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       regular.push(f)
     }
   }
+  if (args.projectDir !== undefined) {
+    const modes = narrowDirModes(
+      [...args.outputs.keys(), ...(args.dirs ?? [])],
+      args.dirs ?? [],
+      (name) =>
+        name.startsWith('outputs/')
+          ? path.join(args.projectDir!, name.slice('outputs/'.length))
+          : path.join(args.root ?? args.projectDir!, name.slice(WORKSPACE_PREFIX.length)),
+    )
+    if (modes !== undefined) meta.dirModes = modes
+  }
   const stdout = new TextEncoder().encode(args.stdout)
   const metaBytes = new TextEncoder().encode(JSON.stringify(meta))
   const inputs: TarInput[] = [
@@ -378,6 +416,36 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   return { inputs, size: tarSize([...inputs, sumInput('0'.repeat(SUM_SIZE))]) }
 }
 
+/**
+ * The modes `MetaFile.dirModes` keeps: of each directory on the way to an
+ * output name below its namespace, and of each empty output directory, the
+ * ones that withhold a permission 0755 grants. A wider mode is left to the
+ * restoring umask, as a plain mkdir's is, so most artifacts carry none.
+ */
+function narrowDirModes(
+  names: readonly string[],
+  emptyDirs: readonly string[],
+  abs: (name: string) => string,
+): Record<string, number> | undefined {
+  const seen = new Set<string>()
+  let out: Record<string, number> | undefined
+  const visit = (dir: string): void => {
+    if (seen.has(dir)) return
+    seen.add(dir)
+    const st = statSync(abs(dir), { throwIfNoEntry: false })
+    if (st?.isDirectory() !== true || (st.mode & 0o755) === 0o755) return
+    ;(out ??= {})[dir] = st.mode & 0o777
+  }
+  for (const d of emptyDirs) visit(d)
+  for (const name of names) {
+    const top = name.startsWith('outputs/') ? 'outputs/'.length : WORKSPACE_PREFIX.length
+    for (let i = name.lastIndexOf('/'); i > top; i = name.lastIndexOf('/', i - 1)) {
+      visit(name.slice(0, i))
+    }
+  }
+  return out
+}
+
 /** The tar as a stream: each output is read from disk as it is written. */
 export function packArtifactStream(plan: ArtifactPlan): ReadableStream<Uint8Array> {
   return streamOf(tarPack(summed(plan.inputs)))
@@ -503,7 +571,10 @@ export async function writeTree(plan: ArtifactPlan, dir: string): Promise<Artifa
     plan.inputs.map(async (i) => {
       if (!(i.body instanceof Blob)) return
       const to = path.join(dir, i.name)
-      await Bun.write(to, i.body)
+      // The tar form's refusal (`tarPackInto`): an output that grew or shrank
+      // since the plan's stat is not the file its row describes.
+      const n = await Bun.write(to, i.body)
+      if (n !== i.size) throw new TarFormatError(`${i.name}: ${n} bytes, ${i.size} declared`)
       const at = new Date(times[i.name]![1])
       await utimes(to, at, at)
     }),
@@ -526,6 +597,7 @@ export async function sealTree(dir: string, scan: ArtifactScan): Promise<void> {
   }
   if (scan.dirs.length > 0) meta.dirs = scan.dirs
   if (scan.links.length > 0) meta.links = Object.fromEntries(scan.links)
+  if (scan.dirModes.length > 0) meta.dirModes = Object.fromEntries(scan.dirModes)
   if (scan.exec !== undefined) meta.exec = scan.exec
   await writeFile(path.join(dir, META_ENTRY), JSON.stringify(meta))
 }
@@ -537,10 +609,14 @@ export function planOfTree(dir: string, stdout: string): ArtifactPlan {
   const out = new TextEncoder().encode(stdout)
   const inputs: TarInput[] = [{ name: STDOUT_ENTRY, size: out.byteLength, body: out }]
   for (const [name, [mode, mtimeMs]] of Object.entries(meta.files)) {
+    // Bun.file reads through a link: only a regular file is packed as one.
+    const st = lstatSync(path.join(dir, name))
+    if (!st.isFile())
+      throw new ArchiveSecurityError(`kept tree entry ${name} is not a regular file`)
     const file = Bun.file(path.join(dir, name))
     inputs.push({
       name,
-      size: statSync(path.join(dir, name)).size,
+      size: st.size,
       mode,
       mtime: Math.min(USTAR_MTIME_MAX, Math.max(0, Math.floor(mtimeMs / 1000))),
       body: file,
@@ -557,6 +633,8 @@ interface ArtifactScan {
   dirs: string[]
   /** The sidecar's symlinks, `[name, target]`, each name and target proven safe. */
   links: Array<[name: string, target: string]>
+  /** The sidecar's directory modes, each a directory the artifact holds something in or is. */
+  dirModes: Array<[name: string, mode: number]>
   stdout: string | null
   exec: ExecUsage | undefined
   key: string | undefined
@@ -568,15 +646,17 @@ class ScanFold {
   private files: MetaFile['files'] = {}
   private dirs: string[] = []
   private links: Array<[string, string]> = []
+  private dirModes: Array<[string, number]> = []
   private exec: ExecUsage | undefined
   private key: string | undefined
   stdout: string | null = null
 
   sidecar(text: string): void {
     const parsed = JSON.parse(text) as MetaFile
-    this.files = parsed.files ?? {}
+    this.files = filesOf(parsed)
     this.dirs = dirsOf(parsed)
     this.links = linksOf(parsed)
+    this.dirModes = dirModesOf(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)
@@ -588,6 +668,26 @@ class ScanFold {
   }
 
   result(): ArtifactScan {
+    // A mode names a directory the artifact holds, never one a restore
+    // would otherwise not make: the row it becomes is a directory a hit
+    // makes and asks to stand.
+    if (this.dirModes.length > 0) {
+      const held = new Set(this.dirs)
+      const hold = (name: string): void => {
+        for (let i = name.indexOf('/'); i !== -1; i = name.indexOf('/', i + 1))
+          held.add(name.slice(0, i))
+      }
+      for (const s of this.seen) hold(s.name)
+      for (const d of this.dirs) hold(d)
+      for (const [name] of this.links) hold(name)
+      for (const [name] of this.dirModes) {
+        if (!held.has(name)) {
+          throw new ArchiveSecurityError(
+            `archive directory mode names no output directory: ${name}`,
+          )
+        }
+      }
+    }
     return {
       entries: this.seen.map((s) => {
         const m = this.files[s.name]
@@ -598,6 +698,7 @@ class ScanFold {
       }),
       dirs: this.dirs,
       links: this.links,
+      dirModes: this.dirModes,
       stdout: this.stdout,
       exec: this.exec,
       key: this.key,
@@ -663,6 +764,37 @@ export function scanTarBytes(tar: Uint8Array): ArtifactScan {
   return fold.result()
 }
 
+/** The largest millisecond count a Date holds (ECMA-262 §21.4.1.1). */
+const DATE_MAX_MS = 8.64e15
+
+/**
+ * The sidecar's stats, each an integer mode in 0..0o7777 and an integer
+ * mtime a Date holds: one taken as is reached the index, and its restore
+ * threw a TypeError out of `utimesSync` after renames had begun.
+ */
+function filesOf(meta: MetaFile): MetaFile['files'] {
+  const raw: unknown = meta.files
+  if (raw === undefined || raw === null) return {}
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new ArchiveSecurityError('archive sidecar files is not a map')
+  }
+  for (const [name, pair] of Object.entries(raw as Record<string, unknown>)) {
+    if (
+      !Array.isArray(pair) ||
+      !Number.isInteger(pair[0]) ||
+      pair[0] < 0 ||
+      pair[0] > 0o7777 ||
+      !Number.isInteger(pair[1]) ||
+      Math.abs(pair[1]) > DATE_MAX_MS
+    ) {
+      throw new ArchiveSecurityError(
+        `archive sidecar has a bad stat for ${name}: ${JSON.stringify(pair)}`,
+      )
+    }
+  }
+  return raw as MetaFile['files']
+}
+
 /**
  * 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
@@ -707,6 +839,73 @@ function linksOf(meta: MetaFile): Array<[string, string]> {
   })
 }
 
+/**
+ * The first of `links` (absolute paths) that `to` passes through, walked
+ * from `dir` a segment at a time. Each link's target is checked as text,
+ * but the kernel follows one link while it resolves the next: `up -> ..`
+ * and `esc -> up/../../x` each read as inside while `esc` lands outside.
+ */
+function throughLink(
+  dir: string,
+  to: string,
+  links: ReadonlyMap<string, string>,
+): string | undefined {
+  let at = dir
+  for (const seg of to.split('/')) {
+    if (seg === '' || seg === '.') continue
+    at = seg === '..' ? path.dirname(at) : path.join(at, seg)
+    if (links.has(at)) return at
+  }
+  return undefined
+}
+
+/**
+ * The sidecar's directory modes, each name held to a file entry's rules and
+ * each mode to permission bits.
+ */
+function dirModesOf(meta: MetaFile): Array<[string, number]> {
+  const raw: unknown = meta.dirModes
+  if (raw === undefined) return []
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new ArchiveSecurityError('archive sidecar dirModes is not a map')
+  }
+  return Object.entries(raw as Record<string, unknown>).map(([name, mode]) => {
+    if (!(name.startsWith('outputs/') || name.startsWith(WORKSPACE_PREFIX))) {
+      throw new ArchiveSecurityError(`archive directory is not an output: ${name}`)
+    }
+    assertSafeName(name)
+    if (typeof mode !== 'number' || !Number.isInteger(mode) || mode < 0 || mode > 0o777) {
+      throw new ArchiveSecurityError(
+        `archive directory ${name} has an unsafe mode: ${String(mode)}`,
+      )
+    }
+    return [name, mode]
+  })
+}
+
+/**
+ * A file this user cannot read, or one gone since its stat, is not the
+ * same bytes: the rename replaces it. Any other failure is the restore's:
+ * an EMFILE read as "differs" sent the restore on to stage, and its error
+ * named the staging file.
+ */
+function sameBytes(file: string, body: Uint8Array): boolean {
+  try {
+    return readFileSync(file).equals(body)
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'EACCES' || code === 'EPERM' || code === 'ENOENT') return false
+    throw err
+  }
+}
+
+/** The deepest directory holding both `a` and `b`. */
+function commonDir(a: string, b: string): string {
+  let dir = a
+  while (!inside(b, dir) && path.dirname(dir) !== dir) dir = path.dirname(dir)
+  return dir
+}
+
 /** `p` is `root` or under it, lexically. */
 const inside = (p: string, root: string): boolean => {
   const r = path.resolve(root)
@@ -757,6 +956,7 @@ export async function extractArtifactStream(
   let meta: MetaFile['files'] = {}
   let dirs: string[] = []
   let links: Array<[string, string]> = []
+  let dirModes: Array<[string, number]> = []
   const fold = onScan === undefined ? undefined : new ScanFold()
   try {
     const check = new SumCheck()
@@ -768,9 +968,10 @@ export async function extractArtifactStream(
         const text = await textOf(body)
         fold?.sidecar(text)
         const parsed = JSON.parse(text) as MetaFile
-        meta = parsed.files ?? {}
+        meta = filesOf(parsed)
         dirs = dirsOf(parsed)
         links = linksOf(parsed)
+        dirModes = dirModesOf(parsed)
         continue
       }
       assertSafeName(e.name)
@@ -811,8 +1012,23 @@ export async function extractArtifactStream(
       provided.add(`${name}/`)
     }
     // A link may point only inside the workspace (the project, without one).
-    const bound = stageRoot ?? workspaceDest ?? destDir
+    // Unpacked into a cache tree (no stage root), `outputs/` and
+    // `workspace-outputs/` are siblings: bounded by the latter alone, a
+    // `dist/link -> big.bin` pointed "out" and the ingest failed. The tree
+    // bounds by their parent; its restore checks against the workspace.
+    const bound =
+      stageRoot ?? (workspaceDest === undefined ? destDir : commonDir(destDir, workspaceDest))
+    const linked = new Map<string, string>()
+    for (const [name] of links) {
+      const dest = x.destFor(name)
+      if (dest !== null && dest.rel.length > 0) linked.set(path.join(dest.base, dest.rel), name)
+    }
     for (const [name, to] of links) {
+      // Renamed over an entry just written, the link would stand where the
+      // sidecar says a file is, and a re-pack of the tree reads through it.
+      if (provided.has(name) || [...provided].some((p) => p.startsWith(`${name}/`))) {
+        throw new ArchiveSecurityError(`archive link ${name} is also a file or directory entry`)
+      }
       if (accept !== undefined && !accept(name)) {
         throw new ArchiveSecurityError(
           `archive link is not one of the task's declared outputs: ${name}`,
@@ -822,12 +1038,30 @@ export async function extractArtifactStream(
       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)) {
+      const at = path.resolve(path.dirname(target), to)
+      if (!inside(at, bound)) {
         throw new ArchiveSecurityError(`archive link ${name} points out of the workspace: ${to}`)
       }
+      const via = throughLink(path.dirname(target), to, linked)
+      if (via !== undefined) {
+        throw new ArchiveSecurityError(
+          `archive link ${name} points through ${linked.get(via)}, another link it restores: ${to}`,
+        )
+      }
+      // Lexical: a write through a link is judged where it resolves, so an
+      // alias chain into .git gets no further than this link would.
+      if (!writableUnder(at, path.resolve(bound))) {
+        throw new ArchiveSecurityError(`archive link ${name} points into .git: ${to}`)
+      }
       await x.stageLink(name, dest.base, target, to)
       provided.add(name)
     }
+    // A moded directory is one the entries above make; its row, like an
+    // empty directory's, names it with a trailing slash. The cache applies
+    // the mode (`Cache.restoreOutputs`), to the directories a hit makes.
+    for (const [name] of dirModes) {
+      if (x.destFor(name) !== null) 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
@@ -887,7 +1121,8 @@ function keep(s: Staged, ino: number, mode: number, mtimeMs: number | undefined)
   const fd = openSync(s.target, constants.O_RDONLY | constants.O_NOFOLLOW)
   try {
     const st = fstatSync(fd)
-    if (st.ino !== ino || st.nlink !== 1) {
+    // An in-place write since the compare keeps the inode and bumps the ctime.
+    if (st.ino !== ino || st.nlink !== 1 || st.ctimeMs !== s.sameCtimeMs) {
       throw new Error(`${s.target} changed while it was restored`)
     }
     if ((st.mode & 0o7777) !== restoredMode(mode)) fchmodSync(fd, restoredMode(mode))
@@ -915,6 +1150,8 @@ 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
+  /** The kept target's ctime when its bytes were compared. */
+  sameCtimeMs?: 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. */
@@ -938,6 +1175,8 @@ interface Tree {
  */
 class Extractor {
   private readonly staged: Staged[] = []
+  /** Directories given owner write for a rename into them, with the mode to put back. */
+  private readonly reopened = new Map<string, number>()
   /** Empty output directories made, with the top of each chain created. */
   private readonly madeDirs: Array<{ dir: string; created: string }> = []
   private inflight: Promise<unknown>[] = []
@@ -1061,7 +1300,7 @@ class Extractor {
       )
       if (real !== null) {
         const realBase = await this.realBaseOf(base)
-        if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+        if (!writableUnder(real, realBase)) {
           throw await linkOutError(baseResolved, probe, realBase)
         }
         return
@@ -1090,7 +1329,7 @@ class Extractor {
     if (err.code !== 'EEXIST' && err.code !== 'ENOENT' && err.code !== 'ELOOP') throw err
     const real = await resolveThrough(dir)
     const realBase = await this.realBaseOf(base)
-    if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+    if (!writableUnder(real, realBase)) {
       throw await linkOutError(path.resolve(base), dir, realBase)
     }
     // What stands there without a link on the way (a file named like the
@@ -1219,14 +1458,21 @@ class Extractor {
     // 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).
+    const st = created === undefined ? lstatSync(target, { throwIfNoEntry: false }) : undefined
+    // A directory there fails its rename at commit, after the renames
+    // before it landed: refused now, no output is replaced.
+    if (st?.isDirectory() === true)
+      throw Object.assign(
+        new Error(`EISDIR: illegal operation on a directory, rename '${target}'`),
+        { code: 'EISDIR', path: target },
+      )
     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)
+        sameBytes(target, body)
       ) {
         this.staged.push({
           staged: false,
@@ -1237,6 +1483,7 @@ class Extractor {
           streamed: false,
           base,
           same: st.ino,
+          sameCtimeMs: st.ctimeMs,
         })
         return
       }
@@ -1260,7 +1507,7 @@ class Extractor {
     // fail-closed outcome the plain write had.
     // 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).
+    // outputs, and a killed restore left them there (2026-10-16).
     const staged = this.stageRoot !== undefined
     const tmp = staged
       ? path.join(await stagingDir(this.stageRoot!), (tmpSeq++).toString(36))
@@ -1360,6 +1607,16 @@ class Extractor {
    */
   async commit(
     metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
+  ): Promise<void> {
+    try {
+      await this.commitAll(metaFor)
+    } finally {
+      this.closeReopened()
+    }
+  }
+
+  private async commitAll(
+    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.
@@ -1472,11 +1729,49 @@ class Extractor {
       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 this.renameInto(s.tmp, s.target)
     }
     await rm(t.at, { recursive: true, force: true })
   }
 
+  /**
+   * `rename`, into a directory of this user's that withholds its own write
+   * (a task's `chmod 555 dist/ro`, which a hit now restores): the
+   * directory gets owner write and search for the rest of the commit, and
+   * its mode back after. Without it every later hit that changed a file
+   * there failed EACCES, as only root could replace it.
+   */
+  private async renameInto(from: string, to: string): Promise<void> {
+    try {
+      await rename(from, to)
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EACCES' || !this.reopen(path.dirname(to)))
+        throw err
+      await rename(from, to)
+    }
+  }
+
+  private reopen(dir: string): boolean {
+    if (this.reopened.has(dir)) return false
+    const st = lstatSync(dir, { throwIfNoEntry: false })
+    if (st?.isDirectory() !== true || st.uid !== process.getuid?.()) return false
+    if ((st.mode & 0o300) === 0o300) return false
+    this.reopened.set(dir, st.mode & 0o7777)
+    chmodSync(dir, (st.mode & 0o7777) | 0o300)
+    return true
+  }
+
+  private closeReopened(): void {
+    for (const [dir, mode] of this.reopened) {
+      try {
+        chmodSync(dir, mode)
+      } catch {
+        // gone with an abort's cleanup
+      }
+    }
+    this.reopened.clear()
+  }
+
   private async makeDirIn(base: string, dir: string): Promise<void> {
     try {
       await mkdir(dir, { recursive: true })
@@ -1529,7 +1824,7 @@ class Extractor {
    */
   private async place(s: Staged, mode: number, t: Date | undefined): Promise<void> {
     try {
-      await rename(s.tmp, s.target)
+      await this.renameInto(s.tmp, s.target)
     } catch (err) {
       if (!s.staged || (err as NodeJS.ErrnoException).code !== 'EXDEV') throw err
       const side = siblingTemp(s.target)
@@ -1540,7 +1835,7 @@ class Extractor {
           chmodSync(side, restoredMode(mode))
           if (t !== undefined) utimesSync(side, t, t)
         }
-        await rename(side, s.target)
+        await this.renameInto(side, s.target)
       } catch (e) {
         await unlink(side).catch(() => undefined)
         throw e
@@ -1564,7 +1859,7 @@ class Extractor {
     checked.add(dir)
     const realBase = await this.realBaseOf(base)
     const real = await realOf(dir, true)
-    if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+    if (!writableUnder(real, realBase)) {
       throw await linkOutError(path.resolve(base), dir, realBase)
     }
   }
@@ -1590,7 +1885,7 @@ class Extractor {
     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
+      if (real === null || writableUnder(real, realBase)) continue
       await Promise.allSettled(placed.map((p) => rm(p, { recursive: true, force: true })))
       throw await linkOutError(path.resolve(base), dir, realBase)
     }
@@ -1681,7 +1976,7 @@ async function settle(renames: readonly Promise<void>[]): Promise<void> {
 let tmpSeq = 0
 
 /** `.vx/<STAGING>/`: where restores stage, each process in its own `<pid>-0` directory. */
-export const STAGING = 'tmp'
+const STAGING = 'tmp'
 
 const stagingMade = new Set<string>()
 
@@ -1698,7 +1993,7 @@ async function stagingDir(root: string): Promise<string> {
   await mkdir(own, { recursive: true })
   // Ignored by git whatever `.vx/.gitignore` an older init committed.
   try {
-    writeFileSync(path.join(top, '.gitignore'), '*\n', { flag: 'wx' })
+    ignoreDir(top)
   } catch {
     // there already, or the restore fails on its first write anyway
   }
@@ -1735,7 +2030,13 @@ async function linkOutError(base: string, probe: string, realBase: string): Prom
   for (const part of path.relative(base, probe).split(path.sep)) {
     dir = path.join(dir, part)
     real = await resolveThrough(dir)
-    if (real !== realBase && !real.startsWith(realBase + path.sep)) break
+    if (!writableUnder(real, realBase)) break
+  }
+  if (real.startsWith(realBase + path.sep)) {
+    return new UserError(
+      `${dir} is a symbolic link to ${real}, Git's metadata — a cache restore never writes ` +
+        'into a .git directory. Remove the link and re-run, or stop declaring outputs under it.',
+    )
   }
   return new UserError(
     `${dir} is a symbolic link to ${real}, outside ${base} — a cache restore never writes ` +