rvlib-shipkit 0.38.0 → 1.0.0

package/src/ledger/git-scan.ts

@@ -1,6 +1,6 @@
 // WHAT IS ON DISK RIGHT NOW, as git object ids, using git's own index.
 //
-// A cache key needs the identity of the files a unit reads, INCLUDING files
+// A cache key needs the identity of the files a check reads, INCLUDING files
 // that are untracked or modified. `git hash-object` per file is O(files) and
 // re-reads everything; git's index already carries a stat cache that answers
 // "unchanged" without reading the blob. So: a scratch index of our own, per
@@ -9,20 +9,21 @@
 // FOUR THINGS THIS FILE EXISTS TO GET RIGHT, each reproduced before it was
 // written:
 //
-//  1. PER PATH ADDS, EXIT CODE CHECKED. `git add -A -- a.txt missing/` exits
-//     128, stages NOTHING, and `write-tree` then hands back the tree of the
-//     LAST successful write. Measured on a scratch repo: the batched form
-//     returned HEAD's tree while a.txt was modified on disk, so every key
-//     derived from it described a file nobody had. One add per path turns that
-//     into one loud failure on one path.
+//  1. ONE ADD, EXIT CODE CHECKED, NOTHING MISSING IN IT. `git add -A -- a.txt
+//     missing/` exits 128, stages NOTHING, and `write-tree` then hands back
+//     the tree of the LAST successful write. Measured on a scratch repo: that
+//     tree was HEAD's while a.txt was modified on disk, so every key derived
+//     from it described a file nobody had. So a missing path never reaches the
+//     add (rule 2), and a failed add throws before any `write-tree`, with
+//     git's own words, which name the path it refused.
 //  2. A MISSING DECLARED PATH IS NOT A GIT ERROR. A repo without `tests/` is
 //     normal, and hard-failing the gate on it would be wrong, so a path that
 //     does not exist never reaches `git add`: it comes back in `missing` and
-//     the caller refuses to cache that unit. That keeps rule 1's hard failure
+//     the caller refuses to cache that check. That keeps rule 1's hard failure
 //     for what it is actually about, git going wrong on a path that IS there.
 //  3. ONLY AN IGNORED PATH IS FORCE ADDED. `git add -Af` on a broad path force
 //     adds node_modules and costs 17.7s; the ignored paths that genuinely hold
-//     declared inputs here (.rv-social/patreon/, .rv-assets/out/) cost 76ms.
+//     declared inputs here (.shipkit/social/patreon/, .shipkit/assets/out/) cost 76ms.
 //     One `ls-files --others -i --directory` names them, and node_modules is
 //     refused force-add at any depth.
 //  4. THE SCRATCH INDEX IS SHARED, SO IT IS CONTENDED. Measured: 10 parallel
@@ -30,8 +31,10 @@
 //     agents in one checkout is the normal case here, so lock contention is
 //     retried and only a NON lock failure is fatal.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'fs'
-import { isAbsolute, join, normalize } from 'path'
+import { isAbsolute, join, normalize, resolve } from 'path'
+import { probeGitRoot } from '../core/git-root.ts'
 import { treePrefix } from '../core/nesting.ts'
+import { gitBin } from '../core/git-bin.ts'
 
 /** what a scan measured. Every OID is a git object id of the CURRENT disk
  *  content, tracked or not. */
@@ -45,6 +48,11 @@ export type ScanResult = {
     /** repo-relative path → ignored content under it that is NOT in the key
      *  (node_modules only, by policy: toolchain-identity.ts owns installs) */
     excluded: Map<string, string[]>
+    /** git's ignored answer for the declared paths, kept so a re-scan of the
+     *  same paths can skip asking again */
+    ignored: string[]
+    /** root tree of the force-add index, null when nothing was force-added */
+    ignoredTreeOid: string | null
     /** wall time of the whole scan */
     ms: number
 }
@@ -63,7 +71,7 @@ const LOCK_RE = /Unable to create '.*\.lock'|index\.lock/i
 const RETRIES = 12
 
 const git = (root: string, args: string[], indexFile: string): { code: number; out: string } => {
-    const p = Bun.spawnSync(['git', ...args], {
+    const p = Bun.spawnSync([gitBin(), ...args], {
         cwd: root,
         stdout: 'pipe',
         stderr: 'pipe',
@@ -99,9 +107,9 @@ function gitOrThrow(root: string, args: string[], indexFile: string): string {
  *  `git add -- .` plus `write-tree` measures 30 to 40ms, FASTER than the
  *  persistent index it replaces.
  *
- *  IGNORED is a separate index for the force-adds, so a path one unit named
- *  can never leak into the whole-tree id another unit is keyed on. Without the
- *  split, one unit's key changed depending on which OTHER units were in the
+ *  IGNORED is a separate index for the force-adds, so a path one check named
+ *  can never leak into the whole-tree id another check is keyed on. Without the
+ *  split, one check's key changed depending on which OTHER checks were in the
  *  run, which is exactly the silently narrowed key the excluded list exists to
  *  prevent. It stays warm across runs: an entry left in it can only affect the
  *  path it belongs to, never the root tree.
@@ -111,9 +119,9 @@ function gitOrThrow(root: string, args: string[], indexFile: string): string {
  *  reports a force-added path as no longer ignored, and the next run then
  *  plain-adds it, which exits 1 and takes the scan down. */
 export function indexPaths(root: string): { scratch: string; ignored: string; real: string } {
-    const p = Bun.spawnSync(['git', 'rev-parse', '--absolute-git-dir'], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
-    if (p.exitCode !== 0) throw new GitScanError(`not a git repository: ${root} (${p.stderr.toString().trim()})`)
-    const gitDir = p.stdout.toString().trim()
+    const g = probeGitRoot(root)
+    if (g.root == null) throw new GitScanError(`not a git repository: ${root} (${g.error})`)
+    const gitDir = g.root.gitDir
     const dir = join(gitDir, 'shipkit')
     mkdirSync(dir, { recursive: true })
     const real = join(gitDir, 'index')
@@ -200,7 +208,7 @@ const underNodeModules = (p: string): boolean => p.split('/').includes('node_mod
  * stale describes files nobody has, and a key built on it is a false green
  * waiting for its first hit.
  */
-export function scanPaths(root: string, rawPaths: string[]): ScanResult {
+export function scanPaths(root: string, rawPaths: string[], prior?: ScanResult): ScanResult {
     const started = performance.now()
     const { scratch: indexFile, ignored: ignoredIndex, real: realIndex } = indexPaths(root)
     const wanted = [...new Set(rawPaths.map(normalizeInput))].sort()
@@ -213,7 +221,15 @@ export function scanPaths(root: string, rawPaths: string[]): ScanResult {
     // answers "is this declared path itself ignored": `--directory` collapses
     // a dir whose ENTIRE content is ignored, so the answer comes back as the
     // dir with a trailing slash.
-    const ignored = toAdd.length === 0
+    //
+    // A re-scan (`prior`) reuses the first answer while the set of missing
+    // paths is the same: a declared path that appeared was never asked about.
+    // A path that became ignored in between makes its plain add fail, which
+    // throws, and a throw stores nothing: the one failure mode stays loud.
+    const sameMissing = prior != null && prior.missing.join('\n') === [...new Set(missing)].sort().join('\n')
+    const ignored = prior != null && sameMissing
+        ? prior.ignored
+        : toAdd.length === 0
         ? []
         : gitOrThrow(root, ['ls-files', '--others', '-i', '--exclude-standard', '--directory', '--', ...toAdd], realIndex)
             .split('\n')
@@ -238,12 +254,31 @@ export function scanPaths(root: string, rawPaths: string[]): ScanResult {
     // a path git itself calls ignored must NOT get the plain add: `git add --
     // <ignored>` exits 1 and takes the whole scan down with it
     const ignoredSet = new Set(ignored)
-    for (const p of toAdd) if (!ignoredSet.has(p)) gitOrThrow(root, ['add', '--', p], indexFile)
-    // force-adds land in their OWN index, so a path one unit named can never
-    // ride inside the whole-tree id another unit is keyed on
-    for (const p of forceAdd) gitOrThrow(root, ['add', '-Af', '--', p], ignoredIndex)
+    const plainAdds = toAdd.filter((p) => !ignoredSet.has(p))
+    if (plainAdds.length > 0) gitOrThrow(root, ['add', '--', ...plainAdds], indexFile)
+    // force-adds land in their OWN index, so a path one check named can never
+    // ride inside the whole-tree id another check is keyed on
+    if (forceAdd.length > 0) gitOrThrow(root, ['add', '-Af', '--', ...forceAdd], ignoredIndex)
 
+    const excluded = excludedBy(wanted, ignored, new Set(forceAdd))
+    // write-tree and every `<tree>:<path>` answer are pure functions of the
+    // index bytes, so staged bytes this process already derived need no git.
+    // the post-run re-hash of an untouched tree is the common hit
+    const memoKey = derivedKey(root, indexFile, forceAdd.length > 0 ? ignoredIndex : null, wanted, missing)
+    const hit = memoKey == null ? undefined : derived.get(memoKey)
+    if (hit != null)
+        return { ...hit, oidByPath: new Map(hit.oidByPath), missing: [...hit.missing], excluded, ignored, ms: performance.now() - started }
     const treeOid = gitOrThrow(root, ['write-tree'], indexFile).trim()
+    const ignoredTreeOid = forceAdd.length > 0 ? gitOrThrow(root, ['write-tree'], ignoredIndex).trim() : null
+    const done = (oidByPath: Map<string, string>): ScanResult => {
+        const r: ScanResult = { treeOid, oidByPath, missing: [...new Set(missing)].sort(), excluded, ignored, ignoredTreeOid, ms: performance.now() - started }
+        if (memoKey != null) remember(memoKey, { ...r, oidByPath: new Map(oidByPath), missing: [...r.missing] })
+        return r
+    }
+    // both root trees unchanged and the same paths on disk: every path under
+    // them names the same object, so the per path answer is the prior one
+    if (prior != null && prior.treeOid === treeOid && prior.ignoredTreeOid === ignoredTreeOid && prior.missing.join('\n') === [...new Set(missing)].sort().join('\n'))
+        return done(new Map(prior.oidByPath))
     const oidByPath = new Map<string, string>()
     // a declared path is relative to root, and `<tree>:<path>` reads from the
     // work tree root. In a nested repo the two differ, so every query carries
@@ -255,11 +290,11 @@ export function scanPaths(root: string, rawPaths: string[]): ScanResult {
     if (wanted.includes(WHOLE_TREE) && prefix === '') oidByPath.set(WHOLE_TREE, treeOid)
     const forceSet = new Set(forceAdd)
     const plain = [...named.filter((p) => !forceSet.has(p)), ...(wanted.includes(WHOLE_TREE) && prefix !== '' ? [WHOLE_TREE] : [])]
-    for (const [tree, paths, index] of [[treeOid, plain, indexFile], [null, forceAdd, ignoredIndex]] as const) {
-        if (paths.length === 0) continue
-        const root_ = tree ?? gitOrThrow(root, ['write-tree'], index).trim()
+    for (const [tree, paths, index] of [[treeOid, plain, indexFile], [ignoredTreeOid, forceAdd, ignoredIndex]] as const) {
+        if (paths.length === 0 || tree == null) continue
+        const root_ = tree
         const query = paths.map((p) => `${root_}:${underRoot(p)}`).join('\n')
-        const p = Bun.spawnSync(['git', 'cat-file', '--batch-check'], {
+        const p = Bun.spawnSync([gitBin(), 'cat-file', '--batch-check'], {
             cwd: root,
             stdin: Buffer.from(`${query}\n`),
             stdout: 'pipe',
@@ -279,26 +314,52 @@ export function scanPaths(root: string, rawPaths: string[]): ScanResult {
         })
     }
 
+    return done(oidByPath)
+}
+
+/** scans already derived in this process, by the exact bytes they staged */
+const derived = new Map<string, ScanResult>()
+const DERIVED_MAX = 64
+
+/** the repo, both staged index files byte for byte, and the question asked.
+ *  null when an index cannot be read: no key, so no reuse */
+function derivedKey(root: string, index: string, ignoredIndex: string | null, wanted: string[], missing: string[]): string | null {
+    try {
+        const bytes = (f: string | null): string => (f == null ? '-' : Bun.hash(readFileSync(f)).toString(36))
+        return [resolve(root), bytes(index), bytes(ignoredIndex), wanted.join('\n'), [...new Set(missing)].sort().join('\n')].join('\0')
+    } catch {
+        return null
+    }
+}
+
+function remember(key: string, r: ScanResult): void {
+    derived.delete(key)
+    derived.set(key, r)
+    if (derived.size > DERIVED_MAX) derived.delete(derived.keys().next().value!)
+}
+
+/** which declared path is blind to which ignored content */
+function excludedBy(wanted: string[], ignored: string[], forced: Set<string>): Map<string, string[]> {
     const excluded = new Map<string, string[]>()
     for (const d of ignored) {
         // EVERY owner that covers it, not the first one found, and membership
-        // must not depend on what OTHER units declared. `.` sorts first and
+        // must not depend on what OTHER checks declared. `.` sorts first and
         // covers everything, so a `find` here handed the whole exclusion list
-        // to the whole-tree unit and left every narrower unit claiming it was
+        // to the whole-tree check and left every narrower check claiming it was
         // blind to nothing. Filtering force-added paths out globally had the
-        // same shape: one unit naming `ign` deleted `excluded=ign` from a
-        // whole-tree unit that is still blind to it. Measured both ways, one
-        // unit producing two keys for one unchanged tree, and the component
+        // same shape: one check naming `ign` deleted `excluded=ign` from a
+        // whole-tree check that is still blind to it. Measured both ways, one
+        // check producing two keys for one unchanged tree, and the component
         // that vanished is the one that exists to stop a silently narrowed key.
         for (const w of wanted) {
             if (!(w === WHOLE_TREE || d === w || d.startsWith(`${w}/`))) continue
             // the one owner that is NOT blind: it named the path itself, so it
             // got the content through the force-add
-            if (d === w && forceSet.has(d)) continue
+            if (d === w && forced.has(d)) continue
             excluded.set(w, [...(excluded.get(w) ?? []), d])
         }
     }
-    return { treeOid, oidByPath, missing: [...new Set(missing)].sort(), excluded, ms: performance.now() - started }
+    return excluded
 }
 
 /**
@@ -319,7 +380,7 @@ export function hashFiles(root: string, files: string[]): { oids: Map<string, st
     const missing = wanted.filter((f) => !existsSync(join(root, f)))
     const present = wanted.filter((f) => existsSync(join(root, f)))
     if (present.length === 0) return { oids, missing }
-    const p = Bun.spawnSync(['git', 'hash-object', '--stdin-paths'], {
+    const p = Bun.spawnSync([gitBin(), 'hash-object', '--stdin-paths'], {
         cwd: root,
         stdin: Buffer.from(`${present.join('\n')}\n`),
         stdout: 'pipe',

package/src/ledger/ledger.ts

@@ -1,4 +1,4 @@
-// THE LEDGER — the CONTENT half of the three populations: a unit's answer,
+// THE LEDGER — the CONTENT half of the three populations: a check's answer,
 // stored under the identity of the question it answered, replayed only when
 // that identity is bit-for-bit the same question again.
 //
@@ -7,11 +7,11 @@
 // green, so every rule below exists because a specific failure was reproduced
 // during the design pass:
 //
-//  1. DEFAULT DENY. A unit that declared nothing is never replayed and never
+//  1. DEFAULT DENY. A check that declared nothing is never replayed and never
 //     stored. Forgetting to declare costs speed, never correctness, which is
 //     what makes the burn-down a to-do rather than a hazard.
 //  2. POST RUN RE HASH. Results are BUFFERED while the gate runs and written
-//     only after the inputs are hashed a second time. A unit whose inputs
+//     only after the inputs are hashed a second time. A check whose inputs
 //     moved between its run and that second hash answered about a tree that no
 //     longer exists, so its result is discarded rather than stored under a key
 //     that describes the file as it was BEFORE the edit. Three agents in one
@@ -22,26 +22,38 @@
 //     configurably. Every remaining hole is then capped at "an agent saw a
 //     stale local green", never "a stale green authorised a publish".
 //  5. NO SILENT REPLAY. Every replayed line is stamped with the word
-//     `replayed` and what the measured run cost, and the run prints hit, miss
-//     and uncacheable counts. A cached green that cannot be told from a
-//     measured green is the bug this whole design exists to not ship.
+//     `cached` and what the run it came from cost, and the run prints the
+//     cached, ran and never cached counts (core/outcome-words.ts owns the
+//     words). A cached green that cannot be told from a green that ran is the
+//     bug this whole design exists to not ship.
 //  6. ONLY A GREEN REPLAYS. A red is the one outcome an agent acts on
 //     immediately, and acting on it changes content, which moves the key — so
 //     replaying a red buys almost nothing, while an undeclared flake would
 //     pin its red until something unrelated happened to change. The safe
 //     direction here is re-measuring, and it costs only the run that was
 //     already going red.
+//  7. A READS ANSWER CARRIES ITS READ SET. A `run` check keyed on what it
+//     read (git-key.ts READS) stores every file hash, existence and listing
+//     hash beside the answer, and replays only while all of them still hold
+//     on disk. The same set is re-checked at commit, so an edit landing
+//     between the read and the store throws the answer away (rule 2). A body
+//     that reached the world (exec, fetch, tool) stores nothing.
+import { dirname, join } from 'path'
 import type { RvtConfig } from '../ts/config.ts'
 import type { Line } from '../core/wire.ts'
-import { KeyLayer, type UnitDecl, type UnitKey } from './git-key.ts'
+import { KeyLayer, type CheckDecl, type CheckKey } from './git-key.ts'
 import { entryPath, FRESH_ENV, KEEP_MS, readStored, storeRoot, sweepStore, writeStored } from './store.ts'
+import type { Problem } from '../problems/problem-line.ts'
+import { cachedStamp, outcomeCounts } from '../core/outcome-words.ts'
+import { readSetDrift, type ReadSet } from '../core/read-set.ts'
+import { RepoView } from './repo-view.ts'
 
 /** the env var that turns the READ path on or off for a whole session.
  *  Writing is unconditional either way: an entry nobody reads breaks nothing. */
 export const LEDGER_ENV = 'SHIPKIT_LEDGER'
 
-/** where unit results live inside the one store */
-const NS = 'units'
+/** where check results live inside the one store */
+const NS = 'checks'
 
 /** whether the read path is on by default, before any flag.
  *
@@ -53,21 +65,28 @@ const NS = 'units'
  *  `SHIPKIT_LEDGER=0` turns it off for a session, and this line is the revert. */
 export const READ_DEFAULT = true
 
-export type UnitOutcome = {
+export type CheckOutcome = {
     /** only a green is ever stored (rule 6 above) */
     status: 'pass' | 'warn'
     lines: Line[]
     /** the task-runner headline, which the gate greps for the test count */
     lastLine?: string
+    /** the file anchored findings of this verdict, so a replay re-prints them
+     *  into the problems pane. A build step's lines are empty, so they cannot
+     *  be derived again from what is stored */
+    problems?: Problem[]
     /** what the measured run cost, ms — printed on the replay so a hit says
      *  what it saved instead of pretending the work was free */
     measuredMs: number
 }
 
+/** what a READS answer is stored as: the verdict and what it read */
+type Stored = CheckOutcome & { reads?: ReadSet }
+
 export type LedgerOpts = {
     /** the cli entry driving this run (toolchain identity needs it) */
     cliEntry: string
-    /** read the store at all. false = every unit is measured this run. */
+    /** read the store at all. false = every check is measured this run. */
     read?: boolean
     /** this run re-measures everything, and re-stores what it measured */
     fresh?: boolean
@@ -77,9 +96,9 @@ export type LedgerOpts = {
 }
 
 export type CommitReport = {
-    /** unit ids written to the store */
+    /** check ids written to the store */
     stored: string[]
-    /** unit ids whose result was thrown away because an input moved */
+    /** check ids whose result was thrown away because an input moved */
     discarded: string[]
     /** the paths that moved */
     drifted: string[]
@@ -97,11 +116,13 @@ export function ledgerReadEnabled(): boolean {
 }
 
 export class Ledger {
-    private readonly buffered = new Map<string, UnitOutcome>()
-    private readonly keys = new Map<string, UnitKey>()
+    private readonly buffered = new Map<string, Stored>()
+    private viewMemo: RepoView | null = null
+    private readonly keys = new Map<string, CheckKey>()
     private hits = 0
     private misses = 0
     private unkeyed = 0
+    private joined = 0
 
     private constructor(
         readonly layer: KeyLayer,
@@ -111,43 +132,87 @@ export class Ledger {
         private readonly now: () => number,
     ) {}
 
-    static open(root: string, decls: UnitDecl[], o: LedgerOpts): Ledger {
+    static open(root: string, decls: CheckDecl[], o: LedgerOpts): Ledger {
         const layer = KeyLayer.open(root, decls, { cliEntry: o.cliEntry, cfg: o.cfg })
         const fresh = o.fresh === true || process.env[FRESH_ENV] != null
         const reading = (o.read ?? ledgerReadEnabled()) && !fresh
         return new Ledger(layer, storeRoot(root), reading, o.now ?? Date.now)
     }
 
-    /** the key for a unit, computed once per run and remembered: `keyFor`
+    /** the key for a check, computed once per run and remembered: `keyFor`
      *  re-derives the component list every call, and the gate asks twice (once
      *  to replay, once to record). */
-    private key(id: string): UnitKey {
+    private key(id: string): CheckKey {
         let k = this.keys.get(id)
         if (k == null) { k = this.layer.keyFor(id); this.keys.set(id, k) }
         return k
     }
 
-    private path(k: UnitKey): string {
-        return entryPath(this.store, NS, `${k.kind}:${k.id}`, k.key!)
+    private path(k: CheckKey): string {
+        return entryPath(this.store, NS, k.id, k.key!)
+    }
+
+    /** the file list this run lists and validates against, taken once */
+    view(): RepoView {
+        this.viewMemo ??= RepoView.open(this.layer.root)
+        return this.viewMemo
     }
 
-    /** the stored answer for this unit, or null when it must run. Counts what
+    /** the stored answer for this check, or null when it must run. Counts what
      *  it was asked, so the run can report hit/miss/uncacheable honestly. */
-    replay(id: string): UnitOutcome | null {
+    replay(id: string): CheckOutcome | null {
         const k = this.key(id)
         if (k.key == null) { this.unkeyed++; return null }
         if (!this.reading) { this.misses++; return null }
-        const e = readStored<UnitOutcome>(this.path(k), k.key)
+        const e = readStored<Stored>(this.path(k), k.key)
         if (e == null || !Array.isArray(e.payload.lines)) { this.misses++; return null }
+        if (k.population === 'reads' && (e.payload.reads == null || this.driftOf(e.payload.reads, this.view()) != null)) { this.misses++; return null }
         this.hits++
         return e.payload
     }
 
-    /** buffer what a unit just measured. Nothing reaches the store until
-     *  commit() has re-hashed the inputs (rule 2). */
-    record(id: string, outcome: UnitOutcome): void {
+    /** the stored read set of a READS check, as the last store wrote it */
+    storedReads(id: string): ReadSet | null {
+        const k = this.key(id)
+        if (k.key == null || k.population !== 'reads') return null
+        return readStored<Stored>(this.path(k), k.key)?.payload.reads ?? null
+    }
+
+    private driftOf(reads: ReadSet, view: RepoView): string | null {
+        return readSetDrift(this.layer.root, reads, (g) => (view.fallback != null ? null : view.list(g)))
+    }
+
+    /** where askers of this check's exact question meet while one of them is
+     *  measuring it (core/attach.ts), or null when there is no shared
+     *  question: no key, or a run that must measure for itself (a release,
+     *  --fresh, reads off) */
+    attachSlot(id: string): string | null {
+        if (!this.reading) return null
+        const k = this.key(id)
+        // a READS key names the question and not the tree, so two runs over
+        // different trees share it: only one over this tree may answer
+        if (k.population === 'reads') return null
+        return k.key == null ? null : entryPath(join(dirname(this.store), 'inflight'), NS, k.id, k.key).replace(/\.json$/, '')
+    }
+
+    /** a check that missed the store and then adopted another run's in
+     *  flight answer: counted apart, so the header never claims it measured */
+    noteAttached(): void {
+        if (this.misses > 0) this.misses--
+        this.joined++
+    }
+
+    /** buffer what a check just measured. Nothing reaches the store until
+     *  commit() has re-hashed the inputs (rule 2). A READS check with no read
+     *  set (it reached the world) is never stored (rule 7). */
+    record(id: string, outcome: CheckOutcome, reads?: ReadSet | null): void {
         const k = this.key(id)
         if (k.key == null) return
+        if (k.population === 'reads') {
+            if (reads == null) return
+            this.buffered.set(id, { ...outcome, reads })
+            return
+        }
         this.buffered.set(id, outcome)
     }
 
@@ -161,42 +226,51 @@ export class Ledger {
         const touched = this.layer.unitsTouchedBy(d.drifted)
         const stored: string[] = []
         const discarded: string[] = []
+        const drifted = [...d.drifted]
+        // a fresh list, never this run's: the question is whether the tree
+        // still is what the body read
+        let fresh: RepoView | null = null
         for (const [id, outcome] of this.buffered) {
             if (touched.has(id)) { discarded.push(id); continue }
+            if (outcome.reads != null) {
+                fresh ??= RepoView.open(this.layer.root, this.viewMemo)
+                const moved = this.driftOf(outcome.reads, fresh)
+                if (moved != null) { discarded.push(id); drifted.push(moved); continue }
+            }
             const k = this.key(id)
             writeStored(this.path(k), k.key!, outcome, this.now())
             stored.push(id)
         }
         sweepStore(this.store, NS, this.now(), KEEP_MS)
-        return { stored: stored.sort(), discarded: discarded.sort(), drifted: d.drifted, error: null, ms: performance.now() - started }
+        return { stored: stored.sort(), discarded: discarded.sort(), drifted, error: null, ms: performance.now() - started }
     }
 
-    get counts(): { hit: number; miss: number; uncacheable: number } {
-        return { hit: this.hits, miss: this.misses, uncacheable: this.unkeyed }
+    get counts(): { hit: number; miss: number; attached: number; uncacheable: number } {
+        return { hit: this.hits, miss: this.misses, attached: this.joined, uncacheable: this.unkeyed }
     }
 
     /** the one line a run prints about its own cache. Never silent: a run that
      *  replayed nothing says so, so a green is always attributable. */
     header(commit: CommitReport): Line[] {
         const c = this.counts
-        const asked = c.hit + c.miss + c.uncacheable
+        const asked = c.hit + c.miss + c.attached + c.uncacheable
         if (asked === 0) return []
         const out: Line[] = []
-        // `skip:` and not a bare note: the ci wire prefixes are a frozen
-        // contract every agent and every parser reads, and these lines are
-        // exactly what the run did NOT measure
-        const mode = this.reading ? '' : this.layer.failure != null ? ', reads off because the git scan failed' : ', reads off'
-        out.push({ kind: 'skip', text: `ledger — ${c.hit} replayed, ${c.miss} measured, ${c.uncacheable} uncacheable${mode}` })
-        if (commit.error != null) out.push({ kind: 'warn', text: `ledger stored nothing this run — the post-run re-hash failed: ${commit.error}` })
+        // a wire prefix and not a bare note: the ci wire prefixes are a frozen
+        // contract every agent and every parser reads. `ok:` because the line
+        // is an account of the run, never a verdict of its own
+        const mode = this.reading ? '' : this.layer.failure != null ? ', cache reads off because the git scan failed' : ', cache reads off'
+        out.push({ kind: 'ok', text: `cache — ${outcomeCounts({ cached: c.hit, ran: c.miss, attached: c.attached, neverCached: c.uncacheable })}${mode}` })
+        if (commit.error != null) out.push({ kind: 'warn', text: `cache stored nothing this run — the post-run re-hash failed: ${commit.error}` })
         else if (commit.discarded.length > 0)
-            out.push({ kind: 'skip', text: `ledger stored nothing for ${commit.discarded.length} unit(s) — ${commit.drifted.slice(0, 3).join(', ')}${commit.drifted.length > 3 ? ` +${commit.drifted.length - 3} more` : ''} moved while the gate ran` })
+            out.push({ kind: 'skip', text: `cache stored nothing for ${commit.discarded.length} check(s) — ${commit.drifted.slice(0, 3).join(', ')}${commit.drifted.length > 3 ? ` +${commit.drifted.length - 3} more` : ''} moved while the gate ran` })
         return out
     }
 }
 
-/** stamp a replayed unit's lines. The FIRST line carries the word, because
- *  that is the line an agent reads, and a replay that renders identically to a
- *  measurement is the one thing this design refuses to ship. */
-export function stampReplayed(lines: Line[], measuredMs: number): Line[] {
-    return lines.map((l, i) => (i === 0 ? { ...l, text: `${l.text} (replayed, ${(measuredMs / 1000).toFixed(1)}s saved)` } : l))
+/** stamp a cached check's lines. The FIRST line carries the word, because
+ *  that is the line an agent reads, and a cached answer that renders
+ *  identically to one that ran is the one thing this design refuses to ship. */
+export function stampCached(lines: Line[], measuredMs: number): Line[] {
+    return lines.map((l, i) => (i === 0 ? { ...l, text: `${l.text} ${cachedStamp(measuredMs)}` } : l))
 }

package/src/ledger/live-runs.ts

@@ -0,0 +1,111 @@
+// THE RUNS IN FLIGHT, as the run record holds them: one `live` row per runner
+// that is going right now, whoever started it (a terminal, the hub's buttons,
+// its daily pass). The runner rewrites its row as checks start and finish,
+// marks it ended when it returns, and the flush that writes the run's rows
+// deletes it in the same transaction, so a check that finished never drops
+// out of view between the two. While it runs it stamps the row every few
+// seconds, changed or not. A row whose stamp stopped, whose process died, or
+// that was marked ended and never flushed, expires on read.
+//
+// Pure: the reader hands the rows in, so the rules are pinned without a disk.
+import type { InvocationKind, InvokedBy, RunStatus } from './run-log.ts'
+
+/** a check the runner has started and not finished */
+export type LiveCheck = { id: string; started: number }
+
+/** a check this run has finished: what it measured, where it sits in time */
+export type LiveDone = { id: string; start: number; end: number; status: RunStatus; advisory: boolean; replayed: boolean }
+
+/** a check the runner has not started: `deps` lists the ones it still waits
+ *  on, and an empty list means it only waits for a free slot */
+export type LiveWait = { id: string; deps: string[] }
+
+/** what the runner writes on every turn of its loop */
+export type LiveState = {
+    /** how many checks may run at once in this run: the cap the runner used */
+    cap: number
+    /** how many checks this run measures */
+    total: number
+    done: number
+    /** blocking failures so far */
+    reds: number
+    running: LiveCheck[]
+    waiting: LiveWait[]
+    finished: LiveDone[]
+    /** when the runner returned. null while it runs */
+    ended: number | null
+}
+
+export type LiveRow = LiveState & { runId: string; kind: InvocationKind; label: string; by: InvokedBy; pid: number; started: number; updated: number }
+
+/** how long a row marked ended is still read when nothing flushed it: the
+ *  flush normally deletes it within a second, and a caller that never
+ *  flushes must not leave a run on screen forever */
+export const LIVE_LINGER_MS = 15_000
+
+/** how often a runner in flight stamps its row, changed or not: a check can
+ *  run for minutes without the state moving, and the stamp is its pulse */
+export const LIVE_BEAT_MS = 3_000
+
+/** a row whose stamp is older than this has no writer left, whatever its
+ *  pid says: a process that restarted its module in place (`bun --watch`)
+ *  keeps the pid and loses the run. Well above the beat, so a busy db that
+ *  drops a few beats is not mistaken for a dead run */
+export const LIVE_STALE_MS = 20_000
+
+/** a process that is still there. EPERM means it exists and belongs to
+ *  someone else, which is alive too */
+export const pidAlive = (pid: number): boolean => {
+    if (!Number.isInteger(pid) || pid <= 0) return false
+    try {
+        process.kill(pid, 0)
+        return true
+    } catch (e) {
+        return (e as { code?: string }).code === 'EPERM'
+    }
+}
+
+/** a row nobody writes anymore: its process is gone, or its stamp stopped
+ *  moving (a writer that lost its run keeps its pid) */
+export const liveRowDead = (r: Pick<LiveRow, 'pid' | 'updated'>, now: number, alive: (pid: number) => boolean = pidAlive): boolean =>
+    now - r.updated >= LIVE_STALE_MS || !alive(r.pid)
+
+/** the rows still worth reading, newest first: a row nobody writes and an
+ *  ended row nothing flushed are gone */
+export function liveRowsOf(rows: LiveRow[], now: number, alive: (pid: number) => boolean = pidAlive): LiveRow[] {
+    return rows
+        .filter((r) => !liveRowDead(r, now, alive) && (r.ended == null || now - r.ended < LIVE_LINGER_MS))
+        .sort((a, b) => b.started - a.started || a.runId.localeCompare(b.runId))
+}
+
+/** the runs still going: rows worth reading whose runner has not returned */
+export function liveRunsOf(rows: LiveRow[], now: number, alive: (pid: number) => boolean = pidAlive): LiveRow[] {
+    return liveRowsOf(rows, now, alive).filter((r) => r.ended == null)
+}
+
+/** the snapshot the runner writes, from its own scheduler state. Waiting
+ *  checks keep only the deps that are selected and not finished, because a
+ *  dep that is filtered out or already done is not something to wait on. A
+ *  finished check that never started (a dead dep, a bail) ran nothing and is
+ *  not a bar */
+export function liveStateOf(o: {
+    cap: number
+    total: number
+    finished: Map<string, { status: RunStatus; advisory: boolean; replayed: boolean; startedAt: number; ms: number }>
+    running: Iterable<string>
+    startedAt: (id: string) => number
+    queued: Iterable<string>
+    depsOf: (id: string) => string[]
+    selected: Set<string>
+    ended?: number | null
+}): LiveState {
+    const running = [...o.running].map((id) => ({ id, started: o.startedAt(id) })).sort((a, b) => a.started - b.started || a.id.localeCompare(b.id))
+    const waiting = [...o.queued].map((id) => ({ id, deps: o.depsOf(id).filter((d) => o.selected.has(d) && !o.finished.has(d)) }))
+    let reds = 0
+    const finished: LiveDone[] = []
+    for (const [id, f] of o.finished) {
+        if (f.status === 'fail' && !f.advisory) reds++
+        if (f.startedAt > 0) finished.push({ id, start: f.startedAt, end: f.startedAt + f.ms, status: f.status, advisory: f.advisory, replayed: f.replayed })
+    }
+    return { cap: o.cap, total: o.total, done: o.finished.size, reds, running, waiting, finished, ended: o.ended ?? null }
+}