@vzn/vx-reapi 0.0.645 → 0.0.648

package/src/executor.ts

@@ -9,7 +9,17 @@
 // anything depending on one, and `exec.remote: false` never reach an
 // executor. This declines the rest of what it cannot honour.
 
-import { mkdir, writeFile, chmod, readlink, realpath, rm, symlink, unlink } from 'node:fs/promises'
+import {
+  mkdir,
+  writeFile,
+  chmod,
+  readlink,
+  realpath,
+  rm,
+  statfs,
+  symlink,
+  unlink,
+} from 'node:fs/promises'
 import { constants, existsSync } from 'node:fs'
 import path from 'node:path'
 import {
@@ -18,6 +28,7 @@ import {
   isUserError,
   normalizeGlob,
   restorableOutput,
+  ui,
   UserError,
   withForwardArgs,
 } from '@vzn/vx'
@@ -38,7 +49,14 @@ import {
   type TreeGraft,
 } from './merkle.js'
 import { execDigestFor } from './cache.js'
-import type { ActionResult, Digest, Directory, Operation, ReapiClient } from './wire.js'
+import {
+  type ActionResult,
+  type Digest,
+  type Directory,
+  MAX_TIMER_MS,
+  type Operation,
+  type ReapiClient,
+} from './wire.js'
 
 // A default decoder strips a leading U+FEFF, which is part of a path.
 const PATH_UTF8 = new TextDecoder('utf-8', { ignoreBOM: true })
@@ -87,7 +105,7 @@ async function decomposeOutputDir(
 
   const blob = await client.readBlob(entry.tree_digest)
   if (blob === null) {
-    warn(`vx/reapi: could not read the Tree for ${entry.path} — recording it whole`)
+    warn(`[vx] vx-reapi: could not read the Tree for ${entry.path} — recording it whole`)
     return whole
   }
   // Keyed by the WORKER's own bytes, not by re-encoding our parse of them —
@@ -103,16 +121,27 @@ async function decomposeOutputDir(
   const seen = new Set<string>()
 
   // Every transitive child of `dir`, which is what a Tree message must carry.
-  const descendants = (dir: Directory, acc: Directory[] = []): Directory[] => {
+  // Each once: a subtree a Tree names under many names was walked per name,
+  // 2^depth from a Tree of depth+1 directories.
+  const descendants = (
+    dir: Directory,
+    acc: Directory[] = [],
+    had = new Set<string>(),
+  ): Directory[] => {
     for (const d of dir.directories) {
       const child = byDigest.get(d.digest.hash)
-      if (child === undefined) continue
+      if (child === undefined || had.has(d.digest.hash)) continue
+      had.add(d.digest.hash)
       acc.push(child)
-      descendants(child, acc)
+      descendants(child, acc, had)
     }
     return acc
   }
 
+  // The whole working directory's capture is `''`: `/name` was recorded
+  // 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 => {
     if (segments.length === 0) {
       if (seen.has(prefix)) return
@@ -125,13 +154,13 @@ async function decomposeOutputDir(
     const matches = (name: string): boolean => head === '*' || name === head
     if (rest.length === 0) {
       for (const f of dir.files) {
-        const at = `${prefix}/${f.name}`
+        const at = join(prefix, f.name)
         if (!matches(f.name) || seen.has(at)) continue
         seen.add(at)
         files.push({ path: at, digest: f.digest, is_executable: f.is_executable })
       }
       for (const sl of dir.symlinks) {
-        const at = `${prefix}/${sl.name}`
+        const at = join(prefix, sl.name)
         if (!matches(sl.name) || seen.has(at)) continue
         seen.add(at)
         symlinks.push({ path: at, target: sl.target })
@@ -141,7 +170,7 @@ async function decomposeOutputDir(
       if (!matches(d.name)) continue
       const child = byDigest.get(d.digest.hash)
       if (child === undefined) continue
-      walk(child, rest, `${prefix}/${d.name}`)
+      walk(child, rest, join(prefix, d.name))
     }
   }
 
@@ -156,7 +185,10 @@ async function decomposeOutputDir(
     digest: e.tree_digest,
     data: (e as unknown as { __data: Uint8Array }).__data,
   }))
-  await client.uploadBlobs(blobs).catch(async () => {
+  await client.uploadBlobs(blobs).catch(async (err: unknown) => {
+    warn(
+      `[vx] vx-reapi: uploading ${entry.path}'s Tree blobs together failed (${errText(err)}) — writing each`,
+    )
     for (const b of blobs) await client.writeBlob(b.digest, b.data)
   })
   return {
@@ -511,21 +543,28 @@ export function acceptsTask(task: TaskPlacement): boolean {
 
 export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions = {}): TaskExecutor {
   // A zero or non-number bound stopped every action the moment it began
-  // executing.
+  // executing, and so did a month's: a timer past MAX_TIMER_MS fires after
+  // 1 ms. Core refuses such an exec.timeout, so every bound fits a timer.
   for (const key of ['executeTimeoutMs', 'queueTimeoutMs'] as const) {
     const ms = opts[key]
-    if (ms !== undefined && !(typeof ms === 'number' && Number.isFinite(ms) && ms > 0)) {
+    if (ms !== undefined && !(typeof ms === 'number' && ms > 0 && ms <= MAX_TIMER_MS)) {
       throw new Error(
-        `@vzn/vx-reapi: ${key} must be a positive number of ms (got ${JSON.stringify(ms)})`,
+        `reapi(): ${key} must be a positive number of ms up to ${MAX_TIMER_MS} (got ${typeof ms === 'number' ? String(ms) : JSON.stringify(ms)})`,
       )
     }
   }
-  const warn = opts.warn ?? (() => undefined)
+  // No listener is no reason to say nothing.
+  const warn = opts.warn ?? ((m: string) => ui.say('warn', m))
   // One Capabilities round trip per executor, not per task — the answer
   // cannot change mid-run, and a 400-task graph would otherwise ask 400 times.
   let capsPromise: ReturnType<ReapiClient['capabilities']> | undefined
+  // A failed ask is not kept: one call past its deadline failed every later
+  // task of the run with the same error.
   const capabilitiesOnce = (): ReturnType<ReapiClient['capabilities']> =>
-    (capsPromise ??= client.capabilities())
+    (capsPromise ??= client.capabilities().catch((err: unknown) => {
+      capsPromise = undefined
+      throw err
+    }))
   const executor: TaskExecutor = {
     name: 'vx/reapi',
     remote: true,
@@ -542,9 +581,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       // status is turned into one by `namedRefusal`), so the scheduler
       // prints it plainly instead of "internal error in <task>".
       if (req.inputs === undefined) {
-        throw new Error(
-          `vx/reapi: ${req.taskId} reached the remote executor with no described inputs`,
-        )
+        throw new Error(`${req.taskId} reached the remote executor with no described inputs`)
       }
 
       // A key that already has an execution record needs no worker at all:
@@ -574,14 +611,22 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
           .getActionResult(execDigestFor(req.cacheKey), { stdout: true, files: [] })
           .catch((err) => {
             warn(
-              `vx/reapi: ${req.taskId} could not read its execution record (${errText(err)}) — executing`,
+              `[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!]
+              : []
           const referenced = [
             ...(prior.output_files ?? []).map((f) => f.digest),
             ...(prior.output_directories ?? []).map((d) => d.tree_digest),
+            ...stdoutBlob,
           ]
           // AC and CAS evict independently, so a record can outlive its
           // blobs. A gap means it cannot produce the outputs — fall through
@@ -591,7 +636,12 @@ 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(() => referenced)
+              ? 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
+                })
               : []
           // The record's paths are WORKSPACE-relative (rebased when it was
           // written), so the anchor is the workspace root, not the cwd.
@@ -633,7 +683,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
               : await replay().catch(async (err: unknown) => {
                   for (const p of created.reverse()) await rm(p, { recursive: true, force: true })
                   warn(
-                    `vx/reapi: ${req.taskId} could not replay its execution record (${errText(err)}) — executing`,
+                    `[vx] vx-reapi: ${req.taskId} could not replay its execution record (${errText(err)}) — executing`,
                   )
                   return null
                 })
@@ -731,7 +781,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
             if (present.length > 0) {
               if (present.length !== up.outputs.length) {
                 warn(
-                  `vx/reapi: ${up.taskId} has ${up.outputs.length - present.length} output(s) recorded ` +
+                  `[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`,
                 )
               }
@@ -756,7 +806,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
             const gone = await client.findMissingBlobs(referenced)
             if (gone.length > 0) {
               throw new UserError(
-                `vx/reapi: upstream ${up.taskId} outputs evicted from the remote store (${gone.length} blob(s)) and never materialised locally — re-run it (e.g. --force)`,
+                `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) => ({
@@ -780,7 +830,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
                   // real and silently dropping the graft is the same wrong-result
                   // hazard as an evicted file.
                   throw new UserError(
-                    `vx/reapi: upstream ${up.taskId} tree ${d.tree_digest.hash.slice(0, 12)} evicted from CAS — re-run it (e.g. --force)`,
+                    `upstream ${up.taskId} tree ${d.tree_digest.hash.slice(0, 12)} evicted from CAS — re-run it (e.g. --force)`,
                   )
                 }
                 const decodedTree = decodeTreeWithBytes(treeBlob)
@@ -829,12 +879,12 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       // next run anywhere replayed the edited outputs (item 1037).
       if (tree.moved.length > 0) {
         warn(
-          `vx/reapi: ${req.taskId}: \`${tree.moved[0]}\` changed after its key was taken — the execution is not recorded under it`,
+          `[vx] vx-reapi: ${req.taskId}: \`${tree.moved[0]}\` changed after its key was taken — the execution is not recorded under it`,
         )
       }
       for (const shadowedPath of tree.shadowed) {
         warn(
-          `vx/reapi: ${req.taskId} declares input files under ${shadowedPath}, which an upstream graft replaces — those files are NOT in the input tree`,
+          `[vx] vx-reapi: ${req.taskId} declares input files under ${shadowedPath}, which an upstream graft replaces — those files are NOT in the input tree`,
         )
       }
 
@@ -871,6 +921,9 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       })
       const actionDigest = sha256(actionBytes)
 
+      // 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 upload: Blob[] = [
         ...tree.blobs,
@@ -879,9 +932,6 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       ]
       await client.uploadBlobs(upload, caps.maxBatchBytes)
 
-      // The action id lets a server group this action's CAS/AC traffic in its
-      // UI; set before Execute so the streaming call carries it too.
-      client.actionId = actionDigest.hash
       // `exec.timeout` rides the Action so the SERVER can enforce it, but a
       // server that ignores it — or has stopped making progress at all —
       // leaves the client waiting forever, and the operation stream is no
@@ -917,6 +967,11 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
         queued.signal,
         ...(req.signal === undefined ? [] : [req.signal]),
       ])
+      // A cancel the server refused leaves the action running on its worker.
+      const cancelFailed = (err: unknown): void =>
+        warn(
+          `[vx] vx-reapi: cancelling ${req.taskId}'s operation failed (${errText(err)}) — it may still run on its worker`,
+        )
       let op: Operation
       try {
         if (req.signal?.aborted === true) throw new Error('aborted before Execute')
@@ -942,7 +997,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
           // closed stream left the action running on its worker. The action
           // 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(() => undefined)
+          if (operation !== '') await client.cancelOperation(operation).catch(cancelFailed)
           return {
             exitCode: 143,
             durationMs: Math.round((Bun.nanoseconds() - started) / 1e6),
@@ -955,14 +1010,16 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
         if (queued.signal.aborted) {
           // Best effort: a server without the service, or one that has lost
           // the operation, still has the task given back.
-          if (operation !== '') await client.cancelOperation(operation).catch(() => undefined)
+          if (operation !== '') await client.cancelOperation(operation).catch(cancelFailed)
           throw executorFallback(
-            `vx/reapi: no worker started the action within queueTimeoutMs (${opts.queueTimeoutMs}ms); its operation was cancelled`,
+            `no worker started the action within queueTimeoutMs (${opts.queueTimeoutMs}ms); its operation was cancelled`,
           )
         }
         if (stall.signal.aborted) {
+          // Closing the stream alone left the action on its worker.
+          if (operation !== '') await client.cancelOperation(operation).catch(cancelFailed)
           throw new UserError(
-            `vx/reapi: ${req.taskId} was still executing ${stallAfter}ms after the worker ` +
+            `${req.taskId} was still executing ${stallAfter}ms after the worker ` +
               `started it and the server never reported a result — giving up on the remote ` +
               `operation. Raise exec.timeout (or the plugin's executeTimeoutMs) if the task ` +
               `is legitimately this slow; otherwise the remote is not making progress.`,
@@ -975,7 +1032,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       }
       if (op.error !== undefined && (op.error.code ?? 0) !== 0) {
         throw new UserError(
-          `vx/reapi: execution failed for ${req.taskId}: ${op.error.message ?? `code ${op.error.code}`}`,
+          `execution failed for ${req.taskId}: ${op.error.message ?? `code ${op.error.code}`}`,
         )
       }
       const decoded = decodeExecuteResponse(op)
@@ -988,23 +1045,31 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
         // partial result, as the spec suggests: what the command printed
         // is delivered before the refusal, best effort (F-48).
         if (result !== undefined) {
+          const unread = (stream: string) => (e: unknown) => {
+            warn(`[vx] vx-reapi: ${req.taskId}'s ${stream} could not be read (${errText(e)})`)
+            return ''
+          }
           const [out, err] = await Promise.all([
-            this_readStream(client, result.stdout_raw, result.stdout_digest).catch(() => ''),
-            this_readStream(client, result.stderr_raw, result.stderr_digest).catch(() => ''),
+            this_readStream(client, result.stdout_raw, result.stdout_digest).catch(
+              unread('stdout'),
+            ),
+            this_readStream(client, result.stderr_raw, result.stderr_digest).catch(
+              unread('stderr'),
+            ),
           ])
           if (out.length > 0) req.onStdout(out)
           if (err.length > 0) req.onStderr(err)
         }
-        const logs = await fetchServerLogs(client, decoded.serverLogs)
+        const logs = await fetchServerLogs(client, decoded.serverLogs, warn)
         throw new UserError(
-          `vx/reapi: ${req.taskId} execution failed: ${decoded.status.message || `code ${decoded.status.code}`}` +
+          `${req.taskId} execution failed: ${decoded.status.message || `code ${decoded.status.code}`}` +
             (decoded.message === undefined ? '' : ` — ${decoded.message}`) +
             logs,
         )
       }
       if (result === undefined) {
         throw new UserError(
-          `vx/reapi: ${req.taskId} returned no ActionResult${decoded.message === undefined ? '' : `: ${decoded.message}`}`,
+          `${req.taskId} returned no ActionResult${decoded.message === undefined ? '' : `: ${decoded.message}`}`,
         )
       }
       // The worker id is REPORTED, not logged: it rides `ExecuteResult.where`
@@ -1031,7 +1096,9 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
       ])
       // Settled below with the outputs; a log that cannot be read still
       // fails the task, after the outputs have landed or failed.
+      // quiet: settled below, where its error fails the task
       logs.catch(() => undefined)
+      // quiet: settled below, where its error fails the task
       materialised.catch(() => undefined)
       const [stdout, stderr] = await logs.catch(async (err: unknown) => {
         await materialised.catch(() => undefined)
@@ -1082,21 +1149,33 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
                 stdoutDigest = result.stdout_digest
               } else if (stdoutBytes.length > 0 && !inlineStdout) {
                 const d = sha256(stdoutBytes)
-                const missing = await client.findMissingBlobs([d]).catch(() => [d])
+                const missing = await client.findMissingBlobs([d]).catch((err: unknown) => {
+                  warn(
+                    `[vx] vx-reapi: ${req.taskId}'s stdout probe failed (${errText(err)}) — uploading it`,
+                  )
+                  return [d]
+                })
                 const uploaded =
                   missing.length === 0
                     ? true
                     : await client.writeBlob(d, stdoutBytes).then(
                         () => true,
-                        () => false,
+                        (err: unknown) => {
+                          warn(
+                            `[vx] vx-reapi: ${req.taskId}'s stdout upload failed (${errText(err)}) — recorded without it`,
+                          )
+                          return false
+                        },
                       )
                 if (uploaded) stdoutDigest = d
               }
               // A coarse capture is split into the paths its glob really names
               // before it is recorded — see decomposeOutputDir.
               const declaredGlobs = [
-                ...req.outputs.workspaceFiles,
-                ...req.outputs.files.map((g) => (projectRel === '' ? g : `${projectRel}/${g}`)),
+                ...req.outputs.workspaceFiles.filter(isOutputGlob),
+                ...req.outputs.files
+                  .filter(isOutputGlob)
+                  .map((g) => (projectRel === '' ? g : `${projectRel}/${g}`)),
               ].map((g) => normalizeGlob(g))
               const recorded: DecomposedOutputs = {
                 directories: [],
@@ -1117,7 +1196,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
                 const split = await decomposeOutputDir(client, rebased, declaredGlobs, warn).catch(
                   (err: unknown) => {
                     warn(
-                      `vx/reapi: could not read the Tree for ${rebased.path} (${errText(err)}) — recording it whole`,
+                      `[vx] vx-reapi: could not read the Tree for ${rebased.path} (${errText(err)}) — recording it whole`,
                     )
                     return { directories: [rebased], files: [], symlinks: [] }
                   },
@@ -1136,7 +1215,9 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
                   output_symlinks: recorded.symlinks,
                 })
                 .catch((err: Error) =>
-                  warn(`vx/reapi: could not record execution for ${req.taskId}: ${err.message}`),
+                  warn(
+                    `[vx] vx-reapi: could not record execution for ${req.taskId}: ${err.message}`,
+                  ),
                 )
             })(req.cacheKey!)
           : Promise.resolve()
@@ -1165,9 +1246,11 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
   }
   const run = executor.execute.bind(executor)
   executor.execute = (req) =>
-    run(req).catch((err: unknown) => {
-      throw namedRefusal(req.taskId, err)
-    })
+    client
+      .inAction(() => run(req))
+      .catch((err: unknown) => {
+        throw namedRefusal(req.taskId, err)
+      })
   return executor
 }
 
@@ -1181,7 +1264,7 @@ function namedRefusal(taskId: string, err: unknown): unknown {
   if (isUserError(err) || !(err instanceof Error)) return err
   const status = err as Error & { code?: unknown; details?: unknown }
   if (typeof status.code !== 'number' || typeof status.details !== 'string') return err
-  return new UserError(`vx/reapi: ${taskId}: the remote server failed the call — ${err.message}`)
+  return new UserError(`${taskId}: the remote server failed the call — ${err.message}`)
 }
 
 /**
@@ -1191,12 +1274,16 @@ function namedRefusal(taskId: string, err: unknown): unknown {
 async function fetchServerLogs(
   client: ReapiClient,
   logs: ReadonlyArray<{ name: string; digest: Digest; humanReadable: boolean }>,
+  warn: (m: string) => void,
 ): Promise<string> {
   const readable = logs.filter((l) => l.humanReadable && l.digest.size_bytes <= 64 * 1024)
   if (readable.length === 0) return ''
   const parts: string[] = []
   for (const log of readable) {
-    const bytes = await client.readBlob(log.digest).catch(() => null)
+    const bytes = await client.readBlob(log.digest).catch((err: unknown) => {
+      warn(`[vx] vx-reapi: the server log ${log.name} could not be read (${errText(err)})`)
+      return null
+    })
     if (bytes !== null)
       parts.push(`\n--- server log ${log.name} ---\n${new TextDecoder().decode(bytes)}`)
   }
@@ -1249,17 +1336,25 @@ function fullCommand(req: ExecuteRequest, cdInto: string, projectRel: string): s
           .join('/')}`
   const root = cdInto === '' ? `"$PWD${climb}"` : '"$PWD"'
   // Order matters: VX_ROOT is read BEFORE the cd, the project-local bin dir
-  // AFTER it, so both are right whichever mode we are in.
+  // AFTER it, so both are right whichever mode we are in. The project's
+  // first, as core's taskBinDirs: a tool the project pins beats the root's.
   // Quoted as the forwarded args are: a project directory is a name like
   // any other, and `it's` ended the quote and ran the rest as script (L-7).
   const cd = cdInto === '' ? '' : `cd '${cdInto.replaceAll("'", `'\\''`)}' || exit 1; `
   return (
     `VX_ROOT=${root}; ${cd}` +
-    `export PATH="$VX_ROOT/node_modules/.bin:$PWD/node_modules/.bin:$PATH"; ` +
+    `export PATH="$PWD/node_modules/.bin:$VX_ROOT/node_modules/.bin:$PATH"; ` +
     command
   )
 }
 
+/**
+ * A `!` take-back names what is NOT an output (core's restore gate reads
+ * it): requested, `!dist/cache/**` was the path `!dist/cache`, and as a
+ * matcher `Bun.Glob('!x')` matches every path but `x`.
+ */
+const isOutputGlob = (glob: string): boolean => !glob.startsWith('!')
+
 /**
  * vx declares output GLOBS; REAPI `output_paths` are LITERAL paths. The
  * mapping the design doc prescribes: each glob contributes the deepest
@@ -1342,9 +1437,10 @@ export function outputPathSets(
   const prefix = (p: string): string =>
     workingDirectory === '' && projectRel !== '' ? `${projectRel}/${p}` : p
   // `app/\[id\]/x` names the file `app/[id]/x`: `literalHead` unescapes.
-  const globs = [...req.outputs.files.map(prefix), ...req.outputs.workspaceFiles.map(rebase)].map(
-    (g) => normalizeGlob(g),
-  )
+  const globs = [
+    ...req.outputs.files.filter(isOutputGlob).map(prefix),
+    ...req.outputs.workspaceFiles.filter(isOutputGlob).map(rebase),
+  ].map((g) => normalizeGlob(g))
   const paths = new Set<string>()
   const files = new Set<string>()
   const dirs = new Set<string>()
@@ -1402,17 +1498,17 @@ export async function materialiseOutputs(
   const wholeTreeCapture = [
     ...(req.outputs?.files ?? []),
     ...(req.outputs?.workspaceFiles ?? []),
-  ].some((g) => globToOutputPath(g) === '')
+  ].some((g) => isOutputGlob(g) && globToOutputPath(g) === '')
   // `abs` names a file a declared glob matches: missing, it is a hole in a
   // declared output under either capture, and warning let `save` cache the
   // short tree under the key (F-8).
   const missing = (what: string, hash: string, abs?: string): void => {
     if (!wholeTreeCapture || req.replay === true || (abs !== undefined && isDeclared(abs))) {
       throw new UserError(
-        `vx/reapi: ${req.taskId} declared output ${what} is missing from the CAS (${hash.slice(0, 12)}) — re-run it (e.g. --force)`,
+        `${req.taskId} declared output ${what} is missing from the CAS (${hash.slice(0, 12)}) — re-run it (e.g. --force)`,
       )
     }
-    warn(`vx/reapi: output ${what} missing from CAS (${hash.slice(0, 12)})`)
+    warn(`[vx] vx-reapi: output ${what} missing from CAS (${hash.slice(0, 12)})`)
   }
   // A glob cut at its wildcard captured a directory that holds more than
   // the outputs — `src/*.gen.js` returns all of `src`, inputs included.
@@ -1422,8 +1518,10 @@ export async function materialiseOutputs(
   // the task (item 1038). A directory a LITERAL glob names is written whole.
   const projectRel = req.projectRel ?? toPosix(path.relative(req.workspaceRoot, req.cwd))
   const declared = [
-    ...(req.outputs?.files ?? []).map((g) => (projectRel === '' ? g : `${projectRel}/${g}`)),
-    ...(req.outputs?.workspaceFiles ?? []),
+    ...(req.outputs?.files ?? [])
+      .filter(isOutputGlob)
+      .map((g) => (projectRel === '' ? g : `${projectRel}/${g}`)),
+    ...(req.outputs?.workspaceFiles ?? []).filter(isOutputGlob),
   ].map((g) => normalizeGlob(g))
   const matchers = declared.map((g) => new Bun.Glob(g))
   // Core's restore gate: a `!` take-back, vx's own files and a
@@ -1457,39 +1555,43 @@ export async function materialiseOutputs(
   )
   // Batch the small ones into one round trip; anything larger goes over
   // ByteStream, which is also the only path that can be compressed.
-  const small = files.filter((f) => f.digest.size_bytes > 0 && f.digest.size_bytes <= 1024 * 1024)
-  const batched = await client.batchReadBlobs(small.map((f) => f.digest))
-
-  await mapBounded(files, WRITE_CONCURRENCY, async (f) => {
-    const abs = fence.lexical(req.cwd, f.path)
-    await fence.dir(path.dirname(abs))
-    await makeDir(path.dirname(abs), created)
-    await fence.landing(abs)
-    // Inlined only when it has bytes: an ActionResult read back through
-    // proto-loader (the execution-record replay) carries `contents` as an
-    // EMPTY Buffer on every file, and taking that as inline wrote each
-    // replayed output empty (item 827). An empty file is the next branch.
-    // Inline bytes are held to the digest they ride with, as fetched ones
-    // are in wire.ts: a server's wrong inline copy was written as the output
-    // and cached under the key (F-8). A mismatch fetches the blob instead.
-    const inline =
-      f.contents !== undefined &&
-      f.contents.length > 0 &&
-      digestWith(client.digest, f.contents).hash === f.digest.hash
-    const bytes = inline
-      ? f.contents! // inlined by the server (`inline_output_files`): zero fetches
-      : Number(f.digest.size_bytes) === 0
-        ? new Uint8Array()
-        : (batched.get(f.digest.hash) ?? (await client.readBlob(f.digest)))
-    if (bytes === null) {
-      missing(f.path, f.digest.hash, abs)
-      return
-    }
-    await writeOutput(abs, bytes, created)
-    // REAPI carries the executable bit per output; a build that produces a
-    // script and a later task that runs it depends on it surviving.
-    if (f.is_executable === true) await chmod(abs, 0o755)
-  })
+  // A window at a time, as a Tree's files are: one batch read of every
+  // small output held them all in memory at once.
+  for (const window of fetchWindows(files, (f) => f.digest)) {
+    const batched = await client.batchReadBlobs(
+      window.filter((f) => isSmallBlob(f.digest)).map((f) => f.digest),
+    )
+    await mapBounded(window, WRITE_CONCURRENCY, async (f) => {
+      const abs = fence.lexical(req.cwd, f.path)
+      await fence.dir(path.dirname(abs))
+      await makeDir(path.dirname(abs), created)
+      await fence.landing(abs)
+      // Inlined only when it has bytes: an ActionResult read back through
+      // proto-loader (the execution-record replay) carries `contents` as an
+      // EMPTY Buffer on every file, and taking that as inline wrote each
+      // replayed output empty (item 827). An empty file is the next branch.
+      // Inline bytes are held to the digest they ride with, as fetched ones
+      // are in wire.ts: a server's wrong inline copy was written as the output
+      // and cached under the key (F-8). A mismatch fetches the blob instead.
+      const inline =
+        f.contents !== undefined &&
+        f.contents.length > 0 &&
+        digestWith(client.digest, f.contents).hash === f.digest.hash
+      const bytes = inline
+        ? f.contents! // inlined by the server (`inline_output_files`): zero fetches
+        : Number(f.digest.size_bytes) === 0
+          ? new Uint8Array()
+          : (batched.get(f.digest.hash) ?? (await client.readBlob(f.digest)))
+      if (bytes === null) {
+        missing(f.path, f.digest.hash, abs)
+        return
+      }
+      await writeOutput(abs, bytes, created)
+      // REAPI carries the executable bit per output; a build that produces a
+      // script and a later task that runs it depends on it surviving.
+      if (f.is_executable === true) await chmod(abs, masked(0o755))
+    })
+  }
 
   // `OutputSymlink` — a declared output that is a link, not a file. Restoring
   // it as a copy would silently change what the next task sees.
@@ -1553,6 +1655,7 @@ class Fence {
    * containment checks passed). The landing must itself be declared.
    */
   async landing(abs: string): Promise<void> {
+    // quiet: a local realpath; the root as given stands
     this.realRoot ??= await realpath(this.root).catch(() => this.root)
     const dir = path.dirname(abs)
     let real = this.realDirs.get(dir)
@@ -1585,9 +1688,11 @@ class Fence {
   /** `dir`, or its deepest existing ancestor, resolves inside the root. */
   async dir(dir: string): Promise<void> {
     if (this.checked.has(dir)) return
+    // quiet: a local realpath; the root as given stands
     this.realRoot ??= await realpath(this.root).catch(() => this.root)
     let probe = dir
     for (;;) {
+      // quiet: a local path not there yet: its parent is checked
       const real = await realpath(probe).catch(() => null)
       if (real !== null) {
         if (real !== this.realRoot && !real.startsWith(this.realRoot + path.sep)) {
@@ -1601,13 +1706,25 @@ class Fence {
     this.checked.add(dir)
   }
 
-  /** A link whose target, read from where it stands, stays under the root. */
+  /**
+   * A link whose target, read from where it stands, stays under the root,
+   * placed only where a declared output lands: through an earlier link it
+   * planted a hook or replaced another project's file.
+   */
   async symlink(target: string, abs: string, created: string[] | undefined): Promise<void> {
     const to = path.resolve(path.dirname(abs), target)
     if (target.includes('\0') || (to !== this.root && !to.startsWith(this.root + path.sep))) {
       throw this.refuse(`${abs} -> ${target}`)
     }
+    await this.landing(abs)
     await placeSymlink(target, abs, created)
+    // A link re-placed at `abs` moves every directory under it: a memo
+    // judged through the old one let the next write land through the new.
+    for (const memo of [this.realDirs, this.checked]) {
+      for (const dir of memo.keys()) {
+        if (dir === abs || dir.startsWith(abs + path.sep)) memo.delete(dir)
+      }
+    }
     this.links.push({ abs, target })
   }
 
@@ -1619,6 +1736,7 @@ class Fence {
    * escaping link is removed before the refusal.
    */
   async verifyLinks(): Promise<void> {
+    // quiet: a local realpath; the root as given stands
     this.realRoot ??= await realpath(this.root).catch(() => this.root)
     for (const { abs, target } of this.links) {
       const to = await resolveThrough(
@@ -1633,7 +1751,7 @@ class Fence {
 
   private refuse(what: string): UserError {
     return new UserError(
-      `vx/reapi: the server returned an output outside the workspace (${what}) — refused; nothing is written outside ${this.root}`,
+      `the server returned an output outside the workspace (${what}) — refused; nothing is written outside ${this.root}`,
     )
   }
 }
@@ -1694,6 +1812,7 @@ async function resolveThrough(p: string): Promise<string> {
       continue
     }
     const next = path.join(at, c)
+    // quiet: a local path that is no link
     const target = await readlink(next).catch(() => null)
     if (target === null || ++hops > 40) {
       at = next
@@ -1723,7 +1842,7 @@ 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
 
-/** Small blobs a tree restore holds in memory at once, fetched batched. */
+/** Small blobs a restore holds in memory at once, fetched batched. */
 const TREE_FETCH_WINDOW_BYTES = 64 * 1024 * 1024
 
 /**
@@ -1763,6 +1882,33 @@ async function materialiseTree(
   const byDigest = new Map<string, Directory>()
   tree.children.forEach((child, i) => byDigest.set(tree.childDigests[i]!, child))
 
+  // 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
+    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
+    }
+    return n
+  }
+  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`,
+    )
+  }
+
   // 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
@@ -1795,18 +1941,9 @@ async function materialiseTree(
   }
   await walk(tree.root, destDir, declared === null)
 
-  const isSmall = (f: { digest: Digest }): boolean =>
-    f.digest.size_bytes > 0 && f.digest.size_bytes <= 1024 * 1024
-  for (let i = 0; i < files.length;) {
-    let held = 0
-    let j = i
-    while (j < files.length && (j === i || held < TREE_FETCH_WINDOW_BYTES)) {
-      if (isSmall(files[j]!.f)) held += Number(files[j]!.f.digest.size_bytes)
-      j++
-    }
-    const window = files.slice(i, j)
+  for (const window of fetchWindows(files, (w) => w.f.digest)) {
     const batched = await client.batchReadBlobs(
-      window.filter((w) => isSmall(w.f)).map((w) => w.f.digest),
+      window.filter((w) => isSmallBlob(w.f.digest)).map((w) => w.f.digest),
     )
     await mapBounded(window, WRITE_CONCURRENCY, async ({ abs, f }) => {
       const bytes =
@@ -1819,14 +1956,57 @@ async function materialiseTree(
       }
       await fence.landing(abs)
       await writeOutput(abs, bytes, created)
-      if (f.is_executable) await chmod(abs, 0o755)
+      if (f.is_executable) await chmod(abs, masked(0o755))
       // NodeProperties.unix_mode is authoritative when the server sent it.
       const mode = f.node_properties?.unixMode
       // Permission bits only: a server's setuid or setgid bit is not a build output's.
-      if (mode !== undefined) await chmod(abs, mode & 0o777)
+      if (mode !== undefined) await chmod(abs, masked(mode))
     })
+  }
+}
+
+/** A blob fetched in a batch read, and so held in memory with its window. */
+const isSmallBlob = (d: Digest): boolean =>
+  Number(d.size_bytes) > 0 && Number(d.size_bytes) <= 1024 * 1024
+
+/** `items` cut where their small blobs reach `TREE_FETCH_WINDOW_BYTES`. */
+function fetchWindows<T>(items: readonly T[], digestOf: (item: T) => Digest): T[][] {
+  const windows: T[][] = []
+  for (let i = 0; i < items.length;) {
+    let held = 0
+    let j = i
+    while (j < items.length && (j === i || held < TREE_FETCH_WINDOW_BYTES)) {
+      const d = digestOf(items[j]!)
+      if (isSmallBlob(d)) held += Number(d.size_bytes)
+      j++
+    }
+    windows.push(items.slice(i, j))
     i = j
   }
+  return windows
+}
+
+/**
+ * A mode as this machine gives it: minus the umask, as a local build and
+ * core's restore do. A server's 0777 was written world-writable under
+ * umask 022, and 0755 world-readable under 077.
+ */
+function masked(mode: number): number {
+  return mode & 0o777 & ~process.umask()
+}
+
+/**
+ * The files `dir`'s file system can still create: its free inodes, or its
+ * free blocks where it keeps no inode count (btrfs reports 0 of 0). Asked of
+ * the nearest ancestor that exists; unbounded when none answers.
+ */
+async function freeEntries(dir: string): Promise<number> {
+  for (let at = dir; ; at = path.dirname(at)) {
+    // quiet: a path not there yet: its parent answers
+    const fs = await statfs(at).catch(() => null)
+    if (fs !== null) return fs.files > 0 ? fs.ffree : fs.bavail
+    if (path.dirname(at) === at) return Infinity
+  }
 }
 
 /** Output files `materialiseOutputs` writes at once. */