@vzn/vx 0.0.631 → 0.0.633

package/src/orchestrator/index.ts

@@ -4,6 +4,7 @@
 export { run, planRun, nxProjectTarget, projectNamed } from './run.js'
 export { prepareRun, type PreparedRun } from './prepare.js'
 export { affectedTaskProjects } from './affected-tasks.js'
+export type { AffectedReason } from './affected-tasks.js'
 export {
   discoverProjects,
   gitOfDiscovery,
@@ -156,12 +157,22 @@ export {
   latestRunId,
   listInvocations,
   listRuns,
+  rootCauses,
   whyDidThisRerun as whyDidThisRerunQuery,
 } from './metrics.js'
+export {
+  runFailures,
+  type RunFailures,
+  type TaskFailure,
+  type TaskLog,
+  taskLog,
+} from './run-failures.js'
+export type { OutputLocation } from './path-links.js'
 export { resolveRunId, shortRunId } from './run-id.js'
 export type {
   CacheEntryRow,
   CacheKeyDiff,
+  RootCause,
   CacheKeyExplanation,
   InputDiffEntry,
   InvocationDetail,

package/src/orchestrator/logger.ts

@@ -37,6 +37,7 @@ import {
   notifyEscape,
   PROGRESS_CLEAR,
   progressEscape,
+  terminalLinks,
   terminalSignals,
 } from './terminal-signals.js'
 
@@ -298,6 +299,7 @@ export function defaultLogger(
   const signals = writer.enabled
     ? terminalSignals(opts.env ?? process.env)
     : { progress: false, notify: false }
+  const links = writer.enabled && terminalLinks(opts.env ?? process.env)
   let progressShown = -1
   let progressRed = false
 
@@ -753,7 +755,15 @@ export function defaultLogger(
         }
         if (framed && output.some((c) => c.text.length > 0)) {
           emitBlock(
-            formatTaskBlock(node, outcome, { output, ...dropped }, colors, true, forwardArgs),
+            formatTaskBlock(
+              node,
+              outcome,
+              { output, ...dropped },
+              colors,
+              true,
+              forwardArgs,
+              links,
+            ),
           )
           return
         }
@@ -846,7 +856,15 @@ export function defaultLogger(
           if (outcome.status !== 'failed') return
           emitLine(failureRow(node, outcome))
           deferredFailures.push(
-            formatTaskBlock(node, outcome, { output, ...dropped }, colors, false, forwardArgs),
+            formatTaskBlock(
+              node,
+              outcome,
+              { output, ...dropped },
+              colors,
+              false,
+              forwardArgs,
+              links,
+            ),
           )
           return
         case 'broad':
@@ -858,7 +876,15 @@ export function defaultLogger(
             // ◼ row now; the full frame replays at runEnd.
             emitLine(failureRow(node, outcome))
             deferredFailures.push(
-              formatTaskBlock(node, outcome, { output, ...dropped }, colors, false, forwardArgs),
+              formatTaskBlock(
+                node,
+                outcome,
+                { output, ...dropped },
+                colors,
+                false,
+                forwardArgs,
+                links,
+              ),
             )
           } else if (outcome.status === 'success') {
             emitLine(formatTaskExecutedLine(node, outcome, colors))
@@ -895,14 +921,30 @@ export function defaultLogger(
             if (outcome.status === 'failed') {
               emitLine(failureRow(node, outcome))
               deferredFailures.push(
-                formatTaskBlock(node, outcome, { output, ...dropped }, colors, false, forwardArgs),
+                formatTaskBlock(
+                  node,
+                  outcome,
+                  { output, ...dropped },
+                  colors,
+                  false,
+                  forwardArgs,
+                  links,
+                ),
               )
               return
             }
             // forceCommand: a requested task's frame shows `$ cmd`
             // whether it ran or was cached — same frame every run.
             emitBlock(
-              formatTaskBlock(node, outcome, { output, ...dropped }, colors, true, forwardArgs),
+              formatTaskBlock(
+                node,
+                outcome,
+                { output, ...dropped },
+                colors,
+                true,
+                forwardArgs,
+                links,
+              ),
             )
             return
           }
@@ -913,7 +955,15 @@ export function defaultLogger(
           } else if (outcome.status === 'failed') {
             emitLine(failureRow(node, outcome))
             deferredFailures.push(
-              formatTaskBlock(node, outcome, { output, ...dropped }, colors, false, forwardArgs),
+              formatTaskBlock(
+                node,
+                outcome,
+                { output, ...dropped },
+                colors,
+                false,
+                forwardArgs,
+                links,
+              ),
             )
           }
           return
@@ -939,6 +989,7 @@ export function defaultLogger(
             colors,
             false,
             forwardArgs,
+            links,
           )
           if (block.length === 0) return
           if (view.gha) {

package/src/orchestrator/metrics.ts

@@ -610,10 +610,17 @@ export interface CacheKeyDiff {
   note: string
 }
 
-function loadEntryInputs(db: Database, entryHash: string): TaskInputComponent[] {
-  return db
-    .query('SELECT kind, name, hash FROM entry_inputs WHERE entry_hash = ?')
-    .all(entryHash) as TaskInputComponent[]
+/** An entry's key components, from its one `entry_inputs` row (v34); none when it has none. */
+export function loadEntryInputs(db: Database, entryHash: string): TaskInputComponent[] {
+  const row = db
+    .query('SELECT components FROM entry_inputs WHERE entry_hash = ?')
+    .get(entryHash) as { components: string } | null
+  if (row === null) return []
+  return (JSON.parse(row.components) as [string, string, string][]).map(([kind, name, hash]) => ({
+    kind,
+    name,
+    hash,
+  }))
 }
 
 /**
@@ -757,6 +764,36 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   const cur = loadEntryInputs(db, this_.hash)
   const old = loadEntryInputs(db, prev.hash)
 
+  // A failed previous run kept no fingerprints; the last run that saved an
+  // entry still names what moved since then (the edit an agent made to fix
+  // the failure, or the one that broke it).
+  if (cur.length > 0 && old.length === 0 && !isPassStatus(prev.status)) {
+    const saved = db
+      .query(
+        `SELECT run_id AS runId, hash FROM runs
+         WHERE project = ? AND task = ? AND id < ? AND ${KEYED_RUNS_SQL}
+           AND hash IN (SELECT entry_hash FROM entry_inputs)
+         ORDER BY id DESC LIMIT 1`,
+      )
+      .get(project, task, this_.id) as { runId: string | null; hash: string } | undefined
+    if (saved) {
+      const { entries, unchangedCount } = diffKeyComponents(loadEntryInputs(db, saved.hash), cur)
+      const since = `run ${saved.runId}, the last that saved an entry (the previous run ended ${prev.status})`
+      return {
+        runId,
+        taskId,
+        found: true,
+        previousRunId: saved.runId,
+        entries,
+        unchangedCount,
+        note:
+          entries.length > 0
+            ? `${entries.length} cache-key component(s) changed since ${since}`
+            : `cache key matches ${since}`,
+      }
+    }
+  }
+
   // Input fingerprints are pruned with their entry (ON DELETE CASCADE); if
   // either side's rows are gone, we can name the hash change but not the
   // component-level diff.
@@ -803,6 +840,41 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   }
 }
 
+export interface RootCause {
+  /** From the asked task down to the one whose own inputs moved. */
+  chain: string[]
+  entries: CacheKeyDiff['entries']
+}
+
+/**
+ * The tasks under `taskId`'s moved upstreams whose OWN key components
+ * moved in the same run, each with the chain that carried it up. A task
+ * visited once is not walked again (a diamond names its root once).
+ */
+export function rootCauses(
+  db: Database,
+  runId: string,
+  taskId: string,
+  entries: CacheKeyDiff['entries'],
+): RootCause[] {
+  const roots: RootCause[] = []
+  const seen = new Set([taskId])
+  const walk = (chain: string[], moved: CacheKeyDiff['entries']): void => {
+    for (const e of moved) {
+      if (e.kind !== 'upstream' || seen.has(e.name)) continue
+      seen.add(e.name)
+      const next = [...chain, e.name]
+      const d = cacheKeyDiff(db, runId, e.name)
+      if (!d.found) continue
+      const own = d.entries.filter((x) => x.kind !== 'upstream')
+      if (own.length > 0) roots.push({ chain: next, entries: own })
+      walk(next, d.entries)
+    }
+  }
+  walk([taskId], entries)
+  return roots
+}
+
 // ---------------------------------------------------------------------------
 // Run comparison — diff a run against the immediately-previous invocation
 // ---------------------------------------------------------------------------

package/src/orchestrator/miss-reason.ts

@@ -4,11 +4,11 @@
 //
 // Paid only when a telemetry sink exists, and only on a miss: one scan of
 // `entries` for the newest entry per task, the first time a miss asks, then
-// one primary-key read of that entry's `entry_inputs` per miss.
+// one primary-key read of that entry's `entry_inputs` row per miss.
 
 import type { Database } from 'bun:sqlite'
 import type { InputChanges } from '../graph/index.js'
-import { diffKeyComponents } from './metrics.js'
+import { diffKeyComponents, loadEntryInputs } from './metrics.js'
 import type { TaskInputComponent } from './task-hash.js'
 
 /** How many changed components a miss names; `count` says how many there were. */
@@ -37,9 +37,7 @@ export function createMissExplainer(db: Database): MissExplainer {
       )
       const prev = newest.get(taskId)
       if (prev === undefined) return undefined
-      const before = db
-        .query('SELECT kind, name, hash FROM entry_inputs WHERE entry_hash = ?')
-        .all(prev) as TaskInputComponent[]
+      const before = loadEntryInputs(db, prev)
       // Pruned, or saved before fingerprints were kept: nothing to compare.
       if (before.length === 0) return undefined
       const { entries } = diffKeyComponents(before, components)

package/src/orchestrator/miss-save.ts

@@ -191,11 +191,12 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
     endSave()
     if (a.measure === true) {
       facts.saveMs = Math.round(performance.now() - saveStart)
-      try {
-        facts.artifactBytes = statSync(cache.outputsPath(a.hash)).size
-      } catch {
-        // No local artifact (local writes off): no size to say.
-      }
+      // No local artifact (local writes off): no size to say.
+      const size =
+        cache.artifactSize !== undefined
+          ? cache.artifactSize(a.hash)
+          : statSync(cache.outputsPath(a.hash), { throwIfNoEntry: false })?.size
+      if (size !== undefined) facts.artifactBytes = size
     }
     // The files the task just wrote are the entry's bytes: stamp them,
     // so the next hit can tell them from another entry's with the same

package/src/orchestrator/options.ts

@@ -5,9 +5,11 @@
 import type { CachePolicy, RemoteCacheLayer } from '../cache/index.js'
 import type { ContinueMode } from '../graph/index.js'
 import type { TaskOutcome } from '../graph/index.js'
+import type { AffectedReason } from './affected-tasks.js'
 import type { EventBus } from './events.js'
 import type { TelemetrySink } from './telemetry.js'
 import type { Logger } from './logger.js'
+import type { RunSummaryJson } from './run-artifacts.js'
 import type { AffectedChanges, ProjectEntry, ProjectMeta } from '../workspace/index.js'
 
 export interface RunOptions {
@@ -41,6 +43,8 @@ export interface RunOptions {
    * whether or not `affected` reaches them (X-10).
    */
   selectedOutright?: readonly string[]
+  /** Filled with why `--affected` kept each requested task; `planRun` (`--dry`) passes it. */
+  affectedReasons?: Map<string, AffectedReason>
   /**
    * Configs a selection pass in this same process already loaded and
    * staged with the same `cacheDir` and `frozen` (the CLI walks every
@@ -171,6 +175,12 @@ export interface RunOptions {
    * else is treated as the literal file path (cwd-relative).
    */
   summarize?: string
+  /**
+   * `vx run --format json`: the terminal renderer writes stderr, and the
+   * run hands back `RunSummary.json`, the `--summarize` document, for the
+   * caller to print on stdout.
+   */
+  json?: boolean
   /**
    * Text printed just above the run's footer, given the outcomes the
    * footer counts, after the `summaryTable`: nothing prints below the
@@ -312,6 +322,8 @@ export interface RunSummary {
    * caller prints it; `vx run` writes it to stderr.
    */
   refused?: string
+  /** The `--summarize` document, when `RunOptions.json` asked for it. */
+  json?: RunSummaryJson
 }
 
 export interface HeldPersistent {

package/src/orchestrator/output-log.ts

@@ -4,7 +4,7 @@
 // RS (U+001E) + `e` / `o` where the stream switches to stderr / stdout, and
 // a literal RS doubled. Output that never touched stderr is its own text.
 
-import type { CapturedChunk } from '../exec/index.js'
+import { BoundedCapture, type CapturedChunk } from '../exec/index.js'
 
 const RS = '\x1e'
 
@@ -51,3 +51,16 @@ export function decodeOutputLog(log: string): CapturedChunk[] {
   flush()
   return chunks
 }
+
+// What a failed task reports of its output (`vx last`, an agent): the
+// error is usually at the end, and a run's history keeps one per failure.
+export const FAILED_OUTPUT_HEAD_CHARS = 8 * 1024
+export const FAILED_OUTPUT_TAIL_CHARS = 56 * 1024
+
+/** A failed attempt's capture, re-bounded to the failure's limits when it is the entry's. */
+export function failedOutputLog(capture: BoundedCapture, entrySized: boolean): string {
+  if (!entrySized) return encodeOutputLog(capture.chunks())
+  const small = new BoundedCapture(FAILED_OUTPUT_HEAD_CHARS, FAILED_OUTPUT_TAIL_CHARS)
+  for (const c of capture.chunks()) small.push(c.text, c.err)
+  return encodeOutputLog(small.chunks())
+}

package/src/orchestrator/path-links.ts

@@ -0,0 +1,79 @@
+// A failed task's output with each file it names made a terminal link
+// (OSC 8). A tool prints paths relative to where it ran, the task's
+// project, so the terminal's own path detection, which resolves against
+// the shell's directory, opens the wrong file or none in a monorepo. The
+// visible text stays the task's bytes; only the link target is vx's.
+
+import { statSync } from 'node:fs'
+import path from 'node:path'
+
+// `src/a.ts`, `./a.ts:12`, `/abs/a.ts:12:5`, tsc's `src/a.ts(12,5)`. Not
+// after a word, dot, slash or `@`, so a URL's path or a scoped name's tail
+// never starts a match. Groups: file, then line and column of either form.
+const PATH =
+  /(?<![\w./@+-])((?:\/|\.{1,2}\/)?(?:[\w@.+-]+\/)*[\w@+-][\w@.+-]*\.[A-Za-z][A-Za-z0-9]{0,9})(?::(\d+)(?::(\d+))?|\((\d+),(\d+)\))?/g
+
+/** A file a task's output names; `file` absolute. */
+export interface OutputLocation {
+  file: string
+  line?: number
+  col?: number
+}
+
+/** Most locations one output reports: past it, the first ones are the cause. */
+const LOCATIONS_CAP = 50
+
+/** `text` with every path that names a file under `dir` (or an absolute one) linked. */
+export function linkPaths(text: string, dir: string, isFile: (abs: string) => boolean): string {
+  if (text.includes('\x1b]8;')) return text
+  return text.replace(PATH, (match: string, file: string) => {
+    const abs = path.resolve(dir, file)
+    if (!isFile(abs)) return match
+    return `\x1b]8;;file://${encodeURI(abs)}\x1b\\${match}\x1b]8;;\x1b\\`
+  })
+}
+
+/**
+ * The files `text` names that exist (resolved against `dir`), each with the
+ * line and column it gave, unique, in order of first appearance.
+ */
+export function fileLocations(
+  text: string,
+  dir: string,
+  isFile: (abs: string) => boolean,
+): OutputLocation[] {
+  const out: OutputLocation[] = []
+  const seen = new Set<string>()
+  for (const m of text.matchAll(PATH)) {
+    const file = path.resolve(dir, m[1]!)
+    const line = m[2] ?? m[4]
+    const col = m[3] ?? m[5]
+    const id = `${file}:${line}:${col}`
+    if (seen.has(id) || !isFile(file)) continue
+    seen.add(id)
+    out.push({
+      file,
+      ...(line !== undefined ? { line: Number(line) } : {}),
+      ...(col !== undefined ? { col: Number(col) } : {}),
+    })
+    if (out.length === LOCATIONS_CAP) break
+  }
+  return out
+}
+
+/** A file test that asks the file system once per path. */
+export function fileMemo(): (abs: string) => boolean {
+  const seen = new Map<string, boolean>()
+  return (abs) => {
+    let known = seen.get(abs)
+    if (known === undefined) {
+      try {
+        known = statSync(abs).isFile()
+      } catch {
+        known = false
+      }
+      seen.set(abs, known)
+    }
+    return known
+  }
+}

package/src/orchestrator/plan.ts

@@ -15,6 +15,7 @@ import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
 import { cachesNothing, FULL_CACHE_POLICY } from '../cache/index.js'
 import { ranNoCache } from './events.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 { computeGroupKey, computeTaskHash } from './task-hash.js'
 import { keyedOutcome, keyUpstream } from './upstream.js'
@@ -53,6 +54,8 @@ export interface PlannedTask {
    * eager task is the default and saying so on every line says nothing.
    */
   download?: 'deferred'
+  /** Why `--affected` kept this requested task; absent without `--affected` and on a dependency it pulled in. */
+  affected?: AffectedReason
 }
 
 /**
@@ -68,6 +71,9 @@ export interface PlanPrediction {
   /** Would-run tasks with NO history — their cost is unknown and counted as
    *  0, so wallMs/workMs are lower bounds when this is > 0. */
   unknownCount: number
+  /** The would-run tasks with history along the chain `wallMs` measures,
+   *  dependencies first; empty when nothing with history would run. */
+  criticalPath: string[]
 }
 
 export interface RunPlan {
@@ -271,19 +277,27 @@ function predictPlan(tasks: PlannedTask[]): PlanPrediction {
   const dist = new Map<string, number>()
   const queue: string[] = []
   for (const [id, n] of indeg) if (n === 0) queue.push(id)
+  const via = new Map<string, string>()
   let head = 0
   let wallMs = 0
+  let end: string | undefined
   while (head < queue.length) {
     const id = queue[head++]!
     const t = byId.get(id)!
     let best = 0
     for (const d of t.deps) {
       const v = dist.get(d)
-      if (v !== undefined && v > best) best = v
+      if (v !== undefined && v > best) {
+        best = v
+        via.set(id, d)
+      }
     }
     const v = best + cost(t)
     dist.set(id, v)
-    if (v > wallMs) wallMs = v
+    if (v > wallMs) {
+      wallMs = v
+      end = id
+    }
     for (const dep of dependents.get(id) ?? []) {
       const n = indeg.get(dep)! - 1
       indeg.set(dep, n)
@@ -297,5 +311,8 @@ function predictPlan(tasks: PlannedTask[]): PlanPrediction {
     if (t.p50Ms === undefined) unknownCount++
     else workMs += t.p50Ms
   }
-  return { wallMs, workMs, unknownCount }
+  const criticalPath: string[] = []
+  for (let id = end; id !== undefined; id = via.get(id))
+    if (cost(byId.get(id)!) > 0) criticalPath.push(id)
+  return { wallMs, workMs, unknownCount, criticalPath: criticalPath.reverse() }
 }

package/src/orchestrator/plugin.ts

@@ -251,6 +251,13 @@ export interface CommandContext extends BaseContext {
    * `machineParallelism()` said 4 cores beside `concurrency: 1` (item 1068).
    */
   readonly concurrency: number
+  /**
+   * The argv that runs this vx again: the binary alone when compiled, the
+   * runtime and its entry script from source. A verb that runs tasks
+   * (`vx mcp`'s `runTasks`) spawns `[...vx, 'run', …]` rather than guess
+   * which `vx` a PATH holds.
+   */
+  readonly vx: readonly string[]
 }
 
 /** `config` runs before the cache dir is known — it may be what the hook changes. */

package/src/orchestrator/prepare.ts

@@ -74,6 +74,7 @@ import type { VxPlugin } from './plugin.js'
 import { createHashCache, type HashCache } from './task-hash.js'
 import type { Logger } from './logger.js'
 import type { RunOptions } from './options.js'
+import { refuseFiltersThroughGroups } from './upstream.js'
 
 export interface PreparedRun {
   workspaceRoot: string
@@ -549,10 +550,18 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     if (options.affected !== undefined) {
       const before = hooksFirst ? new Set(nodes.keys()) : null
       if (hooksFirst) await graphStage()
-      const kept = keptByAffected(nodes, requested, options.affected, projects, packageGraph, {
-        named: new Set(tasks.filter((t) => t.includes('#'))),
-        outright: new Set(options.selectedOutright),
-      })
+      const kept = keptByAffected(
+        nodes,
+        requested,
+        options.affected,
+        projects,
+        packageGraph,
+        {
+          named: new Set(tasks.filter((t) => t.includes('#'))),
+          outright: new Set(options.selectedOutright),
+        },
+        options.affectedReasons && { workspaceRoot, reasons: options.affectedReasons },
+      )
       if (kept.length === 0) return emptyRun('none-affected')
       if (before !== null) {
         const asked = new Set(requested.map((r) => `${r.project}#${r.task}`))
@@ -656,6 +665,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) })
     }
+    refuseFiltersThroughGroups(nodes)
     const exclude = options.excludeDependencies
     let keyOnly: ReadonlyMap<string, TaskNode> = new Map()
     if (exclude !== undefined && (exclude === 'all' || exclude.length > 0)) {

package/src/orchestrator/projects.ts

@@ -328,8 +328,8 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
  * one (owner, 2026-10-04): a group behind `^build`, keyed on every file of
  * the project. A package consumed as source then carries its files to every
  * dependent behind `^build`, in the key and in `--affected`, and the chain
- * through it to deeper builds holds. The one keyed group: a config cannot
- * declare `cache` on a group (config-schema.ts), so nothing else is.
+ * through it to deeper builds holds. A keyed group, as a config may
+ * declare one (config-schema.ts).
  */
 const DEFAULT_BUILD: TaskConfig = Object.freeze({
   dependsOn: Object.freeze(['^build']),

package/src/orchestrator/run-artifacts.ts

@@ -52,6 +52,7 @@ export interface SummaryTaskJson {
   flaky?: { passes: number; failures: number; attempts: number }
   cpuMs?: number
   peakRssBytes?: number
+  storedDurationMs?: number
   storedCpuMs?: number
   storedPeakRssBytes?: number
   admissionHeldMs?: number
@@ -71,6 +72,8 @@ export interface RunSummaryJson {
   startedAt: string
   endedAt: string
   totalMs: number
+  /** What the hits skipped: the sum of their `storedDurationMs`. */
+  savedMs: number
   tasks: SummaryTaskJson[]
   aborted: SummaryTaskJson[]
   summary: Tally
@@ -105,6 +108,7 @@ function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): SummaryTaskJson {
     ...(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.
@@ -130,6 +134,14 @@ export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
     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.
@@ -151,6 +163,11 @@ export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
     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
@@ -158,8 +175,7 @@ export async function writeRunSummary(args: SummarizeArgs): Promise<string> {
     // it — but `summary.aborted` is only non-zero if it sees them.
     summary: tallyOutcomes(args.outcomes),
   }
-  await Bun.write(outPath, JSON.stringify(payload, null, 2))
-  return outPath
+  return payload
 }
 
 export interface ProfileArgs {