@vzn/vx-reapi 0.0.652 → 0.0.653

package/src/executor.ts

@@ -89,6 +89,7 @@ async function decomposeOutputDir(
   entry: { path: string; tree_digest: Digest },
   globs: readonly string[],
   warn: (m: string) => void,
+  workspaceRoot: string,
 ): Promise<DecomposedOutputs> {
   const whole: DecomposedOutputs = { directories: [entry], files: [], symlinks: [] }
   // Only globs that COLLAPSED to this entry are interesting; a literal glob
@@ -114,8 +115,22 @@ async function decomposeOutputDir(
   if (tree.root === undefined) return whole
   const byDigest = new Map<string, Directory>()
   tree.children.forEach((c, i) => byDigest.set(tree.childDigests[i]!, c))
+  // Every match's Tree is written by a replay, and their sum is at most the
+  // capture's own expansion. One past the free inodes is refused by the
+  // download (materialiseOutputs), so splitting it first is wasted work:
+  // recorded whole, a replay refuses it the same.
+  const room = await freeEntries(path.join(workspaceRoot, entry.path))
+  // A path past PATH_MAX is refused the same, and splitting it walked its
+  // depth by recursion.
+  const shape = treeShape(tree.root, byDigest)
+  const deepest = Buffer.byteLength(path.join(workspaceRoot, entry.path)) + shape.longest
+  if (shape.entries > room || deepest >= PATH_MAX) return whole
 
   const out: Array<{ path: string; tree_digest: Digest }> = []
+  // A match's Tree by its directory's digest: a subtree named under many
+  // names was encoded, held and uploaded once per name, 4000 names over one
+  // 4000-directory subtree 65 s and 3.9 GB.
+  const encoded = new Map<string, Blob>()
   const files: DecomposedOutputs['files'] = []
   const symlinks: DecomposedOutputs['symlinks'] = []
   const seen = new Set<string>()
@@ -142,12 +157,22 @@ async function decomposeOutputDir(
   // under it, and a consumer grafted a directory with an empty name.
   const join = (prefix: string, name: string): string =>
     prefix === '' ? name : `${prefix}/${name}`
-  const walk = (dir: Directory, segments: readonly string[], prefix: string): void => {
+  const walk = (
+    dir: Directory,
+    segments: readonly string[],
+    prefix: string,
+    hash: string,
+  ): void => {
     if (segments.length === 0) {
       if (seen.has(prefix)) return
       seen.add(prefix)
-      const data = encodeTree(dir, descendants(dir))
-      out.push({ path: prefix, tree_digest: sha256(data), __data: data } as never)
+      let blob = encoded.get(hash)
+      if (blob === undefined) {
+        const data = encodeTree(dir, descendants(dir))
+        blob = { digest: sha256(data), data }
+        encoded.set(hash, blob)
+      }
+      out.push({ path: prefix, tree_digest: blob.digest })
       return
     }
     const [head, ...rest] = segments
@@ -170,21 +195,18 @@ async function decomposeOutputDir(
       if (!matches(d.name)) continue
       const child = byDigest.get(d.digest.hash)
       if (child === undefined) continue
-      walk(child, rest, join(prefix, d.name))
+      walk(child, rest, join(prefix, d.name), d.digest.hash)
     }
   }
 
-  for (const rest of wild) walk(tree.root, rest, entry.path)
+  for (const rest of wild) walk(tree.root, rest, entry.path, entry.tree_digest.hash)
   if (out.length + files.length + symlinks.length === 0) return whole
 
   // Upload the Tree blobs the new entries point at: one probe for all, the
   // small ones batched, one past the batch limit streamed. One probe and
   // write per entry cost 100 packages 3.4 s through 15 ms each way (F-31).
   // A failed probe or batch still uploads: each blob is written.
-  const blobs = out.map((e) => ({
-    digest: e.tree_digest,
-    data: (e as unknown as { __data: Uint8Array }).__data,
-  }))
+  const blobs = [...encoded.values()]
   await client.uploadBlobs(blobs).catch(async (err: unknown) => {
     warn(
       `[vx] vx-reapi: uploading ${entry.path}'s Tree blobs together failed (${errText(err)}) — writing each`,
@@ -192,7 +214,7 @@ async function decomposeOutputDir(
     for (const b of blobs) await client.writeBlob(b.digest, b.data)
   })
   return {
-    directories: out.map((e) => ({ path: e.path, tree_digest: e.tree_digest })),
+    directories: out,
     files,
     symlinks,
   }
@@ -209,6 +231,9 @@ interface DecomposedOutputs {
  *  it for one alias is the speculative widening the project rejects. */
 type DescribedInputs = NonNullable<ExecuteRequest['inputs']>
 
+/** `google.rpc.Code.FAILED_PRECONDITION`: the action's inputs are not all in the CAS. */
+const FAILED_PRECONDITION = 9
+
 /** Message text from an unknown throw, for a warning line. */
 function errText(err: unknown): string {
   return err instanceof Error ? err.message.split('\n')[0]! : String(err)
@@ -218,7 +243,7 @@ interface DecodedExecuteResponse {
   result?: ActionResult
   message?: string
   cachedResult?: boolean
-  status?: { code: number; message: string }
+  status?: RpcStatus
   /** name → log blob; fetched and surfaced when the action FAILS. */
   serverLogs: Array<{ name: string; digest: Digest; humanReadable: boolean }>
 }
@@ -265,9 +290,16 @@ export function decodeExecuteResponseBytes(buf: Uint8Array): DecodedExecuteRespo
   return out
 }
 
-/** `google.rpc.Status { code = 1, message = 2 }` */
-function decodeRpcStatus(buf: Uint8Array): { code: number; message: string } {
-  const st = { code: 0, message: '' }
+interface RpcStatus {
+  code: number
+  message: string
+  /** Hashes a `PreconditionFailure` detail names MISSING. */
+  missing: string[]
+}
+
+/** `google.rpc.Status { code = 1, message = 2, details = 3 (repeated Any) }` */
+function decodeRpcStatus(buf: Uint8Array): RpcStatus {
+  const st: RpcStatus = { code: 0, message: '', missing: [] }
   let i = 0
   while (i < buf.length) {
     const [key, k] = readVarintAt(buf, i)
@@ -281,13 +313,63 @@ function decodeRpcStatus(buf: Uint8Array): { code: number; message: string } {
     } else if (wire === 2) {
       const [len, l] = readVarintAt(buf, i)
       i = l
-      if (field === 2) st.message = new TextDecoder().decode(buf.subarray(i, i + len))
+      const slice = buf.subarray(i, i + len)
+      if (field === 2) st.message = new TextDecoder().decode(slice)
+      else if (field === 3) st.missing.push(...decodeMissing(slice))
       i += len
     } else break
   }
   return st
 }
 
+/** Length-delimited fields of a message, as `[field, bytes]`; other wire types skipped. */
+function* bytesFields(buf: Uint8Array): Generator<[number, Uint8Array]> {
+  let i = 0
+  while (i < buf.length) {
+    const [key, k] = readVarintAt(buf, i)
+    i = k
+    const wire = key & 7
+    if (wire === 0) i = readVarintAt(buf, i)[1]
+    else if (wire === 2) {
+      const [len, l] = readVarintAt(buf, i)
+      yield [key >>> 3, buf.subarray(l, l + len)]
+      i = l + len
+    } else if (wire === 5) i += 4
+    else if (wire === 1) i += 8
+    else return
+  }
+}
+
+/**
+ * A detail `Any { type_url = 1, value = 2 }` holding
+ * `PreconditionFailure { violations = 1 (Violation { type = 1, subject = 2 }) }`:
+ * the hash of each MISSING `blobs/{hash}/{size}` subject.
+ */
+function decodeMissing(any: Uint8Array): string[] {
+  const text = new TextDecoder()
+  let typeUrl = ''
+  let value: Uint8Array | undefined
+  for (const [f, b] of bytesFields(any)) {
+    if (f === 1) typeUrl = text.decode(b)
+    else if (f === 2) value = b
+  }
+  if (!typeUrl.endsWith('/google.rpc.PreconditionFailure') || value === undefined) return []
+  const hashes: string[] = []
+  for (const [f, violation] of bytesFields(value)) {
+    if (f !== 1) continue
+    let type = ''
+    let subject = ''
+    for (const [vf, b] of bytesFields(violation)) {
+      if (vf === 1) type = text.decode(b)
+      else if (vf === 2) subject = text.decode(b)
+    }
+    const [kind, hash] = subject.split('/')
+    if (type === 'MISSING' && kind === 'blobs' && hash !== undefined && hash !== '')
+      hashes.push(hash)
+  }
+  return hashes
+}
+
 /** One `server_logs` map entry: `{ key = 1 (string), value = 2 (LogFile{digest=1, human_readable=2}) }` */
 function decodeLogEntry(
   buf: Uint8Array,
@@ -565,6 +647,12 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       capsPromise = undefined
       throw err
     }))
+  // The record each execution here wrote, by vx key, for its dependants to
+  // graft: a run core will not save writes under a key no later run asks for
+  // (as vx-dte's `runKey`), since the key's own would replay as its hit
+  // (`unsaved`). Null: deferred outputs no record holds.
+  const runNonce = crypto.randomUUID()
+  const ranHere = new Map<string, Digest | null>()
   const executor: TaskExecutor = {
     name: 'vx/reapi',
     remote: true,
@@ -605,28 +693,38 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
         // decide whether a dependency's bytes exist at all, and treating a
         // failure there as "carry on" is how an action runs without its
         // inputs and caches the result.
-        // stdout asked inline: a server that moved it into CAS otherwise
-        // costs the replay a Read for it (F-25).
-        const prior = await client
-          .getActionResult(execDigestFor(req.cacheKey), { stdout: true, files: [] })
-          .catch((err) => {
-            warn(
-              `[vx] vx-reapi: ${req.taskId} could not read its execution record (${errText(err)}) — executing`,
-            )
-            return null
-          })
-        if (prior !== null) {
-          // The stdout blob too: a Read of an evicted one answers "none", and
-          // the replay printed nothing where the task had printed.
-          const stdoutBlob =
-            (prior.stdout_raw?.length ?? 0) === 0 &&
-            Number(prior.stdout_digest?.size_bytes ?? 0) > 0
-              ? [prior.stdout_digest!]
-              : []
+        // Both streams asked inline: a server that moved them into CAS
+        // otherwise costs the replay a Read each (F-25).
+        const prior = await untilAborted(
+          client.getActionResult(execDigestFor(req.cacheKey), {
+            stdout: true,
+            stderr: true,
+            files: [],
+          }),
+          req.signal,
+        ).catch((err: unknown) => {
+          if (req.signal?.aborted === true) throw err
+          warn(
+            `[vx] vx-reapi: ${req.taskId} could not read its execution record (${errText(err)}) — executing`,
+          )
+          return null
+        })
+        // A record of a failed run is no hit: this module records only exit 0,
+        // but the action cache is the server's, and a worker or another client
+        // may cache a failure. Replayed, it was a success with its outputs saved.
+        if (prior !== null && (prior.exit_code ?? 0) === 0) {
+          // The stream blobs too: an evicted one fails the replay, and the
+          // probe says so before any output is written.
+          const streamBlobs = [
+            [prior.stdout_raw, prior.stdout_digest] as const,
+            [prior.stderr_raw, prior.stderr_digest] as const,
+          ].flatMap(([raw, digest]) =>
+            (raw?.length ?? 0) === 0 && Number(digest?.size_bytes ?? 0) > 0 ? [digest!] : [],
+          )
           const referenced = [
             ...(prior.output_files ?? []).map((f) => f.digest),
             ...(prior.output_directories ?? []).map((d) => d.tree_digest),
-            ...stdoutBlob,
+            ...streamBlobs,
           ]
           // AC and CAS evict independently, so a record can outlive its
           // blobs. A gap means it cannot produce the outputs — fall through
@@ -636,15 +734,20 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
           // and would replay a record whose blobs were never checked.
           const gone =
             referenced.length > 0
-              ? await client.findMissingBlobs(referenced).catch((err: unknown) => {
-                  warn(
-                    `[vx] vx-reapi: ${req.taskId} could not check its execution record's blobs (${errText(err)}) — executing`,
-                  )
-                  return referenced
-                })
+              ? await untilAborted(client.findMissingBlobs(referenced), req.signal).catch(
+                  (err: unknown) => {
+                    if (req.signal?.aborted === true) throw err
+                    warn(
+                      `[vx] vx-reapi: ${req.taskId} could not check its execution record's blobs (${errText(err)}) — executing`,
+                    )
+                    return referenced
+                  },
+                )
               : []
           // The record's paths are WORKSPACE-relative (rebased when it was
           // written), so the anchor is the workspace root, not the cwd.
+          // Only the replay in this call stops with the attempt: a deferred
+          // one runs later, for a consumer, past this attempt's signal.
           const fromRecord = (created?: string[]): Promise<void> =>
             materialiseOutputs(
               client,
@@ -657,6 +760,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
                 // replayed as a warning under a whole-tree capture: the task
                 // succeeded, a declared output missing, on every run.
                 replay: true,
+                ...(created === undefined || req.signal === undefined ? {} : { stop: req.signal }),
               },
               prior,
               warn,
@@ -671,33 +775,41 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
           // those paths must not have them saved as its outputs. What it
           // overwrote was on disk before (a whole-tree capture lists the
           // inputs) and stays.
+          // An abort takes back the same: core settles the attempt on it and
+          // may retry, and a replay still writing landed over the retry.
           const created: string[] = []
-          const replay = async (): Promise<string> => {
-            const stdout = await this_readStream(client, prior.stdout_raw, prior.stdout_digest)
+          const replay = async (): Promise<[string, string]> => {
+            const streams = await Promise.all([
+              readStream(client, prior.stdout_raw, prior.stdout_digest, `${req.taskId}'s stdout`),
+              readStream(client, prior.stderr_raw, prior.stderr_digest, `${req.taskId}'s stderr`),
+            ])
             if (req.remoteOnly !== true && !deferRecord) await fromRecord(created)
-            return stdout
+            return streams
           }
-          const priorStdout =
+          const printed =
             gone.length > 0
               ? null
-              : await replay().catch(async (err: unknown) => {
+              : await untilAborted(replay(), req.signal).catch(async (err: unknown) => {
                   for (const p of created.reverse()) await rm(p, { recursive: true, force: true })
+                  if (req.signal?.aborted === true) throw err
                   warn(
                     `[vx] vx-reapi: ${req.taskId} could not replay its execution record (${errText(err)}) — executing`,
                   )
                   return null
                 })
-          if (priorStdout !== null) {
+          if (printed !== null) {
+            const [priorStdout, priorStderr] = printed
             // Delivered whatever `capture` says, as on the execute path below:
             // a deferred producer saves nothing, so its replay had printed
             // nothing at all (item 827). Only once the replay has landed, so
             // a replay that falls through does not print twice.
             if (priorStdout.length > 0) req.onStdout(priorStdout)
+            if (priorStderr.length > 0) req.onStderr(priorStderr)
             return {
               exitCode: 0,
               durationMs: Math.round((Bun.nanoseconds() - started) / 1e6),
               stdout: req.capture.stdout === false ? '' : priorStdout,
-              stderr: '',
+              stderr: req.capture.stderr === false ? '' : priorStderr,
               violations: [],
               ...(deferRecord
                 ? { outputs: { kind: 'deferred' as const, materialize: () => fromRecord() } }
@@ -749,103 +861,117 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       // Every upstream at once, and each one's trees at once (F-30): a
       // remote-only upstream costs a record read, a probe and a read per
       // tree, and in sequence N upstreams cost N times that.
-      const grafts = await Promise.all(
-        req.inputs.upstream.map(
-          async (
-            up,
-          ): Promise<{
-            local?: string[]
-            files?: FileGraft[]
-            trees?: TreeGraft[]
-            symlinks?: { path: string; target: string }[]
-          }> => {
-            // LOCAL DISK IS TRUTH when the upstream's outputs are materialised
-            // here (core restored or produced them before this task started).
-            // Grafting from the remote execution record instead can DIVERGE: two
-            // machines racing a nondeterministic miss leave the artifact store
-            // and the execution record holding results of DIFFERENT executions
-            // under one pure-input key, and a worker fed the record would see
-            // bytes this machine's own tasks do not. The graft is for outputs
-            // that exist nowhere locally — a remote-only upstream.
-            // "Materialised here" has to be CHECKED, not assumed. `up.outputs`
-            // comes from the local index, which records what an entry contains —
-            // not whether those files are on this disk right now. A task whose
-            // producer ran remotely and did not bring its outputs home has index
-            // rows and no files, and the tree build then dies on `stat` with
-            // ENOENT naming a path the user never asked about. When they are
-            // genuinely absent, the record graft is the correct source, which is
-            // the branch below.
-            const present = up.outputs.filter((rel) =>
-              existsSync(path.join(req.workspaceRoot, rel)),
-            )
-            if (present.length > 0) {
-              if (present.length !== up.outputs.length) {
-                warn(
-                  `[vx] vx-reapi: ${up.taskId} has ${up.outputs.length - present.length} output${up.outputs.length - present.length === 1 ? '' : 's'} recorded ` +
-                    `but missing on disk — grafting is not possible for a partial set, using what is here`,
-                )
-              }
-              return { local: present }
-            }
-            const record = await client.getActionResult(execDigestFor(up.hash))
-            if (record === null) return {}
-            // A record can OUTLIVE its blobs: the AC and the CAS evict on
-            // independent schedules. On THIS branch nothing is local (that is
-            // why we are grafting), so an evicted blob has no local path to
-            // demote to — the declared upstream's outputs exist NOWHERE. An
-            // action shipped without them is not a degraded build, it is a
-            // different one: a command that tolerates the absence exits 0, and
-            // vx caches that result under a key asserting those inputs were
-            // present. Which upstream bytes a command reads is unknowable —
-            // that is what `dependsOn` declares — so refuse, exactly as core's
-            // own materialisation path does. Verified in one round trip.
-            const referenced = [
-              ...(record.output_files ?? []).map((f) => f.digest),
-              ...(record.output_directories ?? []).map((d) => d.tree_digest),
-            ]
-            const gone = await client.findMissingBlobs(referenced)
-            if (gone.length > 0) {
-              throw new UserError(
-                `upstream ${up.taskId} outputs evicted from the remote store (${gone.length} blob${gone.length === 1 ? '' : 's'}) and never materialised locally — re-run it (e.g. --force)`,
+      const grafts = await untilAborted(
+        Promise.all(
+          req.inputs.upstream.map(
+            async (
+              up,
+            ): Promise<{
+              local?: string[]
+              files?: FileGraft[]
+              trees?: TreeGraft[]
+              symlinks?: { path: string; target: string }[]
+            }> => {
+              // LOCAL DISK IS TRUTH when the upstream's outputs are materialised
+              // here (core restored or produced them before this task started).
+              // Grafting from the remote execution record instead can DIVERGE: two
+              // machines racing a nondeterministic miss leave the artifact store
+              // and the execution record holding results of DIFFERENT executions
+              // under one pure-input key, and a worker fed the record would see
+              // bytes this machine's own tasks do not. The graft is for outputs
+              // that exist nowhere locally — a remote-only upstream.
+              // "Materialised here" has to be CHECKED, not assumed. `up.outputs`
+              // comes from the local index, which records what an entry contains —
+              // not whether those files are on this disk right now. A task whose
+              // producer ran remotely and did not bring its outputs home has index
+              // rows and no files, and the tree build then dies on `stat` with
+              // ENOENT naming a path the user never asked about. When they are
+              // genuinely absent, the record graft is the correct source, which is
+              // the branch below.
+              const present = up.outputs.filter((rel) =>
+                existsSync(path.join(req.workspaceRoot, rel)),
               )
-            }
-            const files = (record.output_files ?? []).map((f) => ({
-              path: f.path, // recorded workspace-relative — see the record write below
-              digest: f.digest,
-              isExecutable: f.is_executable === true,
-            }))
-            // A record's symlinks are outputs too (a worker's own, and a glob's
-            // last-segment matches since item 911); without them the action ran
-            // without an input it declared, and its result was cached (item 920).
-            const symlinks = (record.output_symlinks ?? []).map((sl) => ({
-              path: sl.path,
-              target: sl.target,
-            }))
-            const trees = await Promise.all(
-              (record.output_directories ?? []).map(async (d): Promise<TreeGraft | null> => {
-                const treeBlob = await client.readBlob(d.tree_digest)
-                if (treeBlob === null) {
-                  // Raced an eviction between the completeness check and this
-                  // read; on this branch no local copy exists, so the loss is
-                  // real and silently dropping the graft is the same wrong-result
-                  // hazard as an evicted file.
-                  throw new UserError(
-                    `upstream ${up.taskId} tree ${d.tree_digest.hash.slice(0, 12)} evicted from CAS — re-run it (e.g. --force)`,
+              if (present.length > 0) {
+                if (present.length !== up.outputs.length) {
+                  warn(
+                    `[vx] vx-reapi: ${up.taskId} has ${up.outputs.length - present.length} output${up.outputs.length - present.length === 1 ? '' : 's'} recorded ` +
+                      `but missing on disk — grafting is not possible for a partial set, using what is here`,
                   )
                 }
-                const decodedTree = decodeTreeWithBytes(treeBlob)
-                if (decodedTree.root === undefined) return null
-                return {
-                  path: d.path,
-                  root: decodedTree.root,
-                  children: decodedTree.children,
-                  childDigests: decodedTree.childDigests,
-                }
-              }),
-            )
-            return { files, symlinks, trees: trees.filter((t) => t !== null) }
-          },
+                return { local: present }
+              }
+              const known = ranHere.get(up.hash)
+              const record =
+                known === null
+                  ? null
+                  : await client.getActionResult(known ?? execDigestFor(up.hash))
+              if (record === null) {
+                // An upstream with nothing to bring (no outputs, or one that
+                // ran here locally and wrote none) has no record either.
+                if (known === undefined && up.outputs.length === 0) return {}
+                throw new UserError(
+                  `upstream ${up.taskId} outputs are neither on this machine nor in the remote store — re-run it (e.g. --force)`,
+                )
+              }
+              // A record can OUTLIVE its blobs: the AC and the CAS evict on
+              // independent schedules. On THIS branch nothing is local (that is
+              // why we are grafting), so an evicted blob has no local path to
+              // demote to — the declared upstream's outputs exist NOWHERE. An
+              // action shipped without them is not a degraded build, it is a
+              // different one: a command that tolerates the absence exits 0, and
+              // vx caches that result under a key asserting those inputs were
+              // present. Which upstream bytes a command reads is unknowable —
+              // that is what `dependsOn` declares — so refuse, exactly as core's
+              // own materialisation path does. Verified in one round trip.
+              const referenced = [
+                ...(record.output_files ?? []).map((f) => f.digest),
+                ...(record.output_directories ?? []).map((d) => d.tree_digest),
+              ]
+              const gone = await client.findMissingBlobs(referenced)
+              if (gone.length > 0) {
+                throw new UserError(
+                  `upstream ${up.taskId} outputs evicted from the remote store (${gone.length} blob${gone.length === 1 ? '' : 's'}) and never materialised locally — re-run it (e.g. --force)`,
+                )
+              }
+              const files = (record.output_files ?? []).map((f) => ({
+                path: f.path, // recorded workspace-relative — see the record write below
+                digest: f.digest,
+                isExecutable: f.is_executable === true,
+              }))
+              // A record's symlinks are outputs too (a worker's own, and a glob's
+              // last-segment matches since item 911); without them the action ran
+              // without an input it declared, and its result was cached (item 920).
+              const symlinks = (record.output_symlinks ?? []).map((sl) => ({
+                path: sl.path,
+                target: sl.target,
+              }))
+              const trees = await Promise.all(
+                (record.output_directories ?? []).map(async (d): Promise<TreeGraft | null> => {
+                  const treeBlob = await client.readBlob(d.tree_digest)
+                  if (treeBlob === null) {
+                    // Raced an eviction between the completeness check and this
+                    // read; on this branch no local copy exists, so the loss is
+                    // real and silently dropping the graft is the same wrong-result
+                    // hazard as an evicted file.
+                    throw new UserError(
+                      `upstream ${up.taskId} tree ${d.tree_digest.hash.slice(0, 12)} evicted from CAS — re-run it (e.g. --force)`,
+                    )
+                  }
+                  const decodedTree = decodeTreeWithBytes(treeBlob)
+                  if (decodedTree.root === undefined) return null
+                  return {
+                    path: d.path,
+                    root: decodedTree.root,
+                    children: decodedTree.children,
+                    childDigests: decodedTree.childDigests,
+                  }
+                }),
+              )
+              return { files, symlinks, trees: trees.filter((t) => t !== null) }
+            },
+          ),
         ),
+        req.signal,
       )
       for (const g of grafts) {
         localUpstreamPaths.push(...(g.local ?? []))
@@ -924,13 +1050,13 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       // The action id lets a server group this action's CAS/AC traffic in its
       // UI; named before the upload, which is most of that traffic.
       client.nameAction(actionDigest.hash)
-      const caps = await capabilitiesOnce()
+      const caps = await untilAborted(capabilitiesOnce(), req.signal)
       const upload: Blob[] = [
         ...tree.blobs,
         { digest: commandDigest, data: commandBytes },
         { digest: actionDigest, data: actionBytes },
       ]
-      await client.uploadBlobs(upload, caps.maxBatchBytes)
+      await untilAborted(client.uploadBlobs(upload, caps.maxBatchBytes), req.signal)
 
       // `exec.timeout` rides the Action so the SERVER can enforce it, but a
       // server that ignores it — or has stopped making progress at all —
@@ -974,22 +1100,38 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
         )
       let op: Operation
       try {
-        if (req.signal?.aborted === true) throw new Error('aborted before Execute')
-        op = await client.execute(
-          actionDigest,
-          {
-            ...(opts.priority === undefined ? {} : { priority: opts.priority }),
-            onOperation: (name) => {
-              operation = name
-            },
-            // Stage transitions are consumed, not printed: they arrive many
-            // times per action and said nothing a reader could act on.
-            onStage: (stage) => {
-              if (stage.toUpperCase() === 'EXECUTING') armStall()
+        for (let reuploaded = false; ; reuploaded = true) {
+          if (req.signal?.aborted === true) throw new Error('aborted before Execute')
+          op = await client.execute(
+            actionDigest,
+            {
+              ...(opts.priority === undefined ? {} : { priority: opts.priority }),
+              onOperation: (name) => {
+                operation = name
+              },
+              // Stage transitions are consumed, not printed: they arrive many
+              // times per action and said nothing a reader could act on.
+              onStage: (stage) => {
+                if (stage.toUpperCase() === 'EXECUTING') armStall()
+              },
             },
-          },
-          stop,
-        )
+            stop,
+          )
+          // FAILED_PRECONDITION: inputs the server lacks, evicted since
+          // FindMissingBlobs answered (or it answered wrong). The spec's
+          // remedy is to upload them and execute again; once, so a server
+          // that keeps refusing still fails the task. Without the named
+          // violations every input is sent, past FindMissingBlobs.
+          const status = op.error === undefined ? decodeExecuteResponse(op).status : undefined
+          if (reuploaded || status?.code !== FAILED_PRECONDITION) break
+          operation = ''
+          const named = new Set(status.missing)
+          const again = upload.filter((b) => named.has(b.digest.hash))
+          await untilAborted(
+            client.uploadBlobs(again.length > 0 ? again : upload, caps.maxBatchBytes, true),
+            stop,
+          )
+        }
       } catch (err) {
         if (req.signal?.aborted === true) {
           // Core aborts on the run's stop and on `exec.timeout`. A refusal
@@ -998,14 +1140,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
           // is cancelled and the task ends as a killed local one does: 143,
           // which core reports timed out when its timer fired.
           if (operation !== '') await client.cancelOperation(operation).catch(cancelFailed)
-          return {
-            exitCode: 143,
-            durationMs: Math.round((Bun.nanoseconds() - started) / 1e6),
-            stdout: '',
-            stderr: '',
-            violations: [],
-            signal: 'SIGTERM',
-          }
+          return killed(started)
         }
         if (queued.signal.aborted) {
           // Best effort: a server without the service, or one that has lost
@@ -1025,6 +1160,9 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
               `is legitimately this slow; otherwise the remote is not making progress.`,
           )
         }
+        // The client gave up on the stream (its re-attach budget spent);
+        // the action it named still runs on its worker unless cancelled.
+        if (operation !== '') await client.cancelOperation(operation).catch(cancelFailed)
         throw err
       } finally {
         clearTimeout(queueTimer)
@@ -1050,10 +1188,10 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
             return ''
           }
           const [out, err] = await Promise.all([
-            this_readStream(client, result.stdout_raw, result.stdout_digest).catch(
+            readStream(client, result.stdout_raw, result.stdout_digest, 'stdout').catch(
               unread('stdout'),
             ),
-            this_readStream(client, result.stderr_raw, result.stderr_digest).catch(
+            readStream(client, result.stderr_raw, result.stderr_digest, 'stderr').catch(
               unread('stderr'),
             ),
           ])
@@ -1088,11 +1226,18 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       const deferred = req.remoteOnly !== true && req.download === 'deferred'
       const materialised =
         req.remoteOnly !== true && !deferred
-          ? materialiseOutputs(client, matReq, result, warn)
+          ? materialiseOutputs(
+              client,
+              req.signal === undefined ? matReq : { ...matReq, stop: req.signal },
+              result,
+              warn,
+            )
           : Promise.resolve()
+      // A stream the server names and the CAS does not hold fails the task:
+      // read as '', it succeeded printing nothing and was recorded so.
       const logs = Promise.all([
-        this_readStream(client, result.stdout_raw, result.stdout_digest),
-        this_readStream(client, result.stderr_raw, result.stderr_digest),
+        readStream(client, result.stdout_raw, result.stdout_digest, `${req.taskId}'s stdout`),
+        readStream(client, result.stderr_raw, result.stderr_digest, `${req.taskId}'s stderr`),
       ])
       // Settled below with the outputs; a log that cannot be read still
       // fails the task, after the outputs have landed or failed.
@@ -1122,9 +1267,25 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       // The record is written while the outputs come down: the two share
       // nothing, and in turn the record's round trips (a stdout blob, Tree
       // reads, the update) all sat before the first output byte (F-27).
+      // A run core will not save (`unsaved`) records under this run's own
+      // key instead: under the task's it would replay as that key's hit
+      // (executor.ts contract), and with none a deferred one's dependants
+      // had nothing to graft.
+      const hasOutputs =
+        (result.output_files ?? []).length +
+          (result.output_directories ?? []).length +
+          (result.output_symlinks ?? []).length >
+        0
+      if (req.cacheKey !== undefined && deferred && hasOutputs && (result.exit_code ?? 0) === 0) {
+        ranHere.set(req.cacheKey, null)
+      }
       const recording: Promise<void> =
         req.cacheKey !== undefined && (result.exit_code ?? 0) === 0 && tree.moved.length === 0
           ? (async (cacheKey: string): Promise<void> => {
+              const recordKey =
+                req.unsaved === true
+                  ? execDigestFor(`${cacheKey}\0${runNonce}`)
+                  : execDigestFor(cacheKey)
               // A whole-tree capture's path is '' — the working directory itself,
               // which `${wd}/` spelled `pkg/`: never matched by a decomposition,
               // and grafted as a directory with an empty name (item 1040).
@@ -1134,41 +1295,46 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
                   : rel === ''
                     ? workingDirectory
                     : `${workingDirectory}/${rel}`
-              // Stdout rides the record as a blob so a short-circuited repeat run
-              // can replay it. Best-effort: a record without it replays empty,
-              // never wrong bytes.
-              let stdoutDigest: Digest | undefined
-              const stdoutBytes = new TextEncoder().encode(stdout)
-              // Small stdout rides the record itself (`stdout_raw`), which the
-              // replay reads as it reads a digest: two CAS round trips fewer (F-27).
-              const inlineStdout =
-                stdoutBytes.length > 0 && stdoutBytes.length <= INLINE_STDOUT_BYTES
-              // A larger one the server already keeps in CAS is recorded by
-              // its digest: no hash, probe or upload of our own (F-35).
-              if (!inlineStdout && result.stdout_digest !== undefined && stdoutBytes.length > 0) {
-                stdoutDigest = result.stdout_digest
-              } else if (stdoutBytes.length > 0 && !inlineStdout) {
-                const d = sha256(stdoutBytes)
+              // Both streams ride the record so a short-circuited repeat run
+              // replays them. Best-effort: a stream the record could not keep
+              // is left out and replays empty, never as wrong bytes.
+              const kept = async (
+                name: 'stdout' | 'stderr',
+                text: string,
+                serverDigest: Digest | undefined | null,
+              ): Promise<{ raw?: Uint8Array; digest?: Digest }> => {
+                const bytes = new TextEncoder().encode(text)
+                if (bytes.length === 0) return {}
+                // A small one rides the record itself (`*_raw`), which the
+                // replay reads as it reads a digest: two CAS round trips fewer (F-27).
+                if (bytes.length <= INLINE_STREAM_BYTES) return { raw: bytes }
+                // A larger one the server already keeps in CAS is recorded by
+                // its digest: no hash, probe or upload of our own (F-35).
+                if (serverDigest !== undefined && serverDigest !== null) {
+                  return { digest: serverDigest }
+                }
+                const d = sha256(bytes)
                 const missing = await client.findMissingBlobs([d]).catch((err: unknown) => {
                   warn(
-                    `[vx] vx-reapi: ${req.taskId}'s stdout probe failed (${errText(err)}) — uploading it`,
+                    `[vx] vx-reapi: ${req.taskId}'s ${name} probe failed (${errText(err)}) — uploading it`,
                   )
                   return [d]
                 })
-                const uploaded =
-                  missing.length === 0
-                    ? true
-                    : await client.writeBlob(d, stdoutBytes).then(
-                        () => true,
-                        (err: unknown) => {
-                          warn(
-                            `[vx] vx-reapi: ${req.taskId}'s stdout upload failed (${errText(err)}) — recorded without it`,
-                          )
-                          return false
-                        },
-                      )
-                if (uploaded) stdoutDigest = d
+                if (missing.length === 0) return { digest: d }
+                return client.writeBlob(d, bytes).then(
+                  () => ({ digest: d }),
+                  (err: unknown) => {
+                    warn(
+                      `[vx] vx-reapi: ${req.taskId}'s ${name} upload failed (${errText(err)}) — recorded without it`,
+                    )
+                    return {}
+                  },
+                )
               }
+              const [out, err] = await Promise.all([
+                kept('stdout', stdout, result.stdout_digest),
+                kept('stderr', stderr, result.stderr_digest),
+              ])
               // A coarse capture is split into the paths its glob really names
               // before it is recorded — see decomposeOutputDir.
               const declaredGlobs = [
@@ -1193,27 +1359,34 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
                 const rebased = { path: rebase(d.path), tree_digest: d.tree_digest }
                 // The record is best-effort like its write below: a Read that
                 // fails while splitting failed a task whose action had succeeded.
-                const split = await decomposeOutputDir(client, rebased, declaredGlobs, warn).catch(
-                  (err: unknown) => {
-                    warn(
-                      `[vx] vx-reapi: could not read the Tree for ${rebased.path} (${errText(err)}) — recording it whole`,
-                    )
-                    return { directories: [rebased], files: [], symlinks: [] }
-                  },
-                )
+                const split = await decomposeOutputDir(
+                  client,
+                  rebased,
+                  declaredGlobs,
+                  warn,
+                  req.workspaceRoot,
+                ).catch((err: unknown) => {
+                  warn(
+                    `[vx] vx-reapi: could not read the Tree for ${rebased.path} (${errText(err)}) — recording it whole`,
+                  )
+                  return { directories: [rebased], files: [], symlinks: [] }
+                })
                 recorded.directories.push(...split.directories)
                 recorded.files.push(...split.files)
                 recorded.symlinks.push(...split.symlinks)
               }
               await client
-                .updateActionResult(execDigestFor(cacheKey), {
+                .updateActionResult(recordKey, {
                   exit_code: 0,
-                  ...(stdoutDigest === undefined ? {} : { stdout_digest: stdoutDigest }),
-                  ...(inlineStdout ? { stdout_raw: stdoutBytes } : {}),
+                  ...(out.digest === undefined ? {} : { stdout_digest: out.digest }),
+                  ...(out.raw === undefined ? {} : { stdout_raw: out.raw }),
+                  ...(err.digest === undefined ? {} : { stderr_digest: err.digest }),
+                  ...(err.raw === undefined ? {} : { stderr_raw: err.raw }),
                   output_files: recorded.files,
                   output_directories: recorded.directories,
                   output_symlinks: recorded.symlinks,
                 })
+                .then(() => ranHere.set(cacheKey, recordKey))
                 .catch((err: Error) =>
                   warn(
                     `[vx] vx-reapi: could not record execution for ${req.taskId}: ${err.message}`,
@@ -1245,15 +1418,52 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
     },
   }
   const run = executor.execute.bind(executor)
-  executor.execute = (req) =>
-    client
+  executor.execute = (req) => {
+    const started = Bun.nanoseconds()
+    return client
       .inAction(() => run(req))
       .catch((err: unknown) => {
+        // A step the abort cut short (a record replay, an upstream read, the
+        // upload, a restore) ends the task as the abort at Execute does.
+        if (req.signal?.aborted === true) return killed(started)
         throw namedRefusal(req.taskId, err)
       })
+  }
   return executor
 }
 
+/**
+ * The run's stop or `exec.timeout` ended the task: as a killed local one
+ * ends (143, `SIGTERM`), which core reports timed out when its timer fired.
+ */
+function killed(started: number): ExecuteResult {
+  return {
+    exitCode: 143,
+    durationMs: Math.round((Bun.nanoseconds() - started) / 1e6),
+    stdout: '',
+    stderr: '',
+    violations: [],
+    signal: 'SIGTERM',
+  }
+}
+
+/**
+ * `work`, or a rejection the moment `signal` aborts. The calls `work` made
+ * are not cancelled and run on unheard; a write they would lead to is
+ * refused by the Fence, which checks the same signal.
+ */
+function untilAborted<T>(work: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return work
+  // quiet: abandoned on abort, which is the task's outcome
+  work.catch(() => undefined)
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(signal.reason)
+    signal.addEventListener('abort', onAbort, { once: true })
+    work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort))
+  })
+}
+
 /**
  * A gRPC status that escaped `execute` (an Execute the server refused, an
  * upload or upstream read that failed) is the server's answer, not a vx bug.
@@ -1300,15 +1510,19 @@ async function fetchServerLogs(
  * caught by the node_modules chain test the moment the record
  * short-circuit widened past `remote: 'only'`.
  */
-async function this_readStream(
+async function readStream(
   client: ReapiClient,
   raw: Uint8Array | undefined,
   digest: Digest | undefined | null,
+  what: string,
 ): Promise<string> {
   if (raw !== undefined && raw !== null && raw.length > 0) return new TextDecoder().decode(raw)
   if (digest !== undefined && digest !== null && digest.size_bytes > 0) {
     const bytes = await client.readBlob(digest)
-    if (bytes !== null) return new TextDecoder().decode(bytes)
+    if (bytes === null) {
+      throw new UserError(`${what} ${digest.hash.slice(0, 12)} is missing from the CAS`)
+    }
+    return new TextDecoder().decode(bytes)
   }
   return ''
 }
@@ -1385,7 +1599,8 @@ function literalHead(glob: string): { path: string; rest: string[] } {
 /**
  * The action's environment: `inputs.env` (values read from THIS
  * machine's environment, already folded into the cache key) plus
- * `exec.env.define` (literals from the task config). A define wins on
+ * `exec.env.define` (literals from the task config), plus the
+ * `FORCE_COLOR=1` vx sets on every local child. A define wins on
  * collision — it is the more explicit statement of intent. An `inputs.env`
  * name crosses only when the local child gets the same value (`childEnv`,
  * the request's resolved environment): a name the config only TRACKS is in
@@ -1414,6 +1629,10 @@ export function commandEnvironment(
     if (e.value !== undefined && childEnv[e.name] === e.value) merged.set(e.name, e.value)
   }
   for (const [name, value] of Object.entries(envDefine)) merged.set(name, value)
+  // Core's exec/env.ts gives the local child FORCE_COLOR=1 unless it already
+  // sees FORCE_COLOR or a non-empty NO_COLOR. Without it here a worker
+  // stored plain bytes under the key a local run stores coloured ones.
+  if (!merged.has('FORCE_COLOR') && !merged.get('NO_COLOR')) merged.set('FORCE_COLOR', '1')
   return [...merged].map(([name, value]) => ({ name, value }))
 }
 
@@ -1472,6 +1691,8 @@ type MaterialiseRequest = ExecuteRequest & {
    * whose capture holds more than the outputs warns instead.
    */
   readonly replay?: boolean
+  /** The attempt's abort: once it fires, nothing more is written. */
+  readonly stop?: AbortSignal
 }
 
 /**
@@ -1545,7 +1766,42 @@ export async function materialiseOutputs(
     }
     return false
   }
-  const fence = new Fence(req.workspaceRoot, underDeclared)
+  const fence = new Fence(req.workspaceRoot, underDeclared, req.stop)
+  // Every Tree is read and counted before anything is written, and the sum
+  // is held to the free inodes: a record split into one entry per glob
+  // match fitted Tree by Tree, and its replay wrote them all. One Tree
+  // named by many entries is read once.
+  const dirs = result.output_directories ?? []
+  const trees = new Map<string, ReadTree | null>()
+  let expands = 0
+  for (const d of dirs) {
+    let read = trees.get(d.tree_digest.hash)
+    if (read === undefined) {
+      read = await readTree(client, d.tree_digest, missing)
+      trees.set(d.tree_digest.hash, read)
+    }
+    if (read === null) continue
+    expands += read.entries
+    // Past PATH_MAX the walk made the directories of a path the file system
+    // then refused with a raw ENAMETOOLONG.
+    const dest = fence.lexical(req.cwd, d.path)
+    const longest = Buffer.byteLength(dest) + read.longest
+    if (longest >= PATH_MAX) {
+      throw new UserError(
+        `the server's Tree for ${dest} holds a path ${longest} bytes long, past PATH_MAX (${PATH_MAX}) — refused`,
+      )
+    }
+  }
+  const room = expands > 0 ? await freeEntries(req.workspaceRoot) : Infinity
+  if (expands > room) {
+    const what =
+      dirs.length === 1
+        ? `Tree for ${fence.lexical(req.cwd, dirs[0]!.path)} expands`
+        : `${dirs.length} output directories expand`
+    throw new UserError(
+      `the server's ${what} to ${expands < 1e6 ? expands : expands.toPrecision(2)} entries, more than the ${room} this file system has free — refused`,
+    )
+  }
   // A file or link no declared glob names is neither fetched nor written:
   // the workspace root was the only fence, so a result (or a record planted
   // in the action cache) could write `.git/hooks/post-checkout` 0755 or
@@ -1603,18 +1859,12 @@ export async function materialiseOutputs(
     await fence.symlink(sl.target, abs, created)
   }
 
-  for (const d of result.output_directories ?? []) {
+  for (const d of dirs) {
+    const read = trees.get(d.tree_digest.hash)
+    if (read === null || read === undefined) continue
     const dest = fence.lexical(req.cwd, d.path)
     const whole = isDeclared(dest)
-    await materialiseTree(
-      client,
-      fence,
-      dest,
-      d.tree_digest,
-      missing,
-      created,
-      whole ? null : isDeclared,
-    )
+    await materialiseTree(client, fence, dest, read, missing, created, whole ? null : isDeclared)
   }
   await fence.verifyLinks()
 }
@@ -1644,6 +1894,12 @@ class Fence {
     root: string,
     /** A workspace-relative path the task declared as output, or under one. */
     private readonly declared: (rel: string) => boolean = () => true,
+    /**
+     * Once aborted, nothing more is written: each write is preceded by
+     * `landing` or `dir`, which then refuse. A Read already in flight when
+     * the attempt was abandoned lands here, not on disk.
+     */
+    private readonly stop?: AbortSignal,
   ) {
     this.root = path.resolve(root)
   }
@@ -1666,6 +1922,7 @@ class Fence {
     const rel = toPosix(path.relative(this.realRoot, path.join(await real, path.basename(abs))))
     if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel) || !this.declared(rel))
       throw this.refuse(abs)
+    this.stop?.throwIfAborted()
   }
 
   /** `rel` joined under `base`, refused when the join leaves the root. */
@@ -1687,6 +1944,7 @@ class Fence {
 
   /** `dir`, or its deepest existing ancestor, resolves inside the root. */
   async dir(dir: string): Promise<void> {
+    this.stop?.throwIfAborted()
     if (this.checked.has(dir)) return
     // quiet: a local realpath; the root as given stands
     this.realRoot ??= await realpath(this.root).catch(() => this.root)
@@ -1703,6 +1961,7 @@ class Fence {
       if (probe === this.root || path.dirname(probe) === probe) break
       probe = path.dirname(probe)
     }
+    this.stop?.throwIfAborted()
     this.checked.add(dir)
   }
 
@@ -1839,12 +2098,18 @@ async function placeSymlink(
   }
 }
 
-/** Stdout up to this size is recorded inline (`stdout_raw`) rather than as a CAS blob. */
-const INLINE_STDOUT_BYTES = 64 * 1024
+/** A stream up to this size is recorded inline (`stdout_raw`, `stderr_raw`), not as a CAS blob. */
+const INLINE_STREAM_BYTES = 64 * 1024
 
 /** Small blobs a restore holds in memory at once, fetched batched. */
 const TREE_FETCH_WINDOW_BYTES = 64 * 1024 * 1024
 
+/** A Tree read, its children by digest, and what it writes. */
+interface ReadTree extends TreeShape {
+  root: Directory
+  byDigest: Map<string, Directory>
+}
+
 /**
  * An `OutputDirectory` points at the digest of an encoded **`Tree` proto**
  * (root Directory + every descendant), NOT at a Directory to be walked with
@@ -1852,28 +2117,20 @@ const TREE_FETCH_WINDOW_BYTES = 64 * 1024 * 1024
  * this module's first version — because `GetTree` takes a Directory root and
  * would either error or, worse, traverse something else.
  */
-async function materialiseTree(
+async function readTree(
   client: ReapiClient,
-  fence: Fence,
-  destDir: string,
   treeDigest: Digest,
-  // Same policy as the file path: under a literal capture an unmaterialisable
-  // entry is a hole in a DECLARED output directory, so it fails the task.
   missing: (what: string, hash: string, abs?: string) => void,
-  created: string[] | undefined,
-  // Null writes the whole Tree; otherwise only an entry it names, or one
-  // under a directory it names, is written.
-  declared: ((abs: string) => boolean) | null,
-): Promise<void> {
+): Promise<ReadTree | null> {
   const blob = await client.readBlob(treeDigest)
   if (blob === null) {
     missing('tree', treeDigest.hash)
-    return
+    return null
   }
   const tree = decodeTreeWithBytes(blob)
   if (tree.root === undefined) {
     missing('tree (no root directory)', treeDigest.hash)
-    return
+    return null
   }
   // Children are addressed by the digest of the bytes the WORKER encoded.
   // Re-encoding our parse reproduces it only when both encoders agree byte
@@ -1881,34 +2138,83 @@ async function materialiseTree(
   // (item 827), the miss decomposeOutputDir's own comment measured.
   const byDigest = new Map<string, Directory>()
   tree.children.forEach((child, i) => byDigest.set(tree.childDigests[i]!, child))
+  return { root: tree.root, byDigest, ...treeShape(tree.root, byDigest) }
+}
+
+/** What a Tree writes: its paths, and the bytes of its longest one. */
+interface TreeShape {
+  entries: number
+  longest: number
+}
 
-  // A Tree may name one subtree under many names, so 41 directories can
-  // expand to 2^41 paths, and the walk wrote until the disk gave out. Each
-  // path is an inode on disk: counted once per distinct directory, a Tree
-  // that expands past what the file system has free is refused unwritten.
-  const counted = new Map<string, number>()
-  const entries = (dir: Directory): number => {
-    let n = 1 + dir.files.length + dir.symlinks.length
+/** Bytes a path may hold, its terminating NUL included (limits.h). */
+const PATH_MAX = process.platform === 'darwin' ? 1024 : 4096
+
+/**
+ * The paths `root` expands to on disk, itself included, and the bytes of
+ * the longest below it. A Tree may name one subtree under many names, so 41
+ * directories can expand to 2^41 paths, and the walk wrote until the disk
+ * gave out: counted once per distinct directory, a Tree that expands past
+ * what the file system has free is refused unwritten. Walked without
+ * recursion: a Tree 100 000 directories deep overflowed the stack.
+ */
+function treeShape(root: Directory, byDigest: ReadonlyMap<string, Directory>): TreeShape {
+  const shapes = new Map<string, TreeShape>()
+  const shapeOf = (dir: Directory): TreeShape => {
+    let entries = 1 + dir.files.length + dir.symlinks.length
+    let longest = 0
+    for (const f of [...dir.files, ...dir.symlinks]) {
+      longest = Math.max(longest, 1 + Buffer.byteLength(f.name))
+    }
     for (const d of dir.directories) {
-      const node = byDigest.get(d.digest.hash)
-      if (node === undefined) continue
-      let below = counted.get(d.digest.hash)
-      if (below === undefined) {
-        below = entries(node)
-        counted.set(d.digest.hash, below)
-      }
-      n += below
+      const below = shapes.get(d.digest.hash)
+      if (below === undefined) continue
+      entries += below.entries
+      longest = Math.max(longest, 1 + Buffer.byteLength(d.name) + below.longest)
     }
-    return n
+    return { entries, longest }
   }
-  const expands = entries(tree.root)
-  const room = await freeEntries(destDir)
-  if (expands > room) {
-    throw new UserError(
-      `the server's Tree for ${destDir} expands to ${expands < 1e6 ? expands : expands.toPrecision(2)} entries, more than the ${room} this file system has free — refused`,
-    )
+  // Each directory after its children: a child under many names is shaped once.
+  const stack: Array<{ dir: Directory; hash: string; open: boolean }> = [
+    { dir: root, hash: '', open: false },
+  ]
+  for (;;) {
+    const top = stack.at(-1)!
+    if (top.hash !== '' && shapes.has(top.hash)) {
+      stack.pop()
+      continue
+    }
+    if (!top.open) {
+      top.open = true
+      for (const d of top.dir.directories) {
+        const node = byDigest.get(d.digest.hash)
+        if (node !== undefined && !shapes.has(d.digest.hash)) {
+          stack.push({ dir: node, hash: d.digest.hash, open: false })
+        }
+      }
+      continue
+    }
+    stack.pop()
+    const shape = shapeOf(top.dir)
+    if (top.hash === '') return shape
+    shapes.set(top.hash, shape)
   }
+}
 
+/** Writes a Tree `readTree` read and `materialiseOutputs` counted. */
+async function materialiseTree(
+  client: ReapiClient,
+  fence: Fence,
+  destDir: string,
+  { root, byDigest }: ReadTree,
+  // Same policy as the file path: under a literal capture an unmaterialisable
+  // entry is a hole in a DECLARED output directory, so it fails the task.
+  missing: (what: string, hash: string, abs?: string) => void,
+  created: string[] | undefined,
+  // Null writes the whole Tree; otherwise only an entry it names, or one
+  // under a directory it names, is written.
+  declared: ((abs: string) => boolean) | null,
+): Promise<void> {
   // Files are gathered from the whole tree before any is fetched: one
   // BatchReadBlobs per DIRECTORY was a round trip each, so a `dist/` of 200
   // directories restored in 200 sequential calls (F-18). Windows bound what
@@ -1939,7 +2245,7 @@ async function materialiseTree(
       await walk(node, childAt, whole || declared!(childAt))
     }
   }
-  await walk(tree.root, destDir, declared === null)
+  await walk(root, destDir, declared === null)
 
   for (const window of fetchWindows(files, (w) => w.f.digest)) {
     const batched = await client.batchReadBlobs(