@vzn/vx 0.0.651 → 0.0.653

package/README.md

@@ -47,9 +47,8 @@ export default defineProject({
       exec: { command: 'tsc -b' },
       dependsOn: ['^build'], // dependencies build first
       inputs: { files: ['src/**', 'tsconfig.json'] },
-      cache: {
-        outputs: { files: ['dist/**'] },
-      },
+      outputs: { files: ['dist/**', '*.tsbuildinfo'] }, // tsc's incremental state too
+      cache: true,
     },
   },
 })
@@ -127,7 +126,7 @@ Beside `turbo.json` or `nx.json`, `bunx @vzn/vx init` runs `@vzn/vx-migrate`:
 it writes a `vx.config.ts` per package from `turbo.json` or the Nx graph,
 and you keep those and delete the old config. `vx init --keep` writes only
 a `.vx/workspace.ts` that maps the old config instead, and its lock: a temporary start,
-not a way to run the repo. The benchmark below uses native vx config.
+not a way to run the workspace. The benchmark below uses native vx config.
 [Migration guide](https://vznjs.github.io/vx/guides/migrate/).
 
 ## How it compares

package/launcher.sh

@@ -48,7 +48,8 @@ if [ -z "${VX_HANDED_OFF-}" ] && [ -z "$stay" ]; then
   while :; do
     root=
     for ext in ts mts js mjs cts cjs; do
-      if [ -f "$d/.vx/workspace.$ext" ]; then
+      # Any entry, a broken link or a directory too: vx refuses it there.
+      if [ -e "$d/.vx/workspace.$ext" ] || [ -L "$d/.vx/workspace.$ext" ]; then
         root=${d:-/}
         break
       fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.651",
+  "version": "0.0.653",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.651",
-    "@vzn/vx-linux-arm64": "0.0.651",
-    "@vzn/vx-darwin-x64": "0.0.651",
-    "@vzn/vx-darwin-arm64": "0.0.651"
+    "@vzn/vx-linux-x64": "0.0.653",
+    "@vzn/vx-linux-arm64": "0.0.653",
+    "@vzn/vx-darwin-x64": "0.0.653",
+    "@vzn/vx-darwin-arm64": "0.0.653"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/error.json

@@ -14,7 +14,7 @@
       "properties": {
         "code": {
           "type": "string",
-          "description": "Stable; branch on it. VX_E_USAGE, VX_E_UNKNOWN_COMMAND, VX_E_UNKNOWN_TASK, VX_E_UNKNOWN_PROJECT, VX_E_NO_HISTORY, VX_E_AMBIGUOUS, VX_E_CONFIG, VX_E_CYCLE, VX_E_LOCK, VX_E_NO_WORKSPACE, VX_E_CACHE_VERSION, VX_E_REFUSED, VX_E_FS, VX_E_FDS, VX_E_AFFECTED_BASE, VX_E_NO_GIT, VX_E_GIT, VX_E_NETWORK, VX_E_DEPENDS_ON, VX_E_OUTPUT_OVERLAP, VX_E_INPUT_IS_OUTPUT, VX_E_DEPENDENCY_RULE, VX_E_NESTED_INPUT, VX_E_INTERNAL. A plugin may name its own."
+          "description": "Stable; branch on it. VX_E_USAGE, VX_E_UNKNOWN_COMMAND, VX_E_UNKNOWN_TASK, VX_E_UNKNOWN_PROJECT, VX_E_NO_HISTORY, VX_E_AMBIGUOUS, VX_E_CONFIG, VX_E_CYCLE, VX_E_LOCK, VX_E_NO_WORKSPACE, VX_E_CACHE_VERSION, VX_E_REFUSED, VX_E_FS, VX_E_FDS, VX_E_AFFECTED_BASE, VX_E_NO_GIT, VX_E_GIT, VX_E_NETWORK, VX_E_DEPENDS_ON, VX_E_OUTPUT_OVERLAP, VX_E_INPUT_IS_OUTPUT, VX_E_DEPENDENCY_RULE, VX_E_NESTED_INPUT, VX_E_NESTED_OUTPUT, VX_E_INTERNAL. A plugin may name its own."
         },
         "message": { "type": "string", "description": "The refusal in prose; may change." },
         "docs": {

package/schemas/show.json

@@ -93,6 +93,7 @@
               "type": "array",
               "items": { "enum": ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64"] }
             },
+            "worker": { "type": "string" },
             "sandbox": {
               "type": "object",
               "description": "as declared; its fields are the `exec.sandbox` section of the config schema"
@@ -109,25 +110,8 @@
             "env": { "$ref": "#/$defs/stringList" },
             "tasks": { "$ref": "#/$defs/stringList" },
             "runtime": { "$ref": "#/$defs/stringList" },
-            "workspaceRuntime": { "$ref": "#/$defs/stringList" }
-          }
-        },
-        "cache": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["outputs"],
-          "properties": {
-            "outputs": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["files"],
-              "properties": {
-                "files": { "$ref": "#/$defs/stringList" },
-                "workspaceFiles": { "$ref": "#/$defs/stringList" },
-                "clean": { "type": "boolean" }
-              }
-            },
-            "inputStability": {
+            "workspaceRuntime": { "$ref": "#/$defs/stringList" },
+            "stability": {
               "type": "object",
               "additionalProperties": false,
               "properties": {
@@ -136,7 +120,18 @@
               }
             }
           }
-        }
+        },
+        "outputs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["files"],
+          "properties": {
+            "files": { "$ref": "#/$defs/stringList" },
+            "workspaceFiles": { "$ref": "#/$defs/stringList" },
+            "clean": { "type": "boolean" }
+          }
+        },
+        "cache": { "type": "boolean" }
       }
     }
   }

package/skills/vx/SKILL.md

@@ -116,9 +116,9 @@ vx lock --check --format json  # a vx.config that changed since the lock, or no
   print whole.
 - Docs as markdown: https://vznjs.github.io/vx/llms.txt (its index).
   When that host is unreachable, the same pages are
-  `https://raw.githubusercontent.com/vznjs/vx/main/private/vx-docs/src/content/docs/<page>.md`:
-  `quickstart`, `guides/migrate`, `guides/configure`, `guides/agents`,
-  `guides/troubleshooting`, `guides/ci`, `guides/plugins`.
+  `https://raw.githubusercontent.com/vznjs/vx/main/private/vx-docs/src/content/docs/<page>.mdx`:
+  `quickstart`, `guides/migrate`, `docs/workspace`, `docs/agents`,
+  `guides/troubleshooting`, `docs/ci`, `docs/plugins`.
 
 ## Install
 

package/src/bin.ts

@@ -7,6 +7,21 @@ let settled = false
 
 async function main(): Promise<void> {
   const argv = process.argv.slice(2)
+  // A rejection nothing awaited (a plugin verb's floating promise) is a
+  // failure: the exit after the streams end came before Bun reported it,
+  // and the run said nothing and exited 0.
+  process.on('unhandledRejection', (reason) => {
+    process.exitCode = 1
+    void Promise.all([import('./ui/index.js'), import('./util/index.js')]).then(
+      ([ui, { maskedLine }]) =>
+        ui.say(
+          'error',
+          maskedLine(
+            `vx: unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}\n`,
+          ),
+        ),
+    )
+  })
   try {
     // Inside the try: `process.cwd()` throws EMFILE when out of descriptors,
     // and that is a one-line UserError below, not a stack.
@@ -38,7 +53,10 @@ async function main(): Promise<void> {
     // package, a workspace or project config — resolves to THIS core, not to
     // a second copy from node_modules (core-alias.ts says why and what it
     // costs). Registered before any verb runs; the façade loads on first use.
-    registerCoreAlias(() => require('./index.js') as Record<string, unknown>)
+    registerCoreAlias(
+      () => require('./index.js') as Record<string, unknown>,
+      () => require('./config.js') as Record<string, unknown>,
+    )
     const code = await run(argv)
     // Not `process.exit` here: Bun drops what a pipe has not yet taken
     // when it follows a large write (300 KB written, 64 KiB delivered;
@@ -71,14 +89,19 @@ async function main(): Promise<void> {
       // A message that names its verb (`vx why: …`, a plugin's `vx dte
       // worker: …`) is that verb's; any other is the verb typed. A config
       // refusal shows its line.
-      const named = /^(vx [a-z][\w-]*(?: [a-z][\w-]*)?): /.exec(err.message)
-      const typed = /^[a-z][\w-]*$/.test(argv[0] ?? '') ? `vx ${argv[0]}` : 'vx'
+      // A plugin verb may hold a capital, `.` or `:` (`my.verb`).
+      const named = /^(vx [A-Za-z0-9][\w:.-]*(?: [a-z][\w-]*)?): /.exec(err.message)
+      const typed = /^[A-Za-z0-9][\w:.-]*$/.test(argv[0] ?? '') ? `vx ${argv[0]}` : 'vx'
       const block = refusalNotice(
         named?.[1] ?? typed,
         named === null ? err.message : err.message.slice(named[0].length),
         err.parts,
       )
       ui.data('err', maskedLine(ui.render([block], ui.colorsOf('err'))))
+    } else if (cwdGone(err)) {
+      // Removed under the shell (a checkout of another branch, `rm -rf` in
+      // another): every verb starts from the cwd.
+      say('vx: the current directory no longer exists — cd into the workspace again and re-run\n')
     } else if (isOutOfFds(err)) {
       say(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {
@@ -116,6 +139,9 @@ async function main(): Promise<void> {
  */
 async function exitOnceFlushed(): Promise<void> {
   if ((await import('./util/index.js')).exitClaimedBySignal()) return
+  // One macrotask: a floating rejection is reported after the microtasks
+  // drain, and its handler above sets the code and writes its line.
+  await new Promise((resolve) => setImmediate(resolve))
   let open = 2
   const ended = (): void => {
     if (--open === 0) process.exit()
@@ -159,6 +185,14 @@ process.on('beforeExit', () => {
   process.exitCode = 1
 })
 
+/** `process.cwd()`'s refusal of a directory removed under the process. */
+function cwdGone(err: unknown): boolean {
+  return (
+    (err as NodeJS.ErrnoException | null)?.code === 'ENOENT' &&
+    /\buv_cwd\b/.test((err as Error).message)
+  )
+}
+
 // A reader that leaves is not the run's failure. `vx run build | head -1`
 // closes the pipe after one line; every later write gets EPIPE, which Bun
 // raises as an `error` event on the stream, and an `error` nobody listens

package/src/cache/archive.ts

@@ -11,8 +11,10 @@
 // lost executable bit builds cold and breaks warm, and `isOutputsCurrent`
 // skips a restore when size+mode+mtime match at millisecond precision —
 // so the pack side stats each output once and writes both into
-// `.vx-meta.json`, and the restore side applies them. That also makes a
-// REMOTE-ingested entry's index rows millisecond-accurate.
+// `.vx-meta.json`. A restore applies the mode; it dates a file it writes
+// now, as the task's write would be, and leaves the mtime of one whose
+// bytes already stood. The sidecar mtime is the index rows' (a
+// REMOTE-ingested entry's too) and the cache's own tree form's.
 //
 // Both directions stream. `packArtifactStream` reads each output as it is
 // written; `scanArtifact` lists what an artifact holds without
@@ -341,16 +343,23 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
             `${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`,
           )
         }
-        if (args.root === undefined || !inside(path.resolve(path.dirname(abs), to), args.root)) {
+        const refused =
+          args.root === undefined ? 'out' : linkRefused(path.dirname(abs), to, args.root)
+        if (refused === 'out') {
           throw new UserError(
             `${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`,
           )
         }
+        if (refused === '.git') {
+          throw new UserError(
+            `${shown} is a symlink to ${to}, inside .git: vx never restores into Git's metadata — emit a file there, or take it back with a '!' entry`,
+          )
+        }
         return { name, link: to, abs, shown }
       }
       if (!st.isFile()) {
         throw new UserError(
-          `${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`,
+          `${shown} is not a regular file: vx stores regular files and symlinks only — emit a file there, or narrow outputs.files to the files the task produces, or take it back with a '!' entry`,
         )
       }
       const mode = st.mode & 0o777
@@ -380,6 +389,23 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       )
     }
   }
+  if (symlinks.length > 0 && args.root !== undefined) {
+    const realRoot = await realOf(args.root)
+    const realDirs = new Map<string, Promise<string>>()
+    for (const f of symlinks) {
+      const refused = await linkLandsRefused(path.dirname(f.abs), f.link, realRoot, realDirs)
+      if (refused === 'out') {
+        throw new UserError(
+          `${f.shown} is a symlink to ${f.link}, 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`,
+        )
+      }
+      if (refused === '.git') {
+        throw new UserError(
+          `${f.shown} is a symlink to ${f.link}, inside .git: vx never restores into Git's metadata — emit a file there, 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) {
@@ -567,7 +593,9 @@ export async function writeTree(plan: ArtifactPlan, dir: string): Promise<Artifa
   }
   // A stdout-only entry writes no file to make the directory.
   await mkdir(dir, { recursive: true })
-  await Promise.all(
+  // Every write settles before a failure is thrown: the caller removes
+  // `dir`, and a write still in flight would make its parents again.
+  const settled = await Promise.allSettled(
     plan.inputs.map(async (i) => {
       if (!(i.body instanceof Blob)) return
       const to = path.join(dir, i.name)
@@ -579,6 +607,8 @@ export async function writeTree(plan: ArtifactPlan, dir: string): Promise<Artifa
       await utimes(to, at, at)
     }),
   )
+  const failed = settled.find((s) => s.status === 'rejected')
+  if (failed !== undefined) throw failed.reason
   await writeFile(path.join(dir, META_ENTRY), meta)
   return fold.result()
 }
@@ -912,6 +942,81 @@ const inside = (p: string, root: string): boolean => {
   return p === r || p.startsWith(r + path.sep)
 }
 
+/**
+ * Where a link in `dir` reading `to` lands against `bound`, if a restore may
+ * not write it: out of it, or into its `.git` (lexical: a write through a
+ * link is judged where it resolves, so an alias chain into .git gets no
+ * further than this link would). Out is any step above `bound`, even one
+ * that comes back: `../../../ws/app/x` resolves inside only a root named
+ * `ws`, so judged by where it ends it saved here and was refused on every
+ * checkout under another name. The save asks it too, or it stored a link
+ * every restore refused, an entry that never hit on any machine.
+ */
+function linkRefused(dir: string, to: string, bound: string): 'out' | '.git' | undefined {
+  const root = path.resolve(bound)
+  const from = path.resolve(dir)
+  if (!inside(from, root)) return 'out'
+  let depth = from === root ? 0 : path.relative(root, from).split(path.sep).length
+  for (const seg of to.split(path.sep === '/' ? '/' : /[\\/]/)) {
+    if (seg === '..') depth--
+    else if (seg !== '' && seg !== '.') depth++
+    if (depth < 0) return 'out'
+  }
+  return writableUnder(path.resolve(from, to), root) ? undefined : '.git'
+}
+
+/**
+ * `linkRefused` on disk: the kernel resolves a `..` from where the links
+ * before it lead, so with a committed `app/up -> ..` the text
+ * `../up/../x` read as inside and landed beside the workspace. Walked from
+ * `dir`'s real path, each link on disk before the last `..` followed,
+ * every step held to `realBound`. A target with no `..` touches no disk;
+ * the links the artifact itself restores are `throughLink`'s.
+ */
+async function linkLandsRefused(
+  dir: string,
+  to: string,
+  realBound: string,
+  realDirs: Map<string, Promise<string>>,
+): Promise<'out' | '.git' | undefined> {
+  const segs = to.split(path.sep === '/' ? '/' : /[\\/]/)
+  const lastUp = segs.lastIndexOf('..')
+  if (lastUp < 0) return undefined
+  let realDir = realDirs.get(dir)
+  if (realDir === undefined) {
+    // At a restore the link's directory may not exist yet.
+    realDir = realOf(dir).catch(() => resolveThrough(dir))
+    realDirs.set(dir, realDir)
+  }
+  let at = await realDir
+  let onDisk = true
+  for (let i = 0; i <= lastUp; i++) {
+    const seg = segs[i]!
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') at = path.dirname(at)
+    else {
+      at = path.join(at, seg)
+      if (onDisk) {
+        const st = statOrAbsent(at)
+        if (st === undefined) onDisk = false
+        else if (st.isSymbolicLink()) at = await resolveThrough(at)
+      }
+    }
+    if (!inside(at, realBound)) return 'out'
+  }
+  return writableUnder(path.join(at, ...segs.slice(lastUp + 1)), realBound) ? undefined : '.git'
+}
+
+/** `lstat`, or undefined for a name that is not there (under a file too). */
+function statOrAbsent(p: string): Stats | undefined {
+  try {
+    return lstatSync(p, { throwIfNoEntry: false })
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOTDIR') return undefined
+    throw err
+  }
+}
+
 /** 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
@@ -944,6 +1049,13 @@ export async function extractArtifactStream(
   stageRoot?: string,
   /** Handed what `scanArtifact` would read of the same bytes, once their sum has checked. */
   onScan?: (scan: ArtifactScan) => void,
+  /**
+   * Given, a restore into a workspace: each file written is dated now, and
+   * one whose bytes already stood keeps its own mtime; either is set here
+   * by entry name. Absent, an unpack into the cache's tree form: the saved
+   * mtimes apply.
+   */
+  dated?: Map<string, number>,
 ): Promise<Set<string>> {
   // No `mkdir -p` of the destination here: `stage` creates each entry's
   // directory chain, the destination included, and the cache restores
@@ -1023,6 +1135,8 @@ export async function extractArtifactStream(
       const dest = x.destFor(name)
       if (dest !== null && dest.rel.length > 0) linked.set(path.join(dest.base, dest.rel), name)
     }
+    let realBound: Promise<string> | undefined
+    const realDirs = new Map<string, Promise<string>>()
     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.
@@ -1038,8 +1152,8 @@ 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)
-      const at = path.resolve(path.dirname(target), to)
-      if (!inside(at, bound)) {
+      let refused = linkRefused(path.dirname(target), to, bound)
+      if (refused === 'out') {
         throw new ArchiveSecurityError(`archive link ${name} points out of the workspace: ${to}`)
       }
       const via = throughLink(path.dirname(target), to, linked)
@@ -1048,9 +1162,14 @@ export async function extractArtifactStream(
           `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))) {
+      if (refused === undefined) {
+        realBound ??= realOf(bound)
+        refused = await linkLandsRefused(path.dirname(target), to, await realBound, realDirs)
+      }
+      if (refused === 'out') {
+        throw new ArchiveSecurityError(`archive link ${name} points out of the workspace: ${to}`)
+      }
+      if (refused === '.git') {
         throw new ArchiveSecurityError(`archive link ${name} points into .git: ${to}`)
       }
       await x.stageLink(name, dest.base, target, to)
@@ -1071,7 +1190,7 @@ export async function extractArtifactStream(
       if (m !== undefined) return [m[0], m[1]]
       const header = headerMtime.get(name)
       return [0o644, header !== undefined && header > 0 ? header : undefined]
-    })
+    }, dated)
   } catch (err) {
     await x.abort()
     throw err
@@ -1113,11 +1232,12 @@ 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.
+ * Bring a target that already held the entry's bytes to its mode and, when
+ * given, `mtimeMs`, through a descriptor opened without following a link:
+ * one planted since the compare is refused, never written through.
+ * Answers the mtime it leaves, in whole milliseconds.
  */
-function keep(s: Staged, ino: number, mode: number, mtimeMs: number | undefined): void {
+function keep(s: Staged, ino: number, mode: number, mtimeMs: number | undefined): number {
   const fd = openSync(s.target, constants.O_RDONLY | constants.O_NOFOLLOW)
   try {
     const st = fstatSync(fd)
@@ -1129,7 +1249,9 @@ function keep(s: Staged, ino: number, mode: number, mtimeMs: number | undefined)
     if (mtimeMs !== undefined && Math.floor(st.mtimeMs) !== mtimeMs) {
       const t = new Date(mtimeMs)
       futimesSync(fd, t, t)
+      return mtimeMs
     }
+    return Math.floor(st.mtimeMs)
   } finally {
     closeSync(fd)
   }
@@ -1367,17 +1489,7 @@ class Extractor {
     }
     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
-    }
+    if (!stagesInto(statSync(staging), statSync(probe, { throwIfNoEntry: false }))) return undefined
     const at = path.join(staging, (tmpSeq++).toString(36))
     this.trees.set(top, { at, base, dirs: [] })
     return at + abs.slice(top.length)
@@ -1457,7 +1569,10 @@ class Extractor {
     // 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).
+    // reproducible build gives every output one mtime (item 886). Never an
+    // empty file: one left in place reads as an untouched write-grant
+    // placeholder, and the sweep after a remote executor's task removed
+    // the empty output its restore had just landed.
     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.
@@ -1466,7 +1581,7 @@ class Extractor {
         new Error(`EISDIR: illegal operation on a directory, rename '${target}'`),
         { code: 'EISDIR', path: target },
       )
-    if (body instanceof Uint8Array && created === undefined) {
+    if (body instanceof Uint8Array && body.byteLength > 0 && created === undefined) {
       if (
         st !== undefined &&
         st.isFile() &&
@@ -1607,9 +1722,10 @@ class Extractor {
    */
   async commit(
     metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
+    dated?: Map<string, number>,
   ): Promise<void> {
     try {
-      await this.commitAll(metaFor)
+      await this.commitAll(metaFor, dated)
     } finally {
       this.closeReopened()
     }
@@ -1617,8 +1733,15 @@ class Extractor {
 
   private async commitAll(
     metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
+    dated: Map<string, number> | undefined,
   ): Promise<void> {
     await this.drain()
+    // A restore dates each file it writes now, as the task's own write
+    // would, and moves no file's mtime back: the saved mtime predates
+    // outputs written since, and a make-style dependant took a changed
+    // upstream as older than its own output and kept bytes built from
+    // another one. Read once: one clock for the whole restore.
+    const now = dated === undefined ? undefined : Date.now()
     // One stat per directory, shared by the filesystem check and the group.
     const dirStats = new Map<string, Stats>()
     const statDir = (dir: string): Stats => {
@@ -1642,11 +1765,14 @@ class Extractor {
       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)
+        const [mode, savedMtimeMs] = metaFor(s.name)
         if (s.same !== undefined) {
-          keep(s, s.same, mode, mtimeMs)
+          const own = keep(s, s.same, mode, now === undefined ? savedMtimeMs : undefined)
+          dated?.set(s.name, own)
           continue
         }
+        const mtimeMs = now ?? savedMtimeMs
+        if (now !== undefined && s.link === undefined) dated!.set(s.name, now)
         if (s.link !== undefined) {
           if (s.tree !== undefined) continue
           renames.push(handled(this.place(s, mode, undefined)))
@@ -1988,7 +2114,7 @@ const stagingMade = new Set<string>()
  */
 async function stagingDir(root: string): Promise<string> {
   const top = path.join(root, '.vx', STAGING)
-  const own = path.join(top, `${process.pid.toString(36)}-0`)
+  const own = ownStaging(root)
   if (stagingMade.has(own) && existsSync(own)) return own
   await mkdir(own, { recursive: true })
   // Ignored by git whatever `.vx/.gitignore` an older init committed.
@@ -2001,6 +2127,45 @@ async function stagingDir(root: string): Promise<string> {
   return own
 }
 
+function ownStaging(root: string): string {
+  return path.join(root, '.vx', STAGING, `${process.pid.toString(36)}-0`)
+}
+
+/**
+ * Where a tree restore's copy-out stages: this process's directory under
+ * `root`'s `.vx/tmp/`, its stats, and a fresh name in it per call of
+ * `temp`. With no root each temp sits beside its target.
+ */
+export async function copyStaging(
+  root: string | undefined,
+): Promise<{ stats: Stats | undefined; temp: (target: string) => string }> {
+  if (root === undefined) return { stats: undefined, temp: siblingTemp }
+  // Made already: its stat is the check that it still stands, one call
+  // where `stagingDir`'s check and a stat were two on every restore.
+  let dir = ownStaging(root)
+  let stats = stagingMade.has(dir) ? statSync(dir, { throwIfNoEntry: false }) : undefined
+  if (stats === undefined) {
+    dir = await stagingDir(root)
+    stats = statSync(dir)
+  }
+  return { stats, temp: () => path.join(dir, (tmpSeq++).toString(36)) }
+}
+
+/**
+ * Whether what is made in the directory `staging` names keeps, renamed
+ * into `dir`, what a write in place would give it: the same filesystem
+ * (a rename across fails), and the same group.
+ */
+export function stagesInto(staging: Stats, dir: Stats | undefined): boolean {
+  return (
+    dir !== undefined &&
+    dir.isDirectory() &&
+    dir.dev === staging.dev &&
+    ((dir.mode | staging.mode) & 0o2000) === 0 &&
+    (!INHERITS_GROUP || dir.gid === staging.gid)
+  )
+}
+
 /**
  * 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