@vzn/vx 0.0.18 → 0.0.22

package/src/orchestrator/hit-restore.ts

@@ -0,0 +1,285 @@
+// What a HIT leaves behind: the outputs of a confirmed cache entry
+// materialised in the project — or proved already current and left alone —
+// the exact changed paths marked so a same-project consumer need not
+// re-spawn git, the stored stdout replayed, and the cache-hit outcome
+// built. There is ONE restore path: `executeCachedTask` and the local
+// short-circuit (a stable hit restored ahead of its deps) both come here,
+// so the two cannot drift. Stale-hit-critical: a line moved here changes
+// which bytes a green run replays. Moved out of execute-task.ts
+// 2026-09-10 as pure code motion, the mirror of miss-save.ts.
+
+import path from 'node:path'
+import type { CacheConfig } from '../config.js'
+import {
+  type CacheEntry,
+  cleanOutputPaths,
+  cleanOutputs,
+  cleanWorkspaceOutputs,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+  WORKSPACE_OUTPUT_PREFIX,
+} from '../cache/index.js'
+import type { TaskOutcome } from '../graph/index.js'
+import { asTrees, span, taskGlob, wholeSubtreePrefixes } from '../util/index.js'
+import type { ExecuteArgs } from './execute-task.js'
+
+export interface RestoreHitArgs {
+  args: ExecuteArgs
+  hash: string
+  hit: CacheEntry
+  /** `performance.now()` when the cache op (probe) started — the
+   *  user-perceived restore duration is measured from here. */
+  cacheOpStart: number
+  /** ns offset from run start for the outcome's wallclock window. */
+  taskStartNs: bigint
+}
+
+/**
+ * Materialize a confirmed cache hit: decide skip-restore, clean +
+ * restore declared outputs, mark the exact changed paths so downstream
+ * same-project tasks needn't re-spawn git, replay stored stdout, and
+ * build the cache-hit `TaskOutcome`. Extracted from `executeCachedTask`
+ * so the local short-circuit can restore a stable-key hit ahead of the
+ * schedule using the IDENTICAL logic — there is one restore path, not
+ * two that could drift.
+ */
+export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome> {
+  const { args, hash, hit, cacheOpStart, taskStartNs } = restore
+  const { node, log } = args
+  const cacheCfg: CacheConfig | undefined = node.config.cache
+  const outputs = cacheCfg?.outputs.files ?? []
+  const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
+  const anyOutputs = outputs.length > 0 || wsOutputs.length > 0
+  const dirPrefixes = wholeSubtreePrefixes(outputs)
+  const cleanArgs = {
+    projectDir: node.projectDir,
+    outputs,
+    nestedProjectDirs: args.nestedProjectDirs,
+  }
+  const wsCleanArgs = { workspaceRoot: args.workspaceRoot, outputs: wsOutputs }
+  // The two sides of an overlapping pair (item 588). An ADDITIVE task owns
+  // only its recorded rows: its glob also selects the upstream's files it
+  // adds beside, so "no strays" is not a claim it can make, and its clean
+  // takes the rows, never the glob. The UPSTREAM ignores what its
+  // dependants declare they add when it judges its own tree current — an
+  // addition below is not a stray — while its glob clean still takes them:
+  // the dependant restores or runs after it, by the edge.
+  const additive = (node.addsToOutputsOf?.length ?? 0) > 0
+  const addedGlobs = (node.outputsAddedToBy ?? [])
+    .flatMap((g) => asTrees([g]))
+    .map((g) => taskGlob(g))
+  const isAddition = (rel: string): boolean => addedGlobs.some((g) => g.match(rel))
+
+  // "Tree is already current" short-circuit — skip cleanOutputs
+  // + restoreOutputs when the on-disk state matches what this
+  // entry recorded at save time. Integrity-preserving: we
+  // require BOTH that the output-glob walk yields exactly the
+  // expected paths (no strays, no missing) AND that every file's
+  // (size, mode, mtime) matches the stored fingerprint. Any
+  // divergence falls through to a real clean + restore.
+  //
+  // The output-file fingerprints can't be batch-loaded at
+  // prepareRun time — non-leaf task hashes depend on upstream
+  // outputs that haven't been written yet, so hashes are
+  // necessarily computed mid-run. The short-circuit's batched probe
+  // loads the rows with the entry (`hit.outputRows`); only the lazy
+  // path pays one SELECT here. Either beats reading the manifest from
+  // the tar (decompress + parse) at the same point.
+  // A task with no declared outputs has nothing to clean or restore: its
+  // stdout replays from the row (`hit.stdout`), and its artifact holds
+  // only logs. Extracting it anyway cost an `exists` + a tar read per hit
+  // — 1.7 ms each on a four-task real repo whose `link` and `element`
+  // tasks declare `outputs: []` (2026-09-10, VX_TIMING).
+  let skipRestore = !anyOutputs
+  if (anyOutputs) {
+    const endRows = span('output rows')
+    const expected = hit.outputRows ?? args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
+    endRows()
+    if (expected.length > 0) {
+      // Two namespaces in the rows: bare rels are project outputs,
+      // `workspace-outputs/<rel>` rows anchor at the workspace root.
+      const projExpected = expected.filter((e) => !e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
+      const wsExpected = expected
+        .filter((e) => e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
+        .map((e) => ({ ...e, path: e.path.slice(WORKSPACE_OUTPUT_PREFIX.length) }))
+      // The directory short-circuit: for whole-subtree globs, unchanged
+      // mtimes on every directory recorded at the last save/restore prove
+      // the output SET is unchanged (a file added or removed anywhere the
+      // glob could see bumps a recorded directory), so the walk that cost
+      // 0.36 ms per warm hit is replaced by a few stats. The per-file
+      // fingerprint check below still runs; only the enumeration is skipped.
+      let setKnown = false
+      if (dirPrefixes !== null && wsOutputs.length === 0 && args.cache.outputDirsCurrent) {
+        const endDirs = span('output dirs')
+        // Loaded with the entry (batched by getMany, or with the lazy get).
+        const dirRows = hit.outputDirRows ?? []
+        // Rows are recorded for these same prefixes under this same key
+        // (the outputs are folded into it), so `covers` cannot be false
+        // today — deleting it reddens nothing (item 638). Kept: a row
+        // set that shrank would otherwise vouch for a tree it never saw,
+        // and the failure it would let through is a skipped restore.
+        const covers = dirPrefixes.every((pre) => dirRows.some((r) => r.path === pre))
+        setKnown = covers && (await args.cache.outputDirsCurrent!(node.projectDir, dirRows))
+        endDirs()
+      }
+      let actualAbs: string[]
+      let actualWsAbs: string[]
+      if (setKnown) {
+        actualAbs = projExpected.map((e) => path.join(node.projectDir, e.path))
+        actualWsAbs = []
+      } else {
+        const endGlob = span('output glob')
+        actualAbs = await resolveOutputs({
+          projectDir: node.projectDir,
+          outputs,
+          nestedProjectDirs: args.nestedProjectDirs,
+        })
+        actualWsAbs = await resolveWorkspaceOutputs({
+          workspaceRoot: args.workspaceRoot,
+          outputs: wsOutputs,
+        })
+        endGlob()
+      }
+      const setsMatch = (
+        actual: readonly string[],
+        exp: ReadonlyArray<{ path: string }>,
+      ): boolean => {
+        const expSet = new Set(exp.map((e) => e.path))
+        return actual.length === expSet.size && actual.every((r) => expSet.has(r))
+      }
+      // A stray a dependant's glob could have added is not a stray; a path
+      // this entry recorded is never dropped, even where that glob covers
+      // the whole tree (strapi's shape: both on `dist`).
+      const expectedRels = new Set(projExpected.map((e) => e.path))
+      const expectedWsRels = new Set(wsExpected.map((e) => e.path))
+      const actualRels = actualAbs
+        .map((p) => path.relative(node.projectDir, p).split(path.sep).join('/'))
+        .filter((rel) => expectedRels.has(rel) || !isAddition(rel))
+      const actualWsRels = actualWsAbs
+        .map((p) => path.relative(args.workspaceRoot, p).split(path.sep).join('/'))
+        .filter((rel) => expectedWsRels.has(rel) || !isAddition(rel))
+      const rowsPresent = (
+        actual: readonly string[],
+        exp: ReadonlyArray<{ path: string }>,
+      ): boolean => {
+        const have = new Set(actual)
+        return exp.every((e) => have.has(e.path))
+      }
+      const treeMatches = additive
+        ? rowsPresent(actualRels, projExpected) && rowsPresent(actualWsRels, wsExpected)
+        : setsMatch(actualRels, projExpected) && setsMatch(actualWsRels, wsExpected)
+      if (treeMatches) {
+        const endStat = span('output stat')
+        skipRestore =
+          (await args.cache.isOutputsCurrent(node.projectDir, projExpected)) &&
+          (await args.cache.isOutputsCurrent(args.workspaceRoot, wsExpected))
+        endStat()
+        // The walk ran and proved the tree current (rows absent, or a
+        // directory had moved — a benign touch): snapshot the directories
+        // so the next hit skips the walk.
+        if (skipRestore && !setKnown && dirPrefixes !== null) {
+          await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
+        }
+      }
+    }
+  }
+  // An entry with NO rows (its declared outputs matched nothing at save
+  // time, the warned case) is current exactly when the globs still match
+  // nothing: then the empty artifact has nothing to put back and the read
+  // of the tar is spared. A stray under the glob still falls through to
+  // the clean, as strict ownership requires (item 589).
+  if (anyOutputs && !skipRestore) {
+    const expected = hit.outputRows ?? args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
+    if (expected.length === 0) {
+      const endGlob = span('output glob')
+      const actual = await resolveOutputs({
+        projectDir: node.projectDir,
+        outputs,
+        nestedProjectDirs: args.nestedProjectDirs,
+      })
+      const actualWs = await resolveWorkspaceOutputs({
+        workspaceRoot: args.workspaceRoot,
+        outputs: wsOutputs,
+      })
+      endGlob()
+      skipRestore = actual.length === 0 && actualWs.length === 0
+    }
+  }
+  if (!skipRestore) {
+    let cleanedRels: string[] = []
+    let cleanedWsRels: string[] = []
+    if (additive) {
+      cleanedRels = hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+      await cleanOutputPaths({ projectDir: node.projectDir, rels: cleanedRels })
+      cleanedWsRels = hit.outputFiles
+        .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+        .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length))
+      await cleanOutputPaths({ projectDir: args.workspaceRoot, rels: cleanedWsRels })
+    } else {
+      if (outputs.length > 0) cleanedRels = await cleanOutputs(cleanArgs)
+      if (wsOutputs.length > 0) cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
+    }
+    await args.cache.restoreOutputs(hash, node.projectDir, args.workspaceRoot)
+    // The tree now holds this entry's bytes: stamp them for the next hit
+    // (item 886).
+    args.cache.recordOutputStamps?.(hash, node.projectDir, args.workspaceRoot)
+    // The directory snapshot behind the NEXT hit's skip-restore, taken at
+    // run end from the run's list (as the miss path does, see
+    // miss-save.ts): the restore renamed into these directories
+    // microseconds ago, inside the snapshot's racy window, so a snapshot
+    // taken here was refused and the first warm run after every restore
+    // walked its output trees — 41 of payload's 45 tasks, 14,430 files,
+    // ~75 ms of the no-op's CPU (2026-09-11). A caller with no list gets
+    // no snapshot (item 637: recording here was that same refusal).
+    if (dirPrefixes !== null && args.outputDirSnapshots !== undefined) {
+      args.outputDirSnapshots.push({ hash, projectDir: node.projectDir, prefixes: dirPrefixes })
+    }
+    // Restored outputs changed the project's tree — but on this
+    // path we know the EXACT changed paths (wiped declared
+    // outputs + the artifact's files). Record them instead of
+    // dropping the snapshot; downstream same-project tasks only
+    // re-spawn git when their input globs can actually see one of
+    // these paths. The cache-miss save path keeps the
+    // unconditional drop (an executed task may write undeclared
+    // files only git can see).
+    if (outputs.length > 0) {
+      args.gitFilesCache?.markOutputsChanged(node.projectDir, [
+        ...cleanedRels,
+        ...hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX)),
+      ])
+    }
+    if (wsOutputs.length > 0) {
+      args.gitFilesCache?.markWorkspaceOutputsChanged(args.workspaceRoot, [
+        ...cleanedWsRels,
+        ...hit.outputFiles
+          .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+          .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length)),
+      ])
+    }
+  }
+  if (hit.stdout) log.taskStdout(node, hit.stdout)
+  const status =
+    hit.exitCode !== 0 ? 'failed' : hit.source === 'remote' ? 'cache-hit-remote' : 'cache-hit'
+  // `restored` distinguishes "we just wrote files to disk" from
+  // "disk already matched the cached snapshot". Drives the
+  // "up-to-date" vs "local-cache" / "remote-cache" label in the
+  // framed block. Only meaningful when at least one output was
+  // declared — no-outputs tasks never materialize anything, so
+  // they're vacuously up-to-date.
+  const restored = !skipRestore && anyOutputs
+  return {
+    node,
+    status,
+    exitCode: hit.exitCode,
+    // What THIS run spent: probe + restore. NOT the stored exec time — see
+    // `storedDurationMs`, which is what the hit skipped.
+    durationMs: Math.round(performance.now() - cacheOpStart),
+    storedDurationMs: hit.durationMs,
+    ...(hit.cpuMs !== undefined ? { storedCpuMs: hit.cpuMs } : {}),
+    ...(hit.peakRssBytes !== undefined ? { storedPeakRssBytes: hit.peakRssBytes } : {}),
+    hash,
+    restored,
+    wallclockStartNs: taskStartNs,
+    wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+  }
+}

package/src/orchestrator/index.ts

@@ -3,12 +3,24 @@
 
 export { run, planRun } from './run.js'
 export { prepareRun, type PreparedRun } from './prepare.js'
+export {
+  loadProjects,
+  loadResolvedProjects,
+  loadWorkspacePlugins,
+  type LoadedProjects,
+  type LoadProjectsArgs,
+} from './projects.js'
 export { computeTaskHash, createHashCache, type HashCache } from './task-hash.js'
-export type { RunOptions, RunSummary } from './options.js'
+export type { HeldPersistent, RunOptions, RunSummary } from './options.js'
 // Re-surface the cache policy contract (defined in the cache module) so
 // embedders constructing RunOptions.cache and the package façade can
 // reach it without importing the cache module directly.
 export { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
+// The CLI reads a recorded exit code; the runner's convention decodes it.
+export { exitSignal } from '../exec/index.js'
+export { forwardedSignal } from './signals.js'
+// `vx cache prune` waits for a run on the workspace before it evicts.
+export { acquireRunLock } from './run-lock.js'
 export { defaultLogger, resolveOutputView } from './logger.js'
 export type { Logger, OutputView } from './logger.js'
 export type { RunPlan, PlannedTask, PlanPrediction, CacheStatus } from './plan.js'
@@ -19,6 +31,8 @@ export {
   toWireEvent,
   projectNode,
   projectOutcome,
+  outcomeWord,
+  outcomeLabel,
 } from './events.js'
 export type {
   EventBus,
@@ -36,6 +50,14 @@ export {
   LocalHistoryProvider,
   type TaskHistory,
 } from './history.js'
+export {
+  detectFlaky,
+  type FailureMode,
+  type FlakyCandidate,
+  type FlakyFinding,
+  type FlakyTask,
+  flakyTasks,
+} from './failure-mode.js'
 export {
   installPlugins,
   type CacheContext,
@@ -46,6 +68,7 @@ export {
   type PluginCommand,
   type ProjectHookContext,
   type ScheduleHookContext,
+  type AdmitContext,
   type WorkspaceHookContext,
   type InstallPluginsArgs,
   type Plugin,
@@ -53,7 +76,13 @@ export {
   type PluginHookHandlers,
   type PluginHookName,
   type PluginSetupContext,
+  type FingerprintChange,
+  type FingerprintClaim,
+  type FingerprintContext,
   type VxPlugin,
+  definePlugin,
+  type PluginHooks,
+  type PluginOrigin,
 } from './plugin.js'
 export {
   applyConfigHooks,
@@ -61,11 +90,20 @@ export {
   applyKeyHooks,
   applyProjectHooks,
   applyScheduleHooks,
+  claimedAffected,
+  fingerprintClaims,
   hasHook,
+  CACHE_LAYER_METHODS,
   resolveCache,
   resolveExecutors,
 } from './plugin-host.js'
-export { MISSING_PLUGIN_HINT } from './missing-plugin.js'
+export {
+  lockfileClaim,
+  reachDigests,
+  type LockfileClaimHooks,
+  type LockfileClaimOptions,
+  type ReachGraph,
+} from './lockfile-claim.js'
 export { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 // The bounded log-capture buffer every telemetry sink shares — see the
 // module header for why one implementation, not one per sink.
@@ -90,9 +128,6 @@ export type {
   TelemetrySink,
   TelemetrySource,
 } from './telemetry.js'
-// `diffOutputTrees` is the ONE tree-diff implementation — the verify verdict
-// and a serve's cross-machine fingerprint diff must never drift on it.
-export { diffOutputTrees } from './verify.js'
 export { deriveStableKeys } from './stable-keys.js'
 export type { DeriveStableKeysArgs, StableKey } from './stable-keys.js'
 export {
@@ -108,6 +143,7 @@ export {
   explainCacheKey as explainCacheKeyQuery,
   getInvocation,
   getRun,
+  latestRunId,
   listInvocations,
   listRuns,
   whyDidThisRerun as whyDidThisRerunQuery,
@@ -125,3 +161,4 @@ export type {
   RunSummaryRow,
   WhyDidThisRerun,
 } from './metrics.js'
+export { collectInfo, type CollectInfoOptions, type InfoFacts } from './doctor.js'

package/src/orchestrator/keyed-projects.ts

@@ -0,0 +1,89 @@
+// The projects a task's cache key answers for: K(T) in
+// docs/design/linked-sibling-reads-2026-09.md. A sandboxed task that
+// declares `cache` is granted a sibling's `node_modules` link only when its
+// key already moves with that sibling's files, and this is where "already"
+// is decided — on the graph, before any hash exists, through the same
+// selection the hash path applies (`selectFoldedDeps`).
+
+import { isGroupTask, type TaskNode } from '../graph/index.js'
+import { selectFoldedDeps, type FoldCandidate } from './upstream.js'
+
+/**
+ * A run's keyed-set lookup: for a task, the directories of every project
+ * holding an exec task whose key the task's key folds, transitively. The
+ * task itself is not counted.
+ *
+ * The fold relation is the hash path's, computed on the graph:
+ *   - an exec task folds its dependencies as its own `cache.inputs.tasks`
+ *     selects them (absent, or no `cache` at all, means all);
+ *   - a group folds every dependency (`computeGroupHash`) and folds no
+ *     files of its own;
+ *   - a persistent task has no hash on the live path, so it is folded by
+ *     no one and its own dependencies reach no key through it. (The local
+ *     classify pass does give it one — stable-keys.ts — so a key there can
+ *     move with more than this set names; never with less.)
+ *
+ * Every exec task reached contributes its project, cached or not: a key
+ * folds the task's own project files, and a task with no `cache` declares
+ * no `inputs.files`, so it folds every file of its project (inputs.ts's
+ * `DEFAULT_FILE_GLOBS`). `tests/keyed-projects.test.ts` holds that to the
+ * key itself.
+ *
+ * Lazy and memoized by task id: only a sandboxed task that executes asks,
+ * so a run of hits walks nothing, and a shared subgraph is walked once.
+ */
+export function keyedProjects(
+  nodes: ReadonlyMap<string, TaskNode>,
+): (node: TaskNode) => ReadonlySet<string> {
+  const below = new Map<string, ReadonlySet<string>>()
+  // Post-order on an explicit stack: a fold is as deep as the graph, and a
+  // recursion per edge threw `RangeError` at the 50,000 the builder takes
+  // (item 737). A frame's folded dependencies are listed when it is first
+  // reached and combined once each has its set.
+  return (root) => {
+    const stack: Array<[node: TaskNode, deps: FoldCandidate[] | undefined]> = [[root, undefined]]
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1]!
+      const [node, deps] = frame
+      if (below.has(node.id)) {
+        stack.pop()
+        continue
+      }
+      if (deps === undefined) {
+        frame[1] = folded(node, nodes)
+        for (const { node: dep } of frame[1]) if (!below.has(dep.id)) stack.push([dep, undefined])
+        continue
+      }
+      stack.pop()
+      const out = new Set<string>()
+      for (const { node: dep } of deps) {
+        if (!isGroupTask(dep)) out.add(dep.projectDir)
+        for (const dir of below.get(dep.id)!) out.add(dir)
+      }
+      below.set(node.id, out)
+    }
+    return below.get(root.id)!
+  }
+}
+
+/** The dependencies `node`'s key folds, per the hash path's rules above. */
+function folded(node: TaskNode, nodes: ReadonlyMap<string, TaskNode>): FoldCandidate[] {
+  const candidates: FoldCandidate[] = []
+  for (const id of node.deps) {
+    const dep = nodes.get(id)!
+    if (dep.config.exec?.persistent !== undefined) continue
+    candidates.push({ node: dep, unit: foldUnit(dep) })
+  }
+  if (isGroupTask(node)) return candidates
+  return selectFoldedDeps(candidates, node.config.cache?.inputs?.tasks, node.projectName, node.id)
+}
+
+/**
+ * What stands in for a dependency's hash in the dedup: equal exactly when
+ * the hashes are. An exec task's key folds its own id (`task:<id>`), so its
+ * id is enough; a group's hash is a roll-up of its members' ids and hashes
+ * with no id of its own, so two groups over the same members hash alike.
+ */
+function foldUnit(node: TaskNode): string {
+  return isGroupTask(node) ? `group|${[...node.deps].sort().join('|')}` : `task|${node.id}`
+}

package/src/orchestrator/local-shortcircuit.ts

@@ -32,16 +32,19 @@
 //   - Only STABLE-key, cacheable, local-read tasks are classified. A
 //     stable miss stays in the normal (dep-gated) schedule; an unstable
 //     task is never probed here.
-//   - If ANY task in the graph declares `cache.outputs.workspaceFiles`,
-//     no task is restore-tiered (the boundary-ignoring escape hatch
-//     could let a task write where a restore touches — a blanket
-//     conservative exclusion). Those tasks still get an exec-tier probe
-//     reuse entry so there's no double work.
+//   - A task that declares `cache.outputs.workspaceFiles` (the
+//     boundary-ignoring escape hatch) can write where a restore touches,
+//     so every task whose project directory a workspace-output glob's
+//     static prefix REACHES stays out of the restore tier, and so does
+//     every transitive dependant of one (its up-front key folds a key
+//     that is preliminary). A glob with no literal prefix reaches every
+//     project, which is the old graph-wide rule. Excluded tasks still get
+//     an exec-tier probe reuse entry so there's no double work.
 
-import { span } from '../util/index.js'
+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 } from './stable-keys.js'
+import { deriveStableKeys, workspaceInputsReach } from './stable-keys.js'
 import type { HashCache } from './task-hash.js'
 
 export interface ShortCircuitArgs {
@@ -104,22 +107,13 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
   } finally {
     endKeys()
   }
-  const candidates = stableKeys.filter(({ node }) => node.config.cache !== undefined)
+  // Every stable key is a cacheable task's: deriveStableKeys pushes only
+  // `cacheEnabled && !unstable` (item 640 deleted a second filter here and
+  // nothing reddened).
+  const candidates = stableKeys
   if (candidates.length === 0) return EMPTY
 
-  // Belt-and-suspenders for the boundary-ignoring escape hatch: a
-  // root-anchored output can land anywhere, so if ANY task declares
-  // workspace outputs a task could in principle write where a
-  // restore-tier task restores. Disable the RESTORE tier graph-wide —
-  // workspace outputs are rare bad-practice. (Probe reuse still applies,
-  // so there's no double work; those tasks just stay dep-gated.)
-  let anyWorkspaceOutputs = false
-  for (const node of args.nodes.values()) {
-    if ((node.config.cache?.outputs.workspaceFiles?.length ?? 0) > 0) {
-      anyWorkspaceOutputs = true
-      break
-    }
-  }
+  const keptOut = restoreTierExclusions(args.nodes, args.workspaceRoot)
 
   const preProbed = new Map<string, ProbedEntry>()
   const restoreTier = new Set<string>()
@@ -139,7 +133,7 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
       for (const { hash, node } of candidates) {
         const hit = hits.get(hash) ?? null
         preProbed.set(node.id, { hash, hit })
-        if (hit !== null && !anyWorkspaceOutputs) restoreTier.add(node.id)
+        if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       }
       return { preProbed, restoreTier }
     } catch {
@@ -156,7 +150,7 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
         const command = node.config.exec?.command ?? ''
         const hit = await args.cache.get(hash, { taskId: node.id, command })
         preProbed.set(node.id, { hash, hit })
-        if (hit !== null && !anyWorkspaceOutputs) restoreTier.add(node.id)
+        if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       } catch {
         // Leave this task out of preProbed → it probes lazily in
         // execute(), exactly as today.
@@ -167,3 +161,69 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
 
   return { preProbed, restoreTier }
 }
+
+/**
+ * The tasks a workspace-output declaration keeps out of the restore tier.
+ *
+ * A root-anchored output can land in any project's directory, edge or no
+ * edge (`tests/local-shortcircuit.test.ts` § "a workspace-output writer"
+ * rows, item 425), so the question is not who depends on the writer but
+ * WHERE it can write: each declared glob's static prefix is tested for
+ * reach against every project directory, and against every task's own
+ * `workspaceFiles` inputs, with the ancestor-or-equal relation
+ * `workspaceInputsReach` already uses. A prefix that is the root reaches
+ * everything — the graph-wide rule this replaced (item 584). Exclusion then
+ * follows the edges DOWN: a dependant's up-front key folds an excluded
+ * task's key, which is preliminary, so it cannot restore early either.
+ * Cost: one pass over the nodes, no filesystem.
+ */
+function restoreTierExclusions(nodes: Map<string, TaskNode>, workspaceRoot: string): Set<string> {
+  const prefixes: string[] = []
+  let everything = false
+  for (const node of nodes.values()) {
+    for (const raw of node.config.cache?.outputs.workspaceFiles ?? []) {
+      // No negation to skip: the schema refuses '!' in output globs
+      // (`validateWorkspaceGlobs`), so the `continue` that stood here
+      // guarded a shape no config can carry (item 640).
+      const glob = normalizeGlob(raw)
+      const prefix = staticPrefix(glob)
+      if (prefix === '.' || prefix === '' || prefix === '/') everything = true
+      else prefixes.push(prefix.replace(/^\.\//, ''))
+    }
+  }
+  const out = new Set<string>()
+  if (everything) {
+    for (const id of nodes.keys()) out.add(id)
+    return out
+  }
+  if (prefixes.length === 0) return out
+  const reaches = (dir: string): boolean =>
+    dir === '' ||
+    dir === '.' ||
+    prefixes.some((p) => p === dir || p.startsWith(`${dir}/`) || dir.startsWith(`${p}/`))
+  const dependants = new Map<string, string[]>()
+  for (const node of nodes.values()) {
+    const dir = relPosix(workspaceRoot, node.projectDir)
+    const wsInputs = node.config.cache?.inputs?.workspaceFiles ?? []
+    if (reaches(dir) || (wsInputs.length > 0 && workspaceInputsReach(wsInputs, prefixes))) {
+      out.add(node.id)
+    }
+    for (const dep of node.deps) {
+      const list = dependants.get(dep)
+      if (list === undefined) dependants.set(dep, [node.id])
+      else list.push(node.id)
+    }
+  }
+  // Up the dependant edges on an explicit stack: a chain is as deep as the
+  // graph, and a recursion per edge threw `RangeError` at the 50,000 the
+  // builder takes (item 737).
+  const stack = [...out]
+  while (stack.length > 0) {
+    for (const up of dependants.get(stack.pop()!) ?? []) {
+      if (out.has(up)) continue
+      out.add(up)
+      stack.push(up)
+    }
+  }
+  return out
+}