@vzn/vx 0.0.18 → 0.0.22

package/src/index.ts

@@ -3,20 +3,37 @@
 // This is the stable cross-package contract — any plugin or integration
 // package imports everything it needs from here via the bare
 // `'@vzn/vx'` specifier (never a deep `src/...` path). The surface is pinned
-// by tests/package-boundaries.test.ts; a widening updates that snapshot
-// deliberately. See docs/design/core-cloud-split-2026-06.md §3.5.
+// by tests/package-boundaries.unsafe.test.ts; a widening updates that snapshot
+// deliberately. The boundary law: docs/architecture.md § Repository shape.
 
 export { VERSION } from './version.js'
 
 // Clean error type — user-input failures print a message without a stack.
-// `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'
+// `clampInt` rides along for the same reason the status predicates do:
+// without it on the façade an integration package writes its own, and that
+// 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.
+export { clampInt, UserError, isUserError } from './util/index.js'
+// "Did you mean": the hint core's own verbs give for a near-miss name, for a
+// plugin verb to give the same one.
+export { nearMatches } from './util/index.js'
+// Every hook a plugin may fill, in pipeline order — the one list the
+// loader, the host and `vx info` read; exported so a doc pin outside core
+// (the site's guides) holds its tables to the same list.
+export { PLUGIN_HOOKS, type PluginHook } from './config.js'
+// The workspace doctor's facts (`vx info`), for a host that answers the
+// same question over another surface — `@vzn/vx-mcp`'s `getWorkspaceInfo`.
+export { collectInfo, type CollectInfoOptions, type InfoFacts } from './orchestrator/index.js'
+// The machine as this process may use it — cores and memory capped by the
+// cgroup a container runs under. Core's default worker count reads the
+// first; a policy that budgets memory (`@vzn/vx-schedule-history`) reads
+// the second, so the cgroup walk has one implementation.
+export { machineMemoryBytes, machineParallelism } from './util/index.js'
+// How core reads a task glob — its spelling, and which characters are
+// wildcards (`[` `]` are not; item 667) — for a plugin that turns declared
+// outputs into something else (`@vzn/vx-reapi`'s literal `output_paths`).
+export { isLiteralPattern, normalizeGlob } from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {
@@ -28,36 +45,31 @@ export type {
   CacheConfig,
   CacheInputs,
   CacheOutputs,
-  ResourcesConfig,
   SandboxConfig,
-  SandboxNetworkConfig,
+  SandboxGrants,
+  SandboxDenials,
 } from './config.js'
 export { defineProject, defineWorkspace } from './config.js'
+export { definePlugin } from './orchestrator/index.js'
 
-// Programmatic engine API (run / plan / prepare) + the graph primitives a
-// distribution submitter/agent reasons over + the cache-key hashing seam.
-// `deriveStableKeys` is THE shared stable-key derivation (remote-prefetch,
-// the local short-circuit, and the distributed submitter must never drift
-// on the stability gate); `captureGitContext`/`captureWorkspaceIdentity`
-// give agents + the submitter identity before/without a telemetry run.
+// Programmatic engine API: run / plan / prepare (docs/cli.md § Programmatic
+// API). The graph primitives, the cache-key hashing seam and the git / host
+// context capture used to sit beside these for a distributed submitter that
+// left the repo (2026-08); they went with it (2026-09-10) — a seam with no
+// consumer is re-added when one appears, shaped by its use.
 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'
+// The per-task duration history a `schedule` plugin learns from
+// (`@vzn/vx-schedule-history` does; a plugin package reaches core only
+// through this façade, which is what put these here).
+export { 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,
-  detectCi,
-} from './orchestrator/index.js'
+// `planRun` returns these, and an embedder that cannot NAME a return type
+// cannot hold it: `run` and `prepareRun` both had theirs here from the
+// start, so the omission read as "planRun is not really public" while
+// docs/cli.md § Programmatic API listed all three (item 387, 2026-09-19).
+export type { RunPlan, PlannedTask } 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,
   Logger,
@@ -65,84 +77,96 @@ export type {
   RunOptions,
   RunSummary,
 } from './orchestrator/index.js'
-export { defaultLogger, resolveOutputView } from './orchestrator/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,
-  TaskOutcome,
-  TaskStatus,
-  VerifyVerdict,
-} from './graph/index.js'
-// The one output-tree diff implementation (verify verdicts + a serve's
-// cross-machine fingerprint diff both name rels through it).
-export { diffOutputTrees } from './orchestrator/index.js'
+export { outputsOverlap, splitTaskId } from './graph/index.js'
+export type { TaskNode, TaskOutcome, TaskStatus } from './graph/index.js'
 
-// Cache classes + the layer interface (the `cache` capability's currency)
-// and input-output resolution. The blob-CAS/digest substrate
-// (cas-backend.ts / digest.ts) stays module-internal until it has a
-// consumer — no speculative public API. `cleanOutputs` is public for the
-// distributed submitter's targeted output materialization (wipe declared
-// outputs, then `restoreOutputs` the artifact — never a naive re-run).
-export {
-  Cache,
-  LayeredCache,
-  GitFilesCache,
-  cleanOutputs,
-  resolveInputs,
-  resolveOutputs,
-} from './cache/index.js'
+// Cache classes + the layer interface (the `cache` capability's currency).
+export { Cache, LayeredCache } from './cache/index.js'
 export type { CacheLayer, RemoteCacheLayer, RunRecord, InvocationRecord } from './cache/index.js'
 
 // Workspace discovery + the project/config catalog surface — an
-// out-of-process service/CLI needs these. `readLockfile` is THE one reader
-// of vx-lock.json (the format carries its own version sentinel; a second
-// 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 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'
+// out-of-process service/CLI needs these. `loadProjectConfig` is the RAW
+// per-file load (`vx lock` freezes exactly that); the resolved view a run
+// or `vx show` sees — plugin stages applied — is `loadResolvedProjects`
+// below. Workspace's `listProjects` re-exports as `listProjectMetas` (the
+// bare name once belonged to a metrics query).
+export { findWorkspaceRoot } from './workspace/index.js'
 export {
   loadWorkspace,
   loadProjectConfig,
   listProjects as listProjectMetas,
 } from './workspace/index.js'
 export type { ProjectMeta } from './workspace/index.js'
+// The package graph as a run sees it (workspace deps by manifest), for a tool
+// that needs a project's transitive closure the way `vx run` computes it.
+export { buildPackageGraph } from './workspace/index.js'
+// The run path's RESOLVED view — plugin `config` and `project` stages
+// applied, cached evaluations served — for a reader outside the CLI (the
+// MCP server's `listTasks`, an embedder's task catalog). What `vx show`
+// prints.
+export { loadResolvedProjects } from './orchestrator/index.js'
+export type { ProjectEntry } from './workspace/index.js'
+// The migration seam: how a generated config is planned, rendered, guarded
+// and written. `vx init` (package.json scripts) uses it in core;
+// `@vzn/vx-migrate` (Turbo, Nx) and any other adoption tool use it from here.
+export {
+  applyMigration,
+  foldScriptHooks,
+  PERSISTENT_TASK_NAMES,
+  PERSISTENT_TODO,
+  quoteTsLiteral,
+} from './workspace/index.js'
+export type {
+  ApplyMigrationArgs,
+  MigrationFormat,
+  GeneratedProject,
+  GeneratedTask,
+  MigrationPlan,
+  RawExpr,
+} from './workspace/index.js'
 
 // Plugin API — the run-level extension points. Behavior capabilities
 // (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.
+// The claimant's shell for a lockfile plugin (`@vzn/vx-lockfile`):
+// the claim, the per-project key, the memo and the `--affected` diff around
+// a parser; `reachDigests` is the Merkle-over-components digest both use.
+export {
+  lockfileClaim,
+  reachDigests,
+  type LockfileClaimHooks,
+  type LockfileClaimOptions,
+  type ReachGraph,
+} from './orchestrator/index.js'
 export type {
   VxPlugin,
+  PluginHooks,
+  PluginOrigin,
   CacheContext,
   ExecutorContext,
   CommandContext,
+  FingerprintChange,
+  FingerprintClaim,
+  FingerprintContext,
   GraphHookContext,
   KeyHookContext,
   PluginCommand,
   ProjectHookContext,
   ScheduleHookContext,
+  AdmitContext,
   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.
+// (`runCommand` / `runSandboxed`, the local executor's own primitives, left
+// the façade 2026-09-10: no executor plugin built on them — `@vzn/vx-reapi`
+// speaks a wire — and a seam with no consumer is a special case in waiting.)
 export type {
   ExecuteRequest,
   ExecuteResult,
@@ -166,7 +190,6 @@ export type {
 // 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,
@@ -180,6 +203,10 @@ export {
 // 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'
+// `exitSignal` is on the façade on the same demonstrated need: a sink that
+// renders a failed task's exit code faces 137 where the frame and `vx last`
+// say `128 + SIGKILL`; the decode is the runner's convention, one copy.
+export { exitSignal } from './orchestrator/index.js'
 export type {
   CacheSource,
   RunContextRecord,
@@ -192,29 +219,11 @@ export type {
   TelemetrySink,
 } 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 } from './orchestrator/index.js'
-export type {
-  EventBus,
-  RunEvent,
-  RunEventSubscriber,
-  WireEvent,
-  TaskView,
-  OutcomeView,
-} from './orchestrator/index.js'
+// The serializable run result and its per-task views (what `run()` returns).
+export type { RunResult, TaskView, OutcomeView } from './orchestrator/index.js'
 
-// 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,
-  explainCacheKeyQuery,
-  getInvocation,
-  getRun,
-  listInvocations,
-  listRuns,
-  whyDidThisRerunQuery,
-} from './orchestrator/index.js'
+// The one run-history query a reader outside the CLI takes today: `vx why`'s
+// answer, which `@vzn/vx-mcp` serves. The event bus / wire form and the
+// other history readers (`listRuns`, `getRun`, …) left the façade 2026-09-10
+// with no consumer; the telemetry seam above is the canonical export path.
+export { latestRunId, whyDidThisRerunQuery } from './orchestrator/index.js'

package/src/orchestrator/admission.ts

@@ -0,0 +1,161 @@
+// What stands between the scheduler's `execute` callback and executeTask:
+// two rules that decide whether a ready task runs NOW and whether its
+// result may be SAVED. Neither changes what the task is.
+//
+// - In-flight dedup: an embedder running concurrent delegated runs in one
+//   process (a daemon built on the façade; core ships none) supplies an
+//   `inflight` registry; a task whose key
+//   a sibling is already computing waits for it and cache-hits on what it
+//   saved. A stateless `vx run` passes none and takes the untouched path.
+// - Continue-taint: under `continueMode: 'always'` a task runs although an
+//   upstream failed. Its key is the healthy one (pure-input hashing) but
+//   its bytes are not, so the taint is tracked here and propagates through
+//   every success built on it — or a grand-dependent would cache the same
+//   partial tree one hop later. Only that mode ever executes a task behind
+//   a failure; the other modes skip it, so a default run carries no check.
+//   `--exclude-dependencies` seeds the same taint: a task whose key folds a
+//   dependency that did not run has bytes nothing vouches for
+//   (excluded-keys.ts).
+//
+// Split from `run.ts` on 2026-09-10 (pure motion).
+
+import type { CachePolicy } from '../cache/index.js'
+import { isGroupTask, RestoreDemoted, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { executeTask, type ExecuteArgs } from './execute-task.js'
+import type { ShortCircuit } from './local-shortcircuit.js'
+import { computeTaskHash, type ComputeHashArgs } from './task-hash.js'
+
+/**
+ * Records which tasks ran behind a failure, or on the key of a dependency
+ * that did not run (`seeds`), and answers, per task, whether this one does.
+ * Disabled (always `false`, nothing recorded) unless the run's
+ * `continueMode` is `'always'` or there is a seed.
+ */
+export function taintTracker(
+  continueAlways: boolean,
+  seeds: ReadonlySet<string>,
+): (node: TaskNode, upstream: TaskOutcome[]) => boolean {
+  if (!continueAlways && seeds.size === 0) return () => false
+  const tainted = new Set<string>()
+  return (node, upstream) => {
+    const taint =
+      seeds.has(node.id) ||
+      upstream.some(
+        // A restore-tier task may run before its deps and see holes here;
+        // it never saves anyway (a hit restores), so a hole is not taint.
+        (u) =>
+          u !== undefined &&
+          (tainted.has(u.node.id) ||
+            (continueAlways &&
+              (u.status === 'failed' || u.status === 'aborted' || u.status === 'skipped'))),
+      )
+    if (taint) tainted.add(node.id)
+    return taint
+  }
+}
+
+export interface AdmissionArgs {
+  /** The shared registry, or undefined for a stateless run (no dedup). */
+  inflight: Map<string, Promise<void>> | undefined
+  policy: CachePolicy
+  shortCircuit: ShortCircuit
+  /** Everything `computeTaskHash` needs besides the node and its upstream. */
+  hashArgs: Omit<ComputeHashArgs, 'node' | 'upstream' | 'nestedProjectDirs'> & {
+    nestedDirsByProject: ReadonlyMap<string, string[]>
+  }
+  /**
+   * The run's execute-args builder. `reuseProbe: false` drops the up-front
+   * probe: a task joining a sibling must let executeTask probe fresh,
+   * because the probe predates the sibling's save.
+   */
+  buildExecuteArgs: (node: TaskNode, upstream: TaskOutcome[], reuseProbe?: boolean) => ExecuteArgs
+}
+
+/** The scheduler's `execute` callback: dedup when it can help, else executeTask. */
+export function admitTasks(
+  args: AdmissionArgs,
+): (node: TaskNode, upstream: TaskOutcome[]) => Promise<TaskOutcome> {
+  const { inflight, policy, shortCircuit, hashArgs, buildExecuteArgs } = args
+  // A probed hit whose artifact vanished before its restore is thrown back
+  // to the scheduler (`RestoreDemoted`, execute-task.ts), which dispatches
+  // the task again once its deps are done. That dispatch probes for itself:
+  // the up-front probe answered for an artifact that is gone. The task
+  // stays in the restore-tier SET, so it still skips dedup below.
+  const dropProbe = (err: unknown): never => {
+    if (err instanceof RestoreDemoted) shortCircuit.preProbed.delete(err.taskId)
+    throw err
+  }
+  return async (node, upstream) => {
+    // Dedup only helps when the sibling will WRITE the artifact and this
+    // task can READ it back — i.e. both axes effectively on.
+    const canRead = policy.localRead || policy.remoteRead
+    const canWrite = policy.localWrite || policy.remoteWrite
+    const cacheable =
+      !isGroupTask(node) &&
+      node.config.exec?.persistent === undefined &&
+      node.config.cache !== undefined &&
+      canRead &&
+      canWrite
+    // A restore-tier task (confirmed local hit, may run before its deps)
+    // needs no dedup — it's a restore, not an executor, and its live
+    // `upstream` is incomplete, so the dedup hash recompute would be
+    // wrong. Route it straight to executeTask, which reuses the up-front
+    // probe.
+    const restorable = shortCircuit.restoreTier.has(node.id)
+    // `!cacheable` is an early-out for bookkeeping, not a guard: measured
+    // (item 506), a non-cacheable task never finds a sibling barrier,
+    // because the hash folds the taskId and a taskId executes once per
+    // run. Removing it reddens nothing and a throw on "a non-cacheable
+    // task joined a barrier" never fires across the whole suite. It saves
+    // the set/delete, and the wait a joiner would spend before running the
+    // task anyway — there is no artifact for it to hit.
+    if (inflight === undefined || !cacheable || restorable) {
+      return executeTask(buildExecuteArgs(node, upstream)).catch(dropProbe)
+    }
+    const { nestedDirsByProject, ...rest } = hashArgs
+    const hash = await computeTaskHash({
+      ...rest,
+      node,
+      upstream,
+      nestedProjectDirs: nestedDirsByProject.get(node.projectName) ?? [],
+    })
+    const existing = inflight.get(hash)
+    if (existing !== undefined) {
+      // Join a sibling already computing this exact task: wait, then
+      // executeTask cache-hits on the artifact it just saved.
+      await existing.catch(() => {})
+      return executeTask(buildExecuteArgs(node, upstream, false))
+    }
+    // Become the executor: register a barrier siblings await. get→set has
+    // no await between, so registration is atomic — at most one executor
+    // per hash. Released on every exit (success / failure / throw).
+    let release!: () => void
+    inflight.set(
+      hash,
+      new Promise<void>((resolve) => {
+        release = resolve
+      }),
+    )
+    const execArgs = buildExecuteArgs(node, upstream)
+    try {
+      // `return await`, deliberately: the finally must run after the task
+      // settles, not when its promise is handed back.
+      return await executeTask(execArgs)
+    } catch (err) {
+      return dropProbe(err)
+    } finally {
+      // The barrier lifts when the ENTRY is there, not when the task is:
+      // the save runs off the slot (save-lane.ts), and a sibling released
+      // before it landed would probe a miss and run the task again. The
+      // executor's own return is not held — only the joiners wait.
+      const landed = execArgs.deferredSaves?.get(node.id)
+      const lift = (): void => {
+        execArgs.deferredSaves?.delete(node.id)
+        inflight.delete(hash)
+        release()
+      }
+      if (landed !== undefined) void landed.then(lift, lift)
+      else lift()
+    }
+  }
+}

package/src/orchestrator/colors.ts

@@ -24,13 +24,18 @@ export interface PaintOptions {
 
 /**
  * Standard env precedence:
- *   NO_COLOR=anything   → off (overrides FORCE_COLOR)
- *   FORCE_COLOR=anything → on
+ *   NO_COLOR non-empty          → off (overrides FORCE_COLOR)
+ *   FORCE_COLOR=0 or =false     → off, even on a TTY
+ *   FORCE_COLOR any other value → on (the empty string too)
  *   else: on iff stdout is a TTY.
+ * `0` and `false` are the convention's "off" (supports-color, chalk,
+ * Node); reading every non-empty value as on painted a piped CI log that
+ * set `FORCE_COLOR=0` (nx#35292's bug).
  */
 export function detectColors(stream: NodeJS.WriteStream = process.stdout): ColorSupport {
   if (process.env['NO_COLOR']) return { enabled: false }
-  if (process.env['FORCE_COLOR']) return { enabled: true }
+  const force = process.env['FORCE_COLOR']
+  if (force !== undefined) return { enabled: force !== '0' && force !== 'false' }
   return { enabled: stream.isTTY === true }
 }
 

package/src/orchestrator/deferred-outputs.ts

@@ -77,15 +77,24 @@ export class DeferredOutputs {
   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)
+    // Pre-order on an explicit stack of dependency lists: a closure is as
+    // deep as the graph, and a recursion per edge threw `RangeError` at the
+    // 50,000 the builder takes (item 737).
+    const stack: Array<[deps: readonly string[], next: number]> = [
+      [this.args.nodes.get(node.id)?.deps ?? [], 0],
+    ]
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1]!
+      if (frame[1] === frame[0].length) {
+        stack.pop()
+        continue
       }
+      const dep = frame[0][frame[1]++]!
+      if (seen.has(dep)) continue
+      seen.add(dep)
+      if (this.entries.has(dep)) needed.push(dep)
+      stack.push([this.args.nodes.get(dep)?.deps ?? [], 0])
     }
-    walk(node.id)
     if (needed.length === 0) return
     await Promise.all(needed.map((id) => this.materializeOne(id)))
   }
@@ -101,12 +110,21 @@ export class DeferredOutputs {
   private async run(taskId: string): Promise<void> {
     const entry = this.entries.get(taskId)!
     const producer = this.args.nodes.get(taskId)!
+    // Project outputs only: a task declaring `outputs.workspaceFiles` is
+    // never deferred (`deferralEligibility` forces it eager), so nothing
+    // workspace-anchored can reach this path.
     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.
+    // The wipe is a rule (a straggler in the declared tree is gone after
+    // the fetch); the two marks are the mirror's cost, not a rule: no
+    // reader of these outputs can be in the run — `deferralEligibility`
+    // keeps every same-project reader and every workspaceFiles reader
+    // eager — so deleting the post-fetch mark survives the whole core
+    // suite (item 643).
     if (outputs.length > 0) {
       const cleaned = await cleanOutputs(cleanArgs)
       this.args.gitFilesCache?.markOutputsChanged(producer.projectDir, cleaned)