@vzn/vx 0.0.21 → 0.0.22

package/src/orchestrator/logger.ts

@@ -1,6 +1,7 @@
 import type { TaskNode, TaskOutcome } from '../graph/index.js'
 import { detectColors, type ColorSupport } from './colors.js'
 import {
+  formatFailureRecap,
   formatFrameClose,
   formatFrameOpen,
   formatPersistentTailBlock,
@@ -8,7 +9,15 @@ import {
   formatTaskExecutedLine,
   formatTaskHitLine,
   formatTaskSkippedLine,
+  type RecapEntry,
 } from './framed-output.js'
+import {
+  appendRecapRing,
+  createRecapRing,
+  RECAP_TASKS,
+  recapTail,
+  type RecapRing,
+} from './failure-recap.js'
 import {
   createOutputWriter,
   formatFailureLine,
@@ -20,7 +29,7 @@ import { formatDuration, formatSummarySection, type RunContext } from './summary
 import { isGroupTask } from '../graph/index.js'
 import { appendTail, createTail, resetTail, tailText, type Tail } from '../util/index.js'
 import { isCacheHit } from './telemetry.js'
-import { outcomeWord } from './events.js'
+import { failedLabel, outcomeWord } from './events.js'
 
 export interface Logger {
   /** Header / footer / status text. Written verbatim, one trailing \n added. */
@@ -53,6 +62,21 @@ export interface Logger {
   runEnd?(): void
 }
 
+/** The logger `run()` builds when none is passed, and the one that owns the recap. */
+export interface DefaultLogger extends Logger {
+  /**
+   * The run's last block: each failed task's last lines (item 706). Empty
+   * when nothing failed, and in the modes that promise no task output.
+   */
+  failureRecap(): string[]
+  /**
+   * Hand over any output still coalesced, and write straight through from
+   * now on. `runEnd` does it; the run's own `finally` does it again for a
+   * throw that never reached `runEnd`.
+   */
+  settle(): void
+}
+
 /**
  * The default logger's per-task output policy. Resolved once per run
  * from (in priority order) the explicit `--output-logs` override, a
@@ -152,8 +176,8 @@ export function defaultLogger(
   colors: ColorSupport = detectColors(),
   view: OutputView = { mode: 'full' },
   out: StatusStream = process.stdout,
-  opts: { forceFloorMs?: number } = {},
-): Logger {
+  opts: { forceFloorMs?: number; coalesce?: boolean } = {},
+): DefaultLogger {
   // Per-task buffers, split by stream. Splitting lets the framed-output
   // renderer put stdout under `├─ stdout` and stderr under `├─ stderr`.
   // The price: chunks that interleaved at runtime get re-ordered (all
@@ -215,6 +239,7 @@ export function defaultLogger(
   const writer = createOutputWriter(out, {
     enabled: view.ci !== true,
     ...(opts.forceFloorMs !== undefined ? { forceFloorMs: opts.forceFloorMs } : {}),
+    ...(opts.coalesce === true ? { coalesce: true } : {}),
   })
 
   // Status-display state, driven by the optional lifecycle hooks.
@@ -257,11 +282,12 @@ export function defaultLogger(
   let spreadMin = Infinity
   let spreadSum = 0
   let spreadCount = 0
-  // Pinned zones above the worker rows: failures accumulate as they
-  // happen; persistent tasks pin at ready (their outcome lands while
-  // the child keeps running). Both live until runEnd kills the region.
-  // Full failure frames, deferred to runEnd (owner: '✗ line, continue,
-  // all full frames at the end'). 'full'/CI keeps frames inline.
+  // The pinned zone above the worker rows: persistent tasks pin at
+  // ready (their outcome lands while the child keeps running) and live
+  // until runEnd kills the region. A failure is not pinned: it is a
+  // permanent ◼ row the moment it happens, and its full frame is
+  // deferred to runEnd (owner: '✗ line, continue, all full frames at
+  // the end'). 'full'/CI keeps frames inline.
   const deferredFailures: string[] = []
   const pinnedPersistent: string[] = []
   let flushedFailures = false
@@ -287,6 +313,13 @@ export function defaultLogger(
     { node: TaskNode; outcome?: TaskOutcome; out: Tail; err: Tail }
   >()
   let flushedPersistent = false
+  // The recap's material, decided at each failure so nothing is held for a
+  // task that passed. A buffered task's tail is read off the buffers the
+  // frame drains; a live-streamed one keeps no buffer, so a bounded ring
+  // follows it from its frame-open until its outcome.
+  const recapEntries: RecapEntry[] = []
+  const recapMore: string[] = []
+  const liveRings = new Map<string, RecapRing>()
 
   const refresh = (force: boolean): void => {
     if (statusDead) return
@@ -372,6 +405,23 @@ export function defaultLogger(
     view.mode === 'focused' && isPrimary(node) && !isGroupTask(node) && requestedCount <= 1
 
   return {
+    settle() {
+      writer.settle()
+    },
+    failureRecap() {
+      if (recapEntries.length === 0) return []
+      // Fenced like a frame: a tail is the task's own text, and a line of it
+      // must not become a workflow command. Never inside a group, so it reads
+      // with every group collapsed.
+      const fence =
+        view.gha === true
+          ? (lines: string[]) =>
+              ghaFence(`${lines.join('\n')}\n`, ghaToken)
+                .slice(0, -1)
+                .split('\n')
+          : undefined
+      return formatFailureRecap(recapEntries, recapMore, colors, fence)
+    },
     status(line) {
       writer.write(`${line}\n`)
     },
@@ -404,6 +454,7 @@ export function defaultLogger(
         // Open the live frame: full task info even when the command
         // streams nothing (or the hit replays nothing).
         emitLine(formatFrameOpen(node, colors))
+        liveRings.set(node.id, createRecapRing())
         return
       }
       // Bound a persistent task's output from its FIRST chunk. Waiting for
@@ -452,13 +503,16 @@ export function defaultLogger(
         }
       }
       // Failures end the log: every deferred frame replays here, right
-      // above the summary — the ✗ one-liners marked them in the
-      // stream, the full diagnostics read last where eyes land.
+      // above the summary — the ◼ rows marked them in the stream,
+      // the full diagnostics read last where eyes land.
       // Guarded for repeat runEnd calls.
       if (!flushedFailures && deferredFailures.length > 0) {
         flushedFailures = true
         for (const block of deferredFailures) emitBlock(block)
       }
+      // The summary and the CLI's own lines follow on the stream directly:
+      // nothing may still be held, and nothing after this is.
+      writer.settle()
     },
     taskStdout(node, chunk) {
       if (discardsOutput) return
@@ -466,6 +520,8 @@ export function defaultLogger(
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
         writer.write(chunk)
+        const ring = liveRings.get(node.id)
+        if (ring !== undefined) appendRecapRing(ring, chunk)
         return
       }
       const tail = persistentTails.get(node.id)
@@ -481,6 +537,8 @@ export function defaultLogger(
         streamedSinceBlock = true
         if (chunk.length > 0) streamMidLine = !chunk.endsWith('\n')
         writer.write(chunk)
+        const ring = liveRings.get(node.id)
+        if (ring !== undefined) appendRecapRing(ring, chunk)
         return
       }
       const tail = persistentTails.get(node.id)
@@ -505,6 +563,28 @@ export function defaultLogger(
       // The pre-ready window closed either way: a failed task is over, and
       // a ready one starts a fresh post-ready tail below.
       persistentTails.delete(node.id)
+      const liveRing = liveRings.get(node.id)
+      liveRings.delete(node.id)
+      if (outcome.status === 'failed' && !discardsOutput) {
+        if (recapEntries.length === RECAP_TASKS) recapMore.push(node.id)
+        else {
+          let ring = liveRing
+          if (ring === undefined) {
+            ring = createRecapRing()
+            appendRecapRing(ring, stdout)
+            if (stdout.length > 0 && stderr.length > 0 && !stdout.endsWith('\n')) {
+              appendRecapRing(ring, '\n')
+            }
+            appendRecapRing(ring, stderr)
+          }
+          recapEntries.push({
+            node,
+            outcome,
+            tail: recapTail(ring),
+            droppedChars: (preReady?.out.dropped ?? 0) + (preReady?.err.dropped ?? 0),
+          })
+        }
+      }
       // An aborted task (child killed by a shutdown signal) reverts
       // to pending: free its worker slot, but never count or render it
       // — the run is tearing down and it has no honest outcome.
@@ -516,6 +596,22 @@ export function defaultLogger(
           if (qi >= 0) slotQueue.splice(qi, 1)
         }
         refresh(true)
+        // What it printed while it stopped (a trap's cleanup) still reaches
+        // the terminal where a frame would have: a task that traps Ctrl-C
+        // and exits 0 is aborted since item 962, and its frame was dropped
+        // with the count.
+        const framed = view.mode === 'full' || (view.mode === 'focused' && isPrimary(node))
+        if (framed && !isGroupTask(node)) {
+          if (streamsLive(node)) {
+            if (streamMidLine) {
+              writer.write('\n')
+              streamMidLine = false
+            }
+            emitFrameClose(formatFrameClose(node, outcome, colors))
+          } else if (stdout.length > 0 || stderr.length > 0) {
+            emitBlock(formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors, true))
+          }
+        }
         return
       }
       // Group tasks (no exec) do no work — no surface prints them.
@@ -595,7 +691,7 @@ export function defaultLogger(
           // their replay buffers are deliberately dropped; the counts
           // surface in the end-of-run summary.
           if (outcome.status === 'failed') {
-            // ✗ marker now; the full frame replays at runEnd.
+            // ◼ row now; the full frame replays at runEnd.
             emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
             deferredFailures.push(
               formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors),
@@ -606,11 +702,11 @@ export function defaultLogger(
           return
         case 'focused':
           if (isPrimary(node)) {
-            // Skipped tasks never started (upstream failed), so no
-            // frame-open fired — and a skip has no output, so a
-            // one-liner carries everything a frame would.
+            // Skipped tasks never started (blocked upstream, or the run
+            // stopped), so no frame-open fired — and a skip has no output,
+            // so a one-liner carries everything a frame would.
             if (outcome.status === 'skipped') {
-              emitLine(formatTaskSkippedLine(node, colors))
+              emitLine(formatTaskSkippedLine(node, colors, outcome.blockedBy))
               return
             }
             if (streamsLive(node)) {
@@ -643,7 +739,7 @@ export function defaultLogger(
             return
           }
           // Dependency-pulled nodes: silent on success; failures get
-          // the ✗ marker now and their frame replayed at runEnd.
+          // the ◼ row now and their frame replayed at runEnd.
           if (outcome.status === 'failed') {
             emitLine(formatFailureLine(node.id, outcome.durationMs, colors, cacheWordOf(node)))
             deferredFailures.push(
@@ -663,7 +759,7 @@ export function defaultLogger(
             return
           }
           if (outcome.status === 'skipped') {
-            emitLine(formatTaskSkippedLine(node, colors))
+            emitLine(formatTaskSkippedLine(node, colors, outcome.blockedBy))
             return
           }
           const block = formatTaskBlock(node, outcome, { stdout, stderr, ...dropped }, colors)
@@ -676,10 +772,10 @@ export function defaultLogger(
             // Failed tasks stay pre-expanded in the Actions viewer:
             // an ::error annotation instead of a collapsed group.
             if (outcome.status === 'failed') {
-              // The message is ours (a literal + an integer); only the title
-              // carries user input.
+              // The message is ours (a literal, an integer and a signal
+              // name); only the title carries user input.
               emitBlock(
-                `::error title=${ghaProperty(node.id)}::failed (exit ${outcome.exitCode})\n${body}`,
+                `::error title=${ghaProperty(node.id)}::${failedLabel(outcome.exitCode, outcome.timedOut, outcome.sandboxViolations, outcome.notReady)}\n${body}`,
               )
             } else {
               emitBlock(

package/src/orchestrator/metrics.ts

@@ -15,6 +15,8 @@ import type { Database } from 'bun:sqlite'
 import { KEYED_RUNS_SQL } from '../cache/index.js'
 import { splitTaskId } from '../graph/index.js'
 import { clampInt } from '../util/index.js'
+import type { TaskInputComponent } from './task-hash.js'
+import { isPassStatus } from './telemetry.js'
 
 // ---------------------------------------------------------------------------
 // Run listing + detail
@@ -39,6 +41,11 @@ export interface RunSummaryRow {
   // (bigints aren't JSON-safe); use BigInt or Number on the client.
   wallclockStartNs: string | null
   wallclockEndNs: string | null
+  /** Why the task failed or was skipped (v27); null where the reason does not apply. */
+  blockedBy: string | null
+  timedOut: boolean | null
+  sandboxViolations: number | null
+  notReady: 'timeout' | 'exited' | 'spawn' | null
 }
 
 export interface ListRunsArgs {
@@ -69,12 +76,18 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
   const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''
   type RawRow = Omit<
     RunSummaryRow,
-    'cacheHit' | 'cached' | 'wallclockStartNs' | 'wallclockEndNs'
+    'cacheHit' | 'cached' | 'wallclockStartNs' | 'wallclockEndNs' | 'timedOut'
   > & {
     cacheHit: number | null
     cached: number | null
-    wallclockStartNs: bigint | null
-    wallclockEndNs: bigint | null
+    // NOT bigint: `bun:sqlite` hands these back as JS numbers (the handle
+    // does not set `safeIntegers`), so the annotation claimed a precision
+    // the read never had. Harmless in practice — these are ns RELATIVE to
+    // run t=0, and 2^53 ns is 104 days of run time — but a `bigint` here
+    // was simply false. `.toString()` reads the same on either.
+    wallclockStartNs: number | null
+    wallclockEndNs: number | null
+    timedOut: number | null
   }
   const rows = db
     .query(
@@ -82,14 +95,17 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
               duration_ms AS durationMs, started_at AS startedAt, ended_at AS endedAt,
               cache_hit AS cacheHit, cached, hash,
               cpu_ms AS cpuMs, peak_rss_bytes AS peakRssBytes,
-              wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs
-       FROM runs ${clause} ORDER BY started_at DESC LIMIT ?`,
+              wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs,
+              blocked_by AS blockedBy, timed_out AS timedOut,
+              sandbox_violations AS sandboxViolations, not_ready AS notReady
+       FROM runs ${clause} ORDER BY id DESC LIMIT ?`,
     )
     .all(...params, limit) as RawRow[]
   return rows.map((r) => ({
     ...r,
     cacheHit: r.cacheHit === null ? null : Boolean(r.cacheHit),
     cached: r.cached === null ? null : Boolean(r.cached),
+    timedOut: r.timedOut === null ? null : Boolean(r.timedOut),
     wallclockStartNs: r.wallclockStartNs === null ? null : r.wallclockStartNs.toString(),
     wallclockEndNs: r.wallclockEndNs === null ? null : r.wallclockEndNs.toString(),
   }))
@@ -264,7 +280,7 @@ export function listInvocations(
   const rows = db
     .query(
       `SELECT ${INVOCATION_COLUMNS} FROM invocations ${clause}
-       ORDER BY started_at DESC LIMIT ?`,
+       ORDER BY rowid DESC LIMIT ?`,
     )
     .all(...params, limit) as InvocationRawRow[]
   return rows.map(mapInvocation)
@@ -370,25 +386,72 @@ export interface WhyDidThisRerun {
   note: string
 }
 
-/** The three endings an UNCHANGED cache key can have. */
-function unchangedKeyNote(cacheHit: number | null): string {
-  if (cacheHit === null) {
+/**
+ * The endings an UNCHANGED cache key can have. A re-execution is told apart
+ * by the evidence the index holds: every one used to blame `--no-cache` /
+ * `--force`, when the previous run on the key had failed (a failure saves
+ * nothing) or the entry had been pruned, and the invocation recorded that
+ * no flag was passed (item 1009).
+ */
+function unchangedKeyNote(
+  db: Database,
+  runId: string,
+  this_: { hash: string; cacheHit: number | null; startedAt: number },
+  prev: { status: string },
+): string {
+  if (this_.cacheHit === null) {
     return 'cache key unchanged — this run recorded no cache outcome, so whether it re-ran is unknown'
   }
-  return cacheHit
-    ? 'cache key unchanged — this run was served from cache, nothing re-ran'
-    : 'cache key unchanged — re-executed on the same key (--no-cache / --force, or unrelated)'
+  if (this_.cacheHit) return 'cache key unchanged — this run was served from cache, nothing re-ran'
+  if (prev.status === 'failed') {
+    return 'cache key unchanged — the previous run on this key failed and saved nothing, so there was nothing to hit'
+  }
+  const policy = (
+    db.query('SELECT cache_policy AS p FROM invocations WHERE run_id = ?').get(runId) as {
+      p: string
+    } | null
+  )?.p
+  if (policy !== undefined && !policy.split(',').some((axis) => axis === 'lR' || axis === 'rR')) {
+    return 'cache key unchanged — re-executed because this run did not read the cache (--force, or a --cache without read)'
+  }
+  // `get` answers null, not undefined, for no row.
+  const createdAt = (
+    db.query('SELECT created_at AS at FROM entries WHERE hash = ?').get(this_.hash) as {
+      at: number
+    } | null
+  )?.at
+  if (createdAt !== undefined && createdAt >= this_.startedAt) {
+    return 'cache key unchanged — no entry for this key was in the cache when it ran (pruned or evicted), so it executed and saved one'
+  }
+  return 'cache key unchanged — re-executed on the same key (--no-cache / --force, or unrelated)'
+}
+
+/**
+ * The latest recorded run of a task (run_id may be NULL on very old rows).
+ * One query for `vx why` and `vx mcp`: the CLI defaulted to it while the
+ * tool demanded a run id an agent had to fetch first (2026-09-16).
+ */
+export function latestRunId(db: Database, taskId: string): string | null {
+  const [project, task] = splitTaskId(taskId)
+  const row = db
+    .query(
+      `SELECT run_id AS runId FROM runs WHERE project = ? AND task = ?
+       ORDER BY id DESC LIMIT 1`,
+    )
+    .get(project, task) as { runId: string | null } | undefined
+  return row?.runId ?? null
 }
 
 export function whyDidThisRerun(db: Database, runId: string, taskId: string): WhyDidThisRerun {
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      `SELECT hash, status, cache_hit AS cacheHit, cached, started_at AS startedAt
+      `SELECT id, hash, status, cache_hit AS cacheHit, cached, started_at AS startedAt
        FROM runs WHERE run_id = ? AND project = ? AND task = ?`,
     )
     .get(runId, project, task) as
     | {
+        id: number
         hash: string
         status: string
         cacheHit: number | null
@@ -411,10 +474,10 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
   const prev = db
     .query(
       `SELECT hash, status, cache_hit AS cacheHit, started_at AS startedAt
-       FROM runs WHERE project = ? AND task = ? AND started_at < ? AND ${KEYED_RUNS_SQL}
-       ORDER BY started_at DESC LIMIT 1`,
+       FROM runs WHERE project = ? AND task = ? AND id < ? AND ${KEYED_RUNS_SQL}
+       ORDER BY id DESC LIMIT 1`,
     )
-    .get(project, task, this_.startedAt) as
+    .get(project, task, this_.id) as
     | { hash: string; status: string; cacheHit: number | null; startedAt: number }
     | undefined
   // …and this run must have one too, or there is nothing to compare.
@@ -424,9 +487,11 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
     taskId,
     found: true,
     thisRun: {
-      ...this_,
+      hash: this_.hash,
+      status: this_.status,
       cacheHit: this_.cacheHit === null ? null : Boolean(this_.cacheHit),
       cached: this_.cached === null ? null : Boolean(this_.cached),
+      startedAt: this_.startedAt,
     },
     previousRun: prev
       ? { ...prev, cacheHit: prev.cacheHit === null ? null : Boolean(prev.cacheHit) }
@@ -447,7 +512,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
               // have applied. Only a run that EXECUTED on an unchanged key is
               // the case this verb exists to explain. A row with no recorded
               // cacheHit (older rows) is neither — say that, do not guess.
-              unchangedKeyNote(this_.cacheHit)
+              unchangedKeyNote(db, runId, this_, prev)
             : 'no prior run for this (project, task)',
   }
 }
@@ -478,17 +543,55 @@ export interface CacheKeyDiff {
   note: string
 }
 
-interface EntryInputRow {
-  kind: string
-  name: string
-  hash: 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[]
 }
 
-function loadEntryInputs(db: Database, entryHash: string): Map<string, EntryInputRow> {
-  const rows = db
-    .query('SELECT kind, name, hash FROM entry_inputs WHERE entry_hash = ?')
-    .all(entryHash) as EntryInputRow[]
-  return new Map(rows.map((r) => [`${r.kind}\0${r.name}`, r]))
+/**
+ * The rule `vx why` and the site's playground both name a moved key by: join
+ * two keys' components over `(kind, name)`. A component in both with a
+ * different hash is `changed`, one only in `after` is `added`, one only in
+ * `before` is `removed`, and an equal one is counted. Entries are ordered by
+ * kind, then name.
+ */
+export function diffKeyComponents(
+  before: readonly TaskInputComponent[],
+  after: readonly TaskInputComponent[],
+): { entries: InputDiffEntry[]; unchangedCount: number } {
+  const id = (c: TaskInputComponent): string => `${c.kind}\0${c.name}`
+  const cur = new Map(after.map((c) => [id(c), c]))
+  const old = new Map(before.map((c) => [id(c), c]))
+  const entries: InputDiffEntry[] = []
+  let unchangedCount = 0
+  const keys = new Set<string>([...cur.keys(), ...old.keys()])
+  for (const key of keys) {
+    const a = cur.get(key)
+    const b = old.get(key)
+    if (a && b) {
+      if (a.hash === b.hash) unchangedCount++
+      else
+        entries.push({
+          kind: a.kind,
+          name: a.name,
+          change: 'changed',
+          before: b.hash,
+          after: a.hash,
+        })
+    } else if (a) {
+      entries.push({ kind: a.kind, name: a.name, change: 'added', before: null, after: a.hash })
+    } else if (b) {
+      entries.push({ kind: b.kind, name: b.name, change: 'removed', before: b.hash, after: null })
+    }
+  }
+  // Code-unit order, not `localeCompare`: collation follows the machine's
+  // locale, and the playground runs this same join in the reader's browser,
+  // so the CLI and the page could list one diff in two orders. Code units
+  // are also SQLite's BINARY order, the `entry_inputs` scan's own.
+  const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0)
+  entries.sort((x, y) => byCodeUnit(x.kind, y.kind) || byCodeUnit(x.name, y.name))
+  return { entries, unchangedCount }
 }
 
 /**
@@ -503,7 +606,8 @@ function loadEntryInputs(db: Database, entryHash: string): Map<string, EntryInpu
  * - only in the previous run → `removed`
  * - equal → counted as unchanged
  *
- * Pure SQL + an app-side set join — no config re-evaluation, no re-hash.
+ * Pure SQL + an app-side set join (`diffKeyComponents`) — no config
+ * re-evaluation, no re-hash.
  * Always returns a value (never throws); `found:false` when the run/task pair
  * has no row, `entries:[]` for the first run of a task.
  */
@@ -511,10 +615,10 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      'SELECT hash, cached, started_at AS startedAt FROM runs WHERE run_id = ? AND project = ? AND task = ?',
+      'SELECT id, hash, cached, status, started_at AS startedAt FROM runs WHERE run_id = ? AND project = ? AND task = ?',
     )
     .get(runId, project, task) as
-    | { hash: string; cached: number | null; startedAt: number }
+    | { id: number; hash: string; cached: number | null; status: string; startedAt: number }
     | undefined
   if (!this_) {
     return {
@@ -545,11 +649,13 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
 
   const prev = db
     .query(
-      `SELECT run_id AS runId, hash FROM runs
-       WHERE project = ? AND task = ? AND started_at < ? AND ${KEYED_RUNS_SQL}
-       ORDER BY started_at DESC LIMIT 1`,
+      `SELECT run_id AS runId, hash, status FROM runs
+       WHERE project = ? AND task = ? AND id < ? AND ${KEYED_RUNS_SQL}
+       ORDER BY id DESC LIMIT 1`,
     )
-    .get(project, task, this_.startedAt) as { runId: string | null; hash: string } | undefined
+    .get(project, task, this_.id) as
+    | { runId: string | null; hash: string; status: string }
+    | undefined
 
   if (!prev) {
     return {
@@ -581,7 +687,15 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   // 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.
-  if (cur.size === 0 || old.size === 0) {
+  if (cur.length === 0 || old.length === 0) {
+    // A run that did not pass saved no entry, so it kept no fingerprints:
+    // that is the cause to name, not a prune (item 898).
+    const unsaved =
+      cur.length === 0 && !isPassStatus(this_.status)
+        ? `this run ended ${this_.status}`
+        : old.length === 0 && !isPassStatus(prev.status)
+          ? `the previous run ended ${prev.status}`
+          : null
     return {
       runId,
       taskId,
@@ -591,34 +705,16 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
       unchangedCount: 0,
       note:
         this_.cached === 0
-          ? 'this task declares no `cache` block — it runs every time; its key moved, but no input fingerprints exist for an uncached task'
-          : 'cache key changed but input fingerprints are unavailable — the entry was pruned (or the row predates the `cached` column); only the key change is known',
+          ? // The verdict already says the task is uncached; this line says
+            // what moved a key that declares nothing.
+            'no `cache` block declares its inputs, so its key folds every file in its project — a file it wrote, or any untracked file, moves it — and no fingerprints are kept to say which'
+          : unsaved !== null
+            ? `cache key changed but input fingerprints are unavailable — ${unsaved} and saved no entry; only the key change is known`
+            : 'cache key changed but input fingerprints are unavailable — the entry was pruned (or the row predates the `cached` column); only the key change is known',
     }
   }
 
-  const entries: InputDiffEntry[] = []
-  let unchangedCount = 0
-  const keys = new Set<string>([...cur.keys(), ...old.keys()])
-  for (const key of keys) {
-    const a = cur.get(key)
-    const b = old.get(key)
-    if (a && b) {
-      if (a.hash === b.hash) unchangedCount++
-      else
-        entries.push({
-          kind: a.kind,
-          name: a.name,
-          change: 'changed',
-          before: b.hash,
-          after: a.hash,
-        })
-    } else if (a) {
-      entries.push({ kind: a.kind, name: a.name, change: 'added', before: null, after: a.hash })
-    } else if (b) {
-      entries.push({ kind: b.kind, name: b.name, change: 'removed', before: b.hash, after: null })
-    }
-  }
-  entries.sort((x, y) => x.kind.localeCompare(y.kind) || x.name.localeCompare(y.name))
+  const { entries, unchangedCount } = diffKeyComponents(old, cur)
 
   return {
     runId,