@vzn/vx 0.0.504 → 0.0.506

package/README.md

@@ -149,8 +149,6 @@ Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
 | [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: a read-only MCP server for AI coding agents                         |
 | [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
 
-Only `@vzn/vx` is on npm today; the plugins' first publish is pending.
-
 Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
 [architecture](packages/vx/docs/architecture.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.504",
+  "version": "0.0.506",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.504",
-    "@vzn/vx-linux-arm64": "0.0.504",
-    "@vzn/vx-darwin-x64": "0.0.504",
-    "@vzn/vx-darwin-arm64": "0.0.504"
+    "@vzn/vx-linux-x64": "0.0.506",
+    "@vzn/vx-linux-arm64": "0.0.506",
+    "@vzn/vx-darwin-x64": "0.0.506",
+    "@vzn/vx-darwin-arm64": "0.0.506"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/cache.ts

@@ -231,7 +231,11 @@ export function noteSchemaReset(cache: Cache, warn: (message: string) => void):
 //   v30: blob_verdicts — the blob-size check's verdict by a hash of the
 //        index file (A-60), so a warm run reads one row. The cache KEY is
 //        unchanged.
-export const SCHEMA_VERSION = 'v30'
+//   v31: runs.restored and invocations' up_to_date / restored_local /
+//        restored_remote counts — a hit that restored outputs apart from
+//        one that found them in place, for every reader after the run.
+//        The cache KEY is unchanged.
+export const SCHEMA_VERSION = 'v31'
 
 /** An entry row with its stdout, which lives apart (v29); none stored reads as ''. */
 const SELECT_ENTRY =
@@ -1744,16 +1748,17 @@ export class Cache implements CacheLayer {
     const since = Date.now() - 24 * 60 * 60 * 1000
     const runs = this.db
       .prepare(
-        `SELECT COUNT(*) AS total, COALESCE(SUM(CASE WHEN status IN ('cache-hit', 'cache-hit-remote') THEN 1 ELSE 0 END), 0) AS hits FROM runs WHERE started_at >= ? AND ${EXECUTED_RUNS_SQL}${
+        `SELECT COUNT(*) AS total, COALESCE(SUM(CASE WHEN status IN ('cache-hit', 'cache-hit-remote') THEN 1 ELSE 0 END), 0) AS hits, COALESCE(SUM(restored = 1), 0) AS restored FROM runs WHERE started_at >= ? AND ${EXECUTED_RUNS_SQL}${
           scoped ? ' AND project = ?' : ''
         }`,
       )
-      .get(since, ...scopeParams) as { total: number; hits: number }
+      .get(since, ...scopeParams) as { total: number; hits: number; restored: number }
     return {
       entryCount: aggregate.n,
       totalBytes: aggregate.bytes,
       runCountLast24h: runs.total,
       hitCountLast24h: runs.hits,
+      restoredCountLast24h: runs.restored,
     }
   }
 

package/src/cache/layer.ts

@@ -192,6 +192,11 @@ export interface RunRecord {
   wallclockStartNs?: bigint // hrtime span relative to run t=0
   wallclockEndNs?: bigint
   cacheHit?: boolean // convenience for flamegraph color; derivable from status
+  /**
+   * On a hit: whether outputs were written (`true`) or the disk already
+   * matched the entry (`false`, up-to-date). Absent on other statuses (v31).
+   */
+  restored?: boolean
   attempts?: number // >1 when the task retried; the direct within-run flaky signal
   /**
    * Whether the task declared a `cache` block. An uncached task executes
@@ -235,6 +240,10 @@ export interface InvocationRecord {
   hitCount: number
   hitLocalCount: number
   hitRemoteCount: number
+  /** Hits that restored nothing, and hits that restored outputs per layer (v31); they sum to `hitCount`. */
+  upToDateCount: number
+  restoredLocalCount: number
+  restoredRemoteCount: number
   exitOk: boolean
   commitSha: string | null
   branch: string | null
@@ -269,6 +278,8 @@ export interface CacheStats {
   totalBytes: number
   runCountLast24h: number
   hitCountLast24h: number
+  /** Of those hits, the ones that restored outputs; the rest found the disk up to date. */
+  restoredCountLast24h: number
 }
 
 export interface CacheStatsOptions {

package/src/cache/run-history.ts

@@ -13,11 +13,11 @@ const INSERT_RUNS = `
         started_at, ended_at,
         run_id, cpu_ms, peak_rss_bytes, wallclock_start_ns, wallclock_end_ns,
         cache_hit, attempts, cached,
-        blocked_by, timed_out, sandbox_violations, not_ready
+        blocked_by, timed_out, sandbox_violations, not_ready, restored
       )
       VALUES `
-/** One `runs` row's placeholders: the 21 columns `bindRun` fills. */
-const RUN_TUPLE = `(${Array(21).fill('?').join(', ')})`
+/** One `runs` row's placeholders: the 22 columns `bindRun` fills. */
+const RUN_TUPLE = `(${Array(22).fill('?').join(', ')})`
 
 /** An INSERT of `n` `runs` rows. */
 function insertRunsSql(n: number): string {
@@ -25,7 +25,7 @@ function insertRunsSql(n: number): string {
 }
 
 /**
- * Rows per INSERT: 40 × 21 variables stays under 999, the oldest default
+ * Rows per INSERT: 40 × 22 variables stays under 999, the oldest default
  * ceiling. A statement per row was 8.7 ms of 1,000 rows, 40 at a time 6.4
  * (2026-10-03).
  */
@@ -48,11 +48,12 @@ export class RunHistory {
         run_id, command, requested_tasks, cache_policy, concurrency, flow,
         started_at, ended_at, total_duration_ms,
         task_count, failed_count, hit_count, hit_local_count, hit_remote_count,
+        up_to_date_count, restored_local_count, restored_remote_count,
         exit_ok,
         commit_sha, branch, dirty, ci, ci_provider,
         host, os, arch, vx_version, tags
       )
-      VALUES (?, ?, ?, ?, ?, ?,  ?, ?, ?,  ?, ?, ?, ?, ?,  ?,  ?, ?, ?, ?, ?,  ?, ?, ?, ?, ?)
+      VALUES (?, ?, ?, ?, ?, ?,  ?, ?, ?,  ?, ?, ?, ?, ?,  ?, ?, ?,  ?,  ?, ?, ?, ?, ?,  ?, ?, ?, ?, ?)
       ON CONFLICT(run_id) DO NOTHING
     `,
     )
@@ -119,7 +120,7 @@ export class RunHistory {
 
 /**
  * Bind a RunRecord to the positional parameters expected by the
- * `insertRun` prepared statement (21 columns). Shared between the
+ * `insertRun` prepared statement (22 columns). Shared between the
  * single and batched record paths.
  */
 function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
@@ -150,12 +151,13 @@ function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBi
     run.timedOut === true ? 1 : null,
     run.sandboxViolations ?? null,
     run.notReady ?? null,
+    run.restored === undefined ? null : run.restored ? 1 : 0,
   ]
 }
 
 /**
  * Bind an InvocationRecord to the positional parameters of the
- * `insertInvocation` prepared statement (25 columns). Booleans map to
+ * `insertInvocation` prepared statement (28 columns). Booleans map to
  * 0/1; null-or-bool columns (`dirty`) keep null distinct from 0.
  */
 function bindInvocation(inv: InvocationRecord): SQLQueryBindings[] {
@@ -174,6 +176,9 @@ function bindInvocation(inv: InvocationRecord): SQLQueryBindings[] {
     inv.hitCount,
     inv.hitLocalCount,
     inv.hitRemoteCount,
+    inv.upToDateCount,
+    inv.restoredLocalCount,
+    inv.restoredRemoteCount,
     inv.exitOk ? 1 : 0,
     inv.commitSha,
     inv.branch,

package/src/cache/schema.ts

@@ -93,7 +93,10 @@ export function createTables(db: Database): void {
       blocked_by          TEXT,
       timed_out           INTEGER,
       sandbox_violations  INTEGER,
-      not_ready           TEXT
+      not_ready           TEXT,
+      -- v31: on a hit, 1 when outputs were restored, 0 when the disk
+      -- already matched (up-to-date); NULL on every other status.
+      restored            INTEGER
     );
     -- Two whole-table indexes only, and both APPEND: every row of a run carries the
     -- same run_id and a started_at newer than everything before it, so
@@ -214,6 +217,10 @@ export function createTables(db: Database): void {
       hit_count         INTEGER NOT NULL,
       hit_local_count   INTEGER NOT NULL,
       hit_remote_count  INTEGER NOT NULL,
+      -- v31: the hits by what they did to the disk; they sum to hit_count.
+      up_to_date_count       INTEGER NOT NULL DEFAULT 0,
+      restored_local_count   INTEGER NOT NULL DEFAULT 0,
+      restored_remote_count  INTEGER NOT NULL DEFAULT 0,
       exit_ok           INTEGER NOT NULL,
       commit_sha        TEXT,
       branch            TEXT,

package/src/cli/info.ts

@@ -104,7 +104,13 @@ export function renderInfo(f: InfoFacts): string {
       : []),
     // Task runs, not invocations (which `vx last` calls runs): the count
     // the hits are a share of.
-    ['task runs (24h)', `${f.runs24h} (${f.hits24h} cache hits)`],
+    [
+      'task runs (24h)',
+      `${f.runs24h} (${f.hits24h} cache hits` +
+        (f.hits24h > 0
+          ? `: ${f.hits24h - f.restored24h} up-to-date, ${f.restored24h} restored)`
+          : ')'),
+    ],
     ['flaky tasks', describeFlakyTasks(f.flakyTasks)],
     ['sandbox', describeSandbox(f.sandbox)],
     ['vx-lock.json', f.lockfile ? 'yes' : 'no'],

package/src/cli/last.ts

@@ -14,6 +14,7 @@ import {
   getRun,
   type InvocationDetail,
   listInvocations,
+  outcomeWord,
   type RunSummaryRow,
   resolveRunId,
   shortRunId,
@@ -184,7 +185,14 @@ export function formatTaskRows(tasks: readonly RunSummaryRow[]): string[] {
     // by design; a reader must not take its row for a miss.
     // A failure's row reads as the frame did — `failed (exit 137)` —
     // and above 128 names the signal the number stands for (260).
-    const status = t.status === 'failed' ? `failed (exit ${t.exitCode})` : t.status
+    // A hit reads as the run's own summary said it: up-to-date (nothing
+    // restored) or restored-local / restored-remote.
+    const status =
+      t.status === 'failed'
+        ? `failed (exit ${t.exitCode})`
+        : t.cacheHit === true && t.restored !== null
+          ? outcomeWord({ status: t.status as 'cache-hit', restored: t.restored })
+          : t.status
     lines.push(
       `  ${status.padEnd(17)} ${id.padEnd(idW)}  ${fmtMs(t.durationMs).padStart(8)}` +
         `${t.hash !== '' ? `  ${t.hash}` : ''}${t.cached === false ? '  no-cache' : ''}${fmtUsage(t)}` +
@@ -199,6 +207,25 @@ export function formatTaskRows(tasks: readonly RunSummaryRow[]): string[] {
   return lines
 }
 
+/**
+ * A run's hits by what they did to the disk, as its summary counted them:
+ * `5 hits (3 up-to-date, 2 restored: 1 local, 1 remote)`; the layers only
+ * when something was restored.
+ */
+function hitsLine(
+  inv: Pick<
+    InvocationDetail,
+    'hitCount' | 'upToDateCount' | 'restoredLocalCount' | 'restoredRemoteCount'
+  >,
+): string {
+  const hits = `${inv.hitCount} hit${inv.hitCount === 1 ? '' : 's'}`
+  if (inv.hitCount === 0) return hits
+  const restored = inv.restoredLocalCount + inv.restoredRemoteCount
+  const layers =
+    restored > 0 ? `: ${inv.restoredLocalCount} local, ${inv.restoredRemoteCount} remote` : ''
+  return `${hits} (${inv.upToDateCount} up-to-date, ${restored} restored${layers})`
+}
+
 export async function lastCmd(args: readonly string[]): Promise<number> {
   const parsed = parseLastArgs(args)
   if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`)
@@ -232,7 +259,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         const verdict = inv.exitOk ? 'ok    ' : 'FAILED'
         process.stdout.write(
           `${verdict} ${fmtWhen(inv.startedAt)}  ${shortRunId(db, inv.runId)}  ` +
-            `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${inv.hitCount} hit${inv.hitCount === 1 ? '' : 's'}` +
+            `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${hitsLine(inv)}` +
             `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''} · ${fmtMs(inv.totalDurationMs)}  $ ${inv.command}\n`,
         )
       }
@@ -273,8 +300,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         `${inv.ci ? ` · CI${inv.ciProvider !== null ? ` (${inv.ciProvider})` : ''}` : ''}`,
     )
     lines.push(
-      `  ${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${inv.hitCount} hit${inv.hitCount === 1 ? '' : 's'}` +
-        ` (${inv.hitLocalCount} local, ${inv.hitRemoteCount} remote)` +
+      `  ${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${hitsLine(inv)}` +
         `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''}`,
     )
     lines.push(...formatTaskRows(detail?.tasks ?? []))

package/src/cli/why.ts

@@ -171,6 +171,11 @@ async function rootSpelled(root: string, target: string): Promise<string> {
   return typeof name === 'string' && name !== '' ? `${name}#${target.slice(3)}` : target
 }
 
+/** ` · up-to-date` or ` · restored` on a hit, as the run's summary said it; nothing otherwise. */
+function restoredWord(r: { restored: boolean | null }): string {
+  return r.restored === null ? '' : r.restored ? ' · restored' : ' · up-to-date'
+}
+
 export async function whyCmd(args: readonly string[]): Promise<number> {
   const parsed = parseWhyArgs(args)
   if (parsed.error !== undefined) throw new UserError(`vx why: ${parsed.error}`)
@@ -223,18 +228,21 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     const t = why.thisRun!
     lines.push(`${taskId} — run ${runId}`)
     // A hit's status (`cache-hit`, `cache-hit-remote`) already names it and
-    // its tier; only an executed run needs the word. A skipped task never
-    // ran and has no key: it read `skipped · executed · key ` (item 898).
+    // its tier, and `up-to-date` / `restored` says what it did to the disk;
+    // only an executed run needs the word. A skipped task never ran and has
+    // no key: it read `skipped · executed · key ` (item 898).
     const ran = t.cacheHit === false && t.status !== 'skipped'
     lines.push(
-      `  this run   ${fmtWhen(t.startedAt)} · ${t.status}` +
+      `  this run   ${fmtWhen(t.startedAt)} · ${t.status}${restoredWord(t)}` +
         `${ran ? ' · executed' : ''}${t.hash === '' ? ' · no key' : ` · key ${t.hash}`}`,
     )
     if (why.previousRun == null) {
       lines.push('  previous   (none — first recorded run of this task)')
     } else {
       const p = why.previousRun
-      lines.push(`  previous   ${fmtWhen(p.startedAt)} · ${p.status} · key ${p.hash}`)
+      lines.push(
+        `  previous   ${fmtWhen(p.startedAt)} · ${p.status}${restoredWord(p)} · key ${p.hash}`,
+      )
       // The key moved and the diff says by what: the verdict names it, so
       // an env-only change reads as one line, not "inputs differ" above a
       // table to scan.

package/src/orchestrator/doctor.ts

@@ -88,6 +88,8 @@ export interface InfoFacts {
   orphans: { artifacts: number; bytes: number }
   runs24h: number
   hits24h: number
+  /** Of `hits24h`, the hits that restored outputs; the rest were up to date. */
+  restored24h: number
   /** Tasks the retained history shows both passing and failing on unchanged inputs. */
   flakyTasks: FlakyTask[]
   lockfile: boolean
@@ -243,6 +245,7 @@ async function collectWorkspaceInfo(
     orphans: { artifacts: orphans.orphans, bytes: orphans.orphanBytes },
     runs24h: stats.runCountLast24h,
     hits24h: stats.hitCountLast24h,
+    restored24h: stats.restoredCountLast24h,
     // Same inputs, both outcomes — the history's definition of flaky, over
     // the 30 days it keeps. A run names its own findings in its footer;
     // this is the workspace's standing list.

package/src/orchestrator/metrics.ts

@@ -32,6 +32,8 @@ export interface RunSummaryRow {
   startedAt: number
   endedAt: number
   cacheHit: boolean | null
+  /** On a hit: true when outputs were restored, false when up-to-date (v31); null otherwise. */
+  restored: boolean | null
   /** Whether the task declared a `cache` block; null on rows older than the column. */
   cached: boolean | null
   hash: string
@@ -76,9 +78,10 @@ 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' | 'timedOut'
+    'cacheHit' | 'restored' | 'cached' | 'wallclockStartNs' | 'wallclockEndNs' | 'timedOut'
   > & {
     cacheHit: number | null
+    restored: number | null
     cached: number | null
     // NOT bigint: `bun:sqlite` hands these back as JS numbers (the handle
     // does not set `safeIntegers`), so the annotation claimed a precision
@@ -93,7 +96,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
     .query(
       `SELECT run_id AS runId, project, task, status, exit_code AS exitCode,
               duration_ms AS durationMs, started_at AS startedAt, ended_at AS endedAt,
-              cache_hit AS cacheHit, cached, hash,
+              cache_hit AS cacheHit, restored, cached, hash,
               cpu_ms AS cpuMs, peak_rss_bytes AS peakRssBytes,
               wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs,
               blocked_by AS blockedBy, timed_out AS timedOut,
@@ -104,6 +107,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
   return rows.map((r) => ({
     ...r,
     cacheHit: r.cacheHit === null ? null : Boolean(r.cacheHit),
+    restored: r.restored === null ? null : Boolean(r.restored),
     cached: r.cached === null ? null : Boolean(r.cached),
     timedOut: r.timedOut === null ? null : Boolean(r.timedOut),
     wallclockStartNs: r.wallclockStartNs === null ? null : r.wallclockStartNs.toString(),
@@ -134,6 +138,10 @@ export interface InvocationDetail {
   hitCount: number
   hitLocalCount: number
   hitRemoteCount: number
+  /** The hits by what they did to the disk (v31); they sum to `hitCount`. */
+  upToDateCount: number
+  restoredLocalCount: number
+  restoredRemoteCount: number
   exitOk: boolean
   commitSha: string | null
   branch: string | null
@@ -162,6 +170,9 @@ interface InvocationRawRow {
   hitCount: number
   hitLocalCount: number
   hitRemoteCount: number
+  upToDateCount: number
+  restoredLocalCount: number
+  restoredRemoteCount: number
   exitOk: number
   commitSha: string | null
   branch: string | null
@@ -181,6 +192,8 @@ const INVOCATION_COLUMNS = `
   started_at AS startedAt, ended_at AS endedAt, total_duration_ms AS totalDurationMs,
   task_count AS taskCount, failed_count AS failedCount, hit_count AS hitCount,
   hit_local_count AS hitLocalCount, hit_remote_count AS hitRemoteCount,
+  up_to_date_count AS upToDateCount, restored_local_count AS restoredLocalCount,
+  restored_remote_count AS restoredRemoteCount,
   exit_ok AS exitOk,
   commit_sha AS commitSha, branch, dirty, ci, ci_provider AS ciProvider,
   host, os, arch, vx_version AS vxVersion, tags`
@@ -215,6 +228,9 @@ function mapInvocation(r: InvocationRawRow): InvocationDetail {
     hitCount: r.hitCount,
     hitLocalCount: r.hitLocalCount,
     hitRemoteCount: r.hitRemoteCount,
+    upToDateCount: r.upToDateCount,
+    restoredLocalCount: r.restoredLocalCount,
+    restoredRemoteCount: r.restoredRemoteCount,
     exitOk: Boolean(r.exitOk),
     commitSha: r.commitSha,
     branch: r.branch,
@@ -340,11 +356,19 @@ export interface WhyDidThisRerun {
     hash: string
     status: string
     cacheHit: boolean | null
+    /** On a hit: outputs restored (true) or up-to-date (false); null otherwise. */
+    restored: boolean | null
     /** Whether the task declared a `cache` block; null on rows older than the column. */
     cached: boolean | null
     startedAt: number
   }
-  previousRun?: { hash: string; status: string; cacheHit: boolean | null; startedAt: number } | null
+  previousRun?: {
+    hash: string
+    status: string
+    cacheHit: boolean | null
+    restored: boolean | null
+    startedAt: number
+  } | null
   hashChanged?: boolean | null
   note: string
 }
@@ -427,7 +451,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      `SELECT id, hash, status, cache_hit AS cacheHit, cached, started_at AS startedAt
+      `SELECT id, hash, status, cache_hit AS cacheHit, restored, cached, started_at AS startedAt
        FROM runs WHERE run_id = ? AND project = ? AND task = ?`,
     )
     .get(runId, project, task) as
@@ -436,6 +460,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
         hash: string
         status: string
         cacheHit: number | null
+        restored: number | null
         cached: number | null
         startedAt: number
       }
@@ -454,7 +479,8 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
   // a key — a statement about inputs, made from no evidence.
   const prev = db
     .query(
-      `SELECT hash, status, cache_hit AS cacheHit, started_at AS startedAt, run_id AS runId
+      `SELECT hash, status, cache_hit AS cacheHit, restored, started_at AS startedAt,
+              run_id AS runId
        FROM runs WHERE project = ? AND task = ? AND id < ? AND ${KEYED_RUNS_SQL}
        ORDER BY id DESC LIMIT 1`,
     )
@@ -463,6 +489,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
         hash: string
         status: string
         cacheHit: number | null
+        restored: number | null
         startedAt: number
         runId: string | null
       }
@@ -477,6 +504,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
       hash: this_.hash,
       status: this_.status,
       cacheHit: this_.cacheHit === null ? null : Boolean(this_.cacheHit),
+      restored: this_.restored === null ? null : Boolean(this_.restored),
       cached: this_.cached === null ? null : Boolean(this_.cached),
       startedAt: this_.startedAt,
     },
@@ -485,6 +513,7 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
           hash: prev.hash,
           status: prev.status,
           cacheHit: prev.cacheHit === null ? null : Boolean(prev.cacheHit),
+          restored: prev.restored === null ? null : Boolean(prev.restored),
           startedAt: prev.startedAt,
         }
       : null,

package/src/orchestrator/run-artifacts.ts

@@ -17,6 +17,7 @@ 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'
 
 export interface SummarizeArgs {
   /** Empty string → default path; otherwise the explicit file path. */
@@ -45,6 +46,7 @@ export interface SummaryTaskJson {
   exitCode: number
   durationMs: number
   hash: string | null
+  restored?: boolean
   noCache?: true
   flaky?: { passes: number; failures: number; attempts: number }
   cpuMs?: number
@@ -83,6 +85,9 @@ function taskEntry(o: TaskOutcome, flaky?: FlakyFinding): SummaryTaskJson {
     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

package/src/orchestrator/run-records.ts

@@ -57,6 +57,9 @@ export function assembleRunRecords(input: RunRecordsInput): RunRecords {
   let failedCount = 0
   let hitLocalCount = 0
   let hitRemoteCount = 0
+  let upToDateCount = 0
+  let restoredLocalCount = 0
+  let restoredRemoteCount = 0
   for (const o of outcomes) {
     if (isGroupTask(o.node)) continue
     // aborted (killed by a shutdown signal) isn't a real run.
@@ -91,6 +94,7 @@ export function assembleRunRecords(input: RunRecordsInput): RunRecords {
       ...(o.wallclockStartNs !== undefined ? { wallclockStartNs: o.wallclockStartNs } : {}),
       ...(o.wallclockEndNs !== undefined ? { wallclockEndNs: o.wallclockEndNs } : {}),
       cacheHit: isCacheHit(o.status),
+      ...(isCacheHit(o.status) ? { restored: o.restored === true } : {}),
       ...(o.attempts !== undefined ? { attempts: o.attempts } : {}),
       cached: o.node.config.cache !== undefined,
       ...(o.blockedBy !== undefined ? { blockedBy: o.blockedBy } : {}),
@@ -101,6 +105,11 @@ export function assembleRunRecords(input: RunRecordsInput): RunRecords {
     if (o.status === 'failed') failedCount++
     if (o.status === 'cache-hit') hitLocalCount++
     if (o.status === 'cache-hit-remote') hitRemoteCount++
+    if (isCacheHit(o.status)) {
+      if (o.restored !== true) upToDateCount++
+      else if (o.status === 'cache-hit') restoredLocalCount++
+      else restoredRemoteCount++
+    }
   }
   const invocation: InvocationRecord = {
     runId,
@@ -117,6 +126,9 @@ export function assembleRunRecords(input: RunRecordsInput): RunRecords {
     hitCount: hitLocalCount + hitRemoteCount,
     hitLocalCount,
     hitRemoteCount,
+    upToDateCount,
+    restoredLocalCount,
+    restoredRemoteCount,
     exitOk: input.ok,
     commitSha: input.git.commitSha,
     branch: input.git.branch,

package/src/orchestrator/run-report.ts

@@ -139,7 +139,10 @@ export function formatRunReportMarkdown(result: RunResult): string {
     `**${t.total} task${t.total === 1 ? '' : 's'}**`,
     `${t.successful} success`,
     `${t.failed} failed`,
-    `${cached} cached`,
+    // What the hits did to the disk, as the run's summary splits them.
+    cached > 0
+      ? `${cached} cached (${t.upToDate} up-to-date, ${t.restoredLocal + t.restoredRemote} restored)`
+      : '0 cached',
   ]
   if (t.skipped > 0) parts.push(`${t.skipped} skipped`)
   if (t.aborted > 0) parts.push(`${t.aborted} aborted`)

package/src/orchestrator/telemetry.ts

@@ -180,6 +180,12 @@ export interface TaskTelemetry {
   sandboxViolations?: number
   /** On a failed persistent task: why it never became ready. `exitCode` is the child's own when it exited. Additive. */
   notReady?: 'timeout' | 'exited' | 'spawn'
+  /**
+   * On a cache hit: whether outputs were written this run (`true`) or the
+   * disk already matched the entry and nothing was restored (`false`, an
+   * up-to-date hit). Absent on every other status. Additive.
+   */
+  restored?: boolean
   /** bigint hrtime ns relative to run t=0, encoded as a decimal string. */
   wallclockStartNs?: string
   wallclockEndNs?: string
@@ -245,8 +251,17 @@ export interface RunSummaryRecord {
    */
   abortedCount: number
   hitCount: number
+  /** Hits by the layer that answered, up-to-date ones included. */
   hitLocalCount: number
   hitRemoteCount: number
+  /**
+   * Hits by what they did to the disk, as the run's summary counts them:
+   * nothing restored (up-to-date, from either layer), or outputs restored
+   * from the local or the remote layer. The three sum to `hitCount`.
+   */
+  upToDateCount: number
+  restoredLocalCount: number
+  restoredRemoteCount: number
   exitOk: boolean
   tasks: readonly TaskTelemetry[]
 }
@@ -276,10 +291,17 @@ export function assembleRunSummary(
   let failedCount = 0
   let hitLocalCount = 0
   let hitRemoteCount = 0
+  let upToDateCount = 0
+  let restoredLocalCount = 0
+  let restoredRemoteCount = 0
   for (const t of tasks) {
     if (t.status === 'failed') failedCount++
     if (t.cacheSource === 'local') hitLocalCount++
     else if (t.cacheSource === 'remote') hitRemoteCount++
+    else continue
+    if (t.restored !== true) upToDateCount++
+    else if (t.cacheSource === 'local') restoredLocalCount++
+    else restoredRemoteCount++
   }
   return {
     v: TELEMETRY_SCHEMA_VERSION,
@@ -293,6 +315,9 @@ export function assembleRunSummary(
     hitCount: hitLocalCount + hitRemoteCount,
     hitLocalCount,
     hitRemoteCount,
+    upToDateCount,
+    restoredLocalCount,
+    restoredRemoteCount,
     exitOk: timing.exitOk,
     tasks,
   }
@@ -558,6 +583,7 @@ export function taskTelemetryOf(o: TaskOutcome): TaskTelemetry {
   if (o.timedOut === true) t.timedOut = true
   if (o.sandboxViolations !== undefined) t.sandboxViolations = o.sandboxViolations
   if (o.notReady !== undefined) t.notReady = o.notReady
+  if (isCacheHit(o.status)) t.restored = o.restored === true
   if (o.wallclockStartNs !== undefined) t.wallclockStartNs = o.wallclockStartNs.toString()
   if (o.wallclockEndNs !== undefined) t.wallclockEndNs = o.wallclockEndNs.toString()
   return t