@vzn/vx 0.0.638 → 0.0.639

package/src/orchestrator/plan.ts

@@ -1,6 +1,6 @@
 // Planning: walk the task graph, compute every task's cache key, and
 // probe the cache to predict what would happen if `vx run` actually
-// ran. Used by `--dry-run` (preview output) and `--graph` (DOT export).
+// ran. Used by `--dry`.
 //
 // No TASK execution happens: no task spawn, no cleanOutputs, no
 // restoreOutputs. Cache probing uses the byte-free `cache.has()`
@@ -13,10 +13,10 @@
 
 import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
 import { cachesNothing, FULL_CACHE_POLICY } from '../cache/index.js'
-import { ranNoCache } from './events.js'
+import { ranNoCache } from '../report/index.js'
 import { idleServers, isGroupTask, runGraph, type TaskNode } from '../graph/index.js'
 import type { AffectedReason } from './affected-tasks.js'
-import type { HistoryProvider } from './history.js'
+import type { HistoryProvider } from '../history/index.js'
 import { computeGroupKey, computeTaskHash } from './task-hash.js'
 import { keyedOutcome, keyUpstream } from './upstream.js'
 
@@ -139,6 +139,9 @@ export interface PlanArgs {
  */
 export async function plan(args: PlanArgs): Promise<RunPlan> {
   const cacheStatusById = new Map<string, CacheStatus>()
+  // Keyed first, probed after: a remote that can batch (`hasMany`) is
+  // asked once for every key, one that cannot is asked per key.
+  const probed = new Map<string, string>()
 
   const outcomes = await runGraph({
     nodes: args.nodes,
@@ -176,13 +179,23 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
       } else if (!reads) {
         status = 'miss'
       } else {
-        const where = await args.cache.has(hash)
-        status = where === null ? 'miss' : where === 'remote' ? 'hit-remote' : 'hit-local'
+        probed.set(node.id, hash)
+        return keyedOutcome(node, hash)
       }
       cacheStatusById.set(node.id, status)
       return keyedOutcome(node, hash)
     },
   })
+  if (probed.size > 0) {
+    await args.cache.remoteHasMany?.([...new Set(probed.values())])
+    for (const [id, hash] of probed) {
+      const where = await args.cache.has(hash)
+      cacheStatusById.set(
+        id,
+        where === null ? 'miss' : where === 'remote' ? 'hit-remote' : 'hit-local',
+      )
+    }
+  }
 
   if (args.restorable !== undefined) {
     const restoreTier = new Set(

package/src/orchestrator/plugin-host.ts

@@ -10,13 +10,12 @@
 import path from 'node:path'
 import {
   type Cache,
-  ChainedCache,
   type CacheLayer,
   type CachePolicy,
   LayeredCache,
   absentPluginCache,
   type PluginCache,
-  type PluginCacheRemote,
+  type ResolvedRemote,
 } from '../cache/index.js'
 import { localExecutor, type TaskExecutor } from '../exec/index.js'
 import { maskedLine, settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
@@ -485,70 +484,39 @@ export interface CacheHost extends CacheContext {
   readonly localCache: Cache
   readonly policy: CachePolicy
   /** Filled with each remote and what its policy lets it do, for the plugins' `ctx.cache`. */
-  readonly remotes?: PluginCacheRemote[]
+  readonly remotes?: ResolvedRemote[]
 }
 
 /**
  * Collect every plugin's remote (`cache` hook) in declaration order and
  * layer each over the local store: a lookup asks the local store first,
  * then each remote in order (owner, 2026-10-13), and a save reaches every
- * remote. The run's policy, narrowed by a remote's `access`, and its scope
- * gate each remote; a remote's throw is a miss and a warning naming its
- * plugin. No remote → the local store alone.
+ * remote. The run's policy, narrowed by a remote's `access`, gates each
+ * remote; a remote's throw is a miss and a warning naming its plugin. No
+ * remote → the local store alone.
  */
 export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
   const { localCache, policy, remotes, ...ctx } = host
-  const layers: CacheLayer[] = []
-  const owners: string[] = []
+  const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
     const remote = await safe(plugin, 'cache', () => plugin.cache!(ctx))
     if (remote === undefined) continue
-    // The hook returned a whole layer until 0.0.637: name the fix, not the
-    // three methods such a layer happens to have.
-    if (isRecordLike(remote) && typeof remote['restoreOutputs'] === 'function') {
-      throw new UserError(
-        `plugin '${plugin.name}' returned a cache layer from cache: since vx 0.0.637 the hook ` +
-          'returns the remote alone (a RemoteCacheLayer: has, get, put) and core layers it over ' +
-          'the local cache — return the remote you passed to LayeredCache',
-      )
-    }
     assertShape(plugin, 'cache', remote, REMOTE_CACHE_METHODS, 'a remote cache layer')
     const access = remote.access
-    const own: CachePolicy = {
-      ...policy,
-      remoteRead: policy.remoteRead && access?.read !== false,
-      remoteWrite: policy.remoteWrite && access?.write !== false,
+    const entry: ResolvedRemote = {
+      remote,
+      read: policy.remoteRead && access?.read !== false,
+      write: policy.remoteWrite && access?.write !== false,
+      onError: (err) => ctx.warn(`[vx] plugin '${plugin.name}': ${err.message}`),
     }
-    remotes?.push({ remote, read: own.remoteRead, write: own.remoteWrite })
-    layers.push(
-      new LayeredCache(localCache, remote, {
-        policy: own,
-        onRemoteError: (err) => ctx.warn(`[vx] plugin '${plugin.name}': ${err.message}`),
-      }),
-    )
-    owners.push(`the cache layer of plugin '${plugin.name}'`)
+    resolved.push(entry)
+    remotes?.push(entry)
   }
-  if (layers.length === 0) return localCache
-  if (layers.length === 1) return layers[0]!
-  // One line per layer and method: a layer that throws on every lookup
-  // would otherwise print once per task.
-  const told = new Set<string>()
-  return new ChainedCache(layers, (i, method, err) => {
-    if (told.has(`${i}\0${method}`)) return
-    told.add(`${i}\0${method}`)
-    const m = err instanceof Error ? err.message : String(err)
-    const then =
-      method === 'save' ? 'the other layers still save' : 'a miss there; the next layer answers'
-    ctx.warn(`[vx] ${owners[i]} failed in cache ${method}: ${m}; ${then}`)
-  })
-}
-
-function isRecordLike(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null
+  return resolved.length === 0 ? localCache : new LayeredCache(localCache, resolved)
 }
 
 /** The plugin each resolved executor came from, so a hook of it that throws is named. */
@@ -581,6 +549,55 @@ export function executorLabel(executor: TaskExecutor): string {
     : `plugin '${plugin}' (executor '${executor.name}')`
 }
 
+/**
+ * Demand: what each executor still has left to run. An executor that
+ * provisions per task (a container, an allocation, a pod) otherwise has to
+ * guess from `capacity` alone and hold everything until teardown. Built
+ * ONLY for executors that asked: with none declared there is no map, no
+ * set, and the returned narrower does nothing.
+ *
+ * The SAME set is handed back every time, narrowed in place: a consumer
+ * reading it later sees the truth rather than a stale snapshot. A hint,
+ * as `admit` is: one that throws is named once and asked no more, where
+ * it surfaced as a bare stack, or mid-run from the completion path
+ * (item 1022). Returns the call that drops a finished task's id.
+ */
+export function executorDemand(
+  placed: ReadonlyMap<string, TaskExecutor>,
+  warn: (message: string) => void,
+): (id: string) => void {
+  const demandOf = new Map<TaskExecutor, Set<string>>()
+  for (const [id, executor] of placed) {
+    if (executor.demand === undefined) continue
+    let remaining = demandOf.get(executor)
+    if (remaining === undefined) demandOf.set(executor, (remaining = new Set()))
+    remaining.add(id)
+  }
+  if (demandOf.size === 0) return () => {}
+  const tell = (executor: TaskExecutor, remaining: ReadonlySet<string>): void => {
+    const failed = (err: unknown): void => {
+      if (!demandOf.delete(executor)) return
+      const m = err instanceof Error ? err.message : String(err)
+      warn(`[vx] ${executorLabel(executor)} failed in demand: ${m}; not asked again this run`)
+    }
+    try {
+      // An `async demand` that rejects did so where no one listened: an
+      // unhandled rejection, a stack, the run killed. Its rejection is a
+      // throw like any other.
+      const ret: unknown = executor.demand!(remaining)
+      if (ret instanceof Promise) ret.catch(failed)
+    } catch (err) {
+      failed(err)
+    }
+  }
+  for (const [executor, remaining] of demandOf) tell(executor, remaining)
+  return (id) => {
+    for (const [executor, remaining] of demandOf) {
+      if (remaining.delete(id)) tell(executor, remaining)
+    }
+  }
+}
+
 /**
  * Collect every plugin's `executor`, in declaration order, with core's
  * own appended at the tail: per task, `selectExecutor` takes the first
@@ -638,12 +655,15 @@ export async function teardownPlugins(
   plugins: readonly VxPlugin[],
   warn: (message: string) => void,
   report?: RunReport,
+  step: <T>(id: string, work: () => Promise<T>) => Promise<T> = (_id, work) => work(),
 ): Promise<void> {
   for (const plugin of plugins) {
     if (plugin.teardown === undefined) continue
     const ms = teardownTimeoutMs()
     try {
-      const settled = await settleWithin(Promise.resolve(plugin.teardown(report)), ms)
+      const settled = await step(`${plugin.name}:teardown`, () =>
+        settleWithin(Promise.resolve(plugin.teardown?.(report)), ms),
+      )
       // Same rule as the flush above. A teardown that never settles has left
       // whatever it owns un-released, and the run exits anyway — silence would
       // present that as a clean shutdown.

package/src/orchestrator/plugin.ts

@@ -22,10 +22,9 @@ import type { TaskExecutor } from '../exec/index.js'
 import type { TaskNode, TaskOutcome, TaskStatus } from '../graph/index.js'
 import { maskedLine, nearest, UserError } from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
-import type { EventBus, RunStartInfo } from './events.js'
+import type { EventBus, Logger, RunStartInfo } from '../report/index.js'
 import type { CiContext } from './run-context.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
-import type { Logger } from './logger.js'
 
 /**
  * A vx plugin. Contributes any subset of the run-level capabilities —
@@ -462,12 +461,10 @@ export interface CacheContext extends BaseContext {
 }
 
 export interface OutputContext extends BaseContext {
-  /** Core would write to a terminal: stdout (stderr under `json`) is a TTY. */
+  /** Core would write to a terminal: stdout is a TTY. */
   readonly isTTY: boolean
   /** The run is on CI (`CI` set, or a provider core detects). */
   readonly ci: boolean
-  /** `--format json`: stdout carries the machine-readable result. */
-  readonly json: boolean
 }
 
 export interface ExecutorContext extends BaseContext {
@@ -688,6 +685,8 @@ export interface InstallPluginsArgs {
   ci?: boolean
   /** Default null. */
   branch?: string | null
+  /** Each setup as the step `<plugin>:setup`; default: untimed. */
+  step?: <T>(id: string, work: () => Promise<T>) => Promise<T>
 }
 
 /**
@@ -824,7 +823,8 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
     }
 
     try {
-      await plugin.setup(ctx)
+      if (args.step === undefined) await plugin.setup(ctx)
+      else await args.step(`${plugin.name}:setup`, async () => plugin.setup?.(ctx))
     } catch (err) {
       // Earlier plugins' subscriptions too: the caller never gets the
       // disposer, and a bus that outlives the run would keep them.

package/src/orchestrator/prepare.ts

@@ -24,7 +24,7 @@ import {
   putRunEntry,
   writesRunStore,
   type PluginCache,
-  type PluginCacheRemote,
+  type ResolvedRemote,
   ScopedCache,
   applyGitEnumeration,
   gitPathspecs,
@@ -78,9 +78,10 @@ import { applyGraphStage } from './graph-stage.js'
 import { keyExcludedDependencies } from './excluded-keys.js'
 import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
+import { askIgnoredOutputs, gatedOutputs } from './stable-keys.js'
 import { currentBranch } from './run-context.js'
 import { createHashCache, type HashCache } from './task-hash.js'
-import type { Logger } from './logger.js'
+import { type Logger, warnOf } from '../report/index.js'
 import type { RunOptions } from './options.js'
 import { refuseFiltersThroughGroups } from './upstream.js'
 import { runRules } from '../settings.js'
@@ -241,9 +242,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     (reused !== undefined ? gitOfDiscovery(reused.projects) : undefined) ??
     lazyGitEnumeration(workspaceRoot)
   if (wholeTree) void git.start()
-  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, (m) =>
-    log.status(m),
-  )
+  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warnOf(log))
   mark('workspace config')
   let learnedBranch: string | null | undefined
   const branch = (): string | null =>
@@ -263,14 +262,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   const projectMetas =
     reused !== undefined
       ? reused.projects
-      : await discoverProjects(
-          workspaceRoot,
-          readLock,
-          plugins,
-          cacheDir,
-          (m) => log.status(m),
-          git,
-        )
+      : await discoverProjects(workspaceRoot, readLock, plugins, cacheDir, warnOf(log), git)
   mark('discover projects')
 
   // SCOPED config loading: configs are programs, and evaluating 1090
@@ -368,7 +360,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     projectMetas,
     packageGraph,
     configs: readLock,
-    warn: (m: string) => log.status(m),
+    warn: warnOf(log),
   }
   let loaded: LoadedProjects
   try {
@@ -464,21 +456,22 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // winning prevents double-wrapping when the workspace also declares a
   // cache plugin.
   let cache: CacheLayer
-  const remotes: PluginCacheRemote[] = []
+  const remotes: ResolvedRemote[] = []
   if (options.remoteCache) {
-    const { remoteCache } = options
-    remotes.push({ remote: remoteCache, read: policy.remoteRead, write: policy.remoteWrite })
+    remotes.push({
+      remote: options.remoteCache,
+      read: policy.remoteRead,
+      write: policy.remoteWrite,
+      onError: (err) => warnOf(log)(`[vx] remote cache: ${err.message}`),
+    })
   }
   try {
     cache = options.remoteCache
-      ? new LayeredCache(localCache, options.remoteCache, {
-          policy,
-          onRemoteError: (err) => log.status(`[vx] remote cache: ${err.message}`),
-        })
+      ? new LayeredCache(localCache, remotes)
       : await resolveCache(plugins, {
           workspaceRoot,
           cacheDir,
-          warn: (m) => log.status(m),
+          warn: warnOf(log),
           scope: cacheScope,
           localCache,
           policy,
@@ -489,7 +482,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     // refused by name; the local handle opened above must not leak with it,
     // nor what another plugin's factory opened: the factories have run
     // (C-4, item 1029's contract).
-    await teardownPlugins(plugins, (m) => log.status(m))
+    await teardownPlugins(plugins, warnOf(log))
     localCache.close()
     throw err
   }
@@ -581,7 +574,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         workspaceRoot,
         cacheDir,
         projectMetas,
-        warn: (m) => log.status(m),
+        warn: warnOf(log),
         rules: graphRules,
       })
     // `--affected` selects over the FINAL graph: an edge or an input a
@@ -678,11 +671,16 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       if ((n.config.cache?.inputs.workspaceFiles?.length ?? 0) > 0) usesWorkspaceInputs = true
     }
     const projectDirs = [...graphDirs]
-    const enumeration = await (git.started ??
+    const enumerating =
+      git.started ??
       startGitEnumeration(
         workspaceRoot,
         gitPathspecs(workspaceRoot, projectDirs, usesWorkspaceInputs),
-      ))
+      )
+    // While git walks: the gate's pass over every task cost 2-8 ms at
+    // 1,000 projects when it ran before the spawn.
+    const settleIgnored = askIgnoredOutputs(gatedOutputs(nodes, workspaceRoot), workspaceRoot)
+    const enumeration = await enumerating
     await applyGitEnumeration(
       enumeration,
       workspaceRoot,
@@ -691,6 +689,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       usesWorkspaceInputs,
       localCache,
     )
+    await settleIgnored(gitFilesCache)
     mark('git enumeration')
     if (hasGraphHook && !hooksFirst) await graphStage()
     // Args after `--` go to requested commands only; with none among them
@@ -706,7 +705,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       }
     }
     if (hasHook(plugins, 'key')) {
-      await applyKeyHooks(plugins, nodes, { workspaceRoot, cacheDir, warn: (m) => log.status(m) })
+      await applyKeyHooks(plugins, nodes, { workspaceRoot, cacheDir, warn: warnOf(log) })
     }
     refuseFiltersThroughGroups(nodes)
     const exclude = options.excludeDependencies
@@ -752,7 +751,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
             {
               workspaceRoot,
               cacheDir,
-              warn: (m) => log.status(m),
+              warn: warnOf(log),
               localCache,
               branch: branch(),
             },
@@ -790,7 +789,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       empty: nodes.size === 0 ? 'empty-graph' : null,
     }
   } catch (err) {
-    await teardownPlugins(plugins, (m) => log.status(m))
+    await teardownPlugins(plugins, warnOf(log))
     cache.close()
     throw err
   }

package/src/orchestrator/remote-prefetch.ts

@@ -41,6 +41,11 @@ export interface PrefetchArgs {
   concurrency: number
   /** When false (remote reads disabled), no prefetch fires. */
   remoteRead: boolean
+  /**
+   * With reads off and writes on (`--force`), the keys go to
+   * `probeBeforeUpload` instead, so a key a remote holds is not re-sent.
+   */
+  remoteWrite: boolean
 }
 
 /**
@@ -55,7 +60,15 @@ export interface PrefetchArgs {
  * is always correct.
  */
 export function startRemotePrefetch(args: PrefetchArgs): Promise<void> {
-  if (!args.remoteRead) return Promise.resolve()
+  if (!args.remoteRead) {
+    if (!args.remoteWrite || args.cache.probeBeforeUpload === undefined) return Promise.resolve()
+    const hashes = deriveStableKeys(args).then((keys) => [...new Set(keys.map((k) => k.hash))])
+    args.cache.probeBeforeUpload(hashes)
+    return hashes.then(
+      () => {},
+      () => {},
+    )
+  }
   // Detached from EXECUTION: the caller does NOT await this before
   // scheduling, so prefetch network latency overlaps the run. But the
   // caller DOES await the returned handle before closing the cache, so

package/src/orchestrator/run-artifacts.ts

@@ -1,182 +1,10 @@
-// Optional per-run output artifacts:
-//
-//   --summarize[=<path>] → JSON describing every task's outcome
-//                          (id, status, exit code, durations, hash,
-//                          cpu_ms, peak_rss_bytes, hrtime spans).
-//                          Default path: <cacheDir>/runs/<run_id>.json.
-//
-//   --profile[=<path>]   → Chrome-trace JSON of the run. Each task is
-//                          a single complete event (`ph: 'X'`) with
-//                          ts / dur in microseconds derived from the
-//                          hrtime spans the runner already captures.
-//                          Default path: profile.json (cwd-relative).
-//
-// Both are no-ops if the corresponding RunOptions field is undefined.
+// `--profile[=<path>]`: Chrome-trace JSON of the run. Each task is a single
+// complete event (`ph: 'X'`) with ts / dur in microseconds derived from the
+// hrtime spans the runner already captures. Default path: profile.json
+// (cwd-relative).
 
 import path from 'node:path'
-import { isGroupTask, type TaskOutcome } from '../graph/index.js'
-import { tallyOutcomes, type Tally } from './tally.js'
-import type { FlakyFinding } from './failure-mode.js'
-import { isCacheHit } from './telemetry.js'
-import { ranNoCache } from './events.js'
-
-export interface SummarizeArgs {
-  /** Empty string → default path; otherwise the explicit file path. */
-  target: string
-  cacheDir: string
-  cwd: string
-  runId: string
-  startedAtMs: number
-  endedAtMs: number
-  totalMs: number
-  /** The run's verdict — the same value the CLI turns into the exit code. */
-  ok: boolean
-  /** The process's exit code where it is not `ok ? 0 : 1`: a stopping signal's. */
-  exitCode?: number
-  outcomes: readonly TaskOutcome[]
-  /** What `detectFlaky` found this run; each row's flaky note, typed. */
-  flaky?: readonly FlakyFinding[]
-}
-
-/** One task of `--summarize`: the wire, stated by `schemas/summary.json`. */
-export interface SummaryTaskJson {
-  id: string
-  project: string
-  task: string
-  status: TaskOutcome['status']
-  exitCode: number
-  durationMs: number
-  hash: string | null
-  restored?: boolean
-  noCache?: true
-  flaky?: { passes: number; failures: number; attempts: number }
-  cpuMs?: number
-  peakRssBytes?: number
-  storedDurationMs?: number
-  storedCpuMs?: number
-  storedPeakRssBytes?: number
-  admissionHeldMs?: number
-  blockedBy?: string
-  timedOut?: true
-  sandboxViolations?: number
-  notReady?: 'timeout' | 'exited' | 'spawn'
-  wallclockStartNs?: string
-  wallclockEndNs?: string
-}
-
-/** The `--summarize` document. */
-export interface RunSummaryJson {
-  runId: string
-  ok: boolean
-  exitCode: number
-  startedAt: string
-  endedAt: string
-  totalMs: number
-  /** What the hits skipped: the sum of their `storedDurationMs`. */
-  savedMs: number
-  tasks: SummaryTaskJson[]
-  aborted: SummaryTaskJson[]
-  summary: Tally
-}
-
-/** One task's entry. Shared by `tasks` and `aborted` so they read alike. */
-function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): SummaryTaskJson {
-  return {
-    id: o.node.id,
-    project: o.node.projectName,
-    task: o.node.taskName,
-    status: o.status,
-    exitCode: o.exitCode,
-    durationMs: o.durationMs,
-    hash: o.hash ?? null,
-    // On a hit: whether it restored outputs or found them up to date, as
-    // `summary`'s restoredLocal / restoredRemote / upToDate count it.
-    ...(isCacheHit(o.status) ? { restored: o.restored === true } : {}),
-    // A task with no `cache` block executes every run by design; without
-    // the flag a consumer computing a hit rate cannot tell a miss from a
-    // task that could never hit (its `hash` is still set — dependents fold
-    // it). Present only when true, so every other row is byte-identical.
-    ...(ranNoCache(o) ? { noCache: true } : {}),
-    // Present only when the run proved the task flaky: this exact key
-    // failed after it had passed (this run counted), or the task
-    // needed a retry. A consumer gating on `failed` can tell a break from a
-    // flake without the history; every other row is byte-identical.
-    ...(flaky !== undefined
-      ? { flaky: { passes: flaky.passes, failures: flaky.failures, attempts: flaky.attempts } }
-      : {}),
-    ...(o.cpuMs !== undefined ? { cpuMs: o.cpuMs } : {}),
-    ...(o.peakRssBytes !== undefined ? { peakRssBytes: o.peakRssBytes } : {}),
-    // A hit's row names what the PRODUCING execution used under its own
-    // keys, so a consumer never reads a remote worker's peak as this run's.
-    ...(o.storedDurationMs !== undefined ? { storedDurationMs: o.storedDurationMs } : {}),
-    ...(o.storedCpuMs !== undefined ? { storedCpuMs: o.storedCpuMs } : {}),
-    ...(o.storedPeakRssBytes !== undefined ? { storedPeakRssBytes: o.storedPeakRssBytes } : {}),
-    // Present only when an `admit` policy held the task with a worker free.
-    ...(o.admissionHeldMs !== undefined ? { admissionHeldMs: o.admissionHeldMs } : {}),
-    // A skipped row names the failed (or aborted) task at the root of what
-    // blocked it; a fail-fast skip has none.
-    ...(o.blockedBy !== undefined ? { blockedBy: o.blockedBy } : {}),
-    // A failure vx's own `timeout` killed; absent on every other row.
-    ...(o.timedOut === true ? { timedOut: true } : {}),
-    // The sandbox's violation count; present only on a task it recorded any for.
-    ...(o.sandboxViolations !== undefined ? { sandboxViolations: o.sandboxViolations } : {}),
-    // A persistent task that never became ready, and why.
-    ...(o.notReady !== undefined ? { notReady: o.notReady } : {}),
-    // hrtime spans are bigints → emit as strings so JSON.parse on
-    // the consumer side doesn't truncate the ns precision.
-    ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: String(o.wallclockStartNs) } : {}),
-    ...(o.wallclockEndNs !== undefined ? { wallclockEndNs: String(o.wallclockEndNs) } : {}),
-  }
-}
-
-export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
-  const outPath =
-    args.target === ''
-      ? path.join(args.cacheDir, 'runs', `${args.runId}.json`)
-      : path.resolve(args.cwd, args.target)
-  await Bun.write(outPath, JSON.stringify(runSummaryJson(args), null, 2))
-  return outPath
-}
-
-/** The `--summarize` document, which `vx run --format json` prints. */
-export function runSummaryJson(
-  args: Omit<SummarizeArgs, 'target' | 'cacheDir' | 'cwd'>,
-): RunSummaryJson {
-  // `tasks` and `summary` must describe the same population, or one artifact
-  // contradicts itself (a group task listed in `tasks` but absent from
-  // `summary.total`). `tallyOutcomes` owns the rule; mirror its filter here.
-  const counted = args.outcomes.filter((o) => !isGroupTask(o.node) && o.status !== 'aborted')
-  // A task killed by a shutdown signal is in no bucket and no total, yet it
-  // makes the run red. Listing it separately keeps `tasks.length ===
-  // summary.total` while leaving the artifact able to explain a non-zero
-  // exit — the terminal has said so in its Aborted section all along, and a
-  // parser must not be told less than a human is.
-  const aborted = args.outcomes.filter((o) => !isGroupTask(o.node) && o.status === 'aborted')
-  const flakyById = new Map((args.flaky ?? []).map((f) => [f.taskId, f]))
-  const exitCode = args.exitCode ?? (args.ok ? 0 : 1)
-  const payload: RunSummaryJson = {
-    runId: args.runId,
-    // The run-level verdict, first: a consumer gating on this artifact must
-    // not have to re-derive it by re-implementing the bucket rules.
-    ok: exitCode === 0,
-    exitCode,
-    startedAt: new Date(args.startedAtMs).toISOString(),
-    endedAt: new Date(args.endedAtMs).toISOString(),
-    totalMs: args.totalMs,
-    // The summary row's `saved`, by the same rule: hits only, groups aside.
-    savedMs: counted.reduce(
-      (ms, o) => (isCacheHit(o.status) ? ms + (o.storedDurationMs ?? 0) : ms),
-      0,
-    ),
-    tasks: counted.map((o) => taskEntry(o, flakyById.get(o.node.id))),
-    aborted: aborted.map((o) => taskEntry(o)),
-    // The FULL list: `tallyOutcomes` applies the same group/aborted
-    // exclusions internally, so every counted bucket is unchanged by passing
-    // it — but `summary.aborted` is only non-zero if it sees them.
-    summary: tallyOutcomes(args.outcomes),
-  }
-  return payload
-}
+import type { TaskOutcome } from '../graph/index.js'
 
 export interface ProfileArgs {
   target: string