@vzn/vx 0.0.650 → 0.0.652

package/src/index.ts

@@ -41,9 +41,10 @@ export type {
   TaskConfig,
   ExecConfig,
   ExecEnv,
-  CacheConfig,
   InputsConfig,
-  CacheOutputs,
+  TaskOutputs,
+  WorkspaceInputs,
+  WorkspaceOutputs,
   InputStability,
   SandboxConfig,
   SandboxGrants,
@@ -145,7 +146,7 @@ export {
   taskNameProblem,
 } from './workspace/index.js'
 // Output components: a plugin draws its lines with core's, so they look alike.
-export { ui } from './util/index.js'
+export { ui } from './ui/index.js'
 export type {
   ApplyMigrationArgs,
   MigrationFormat,
@@ -186,10 +187,12 @@ export type {
   CacheFacts,
   TaskArtifacts,
   FingerprintChange,
+  FingerprintDigests,
   FingerprintClaim,
   FingerprintContext,
   GraphHookContext,
   KeyHookContext,
+  LockedFile,
   PluginCommand,
   ProjectHookContext,
   ScheduleHookContext,
@@ -243,6 +246,7 @@ export type {
   ServerSpec,
   TaskExecutor,
   TaskPlacement,
+  WorkerAdvice,
 } from './exec/index.js'
 
 // Telemetry — THE canonical, versioned data-export contract every exporter

package/src/orchestrator/admission.ts

@@ -186,7 +186,7 @@ export function admitTasks(
     const cacheable =
       !isGroupTask(node) &&
       node.config.exec?.persistent === undefined &&
-      node.config.cache !== undefined &&
+      node.config.cache === true &&
       canRead &&
       canWrite
     // A restore-tier task (confirmed local hit, may run before its deps)

package/src/orchestrator/command-windows.ts

@@ -1,5 +1,5 @@
 // When each command of the run ran and where it may write, so
-// `inputStability.strategy: 'mutable'` can tell a task's own identical
+// `inputs.stability.strategy: 'mutable'` can tell a task's own identical
 // rewrite from another task's write and restore (STATUS item 28): a file
 // whose bytes match the key after a write is the task's own only if no
 // other command that may write it ran between the describe and that write.

package/src/orchestrator/deferred-outputs.ts

@@ -115,7 +115,7 @@ export class DeferredOutputs {
     // 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 outputs = producer.config.outputs?.files ?? []
     const nestedProjectDirs = this.args.nestedDirsByProject.get(producer.projectName) ?? []
     const cleanArgs = {
       projectDir: producer.projectDir,

package/src/orchestrator/doctor.ts

@@ -19,8 +19,8 @@ import {
   machineMemoryBytes,
   machineParallelism,
   treeBytes,
-  ui,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
 import { vxPath } from '../handoff.js'
 import { VERSION } from '../version.js'
 import { probeSandbox, resetSandbox, untracedReason } from '../exec/index.js'

package/src/orchestrator/download-policy.ts

@@ -44,14 +44,12 @@ export function deferralEligibility(nodes: Map<string, TaskNode>): Map<string, s
     if (list) list.push({ taskId: n.id, prefixes, via })
     else readersByProject.set(n.projectName, [{ taskId: n.id, prefixes, via }])
   }
-  // A task with no `cache` block keys on its inputs, and a cached task that
+  // A task without `cache: true` keys on its inputs, and a cached task that
   // depends on it folds that key: deferring a producer there moved both
   // keys with the transfer flag. Only such a task is a reader — one nothing
   // cached folds keys nothing that lasts.
   const folded = new Set<string>()
-  const stack = [...nodes.values()]
-    .filter((n) => n.config.cache !== undefined)
-    .flatMap((n) => n.deps)
+  const stack = [...nodes.values()].filter((n) => n.config.cache === true).flatMap((n) => n.deps)
   for (let id = stack.pop(); id !== undefined; id = stack.pop()) {
     if (folded.has(id)) continue
     folded.add(id)
@@ -63,7 +61,7 @@ export function deferralEligibility(nodes: Map<string, TaskNode>): Map<string, s
     const inputs = n.config.inputs
     // A task with no inputs has no key to read; an uncached one with inputs
     // is read only for the cached tasks that fold its key.
-    if (inputs === undefined || (n.config.cache === undefined && !folded.has(n.id))) continue
+    if (inputs === undefined || (n.config.cache !== true && !folded.has(n.id))) continue
     if ((inputs?.workspaceFiles?.length ?? 0) > 0) workspaceReader ??= n.id
     // A `runtime` input is a SHELL COMMAND whose reads are unknowable —
     // the same reason vx refuses to infer inputs by tracing. It can `cat` a
@@ -86,11 +84,11 @@ export function deferralEligibility(nodes: Map<string, TaskNode>): Map<string, s
   }
 
   for (const n of nodes.values()) {
-    const outputs = n.config.cache?.outputs
+    const outputs = n.config.outputs
     if ((outputs?.workspaceFiles?.length ?? 0) > 0) {
       ineligible.set(
         n.id,
-        'declares cache.outputs.workspaceFiles — root-anchored outputs can land where any project-relative input reads',
+        'declares outputs.workspaceFiles — root-anchored outputs can land where any project-relative input reads',
       )
       continue
     }

package/src/orchestrator/excluded-keys.ts

@@ -117,7 +117,7 @@ export function excludedTaint(nodes: ReadonlyMap<string, TaskNode>): {
   let unsaved = 0
   for (const id of reached) {
     const cfg = nodes.get(id)!.config
-    if (cfg.cache !== undefined && cfg.exec?.persistent === undefined) unsaved++
+    if (cfg.cache === true && cfg.exec?.persistent === undefined) unsaved++
   }
   return { seeds, unsaved }
 }

package/src/orchestrator/execute-task.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import type { ExecConfig, TaskConfig, CacheConfig, InputStability } from '../config.js'
+import type { ExecConfig, TaskConfig, InputsConfig, InputStability } from '../config.js'
 import {
   ArtifactVanishedError,
   type CacheEntry,
@@ -58,6 +58,7 @@ import { executorLabel, nameExecutorFailure } from './plugin-host.js'
 import type { CommandWindows } from './command-windows.js'
 import {
   commandWriteReach,
+  dependencyReads,
   mayWriteFingerprint,
   type Placeholder,
   reachedWithheld,
@@ -72,6 +73,7 @@ import {
   bracketLiteralHint,
   markUnsaved,
   saveMiss,
+  unsavedOutputBytes,
   type OutputDirSnapshot,
   type SaveFacts,
 } from './miss-save.js'
@@ -182,17 +184,23 @@ export interface ExecuteArgs {
    * byte-identical with and without it.
    */
   retries?: number
+  /**
+   * Whether the run history knows the task as flaky (`knownFlaky`): a keyed
+   * task with no `retries` of its own or of the run that fails gets ONE more
+   * attempt when it does. Decided at run time, so never in the key.
+   */
+  knownFlaky?: (node: TaskNode, hash: string) => boolean
   /**
    * `run.timeout` (ms), already resolved from flag, variable and
    * workspace. Per-task `exec.timeout` wins. Never hashed.
    */
   timeout?: number
   /**
-   * The run's `inputStability` layers around the task's own: `run` from
+   * The run's `inputs.stability` layers around the task's own: `run` from
    * the env vars (above the task), `workspace` from `.vx/workspace` (below).
    */
   inputStability?: { run: InputStability; workspace?: InputStability }
-  /** `cache.outputs.clean` for tasks without their own: `.vx/workspace`. */
+  /** `outputs.clean` for tasks without their own: `.vx/workspace`. */
   cleanOutputs?: boolean
   /** Per-run memo for `git ls-files` (one entry per project dir). */
   gitFilesCache?: GitFilesCache
@@ -235,6 +243,11 @@ export interface ExecuteArgs {
    * granted a linked workspace package only when it is in this set.
    */
   keyedProjects: (node: TaskNode) => ReadonlySet<string>
+  /**
+   * The run's lookup of the tasks whose outputs a sandboxed task may read
+   * (keyed-projects.ts `readableDeps`). Absent: none.
+   */
+  readableDeps?: (node: TaskNode) => readonly TaskNode[]
   /**
    * Run-scoped list the miss path appends its output-directory snapshot
    * request to, taken at run end (run.ts) instead of right after the save:
@@ -344,7 +357,7 @@ function readsCache(args: ExecuteArgs): boolean {
   const policy = args.cachePolicy ?? FULL_CACHE_POLICY
   return (
     args.remoteOnly !== true &&
-    args.node.config.cache !== undefined &&
+    args.node.config.cache === true &&
     (policy.localRead || policy.remoteRead)
   )
 }
@@ -396,16 +409,16 @@ async function restoreOrMiss(
 
 /**
  * What a write to an input during the command means, each field highest
- * first: the env var (`layers.run`), the task's `cache.inputStability`,
+ * first: the env var (`layers.run`), the task's `inputs.stability`,
  * the workspace's, then `'immutable'` and `'warn'` (2026-10-12), so
  * by default any such write withholds the save, on CI too, since a
  * concurrent task can change an input and put it back.
  */
 function inputStabilityOf(
-  cache: CacheConfig | undefined,
+  inputs: InputsConfig | undefined,
   layers: ExecuteArgs['inputStability'],
 ): Required<InputStability> {
-  const task = cache?.inputStability
+  const task = inputs?.stability
   return {
     strategy: layers?.run.strategy ?? task?.strategy ?? layers?.workspace?.strategy ?? 'immutable',
     severity: layers?.run.severity ?? task?.severity ?? layers?.workspace?.severity ?? 'warn',
@@ -517,9 +530,9 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const { node, upstream, cache, log } = args
   const cfg: TaskConfig = node.config
   const step = cfg.exec as ExecConfig // dispatcher guarantees exec is present
-  const cacheCfg: CacheConfig | undefined = cfg.cache
+  const cfgOut = cfg.outputs
   const policy = args.cachePolicy ?? FULL_CACHE_POLICY
-  const cfgCacheable = cacheCfg !== undefined
+  const cfgCacheable = cfg.cache === true
   // We may READ when at least one read axis is on (the cache layer
   // refines local vs remote), and WRITE when at least one write axis is
   // on. Output management (clean before exec) keys off writes — so
@@ -570,8 +583,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const deferralRequested = args.download === 'deferred'
   const capture: CaptureConfig = { stdout: false, stderr: false }
 
-  const outputs = cacheCfg?.outputs.files ?? []
-  const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
+  const outputs = cfgOut?.files ?? []
+  const wsOutputs = cfgOut?.workspaceFiles ?? []
   const effectiveForwardArgs = node.requested ? (args.forwardArgs ?? []) : []
   // Per-task `exec.timeout` beats `run.timeout` (flag, variable,
   // workspace; resolved into `args.timeout` by run.ts).
@@ -734,12 +747,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const additive = (node.addsToOutputsOf?.length ?? 0) > 0
   let stampedBefore: ReadonlyMap<string, OutputStamp> | undefined
   let wsStampedBefore: ReadonlyMap<string, OutputStamp> | undefined
-  // `cache.outputs.clean: false` leaves the outputs to the first attempt's
+  // `outputs.clean: false` leaves the outputs to the first attempt's
   // command, and the save stores whatever they hold after it, a leftover
   // included: the user opted out of the clean-tree guarantee
   // (2026-10-15). A retry still starts clean. An additive task never cleans
   // by glob anyway.
-  const keepOutputs = !additive && (cacheCfg?.outputs.clean ?? args.cleanOutputs ?? true) === false
+  const keepOutputs = !additive && (cfgOut?.clean ?? args.cleanOutputs ?? true) === false
 
   // Cache lookup. On hit, time the user-perceived restore op
   // (clean+restore+log-replay) — that's what the framed-block footer
@@ -888,7 +901,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   // Cache miss path (or caching disabled), up to `1 + retries` attempts.
   // Explicit config wins over the run-level `--retries` default, including
   // an explicit `retries: 0`.
-  const maxAttempts = 1 + (step.retries ?? args.retries ?? 0)
+  const retriesSet = step.retries !== undefined || args.retries !== undefined
+  let maxAttempts = 1 + (step.retries ?? args.retries ?? 0)
   let attempt = 0
   let result: ExecuteResult
   let effectiveExitCode: number
@@ -1172,6 +1186,8 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
   const storeMask = secrets ?? undefined
   const storedOutput = (): string => encodeOutputLog(output?.chunks() ?? [], storeMask)
   const failedAttempts: { endedAt: number; exitCode: number; timedOut?: true }[] = []
+  // Each failed attempt's output, beside `failedAttempts`: kept for `vx last --log`.
+  const attemptOutputs: string[] = []
   // The sampling of the attempt's process tree, stopped once it settles.
   let untrack: (() => TreeLoad | undefined) | undefined
   // What the last attempt's samples saw, for the run history.
@@ -1210,6 +1226,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     if (a.withdrawn) {
       attempt--
       failedAttempts.pop()
+      attemptOutputs.pop()
       break
     }
     forgetUndeclaredWrites(args, writeReach)
@@ -1251,12 +1268,27 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       }
     }
 
+    // A known flake gets the one retry its config did not ask for; a
+    // timeout always fails, and a task whose key names nothing (no cache
+    // block, or keyed on a keyless upstream) has no record to know it by.
+    if (
+      effectiveExitCode !== 0 &&
+      attempt === 1 &&
+      !retriesSet &&
+      result.timedOut !== true &&
+      cfgCacheable &&
+      !keyless &&
+      args.failFast?.aborted !== true &&
+      args.knownFlaky?.(node, hash) === true
+    )
+      maxAttempts = 2
     if (effectiveExitCode === 0 || attempt >= maxAttempts || args.failFast?.aborted === true) break
     failedAttempts.push({
       endedAt: Date.now(),
       exitCode: effectiveExitCode,
       ...(result.timedOut === true ? { timedOut: true as const } : {}),
     })
+    attemptOutputs.push(output === undefined ? '' : failedOutputLog(output, true, storeMask))
     log.taskStderr(
       node,
       `${midLine ? '\n' : ''}vx: retrying ${node.id} (attempt ${attempt + 1}/${maxAttempts}) after ${result.timedOut === true ? 'a timeout' : `exit ${effectiveExitCode}`}\n`,
@@ -1284,6 +1316,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     flushMasked = () => masked?.end()
     const base: ExecuteRequest = {
       taskId: node.id,
+      ...(attempt > 1 ? { attempt } : {}),
       workspaceRoot: args.workspaceRoot,
       command: step.command,
       forwardArgs: effectiveForwardArgs,
@@ -1335,6 +1368,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
       cfgCacheable ? args.keyedProjects(node) : undefined,
       args.nestedProjectDirs,
       args.cacheDir,
+      await dependencyReads(args.readableDeps?.(node) ?? [], args.workspaceRoot),
     )
     placeholders = sb.placeholders
     withheld = sb.withheld
@@ -1343,10 +1377,12 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
 
   const wallclockEndNs = process.hrtime.bigint() - args.runStartHrTimeNs
 
-  const stability = inputStabilityOf(args.node.config.cache, args.inputStability)
+  const stability = inputStabilityOf(args.node.config.inputs, args.inputStability)
   let movedFails: string | undefined
   let own: Awaited<ReturnType<typeof ownOutputs>>
   let saved = false
+  // An unsaved miss's outputs, as a save's are counted: its row's `outputs`.
+  let unsavedBytes: number | undefined
   if (
     effectiveExitCode === 0 &&
     willSave &&
@@ -1408,7 +1444,17 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     // entry is in; without one, the save is taken as done.
     if (args.deferredSaves !== undefined) args.deferredSaves.set(node.id, landed)
     else saved = true
-  } else if (cfgCacheable && !remoteOnly && !deferralRequested && args.noDependants !== true) {
+  } else if (cfgCacheable && !remoteOnly && !deferralRequested && args.noDependants === true) {
+    // Nothing reads after it, so nothing to mark: only its row's `outputs`.
+    if (effectiveExitCode === 0)
+      unsavedBytes = await unsavedOutputBytes({
+        node,
+        workspaceRoot: args.workspaceRoot,
+        nestedProjectDirs: args.nestedProjectDirs,
+        outputs,
+        wsOutputs,
+      })
+  } else if (cfgCacheable && !remoteOnly && !deferralRequested) {
     // Ran here and saves nothing — failed, a read-only policy, a tainted
     // upstream, a key that no longer held — yet it wrote what a save would
     // have marked, and may have rewritten an input the re-check before a
@@ -1422,7 +1468,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     if (moved !== undefined) {
       forgetUndeclaredWrites(args, wsOutputs.length > 0 ? 'workspace' : 'project')
     } else {
-      await markUnsaved({
+      unsavedBytes = await markUnsaved({
         node,
         workspaceRoot: args.workspaceRoot,
         nestedProjectDirs: args.nestedProjectDirs,
@@ -1527,11 +1573,11 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     const hint =
       moved === null || rewroteBy !== undefined
         ? ''
-        : '; if the task writes it, declare it in cache.outputs'
+        : '; if the task writes it, declare it in outputs'
     if (stability.severity === 'error') {
       warnOf(log)(
         `[vx] ${node.id}: ${what} — the result is not saved, ` +
-          `and inputStability.severity is 'error', so the task fails${hint}`,
+          `and inputs.stability.severity is 'error', so the task fails${hint}`,
       )
       movedFails = moved === null ? '' : printable(relPosix(args.workspaceRoot, moved))
     } else {
@@ -1564,7 +1610,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     durationMs: spentMs,
     hash,
     ...(attempt > 1 ? { attempts: attempt } : {}),
-    ...(failedAttempts.length > 0 ? { failedAttempts } : {}),
+    ...(failedAttempts.length > 0 ? { failedAttempts, attemptOutputs } : {}),
     ...(described !== undefined
       ? { inputFiles: captured.reduce((n, c) => (c.kind === 'file' ? n + 1 : n), 0) }
       : {}),
@@ -1572,6 +1618,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     ...(unkeyed ? { unkeyed: true as const } : {}),
     ...(keylessBy !== undefined ? { keylessBy } : {}),
     ...(saved ? { saved: true as const } : {}),
+    ...(unsavedBytes !== undefined ? { outputBytes: unsavedBytes } : {}),
     ...(effectiveExitCode !== 0 && output !== undefined
       ? { failedOutput: failedOutputLog(output, willSave || args.keepRun !== undefined, storeMask) }
       : {}),

package/src/orchestrator/graph-memo.ts

@@ -12,7 +12,12 @@
 // it is never remembered.
 
 import type { FoldMemo } from '../cache/index.js'
-import { buildTaskGraph, declaredTask, type TaskNode } from '../graph/index.js'
+import {
+  buildTaskGraph,
+  computeReverseDepCount,
+  declaredTask,
+  type TaskNode,
+} from '../graph/index.js'
 import { xxh3hex } from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
 import { codeIdentity } from './run-keys.js'
@@ -138,3 +143,47 @@ function rebuilt(
   }
   return nodes
 }
+
+/**
+ * The run's dependents count, the scheduler's baseline and every row's
+ * `blocks`, read back with the graph it was counted on: the closure over a
+ * 9,603-task graph (11k nodes) was ~100 ms of every warm run, the same each
+ * time (2026-10-29). `token` names the graph's edges (`memoGraph`, undefined
+ * once anything edited them), the node ids which of them this run kept
+ * (`--affected` prunes under the same token).
+ */
+export function graphCounts(
+  nodes: ReadonlyMap<string, TaskNode>,
+  folds: FoldMemo | undefined,
+  token: string | undefined,
+): Map<string, number> {
+  if (folds === undefined || token === undefined) return computeReverseDepCount(nodes)
+  // Not `counts`: those rows held a second count the rows no longer show.
+  const id = `\0dependents\0${token}`
+  const probe = xxh3hex([...nodes.keys()].join('\0'))
+  const row = folds.get(id, probe)
+  if (row !== undefined) {
+    const back = countsOf(row, nodes)
+    if (back !== undefined) return back
+  }
+  const counts = computeReverseDepCount(nodes)
+  folds.set(id, probe, JSON.stringify([...nodes.keys()].map((k) => counts.get(k)!)))
+  return counts
+}
+
+function countsOf(
+  row: string,
+  nodes: ReadonlyMap<string, TaskNode>,
+): Map<string, number> | undefined {
+  let all: number[]
+  try {
+    all = JSON.parse(row) as number[]
+  } catch {
+    return undefined
+  }
+  if (all?.length !== nodes.size) return undefined
+  const counts = new Map<string, number>()
+  let i = 0
+  for (const id of nodes.keys()) counts.set(id, all[i++]!)
+  return counts
+}

package/src/orchestrator/graph-stage.ts

@@ -29,6 +29,12 @@ export async function applyGraphStage(
   // keyed and cleaned its outputs there: past the hard project boundary.
   const dirs = new Map(args.projectMetas.map((m) => [m.name, path.resolve(m.dir)]))
   const shown = (dir: string): string => relPosix(args.workspaceRoot, dir) || '.'
+  // The lock shares a task config two tasks declare alike: an edit in place
+  // works on this node's own copy.
+  if (plugins.some((p) => p.graph !== undefined)) {
+    for (const n of nodes.values())
+      if (!isDefaultBuild(n.config)) n.config = structuredClone(n.config)
+  }
   await applyGraphHooks(
     plugins,
     nodes,

package/src/orchestrator/hit-restore.ts

@@ -9,7 +9,6 @@
 // 2026-09-10 as pure code motion, the mirror of miss-save.ts.
 
 import path from 'node:path'
-import type { CacheConfig } from '../config.js'
 import {
   type CacheEntry,
   cleanOutputPaths,
@@ -58,9 +57,9 @@ export interface RestoreHitArgs {
 export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
   const { args, hash } = given
   const { node } = args
-  const cacheCfg: CacheConfig | undefined = node.config.cache
-  const outputs = cacheCfg?.outputs.files ?? []
-  const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
+  const cfgOut = node.config.outputs
+  const outputs = cfgOut?.files ?? []
+  const wsOutputs = cfgOut?.workspaceFiles ?? []
   const anyOutputs = outputs.length > 0 || wsOutputs.length > 0
   // A layer that handed no rows: one SELECT, read by both paths below.
   const restore =
@@ -399,8 +398,8 @@ export async function restoreHit(given: RestoreHitArgs): Promise<TaskOutcome> {
 export function currentHit(restore: RestoreHitArgs): (() => TaskOutcome) | undefined {
   const { args, hash, hit } = restore
   const { node } = args
-  const outputs = node.config.cache?.outputs.files ?? []
-  if ((node.config.cache?.outputs.workspaceFiles?.length ?? 0) > 0) return undefined
+  const outputs = node.config.outputs?.files ?? []
+  if ((node.config.outputs?.workspaceFiles?.length ?? 0) > 0) return undefined
   if (outputs.length > 0) {
     const dirPrefixes = dirPrefixesOf(outputs)
     if (dirPrefixes === null || args.cache.outputDirsCurrent === undefined) return undefined

package/src/orchestrator/index.ts

@@ -60,6 +60,7 @@ export {
   type CommandContext,
   type GraphHookContext,
   type KeyHookContext,
+  type LockedFile,
   type PluginCommand,
   type ProjectHookContext,
   type ScheduleHookContext,
@@ -78,6 +79,7 @@ export {
   type RunReport,
   type RunReportTask,
   type FingerprintChange,
+  type FingerprintDigests,
   type FingerprintClaim,
   type FingerprintContext,
   type VxPlugin,
@@ -95,6 +97,7 @@ export {
   applyScheduleHooks,
   claimedAffected,
   claimedExtraFiles,
+  claimedDigests,
   fingerprintClaims,
   hasHook,
   REMOTE_CACHE_METHODS,

package/src/orchestrator/keyed-projects.ts

@@ -63,3 +63,31 @@ export function keyedProjects(
     return below.get(root.id)!
   }
 }
+
+/**
+ * A run's lookup of the exec tasks whose outputs a sandboxed task may read:
+ * those its key folds, through a group to its members, never past an exec
+ * task. Their outputs are what their keys answer for, and this key folds
+ * those keys, so a read of them can never replay stale (the toolchain
+ * rule: a `tools` project builds Node, every dependant runs it). A
+ * dependency `inputs.tasks` leaves out is ordered, not read.
+ */
+export function readableDeps(
+  nodes: ReadonlyMap<string, TaskNode>,
+  keyOnly: ReadonlyMap<string, TaskNode> = new Map(),
+): (node: TaskNode) => readonly TaskNode[] {
+  const nodeOf = (id: string): TaskNode => nodes.get(id) ?? keyOnly.get(id)!
+  return (root) => {
+    const out = new Map<string, TaskNode>()
+    const seen = new Set<string>()
+    const stack = foldedDeps(root, nodeOf).map((c) => c.node)
+    while (stack.length > 0) {
+      const dep = stack.pop()!
+      if (seen.has(dep.id)) continue
+      seen.add(dep.id)
+      if (!isGroupTask(dep)) out.set(dep.id, dep)
+      else for (const { node } of foldedDeps(dep, nodeOf)) stack.push(node)
+    }
+    return [...out.values()]
+  }
+}

package/src/orchestrator/live-usage.ts

@@ -1,6 +1,9 @@
-// The live list's `cpu` and `mem`: what each running task's process tree
-// uses now. Looked at on a timer only once the list asks for a row, so a
-// run with no live list (a pipe, CI) registers pids and reads nothing.
+// The live list's `cpu` and `mem`: each running task's process tree's
+// average cores since it started and its peak memory so far, the values
+// its results row shows once it ends (2026-10-29: the live row showed the
+// last half second's, and a task's row changed meaning as it finished).
+// Looked at on a timer only once the list asks for a row, so a run with
+// no live list (a pipe, CI) registers pids and reads nothing.
 // The look is async and off the dispatch path: a slow one skips a tick.
 
 import { sampleTrees, type TreeUsage } from '../exec/index.js'
@@ -19,7 +22,10 @@ const everyInterval: Every = (ms, fn) => {
 
 interface Tracked {
   pid: number
-  last?: { ts: number; cpuMs: number }
+  startedAt: number
+  /** The most CPU time the tree has shown: a descendant that exits takes its share out of the sum. */
+  cpuMs: number
+  peakRssBytes: number
   now?: LiveUsage
 }
 
@@ -51,13 +57,12 @@ export function createLiveUsage(
       for (const [id, t] of entries) {
         const u = usage.get(t.pid)
         if (u === undefined || tracked.get(id) !== t) continue
-        // A descendant that exited takes its CPU out of the live sum, so
-        // an interval can read negative: none is shown below zero.
-        if (t.last !== undefined && ts > t.last.ts) {
-          const cores = Math.max(0, (u.cpuMs - t.last.cpuMs) / (ts - t.last.ts))
-          t.now = { cores: Math.round(cores * 100) / 100, rssBytes: u.rssBytes }
+        t.cpuMs = Math.max(t.cpuMs, u.cpuMs)
+        t.peakRssBytes = Math.max(t.peakRssBytes, u.rssBytes)
+        if (ts > t.startedAt) {
+          const cores = t.cpuMs / (ts - t.startedAt)
+          t.now = { cores: Math.round(cores * 100) / 100, rssBytes: t.peakRssBytes }
         }
-        t.last = { ts, cpuMs: u.cpuMs }
       }
     } catch {
       // A failed look is a missing point, never a broken run.
@@ -71,7 +76,7 @@ export function createLiveUsage(
 
   return {
     track(taskId, pid) {
-      const t: Tracked = { pid }
+      const t: Tracked = { pid, startedAt: now(), cpuMs: 0, peakRssBytes: 0 }
       tracked.set(taskId, t)
       start()
       return () => {

package/src/orchestrator/local-shortcircuit.ts

@@ -32,7 +32,7 @@
 //   - Only STABLE-key, cacheable, local-read tasks are classified. A
 //     stable miss stays in the normal (dep-gated) schedule; an unstable
 //     task is never probed here.
-//   - A task that declares `cache.outputs.workspaceFiles` (the
+//   - A task that declares `outputs.workspaceFiles` (the
 //     boundary-ignoring escape hatch) can write where a restore touches,
 //     so every task whose project directory a workspace-output glob's
 //     static prefix REACHES stays out of the restore tier, and so does
@@ -261,7 +261,7 @@ export function restoreTierExclusions(
   const prefixes: string[] = []
   let everything = false
   for (const node of nodes.values()) {
-    for (const raw of node.config.cache?.outputs.workspaceFiles ?? []) {
+    for (const raw of node.config.outputs?.workspaceFiles ?? []) {
       // A `!` entry needs no skip: its prefix (`!gen`) names no directory,
       // so it excludes nothing (A-44; the `continue` that stood here was
       // dropped in item 640).