@vzn/vx 0.0.595 → 0.0.597

package/src/graph/task-graph.ts

@@ -1,4 +1,3 @@
-import path from 'node:path'
 import type { ProjectConfig, TaskConfig, WorkspaceRules } from '../config.js'
 import {
   asTrees,
@@ -109,6 +108,11 @@ export function isGroupTask(node: TaskNode): boolean {
   return node.config.exec === undefined
 }
 
+/** The default `build` (orchestrator/projects.ts): a config cannot key a group, so it is the one keyed group. */
+function isKeyedGroup(task: TaskConfig): boolean {
+  return task.exec === undefined && task.cache !== undefined
+}
+
 /**
  * Mark, for focused-flow display, the real tasks a requested GROUP
  * stands for. A group has no output of its own, so `vx run build`
@@ -160,7 +164,8 @@ export function markSurfacedDeps(nodes: Map<string, TaskNode>): number {
  *
  *   - Bare task names (`'build'`) → one entry per project in
  *     `candidates` that declares the task. Missing in a given project
- *     is silent (sparse tasks are normal across a workspace).
+ *     is silent (sparse tasks are normal across a workspace). A task
+ *     `unselected` holds (the default `build`) is no match.
  *   - Anchored entries (`'pkg#task'`) → one entry exactly, ignoring
  *     `candidates`. Silently dropped if pkg/task doesn't exist (the
  *     CLI's pre-validation catches malformed strings).
@@ -171,6 +176,7 @@ export function expandRequested(
   tasks: readonly string[],
   candidates: readonly string[],
   projects: Map<string, ProjectEntry>,
+  unselected?: (task: TaskConfig) => boolean,
 ): Array<{ project: string; task: string }> {
   const seen = new Set<string>()
   const out: Array<{ project: string; task: string }> = []
@@ -189,7 +195,7 @@ export function expandRequested(
       continue
     }
     for (const name of candidates) {
-      if (declaresTask(projects, name, spec)) push(name, spec)
+      if (selectsTask(projects, name, spec, unselected)) push(name, spec)
     }
   }
   return out
@@ -214,6 +220,17 @@ function declaresTask(projects: Map<string, ProjectEntry>, project: string, task
   return declaredTask(projects.get(project)?.config, task) !== undefined
 }
 
+/** What a bare name matches: a declared task `unselected` leaves alone. */
+function selectsTask(
+  projects: Map<string, ProjectEntry>,
+  project: string,
+  task: string,
+  unselected: ((task: TaskConfig) => boolean) | undefined,
+): boolean {
+  const config = declaredTask(projects.get(project)?.config, task)
+  return config !== undefined && unselected?.(config) !== true
+}
+
 /**
  * The requested specs `expandRequested` silently dropped — each one
  * matched NO project, so nothing it asked for will run.
@@ -230,6 +247,7 @@ export function unresolvedRequests(
   tasks: readonly string[],
   candidates: readonly string[],
   projects: Map<string, ProjectEntry>,
+  unselected?: (task: TaskConfig) => boolean,
 ): string[] {
   const out: string[] = []
   const seen = new Set<string>()
@@ -239,7 +257,8 @@ export function unresolvedRequests(
     const resolved =
       idx >= 0
         ? declaresTask(projects, spec.slice(0, idx), spec.slice(idx + 1))
-        : candidates.length === 0 || candidates.some((name) => declaresTask(projects, name, spec))
+        : candidates.length === 0 ||
+          candidates.some((name) => selectsTask(projects, name, spec, unselected))
     if (resolved) continue
     seen.add(spec)
     out.push(spec)
@@ -315,7 +334,8 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
 
   function add(node: TaskNode): void {
     nodes.set(node.id, node)
-    if ((node.config.dependsOn?.length ?? 0) > 0) {
+    if (isKeyedGroup(node.config) && onCycle(node.projectName)) deferred.push(node)
+    else if ((node.config.dependsOn?.length ?? 0) > 0) {
       stack.push({ node, entry: 0, added: false, pending: null, next: 0 })
     }
   }
@@ -380,6 +400,88 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     return declared.has(name)
   }
 
+  // Package cycles, for the default `build` (`isKeyedGroup`): each project
+  // on one maps to its strongly connected component, found on the first ask
+  // (iterative Tarjan over `directDeps`, the order the `^name` walk reads).
+  const component = new Map<string, number>()
+  const cyclic = new Set<number>()
+  let components = 0
+  function componentOf(start: string): number {
+    const known = component.get(start)
+    if (known !== undefined) return known
+    const index = new Map<string, number>()
+    const low = new Map<string, number>()
+    const open: string[] = []
+    const work: Array<[name: string, next: number]> = []
+    const enter = (name: string): void => {
+      index.set(name, index.size)
+      low.set(name, index.size - 1)
+      open.push(name)
+      work.push([name, 0])
+    }
+    enter(start)
+    while (work.length > 0) {
+      const top = work[work.length - 1]!
+      const deps = packageGraph.directDeps(top[0])
+      if (top[1] < deps.length) {
+        const dep = deps[top[1]++]!
+        if (component.has(dep)) continue
+        if (!index.has(dep)) enter(dep)
+        else low.set(top[0], Math.min(low.get(top[0])!, index.get(dep)!))
+        continue
+      }
+      work.pop()
+      const name = top[0]
+      const parent = work[work.length - 1]
+      if (parent !== undefined) low.set(parent[0], Math.min(low.get(parent[0])!, low.get(name)!))
+      if (low.get(name) !== index.get(name)) continue
+      const id = components++
+      let size = 0
+      for (let member = ''; member !== name; size++) {
+        member = open.pop()!
+        component.set(member, id)
+      }
+      if (size > 1) cyclic.add(id)
+    }
+    return component.get(start)!
+  }
+  // Default builds on a package cycle, expanded once the rest is built.
+  const deferred: TaskNode[] = []
+  const onCycle = (name: string): boolean => cyclic.has(componentOf(name))
+  const sameCycle = (a: string, b: string): boolean =>
+    onCycle(a) && componentOf(a) === componentOf(b)
+
+  // `^name` from `start`: edges to the nearest holders of `name` among the
+  // packages below it, passing through the ones `visited` holds and the
+  // ones that declare no `name`, and on past a default build on a cycle.
+  // True when it found a holder.
+  function walkHolders(frame: Frame, name: string, visited: Set<string>, start: string): boolean {
+    const frontier = [...packageGraph.directDeps(start)]
+    let held = false
+    while (frontier.length > 0) {
+      const target = frontier.pop()!
+      if (visited.has(target)) continue
+      visited.add(target)
+      if (visit(frame, target, name, false)) {
+        held = true
+        const task = declaredTask(projects.get(target)!.config, name)!
+        if (isKeyedGroup(task) && onCycle(target)) {
+          frontier.push(...packageGraph.directDeps(target))
+        }
+      } else frontier.push(...packageGraph.directDeps(target))
+    }
+    return held
+  }
+
+  // An edge by name (`build`, `pkg#build`) to a default build on a package
+  // cycle goes on past it as a `^build` walk does: that build folds nothing
+  // of the builds on its cycle, so `a#test` on `build` with `a` ↔ `b` both
+  // on the default build folded none of `b` and hit after `b` changed.
+  function goPast(frame: Frame, project: string, name: string, visited: Set<string>): void {
+    const task = declaredTask(projects.get(project)!.config, name)!
+    if (isKeyedGroup(task) && onCycle(project)) walkHolders(frame, name, visited, project)
+  }
+
   // Resolves one `dependsOn` entry of `frame`'s task into its edges.
   function resolveEntry(frame: Frame, raw: string): void {
     const { node } = frame
@@ -429,6 +531,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
             `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
           )
         }
+        goPast(frame, projectName, spec.task, new Set([projectName]))
       }
     } else if (spec.kind === 'deps') {
       // Nearest-holder frontier (Turbo/Nx direct-deps parity +
@@ -451,33 +554,37 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       // shape), and a cycle walks the frontier straight back to the
       // origin. Mirrors the self-pattern rule above — a task can never
       // depend on itself.
-      const re = isTaskPattern(spec.task) ? compileTaskPattern(spec.task) : null
+      //
+      // The default `build` sits on every project, so on a package cycle it
+      // would make a task cycle no config declares. One on a cycle walks
+      // last (`resolveDeferred`), and a walk that meets it on a cycle takes
+      // the edge and goes on past it, so the builds it could not depend on
+      // still come first.
       const visited = new Set<string>([projectName])
+      if (!isTaskPattern(spec.task)) {
+        const held = walkHolders(frame, spec.task, visited, projectName)
+        if (!held && !declaredAnywhere(projectName, spec.task)) {
+          if (undeclaredDeps === undefined) throw undeclaredDepsError(id, spec.task)
+          undeclaredDeps(id, spec.task)
+        }
+        return
+      }
+      // A pattern that matches nothing stays legal, as `build.*` does.
+      const re = compileTaskPattern(spec.task)
       const frontier = [...packageGraph.directDeps(projectName)]
-      let held = false
       while (frontier.length > 0) {
         const target = frontier.pop()!
         if (visited.has(target)) continue
         visited.add(target)
-        if (re === null) {
-          if (visit(frame, target, spec.task, false)) held = true
-          else frontier.push(...packageGraph.directDeps(target))
+        const names = Object.keys(projects.get(target)?.config.tasks ?? {}).filter((n) =>
+          re.test(n),
+        )
+        if (names.length > 0) {
+          for (const name of names) visit(frame, target, name, false)
         } else {
-          const names = Object.keys(projects.get(target)?.config.tasks ?? {}).filter((n) =>
-            re.test(n),
-          )
-          if (names.length > 0) {
-            for (const name of names) visit(frame, target, name, false)
-          } else {
-            frontier.push(...packageGraph.directDeps(target))
-          }
+          frontier.push(...packageGraph.directDeps(target))
         }
       }
-      // A pattern that matches nothing stays legal, as `build.*` does.
-      if (re === null && !held && !declaredAnywhere(projectName, spec.task)) {
-        if (undeclaredDeps === undefined) throw undeclaredDepsError(id, spec.task)
-        undeclaredDeps(id, spec.task)
-      }
     } else {
       // Cross-project edge: pkg#task. Missing target is a hard error
       // because the user named the package + task explicitly.
@@ -491,11 +598,11 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
           `Task ${id} depends on ${taskId(spec.project, spec.task)} but no such project or task is declared`,
         )
       }
+      goPast(frame, spec.project, spec.task, new Set([projectName, spec.project]))
     }
   }
 
-  for (const { project, task } of requested) {
-    visit(null, project, task, true)
+  const drain = (): void => {
     while (stack.length > 0) {
       const frame = stack[stack.length - 1]!
       const { node, pending } = frame
@@ -522,10 +629,97 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     }
   }
 
+  for (const { project, task } of requested) {
+    visit(null, project, task, true)
+    drain()
+  }
+
+  // A default build on a package cycle: its `^build` walk, run once the
+  // graph holds everything else. A build on its cycle that reaches it is
+  // passed through (an edge to it would close a task cycle no config
+  // declares); one that does not is a holder like any other, so the default
+  // build waits for it and folds its key. Passed through unasked, `p#test`
+  // on `p#build` ran beside a `t#build` on no `^build` and hit after `t`
+  // changed. A build no other edge brought is expanded to ask, and pruned
+  // again when it reaches back. Each walk sees the edges the ones before it
+  // took, so no edge closes a cycle.
+  let expanded = false
+  const resolveDeferred = (x: TaskNode): void => {
+    // The default build's one entry is `^` and its own name.
+    const name = x.taskName
+    const frame: Frame = { node: x, entry: 0, added: false, pending: null, next: 0 }
+    let reaching: Set<string> | null = null
+    const visited = new Set<string>([x.projectName])
+    const frontier = [...packageGraph.directDeps(x.projectName)]
+    while (frontier.length > 0) {
+      const target = frontier.pop()!
+      if (visited.has(target)) continue
+      visited.add(target)
+      const task = declaredTask(projects.get(target)?.config, name)
+      if (task === undefined) {
+        frontier.push(...packageGraph.directDeps(target))
+        continue
+      }
+      const to = taskId(target, name)
+      if (sameCycle(x.projectName, target)) {
+        if (!isKeyedGroup(task) && !nodes.has(to)) {
+          visit(null, target, name, false)
+          drain()
+          expanded = true
+          reaching = null
+        }
+        if (isKeyedGroup(task) || (reaching ??= reachingTo(nodes, x.id)).has(to)) {
+          frontier.push(...packageGraph.directDeps(target))
+          continue
+        }
+      }
+      const size = nodes.size
+      frame.added = false
+      visit(frame, target, name, false)
+      drain()
+      if (nodes.size !== size) reaching = null
+      if (isKeyedGroup(task) && onCycle(target)) frontier.push(...packageGraph.directDeps(target))
+    }
+    x.deps = [...new Set(x.deps)].sort()
+  }
+  for (let i = 0; i < deferred.length; i++) resolveDeferred(deferred[i]!)
+  if (expanded) {
+    const keep = new Set<string>()
+    const roots = [...nodes.values()].filter((n) => n.requested).map((n) => n.id)
+    while (roots.length > 0) {
+      const id = roots.pop()!
+      if (keep.has(id)) continue
+      keep.add(id)
+      roots.push(...nodes.get(id)!.deps)
+    }
+    for (const id of nodes.keys()) if (!keep.has(id)) nodes.delete(id)
+  }
+
   checkGraph(nodes, options.workspaceRoot, options.rules)
   return nodes
 }
 
+/** The ids of the tasks that reach `target` along `deps`, itself included. */
+function reachingTo(nodes: Map<string, TaskNode>, target: string): Set<string> {
+  const dependants = new Map<string, string[]>()
+  for (const n of nodes.values()) {
+    for (const d of n.deps) {
+      const list = dependants.get(d)
+      if (list === undefined) dependants.set(d, [n.id])
+      else list.push(n.id)
+    }
+  }
+  const out = new Set<string>()
+  const stack = [target]
+  while (stack.length > 0) {
+    const id = stack.pop()!
+    if (out.has(id)) continue
+    out.add(id)
+    stack.push(...(dependants.get(id) ?? []))
+  }
+  return out
+}
+
 /**
  * What a task graph must hold before it is scheduled: each node under its
  * own id, every dep a node, no cycle, and no two tasks deleting each
@@ -975,36 +1169,51 @@ const GLOB_HEAD_END = /[*?{}\\!]/
  * directory its own head names. A whole subtree meets the globs whose
  * literal prefix lies at or under it, found the same way from the glob's
  * side (item 941).
+ *
+ * Given `sideOf`, only the pairs whose members sit on different sides are
+ * wanted (a reader and a writer, `detectInputOverlaps`), and each index is
+ * kept per side, so a member looks up only the other side's: thousands of
+ * readers sharing one input (`src/**`, a root `tsconfig.base.json`) were
+ * paired with each other, millions of pairs no rule judges (X-101).
  */
 function overlapCandidates<T>(
   tasks: readonly T[],
   globsOf: (n: T) => readonly string[] | undefined,
+  sideOf?: (n: T) => boolean,
 ): Array<[number, number]> {
-  const globs = new Map<string, number[]>()
-  const globsUnder = new Map<string, number[]>()
+  const sides = sideOf === undefined ? 1 : 2
+  // The index a member of side `s` looks up: its own side's, or the other's.
+  const across = (s: number): number => (sides === 1 ? s : 1 - s)
+  const perSide = (): Array<Map<string, number[]>> =>
+    Array.from({ length: sides }, () => new Map<string, number[]>())
+  const globs = perSide()
+  const globsUnder = perSide()
   const literals: Array<[task: number, path: string]> = []
   // `covers` (item 941): a whole subtree `P/**` meets every glob whose
   // literal prefix is P or under it, so each glob looks up the subtrees
   // filed at its prefix and at each of that prefix's ancestors.
-  const subtrees = new Map<string, number[]>()
+  const subtrees = perSide()
   const prefixes: Array<[task: number, prefix: string]> = []
   const file = (index: Map<string, number[]>, key: string, i: number): void => {
     const list = index.get(key)
     if (list === undefined) index.set(key, [i])
     else list.push(i)
   }
+  const side: number[] = []
   for (let i = 0; i < tasks.length; i++) {
+    const s = sideOf?.(tasks[i]!) === true ? 1 : 0
+    side.push(s)
     for (const tree of asTrees(globsOf(tasks[i]!) ?? [])) {
       if (isLiteralPattern(tree)) {
         literals.push([i, tree])
         continue
       }
-      file(globs, tree, i)
+      file(globs[s]!, tree, i)
       const dir = wholeSubtreePrefixes([tree])?.[0]
-      if (dir !== undefined) file(subtrees, dir, i)
+      if (dir !== undefined) file(subtrees[s]!, dir, i)
       prefixes.push([i, staticPrefix(tree)])
       const head = tree.slice(0, tree.search(GLOB_HEAD_END))
-      file(globsUnder, head.slice(0, Math.max(0, head.lastIndexOf('/'))), i)
+      file(globsUnder[s]!, head.slice(0, Math.max(0, head.lastIndexOf('/'))), i)
     }
   }
   const n = tasks.length
@@ -1012,34 +1221,38 @@ function overlapCandidates<T>(
   const pair = (x: number, y: number): void => {
     if (x !== y) pairs.add(x < y ? x * n + y : y * n + x)
   }
-  for (const list of globs.values()) {
+  for (const [tree, list] of globs[0]!) {
+    const other = sides === 1 ? list : (globs[1]!.get(tree) ?? [])
     for (let x = 0; x < list.length; x++) {
-      for (let y = x + 1; y < list.length; y++) pair(list[x]!, list[y]!)
+      for (let y = sides === 1 ? x + 1 : 0; y < other.length; y++) pair(list[x]!, other[y]!)
     }
   }
   // `witnessed`: two globs meet only when one's literal prefix is the
   // other's or under it, so each looks up the globs filed at its prefix
   // and at each ancestor.
-  const byPrefix = new Map<string, number[]>()
-  for (const [i, prefix] of prefixes) file(byPrefix, rootless(prefix), i)
+  const byPrefix = perSide()
+  for (const [i, prefix] of prefixes) file(byPrefix[side[i]!]!, rootless(prefix), i)
   for (const [i, raw] of prefixes) {
+    const index = byPrefix[across(side[i]!)]!
     const prefix = rootless(raw)
-    for (const j of byPrefix.get(prefix) ?? []) pair(i, j)
-    if (prefix !== '') for (const j of byPrefix.get('') ?? []) pair(i, j)
+    for (const j of index.get(prefix) ?? []) pair(i, j)
+    if (prefix !== '') for (const j of index.get('') ?? []) pair(i, j)
     for (let sep = prefix.indexOf('/'); sep !== -1; sep = prefix.indexOf('/', sep + 1)) {
-      for (const j of byPrefix.get(prefix.slice(0, sep)) ?? []) pair(i, j)
+      for (const j of index.get(prefix.slice(0, sep)) ?? []) pair(i, j)
     }
   }
   for (const [i, prefix] of prefixes) {
-    for (const j of subtrees.get(prefix) ?? []) pair(i, j)
+    const index = subtrees[across(side[i]!)]!
+    for (const j of index.get(prefix) ?? []) pair(i, j)
     for (let sep = prefix.indexOf('/'); sep !== -1; sep = prefix.indexOf('/', sep + 1)) {
-      for (const j of subtrees.get(prefix.slice(0, sep)) ?? []) pair(i, j)
+      for (const j of index.get(prefix.slice(0, sep)) ?? []) pair(i, j)
     }
   }
   for (const [i, path] of literals) {
-    for (const j of globsUnder.get('') ?? []) pair(i, j)
+    const index = globsUnder[across(side[i]!)]!
+    for (const j of index.get('') ?? []) pair(i, j)
     for (let sep = path.indexOf('/'); sep !== -1; sep = path.indexOf('/', sep + 1)) {
-      for (const j of globsUnder.get(path.slice(0, sep)) ?? []) pair(i, j)
+      for (const j of index.get(path.slice(0, sep)) ?? []) pair(i, j)
     }
   }
   return [...pairs].sort((x, y) => x - y).map((p) => [Math.floor(p / n), p % n])
@@ -1236,7 +1449,11 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
   if (projectReaders) {
     for (const sides of byProject.values()) {
       if (sides.length < 2) continue
-      for (const [i, j] of overlapCandidates(sides, (s) => s.globs)) {
+      for (const [i, j] of overlapCandidates(
+        sides,
+        (s) => s.globs,
+        (s) => s.reads,
+      )) {
         readsOutputs(sides[i]!, sides[j]!, 'files')
       }
     }
@@ -1251,7 +1468,11 @@ function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: strin
       rooted.push({ node, globs, reads: false, rel })
     }
   }
-  for (const [i, j] of overlapCandidates(rooted, (s) => s.globs)) {
+  for (const [i, j] of overlapCandidates(
+    rooted,
+    (s) => s.globs,
+    (s) => s.reads,
+  )) {
     readsOutputs(rooted[i]!, rooted[j]!, 'workspaceFiles')
   }
 }

package/src/orchestrator/admission.ts

@@ -27,7 +27,10 @@ import { computeTaskHash, type ComputeHashArgs } from './task-hash.js'
 
 /** What `taintTracker` answers per dispatch, and what it learns per finish. */
 export interface TaintTracker {
-  /** Whether `node`, dispatched with these `upstream` outcomes, builds on bytes nothing vouches for. */
+  /**
+   * Whether `node`, dispatched with these key `upstream` outcomes, builds on
+   * bytes nothing vouches for. Its order-only deps count too.
+   */
   judge: (node: TaskNode, upstream: TaskOutcome[]) => boolean
   /** Every settled outcome, the scheduler's `onFinish`. */
   settled: (outcome: TaskOutcome) => void
@@ -102,8 +105,14 @@ export function taintTracker(
   }
   return {
     // 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.
-    judge: (node, upstream) => seeds.has(node.id) || upstream.some(through),
+    // never saves anyway (a hit restores), so a hole is not taint. The
+    // upstream is the key's, which drops order-only edges; their failure
+    // reaches the task through the dependency `--exclude-dependencies`
+    // took out, so they are read from the settled outcomes.
+    judge: (node, upstream) =>
+      seeds.has(node.id) ||
+      upstream.some(through) ||
+      node.orderOnly?.some((d) => through(outcomes.get(d))) === true,
     settled: (outcome) => {
       outcomes.set(outcome.node.id, outcome)
     },

package/src/orchestrator/affected-tasks.ts

@@ -4,7 +4,7 @@
 // behind `^build` runs when `ui#build` (or what it depends on) is reached,
 // and a spec edit `ui#build`'s inputs leave out stops at `ui`'s own tasks.
 
-import { declaresInput } from '../cache/index.js'
+import { declaresInput, workspaceFilesReachInto } from '../cache/index.js'
 import {
   compileTaskPattern,
   isGroupTask,
@@ -91,7 +91,11 @@ export function affectedRoots(
     const cache = n.config.cache
     // Asked of every node, not only the changed projects' (the
     // `workspaceFiles` owners): a `graph` hook may have given the glob.
-    if (cache !== undefined && changes.changed.some((rel) => declaresInput(cache, null, rel))) {
+    if (
+      cache !== undefined &&
+      (changes.changed.some((rel) => declaresInput(cache, null, rel)) ||
+        (changes.nested ?? []).some((dir) => workspaceFilesReachInto(cache, dir)))
+    ) {
       return true
     }
     if (!changes.projects.has(n.projectName)) return false

package/src/orchestrator/deferred-outputs.ts

@@ -23,7 +23,8 @@ 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
+  /** The key a fetch saves the bytes under; absent when the inputs moved after it was taken. */
+  hash?: string
   entry: { taskId: string; command: string; durationMs: number; stdout: string }
 }
 
@@ -149,7 +150,7 @@ export class DeferredOutputs {
     // 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) {
+    if (this.args.localWrite && entry.hash !== undefined) {
       await this.args.cache.save({
         hash: entry.hash,
         projectDir: producer.projectDir,

package/src/orchestrator/doctor.ts

@@ -97,7 +97,7 @@ export interface InfoFacts {
   hits24h: number
   /** Of `hits24h`, the hits that restored outputs; the rest were up to date. */
   restored24h: number
-  /** Tasks the retained history shows both passing and failing on unchanged inputs. */
+  /** Tasks the retained history shows failing on a key that had passed. */
   flakyTasks: FlakyTask[]
   lockfile: boolean
   /**
@@ -256,7 +256,7 @@ async function collectWorkspaceInfo(
     runs24h: stats.runCountLast24h,
     hits24h: stats.hitCountLast24h,
     restored24h: stats.restoredCountLast24h,
-    // Same inputs, both outcomes — the history's definition of flaky, over
+    // A key that failed after it had passed — the history's definition of flaky, over
     // the 30 days it keeps. A run names its own findings in its footer;
     // this is the workspace's standing list.
     flakyTasks: flaky,

package/src/orchestrator/events.ts

@@ -13,6 +13,15 @@ import { maskedCommand, secretMask } from '../util/index.js'
 import type { Logger } from './logger.js'
 import type { RunContext } from './summary.js'
 
+/**
+ * A task no cache answered for: it declares no `cache`, or the run's policy
+ * read and wrote nothing. Its run is `no-cache`, never a miss, on every
+ * surface — `--dry`'s plan, the frame, the footer, `--report`, `--summarize`.
+ */
+export function ranNoCache(o: { node: TaskNode; cacheOff?: boolean }): boolean {
+  return o.node.config.cache === undefined || o.cacheOff === true
+}
+
 /** Payload of the `run:start` event — mirrors the Logger.runStart hook. */
 export interface RunStartInfo {
   total: number
@@ -373,7 +382,7 @@ export function projectOutcome(outcome: TaskOutcome): OutcomeView {
     durationMs: outcome.durationMs,
   }
   if (isGroupTask(outcome.node)) view.isGroup = true
-  else if (outcome.node.config.cache === undefined) view.noCache = true
+  else if (ranNoCache(outcome)) view.noCache = true
   if (outcome.storedDurationMs !== undefined) view.storedDurationMs = outcome.storedDurationMs
   if (outcome.storedCpuMs !== undefined) view.storedCpuMs = outcome.storedCpuMs
   if (outcome.storedPeakRssBytes !== undefined) view.storedPeakRssBytes = outcome.storedPeakRssBytes

package/src/orchestrator/excluded-keys.ts

@@ -16,7 +16,7 @@
 import type { CacheLayer, GitFilesCache } from '../cache/index.js'
 import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import { computeGroupKey, computeTaskHash, type HashCache } from './task-hash.js'
-import { filterUpstreamHashes, keyedDeps } from './upstream.js'
+import { filterUpstreamHashes, keyedDeps, keyedOutcome } from './upstream.js'
 
 export interface KeyExcludedArgs {
   /** The scheduled graph, after `excludeDependencies`. */
@@ -50,7 +50,7 @@ export async function keyExcludedDependencies(args: KeyExcludedArgs): Promise<vo
   // (item 737). The keys still resolve concurrently.
   const keys = new Map<string, Promise<string | undefined>>()
   const outcomes = (ids: readonly string[]): Promise<TaskOutcome[]> =>
-    Promise.all(ids.map(async (id) => synthetic(nodeOf(id), await keys.get(id)!)))
+    Promise.all(ids.map(async (id) => keyedOutcome(nodeOf(id), await keys.get(id)!)))
   const derive = async (node: TaskNode): Promise<string | undefined> => {
     const upstream = await outcomes(fullDeps(node))
     return (isGroupTask(node) ? computeGroupKey : computeTaskHash)({
@@ -139,14 +139,3 @@ function foldsExcludedKey(node: TaskNode): boolean {
       .length > 0
   )
 }
-
-/** A dependency as a key reads it: only `node` and `hash` matter. */
-function synthetic(node: TaskNode, hash: string | undefined): TaskOutcome {
-  return {
-    node,
-    status: 'success',
-    exitCode: 0,
-    durationMs: 0,
-    ...(hash !== undefined ? { hash } : {}),
-  }
-}