rvlib-shipkit 0.35.7 → 0.36.0

package/src/core/run-ci.ts

@@ -8,13 +8,14 @@
 import { join } from 'path'
 import { allTasks, loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
-import { collectChecks } from './run-check.ts'
+import { checkSideIds, collectChecks } from './run-check.ts'
 import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
 import { runTasks, selectTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
 import { withContractsScope } from '../contracts/contracts-once.ts'
-import { envTier, FULL_TESTS_ENV, gateUnits, type TestTier } from '../ledger/gate-units.ts'
+import { envTier, FULL_TESTS_ENV, gateInventory, gateUnits, tieredTasks, type TestTier } from '../ledger/gate-units.ts'
+import { UNIT_TABLE_FILE, writeUnitTable } from '../ledger/unit-table.ts'
 import { Ledger, stampReplayed, type UnitOutcome } from '../ledger/ledger.ts'
 
 export type CiOpts = {
@@ -178,7 +179,11 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     // the run entirely, which is also what makes its dependents correct: the
     // runner treats a filtered dep as satisfied, and only a GREEN is ever
     // stored, so a dependent can never start on the back of a red nobody saw.
-    const selectable = new Set(selectTasks({ tasks, logDir: '', skipGroups: o.skipGroups ?? [], withIds: o.withIds ?? [], onlyIds: o.onlyIds ?? [] }).selected.map((t) => t.id))
+    // --only addresses tasks, rules and checks alike, so the task runner is
+    // told which ids belong to the other two surfaces rather than answering
+    // `unknown task id` for a check it was never asked to run
+    const otherIds = checkSideIds(root, c)
+    const selectable = new Set(selectTasks({ tasks, logDir: '', skipGroups: o.skipGroups ?? [], withIds: o.withIds ?? [], onlyIds: o.onlyIds ?? [], otherIds }).selected.map((t) => t.id))
     const replayedTasks = new Map<string, UnitOutcome>()
     const toRun = tasks
         .filter((t) => {
@@ -219,6 +224,7 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
         skipGroups: o.skipGroups ?? [],
         withIds,
         onlyIds,
+        otherIds,
         print: sink,
         onTaskFinish: o.onTaskFinish,
     })
@@ -254,7 +260,11 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     // checks that do want it still pay for exactly one survey between them.
     const checks = o.skipChecks === true
         ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
-        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds, fresh: o.fresh, ledger, reportHome: false, gateOnly: true })
+        // `gate = false` opts a check out of the EVERYDAY gate. failOnAdvisory
+        // is release.requireHealthy, a repo saying it wants a missing cred to
+        // stop its publish, so it re-arms them: the opt-out must not silently
+        // drop the one request that asks for exactly these probes.
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds, fresh: o.fresh, ledger, reportHome: false, gateOnly: o.failOnAdvisory !== true })
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     for (const l of checks.lines) { collected.push(formatLine(l, false)); print(formatLine(l, color)) }
     for (const u of checks.undeclared) {
@@ -285,8 +295,17 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     if (o.status !== false) {
         // scope is named in the file: ci proves the gate, not repo health, and
         // a bare GREEN here would claim clear-to-ship on a repo with red checks
-        const st = writeStatus(root, { name: c.name, ...ciScope(o), lines: collected, exitCode: code })
+        const st = writeStatus(root, {
+            name: c.name,
+            ...ciScope(o),
+            lines: collected,
+            exitCode: code,
+            sidecar: { file: UNIT_TABLE_FILE, says: 'Every unit this repo can run, and whether it blocks you' },
+        })
         if (!st.written) print(`WARN ${st.warn}`)
+        const units = writeUnitTable(root, { name: c.name, rows: gateInventory(root, c, tieredTasks(c, root, tier)) })
+        if (!units.written) print(`WARN ${units.warn}`)
+
     }
     if (o.json === true)
         print(JSON.stringify({ ok: summary.ok, interrupted: summary.interrupted, disabled, tasks: summary.results.map((r) => ({ ...r, lines: undefined })) }))

package/src/core/task-runner.ts

@@ -78,6 +78,10 @@ export type RunOpts = {
     skipGroups?: string[]
     onlyIds?: string[]
     withIds?: string[]
+    /** ids `--only` may name that are NOT tasks: discovered checks and rules.
+     *  The flag addresses all three surfaces, so a check name must not come
+     *  back as `unknown task id` from the one surface that does not own it. */
+    otherIds?: string[]
     /** print sink — tests capture, production defaults to console.log */
     print?: (line: string) => void
     color?: boolean
@@ -115,7 +119,9 @@ export function selectTasks(o: RunOpts): { selected: TaskDef[]; errors: string[]
         if ((t.cmd == null) === (t.logic == null)) errors.push(`task ${t.id}: exactly one of cmd/logic required`)
         for (const d of t.deps ?? []) if (!ids.has(d)) errors.push(`task ${t.id}: unknown dep '${d}'`)
     }
-    for (const id of [...(o.onlyIds ?? []), ...(o.withIds ?? [])]) if (!ids.has(id)) errors.push(`unknown task id '${id}'`)
+    const elsewhere = new Set((o.otherIds ?? []).map((i) => i.toLowerCase()))
+    for (const id of [...(o.onlyIds ?? []), ...(o.withIds ?? [])])
+        if (!ids.has(id) && !elsewhere.has(id.toLowerCase())) errors.push(`unknown task id '${id}'`)
     // cycle check — a dep cycle must die loud at select time, not hang the loop
     const state = new Map<string, 0 | 1>()
     const byId = new Map(o.tasks.map((t) => [t.id, t]))

package/src/core/write-status.ts

@@ -18,6 +18,10 @@ export type StatusInput = {
     /** the run's printed lines (ANSI stripped here) */
     lines: string[]
     exitCode: number
+    /** a companion file this run also refreshed, named so a reader finds it.
+     *  Optional because a caller that does not write one must not advertise
+     *  a file that is not there. */
+    sidecar?: { file: string; says: string }
 }
 
 export type StatusOutcome = { written: boolean; warn?: string }
@@ -61,7 +65,7 @@ export function writeStatus(root: string, s: StatusInput): StatusOutcome {
 # ${s.name} status, ${stamp}
 
 **${verdict}**
-
+${s.sidecar == null ? '' : `\n${s.sidecar.says}: [${s.sidecar.file}](${s.sidecar.file})\n`}
 \`\`\`
 ${clean.join('\n').trim()}
 \`\`\`

package/src/fleet/scan-fleet.ts

@@ -0,0 +1,142 @@
+// The fleet: every repo on this disk that depends on the toolkit, and how far
+// behind each one is.
+//
+// Why a scan and not a registry: `local-projects.md` only holds repos whose
+// `docsBase` points at a wiki, which is 4 of the 10 that actually install the
+// libs. A repo that never reported is exactly the repo most likely to be
+// stale, so a registry is the wrong source for this question.
+//
+// This module DISCOVERS and REPORTS. It never updates: rule SK005 owns the
+// update, with the lease, the dirty-tree guard and the frozen guard that took
+// three bugs to get right. `--update` runs each repo's own `shipkit check`,
+// so the fix travels through that one code path.
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+
+export type Pkg = { name?: string; version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+
+export type FleetDep = {
+    name: string
+    /** the range in package.json, or `link:…` for a source-linked dep */
+    pin: string
+    /** what node_modules actually carries, null when nothing is installed */
+    installed: string | null
+    /** npm latest, null when the registry was not consulted or not reachable */
+    latest: string | null
+}
+
+/** a jump that changes the MAJOR, which is a porting job rather than a bump.
+ *
+ *  Deliberately NOT the semver rule. On a `0.x` package npm treats every
+ *  minor as breaking, and by that rule every repo here is breaking, including
+ *  the `0.24 → 0.35` shipkit jumps that rule SK005 already performs by itself
+ *  every day. A flag that fires on everything is a flag nobody reads. What
+ *  survives is the case a human has to own: `rvlib-pb-mobx 0.2.0 → 2.0.0`. */
+export function isBreaking(installed: string, latest: string): boolean {
+    const major = (v: string) => Number(v.split('-')[0]!.split('.')[0]) || 0
+    return major(installed) !== major(latest)
+}
+
+export type FleetRepo = {
+    name: string
+    dir: string
+    deps: FleetDep[]
+    /** a repo pointing at a checkout rather than a published version. Never
+     *  updated: the source IS the version, and that is a deliberate choice. */
+    linked: boolean
+    /** whether this repo can run the update itself (it has a shipkit binary) */
+    hasShipkit: boolean
+    behind: FleetDep[]
+    /** the subset of `behind` whose jump crosses a breaking boundary */
+    breaking: FleetDep[]
+}
+
+const readPkg = (dir: string): Pkg | null => {
+    const p = join(dir, 'package.json')
+    if (!existsSync(p)) return null
+    try {
+        return JSON.parse(readFileSync(p, 'utf8')) as Pkg
+    } catch {
+        return null
+    }
+}
+
+const installedVersion = (dir: string, name: string): string | null => readPkg(join(dir, 'node_modules', name))?.version ?? null
+
+/** semver-ish compare, enough to answer "is this one behind that one". A
+ *  prerelease tag sorts before its release, which is the safe direction: it
+ *  reports behind rather than pretending parity. */
+export function isBehind(installed: string, latest: string): boolean {
+    const part = (v: string) => v.split('-')[0]!.split('.').map((n) => Number(n) || 0)
+    const [a, b] = [part(installed), part(latest)]
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) < (b[i] ?? 0)) return true
+        if ((a[i] ?? 0) > (b[i] ?? 0)) return false
+    }
+    return installed.includes('-') && !latest.includes('-')
+}
+
+export function scanFleet(root: string, o: { prefix?: string } = {}): FleetRepo[] {
+    const prefix = o.prefix ?? 'rvlib-'
+    const out: FleetRepo[] = []
+    let entries: string[]
+    try {
+        entries = readdirSync(root)
+    } catch {
+        return out
+    }
+    for (const e of entries.sort()) {
+        if (e.startsWith('.')) continue
+        const dir = join(root, e)
+        try {
+            if (!statSync(dir).isDirectory()) continue
+        } catch {
+            continue
+        }
+        const pkg = readPkg(dir)
+        if (pkg == null) continue
+        const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
+        const names = Object.keys(all).filter((n) => n.startsWith(prefix))
+        if (names.length === 0) continue
+        const deps: FleetDep[] = names.sort().map((name) => ({ name, pin: all[name]!, installed: installedVersion(dir, name), latest: null }))
+        out.push({
+            name: e,
+            dir,
+            deps,
+            linked: deps.some((d) => d.pin.startsWith('link:') || d.pin.startsWith('file:')),
+            hasShipkit: existsSync(join(dir, 'node_modules', 'rvlib-shipkit', 'src', 'cli.ts')),
+            behind: [],
+            breaking: [],
+        })
+    }
+    return out
+}
+
+/** npm latest per PACKAGE, fetched once and shared across every repo that
+ *  depends on it. Ten repos on one lib is one request, not ten. */
+export async function resolveLatest(repos: FleetRepo[], fetchLatest: (name: string) => Promise<string | null>): Promise<Map<string, string | null>> {
+    const names = new Set<string>()
+    for (const r of repos) for (const d of r.deps) if (!d.pin.startsWith('link:') && !d.pin.startsWith('file:')) names.add(d.name)
+    const latest = new Map<string, string | null>()
+    await Promise.all(
+        [...names].map(async (n) => {
+            try {
+                latest.set(n, await fetchLatest(n))
+            } catch {
+                latest.set(n, null)
+            }
+        }),
+    )
+    for (const r of repos) {
+        for (const d of r.deps) d.latest = latest.get(d.name) ?? null
+        r.behind = r.deps.filter((d) => d.installed != null && d.latest != null && isBehind(d.installed, d.latest))
+        r.breaking = r.behind.filter((d) => isBreaking(d.installed!, d.latest!))
+    }
+    return latest
+}
+
+export async function npmLatest(name: string): Promise<string | null> {
+    const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(10_000) })
+    if (!res.ok) return null
+    return ((await res.json()) as Pkg).version ?? null
+}

package/src/git-bootstrap.ts

@@ -101,7 +101,7 @@ const samePath = (a: string, b: string): boolean => {
     }
 }
 
-type RepoView = { nameWithOwner?: string; isPrivate?: boolean; url?: string; sshUrl?: string }
+type RepoView = { nameWithOwner?: string; isPrivate?: boolean; sshUrl?: string }
 
 /** phase one: this dir IS a git work tree root. false means the caller must
  *  not publish anything (a subdirectory of another repo, or git refused), and
@@ -194,7 +194,7 @@ export async function publishRepo(root: string, opts: PublishOpts = {}): Promise
     const login = firstGhLine(user.out)
     if (!NAME_RE.test(login)) return void p(`WARN no remote wired: gh did not answer with a login (${login})`)
     const target = `${login}/${name}`
-    const viewArgs = ['repo', 'view', target, '--json', 'nameWithOwner,isPrivate,url,sshUrl']
+    const viewArgs = ['repo', 'view', target, '--json', 'nameWithOwner,isPrivate,sshUrl']
 
     let view = await gh(viewArgs)
     let created = false
@@ -217,9 +217,15 @@ export async function publishRepo(root: string, opts: PublishOpts = {}): Promise
     }
 
     const info = carveGhJson<RepoView>(view.out)
-    const proto = await gh(['config', 'get', 'git_protocol'])
-    const url = (firstGhLine(proto.out) === 'ssh' ? info?.sshUrl : info?.url) ?? info?.url ?? info?.sshUrl
-    if (url == null) return void p(`WARN no remote wired: gh answer unreadable (${firstGhLine(view.out)})`)
+    // ALWAYS the ssh url gh gave, never the https one and never `gh config
+    // get git_protocol`: an https origin re-asks for a credential on every
+    // push, and a machine answering `https` there wires a remote that reports
+    // success and fails at the first push. An answer carrying no sshUrl is
+    // unreadable, not an invitation to build one: this module knows no host,
+    // and a guessed `github.com` remote against an enterprise gh is the same
+    // silent failure one host over
+    const url = info?.sshUrl
+    if (url == null) return void p(`WARN no remote wired: gh answered without an ssh url (${firstGhLine(view.out)})`)
 
     const add = await git(['remote', 'add', 'origin', url])
     if (add.code !== 0) return void p(`WARN no remote wired: git remote add failed (${firstGhLine(add.out)})`)

package/src/ledger/gate-units.ts

@@ -40,44 +40,97 @@ export function tieredTasks(c: RepoConfig, root: string, tier: TestTier): TaskDe
  *  built from the unmodified list would let a quick run replay into a full one
  *  under one identity. */
 export function gateUnits(root: string, c: RepoConfig, tasks?: TaskDef[]): UnitDecl[] {
-    const out: UnitDecl[] = []
+    return gateInventory(root, c, tasks).map((r) => r.decl)
+}
+
+/** one gate unit with everything a reader asks about it, not only what the
+ *  key layer asks. The cache half stays in `decl` so `UnitDecl` never grows
+ *  fields the key layer must then decide to ignore. */
+export type UnitRow = {
+    decl: UnitDecl
+    /** the display name an operator reads (a rule's title, else the id) */
+    title: string
+    /** does `shipkit ci` run it? false = PROACTIVE: `shipkit check` reports it,
+     *  the gate never does, and it may sit red for months without anything
+     *  being wrong with the change in front of you. */
+    gate: boolean
+    /** can a failure stop you? null = the unit never said AND the repo set no
+     *  `checkDefaults.blocking`, which the check runner treats as fatal. */
+    blocking: boolean | null
+    /** where the answer is owned: a rule's wiki page, a check's file, a task's
+     *  command. Null when the unit names none. */
+    owner: string | null
+    /** the group a task was filed under, for the few that declare one */
+    group: string | null
+    /** excluded from a default run unless named with `--with` */
+    optIn: boolean
+}
+
+/** every unit the gate knows, with its metadata. `gateUnits` is this list
+ *  narrowed to the cache declaration, so the three registries are walked in
+ *  exactly one place and a surface can never enumerate a different set than
+ *  the one the key layer keyed. */
+export function gateInventory(root: string, c: RepoConfig, tasks?: TaskDef[]): UnitRow[] {
+    const out: UnitRow[] = []
     for (const t of tasks ?? allTasks(c, root).tasks) {
         out.push({
-            id: t.id,
-            kind: 'task',
-            inputs: t.inputs,
-            ttl: t.ttl,
-            never: t.never,
-            argv: t.cmd,
-            // the env a task SETS is part of what it runs, not something read
-            // off the ambient environment, so it rides as an identity string
-            extra: t.env == null ? undefined : JSON.stringify(Object.entries(t.env).sort()),
+            decl: {
+                id: t.id,
+                kind: 'task',
+                inputs: t.inputs,
+                ttl: t.ttl,
+                never: t.never,
+                argv: t.cmd,
+                extra: t.env == null ? undefined : JSON.stringify(Object.entries(t.env).sort()),
+            },
+            title: t.id,
+            // an optIn task is off the default run, which is the same shape as
+            // a check that opted out of the gate
+            gate: t.optIn !== true,
+            // a task IS the build: it has no non-blocking mode to declare
+            blocking: true,
+            owner: t.cmd == null ? null : t.cmd.join(' '),
+            group: t.group ?? null,
+            optIn: t.optIn === true,
         })
     }
     for (const r of [...RULES, ...(c.rules ?? [])]) {
         out.push({
-            id: r.id,
-            kind: 'rule',
-            inputs: r.inputs,
-            code: r.code,
-            ttl: r.ttl,
-            never: r.never,
-            extra: r.cacheKey?.({ root, config: c }),
+            decl: {
+                id: r.id,
+                kind: 'rule',
+                inputs: r.inputs,
+                code: r.code,
+                ttl: r.ttl,
+                never: r.never,
+                extra: r.cacheKey?.({ root, config: c }),
+            },
+            title: r.title,
+            gate: true,
+            blocking: r.blocking,
+            owner: r.owner,
+            group: null,
+            optIn: false,
         })
     }
     for (const d of discoverChecks(root)) {
         const rel = relative(root, d.path).replace(/\\/g, '/')
         out.push({
-            id: d.name,
-            kind: 'check',
-            inputs: d.inputs ?? undefined,
-            ttl: d.ttl ?? undefined,
-            never: d.never ?? undefined,
-            // a check IS a file, so its own code needs no declaration: the
-            // module graph walks from here through every helper it imports,
-            // which is what makes fixing a shared helper move the check's key
-            code: [rel],
-            argv: ['bun', rel],
+            decl: {
+                id: d.name,
+                kind: 'check',
+                inputs: d.inputs ?? undefined,
+                ttl: d.ttl ?? undefined,
+                never: d.never ?? undefined,
+                code: [rel],
+                argv: ['bun', rel],
+            },
+            title: d.name,
+            gate: d.gate,
+            blocking: d.blocking ?? c.checkDefaults?.blocking ?? null,
+            owner: rel,
+            group: null,
+            optIn: false,
         })
     }
     return out

package/src/ledger/store.ts

@@ -44,6 +44,11 @@ export type Stored<T> = {
     key: string
     /** when it was written, ms since epoch */
     at: number
+    /** how long THIS entry stays valid, when that is shorter than the unit's
+     *  declared TTL. A measured negative writes one, so a red about the world
+     *  clears soon after a human fixes the world, while a clean answer keeps
+     *  for the full declared window. Absent means the declared TTL. */
+    keeps?: number
     payload: T
 }
 
@@ -87,10 +92,10 @@ export function readStored<T>(path: string, key: string): Stored<T> | null {
     } catch { return null }
 }
 
-export function writeStored<T>(path: string, key: string, payload: T, at: number): void {
+export function writeStored<T>(path: string, key: string, payload: T, at: number, keeps?: number): void {
     try {
         mkdirSync(dirname(path), { recursive: true })
-        atomicWrite(path, JSON.stringify({ v: STORE_VERSION, key, at, payload }))
+        atomicWrite(path, JSON.stringify({ v: STORE_VERSION, key, at, keeps, payload }))
     } catch {
         // a store that cannot be written is slow, never wrong: the answer was
         // already printed, and the next run measures again

package/src/ledger/unit-table.ts

@@ -0,0 +1,105 @@
+// THE inventory render — every gate unit as one markdown row, so the question
+// "what runs here, does it block me, and how often does it really run" has a
+// surface that is read rather than reconstructed from three commands.
+//
+// Deliberately carries NO live run state: no timestamps, no key hashes, no
+// last verdict. Everything here is what a unit DECLARED about itself, so two
+// runs a week apart over an unchanged repo write identical bytes and the file
+// never churns. It is still generated, gitignored AND untracked like STATUS.md
+// (rules/untrack-generated.ts), so it is read on disk, never in git history.
+// Live keys are `shipkit keys`, live verdicts are STATUS.md.
+import { join } from 'path'
+import { atomicWrite, withFileLock } from '../core/locked-write.ts'
+import { classify } from './git-key.ts'
+import type { UnitRow } from './gate-units.ts'
+
+/** the sidecar every gate run refreshes beside STATUS.md */
+export const UNIT_TABLE_FILE = 'STATUS.full.md'
+
+/** a cell can never break the table it sits in */
+const cell = (s: string): string => s.replace(/\|/g, '\\|').replace(/\n/g, ' ')
+
+export type UnitTableInput = {
+    /** repo name, for the headline */
+    name: string
+    rows: UnitRow[]
+}
+
+/** what a unit's cache declaration means for how often it actually runs */
+function cacheOf(r: UnitRow): { population: string; ttl: string; reads: string; why: string } {
+    const c = classify(r.decl)
+    const inputs = r.decl.inputs ?? []
+    if (c.error != null) return { population: 'BROKEN', ttl: '', reads: '', why: c.error }
+    if (c.population === 'content') return { population: 'content', ttl: '', reads: inputs.join(', '), why: '' }
+    // no `reads` for these two: the cache column already says "world"/"never",
+    // and restating it on every such row is a column of noise
+    if (c.population === 'world') return { population: 'world', ttl: r.decl.ttl ?? '', reads: '', why: '' }
+    if (c.decided === true) return { population: 'never', ttl: '', reads: '', why: r.decl.never ?? '' }
+    return { population: 'UNDECLARED', ttl: '', reads: '', why: 'nobody has declared what this reads, so it re-runs every single time' }
+}
+
+export function renderUnitTable(input: UnitTableInput): string {
+    const { name, rows } = input
+    const counts = { task: 0, rule: 0, check: 0 }
+    for (const r of rows) counts[r.decl.kind]++
+
+    const body: string[] = []
+    body.push(`<!-- generated by \`shipkit units\`, refreshed by every gate run, gitignored (SK004) -->`)
+    body.push(`# ${name} units — ${rows.length} total`)
+    body.push('')
+    body.push(`Everything \`shipkit ci\` and \`shipkit check\` know how to run: ${counts.task} task(s), ${counts.rule} rule(s), ${counts.check} discovered check(s).`)
+    body.push('')
+    body.push('- **runs in** — `gate` means `shipkit ci` runs it, so a red one says THIS change is broken. `proactive` means only `shipkit check` runs it: it reports the world (a box that is off, a cred nobody minted, a page nobody refreshed), it can sit red for months with nothing wrong, and it never stands between you and a commit.')
+    body.push('- **on failure** — `blocks` stops the run. `warns` prints and carries on. `UNDECLARED` is a defect, not a setting: the unit never said and the repo set no default, so the runner treats it as fatal by guess.')
+    body.push('- **cache** — `content` replays while the files it reads are untouched. `world` replays for its TTL, and a measured RED replays too, capped at one hour so the run after a fix sees the fix. `never` re-runs every time and somebody wrote down why. `UNDECLARED` re-runs every time and nobody has looked yet, which is the burn-down (`shipkit keys --burn-down`). `SHIPKIT_FRESH=1` busts all of it.')
+    const proactive = rows.filter((r) => !r.gate && !r.optIn).length
+    const warns = rows.filter((r) => r.blocking === false).length
+    const neverSaid = rows.filter((r) => r.blocking == null).length
+    const undeclared = rows.filter((r) => cacheOf(r).population === 'UNDECLARED')
+    body.push('')
+    // the most useful line in the file, so it sits ABOVE the 68 rows rather
+    // than under them
+    body.push(
+        `**${rows.length - proactive} in the gate, ${proactive} proactive · ${warns} warn instead of blocking${neverSaid > 0 ? `, ${neverSaid} never said` : ''} · ${undeclared.length} uncacheable with nobody having looked.**`,
+    )
+    body.push('')
+    body.push('| unit | kind | runs in | on failure | cache | ttl | reads | owner |')
+    body.push('|---|---|---|---|---|---|---|---|')
+    for (const r of rows) {
+        const c = cacheOf(r)
+        const blocking = r.blocking == null ? '**UNDECLARED**' : r.blocking ? 'blocks' : 'warns'
+        const runsIn = r.optIn ? 'opt-in' : r.gate ? 'gate' : 'proactive'
+        const population = c.population === 'UNDECLARED' ? '**UNDECLARED**' : c.population
+        body.push(
+            `| \`${cell(r.decl.id)}\` | ${r.decl.kind} | ${runsIn} | ${blocking} | ${population} | ${cell(c.ttl)} | ${cell(c.reads)} | ${r.owner == null ? '' : `\`${cell(r.owner)}\``} |`,
+        )
+    }
+    body.push('')
+
+    const decided = rows.filter((r) => cacheOf(r).population === 'never')
+    if (undeclared.length > 0) {
+        body.push(`## ${undeclared.length} unit(s) nothing can cache yet`)
+        body.push('')
+        body.push('Each of these runs on every single pass. Declaring `inputs` (it reads files), `ttl` (it reads the world) or `never` (nothing can describe it) is the fix, and the last one counts: a written reason is a decision, not a hole.')
+        body.push('')
+        for (const r of undeclared) body.push(`- \`${cell(r.decl.id)}\` (${r.decl.kind})${r.owner == null ? '' : ` — \`${cell(r.owner)}\``}`)
+        body.push('')
+    }
+    if (decided.length > 0) {
+        body.push(`## ${decided.length} unit(s) decided uncacheable`)
+        body.push('')
+        for (const r of decided) body.push(`- \`${cell(r.decl.id)}\` — ${cell(r.decl.never ?? '')}`)
+        body.push('')
+    }
+
+    return body.join('\n')
+}
+
+/** refresh the sidecar beside STATUS.md. Lock-guarded exactly like STATUS.md:
+ *  several runners in one checkout is the normal case, and the loser skipping
+ *  a render it would have written identically costs nothing. */
+export function writeUnitTable(root: string, input: UnitTableInput): { written: boolean; warn?: string } {
+    const target = join(root, UNIT_TABLE_FILE)
+    const r = withFileLock(target, () => { atomicWrite(target, `${renderUnitTable(input).trimEnd()}\n`) })
+    return r.ok ? { written: true } : { written: false, warn: `${UNIT_TABLE_FILE} locked by another runner — skipped this write` }
+}