@vzn/vx 0.0.18 → 0.0.22

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
@@ -30,6 +32,8 @@ export interface RunSummaryRow {
   startedAt: number
   endedAt: number
   cacheHit: boolean | null
+  /** Whether the task declared a `cache` block; null on rows older than the column. */
+  cached: boolean | null
   hash: string
   cpuMs: number | null
   peakRssBytes: number | null
@@ -37,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 {
@@ -65,24 +74,38 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
     params.push(args.runId)
   }
   const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''
-  type RawRow = Omit<RunSummaryRow, 'cacheHit' | 'wallclockStartNs' | 'wallclockEndNs'> & {
+  type RawRow = Omit<
+    RunSummaryRow,
+    'cacheHit' | 'cached' | 'wallclockStartNs' | 'wallclockEndNs' | 'timedOut'
+  > & {
     cacheHit: number | null
-    wallclockStartNs: bigint | null
-    wallclockEndNs: bigint | 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
+    // 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(
       `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, hash,
+              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(),
   }))
@@ -257,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)
@@ -350,31 +373,91 @@ export interface WhyDidThisRerun {
   runId: string
   taskId: string
   found: boolean
-  thisRun?: { hash: string; status: string; cacheHit: boolean | null; startedAt: number }
+  thisRun?: {
+    hash: string
+    status: string
+    cacheHit: 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
   hashChanged?: boolean | null
   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, 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
-    | { hash: string; status: string; cacheHit: number | null; startedAt: number }
+    | {
+        id: number
+        hash: string
+        status: string
+        cacheHit: number | null
+        cached: number | null
+        startedAt: number
+      }
     | undefined
   if (!this_) {
     return {
@@ -391,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.
@@ -403,24 +486,34 @@ export function whyDidThisRerun(db: Database, runId: string, taskId: string): Wh
     runId,
     taskId,
     found: true,
-    thisRun: { ...this_, cacheHit: this_.cacheHit === null ? null : Boolean(this_.cacheHit) },
+    thisRun: {
+      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) }
       : null,
     hashChanged: prev && !noKey ? prev.hash !== this_.hash : null,
     note: noKey
       ? 'this task recorded no cache key (skipped, or a persistent task) — nothing to compare'
-      : prev && prev.hash !== this_.hash
-        ? 'cache key changed between the previous run and this one (inputs differ)'
-        : prev
-          ? // An unchanged key has two very different endings, and calling
-            // both a "re-run" answered the question wrong: a cache HIT did not
-            // re-run at all, so blaming `--no-cache` named a cause that cannot
-            // 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)
-          : 'no prior run for this (project, task)',
+      : this_.cached === 0
+        ? // Not a cache decision at all: the task runs every time by design,
+          // and its key is derived only so dependents can fold it.
+          'this task declares no `cache` block — it runs on every invocation; its key is folded by dependents only'
+        : prev && prev.hash !== this_.hash
+          ? 'cache key changed between the previous run and this one (inputs differ)'
+          : prev
+            ? // An unchanged key has two very different endings, and calling
+              // both a "re-run" answered the question wrong: a cache HIT did not
+              // re-run at all, so blaming `--no-cache` named a cause that cannot
+              // 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(db, runId, this_, prev)
+            : 'no prior run for this (project, task)',
   }
 }
 
@@ -450,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 }
 }
 
 /**
@@ -475,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.
  */
@@ -483,9 +615,11 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
   const [project, task] = splitTaskId(taskId)
   const this_ = db
     .query(
-      'SELECT hash, 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; startedAt: number } | undefined
+    .get(runId, project, task) as
+    | { id: number; hash: string; cached: number | null; status: string; startedAt: number }
+    | undefined
   if (!this_) {
     return {
       runId,
@@ -515,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 {
@@ -551,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,
@@ -559,33 +703,18 @@ export function cacheKeyDiff(db: Database, runId: string, taskId: string): Cache
       previousRunId: prev.runId,
       entries: [],
       unchangedCount: 0,
-      note: 'cache key changed but input fingerprints are unavailable (entry pruned); only the hash change is known',
+      note:
+        this_.cached === 0
+          ? // 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,

package/src/orchestrator/miss-save.ts

@@ -0,0 +1,232 @@
+// What a MISS leaves behind once the command exited 0 and the task will
+// save: the declared outputs resolved, the artifact and its rows saved in
+// one transaction, the whole-subtree output prefixes recorded for the
+// next hit's skip-restore, and the exact written paths marked against the
+// git snapshot so a same-project consumer re-spawns git only when its
+// globs can see them. Stale-hit-critical: a line moved here changes what
+// a later run replays. Moved out of execute-task.ts 2026-09-09 as pure
+// code motion.
+
+import path from 'node:path'
+import {
+  type CacheLayer,
+  type GitFilesCache,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+} from '../cache/index.js'
+import type { TaskNode } from '../graph/index.js'
+import { span, wholeSubtreePrefixes } from '../util/index.js'
+import type { Logger } from './logger.js'
+import type { TaskInputComponent } from './task-hash.js'
+
+/** A snapshot request for `recordOutputDirs`, taken at run end. */
+export interface OutputDirSnapshot {
+  hash: string
+  projectDir: string
+  prefixes: readonly string[]
+}
+
+export interface SaveMissArgs {
+  node: TaskNode
+  hash: string
+  cache: CacheLayer
+  log: Logger
+  workspaceRoot: string
+  nestedProjectDirs: string[]
+  gitFilesCache?: GitFilesCache | undefined
+  /** Declared `cache.outputs.files` / `.workspaceFiles`. */
+  outputs: string[]
+  wsOutputs: string[]
+  /**
+   * An ADDITIVE task's own set (item 588): the files its run added or
+   * changed under its declared outputs, resolved by execute-task against
+   * the stamp it took before the run. Replaces the glob walk below, which
+   * would also take the upstream's files the task adds beside.
+   */
+  ownOutputFiles?: string[] | undefined
+  /** The Tier-3 input fingerprint rows captured by the pre-exec describe. */
+  captured: readonly TaskInputComponent[]
+  command: string
+  durationMs: number
+  stdout: string
+  /** The execution's usage, when the runner reported it — rides the artifact's sidecar. */
+  cpuMs?: number | undefined
+  peakRssBytes?: number | undefined
+  /** When present, the directory snapshot is queued here instead of taken now. */
+  outputDirSnapshots?: OutputDirSnapshot[] | undefined
+  /**
+   * When present, the cache save itself runs off the execution slot: the
+   * outputs are resolved and the git snapshot marked here, in the slot
+   * (a same-project downstream task reads both), and the pack + write +
+   * index go to the run's save lane (save-lane.ts).
+   */
+  deferSave?: ((save: () => Promise<void>) => Promise<void>) | undefined
+}
+
+/** `landed` settles when the entry is in the cache — at once without a lane. */
+export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<void> }> {
+  const { node, cache, log } = a
+  const endResolve = span('miss: resolve outputs')
+  const outputFiles =
+    a.ownOutputFiles ??
+    (await resolveOutputs({
+      projectDir: node.projectDir,
+      outputs: a.outputs,
+      nestedProjectDirs: a.nestedProjectDirs,
+    }))
+  const wsOutputFiles = await resolveWorkspaceOutputs({
+    workspaceRoot: a.workspaceRoot,
+    outputs: a.wsOutputs,
+  })
+  endResolve()
+  // The mirror of the input warning: declared outputs that resolve to
+  // nothing save an empty artifact, and the next hit "restores" it —
+  // the build that ran nowhere looks like a build that ran. `files: []`
+  // is a deliberate cached no-op and says nothing; a glob that matched
+  // nothing is a glob against the wrong directory.
+  if (
+    a.outputs.length + a.wsOutputs.length > 0 &&
+    outputFiles.length + wsOutputFiles.length === 0
+  ) {
+    // One cause is common enough to name, because the task shows no other
+    // symptom: a sandboxed task with no write grant. Its writes land in the
+    // sandbox's own scratch and never reach disk, and whether the shell
+    // even notices depends on the layout — in a single-package workspace
+    // (project dir === workspace root) the write SUCCEEDS into that
+    // scratch and the task exits 0, so this warning is the only thing that
+    // says the build produced nothing (item 444). A declared
+    // `cache.outputs` is not a write grant; `exec.sandbox.allow.write` is.
+    const sandboxed = node.config.exec?.sandbox !== undefined
+    const grantsWrite = (node.config.exec?.sandbox?.allow?.write?.length ?? 0) > 0
+    log.status(
+      `[vx] ${node.id}: cache.outputs matched no files (${[...a.outputs, ...a.wsOutputs].join(', ')}) — ` +
+        `an empty artifact is saved; a later hit restores nothing` +
+        (sandboxed && !grantsWrite
+          ? ` — the task is sandboxed and declares no exec.sandbox.allow.write, so its writes never reached disk`
+          : ''),
+    )
+  }
+  const save = async (): Promise<void> => {
+    const endSave = span('miss: save')
+    // Tier-3 input fingerprint: the digest rows captured by the pre-exec
+    // describe above, persisted with the entry inside `cache.save`'s
+    // transaction. Miss path only — the warm/hit path never reaches here.
+    await cache.save({
+      hash: a.hash,
+      projectDir: node.projectDir,
+      outputFiles,
+      ...(wsOutputFiles.length > 0
+        ? { workspaceOutputFiles: wsOutputFiles, workspaceRoot: a.workspaceRoot }
+        : {}),
+      inputComponents: a.captured.map((c) => ({ entryHash: a.hash, ...c })),
+      // No `exitCode`: the save only runs under `effectiveExitCode === 0`, and
+      // the contract no longer accepts one — so the invariant is enforced by
+      // the type rather than by every call site remembering the gate.
+      entry: {
+        taskId: node.id,
+        command: a.command,
+        durationMs: a.durationMs,
+        stdout: a.stdout,
+        ...(a.cpuMs !== undefined ? { cpuMs: a.cpuMs } : {}),
+        ...(a.peakRssBytes !== undefined ? { peakRssBytes: a.peakRssBytes } : {}),
+      },
+    })
+    endSave()
+    // 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
+    // size and mtime (item 886).
+    cache.recordOutputStamps?.(a.hash, node.projectDir, a.workspaceRoot)
+    // The directory snapshot behind the next hit's skip-restore, taken at
+    // run end from the run's list: the task wrote these directories
+    // milliseconds ago, inside the snapshot's racy window, so a snapshot
+    // taken here was refused and the next hit walked every output tree —
+    // 1,000 walks, 296 ms accumulated, on the first warm run after a cold
+    // build of the 1,000-project bench (2026-09-10). A caller with no
+    // list gets no snapshot: recording here was that same refusal (item
+    // 637 deleted the fallback and nothing reddened), and the next hit
+    // walks, as it did.
+    const savedDirPrefixes = wholeSubtreePrefixes(a.outputs)
+    if (savedDirPrefixes !== null && a.outputDirSnapshots !== undefined) {
+      a.outputDirSnapshots.push({
+        hash: a.hash,
+        projectDir: node.projectDir,
+        prefixes: savedDirPrefixes,
+      })
+    }
+  }
+  markWritten(a, outputFiles, wsOutputFiles)
+  // Off the slot when the run keeps a lane (the save lane bounds and
+  // drains it); in the slot otherwise — an embedder without a lane gets
+  // the entry before the outcome.
+  if (a.deferSave !== undefined) return { landed: a.deferSave(save) }
+  await save()
+  return { landed: Promise.resolve() }
+}
+
+/** What `markUnsaved` reads of a miss: where its declared outputs are. */
+export type UnsavedArgs = Pick<
+  SaveMissArgs,
+  'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'gitFilesCache' | 'outputs' | 'wsOutputs'
+>
+
+/**
+ * A miss that ran here and saves nothing (it failed, the policy writes
+ * nothing, an upstream failed, its key no longer held) still wrote its
+ * outputs, and a same-project reader after it must see them as it sees a
+ * save's: resolved and marked the same way.
+ */
+export async function markUnsaved(a: UnsavedArgs): Promise<void> {
+  const endResolve = span('miss: resolve outputs')
+  const outputFiles = await resolveOutputs({
+    projectDir: a.node.projectDir,
+    outputs: a.outputs,
+    nestedProjectDirs: a.nestedProjectDirs,
+  })
+  const wsOutputFiles = await resolveWorkspaceOutputs({
+    workspaceRoot: a.workspaceRoot,
+    outputs: a.wsOutputs,
+  })
+  endResolve()
+  markWritten(a, outputFiles, wsOutputFiles)
+}
+
+/**
+ * The task just wrote outputs to the project's tree. Record the exact
+ * declared-output paths as changed (same as the cache-hit restore path)
+ * instead of dropping the whole snapshot: a downstream same-project task
+ * then re-spawns git ONLY when its input globs can actually see one of
+ * these paths. On a 1000-package cold run this removes ~one synchronous
+ * `git ls-files` spawn per project (the single largest cold-run cost —
+ * 22% of CPU in profiling). Contract: outputs must be declared — an
+ * executed task that writes files outside `cache.outputs.files` which a
+ * same-project downstream task reads is undeclared behavior (the restore
+ * path already assumes it).
+ */
+function markWritten(
+  a: Pick<SaveMissArgs, 'node' | 'workspaceRoot' | 'gitFilesCache'>,
+  outputFiles: readonly string[],
+  wsOutputFiles: readonly string[],
+): void {
+  const { projectDir } = a.node
+  if (outputFiles.length > 0) {
+    a.gitFilesCache?.markOutputsChanged(
+      projectDir,
+      outputFiles.map((p) => path.relative(projectDir, p).split(path.sep).join('/')),
+    )
+  }
+  // Declared workspace outputs may have landed inside OTHER projects' dirs
+  // (no-boundary escape hatch) — mark the exact paths against every
+  // partition that can see them.
+  if (wsOutputFiles.length > 0) {
+    a.gitFilesCache?.markWorkspaceOutputsChanged(
+      a.workspaceRoot,
+      wsOutputFiles.map((f) => path.relative(a.workspaceRoot, f).split(path.sep).join('/')),
+    )
+  }
+  // The workspace-wide partition (when one exists) spans this project's
+  // subtree, so it inherits the same "undeclared writes are only visible
+  // to git" rule as the project drop above.
+  if (outputFiles.length + wsOutputFiles.length > 0) {
+    a.gitFilesCache?.invalidateWorkspacePartition()
+  }
+}