@vzn/vx 0.0.639 → 0.0.641

package/src/orchestrator/run.ts

@@ -8,11 +8,11 @@ import { realpathSync } from 'node:fs'
 import path from 'node:path'
 import {
   Cache,
-  type CacheLayer,
   type CachePolicy,
   cachesNothing,
   formatCachePolicy,
   stopRuntimeProbes,
+  sweepStaging,
 } from '../cache/index.js'
 import { VERSION } from '../version.js'
 import {
@@ -76,9 +76,10 @@ import {
   warnOf,
 } from '../report/index.js'
 import { installPlugins, PluginSetupError, type RunReport } from './plugin.js'
-import { keepRunBytes } from './run-report.js'
+import { keepsFailures, reportOf, RunKeeper } from './run-report.js'
 import { buildAdmission, executorDemand, resolveExecutors, teardownPlugins } from './plugin-host.js'
 import { createSteps } from './steps.js'
+import { writeRunSteps } from './run-steps.js'
 import { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 import { claimOutput, guardedOutput } from './output-host.js'
 import { assembleRunSummary } from './telemetry.js'
@@ -161,17 +162,14 @@ function effectiveCachePolicy(requested: CachePolicy, hasRemoteLayer: boolean):
 /**
  * The perf firewall for the local short-circuit. Always-on; the only
  * gates are correctness/no-op gates:
- *   - LOCAL-ONLY cache. Behind a remote layer, `cache.get` is a remote
- *     READ-THROUGH — the up-front classify is awaited before scheduling,
- *     so N remote GETs would land on the critical path before any task
- *     starts. Remote runs are owned by `startRemotePrefetch`, which
- *     overlaps the GETs with execution instead (fire-and-forget) and
- *     ingests hits into local for execute-task's lazy probe. The gate asks
- *     the layer (`hasRemote`), not `instanceof LayeredCache` — a
- *     third-party remote layer stalls on the classify just as hard.
  *   - the policy reads locally (a `--no-cache`/`--force`/`--cache-policy=local:`
  *     run reads nothing locally → nothing to restore → skip);
  *   - there is at least one task.
+ * A remote layer does not close it: the local cache sits in front of every
+ * remote (#3619), so the classify probes that local store alone and a local
+ * hit runs ahead of its dependencies as it does with no remote; the remote
+ * GETs stay on `startRemotePrefetch`'s fire-and-forget path (M's solid
+ * run, 2026-10-16: a local hit waited 18 s on a dependency it never read).
  * A flat graph has no ordering to bypass, but the classify pass is worth
  * paying for anyway: it probes every stable key through ONE batched
  * `getMany` instead of a `cache.get` per task inside the run, which
@@ -179,12 +177,7 @@ function effectiveCachePolicy(requested: CachePolicy, hasRemoteLayer: boolean):
  * (2026-09-03, interleaved arms). The per-task correctness gates (stable
  * key, no workspace-outputs in graph) live in `startLocalShortCircuit`.
  */
-export function shouldShortCircuit(
-  nodes: Map<string, TaskNode>,
-  policy: CachePolicy,
-  cache: CacheLayer,
-): boolean {
-  if (cache.hasRemote === true) return false
+export function shouldShortCircuit(nodes: Map<string, TaskNode>, policy: CachePolicy): boolean {
   if (!policy.localRead) return false
   return nodes.size > 0
 }
@@ -358,7 +351,8 @@ async function runOnBus(
   takeOutput?: (claimed: { logger: Logger; owner: string }) => void,
 ): Promise<RunSummary> {
   const log = busLogger(bus)
-  const { step, stepSync } = createSteps(log, showsSteps)
+  const steps = createSteps(log, showsSteps)
+  const { step, stepSync } = steps
   // A server's output goes through a cell of its own: a later watch cycle
   // that keeps the server points it at that cycle's bus (`RunOptions.keep`).
   const serverOuts = new Map<string, { bus: EventBus }>()
@@ -448,9 +442,30 @@ async function runOnBus(
   // carries it so analytics queries can group by invocation; plugins get it
   // in their teardown's `RunReport`.
   const runId = ulid()
+  // A killed run's restore staging (`.vx/tmp/<pid>-0`), once per run.
+  sweepStaging(prepared.workspaceRoot)
   const head = captureGitContext(prepared.workspaceRoot)
   const ciContext = detectCi(process.env)
-  const keepRunLog = prepared.keepRunEntry !== undefined
+  const keepRun =
+    prepared.keepRunEntry === undefined
+      ? undefined
+      : {
+          failures: keepsFailures(
+            resolveSetting('cache.upload.failures', prepared.workspaceConfig).value,
+            ciContext.ci,
+          ),
+        }
+  const keeper =
+    prepared.keepRunEntry === undefined || keepRun === undefined
+      ? undefined
+      : new RunKeeper({
+          runId,
+          workspaceRoot: prepared.workspaceRoot,
+          nestedDirsByProject: prepared.nestedDirsByProject,
+          keep: prepared.keepRunEntry,
+          failures: keepRun.failures,
+          traffic: prepared.localCache.traffic,
+        })
   try {
     disposePlugins = await installPlugins({
       plugins: prepared.plugins,
@@ -579,6 +594,7 @@ async function runOnBus(
     onStop: () => {
       stopRuntimeProbes(hashCache.runtime, hashCache.workspaceRuntime)
       cache.stopUploads?.()
+      keeper?.stop()
     },
   })
   const { liveChildren, persistentRegistry } = stop
@@ -823,7 +839,7 @@ async function runOnBus(
     // unchanged (no upfront key pass, no local probing).
     let prefetchDone: Promise<void> = Promise.resolve()
     if (prepared.hasRemoteLayer) {
-      prefetchDone = step('vx:prefetch', () =>
+      prefetchDone = steps.background('vx:prefetch', () =>
         startRemotePrefetch({
           nodes,
           cache,
@@ -852,16 +868,22 @@ async function runOnBus(
     // An empty local cache answers every probe with a miss: each task
     // derives its key as it starts instead (~100 ms before a cold 1,090-
     // package run's first spawn), and every sandboxed task runs.
+    const remote = cache.hasRemote === true
     const coldLocal =
-      cache === prepared.localCache &&
-      shouldShortCircuit(nodes, policy, cache) &&
-      prepared.localCache.holdsNothing()
-    if (coldLocal) prewarm()
-    else if (shouldShortCircuit(nodes, policy, cache)) {
+      shouldShortCircuit(nodes, policy) && (remote || cache === prepared.localCache)
+        ? prepared.localCache.holdsNothing()
+        : false
+    // A remote may still hold what an empty local store does not: the
+    // prefetch asks it, and no confirmed miss warms the sandbox early.
+    if (coldLocal && !remote) prewarm()
+    else if (!coldLocal && shouldShortCircuit(nodes, policy)) {
       shortCircuit = await step('vx:keys', () =>
         startLocalShortCircuit({
           nodes,
-          cache,
+          // Behind a remote, the local store alone: its hits are certain
+          // now, and a local miss may still be a remote hit.
+          cache: remote ? prepared.localCache : cache,
+          localOnly: remote,
           workspaceRoot,
           claimedFiles: fingerprintWatch.names,
           forwardArgs: options.forwardArgs,
@@ -872,7 +894,8 @@ async function runOnBus(
         }),
       )
       // A confirmed miss runs too.
-      if (sandboxed.some((n) => shortCircuit.preProbed.get(n.id)?.hit === null)) prewarm()
+      if (!remote && sandboxed.some((n) => shortCircuit.preProbed.get(n.id)?.hit === null))
+        prewarm()
     }
 
     // Whether this task runs behind a failure (`continueMode: 'always'`
@@ -938,7 +961,7 @@ async function runOnBus(
     if (cleanOutputs !== undefined) scope.cleanOutputs = cleanOutputs
     if (telemetry?.track !== undefined) scope.track = telemetry.track
     if (explainMiss !== undefined) scope.explainMiss = explainMiss
-    if (keepRunLog) scope.keepRunLog = true
+    if (keepRun !== undefined) scope.keepRun = keepRun
     if (sandboxArmer !== null) scope.armSandbox = () => sandboxArmer.arm()
     const argsOf = executeArgsOf(scope, {
       log: (node) => (node.config.exec?.persistent !== undefined ? serverLog(node.id) : log),
@@ -986,11 +1009,22 @@ async function runOnBus(
     mark('classify + probe')
     // A run whose every task is a confirmed local hit dispatches only
     // restores, which no weight orders: the `schedule` stage is not asked.
+    // A plugin's later weights (`ctx.refine`) re-rank the ready queues
+    // while the graph runs; any that land before it starts, at its start.
+    let reprioritize: ((weights: ReadonlyMap<string, number>) => void) | undefined
+    let refinedEarly: ReadonlyMap<string, number> | undefined
+    let graphOver = false
     const priorities = [...nodes.values()].every(
       (n) => n.config.exec?.command === undefined || shortCircuit.restoreTier.has(n.id),
     )
       ? new Map<string, number>()
-      : await step('vx:schedule', () => prepared.priorities())
+      : await prepared.priorities({
+          step,
+          refined: (merged) => {
+            if (reprioritize !== undefined) reprioritize(merged)
+            else if (!graphOver) refinedEarly = merged
+          },
+        })
     mark('schedule')
     // Judged as each task finishes, against the history BEFORE this run's
     // rows land, so the row that prints next carries the verdict: nothing
@@ -1047,6 +1081,7 @@ async function runOnBus(
         if (cacheOff) o.cacheOff = true
         taint.settled(o)
         judgeFlaky(o)
+        keeper?.taskDone(o)
         log.taskComplete(o.node, o)
         narrowDemand(o.node.id)
       },
@@ -1070,7 +1105,7 @@ async function runOnBus(
       ...(options.continueMode !== 'always' && taintSeeds.size === 0
         ? {
             settleNow: (node: TaskNode, upstream: TaskOutcome[]) =>
-              isGroupTask(node) && node.config.cache === undefined
+              isGroupTask(node) && node.config.inputs === undefined
                 ? unkeyedGroupOutcome(
                     node,
                     keyUpstream(node, upstream),
@@ -1083,6 +1118,10 @@ async function runOnBus(
       // A `schedule` plugin's weights; the scheduler keeps its structural
       // baseline as the tie-break. Empty map → baseline only.
       ...(priorities.size > 0 ? { priorities } : {}),
+      reprioritize: (apply) => {
+        if (refinedEarly !== undefined) apply(refinedEarly)
+        reprioritize = apply
+      },
       // The baseline under them; `most-work` when the workspace names none.
       ...(options.schedule !== undefined ? { strategy: options.schedule } : {}),
       // Local short-circuit: confirmed stable local hits the scheduler
@@ -1091,6 +1130,8 @@ async function runOnBus(
       restoreTier: shortCircuit.restoreTier,
     })
     stop.graphDone()
+    reprioritize = undefined
+    graphOver = true
 
     // Which persistent children outlive the graph, and the bounded SIGTERM
     // of the rest, before the summary prints. Scoped to the real CLI
@@ -1250,22 +1291,13 @@ async function runOnBus(
     // nothing the suite could see, because this gate is the rule.
     await step('vx:uploads', async () => {
       await prefetchDone
-      await cache.drainUploads?.()
+      await Promise.all([cache.drainUploads?.(), keeper?.settled()])
     })
+    writeRunSteps(prepared.cacheDir, runId, steps.ended, warnOf(log))
     // 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))
-    const report = await step('vx:keep-run', () =>
-      keepRunBytes(list, {
-        runId,
-        commit: head.commitSha,
-        ciRun: ciContext,
-        ok,
-        workspaceRoot: prepared.workspaceRoot,
-        nestedDirsByProject: prepared.nestedDirsByProject,
-        keep: prepared.keepRunEntry,
-      }),
-    )
+    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
     // whole block is skipped and the run is byte-identical to before.
@@ -1285,7 +1317,7 @@ async function runOnBus(
       })
       telemetry.emitSummary(summary)
       const sinks = telemetry
-      await step('vx:telemetry', () => sinks.flush())
+      await sinks.flush(step)
     }
     // End-of-run plugin lifecycle: each plugin's teardown(). Crash-isolated
     // + time-bounded inside teardownPlugins, so a faulty plugin can neither
@@ -1477,7 +1509,7 @@ function noneAffected(prepared: PreparedRun, options: RunOptions): string {
  * task. Used by `--dry`.
  *
  * Side-effects are limited to opening + closing the local Cache handle
- * (and running `cache.inputs.runtime` probe commands, which key
+ * (and running `inputs.runtime` probe commands, which key
  * derivation requires). Cache probing is the byte-free `cache.has()`
  * existence check — no artifact download, no ingest, no accessed_at bump.
  */
@@ -1575,7 +1607,7 @@ async function planRestorable(
   const serves = [...nodes.values()].some(
     (n) => n.config.exec?.persistent !== undefined && !n.requested && n.surfaced !== true,
   )
-  if (!serves || !shouldShortCircuit(nodes, policy, prepared.cache)) return {}
+  if (!serves || !shouldShortCircuit(nodes, policy)) return {}
   const keptOut = restoreTierExclusions(nodes, prepared.workspaceRoot)
   const stable = await deriveStableKeys({
     nodes,

package/src/orchestrator/sandbox-fix.ts

@@ -85,7 +85,7 @@ export function sandboxFix(
   projectDir: string,
   mask: (text: string) => string = (t) => t,
   /**
-   * The task's `cache.inputs.files`, undefined when it does not cache: a
+   * The task's `inputs.files`, undefined when it does not cache: a
    * write under one is granted exactly, and a read of the project no glob
    * matches is named for the key too.
    */

package/src/orchestrator/sandbox-request.ts

@@ -163,7 +163,7 @@ export function prepareSandbox(nodes: Iterable<TaskNode>): SandboxArmer | null {
  * cached path (through the executor) and the persistent path (spawned here).
  *
  * The user's grants derive NOTHING from `cache` (owner, 2026-09-05). Those
- * are two different questions: `cache.inputs` says what INVALIDATES the
+ * are two different questions: `inputs` says what INVALIDATES the
  * task, `sandbox.allow` says what it may TOUCH. Deriving one from the other
  * coupled them in both directions — a declaration added for caching
  * silently widened the sandbox, and a path the task needed had to be
@@ -476,7 +476,7 @@ export function withheldLinkLine(taskId: string, w: WithheldLink): string {
     `${w.name}, so an edit there would not re-run it. Add a \`dependsOn\` edge that ` +
     `reaches one (\`^build\` where ${w.name}#build keys its sources, or a \`source\` task: ` +
     `\`${w.name}#source\`), or grant and key the files yourself (\`allow.read\` plus ` +
-    `\`cache.inputs.workspaceFiles\`).`
+    `\`inputs.workspaceFiles\`).`
   )
 }
 

package/src/orchestrator/stable-keys.ts

@@ -5,13 +5,19 @@
 // out so the two callers can never drift on the stability gate.
 //
 // A task's key is "stable" only if its inputs can't be altered by an
-// upstream's outputs (a `cache.inputs.files` glob that could match a
+// upstream's outputs (a `inputs.files` glob that could match a
 // sibling's declared output has a PRELIMINARY key until that upstream
 // runs — probing it would target the wrong artifact). Unstable tasks
 // fall back to lazy read-through in execute-task, which is always
 // correct. The check is conservative: when unsure, treat as unstable.
 
-import { isGroupTask, outputTakenBack, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import {
+  foldedDeps,
+  isGroupTask,
+  outputTakenBack,
+  type TaskNode,
+  type TaskOutcome,
+} from '../graph/index.js'
 import type { CacheLayer, GitFilesCache } from '../cache/index.js'
 import {
   checkIgnore,
@@ -23,7 +29,6 @@ import {
   wholeIgnored,
 } from '../util/index.js'
 import { commandWriteReach, mayWriteFingerprint, undeclaredWriteReach } from './sandbox-request.js'
-import { foldedDeps } from './keyed-projects.js'
 import {
   computeGroupHash,
   computeTaskHash,
@@ -129,12 +134,12 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
   const unfoldedById = new Map<string, ProjectSet>()
   const wsRewriters = new Set<string>()
   // A cached rewriter matters only to a key that leaves a dependency's key
-  // out: a `cache.inputs.tasks` filter. With none in the graph every edge
+  // out: a `inputs.tasks` filter. With none in the graph every edge
   // folds and the sets above stay empty, so they are not built (about 2 ms,
   // median, of a 27 ms memoised walk over the 3,000-task bench; item 750).
   let anyUnfolded = false
   for (const n of args.nodes.values()) {
-    if (n.config.cache?.inputs?.tasks !== undefined) {
+    if (n.config.inputs?.tasks !== undefined) {
       anyUnfolded = true
       break
     }
@@ -241,7 +246,7 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
       // cascade (and forward their producers, above). They inherit
       // instability from any unstable member.
       // `computeGroupKey`, with the unkeyed branch kept synchronous.
-      if (node.config.cache === undefined) {
+      if (node.config.inputs === undefined) {
         const key = computeGroupHash(upstream)
         keyById.set(id, key)
         args.groupKeys?.set(id, { key, upstream })
@@ -293,9 +298,8 @@ export async function deriveStableKeys(args: DeriveStableKeysArgs): Promise<Stab
 
     const cacheEnabled = node.config.cache !== undefined
     if (cacheEnabled && !unstable) stableKeys.push({ hash, node })
-    // An uncached key reads its whole project, so `dependsOnSiblingOutputs`
-    // (which answers false for it) is not the gate: any upstream that may
-    // write into this project, or anywhere, leaves the key preliminary.
+    // An uncached key stays preliminary behind any upstream that may write
+    // into this project, or anywhere: none of its writes is declared.
     else if (
       !cacheEnabled &&
       !unstable &&
@@ -332,7 +336,7 @@ export function gatedOutputs(
   }
   if (outputsOf.size === 0) return out
   for (const n of nodes.values()) {
-    const inputs = n.config.cache?.inputs?.files
+    const inputs = n.config.inputs?.files
     const outputs = outputsOf.get(n.projectName)
     if (inputs === undefined || outputs === undefined || isGroupTask(n)) continue
     let back: string[] | undefined
@@ -396,7 +400,7 @@ function readableOutputs(
 const probesAfterWritesOf = new WeakMap<ReadonlyMap<string, TaskNode>, ReadonlySet<string>>()
 
 /**
- * The cached tasks whose `cache.inputs.runtime` / `workspaceRuntime` probes
+ * The cached tasks whose `inputs.runtime` / `workspaceRuntime` probes
  * may read what an upstream writes this run while the key folds nothing of
  * that upstream (X-34). A probe is a shell command and may read anywhere,
  * so no glob bounds it, and its answer taken before the writer ran is the
@@ -424,8 +428,8 @@ export function probesAfterWrites(
   const late = new Set<string>()
   probesAfterWritesOf.set(nodes, late)
   const probes = (n: TaskNode): boolean =>
-    (n.config.cache?.inputs?.runtime?.length ?? 0) > 0 ||
-    (n.config.cache?.inputs?.workspaceRuntime?.length ?? 0) > 0
+    (n.config.inputs?.runtime?.length ?? 0) > 0 ||
+    (n.config.inputs?.workspaceRuntime?.length ?? 0) > 0
   let anyProbe = false
   for (const n of nodes.values()) {
     if (probes(n)) {
@@ -455,7 +459,7 @@ export function probesAfterWrites(
     let writer = false
     let unfolded = false
     // No filter and no order-only edge: the key folds every dependency.
-    const foldsAll = node.orderOnly === undefined && node.config.cache?.inputs?.tasks === undefined
+    const foldsAll = node.orderOnly === undefined && node.config.inputs?.tasks === undefined
     let folds: Set<string> | undefined
     for (const dep of node.deps) {
       if (!nodes.has(dep)) continue
@@ -483,7 +487,7 @@ function foldedBy(
   upstream: TaskOutcome[],
   keyById: Map<string, string>,
 ): (dep: string) => boolean {
-  const filter = node.config.cache?.inputs?.tasks
+  const filter = node.config.inputs?.tasks
   if (isGroupTask(node) || filter === undefined) return (dep) => keyById.has(dep)
   const hashes = new Set(
     filterUpstreamHashes(upstream, filter, node.projectName, node.id).map(([, h]) => h),
@@ -525,7 +529,7 @@ function synthUpstream(
  *     `outputs.files` — direct or transitive — makes the key
  *     preliminary. Project boundaries are hard, so only SAME-project
  *     outputs can reach a project-relative input.
- *   - `cache.inputs.workspaceFiles` is boundary-free: it can read ANY
+ *   - `inputs.workspaceFiles` is boundary-free: it can read ANY
  *     project's dir (so any upstream `outputs.files`, in any project,
  *     matters) or a root-anchored location (so any upstream
  *     `outputs.workspaceFiles` matters). Either → preliminary key. This
@@ -551,9 +555,9 @@ export function dependsOnSiblingOutputs(
   },
 ): boolean {
   const cache = node.config.cache
-  // A cache-disabled task has no key to prefetch anyway; treat as
-  // unstable-irrelevant (caller filters on cacheEnabled).
-  if (cache === undefined) return false
+  const declared = node.config.inputs
+  // A task with no inputs has no key to take up front.
+  if (declared === undefined) return false
   if (upstreamOutputProjects.has(node.projectName)) {
     // A same-project producer whose writes are all declared reaches this
     // task's inputs only where the globs can meet: a `test` reading `src/**`
@@ -562,15 +566,21 @@ export function dependsOnSiblingOutputs(
     // projects (A-20). Undeclared writes, and a rewriter this key does not
     // fold, may land anywhere: those stay project-wide.
     if (sameProject === undefined || sameProject.wide?.has(node.projectName) === true) return true
-    const inputs = cache.inputs?.files
+    const inputs = declared.files
     const outputs = sameProject.outputsOf.get(node.projectName) ?? []
-    if (inputs === undefined || outputs.length === 0) return true
+    if (outputs.length === 0) return true
     // An output the reader's own `!` inputs take back whole is not in its
     // key: `['**/*', '!dist/**']` beside a `dist/**` producer keys the same
-    // before and after it, which is what `run.rules.upfrontKeys` asks a config
-    // to write (X-54).
+    // before and after it, which is what `vx lock` asks a config to write
+    // (X-54).
     // Nor is an output git ignores whole: a key reads only what git lists.
-    const readable = sameProject.readableOf?.get(node.projectName) ?? outputs
+    // Unless an entry starts inside it (`dist/**`): naming an ignored path
+    // makes it an input (`ignoredReach` in cache/inputs.ts).
+    const readable = withNamedIgnored(
+      inputs,
+      outputs,
+      sameProject.readableOf?.get(node.projectName) ?? outputs,
+    )
     const back = inputs.filter((g) => g.startsWith('!')).map((g) => g.slice(1))
     const reach = back.length === 0 ? readable : readable.filter((o) => !outputTakenBack(o, back))
     if (reach.length > 0 && workspaceInputsReach(inputs, reach.map(literalPrefix))) return true
@@ -578,7 +588,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 = cache?.outputs.files ?? []
     if (own.length > 0) {
       const others = [...outputs]
       for (const g of own) {
@@ -597,7 +607,7 @@ export function dependsOnSiblingOutputs(
   // `app` read `gen/**` project-relative), so the mere presence of a
   // workspace-output producer upstream makes the key preliminary.
   if (hasWsOutputUpstream) return true
-  const wsInputs = cache.inputs?.workspaceFiles ?? []
+  const wsInputs = declared.workspaceFiles ?? []
   if (wsInputs.length > 0 && upstreamOutputProjects.size > 0) {
     // Without the dirs the old answer stands: a workspace reader over any
     // producer is preliminary. With them, only a reader whose globs can
@@ -617,6 +627,29 @@ export function dependsOnSiblingOutputs(
   return false
 }
 
+/**
+ * `readable`, plus each output git ignores whole that a positive entry of
+ * `inputs` starts inside: its literal prefix at or below the output's.
+ */
+function withNamedIgnored(
+  inputs: readonly string[],
+  outputs: readonly string[],
+  readable: readonly string[],
+): readonly string[] {
+  if (readable.length === outputs.length) return readable
+  const named = outputs.filter((o) => {
+    if (readable.includes(o)) return false
+    const at = literalPrefix(o)
+    if (at === '') return false
+    return inputs.some((g) => {
+      if (g.startsWith('!')) return false
+      const p = literalPrefix(g)
+      return p === at || p.startsWith(`${at}/`)
+    })
+  })
+  return named.length === 0 ? readable : [...readable, ...named]
+}
+
 /**
  * Can any positive `workspaceFiles` entry match a path inside one of
  * `dirs` (workspace-relative project dirs)? An entry's reach is its

package/src/orchestrator/steps.ts

@@ -3,25 +3,45 @@
 // `:teardown`. `:` is no task id's separator, so a step never collides with
 // a project named `vx` or a plugin package's own `#setup` task. A step is
 // not a task: no stat, history row or telemetry record counts it.
+//
+// A run shows only the steps it waits on, before its first task or its end
+// (M, 2026-10-16). One that runs beside the tasks (`vx:prefetch`) is a
+// `background` step: never shown, and kept for `vx last` (run-steps.ts).
 import type { Logger } from '../report/index.js'
+import type { RunStep } from './run-steps.js'
 
 export interface Steps {
   /** Time `work` as step `id` when steps show; else run it as it is. */
   step<T>(id: string, work: () => Promise<T>): Promise<T>
   stepSync<T>(id: string, work: () => T): T
-}
-
-const unseen: Steps = {
-  step: (_id, work) => work(),
-  stepSync: (_id, work) => work(),
+  /** Time `work`, which the run does not wait on, as step `id` into `background`. */
+  background<T>(id: string, work: () => Promise<T>): Promise<T>
+  /** The background steps that have ended. */
+  readonly ended: readonly RunStep[]
 }
 
 /** Steps that tell `log`, or none when nothing renders them (zero cost). */
 export function createSteps(log: Logger, shown: boolean): Steps {
-  if (!shown) return unseen
+  const ended: RunStep[] = []
+  // Timed whether or not anything shows: only a run with a remote starts one.
+  const background = async <T>(id: string, work: () => Promise<T>): Promise<T> => {
+    const t0 = performance.now()
+    let ok = false
+    try {
+      const value = await work()
+      ok = true
+      return value
+    } finally {
+      ended.push({ id, durationMs: Math.round(performance.now() - t0), ok })
+    }
+  }
+  if (!shown)
+    return { step: (_id, work) => work(), stepSync: (_id, work) => work(), background, ended }
   const end = (id: string, t0: number, ok: boolean): void =>
     log.stepEnd?.(id, { durationMs: performance.now() - t0, ok })
   return {
+    background,
+    ended,
     async step(id, work) {
       const t0 = performance.now()
       log.stepStart?.(id)