@vzn/vx 0.0.645 → 0.0.648

package/src/orchestrator/local-floor.ts

@@ -0,0 +1,198 @@
+// Core's local floor for a plugin that runs tasks itself: `@vzn/vx-dte`'s
+// workers, which run tasks another machine placed. A run arms the sandbox
+// runtime before it builds a sandboxed request; a worker is no run, so it
+// arms here. It starts a request's servers (`ExecuteRequest.servers`) once
+// each, before the task, each inside its own sandbox, and stops them when
+// it closes.
+
+import type { ExecConfig } from '../config.js'
+import {
+  localExecutor,
+  PersistentReadyError,
+  releaseBridges,
+  resetSandbox,
+  runPersistent,
+  signalExitCode,
+  type ExecuteRequest,
+  type ExecuteResult,
+  type ServerSpec,
+  wrapSandboxedCommand,
+} from '../exec/index.js'
+import { placeholderSweeper, prepareSandbox, sandboxRequestFor } from './sandbox-request.js'
+import { forwardedSignal, terminateChildren } from './signals.js'
+
+/** How much of a server's output before ready a failure to start quotes. */
+const HEARD_BYTES = 8192
+
+export interface LocalFloor {
+  execute(req: ExecuteRequest): Promise<ExecuteResult>
+  /** Arms the sandbox runtime for `sandboxes` from the next sandboxed task on; its servers keep running. */
+  rearm(sandboxes: readonly NonNullable<ExecConfig['sandbox']>[]): Promise<void>
+  /** Stops the servers this started and the sandbox runtime this armed. */
+  close(): Promise<void>
+}
+
+/**
+ * `sandboxes`, in a process that is no run, are the `exec.sandbox` configs
+ * of every sandboxed task the run holds: the runtime's proxy and its
+ * unix-socket filter are one per process, set from their union before the
+ * first sandboxed task (`prepareSandbox`). A request that carries a
+ * `signal` but no `liveChildren` has its children stopped here when it
+ * aborts, the way a run's stop ends its own.
+ */
+export function localFloor(
+  sandboxes: readonly NonNullable<ExecConfig['sandbox']>[] = [],
+): LocalFloor {
+  const local = localExecutor()
+  const prepare = (list: typeof sandboxes) =>
+    prepareSandbox(list.map((sandbox) => ({ config: { exec: { sandbox } } })))
+  let armer = prepare(sandboxes)
+  // Each server, by task id: shared by every task here that depends on it.
+  const servers = new Map<string, Promise<ReturnType<typeof Bun.spawn>>>()
+  const children: ReturnType<typeof Bun.spawn>[] = []
+  // A sandboxed one starts inside its sandbox, built here as a one-shot
+  // task's; its port bridges and untouched placeholders go when it exits.
+  const start = async (spec: ServerSpec, root: string): Promise<ReturnType<typeof Bun.spawn>> => {
+    let command = spec.command
+    let signalChannel = false
+    let gone = async (): Promise<unknown> => undefined
+    if (spec.sandbox !== undefined) {
+      await armer?.arm()
+      const sb = await sandboxRequestFor(
+        { projectDir: spec.cwd },
+        spec.sandbox.config,
+        root,
+        undefined,
+        spec.sandbox.nested,
+      )
+      const swept = placeholderSweeper(sb.placeholders)
+      const wrapped = await wrapSandboxedCommand({
+        command,
+        cwd: spec.cwd,
+        env: spec.env,
+        ...sb.sandbox,
+        server: true,
+      }).catch(async (err: unknown) => {
+        await swept()
+        throw err
+      })
+      command = wrapped.wrapped
+      signalChannel = wrapped.forwardsSignals
+      gone = async () => {
+        if (wrapped.tag !== undefined) releaseBridges(wrapped.tag)
+        return swept()
+      }
+    }
+    // Its output until ready, the tail kept: a server that dies first says
+    // why (`docker run` exiting 125 said nothing on CI, 2026-10-26).
+    let heard: string | undefined = ''
+    const hear = (t: string): void => {
+      if (heard !== undefined) heard = (heard + t).slice(-HEARD_BYTES)
+    }
+    const spawn = runPersistent({
+      command,
+      cwd: spec.cwd,
+      env: spec.env,
+      onStdout: hear,
+      onStderr: hear,
+      ...(spec.readyWhen === undefined ? {} : { readyWhen: spec.readyWhen }),
+      ...(spec.timeoutMs === undefined ? {} : { timeoutMs: spec.timeoutMs }),
+      ...(signalChannel ? { signalChannel } : {}),
+    })
+    // A spawn that threw hands back no child, only a rejected `ready`.
+    if (spawn.child === undefined) void gone()
+    else {
+      children.push(spawn.child)
+      void spawn.child.exited.then(gone, gone)
+    }
+    try {
+      await spawn.ready
+    } catch (err) {
+      // A shell that exited before ready can leave its group running
+      // (`server & …; exit`), holding the port of the one the next task starts.
+      if (
+        err instanceof PersistentReadyError &&
+        err.reason === 'exited' &&
+        spawn.child !== undefined
+      )
+        await terminateChildren(() => [spawn.child!])
+      const why = err instanceof Error ? err.message : String(err)
+      const said = (heard ?? '').trimEnd()
+      throw new Error(said === '' ? why : `${why}; its output:\n${said}`)
+    }
+    heard = undefined
+    // Ready, so it spawned: only a failed spawn has no child.
+    return spawn.child!
+  }
+  const serve = (spec: ServerSpec, root: string): Promise<ReturnType<typeof Bun.spawn>> => {
+    let up = servers.get(spec.taskId)
+    if (up === undefined) {
+      up = start(spec, root)
+      servers.set(spec.taskId, up)
+      // One that never became ready is asked again by the next task.
+      up.catch(() => servers.delete(spec.taskId))
+    }
+    return up
+  }
+  return {
+    async execute(req) {
+      // A stop while a server is not yet ready ends the wait: one that never
+      // prints its `readyWhen` line held the task, and a worker's shutdown
+      // waits on its tasks before `close()` stops the servers. The aborted
+      // request then reads as one stopped before its spawn.
+      const signal = req.signal
+      const stopped =
+        signal === undefined
+          ? undefined
+          : new Promise<void>((resolve) => {
+              if (signal.aborted) resolve()
+              else signal.addEventListener('abort', () => resolve(), { once: true })
+            })
+      for (const spec of req.servers ?? []) {
+        if (signal?.aborted === true) break
+        try {
+          const up = serve(spec, req.workspaceRoot)
+          const child = await (stopped === undefined ? up : Promise.race([up, stopped]))
+          // One that crashed after it was ready serves nobody: the task ran
+          // against nothing and failed on its own "connection refused". A
+          // clean exit is a setup step that did its work (runPersistent).
+          const died = child === undefined ? null : (child.exitCode ?? child.signalCode)
+          if (died !== null && died !== 0) {
+            const code = typeof died === 'number' ? died : signalExitCode(died)
+            const text = `${spec.taskId}, which ${req.taskId} depends on, exited with code ${code} after it was ready\n`
+            req.onStderr(text)
+            return { exitCode: 1, durationMs: 0, stdout: '', stderr: text, violations: [] }
+          }
+        } catch (err) {
+          const why = err instanceof Error ? err.message : String(err)
+          const text = `${spec.taskId}, which ${req.taskId} depends on, did not start: ${why}\n`
+          // Through `onStderr` too, as a spawn failure's text goes: a worker
+          // ships only what its callbacks heard, and a dependant failed
+          // "exit 1, 0ms" with no word of why (CI, 2026-10-25).
+          req.onStderr(text)
+          return { exitCode: 1, durationMs: 0, stdout: '', stderr: text, violations: [] }
+        }
+      }
+      if (req.sandbox !== undefined) await armer?.arm()
+      const stop = req.signal
+      if (stop === undefined || req.liveChildren !== undefined) return local.execute(req)
+      // No run holds this task's children (a worker's): its stop is ours to carry out.
+      const live = new Set<ReturnType<typeof Bun.spawn>>()
+      const end = (): void => void terminateChildren(() => [...live], forwardedSignal(stop.reason))
+      stop.addEventListener('abort', end, { once: true })
+      try {
+        return await local.execute({ ...req, liveChildren: live })
+      } finally {
+        stop.removeEventListener('abort', end)
+      }
+    },
+    async rearm(list) {
+      if (armer?.armed === true) await resetSandbox()
+      armer = prepare(list)
+    },
+    async close() {
+      if (children.length > 0) await terminateChildren(() => children)
+      if (armer?.armed === true) await resetSandbox()
+    },
+  }
+}

package/src/orchestrator/local-shortcircuit.ts

@@ -44,7 +44,8 @@
 import { normalizeGlob, relPosix, span, staticPrefix } from '../util/index.js'
 import type { CacheEntry, CacheLayer, GitFilesCache } from '../cache/index.js'
 import type { TaskNode } from '../graph/index.js'
-import { deriveStableKeys, workspaceInputsReach } from './stable-keys.js'
+import { deriveStableKeys, rederiveKeys, workspaceInputsReach } from './stable-keys.js'
+import { readRunDelta, readRunKeys, runKeysToken, writeRunDelta, writeRunKeys } from './run-keys.js'
 import type { HashCache, UpfrontGroupKey } from './task-hash.js'
 import { getContext } from './remote-prefetch.js'
 
@@ -100,6 +101,8 @@ export interface ShortCircuit {
   uncachedKeys: Map<string, string>
   /** Unkeyed group id → its up-front key (`deriveStableKeys`' `groupKeys`). */
   groupKeys: Map<string, UpfrontGroupKey>
+  /** Behind a remote, each stable task the local store missed → its key: the remote may hold it. */
+  remoteAsk: Map<string, string>
 }
 
 /**
@@ -117,13 +120,46 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
   const groupKeys = new Map<string, UpfrontGroupKey>()
   const endKeys = span('stable keys')
   try {
-    stableKeys = await deriveStableKeys({ ...args, uncachedKeys, groupKeys })
+    const at = runKeysToken(args)
+    const remembered = at === undefined ? undefined : readRunKeys(args, at)
+    if (remembered !== undefined) {
+      stableKeys = remembered.stableKeys
+      for (const [id, key] of remembered.uncachedKeys) uncachedKeys.set(id, key)
+    } else {
+      // An edit moved some files tokens: the last derivation under the same
+      // graph keys again only the tasks the edit reaches.
+      const delta = at === undefined ? undefined : readRunDelta(args, at)
+      let derivation
+      if (delta !== undefined) {
+        derivation = delta.derivation
+        await rederiveKeys(args, derivation.keys, delta.dirty)
+        const keys = derivation.keys
+        stableKeys = derivation.stable.map((id) => ({
+          hash: keys.get(id)!,
+          node: args.nodes.get(id)!,
+        }))
+        for (const id of derivation.uncached) uncachedKeys.set(id, keys.get(id)!)
+      } else {
+        const keys = new Map<string, string>()
+        stableKeys = await deriveStableKeys({ ...args, uncachedKeys, groupKeys, keys })
+        derivation = {
+          keys,
+          stable: stableKeys.map((k) => k.node.id),
+          uncached: [...uncachedKeys.keys()],
+        }
+      }
+      if (at !== undefined) {
+        writeRunKeys(args, at, { stableKeys, uncachedKeys })
+        writeRunDelta(args, at, derivation)
+      }
+    }
   } catch {
     return {
       preProbed: new Map(),
       restoreTier: new Set(),
       uncachedKeys: new Map(),
       groupKeys: new Map(),
+      remoteAsk: new Map(),
     }
   } finally {
     endKeys()
@@ -134,15 +170,16 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
   const candidates = stableKeys
   const preProbed = new Map<string, ProbedEntry>()
   const restoreTier = new Set<string>()
+  const remoteAsk = new Map<string, string>()
   if (candidates.length === 0 && uncachedKeys.size === 0) {
-    return { preProbed, restoreTier, uncachedKeys, groupKeys }
+    return { preProbed, restoreTier, uncachedKeys, groupKeys, remoteAsk }
   }
 
   const keptOut = restoreTierExclusions(args.nodes, args.workspaceRoot)
   // A root-anchored output may land in a project no edge leads from, so an
   // uncached key there is derived again once the writer may have run.
   for (const id of keptOut) uncachedKeys.delete(id)
-  if (candidates.length === 0) return { preProbed, restoreTier, uncachedKeys, groupKeys }
+  if (candidates.length === 0) return { preProbed, restoreTier, uncachedKeys, groupKeys, remoteAsk }
 
   // Bounded pool over the stable candidates: probe local ONCE each. A
   // confirmed hit becomes restore-tier (unless workspace outputs disable
@@ -165,11 +202,14 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
       endProbe()
       for (const { hash, node } of candidates) {
         const hit = hits.get(hash) ?? null
-        if (hit === null && args.localOnly === true) continue
+        if (hit === null && args.localOnly === true) {
+          if (!keptOut.has(node.id)) remoteAsk.set(node.id, hash)
+          continue
+        }
         preProbed.set(node.id, { hash, hit })
         if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       }
-      return { preProbed, restoreTier, uncachedKeys, groupKeys }
+      return { preProbed, restoreTier, uncachedKeys, groupKeys, remoteAsk }
     } catch {
       // Fall through to the per-hash pool, which isolates a failing probe
       // to its own task.
@@ -182,7 +222,10 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
       const { hash, node } = candidates[next++]!
       try {
         const hit = await args.cache.get(hash, getContext(node, node.config.exec?.command ?? ''))
-        if (hit === null && args.localOnly === true) continue
+        if (hit === null && args.localOnly === true) {
+          if (!keptOut.has(node.id)) remoteAsk.set(node.id, hash)
+          continue
+        }
         preProbed.set(node.id, { hash, hit })
         if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       } catch {
@@ -193,7 +236,7 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
   }
   await Promise.all(Array.from({ length: workers }, () => pump()))
 
-  return { preProbed, restoreTier, uncachedKeys, groupKeys }
+  return { preProbed, restoreTier, uncachedKeys, groupKeys, remoteAsk }
 }
 
 /**

package/src/orchestrator/lockfile-claim.ts

@@ -15,7 +15,7 @@
 
 import path from 'node:path'
 import { rename, stat } from 'node:fs/promises'
-import { relPosix, xxh3, xxh3hex } from '../util/index.js'
+import { relPosix, UserError, xxh3, xxh3hex } from '../util/index.js'
 import type { TaskNode } from '../graph/index.js'
 import type {
   FingerprintChange,
@@ -37,7 +37,7 @@ export interface LockfileClaimOptions {
   /**
    * Root-relative files the lockfile names whose BYTES the install uses but
    * the lockfile does not pin (bun.lock's `patchedDependencies` names a patch
-   * file and records no hash of it). Their content hashes ('' when absent)
+   * file and records no hash of it). Their content hashes ('' when absent; unreadable refuses)
    * reach `digest` as `files` and join the memo's identity, so an edited
    * patch moves the key (item 1014). A directory (a `file:` dependency the
    * install copies) hashes every file under it but `node_modules` and
@@ -108,18 +108,30 @@ interface Memo {
   edges?: Record<string, LockfileImporter>
 }
 
-/** A root-relative extra file's content hash, '' when absent; a path leaving the root is never read. */
+/**
+ * A root-relative extra file's content hash, '' when absent; a path leaving
+ * the root is never read. One there but unreadable (EACCES, a symlink loop)
+ * refuses, as a settings file does: folded as '', it keyed as no file at all.
+ */
 async function hashExtra(workspaceRoot: string, rel: string): Promise<string> {
   if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) return 'outside-root'
   const abs = path.join(workspaceRoot, rel)
   try {
     return xxh3hex(await Bun.file(abs).bytes())
   } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === 'EISDIR') return hashDir(abs)
-    return ''
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'EISDIR') return hashDir(abs)
+    if (code === 'ENOENT' || code === 'ENOTDIR') return ''
+    throw unreadable(rel, err)
   }
 }
 
+function unreadable(rel: string, err: unknown): UserError {
+  return new UserError(
+    `${rel}: cannot be read (${err instanceof Error ? err.message : String(err)})`,
+  )
+}
+
 /**
  * Every file under `dir` but its `node_modules` and `.git`, as `rel\0hash`
  * lines in sorted order. Links are followed: a linked file is what a task
@@ -322,7 +334,18 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         return names
       },
       ...(options.extraFiles !== undefined
-        ? { extraFiles: (_file: string, bytes: Uint8Array) => options.extraFiles!(decode(bytes)) }
+        ? {
+            // The memo records which files these exact bytes name, for this
+            // parser: `--affected` asks on every diff, and a cold parse of
+            // a large lockfile was most of its selection's cost.
+            async extraFiles(_file: string, bytes: Uint8Array, ctx: FingerprintContext) {
+              const memoFile = path.join(ctx.cacheDir, 'lockfile-claims', `${file}.json`)
+              const memo = await readMemo(memoFile, version, claimant, xxh3hex(bytes))
+              return memo !== undefined
+                ? Object.keys(memo.extras)
+                : options.extraFiles!(decode(bytes))
+            },
+          }
         : {}),
     },
     async key(task, ctx) {
@@ -347,15 +370,22 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
  * Node's resolution walking up to the root `node_modules` (`@types/*`,
  * a config's plugins) — so a root devDependency bump that moved only the
  * root's digest replayed the old tool's output (nx#36415 class,
- * 2026-09-24). A project the lockfile has no importer for (outside the
- * workspace's `packages`) folds the root's alone; a file with neither
- * folds a constant.
+ * 2026-09-24). A project the lockfile has no importer for folds its
+ * nearest listed ancestor's, as Node resolves from that ancestor's
+ * `node_modules` (`packages/a/e2e` from `packages/a`'s): the root's alone
+ * keyed it on no bump only `a` reached. Outside every importer it folds
+ * the root's alone; a file with neither folds a constant.
  */
 function digestFor(importers: ReadonlyMap<string, string>, importer: string): string {
-  const own = importers.get(importer)
+  let dir = importer
+  while (dir !== '.' && !importers.has(dir)) {
+    const slash = dir.lastIndexOf('/')
+    dir = slash === -1 ? '.' : dir.slice(0, slash)
+  }
+  const own = importers.get(dir)
   const root = importers.get('.')
   if (own === undefined) return root ?? 'no-importer'
-  if (root === undefined || importer === '.') return own
+  if (root === undefined || dir === '.') return own
   return xxh3hex(`${own}\0${root}`)
 }
 
@@ -423,6 +453,49 @@ function decode(bytes: Uint8Array): string {
 
 // --- Reach digests -----------------------------------------------------------
 
+/**
+ * Each member of a cycle as what it is and where its edges land, by
+ * colour refinement: a member starts as its material and the child
+ * digests its edges leave the cycle for, then folds its in-cycle
+ * targets' labels until no two labels part further. npm and bun key two
+ * copies of one version alike (`a/node_modules/foo` → bar@1,
+ * `node_modules/foo` → bar@2), so by material alone two members swapping
+ * copies, in the cycle or out of it, moved nothing. Two members left with
+ * one label have the same material, reach the same children, and their
+ * in-cycle edges land on labels alike to every depth. Telling such a pair
+ * apart takes an isomorphism test; it needs a cycle where copies of one
+ * version reach alike at every step, which no swap of what one reaches
+ * produces.
+ */
+function cycleLabels(
+  g: ReachGraph,
+  members: readonly number[],
+  childOf: (w: number) => string | undefined,
+): string[] {
+  let label = new Map<number, string>()
+  for (const m of members) {
+    const out = new Set<string>()
+    for (const w of g.edges[m]!) {
+      const child = w === m ? undefined : childOf(w)
+      if (child !== undefined) out.add(child)
+    }
+    label.set(m, xxh3hex(`${g.material[m]!}\0${[...out].sort().join('\0')}`))
+  }
+  let parts = new Set(label.values()).size
+  for (;;) {
+    const next = new Map<number, string>()
+    for (const m of members) {
+      const inner = new Set<string>()
+      for (const w of g.edges[m]!) if (w !== m && label.has(w)) inner.add(label.get(w)!)
+      next.set(m, xxh3hex(`${label.get(m)!}\0${[...inner].sort().join('\0')}`))
+    }
+    label = next
+    const now = new Set(label.values()).size
+    if (now === parts) return members.map((m) => label.get(m)!)
+    parts = now
+  }
+}
+
 /** A dependency graph: one material string per node and its out-edges by index. */
 export interface ReachGraph {
   readonly material: readonly string[]
@@ -493,11 +566,18 @@ export function reachDigests(g: ReachGraph): string[] {
       // share one digest, so retargeting an edge between two of them (an
       // importer's `y@1.0.0` → `y@1.1.0` inside one cycle) moved nothing
       // and replayed a stale output (item 1013). A self-loop reaches
-      // nothing new and is left out.
-      const lines = members.map((m) => {
-        const targets = [...new Set(g.edges[m]!.filter((w) => w !== m).map((w) => g.material[w]!))]
-        return `${g.material[m]!}\0${targets.sort().join('\0')}`
-      })
+      // nothing new and is left out. A singleton's children already say
+      // where its edges land, and its line stays as it was, so an acyclic
+      // digest keeps its value.
+      const lines =
+        members.length === 1
+          ? members.map((m) => {
+              const targets = [
+                ...new Set(g.edges[m]!.filter((w) => w !== m).map((w) => g.material[w]!)),
+              ]
+              return `${g.material[m]!}\0${targets.sort().join('\0')}`
+            })
+          : cycleLabels(g, members, (w) => (comp[w] === id ? undefined : compHash[comp[w]!]!))
       let h = xxh3(`members:${members.length}`)
       for (const line of lines.sort()) h = xxh3(`${line}\n`, h)
       h = xxh3(`children:${children.size}`, h)

package/src/orchestrator/miss-save.ts

@@ -7,24 +7,27 @@
 // a later run replays. Moved out of execute-task.ts 2026-09-09 as pure
 // code motion.
 
-import { lstatSync, realpathSync, statSync } from 'node:fs'
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs'
 import path from 'node:path'
 import {
   type CacheLayer,
   type GitFilesCache,
   resolveOutputTree,
+  outputWalkTakes,
   resolveOutputs,
   resolveWorkspaceOutputs,
+  resolveWorkspaceOutputTree,
   WORKSPACE_OUTPUT_PREFIX,
 } from '../cache/index.js'
 import type { TaskNode } from '../graph/index.js'
 import {
   asTrees,
+  outputDirPrefixes,
   relPosix,
   span,
+  splitNegations,
   staticPrefix,
   taskGlob,
-  wholeSubtreePrefixes,
 } from '../util/index.js'
 import { type Logger, warnOf } from '../report/index.js'
 import type { TaskInputComponent } from '../cache/index.js'
@@ -49,8 +52,12 @@ export interface OutputDirSnapshot {
  */
 export function entryHolds(
   node: TaskNode,
+  takes: (rel: string) => boolean,
 ): (files: readonly string[], rows: ReadonlyArray<{ path: string }>) => boolean {
-  return (files, rows) => {
+  return (walked, rows) => {
+    // A root-anchored glob's snapshot walks the whole project: only what
+    // the glob takes is the entry's.
+    const files = walked.filter(takes)
     const expected = new Set(
       rows
         .map((r) => r.path)
@@ -160,12 +167,11 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
           nestedProjectDirs: a.nestedProjectDirs,
         })
   const outputFiles = tree.files
-  const wsOutputFiles =
-    a.ownWsOutputFiles ??
-    (await resolveWorkspaceOutputs({
-      workspaceRoot: a.workspaceRoot,
-      outputs: a.wsOutputs,
-    }))
+  const wsTree =
+    a.ownWsOutputFiles !== undefined
+      ? { files: a.ownWsOutputFiles, emptyDirs: [] }
+      : await resolveWorkspaceOutputTree({ workspaceRoot: a.workspaceRoot, outputs: a.wsOutputs })
+  const wsOutputFiles = wsTree.files
   endResolve()
   // The mirror of the input warning: declared outputs that resolve to
   // nothing save an empty artifact, and the next hit "restores" it —
@@ -196,7 +202,11 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
           ? ` — ${linkedOut.dir} is a symlink to ${linkedOut.target}, outside ${linkedOut.base}, and vx keeps only outputs inside it: make ${linkedOut.dir} a directory`
           : sandboxed && !grantsWrite
             ? ` — the task is sandboxed and declares no exec.sandbox.allow.write, so its writes never reached disk`
-            : ''),
+            : '') +
+        bracketLiteralHint([
+          ...a.outputs.map((g) => [node.projectDir, g] as const),
+          ...a.wsOutputs.map((g) => [a.workspaceRoot, g] as const),
+        ]),
     )
   }
   const facts: SaveFacts = {}
@@ -214,6 +224,7 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
       // The root an output symlink's target must stay inside, outputs.workspaceFiles or not.
       workspaceRoot: a.workspaceRoot,
       ...(wsOutputFiles.length > 0 ? { workspaceOutputFiles: wsOutputFiles } : {}),
+      ...(wsTree.emptyDirs.length > 0 ? { workspaceOutputDirs: wsTree.emptyDirs } : {}),
       inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
       // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
       // the contract no longer accepts one — so the invariant is enforced by
@@ -250,13 +261,13 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
     // list gets no snapshot: recording here was that same refusal (item
     // 637 deleted the fallback and nothing reddened), and the next hit
     // walks, as it did.
-    const savedDirPrefixes = wholeSubtreePrefixes(a.outputs)
+    const savedDirPrefixes = outputDirPrefixes(splitNegations(a.outputs).positive)
     if (savedDirPrefixes !== null && a.outputDirSnapshots !== undefined) {
       a.outputDirSnapshots.push({
         hash: a.hash,
         projectDir: node.projectDir,
         prefixes: savedDirPrefixes,
-        holds: entryHolds(node),
+        holds: entryHolds(node, outputWalkTakes(node.projectDir, a.outputs, a.nestedProjectDirs)),
       })
     }
   }
@@ -380,3 +391,32 @@ function realpathOrNull(p: string): string | null {
     return null
   }
 }
+
+/**
+ * The clause a "matched no files" warning gains when a glob holds an
+ * unescaped `[` and, read as a literal path, names something on disk:
+ * `app/[slug]/page.tsx` is a character class (caching.md) that matches
+ * no route, so the key stops following the file and an edit replays the
+ * old output. Only on the already-empty path; one stat per such glob, on
+ * its literal prefix up to the first segment holding another glob token.
+ */
+export function bracketLiteralHint(
+  globs: readonly (readonly [base: string, glob: string])[],
+): string {
+  let hint = ''
+  for (const [base, glob] of globs) {
+    if (glob.startsWith('!') || !/(^|[^\\])\[/.test(glob)) continue
+    const segments: string[] = []
+    for (const seg of glob.split('/')) {
+      if (/(^|[^\\])[*?{}]/.test(seg)) break
+      segments.push(seg)
+    }
+    const prefix = segments.join('/')
+    if (!/(^|[^\\])\[/.test(prefix)) continue
+    const literal = prefix.replace(/\\(.)/g, '$1')
+    if (!existsSync(path.join(base, literal))) continue
+    const escaped = glob.replace(/(^|[^\\])(?=[[\]])/g, '$1\\')
+    hint += ` — [ starts a character class and ${literal} exists: write ${escaped} to name it`
+  }
+  return hint
+}

package/src/orchestrator/options.ts

@@ -84,12 +84,12 @@ export interface RunOptions {
    */
   cacheFlags?: CacheFlags
   /**
-   * The caller asked for a remote axis by name (`--cache-policy=remote:rw`). With
-   * no cache plugin supplying a remote layer the axes are inert, and a CI
-   * job that believes it is filling a shared cache deserves one line
-   * saying it is not.
+   * The setting that asked for a remote axis by name (`'--cache-policy'` for
+   * `--cache-policy=remote:rw`), named in the warning. With no cache plugin
+   * supplying a remote layer the axes are inert, and a CI job that believes
+   * it is filling a shared cache deserves one line saying it is not.
    */
-  remoteRequested?: boolean
+  remoteRequested?: string
   /** This run's cache scope, above `VX_CACHE_SCOPE`, a plugin's and the branch's (an embedder's). */
   cacheScope?: string
   /**
@@ -205,7 +205,9 @@ export interface RunOptions {
    * never-started ones `aborted`. The seam for an embedder that owns its
    * process's lifetime instead of `handleSignals` — the watch loop aborts
    * its in-flight cycle on SIGINT/SIGTERM this way, so a cancellation
-   * never orphans a cycle's children.
+   * never orphans a cycle's children. A reason naming a signal
+   * (`'SIGINT'`, `'SIGTERM'`, `'SIGHUP'`) is a stop as vx's own handler
+   * makes one: the run records no history, only what finished.
    */
   signal?: AbortSignal
   /**