rvlib-shipkit 0.33.0 → 0.35.0

package/src/core/locked-write.ts

@@ -3,7 +3,7 @@
 // whole read-modify-write, the write lands via tmp + rename so a killed
 // process can never leave a torn file, and the loser of a race SKIPS —
 // never corrupts, never blocks.
-import { renameSync, rmSync, statSync, writeFileSync } from 'fs'
+import { linkSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'fs'
 import { basename, dirname, join } from 'path'
 
 // a writer that died without unlocking must not wedge the file forever
@@ -37,3 +37,172 @@ export function atomicWrite(path: string, content: string): void {
     writeFileSync(tmpPath, content)
     renameSync(tmpPath, path)
 }
+
+// ---------------------------------------------------------------------------
+// the MUTATE LEASE — the second concurrency shape, and the only other one.
+//
+// withFileLock guards ONE file and the loser SKIPS: right for a render that
+// re-renders next run. The lease guards a PHASE that rewrites the worktree
+// (the fix pass, SK005's `bun update --latest`, hooks arming, the asks
+// archive), where skipping means the repair never happens and overlapping
+// means two processes rewrite the same file at once. So the loser WAITS.
+//
+// TWO PRIMITIVES, both atomic, and both were measured before they were
+// trusted. `writeFileSync(..., 'wx')` creates the NAME first and writes the
+// body second, so a racer that reads in between sees an empty file, calls the
+// lock corrupt, and steals a lease whose holder is very much alive: 5 of 15
+// synchronized starts overlapped. So the body is written to a private name and
+// `linkSync`d into place, one step that fails when the name exists and never
+// exposes a half lock. And a steal of `read, rmSync, grab` is three steps, so
+// every racer wins it: 31 of 40 synchronized starts overlapped after a crash.
+// So a steal is a single `renameSync` of the lock out of the way, which
+// exactly one racer can perform; everyone else gets ENOENT and goes back to
+// grabbing.
+//
+// Bounded in every direction, because a gate that hangs is worse than a gate
+// that overlaps. A holder is stale when its pid is not running OR when the
+// lock has not been touched for LOCK_STALE_MS, so a pid reused by a long
+// lived process cannot wedge a repo forever. A holder that is genuinely still
+// working HEARTBEATS the lock while it holds it, so the age rule only ever
+// fires on a run that is gone or wedged. A waiter gives up after maxWaitMs and
+// says so by name, path and escape hatch. Every line it prints carries a
+// FROZEN wire prefix (wire.ts), so a lease that waits or steals inside
+// `shipkit ci` cannot break that contract.
+
+const LEASE_POLL_MS = 100
+const LEASE_ANNOUNCE_MS = 1_000
+const LEASE_REANNOUNCE_MS = 15_000
+const LEASE_HEARTBEAT_MS = 20_000
+/** shorter than the shortest caller timeout (a discovered check is killed at
+ *  120s), so a waiter always gets to PRINT its refusal rather than being
+ *  SIGTERMed mid wait with no cause on screen */
+const LEASE_MAX_WAIT_MS = 60_000
+
+type Holder = { pid: number; at: number; label: string }
+
+let leaseSeq = 0
+
+const readHolder = (lockPath: string): Holder | null => {
+    try {
+        const h = JSON.parse(readFileSync(lockPath, 'utf8')) as Partial<Holder>
+        return typeof h.pid === 'number' ? { pid: h.pid, at: typeof h.at === 'number' ? h.at : 0, label: String(h.label ?? '?') } : null
+    } catch { return null }
+}
+
+/** is that pid still running? signal 0 asks without delivering anything.
+ *  EPERM means alive and owned by another user, which still counts as alive. */
+const alive = (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' }
+}
+
+/** publish a COMPLETE lock under a name that did not exist a moment ago */
+const grabLease = (lockPath: string, label: string): boolean => {
+    const tmp = `${lockPath}.tmp-${process.pid}-${leaseSeq++}`
+    try {
+        writeFileSync(tmp, JSON.stringify({ pid: process.pid, at: Date.now(), label } satisfies Holder))
+        linkSync(tmp, lockPath)
+        return true
+    } catch { return false }
+    finally { rmSync(tmp, { force: true }) }
+}
+
+const sameHolder = (a: Holder | null, b: Holder | null): boolean =>
+    a == null ? b == null : b != null && a.pid === b.pid && a.at === b.at
+
+/** move the lock aside, and ONLY the lock we judged dead. Exactly one racer
+ *  can win the rename; the rest see ENOENT and go back to grabbing.
+ *
+ *  The identity check on both sides is the whole point, and it is a measured
+ *  bug, not a precaution. Reading the holder and stat'ing the file are two
+ *  syscalls, so a racer that read the DEAD holder, then lost the steal, then
+ *  stat'ed the WINNER's fresh lock, judged a live holder dead and threw its
+ *  lease away: 1 in 40 four-process starts against a stale lock. So the holder
+ *  is re-read immediately before the rename, and the moved file is checked
+ *  after it. A lock that turns out to belong to somebody else goes straight
+ *  back and this round is lost. */
+const stealLease = (lockPath: string, expect: Holder | null): boolean => {
+    if (!sameHolder(readHolder(lockPath), expect)) return false
+    const grave = `${lockPath}.dead-${process.pid}-${leaseSeq++}`
+    try { renameSync(lockPath, grave) } catch { return false }
+    if (sameHolder(readHolder(grave), expect)) { rmSync(grave, { force: true }); return true }
+    // it was not the lock we judged: put it back before the name can be taken
+    try { linkSync(grave, lockPath) } catch { /* taken in the gap: the new holder owns it now */ }
+    rmSync(grave, { force: true })
+    return false
+}
+
+/** drop the lock, but only while it is still OURS: a lease that was stolen
+ *  belongs to whoever stole it, and deleting it would hand a third process a
+ *  lease two others believe they hold */
+const releaseLease = (lockPath: string): void => {
+    const h = readHolder(lockPath)
+    if (h == null || h.pid === process.pid) rmSync(lockPath, { force: true })
+}
+
+export type LeaseOutcome<T> = { ok: true; value: T; waitedMs: number } | { ok: false; warn: string }
+
+/** hold `<path>.lock` for the duration of fn. Blocking, stolen from a holder
+ *  that is gone or wedged, refused (never hung) past maxWaitMs. */
+export async function withMutateLease<T>(
+    path: string,
+    o: { label: string; print?: (line: string) => void; maxWaitMs?: number; escape?: string },
+    fn: () => T | Promise<T>,
+): Promise<LeaseOutcome<T>> {
+    const lockPath = `${path}.lock`
+    const print = o.print ?? ((l: string) => console.log(l))
+    const maxWait = o.maxWaitMs ?? LEASE_MAX_WAIT_MS
+    const start = Date.now()
+    // the first announcement is due at LEASE_ANNOUNCE_MS, every later one a
+    // re-announce interval after it
+    let announced = -LEASE_REANNOUNCE_MS
+    mkdirSync(dirname(lockPath), { recursive: true })
+
+    for (;;) {
+        if (grabLease(lockPath, o.label)) break
+        const holder = readHolder(lockPath)
+        let ageMs = 0
+        // the lock vanished between grab and stat: the holder just finished,
+        // so go straight back and take it
+        try { ageMs = Date.now() - statSync(lockPath).mtimeMs } catch { continue }
+        // gone (no such process), or wedged (nothing has touched it for the
+        // stale window, and a live holder heartbeats), or a body no reader can
+        // make sense of that is old enough not to be a write in flight
+        const dead = holder == null ? ageMs > 2_000 : !alive(holder.pid) || ageMs > LOCK_STALE_MS
+        if (dead) {
+            if (stealLease(lockPath, holder)) print(`ok: stole the ${o.label} lease from a holder that is gone (pid ${holder?.pid ?? '?'}, untouched ${Math.round(ageMs / 1000)}s) — a run died mid phase`)
+            continue
+        }
+        const waited = Date.now() - start
+        if (waited > maxWait)
+            return {
+                ok: false,
+                warn: `${o.label} lease held by ${holder == null ? 'an unreadable lock' : `pid ${holder.pid} (${holder.label})`} for ${Math.round(ageMs / 1000)}s — gave up after ${Math.round(waited / 1000)}s rather than run two of these at once. Lock: ${lockPath}${o.escape == null ? '' : `; skip this phase with ${o.escape}`}`,
+            }
+        if (waited >= LEASE_ANNOUNCE_MS && waited - announced >= LEASE_REANNOUNCE_MS) {
+            announced = waited
+            print(`ok: waiting ${Math.round(waited / 1000)}s for the ${o.label} lease — ${holder == null ? 'an unreadable lock holds it' : `pid ${holder.pid} holds it (${holder.label})`}, lock ${lockPath}`)
+        }
+        await Bun.sleep(LEASE_POLL_MS)
+    }
+
+    // a phase that legitimately outlives the stale window must keep proving it
+    // is working, or the age rule steals from it. unref'd, so a held lease
+    // never keeps a process alive on its own
+    const beat = setInterval(() => { try { utimesSync(lockPath, new Date(), new Date()) } catch { /* stolen or gone: the finally sorts it out */ } }, LEASE_HEARTBEAT_MS)
+    beat.unref()
+    try {
+        return { ok: true, value: await fn(), waitedMs: Date.now() - start }
+    } finally {
+        clearInterval(beat)
+        releaseLease(lockPath)
+    }
+}
+
+/** where a repo's mutate leases live. Under the gitignored tmp/ dir so a lease
+ *  file can never enter a commit, and per WORKTREE, because the phases it
+ *  guards rewrite worktree-local files. The NAME is the concern: two phases
+ *  that cannot corrupt each other take different leases, so `asks` never
+ *  blocks a `fix`. `git config` is the one shared-across-worktrees write and
+ *  carries its own retry (hooks/run-hooks.ts). */
+export const mutateLease = (root: string, name: string): string => join(root, 'tmp', `shipkit-${name}`)

package/src/core/motherhome.ts

@@ -24,6 +24,58 @@ type Row = { name: string; root: string; version: string; mode: string; seen: st
 
 const rowLine = (r: Row): string => `- ${r.name} — \`${r.root}\` — shipkit ${r.version} (${r.mode}) — last seen ${r.seen}`
 
+const git = (cwd: string, args: string[]): { ok: boolean; out: string } => {
+    const r = Bun.spawnSync(['git', ...args], { cwd })
+    return { ok: r.exitCode === 0, out: `${r.stdout.toString()}${r.stderr.toString()}`.trim() }
+}
+
+/**
+ * Commit the row we just wrote, and ONLY that file.
+ *
+ * This page is machine written and rewrites whenever a repo's shipkit version
+ * or consumption mode changes, so left alone it dirties the docs repo from a
+ * gate run nobody associates with it, and the dirt then rides into an unrelated
+ * commit or blocks a release. The row is not worth a human's attention in
+ * either direction, so the machine that writes it also lands it.
+ *
+ * Scoped hard, because several agents share this checkout:
+ * - `git commit -- <path>` takes the WORKING TREE version of that one path and
+ *   never reads the index, so a neighbour's staged work cannot ride along.
+ * - it refuses mid merge, mid rebase, on a detached HEAD, and before the first
+ *   commit, where an automatic commit is never what anyone wants.
+ * - it never pushes. Visibility is the human's call.
+ * - the hooks run, as they do for any commit. They are text checks of about a
+ *   second, and this fires only when the row's DATA changed, not every gate.
+ *
+ * Never throws and never fails the calling command: a registry row is not worth
+ * a red gate. `SHIPKIT_NO_AUTOCOMMIT=1` turns it off.
+ */
+function autoCommitRow(page: string, name: string): string {
+    if (process.env['SHIPKIT_NO_AUTOCOMMIT'] === '1') return ''
+    try {
+        const dir = resolve(page, '..')
+        const top = git(dir, ['rev-parse', '--show-toplevel'])
+        if (!top.ok) return '' // the docs tree is not a git repo, nothing to land
+        const root = top.out
+        // a detached HEAD or a repo with no commit yet has nowhere sane to land
+        if (!git(root, ['symbolic-ref', '--quiet', 'HEAD']).ok) return ''
+        if (!git(root, ['rev-parse', '--verify', 'HEAD']).ok) return ''
+        for (const f of ['MERGE_HEAD', 'REBASE_HEAD', 'CHERRY_PICK_HEAD'])
+            if (existsSync(join(root, '.git', f))) return ''
+        const rel = page.startsWith(`${root}/`) ? page.slice(root.length + 1) : page
+        // one retry: a neighbour committing right now holds index.lock
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const r = git(root, ['commit', '-m', `chore(machine): refresh local-projects row (${name})`, '--', rel])
+            if (r.ok) return ' + committed'
+            if (!r.out.includes('index.lock')) return ''
+            Bun.sleepSync(300)
+        }
+        return ''
+    } catch {
+        return ''
+    }
+}
+
 const parseRow = (line: string): Row | null => {
     const m = line.match(/^- (.+?) — `(.+?)` — shipkit (\S+) \((.+?)\) — last seen (\d{4}-\d{2}-\d{2})$/)
     return m == null ? null : { name: m[1]!, root: m[2]!, version: m[3]!, mode: m[4]!, seen: m[5]! }
@@ -90,7 +142,8 @@ export function reportToMotherhome(root: string, config: RepoConfig, today: stri
             // prune rows for repos that no longer exist at their recorded path
             const next = [...rows.filter((row) => row.root !== me.root && existsSync(row.root)), me].sort((a, z) => a.name.localeCompare(z.name))
             atomicWrite(page, [...lines.slice(0, b + 1), ...next.map(rowLine), ...lines.slice(e)].join('\n'))
-            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})` }
+            const committed = autoCommitRow(page, me.name)
+            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})${committed}` }
         })
         // lock lost to a racing reporter — self-heals on the next run
         return r.ok ? r.value : { wrote: false }

package/src/core/one-way-in-policy.ts

@@ -29,8 +29,8 @@ export type RawRunner = {
     use: string
     /** the narrower way in, when there is one: iterating on a single repro
      *  test while you fix a bug is not a verification and stays normal. A
-     *  FILTER, not a path: `bun run` quotes what it forwards, and bun reads a
-     *  quoted path as a name filter that then matches nothing */
+     *  FILE filter (measured): bun's positional argument matches the test FILE
+     *  path, and a test NAME needs `-- -t "<name>"` forwarded through bun run */
     iterate?: string
 }
 
@@ -38,12 +38,12 @@ export type RawRunner = {
 // carrying. Kept tight on purpose: a deny an agent hits for no good reason
 // teaches it to route around the whole file.
 export const RAW_RUNNERS: readonly RawRunner[] = [
-    { head: 'bun test', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'bunx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'npx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'npx jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
+    { head: 'bun test', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'bunx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'npx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'npx jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
     { head: 'bunx tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
     { head: 'npx tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
     { head: 'tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },

package/src/core/run-check.ts

@@ -1,11 +1,20 @@
 // periodic health — contracts + every *.check.ts in the repo. Discovery IS
 // the registration (core/discover-checks.ts); each check runs as a
-// subprocess: wire lines parsed back, exit code is truth. A check that runs
-// its own CheckSuite keeps its own TTL cache and is never double-cached
-// here; plain checks get a short orchestrator TTL. `--fresh` busts both
-// layers (SHIPKIT_FRESH=1 + RV_CHECK_FRESH=1 travel to children).
+// subprocess: wire lines parsed back, exit code is truth.
+//
+// NOTHING here decides what may be remembered any more. A rule or a check is
+// replayed when it DECLARED how ("inputs" makes it content-keyed and the
+// ledger owns it, "ttl" makes it a world probe and CheckSuite owns it), and
+// otherwise it is measured every run. The blanket 30-minute orchestrator TTL
+// that used to cover every plain check died with that: it cached by default,
+// on top of whatever the check cached for itself, so one question had two
+// staleness windows and neither was declared by anyone. `--fresh`
+// (SHIPKIT_FRESH=1, which travels to children) busts the one that is left.
 import { join, relative } from 'path'
 import { CheckSuite, type CheckOutcome } from './check-suite.ts'
+import { gateUnits } from '../ledger/gate-units.ts'
+import { Ledger, stampReplayed } from '../ledger/ledger.ts'
+import { storeRoot } from '../ledger/store.ts'
 import { CheckCtx } from './check-ctx.ts'
 import { discoverChecks } from './discover-checks.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
@@ -18,9 +27,6 @@ import { writeStatus } from './write-status.ts'
 import { SHARE_ENV } from '../release/releases-share.ts'
 import { rmSync } from 'fs'
 
-// orchestrator cache for checks WITHOUT their own suite — short on purpose:
-// this layer only absorbs back-to-back runs, real TTLs live in the checks
-const DISCOVERED_TTL = '30m'
 const CHECK_TIMEOUT_MS = 120_000
 
 export type CheckOpts = {
@@ -50,6 +56,15 @@ export type CheckOpts = {
      *  probed every third-party service the repo knows about. One flag, one
      *  meaning, across all three surfaces. */
     only?: string[]
+    /** the run's ledger, when the caller already opened one (runCi does). A
+     *  standalone `shipkit check` opens its own. */
+    ledger?: Ledger | null
+    /** refresh the motherhome registry row. runCi passes false and does it
+     *  ITSELF, after the ledger has committed: that row is a TRACKED file under
+     *  `wiki/`, so writing it before the post-run re-hash makes the gate look
+     *  like an agent editing the tree and throws away every result the run just
+     *  measured. Two reports per gate run was duplication anyway. */
+    reportHome?: boolean
 }
 
 /** does this rule or check answer to one of the `--only` ids? Matched against
@@ -83,7 +98,61 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     const prevFrozen = process.env.SHIPKIT_FROZEN
     if (o.fresh === true) process.env.SHIPKIT_FRESH = '1'
     if (o.frozen === true) process.env.SHIPKIT_FROZEN = '1'
-    const suite = new CheckSuite({ name: c.name, cacheDir: join(root, 'tmp/.shipkit-cache'), onResult: o.onResult })
+    // the caller's ledger, or this run's own. `shipkit check` is a full run
+    // of every rule and check, so it deserves the same replay the gate gets.
+    let ledger: Ledger | null = o.ledger ?? null
+    if (ledger === null && o.ledger === undefined) {
+        try {
+            ledger = Ledger.open(root, gateUnits(root, c), { cliEntry: new URL('../cli.ts', import.meta.url).pathname, fresh: o.fresh })
+        } catch { ledger = null }
+    }
+    const replayed = new Set<string>()
+    const unitIdByName = new Map<string, string>()
+    /** what a TTL'd answer is remembered under, beside its rotation key. A TTL
+     *  says how long the WORLD keeps; it cannot say that the probe was
+     *  rewritten, or that a different shipkit measured it. Without these two a
+     *  fixed check replayed its old verdict for the rest of its TTL. */
+    const worldKey = (unitId: string, rotation?: string): string => {
+        let code = ''
+        try { code = ledger?.layer.keyFor(unitId).codeKey ?? '' } catch { code = '' }
+        return `tc=${ledger?.layer.toolchainId ?? ''}\0code=${code}\0${rotation ?? ''}`
+    }
+    const suite = new CheckSuite({
+        name: c.name,
+        storeDir: storeRoot(root),
+        onResult: (name, r) => {
+            o.onResult?.(name, r)
+            // a replay measured nothing, and a red is never stored. A check
+            // that cannot block had its FAIL rewritten to a warn before this
+            // fires, so the demotion list is what says it failed: a content
+            // key has no TTL, so storing that red would pin it until an
+            // unrelated edit moved the tree, and "the box is off" is fixed by
+            // turning the box on, which changes no file.
+            if (ledger == null || r.cached || replayed.has(name) || r.status === 'skip' || r.status === 'fail') return
+            if (advisoryFailures.includes(name)) return
+            const id = unitIdByName.get(name)
+            if (id == null) return
+            ledger.record(id, { status: r.status, lines: r.lines, measuredMs: r.ms })
+        },
+    })
+    /** a stored answer, re-emitted as a runner that does no work. Keeping it in
+     *  the suite rather than splicing lines afterwards is what preserves
+     *  declaration order, which the wire contract is frozen on. */
+    const addReplay = (unitId: string, name: string, blocking: boolean): boolean => {
+        const hit = ledger?.replay(unitId)
+        if (hit == null) return false
+        replayed.add(name)
+        unitIdByName.set(name, unitId)
+        suite.addCheck({
+            blocking,
+            name,
+            logic: (t) => {
+                for (const l of stampReplayed(hit.lines, hit.measuredMs)) t.lines.push(l)
+                if (t.lines.some((l) => l.kind === 'warn' || l.kind === 'fix-warn')) t.warned = true
+            },
+        })
+        return true
+    }
     // built-in SK rules (rules/rule-registry.ts) THEN the repo's own
     // (repo.config rules: []), id-tagged, crash-safe, fix-pointer floor
     // (rules/rule.ts runRuleLint owns the semantics). `shipkit ci` runs this
@@ -104,11 +173,13 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     for (const rule of [...RULES, ...(c.rules ?? [])]) {
         if (!matchesOnly(o.only, rule.id, rule.title)) continue
         if (o.onlyBlocking === true && !rule.blocking) continue
+        unitIdByName.set(rule.title, rule.id)
+        if (addReplay(rule.id, rule.title, rule.blocking)) continue
         suite.addCheck({
             blocking: rule.blocking,
             name: rule.title,
             remainValidFor: rule.ttl,
-            cacheExtra: rule.cacheKey != null ? () => rule.cacheKey!({ root, config: c }) : undefined,
+            cacheExtra: () => worldKey(rule.id, rule.cacheKey?.({ root, config: c })),
             logic: async (t) => { await runRuleLint(rule, t, { root, config: c }); demote(t, rule.blocking, rule.title) },
         })
     }
@@ -123,7 +194,7 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     const childEnv: Record<string, string | undefined> = {
         ...process.env,
         [SHARE_ENV]: sharePath,
-        ...(o.fresh === true ? { SHIPKIT_FRESH: '1', RV_CHECK_FRESH: '1' } : {}),
+        ...(o.fresh === true ? { SHIPKIT_FRESH: '1' } : {}),
     }
     for (const d of discoverChecks(root)) {
         const rel = relative(root, d.path)
@@ -133,12 +204,17 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
         const blocking = d.blocking ?? c.checkDefaults?.blocking
         if (blocking == null) undeclared.push(rel)
         if (o.onlyBlocking === true && blocking !== true) continue
+        unitIdByName.set(d.name, d.name)
+        if (addReplay(d.name, d.name, blocking ?? true)) continue
         suite.addCheck({
             // a check about the WORLD may remember a measured negative; one
             // about this repo never does (check-suite.ts, the rule)
             blocking: blocking ?? true,
             name: d.name,
-            remainValidFor: d.selfCached ? undefined : DISCOVERED_TTL,
+            // a WORLD check says how long its answer keeps; everything else is
+            // measured every run rather than blanket-cached by this layer
+            remainValidFor: d.ttl ?? undefined,
+            cacheExtra: () => worldKey(d.name),
             logic: async (t) => {
                 const r = await spawnWithTimeout(['bun', d.path], { cwd: root, timeoutMs: CHECK_TIMEOUT_MS, env: childEnv })
                 for (const l of parseWireOutput(r.out)) t.lines.push(l)
@@ -159,7 +235,11 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
     if (prevFrozen == null) delete process.env.SHIPKIT_FROZEN; else process.env.SHIPKIT_FROZEN = prevFrozen
     // frozen = a release-shaped run: reporting would re-dirty the tree the
     // caller is about to demand clean (field wart 2026-08-05, second head)
-    if (o.frozen !== true) reportToMotherhome(root, c)
+    if (o.frozen !== true && o.reportHome !== false) reportToMotherhome(root, c)
+    // the caller that OPENED the ledger owns committing it: runCi commits once
+    // after its tasks and its checks, so a task and a check in one run share
+    // one post-run re-hash
+    if (o.ledger === undefined && ledger != null) r.lines.push(...ledger.header(ledger.commit()))
     return { lines: r.lines, blocked: r.exitCode !== 0, advisoryFailures, undeclared }
 }