@vzn/vx 0.0.16 → 0.0.18

package/src/graph/task-graph.ts

@@ -23,8 +23,8 @@ export interface TaskNode {
   /** Ids of tasks that must complete before this one runs. */
   deps: string[]
   /**
-   * True for the tasks the user actually asked for (via cwd, `-r`, `-F`,
-   * or `pkg#task`). False for dependencies pulled in by `dependsOn`
+   * True for the tasks the user actually asked for (via cwd, `--all`,
+   * `--filter`, or `pkg#task`). False for deps pulled in by `dependsOn`
    * expansion. Used by the orchestrator to scope `forwardArgs` so trailing
    * CLI args don't leak into upstream tasks the user didn't address.
    */
@@ -38,12 +38,38 @@ export interface TaskNode {
    * them `requested`, so `forwardArgs` scoping is unaffected.
    */
   surfaced?: boolean
+  /**
+   * Extra cache-key material from plugins' `key` stage, as sorted
+   * `[name, value]` pairs; set by `prepareRun`, folded by `Cache.key`.
+   * Absent when no plugin declares the stage.
+   */
+  keyParts?: ReadonlyArray<readonly [name: string, value: string]>
 }
 
 export function taskId(project: string, task: string): string {
   return `${project}#${task}`
 }
 
+/**
+ * The inverse of `taskId`. Splits on the FIRST `#`, so a task name that itself
+ * contains one round-trips: `taskId('a', 'b#c')` → `'a#b#c'` → `['a', 'b#c']`.
+ *
+ * This exists because it kept being written by hand as `id.split('#', 2)`,
+ * which is NOT the inverse — it discards everything after the second segment,
+ * so `'a#b#c'` reads back as task `'b'`. Six call sites had that form while
+ * `parseDependencySpec` (the surface that decides what actually runs) has
+ * always split on the first `#`, so the query layer and the graph disagreed
+ * about the identity of the same task: a lookup either found nothing or, worse,
+ * answered with a different task's history.
+ *
+ * A `#`-containing task name is legal and pinned elsewhere in the suite, so
+ * this is reachable rather than theoretical.
+ */
+export function splitTaskId(id: string): [project: string, task: string] {
+  const i = id.indexOf('#')
+  return i < 0 ? [id, ''] : [id.slice(0, i), id.slice(i + 1)]
+}
+
 /**
  * A task is a "group" if it has no `exec` — it exists only to chain
  * `dependsOn` (an umbrella for `vx run ci`). Group tasks:
@@ -134,16 +160,54 @@ export function expandRequested(
     if (idx >= 0) {
       const project = spec.slice(0, idx)
       const task = spec.slice(idx + 1)
-      if (projects.get(project)?.config.tasks?.[task]) push(project, task)
+      if (declaresTask(projects, project, task)) push(project, task)
       continue
     }
     for (const name of candidates) {
-      if (projects.get(name)?.config.tasks?.[spec]) push(name, spec)
+      if (declaresTask(projects, name, spec)) push(name, spec)
     }
   }
   return out
 }
 
+/** Shared by `expandRequested` + `unresolvedRequests` so the two can't drift. */
+function declaresTask(projects: Map<string, ProjectEntry>, project: string, task: string): boolean {
+  return projects.get(project)?.config.tasks?.[task] !== undefined
+}
+
+/**
+ * The requested specs `expandRequested` silently dropped — each one
+ * matched NO project, so nothing it asked for will run.
+ *
+ * A bare name matching only SOME projects is normal (sparse tasks across
+ * a workspace) and never reported. An empty `candidates` scope is also
+ * never reported: that is the legitimate "nothing selected" outcome
+ * (`--affected` with nothing changed), not a typo — the CLI's selection
+ * layer owns that message.
+ *
+ * Deduped so `vx run x x` names `x` once.
+ */
+export function unresolvedRequests(
+  tasks: readonly string[],
+  candidates: readonly string[],
+  projects: Map<string, ProjectEntry>,
+): string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const spec of tasks) {
+    if (seen.has(spec)) continue
+    const idx = spec.indexOf('#')
+    const resolved =
+      idx >= 0
+        ? declaresTask(projects, spec.slice(0, idx), spec.slice(idx + 1))
+        : candidates.length === 0 || candidates.some((name) => declaresTask(projects, name, spec))
+    if (resolved) continue
+    seen.add(spec)
+    out.push(spec)
+  }
+  return out
+}
+
 export interface BuildGraphOptions {
   projects: Map<string, ProjectEntry>
   packageGraph: PackageGraph
@@ -268,8 +332,14 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         // AT LEAST ONE matching task and it receives edges to ALL its
         // matches — holder-ness is about declaration, so a holder still
         // stops the walk even when every match is --excludeDependencies'd.
+        //
+        // The declaring project seeds `visited`: package graphs may legally
+        // contain cycles (the common "b devDepends on a for its tests"
+        // shape), and a cycle walks the frontier straight back to the
+        // origin. Mirrors the self-pattern rule below — a task can never
+        // depend on itself.
         const re = isTaskPattern(spec.task) ? compileTaskPattern(spec.task) : null
-        const visited = new Set<string>()
+        const visited = new Set<string>([projectName])
         const frontier = [...packageGraph.directDeps(projectName)]
         while (frontier.length > 0) {
           const target = frontier.pop()!
@@ -320,10 +390,154 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
   }
 
   detectCycle(nodes)
+  detectOutputCollisions(nodes)
   return nodes
 }
 
-function detectCycle(nodes: Map<string, TaskNode>): void {
+/** A glob with no wildcard — it names exactly one path. */
+function isLiteralGlob(g: string): boolean {
+  return g.search(/[*?[\]]/) === -1
+}
+
+/**
+ * True only when two output globs PROVABLY select an overlapping set.
+ *
+ * Deliberately conservative, because the caller REFUSES the run: a false
+ * positive breaks a build that works today, which is worse than the defect
+ * being caught. So the three cases are exactly the ones that can be decided
+ * without a general glob-intersection algorithm:
+ *
+ *   both literal    — equal paths
+ *   literal vs glob — ask the glob whether it matches the literal (exact)
+ *   both globs      — only identical strings; anything else is undecided
+ *                     here and deliberately allowed through
+ *
+ * The rejected alternative was comparing each glob's static prefix. It is
+ * cheaper and catches more, but it is UNSOUND for a refusal — measured:
+ * `dist/vx-*` and `dist/other.txt` share the prefix `dist` while matching
+ * disjoint sets, so a prefix check refuses a legitimate config. (vx's own
+ * `build.bun.*` tasks escape only because they declare distinct literals.)
+ */
+function outputsOverlap(a: string, b: string): boolean {
+  if (isLiteralGlob(a) && isLiteralGlob(b)) return a === b
+  if (isLiteralGlob(a)) return new Bun.Glob(b).match(a)
+  if (isLiteralGlob(b)) return new Bun.Glob(a).match(b)
+  return a === b
+}
+
+/**
+ * Refuse a graph in which two tasks declare overlapping outputs.
+ *
+ * vx cleans a task's declared outputs before it runs AND before a cache-hit
+ * restore, so that the tree ends byte-identical to the cached artifact. That
+ * makes output ownership STRICT — and two tasks claiming the same path
+ * silently destroy each other's work, in whichever order they happen to run,
+ * while the run reports success. It is data loss with a green summary.
+ *
+ * This is a hazard vx CREATED: Turbo restores additively and cannot hit it,
+ * which is why no Turbo test surfaces it and why the parity research had to
+ * reproduce it end to end.
+ *
+ * Scope follows the two namespaces' reach. `outputs.files` is
+ * project-relative, so only tasks in the SAME project can collide;
+ * `outputs.workspaceFiles` is anchored at the workspace root and ignores
+ * project boundaries by design, so ANY two tasks can. No cache key changes —
+ * this only refuses a graph that was already destroying files.
+ */
+function detectOutputCollisions(nodes: Map<string, TaskNode>): void {
+  // INDEX FIRST, then compare — never all-pairs over the graph. A naive
+  // pairwise loop that filters by project INSIDE the loop is quadratic in the
+  // whole graph: measured 1.6 SECONDS at this project's stated target of 1000
+  // projects x 10 tasks, on every run, against a ~120ms warm run. (Same shape
+  // as the scheduler's priority closure, which took 8.5s on a 1090-package
+  // repo before it was rewritten.)
+  //
+  // Both namespaces have a much smaller natural domain:
+  //   files          — project-relative, so only same-project tasks can
+  //                    collide. Bucketing makes this O(sum of k^2) over
+  //                    per-project task counts, and k is single digits.
+  //   workspaceFiles — root-anchored and boundary-free, so any two tasks can
+  //                    collide — but only tasks that DECLARE it participate,
+  //                    and that set is nearly always empty.
+  const byProject = new Map<string, TaskNode[]>()
+  const wsDeclarers: TaskNode[] = []
+  for (const n of nodes.values()) {
+    const outs = n.config.cache?.outputs
+    if ((outs?.files?.length ?? 0) > 0) {
+      const bucket = byProject.get(n.projectName)
+      if (bucket) bucket.push(n)
+      else byProject.set(n.projectName, [n])
+    }
+    if ((outs?.workspaceFiles?.length ?? 0) > 0) wsDeclarers.push(n)
+  }
+
+  for (const bucket of byProject.values()) {
+    for (let i = 0; i < bucket.length; i++) {
+      for (let j = i + 1; j < bucket.length; j++) {
+        const a = bucket[i]!
+        const b = bucket[j]!
+        collide(a, b, a.config.cache?.outputs.files, b.config.cache?.outputs.files, 'files')
+      }
+    }
+  }
+  for (let i = 0; i < wsDeclarers.length; i++) {
+    for (let j = i + 1; j < wsDeclarers.length; j++) {
+      const a = wsDeclarers[i]!
+      const b = wsDeclarers[j]!
+      collide(
+        a,
+        b,
+        a.config.cache?.outputs.workspaceFiles,
+        b.config.cache?.outputs.workspaceFiles,
+        'workspaceFiles',
+      )
+    }
+  }
+}
+
+/**
+ * A `remote: 'only'` task never materialises its outputs on THIS machine —
+ * execute-task turns off both the read and the write axis for it, so there is
+ * no probe, no restore, no output clean and no local save. The collision
+ * hazard is entirely about local cleaning ("whichever runs second DELETES the
+ * other's output"), so a pair including one of these cannot exhibit it: there
+ * is nothing of its on disk to delete, and it deletes nothing of anyone's.
+ *
+ * Found while trying to give two projects their own install-as-an-action:
+ * both legitimately capture the workspace-root `node_modules` under a
+ * hoisting package manager, and the refusal fired on a pair that cannot
+ * exhibit the hazard. That particular layout was abandoned for an unrelated
+ * reason (identical definitions still get different cache keys), so this is
+ * not load-bearing today — it is a refusal narrowed to what it can prove,
+ * which this file's header asks for explicitly.
+ */
+function neverWritesLocally(n: TaskNode): boolean {
+  return n.config.exec?.remote === 'only'
+}
+
+function collide(
+  a: TaskNode,
+  b: TaskNode,
+  aGlobs: readonly string[] | undefined,
+  bGlobs: readonly string[] | undefined,
+  field: 'files' | 'workspaceFiles',
+): void {
+  if (neverWritesLocally(a) || neverWritesLocally(b)) return
+  for (const ga of aGlobs ?? []) {
+    for (const gb of bGlobs ?? []) {
+      if (!outputsOverlap(ga, gb)) continue
+      throw new UserError(
+        `${a.id} and ${b.id} both declare the output ${JSON.stringify(ga)}` +
+          (ga === gb ? '' : ` / ${JSON.stringify(gb)}`) +
+          ` in cache.outputs.${field} — vx cleans a task's declared outputs before it runs and ` +
+          `before a cache-hit restore, so whichever of these runs second DELETES the other's ` +
+          `output and the run still reports success. Give each task its own output path.`,
+      )
+    }
+  }
+}
+
+export function detectCycle(nodes: Map<string, TaskNode>): void {
   // Iterative DFS over dense-indexed colors. Recursion + `Map<string,
   // number>` worked, but deep workspaces (long chains of `dependsOn`)
   // can blow V8's frame budget, and per-node Map lookups dominate the

package/src/index.ts

@@ -9,7 +9,14 @@
 export { VERSION } from './version.js'
 
 // Clean error type — user-input failures print a message without a stack.
-export { UserError } from './util/index.js'
+// `clampInt` and `parseDecimalInt` ride along for the same reason the status
+// predicates do: without them on the façade an integration package writes its
+// own, and both had already happened. A bounds helper whose floor is
+// load-bearing (a fractional SQL LIMIT is a datatype mismatch, not a smaller
+// page) should have one implementation — and so should the ONE strict integer
+// parser, whose entire purpose is that `Number()` silently accepts `0x10` and
+// `1e3` at a boundary where a typo must be an error, not a different number.
+export { clampInt, parseDecimalInt, parseSize, UserError, isUserError } from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {
@@ -34,15 +41,22 @@ export { defineProject, defineWorkspace } from './config.js'
 // on the stability gate); `captureGitContext`/`captureWorkspaceIdentity`
 // give agents + the submitter identity before/without a telemetry run.
 export { run, planRun, prepareRun } from './orchestrator/index.js'
+// The per-task duration history a `schedule` plugin learns from (see
+// src/plugins/schedule-history — core's own plugins import core only via
+// this façade, which is what put these here).
+export { EmptyHistoryProvider, LocalHistoryProvider } from './orchestrator/index.js'
+export type { HistoryProvider, HistoryTable, TaskHistory } from './orchestrator/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
 export { computeTaskHash, createHashCache, deriveStableKeys } from './orchestrator/index.js'
 export type { DeriveStableKeysArgs, HashCache, StableKey } from './orchestrator/index.js'
 export {
+  captureDefaultBranch,
   captureGitContext,
+  captureHostContext,
   captureWorkspaceIdentity,
-  resolveCacheScope,
+  detectCi,
 } from './orchestrator/index.js'
-export type { GitContext, WorkspaceIdentity } from './orchestrator/index.js'
+export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './orchestrator/index.js'
 export { FULL_CACHE_POLICY, parseCachePolicy } from './orchestrator/index.js'
 export type {
   CachePolicy,
@@ -52,7 +66,17 @@ export type {
   RunSummary,
 } from './orchestrator/index.js'
 export { defaultLogger, resolveOutputView } from './orchestrator/index.js'
-export { buildTaskGraph, expandRequested, isGroupTask, markSurfacedDeps } from './graph/index.js'
+// `splitTaskId` is on the façade because the alternative is what happened:
+// with only `taskId()` to JOIN an id and nothing exported to SPLIT one,
+// consumers roll their own `split('#', 2)` and drift from the graph, which
+// splits on the FIRST '#'.
+export {
+  buildTaskGraph,
+  expandRequested,
+  isGroupTask,
+  markSurfacedDeps,
+  splitTaskId,
+} from './graph/index.js'
 export type {
   OutputFingerprint,
   TaskNode,
@@ -86,7 +110,7 @@ export type { CacheLayer, RemoteCacheLayer, RunRecord, InvocationRecord } from '
 // parser in a sibling package would drift), and the loader chain
 // (`loadWorkspace` → `listProjectMetas` → `loadProjectConfig`) is the same
 // one `vx show` uses. Workspace's `listProjects` re-exports as
-// `listProjectMetas` — the bare name belongs to the metrics query below.
+// `listProjectMetas` (the bare name once belonged to a metrics query).
 export { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from './workspace/index.js'
 export { readLockfile, LOCKFILE_NAME } from './workspace/index.js'
 export type { Lockfile, LockfileEntry } from './workspace/index.js'
@@ -98,58 +122,82 @@ export {
 export type { ProjectMeta } from './workspace/index.js'
 
 // Plugin API — the run-level extension points. Behavior capabilities
-// (backend / cache) change WHAT/HOW work runs; the observe-only `telemetry`
+// (executor / cache) change WHAT/HOW work runs; the observe-only `telemetry`
 // capability is the canonical data-export path and cannot change behavior.
 // A plugin is declared in vx.workspace.ts via defineWorkspace({ plugins }).
 // See docs/design/observability-architecture-2026-06.md.
 export type {
   VxPlugin,
-  EventSink,
-  BackendContext,
   CacheContext,
-  EventSinkContext,
+  ExecutorContext,
+  CommandContext,
+  GraphHookContext,
+  KeyHookContext,
+  PluginCommand,
+  ProjectHookContext,
+  ScheduleHookContext,
+  WorkspaceHookContext,
   PluginSetupContext,
 } from './orchestrator/index.js'
+// Process primitives — what an executor plugin builds on. `@vzn/vx/plugins/local-executor`
+// is the reference implementation and imports exactly these.
+export { runCommand, runSandboxed } from './exec/index.js'
+// The per-task execution contract a plugin's `executor` capability returns.
+export type {
+  ExecuteRequest,
+  ExecuteResult,
+  ExecuteSandbox,
+  ResolvedSandboxConfig,
+  TaskExecutor,
+  TaskPlacement,
+} from './exec/index.js'
 
 // Telemetry — THE canonical, versioned data-export contract every exporter
 // (an OTel exporter, an HTTP sink, or any third-party consumer) reads. A sink implements TelemetrySink and is
 // returned from VxPlugin.telemetry(); it receives immutable records and holds
 // no run handle (observe-only by construction).
-export { TELEMETRY_SCHEMA_VERSION, deriveCacheSource } from './orchestrator/index.js'
+// `isPassStatus` / `isCacheHit` are on the façade for the reason the sweep
+// that added them found: with only the raw `TaskStatus` union exported, every
+// consumer rolls its own Set of status literals — and a Set has no
+// compile-time tripwire when the union gains a member, so it silently answers
+// "no" for the new one. `TASK_STATUSES` is the union at runtime, for a
+// consumer that needs the list rather than the predicate.
+// `escapeMarkdownCell` is on the façade for the same demonstrated need: a
+// plugin that renders a run as a markdown table takes the same unvalidated
+// task names core does, and the cloud job summary shipped without the escape.
+export {
+  assembleRunSummary,
+  escapeMarkdownCell,
+  TELEMETRY_SCHEMA_VERSION,
+  deriveCacheSource,
+  isCacheHit,
+  isPassStatus,
+  TASK_STATUSES,
+} from './orchestrator/index.js'
+// `TaskLogBuffer` is on the façade on the same demonstrated need: EVERY
+// telemetry sink that ships build output has to bound it, and the retention
+// rules (per-task tail, per-run budget, failures never evicted by successes,
+// a hit's bytes belong to the run that executed) are a decision, not an
+// implementation detail. Two sinks rolling their own is how they fork.
+export { LOG_WIRE_VERSION, TaskLogBuffer } from './orchestrator/index.js'
 export type {
   CacheSource,
   RunContextRecord,
   RunSummaryRecord,
+  TaskLogBundle,
+  TaskLogEntry,
   TaskTelemetry,
   TelemetryContext,
   TelemetryRecord,
   TelemetrySink,
 } from './orchestrator/index.js'
 
-// The submitter wire contract + backend interface (the `backend`
-// capability's currency) and the serializable event projection.
-export {
-  optionsToRequest,
-  requestToOptions,
-  projectNode,
-  projectOutcome,
-  createWireRenderer,
-} from './orchestrator/index.js'
-export type {
-  RunBackend,
-  RunRequest,
-  RunResult,
-  ClientMessage,
-  ServerMessage,
-} from './orchestrator/index.js'
+// The serializable event projection.
+export { projectNode, projectOutcome } from './orchestrator/index.js'
+export type { RunResult } from './orchestrator/index.js'
 
 // Event bus + wire form — adapters (otel-bridge, custom subscribers) ride this.
-export {
-  createEventBus,
-  wireForwarder,
-  toWireEvent,
-  createVxSurface,
-} from './orchestrator/index.js'
+export { createEventBus, wireForwarder, toWireEvent } from './orchestrator/index.js'
 export type {
   EventBus,
   RunEvent,
@@ -159,64 +207,14 @@ export type {
   OutcomeView,
 } from './orchestrator/index.js'
 
-// The JSON-RPC 2.0 wire envelope — an out-of-process serve/agent speaks this framing.
-export {
-  clientMessageToEnvelope,
-  decodeEnvelope,
-  encodeForNDJSON,
-  encodeForSSE,
-  encodeForWS,
-  ENVELOPE_ERRORS,
-  envelopeToClientMessage,
-  envelopeToServerMessage,
-  isEnvelope,
-  isNotification,
-  isRequest,
-  makeError,
-  makeNotification,
-  makeRequest,
-  makeResponse,
-  serverMessageToEnvelope,
-  WIRE_CHANNELS,
-  WIRE_PROTOCOL_VERSION,
-} from './orchestrator/index.js'
-export type {
-  Envelope,
-  ErrorResponse,
-  Notification,
-  WireRequest,
-  WireResponse,
-  WireChannel,
-} from './orchestrator/index.js'
-
-// Metrics / analytics query layer over cache.db — a service plugin's HTTP
-// surface reads from these (the queries stay in core; a serve exposes them over HTTP).
+// Run-history queries over cache.db — what `vx why` / `vx last` read. An
+// out-of-process surface (an MCP server, a dashboard plugin) reads the same.
 export {
   cacheKeyDiff,
-  compareRuns,
   explainCacheKeyQuery,
-  getBottlenecks,
-  getCacheBreakdown,
-  getCacheSavings,
-  getCacheStatsSql,
-  getFlakiestTasks,
-  getHistory,
-  getHitRateSplit,
   getInvocation,
-  getParallelismHistory,
-  getPeriodComparison,
-  getPrunableEntries,
-  getRecentFailures,
-  getRegressions,
   getRun,
-  getRunHeatmap,
-  getRunTrends,
-  getStorageGrowth,
-  getTaskDetail,
-  getTopTimeBurners,
-  listCacheEntries,
   listInvocations,
-  listProjects,
   listRuns,
   whyDidThisRerunQuery,
 } from './orchestrator/index.js'

package/src/orchestrator/deferred-outputs.ts

@@ -0,0 +1,144 @@
+// The run-scoped registry of tasks whose outputs were left in the remote
+// store (`--download=none`), and the lazy materialisation that fetches
+// them when a locally-placed task turns out to need them.
+//
+// See docs/design/download-policy-cas-cache-2026-08.md §5. The two
+// invariants that keep this from becoming a second cache:
+//
+//   - A deferred task writes NOTHING locally — no artifact, no rows. The
+//     remote store (the executor's own record) is the entry.
+//   - Materialisation CONVERGES: after the bytes land, core runs the
+//     ordinary `cache.save`, so the machine is indistinguishable from a
+//     `--download=all` run and every later reader (get, prune, verify,
+//     metrics) sees one entry shape, not two.
+
+import {
+  cleanOutputs,
+  resolveOutputs,
+  type CacheLayer,
+  type GitFilesCache,
+} from '../cache/index.js'
+import type { TaskNode } from '../graph/index.js'
+
+export interface DeferredEntry {
+  /** Fetches this task's outputs onto disk. At-most-once by construction. */
+  materialize: () => Promise<void>
+  hash: string
+  entry: { taskId: string; command: string; durationMs: number; stdout: string }
+}
+
+export interface DeferredOutputsArgs {
+  nodes: Map<string, TaskNode>
+  cache: CacheLayer
+  workspaceRoot: string
+  nestedDirsByProject: Map<string, string[]>
+  gitFilesCache?: GitFilesCache
+  /** False when the run's policy writes no local entries. */
+  localWrite: boolean
+}
+
+export class DeferredOutputs {
+  private readonly entries = new Map<string, DeferredEntry>()
+  private readonly inflight = new Map<string, Promise<void>>()
+
+  constructor(private readonly args: DeferredOutputsArgs) {}
+
+  register(taskId: string, entry: DeferredEntry): void {
+    this.entries.set(taskId, entry)
+  }
+
+  /**
+   * Task ids whose outputs are still remote — the summary's list. An entry
+   * is removed only when materialisation SUCCEEDS, so this covers both
+   * "nothing needed them" and "fetching them failed"; the second is
+   * precisely when a user needs to be told the tree is not current, and an
+   * `inflight` filter here used to hide it.
+   */
+  pending(): string[] {
+    return [...this.entries.keys()].sort()
+  }
+
+  get size(): number {
+    return this.entries.size
+  }
+
+  /**
+   * Materialise every deferred producer in `node`'s TRANSITIVE dependency
+   * closure. Which upstream bytes a command reads is unknowable — that is
+   * what `dependsOn` declares — so the whole closure is taken. Each
+   * producer materialises at most once per run (memoised on the promise,
+   * so two concurrent consumers share one fetch), and they run
+   * concurrently.
+   *
+   * A failure is the CONSUMER's failure: executing against a
+   * half-materialised tree is the stale-input class with extra steps, so
+   * this throws and the caller fails the task naming the producer.
+   */
+  async materializeFor(node: TaskNode): Promise<void> {
+    const needed: string[] = []
+    const seen = new Set<string>()
+    const walk = (id: string): void => {
+      for (const dep of this.args.nodes.get(id)?.deps ?? []) {
+        if (seen.has(dep)) continue
+        seen.add(dep)
+        if (this.entries.has(dep)) needed.push(dep)
+        walk(dep)
+      }
+    }
+    walk(node.id)
+    if (needed.length === 0) return
+    await Promise.all(needed.map((id) => this.materializeOne(id)))
+  }
+
+  private materializeOne(taskId: string): Promise<void> {
+    const existing = this.inflight.get(taskId)
+    if (existing !== undefined) return existing
+    const started = this.run(taskId)
+    this.inflight.set(taskId, started)
+    return started
+  }
+
+  private async run(taskId: string): Promise<void> {
+    const entry = this.entries.get(taskId)!
+    const producer = this.args.nodes.get(taskId)!
+    const outputs = producer.config.cache?.outputs.files ?? []
+    const nestedProjectDirs = this.args.nestedDirsByProject.get(producer.projectName) ?? []
+    const cleanArgs = { projectDir: producer.projectDir, outputs, nestedProjectDirs }
+
+    // Mirror `restoreHit`'s sequencing so the two paths cannot drift: wipe
+    // the declared outputs, write, then tell the git snapshot what moved.
+    if (outputs.length > 0) {
+      const cleaned = await cleanOutputs(cleanArgs)
+      this.args.gitFilesCache?.markOutputsChanged(producer.projectDir, cleaned)
+    }
+    try {
+      await entry.materialize()
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      throw new Error(
+        `could not fetch deferred outputs of ${taskId}: ${msg} — re-run it with --force, or use --download=all`,
+      )
+    }
+    const outputFiles = await resolveOutputs({
+      projectDir: producer.projectDir,
+      outputs,
+      nestedProjectDirs,
+    })
+    this.args.gitFilesCache?.markOutputsChanged(
+      producer.projectDir,
+      outputFiles.map((f) => f.slice(producer.projectDir.length + 1)),
+    )
+    // Convergence: an ordinary entry, so the next run is a plain local hit
+    // and nothing downstream learns a second shape. Policy still governs —
+    // a run that writes no local entries writes none here either.
+    if (this.args.localWrite) {
+      await this.args.cache.save({
+        hash: entry.hash,
+        projectDir: producer.projectDir,
+        outputFiles,
+        entry: entry.entry,
+      })
+    }
+    this.entries.delete(taskId)
+  }
+}