@vzn/vx 0.0.651 → 0.0.652

package/src/orchestrator/run.ts

@@ -8,11 +8,13 @@ import { EMPTY_LOCK, inputStabilityEnv, LOCK_INVALID, lockEntryBroken } from '..
 import { realpathSync } from 'node:fs'
 import path from 'node:path'
 import {
+  historyFiles,
   indexDb,
   Cache,
   type CachePolicy,
   cachesNothing,
   formatCachePolicy,
+  HistoryStream,
   networkConcurrency,
   keepRunNotes,
   stopRuntimeProbes,
@@ -28,10 +30,11 @@ import {
 } from '../exec/index.js'
 import { DeferredOutputs } from './deferred-outputs.js'
 import { resolveDownloadModes } from './download-policy.js'
-import type { MachineReport, TaskExecutor } from '../exec/index.js'
+import type { MachineReport, TaskExecutor, WorkerAdvice } from '../exec/index.js'
 import {
   deadServerBehind,
   declaredTask,
+  isCacheHit,
   isGroupTask,
   markSurfacedDeps,
   runGraph,
@@ -65,7 +68,7 @@ function printTimings(): void {
   if (lines !== undefined) ui.print('err', ui.trace(lines))
 }
 import { detectColors, type ColorSupport } from '../ui/index.js'
-import { keyedProjects } from './keyed-projects.js'
+import { keyedProjects, readableDeps } from './keyed-projects.js'
 import { isDefaultBuild } from '../graph/index.js'
 import { commandWriteReach, prepareSandbox } from './sandbox-request.js'
 import { recordOutputDirSnapshots, type OutputDirSnapshot, type SaveFacts } from './miss-save.js'
@@ -138,7 +141,12 @@ import { deriveStableKeys, probesAfterWrites } from './stable-keys.js'
 import { askRemote, serversToHold } from './held-servers.js'
 
 import { writeRunFailures } from './run-failures.js'
-import { assembleRunRecords, recordLateRemoteErrors } from './run-records.js'
+import {
+  assembleRunRecords,
+  recordLateRemoteErrors,
+  type RecordedOutcome,
+  runRecordOf,
+} from './run-records.js'
 import {
   hasEnded,
   disposeServers,
@@ -155,6 +163,7 @@ import {
   createMissExplainer,
   detectFlaky,
   type FlakyCandidate,
+  knownFlaky,
   LocalHistoryProvider,
 } from '../history/index.js'
 import type { RunOptions, RunSummary } from './options.js'
@@ -452,11 +461,11 @@ async function runOnBus(
     options = withRunSettings(options, prepared.workspaceConfig)
     inputStability = {
       run: inputStabilityEnv(),
-      ...(prepared.workspaceConfig?.cache?.inputStability !== undefined
-        ? { workspace: prepared.workspaceConfig.cache.inputStability }
+      ...(prepared.workspaceConfig?.inputs?.stability !== undefined
+        ? { workspace: prepared.workspaceConfig.inputs.stability }
         : {}),
     }
-    cleanOutputs = resolveSetting('cache.outputs.clean', prepared.workspaceConfig).value as
+    cleanOutputs = resolveSetting('outputs.clean', prepared.workspaceConfig).value as
       | boolean
       | undefined
   } catch (err) {
@@ -639,15 +648,15 @@ async function runOnBus(
   // deliberate — on a machine with no remote pool the ambient state already
   // is what the task would have produced — but it must not be SILENT: a task
   // reporting success while doing nothing is indistinguishable from one that
-  // worked, and the usual cause (no `cache` block, so no executor can
+  // worked, and the usual cause (no `cache: true`, so no executor can
   // describe its inputs to a worker) cannot be read off the outcome.
   if (placements.remoteOnlyNoop.size > 0) {
     const anyRemote = executors.some((e) => e.remote === true)
     for (const id of placements.remoteOnlyNoop) {
       const why = !anyRemote
         ? 'no remote executor is declared'
-        : nodes.get(id)?.config.cache === undefined
-          ? 'no remote executor accepted it — the task declares no `cache` block, so there is no input set to ship'
+        : nodes.get(id)?.config.cache !== true
+          ? 'no remote executor accepted it — the task has no `cache: true`, so there is no input set to ship'
           : 'no remote executor accepted it'
       warnOf(log)(`[vx] ${id}: exec.remote is 'only' and ${why} — nothing ran`)
     }
@@ -853,7 +862,7 @@ async function runOnBus(
     // SRT's proxies holding the process open.
     const surelyRuns = (n: TaskNode): boolean =>
       n.config.exec?.persistent !== undefined ||
-      n.config.cache === undefined ||
+      n.config.cache !== true ||
       !(policy.localRead || policy.remoteRead)
     // Only what runs here arms this machine's sandbox: a `sandbox` executor
     // enforces it where it runs the task, so a distributed run's
@@ -874,6 +883,7 @@ async function runOnBus(
     }
     if (sandboxed.some(surelyRuns)) prewarm()
     const keyed = keyedProjects(nodes, prepared.keyOnly)
+    const readable = readableDeps(nodes, prepared.keyOnly)
     const outputDirSnapshots: OutputDirSnapshot[] = []
     // Saves run off the execution slot, twice the cap at once (memory:
     // each pack holds an artifact's bytes); a failed save is a miss next
@@ -1114,7 +1124,7 @@ async function runOnBus(
           (probe.hit !== null ? hits : missed).push(id)
         // An empty store was not asked: it holds none of them.
         if (coldLocal && !remote)
-          for (const [id, n] of nodes) if (n.config.cache !== undefined) missed.push(id)
+          for (const [id, n] of nodes) if (n.config.cache === true) missed.push(id)
         demand.settle(hits, missed)
       }
     }
@@ -1153,6 +1163,8 @@ async function runOnBus(
     // The scheduler's fail-fast stop, as the retry loop of a task already
     // in flight sees it.
     const failFast = new AbortController()
+    // Tasks a plugin's shared record names flaky (`ctx.flaky`).
+    const sharedFlaky = new Set<string>()
     const scope: RunScope = {
       workspaceRoot,
       cache,
@@ -1168,6 +1180,7 @@ async function runOnBus(
       probesAfterWrites: lateProbes,
       fingerprintWatch,
       keyedProjects: keyed,
+      readableDeps: readable,
       outputDirSnapshots,
       deferSave: saveLane.defer,
       deferredSaves,
@@ -1177,6 +1190,15 @@ async function runOnBus(
       inputStability,
     }
     if (options.retries !== undefined) scope.retries = options.retries
+    scope.knownFlaky = (node, hash) => {
+      if (sharedFlaky.has(node.id)) return true
+      try {
+        return knownFlaky(indexDb(prepared.localCache), node.projectName, node.taskName, hash)
+      } catch {
+        // History is observability: an unreadable one retries nothing.
+        return false
+      }
+    }
     if (taskTimeoutDefault !== undefined) scope.timeout = taskTimeoutDefault
     if (cleanOutputs !== undefined) scope.cleanOutputs = cleanOutputs
     const sinkTrack = telemetry?.track
@@ -1253,6 +1275,9 @@ async function runOnBus(
             if (reprioritize !== undefined) reprioritize(merged)
             else if (!graphOver) refinedEarly = merged
           },
+          flaky: (ids) => {
+            for (const id of ids) if (nodes.has(id)) sharedFlaky.add(id)
+          },
         })
     mark('schedule')
     // Judged as each task finishes, against the history BEFORE this run's
@@ -1294,6 +1319,29 @@ async function runOnBus(
     }
     let lockBroken: boolean | undefined
     prepared.localCache.storeHeldBlobSizes()
+    // A hit's row is whole when it finishes, so it is written while the
+    // graph runs (history-stream.ts); every other row waits for the bundle.
+    // A row with forward args is the bundle's too: only it digests them.
+    const historyAt = historyFiles(prepared.localCache)
+    const stream = historyAt === undefined ? undefined : new HistoryStream<TaskOutcome>(historyAt)
+    const forwards = (options.forwardArgs?.length ?? 0) > 0
+    const streamHit = (o: TaskOutcome): void => {
+      if (stream === undefined || isGroupTask(o.node)) return
+      if (!isCacheHit(o.status)) return
+      if (o.wallclockStartNs === undefined || o.wallclockEndNs === undefined) return
+      if (forwards && o.node.requested) return
+      stream.add(
+        o,
+        runRecordOf(o as RecordedOutcome, {
+          tainted: taintedRan,
+          runId,
+          startedAtMs: endedAtMsAtStart,
+          endedAtMs: endedAtMsAtStart,
+          blocks: blocksNow(),
+          remoteTraffic: prepared.localCache.traffic.keys,
+        }),
+      )
+    }
     const outcomes = await runGraph({
       nodes,
       concurrency,
@@ -1316,6 +1364,7 @@ async function runOnBus(
         judgeFlaky(o)
         keeper?.taskDone(o)
         log.taskComplete(o.node, o)
+        streamHit(o)
         demand.finished(o.node.id)
         // A server that dies while the graph runs is no longer running:
         // its pin stayed `running` under the line naming its exit.
@@ -1420,6 +1469,9 @@ async function runOnBus(
       endedBeforeStop: stop.endedBeforeStop,
     })
 
+    // Every batch the stream sent has answered: what landed is not written again.
+    const streamed = await stream?.finish()
+    const landed = new Set(streamed?.landed.map((s) => s.item))
     mark('run graph')
 
     // Clear the status line for good before the summary prints.
@@ -1520,6 +1572,7 @@ async function runOnBus(
         withTelemetry: telemetry !== undefined,
         blocks: blocksNow(),
         remoteTraffic: prepared.localCache.traffic.keys,
+        landed,
       })
     const records = recordsOf(list, ok)
     const recordHistory = (write: () => void): void => {
@@ -1603,7 +1656,13 @@ async function runOnBus(
     }
     // An upload that failed after the rows went in: its row says so too.
     if (prepared.localCache.uploads.failed > 0 && stop.stoppedBy === undefined && !historyAfterWait)
-      recordHistory(() => recordLateRemoteErrors(prepared.localCache, records.runs, runId))
+      recordHistory(() =>
+        recordLateRemoteErrors(
+          prepared.localCache,
+          [...records.runs, ...(streamed?.landed.map((s) => s.record) ?? [])],
+          runId,
+        ),
+      )
     const report = reportOf(list, { runId, commit: head.commitSha, ciRun: ciContext, ok }, keeper)
     // Hand the per-run summary to the telemetry sinks + drain them. Only
     // when a sink is active (telemetry !== undefined) — otherwise this
@@ -1623,6 +1682,7 @@ async function runOnBus(
         uploads: prepared.localCache.uploads,
         machines: executors.flatMap((e) => executorMachines(e, fault)),
         idealMs: executors.map((e) => executorIdeal(e, fault)).find((ms) => ms !== undefined),
+        advice: executors.flatMap((e) => executorAdvice(e, fault)),
       })
       telemetry.emitSummary(summary)
       const sinks = telemetry
@@ -1981,12 +2041,15 @@ function didYouMean(
   elsewhere: readonly string[],
   taskless: (name: string) => boolean,
 ): string {
-  const tasksOf = (p: ProjectEntry | undefined): string[] => Object.keys(p?.config.tasks ?? {})
-  // What a bare name can select: a default `build` is no match (X-102).
+  // A default `build` is no declared task (X-102): neither a bare name's
+  // match nor a menu item or hint for `p#typo`, which led to `p#build`
+  // and its refusal ("p declares no build").
+  const tasksOf = (p: ProjectEntry | undefined): string[] =>
+    Object.entries(p?.config.tasks ?? {})
+      .filter(([, c]) => !isDefaultBuild(c))
+      .map(([t]) => t)
   const allTasks = new Set<string>()
-  for (const p of projects.values()) {
-    for (const t of tasksOf(p)) if (!isDefaultBuild(p.config.tasks![t])) allTasks.add(t)
-  }
+  for (const p of projects.values()) for (const t of tasksOf(p)) allTasks.add(t)
   // A Set: two typos of the same task hint it once, not once per typo.
   const hints = new Set<string>()
   // A typo past two edits named nothing to pick from (M-56): with no near
@@ -2096,10 +2159,10 @@ function flakyCandidates(
   for (const o of outcomes) {
     if (o.status !== 'success' && o.status !== 'failed') continue
     // "Same inputs, failed after passing" is a claim only a task with declared
-    // inputs can make: a task with no `cache` block keys on its config alone
+    // inputs can make: a task without `cache: true` keys on its config alone
     // and runs every time, so one bad network day would read as a flake for
     // thirty days. Groups do no work.
-    if (o.hash === undefined || o.node.config.cache === undefined || isGroupTask(o.node)) continue
+    if (o.hash === undefined || o.node.config.cache !== true || isGroupTask(o.node)) continue
     // Behind a failed dependency the outcome is not the key's: a failure is
     // the dependency's, and a pass built on bytes the key never named, so a
     // later failure relapsed from it and read as a flake for thirty days.
@@ -2184,6 +2247,16 @@ function executorMachines(e: TaskExecutor, fault: ExecutorFault): readonly Machi
   }
 }
 
+function executorAdvice(e: TaskExecutor, fault: ExecutorFault): readonly WorkerAdvice[] {
+  try {
+    const a = e.advice?.()
+    return Array.isArray(a) ? a : []
+  } catch (err) {
+    fault(e, 'advice', err)
+    return []
+  }
+}
+
 function executorIdeal(e: TaskExecutor, fault: ExecutorFault): number | undefined {
   try {
     const ms = e.idealMs?.()

package/src/orchestrator/sandbox-request.ts

@@ -183,6 +183,10 @@ export function prepareSandbox(nodes: Iterable<SandboxedNode>): SandboxArmer | n
  * anyone's (2026-09-24): `keyed` is the set of project directories the
  * task's key answers for (keyed-projects.ts), and `undefined` for a task
  * with no `cache`, which has no key to be stale.
+ *
+ * The other is the outputs of the tasks its key folds
+ * (`dependencyOutputs`, 2026-11-06): an edge the user drew, whose files
+ * this key already answers for, so the read can replay nothing stale.
  */
 export async function sandboxRequestFor(
   node: Pick<TaskNode, 'projectDir'>,
@@ -197,6 +201,8 @@ export async function sandboxRequestFor(
    * grant covered it could plant artifacts and index rows (L-24).
    */
   cacheDir?: string,
+  /** The dependencies' outputs it may read (`dependencyReads`): absolute paths. */
+  dependencyOutputs: readonly string[] = [],
 ): Promise<SandboxRequest> {
   // The runtime reads a path holding a bracket as a pattern: on Linux it
   // mounts no such write path (B-60); seatbelt's rules compile it as a
@@ -238,7 +244,7 @@ export async function sandboxRequestFor(
   // own `package.json` depends on (2026-09-05) — when the key
   // moves with it.
   const links = await linkedDeps(depDirs, node.projectDir, workspaceRoot, keyed)
-  depDirs.push(...links.granted)
+  depDirs.push(...links.granted, ...dependencyOutputs)
   // bwrap cannot --bind a path that does not exist: the bind silently
   // becomes a no-op and writes to it appear to succeed but never land.
   // Pre-create what the task said it will write — after the grants are
@@ -269,7 +275,8 @@ export async function sandboxRequestFor(
     throw err
   }
   const request: NonNullable<ExecuteRequest['sandbox']> = {
-    // Only what the task declared, plus node_modules. Write paths are
+    // Only what the task declared, plus node_modules and the outputs of
+    // the tasks its key folds (`dependencyReads`). Write paths are
     // readable too: a task that writes `dist/x` expects to read it back
     // (`tsc --incremental` re-reads .tsbuildinfo).
     baseAllowRead: depDirs,
@@ -304,10 +311,46 @@ export async function sandboxRequestFor(
     reportLinked: links.withheld.map((w) => w.dir),
     config,
     ...(keyed === undefined ? {} : { keyed: [...keyed] }),
+    ...(dependencyOutputs.length === 0 ? {} : { dependencyReads: [...dependencyOutputs] }),
   }
   return { sandbox: request, placeholders, withheld: links.withheld }
 }
 
+/**
+ * The paths a sandboxed task may read of its dependencies' declared
+ * outputs (`readableDeps`): each output glob's fixed head, or, for a glob
+ * with none (`*.tsbuildinfo`), the files it matches now, so a root-level
+ * output never grants the dependency's whole project. Asked when the task
+ * runs, after its dependencies ran or were restored: a head that names
+ * nothing is left out, as bwrap binds no missing path.
+ */
+export async function dependencyReads(
+  deps: readonly TaskNode[],
+  workspaceRoot: string,
+): Promise<string[]> {
+  const reads = new Set<string>()
+  for (const dep of deps) {
+    const outputs = dep.config.outputs
+    if (outputs === undefined) continue
+    const globs = [
+      ...outputs.files.map((g) => [dep.projectDir, g] as const),
+      ...(outputs.workspaceFiles ?? []).map((g) => [workspaceRoot, g] as const),
+    ]
+    for (const [base, glob] of globs) {
+      if (glob.startsWith('!')) continue
+      const head = grantPrefix(glob)
+      if (head !== '' && head !== '.') {
+        const abs = path.join(base, head)
+        if (existsSync(abs)) reads.add(abs)
+        continue
+      }
+      for await (const f of new Bun.Glob(glob).scan({ cwd: base, onlyFiles: true, dot: true }))
+        reads.add(path.join(base, f))
+    }
+  }
+  return [...reads]
+}
+
 /**
  * The sandbox half of the request, plus the empty files vx created so a
  * literal write grant had something to bind (`placeholders`). They are
@@ -573,7 +616,7 @@ function wallOff(
     if (wall === undefined) continue
     throw new UserError(
       `exec.sandbox.allow.write: the grant binding ${bind} would make ${wall} writable — another ` +
-        `project's directory, the repository or vx's own. A file grant binds its directory; ` +
+        `project's directory, .git or vx's own. A file grant binds its directory; ` +
         `grant a directory of the task's own instead, such as "dist/".`,
     )
   }
@@ -774,13 +817,13 @@ export type WriteReach = 'none' | 'project' | 'workspace'
  * names — the files whose run-start facts (the git snapshot, its index
  * OIDs) a later key must not reuse (item 743).
  *
- * A cached task declares its outputs and is held to them. A task with no
- * `cache` block can declare none, so it may have written anywhere
- * `commandWriteReach` says. An unsandboxed write into another project is
+ * A cached task declares its outputs and is held to them: its save checks
+ * them. A task with no `cache: true` is held to nothing, even when it
+ * declares outputs, so it may have written anywhere `commandWriteReach` says. An unsandboxed write into another project is
  * out of contract, as it is for a cached task.
  */
 export function undeclaredWriteReach(node: TaskNode, workspaceRoot: string): WriteReach {
-  if (node.config.cache !== undefined) return 'none'
+  if (node.config.cache === true) return 'none'
   return commandWriteReach(node, workspaceRoot)
 }
 

package/src/orchestrator/shell-verdict.ts

@@ -43,6 +43,15 @@ export function shellVerdict(args: {
   if (args.code === 126) {
     return `[vx] exit 126 is the shell's "found but cannot execute": ${what} is not executable or is a directory — chmod +x it`
   }
+  // A program the host's PATH has may be one the sandbox hides (a
+  // hermetic task sees no /usr/bin): the reason is a grant, not an install.
+  const found =
+    word === undefined || args.hidden === undefined
+      ? null
+      : Bun.which(word, { PATH: [...args.bins, process.env['PATH'] ?? ''].join(path.delimiter) })
+  if (found !== null && args.hidden!(found)) {
+    return `[vx] exit 127 is the shell's "command not found": ${word} is ${found} on the host, but no sandbox grant reads it, so inside the sandbox it is not there — add it (or its directory) to exec.sandbox.allow.read`
+  }
   const unnamed = args.bins.find((dir) => dir.includes(path.delimiter))
   if (unnamed !== undefined) {
     return `[vx] exit 127 is the shell's "command not found": ${what} is not on this task's PATH — ${unnamed} holds "${path.delimiter}", which PATH reads as a separator, so vx cannot put it there; move the workspace to a path without "${path.delimiter}"`

package/src/orchestrator/stable-keys.ts

@@ -89,14 +89,14 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   // reached through a no-output intermediate still poisons the key, so each
   // dep's accumulated producers fold forward.
   //   - outputProjects: the project names of every upstream task declaring
-  //     cache.outputs.files (project-relative outputs land in the producer's
-  //     own dir), and of every upstream with no cache block that may write
+  //     outputs.files (project-relative outputs land in the producer's
+  //     own dir), and of every upstream with no `cache: true` that may write
   //     in its own project (`undeclaredWriteReach`, item 743). A bitset over
   //     project indexes: a union per dep was a string Set copied tasks ×
   //     deps × projects times, 101 ms of a 513 ms warm run at 476 packages
   //     (item 744).
-  //   - wsOutputUpstream: any upstream declares cache.outputs.workspaceFiles
-  //     (root-anchored, boundary-ignoring outputs), or has no cache block
+  //   - wsOutputUpstream: any upstream declares outputs.workspaceFiles
+  //     (root-anchored, boundary-ignoring outputs), or has no `cache: true`
   //     and a sandbox write grant elsewhere in the workspace, or may rewrite
   //     a root file a plugin claims (a root `pnpm install`): every key folds
   //     what the claimant took from it, once per run.
@@ -125,7 +125,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   // of what any one reader's upstream producers declare.
   const outputsOf = new Map<string, string[]>()
   for (const n of args.nodes.values()) {
-    const files = n.config.cache?.outputs.files ?? []
+    const files = n.config.outputs?.files ?? []
     if (files.length === 0) continue
     const list = outputsOf.get(n.projectName)
     if (list === undefined) outputsOf.set(n.projectName, [...files])
@@ -185,10 +185,10 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
         const wideOfDep = wideById.get(dep)
         if (wideOfDep !== undefined) wideUnion.addAll(wideOfDep)
         if (wsOutputUpstreamById.get(dep) === true) wsOutputUpstream = true
-        const depOut = depNode.config.cache?.outputs
+        const depOut = depNode.config.outputs
         if ((depOut?.files?.length ?? 0) > 0) outputs.add(depNode.projectName)
         if ((depOut?.workspaceFiles?.length ?? 0) > 0) wsOutputUpstream = true
-        // An uncached producer declares no outputs, yet a same-project reader
+        // An uncached producer is held to no outputs, yet a same-project reader
         // after it (`tasks: []` decouples the key, not the order) read the
         // bytes it wrote: its key taken up front was the pre-producer one, and
         // the fourth run of seeds A,B,B,A replayed B over A (turborepo#13788).
@@ -198,7 +198,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
           wideUnion.add(depNode.projectName)
         } else if (reach === 'workspace') wsOutputUpstream = true
         if (
-          depNode.config.cache === undefined &&
+          depNode.config.cache !== true &&
           mayWriteFingerprint(depNode, args.workspaceRoot, args.claimedFiles)
         )
           wsOutputUpstream = true
@@ -219,7 +219,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
     for (const dep of anyUnfolded ? node.deps : []) {
       const depNode = args.nodes.get(dep)
       if (!depNode) continue
-      const cached = depNode.config.cache !== undefined
+      const cached = depNode.config.cache === true
       // The cached twin: a formatter rewriting its own input ahead of a
       // reader that folds no key of it replayed seed B's build under seed A
       // on the fourth run, the same way (item 750).
@@ -323,7 +323,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
       )
     if (unstable) unstableById.add(id)
 
-    const cacheEnabled = node.config.cache !== undefined
+    const cacheEnabled = node.config.cache === true
     if (cacheEnabled && !unstable) stableKeys.push({ hash, node })
     // An uncached key stays preliminary behind any upstream that may write
     // into this project, or anywhere: none of its writes is declared.
@@ -438,7 +438,7 @@ export function gatedOutputs(
   // 1,000 projects' tasks spent 5-8 ms here re-splitting the same globs.
   const outputsOf = new Map<string, ProjectOutputs>()
   for (const n of nodes.values()) {
-    const files = n.config.cache?.outputs.files
+    const files = n.config.outputs?.files
     if (files === undefined || files.length === 0) continue
     let po = outputsOf.get(n.projectName)
     if (po === undefined) outputsOf.set(n.projectName, (po = new ProjectOutputs()))
@@ -554,8 +554,8 @@ export function probesAfterWrites(
   for (const n of nodes.values()) {
     if (
       commandWriteReach(n, workspaceRoot) !== 'none' ||
-      (n.config.cache?.outputs.files.length ?? 0) > 0 ||
-      (n.config.cache?.outputs.workspaceFiles?.length ?? 0) > 0
+      (n.config.outputs?.files.length ?? 0) > 0 ||
+      (n.config.outputs?.workspaceFiles?.length ?? 0) > 0
     )
       writers.add(n.id)
   }
@@ -581,7 +581,7 @@ export function probesAfterWrites(
     }
     if (writer) writerBelow.add(id)
     if (unfolded) unfoldedBelow.add(id)
-    if (unfolded && node.config.cache !== undefined && probes(node)) late.add(id)
+    if (unfolded && node.config.cache === true && probes(node)) late.add(id)
   }
   return late
 }
@@ -628,8 +628,8 @@ function synthUpstream(
  * Conservative stability check: does any TRANSITIVE-upstream task whose
  * outputs could land where this task reads its inputs make this task's
  * key preliminary? The producers are pre-folded by `deriveStableKeys`
- * (`upstreamOutputProjects` = projects declaring `cache.outputs.files`
- * upstream; `hasWsOutputUpstream` = any `cache.outputs.workspaceFiles`
+ * (`upstreamOutputProjects` = projects declaring `outputs.files`
+ * upstream; `hasWsOutputUpstream` = any `outputs.workspaceFiles`
  * upstream), so a producer reached through a no-output intermediate is
  * caught too.
  *
@@ -663,7 +663,6 @@ export function dependsOnSiblingOutputs(
     readableOf?: ReadonlyMap<string, readonly string[]>
   },
 ): boolean {
-  const cache = node.config.cache
   const declared = node.config.inputs
   // A task with no inputs has no key to take up front.
   if (declared === undefined) return false
@@ -697,7 +696,7 @@ export function dependsOnSiblingOutputs(
     // that producer, its restore raced the producer's clean and extract
     // (M-5; invariant 2 of docs/design/overlapping-outputs-2026-09.md).
     // `outputsOf` holds this task's own globs too; set them aside once.
-    const own = cache?.outputs.files ?? []
+    const own = node.config.outputs?.files ?? []
     if (own.length > 0) {
       const others = [...outputs]
       for (const g of own) {

package/src/orchestrator/task-artifacts.ts

@@ -22,7 +22,7 @@ export interface ArtifactTask {
   /** Absolute. */
   readonly projectDir: string
   readonly command: string
-  /** Its `cache.outputs`: project-relative `files`, root-relative `workspaceFiles`. */
+  /** Its `outputs`: project-relative `files`, root-relative `workspaceFiles`. */
   readonly outputs: {
     readonly files: readonly string[]
     readonly workspaceFiles: readonly string[]

package/src/orchestrator/task-hash.ts

@@ -292,7 +292,7 @@ export async function describeTaskInputs(args: ComputeHashArgs): Promise<{
  * input changed and changed BACK while the command ran matched its digest
  * again, and the entry saved the other content's output under the key (item
  * 1015). A write before it — an upstream's — is judged by content, as before.
- * `byBytes` (`inputStability.strategy: 'mutable'`) judges a write during
+ * `byBytes` (`inputs.stability.strategy: 'mutable'`) judges a write during
  * the command by content too, when it answers true for that file and its
  * ctime: the task says the same bytes are its own identical rewrite
  * (tsdown's package.json), not an edit undone, unless another command that
@@ -353,14 +353,14 @@ export function taskFilesToken(
 /** What `resolveInputs` is asked for a task's key. */
 function inputsArgs(args: ComputeHashArgs): ResolveInputsArgs {
   const cfg = args.node.config
-  const cacheCfg = cfg.cache
+  const cfgOut = cfg.outputs
   return {
     projectDir: args.node.projectDir,
     workspaceRoot: args.workspaceRoot,
     envSource: process.env,
     inputs: cfg.inputs,
-    ownOutputs: cacheCfg?.outputs.files ?? [],
-    ownWorkspaceOutputs: cacheCfg?.outputs.workspaceFiles ?? [],
+    ownOutputs: cfgOut?.files ?? [],
+    ownWorkspaceOutputs: cfgOut?.workspaceFiles ?? [],
     nestedProjectDirs: args.nestedProjectDirs,
     ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
     ...(args.probesAfterWrites?.has(args.node.id) === true ? { runtimeScope: args.node.id } : {}),

package/src/orchestrator/telemetry.ts

@@ -16,7 +16,7 @@
 // what or how tasks run. Contrast `cache`/`executor`, which return objects
 // core calls INTO; those are the behavior capabilities, kept separate.
 
-import { sampleTrees, type MachineReport } from '../exec/index.js'
+import { sampleTrees, type MachineReport, type WorkerAdvice } from '../exec/index.js'
 import {
   type CacheSource,
   deriveCacheSource,
@@ -301,6 +301,8 @@ export interface RunSummaryRecord {
    * (`TaskExecutor.idealMs`), beside `totalDurationMs`. Additive.
    */
   idealMs?: number
+  /** The workers that would have run it best (`TaskExecutor.advice`). Additive. */
+  advice?: readonly WorkerAdvice[]
 }
 
 /** One stage of a run, a wall window in epoch ms. */
@@ -334,6 +336,7 @@ export function assembleRunSummary(
     uploads?: { count: number; bytes: number; ms: number; failed: number }
     machines?: readonly MachineReport[]
     idealMs?: number | undefined
+    advice?: readonly WorkerAdvice[]
   },
 ): RunSummaryRecord {
   let failedCount = 0
@@ -376,6 +379,7 @@ export function assembleRunSummary(
       ? { machines: timing.machines }
       : {}),
     ...(timing.idealMs !== undefined ? { idealMs: timing.idealMs } : {}),
+    ...(timing.advice !== undefined && timing.advice.length > 0 ? { advice: timing.advice } : {}),
   }
 }
 

package/src/report/events.ts

@@ -14,12 +14,12 @@ 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
+ * A task no cache answered for: it has no `cache: true`, 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, the run history.
  */
 export function ranNoCache(o: { node: TaskNode; cacheOff?: boolean }): boolean {
-  return o.node.config.cache === undefined || o.cacheOff === true
+  return o.node.config.cache !== true || o.cacheOff === true
 }
 
 /** Payload of the `run:start` event — mirrors the Logger.runStart hook. */
@@ -281,7 +281,7 @@ export interface OutcomeView {
    * and counting groups as executed tasks drifts from the terminal.
    */
   isGroup?: boolean
-  /** Executed with no `cache` block: never consulted the cache, not a miss. */
+  /** Executed without `cache: true`: never consulted the cache, not a miss. */
   noCache?: boolean
   /** Cache hits only: the exec time the entry was stored with — the work
    *  this hit skipped, as opposed to `durationMs`, the restore it cost. */