rvlib-shipkit 1.4.0 → 1.5.0

package/src/home/pm.ts

@@ -27,6 +27,10 @@ export type ChildView = ProcView & { tail: string[] }
 /** where pm, the daemon and the web listen */
 export type CorePorts = { pm: number; daemon: number; web: number }
 
+/** a child whose pid lives but has not answered for this long is hung and
+ *  gets killed: a healthy daemon answers within about 20 s of its start */
+export const CHILD_HANG_MS = 90_000
+
 /** how many log lines each of shipkit's own processes hands the page */
 const CORE_TAIL = 20
 
@@ -61,6 +65,8 @@ export type PmDeps = {
     /** runs a stop or restart of the web once its answer is out: the web
      *  proxies that very request (default: 200 ms later) */
     later?: (f: () => void) => void
+    /** where pm says what it did on its own, a hung child killed */
+    say?: (line: string) => void
 }
 
 const WEB_ANSWER_MS = 200
@@ -79,6 +85,8 @@ export class Pm {
             probe: () => d.probe(role),
             // a crash loop while its code is being edited heals itself
             neverGiveUp: true,
+            hangMs: CHILD_HANG_MS,
+            say: d.say,
         }, d.deps ?? realDeps)]))
     }
 

package/src/home/run-pm.ts

@@ -100,6 +100,7 @@ export async function runPm(root: string, io: HomeIo, o: { port?: number } = {})
         cmd: (role) => [process.execPath, CLI, role],
         probe: roleAnswers,
         resources: new Resources(c.processes, dir),
+        say: io.printErr,
     })
     let server: Bun.Server<unknown>
     try {

package/src/home/serve-web.ts

@@ -51,8 +51,8 @@ export const REPO_ANSWER_MS = 30_000
 export const LIST_EVERY_MS = 30_000
 export const LIST_RETRY_MS = 1_000
 
-/** the one home answer that can wait on git: the activity page's first read of a window */
-export const readsGit = (path: string): boolean => path === '/api/home/activity.json'
+/** the home answers that can wait on git: the activity page's first read of a window, and a repo's git page */
+export const readsGit = (path: string): boolean => path === '/api/home/activity.json' || path === '/api/home/git.json'
 
 /** a run or a check run streams for minutes, and a silent one is never cut */
 export const streams = (path: string): boolean => /\/api\/(run|check\/run)$/.test(path)

package/src/home/supervise.ts

@@ -29,6 +29,12 @@ export type ProcSpec = {
     /** never left down after CRASH_LIMIT crashes: it keeps retrying at the
      *  longest backoff, so a code fix brings it back with no hand */
     neverGiveUp?: boolean
+    /** a pid that lives but has not answered its probe for this long is hung
+     *  (a main thread stuck in one synchronous step still holds its port):
+     *  killed, then started again after the crash backoff. None = never */
+    hangMs?: number
+    /** a line for every act the supervisor takes on its own */
+    say?: (line: string) => void
 }
 
 export type ProcView = {
@@ -137,6 +143,8 @@ export class Proc {
     private retryAt: number | null = null
     private killAt: number | null = null
     private probing = false
+    /** why the kill in flight was a hang kill, for the crash note */
+    private hung: string | null = null
     /** a restart: start again once the stop landed */
     private again = false
     /** it answers its probe with no pid of ours behind it */
@@ -275,6 +283,8 @@ export class Proc {
         const now = this.d.now()
         if (this.pid != null && !this.d.alive(this.pid)) {
             this.gone()
+            const hung = this.hung
+            this.hung = null
             if (this.again) {
                 this.again = false
                 this.want = 'up'
@@ -287,7 +297,7 @@ export class Proc {
                     this.set('crashed', `exited ${this.crashes.length} times in ${Math.round(CRASH_WINDOW_MS / 60_000)} min, left down: see the log`)
                 } else {
                     this.retryAt = now + BACKOFF_MS[Math.min(this.crashes.length - 1, BACKOFF_MS.length - 1)]!
-                    this.set('crashed', `exited, restart in ${Math.round((this.retryAt - now) / 1000)}s`)
+                    this.set('crashed', `${hung != null ? `${hung}, killed` : 'exited'}, restart in ${Math.round((this.retryAt - now) / 1000)}s`)
                 }
             }
         }
@@ -318,6 +328,19 @@ export class Proc {
         } finally {
             this.probing = false
         }
+        this.killIfHung(now)
+    }
+
+    /** a pid that lives and still has not answered, hangMs after it last
+     *  changed status, is stopped: the crash path starts it again */
+    private killIfHung(now: number): void {
+        const hang = this.spec.hangMs
+        if (hang == null || this.status !== 'starting' || this.pid == null || this.want !== 'up' || now - this.since < hang) return
+        this.hung = `did not answer its probe for ${Math.round((now - this.since) / 1000)}s`
+        this.spec.say?.(`WARN ${this.spec.id} (pid ${this.pid}) ${this.hung}: killed, it starts again`)
+        this.d.kill(this.pid, 'SIGTERM')
+        this.killAt = now + KILL_AFTER_MS
+        this.set('stopping', `${this.hung}, killing it`)
     }
 
     view(): ProcView {

package/src/hooks/run-hooks.ts

@@ -14,6 +14,11 @@ import { gitRoot } from '../core/git-root.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { gitBin } from '../core/git-bin.ts'
+import { discoverChecks } from '../core/discover-checks.ts'
+import { CheckCtx } from '../core/check-ctx.ts'
+import { runCheckBody, type CheckDef } from '../check.ts'
+import { repoOff } from '../core/when.ts'
+import { formatLine } from '../core/wire.ts'
 
 export type HooksConfig = {
     /** repo-specific commands run in the pre-commit gate, after the built-ins.
@@ -210,7 +215,7 @@ export function blockedStaged(staged: string[], config: RepoConfig): string[] {
 const draftsOpen = (c: RepoConfig): boolean => c.visibility === 'private'
 
 /** the pre-commit gate: built-in leak guard, then the repo's own commands.
- *  A commit takes ~1s (build/shipkit.md): the gate times itself, and going
+ *  A commit takes ~1s (build/shipkit/commit-gates.md): the gate times itself, and going
  *  over budget WARNs naming the fix, so drift back to slow commits is loud. */
 export async function runPreCommit(root: string, config: RepoConfig): Promise<GateOutcome[]> {
     const started = performance.now()
@@ -273,6 +278,7 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
             ],
         })
     }
+    out.push(...(await runPreCommitChecks(root, config)))
     for (const c of h.preCommit ?? []) {
         const r = await spawnWithTimeout(c.cmd, { cwd: root, timeoutMs: 120_000 })
         out.push({
@@ -282,15 +288,52 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
         })
     }
     const elapsed = performance.now() - started
-    if (elapsed > 1500)
+    if (elapsed > HOOK_BUDGET_MS)
         out.push({
             id: 'hook-budget',
             ok: true,
-            lines: [`WARN pre-commit took ${(elapsed / 1000).toFixed(1)}s (budget ~1s) — move slow preCommit commands to ci tasks (build/shipkit.md)`],
+            lines: [`WARN pre-commit took ${(elapsed / 1000).toFixed(1)}s (budget ${HOOK_BUDGET_MS / 1000}s) — move slow preCommit commands to ci tasks, or a check off onPreCommit (build/shipkit/runs.md)`],
         })
     return out
 }
 
+/** the whole hook, boot included, past which it warns */
+export const HOOK_BUDGET_MS = 1_000
+
+/** the checks that declare `onPreCommit` and apply here, with their budget */
+export type PreCommitCheck = { id: string; title: string; owner: string; budgetMs: number; run: NonNullable<CheckDef['run']>; repair: unknown }
+
+export async function preCommitChecks(root: string, config: RepoConfig): Promise<PreCommitCheck[]> {
+    const out: PreCommitCheck[] = []
+    for (const u of await discoverChecks(root)) {
+        const p = u.def.runs.onPreCommit
+        if (p === false || u.def.run == null) continue
+        if (repoOff(config, u.id) != null) continue
+        if (typeof u.def.applies === 'function') {
+            try { if (u.def.applies({ root, config }) != null) continue } catch (e) { console.error(`WARN ${u.id} applies threw, so it applies: ${(e as Error).message}`) }
+        }
+        out.push({ id: u.id, title: u.title, owner: u.owner, budgetMs: p.budgetMs, run: u.def.run, repair: u.def.repair })
+    }
+    return out
+}
+
+/** every `onPreCommit` check, run RAW on the working tree: no ledger, no
+ *  cache, no repair. A failure refuses the commit, a pass over its budget
+ *  warns by name and never blocks on time */
+async function runPreCommitChecks(root: string, config: RepoConfig): Promise<GateOutcome[]> {
+    const out: GateOutcome[] = []
+    for (const k of await preCommitChecks(root, config)) {
+        const c = CheckCtx.open({ root, config })
+        const t = performance.now()
+        await runCheckBody({ id: k.id, title: k.title, owner: k.owner, run: k.run, fix: k.repair }, c)
+        const ms = performance.now() - t
+        const lines = c.failed ? c.lines.map((l) => formatLine(l, false)) : [`ok: ${k.id} (${Math.round(ms)}ms)`]
+        if (ms > k.budgetMs) lines.push(`WARN ${k.id} took ${Math.round(ms)}ms at commit, over its ${k.budgetMs}ms onPreCommit budget — make it cheaper, or move it off onPreCommit`)
+        out.push({ id: k.id, ok: !c.failed, lines })
+    }
+    return out
+}
+
 /** the commit-msg gate: the shared message predicate, then the repo's own. */
 export async function runCommitMsg(root: string, config: RepoConfig, messageFile: string): Promise<GateOutcome[]> {
     const h = config.hooks ?? {}
@@ -339,7 +382,7 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
 }
 
 /** what blocks a commit here, the enumeration hand-rolled hooks never had. */
-export function listGates(config: RepoConfig, root = process.cwd()): string[] {
+export function listGates(config: RepoConfig, root = process.cwd(), checks: { id: string; budgetMs: number }[] = []): string[] {
     const h = config.hooks ?? {}
     const off = new Set(h.disable ?? [])
     const kw = h.keywordFile ?? KEYWORD_FILE
@@ -354,6 +397,7 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
         `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.shipkit/private/banned-keywords.txt${leakAllowState}`,
         ...((h.blockedPaths ?? []).length > 0 ? [`pre-commit  blocked-paths — nothing under ${h.blockedPaths!.join(', ')} enters git${draftsOpen(config) && blockedStaged([COMFY_DRAFTS], config).length === 0 && h.blockedPaths!.some((p) => COMFY_DRAFTS.startsWith(p)) ? `, except ${COMFY_DRAFTS} (declared private)` : ''}`] : []),
         `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
+        ...checks.map((c) => `pre-commit  ${c.id} — the check, onPreCommit, budget ${c.budgetMs}ms`),
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),
         off.has('commit-message')
             ? `commit-msg  commit-message (DISABLED by config) — dash punctuation + French; ai-attribution stays on, never disabled`

package/src/init-repo.ts

@@ -100,7 +100,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         // its .gitignore policy block (same fixer as `check --fix SK004`),
         // with the repo's own contributed lines honored
         const cfg = await loadRepoConfig(root)
-        const g = await gitignorePolicy.fix!(CheckCtx.open({ root, config: cfg }))
+        const g = await gitignorePolicy.repair!(CheckCtx.open({ root, config: cfg }))
         p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
         // the repos that need ONE WAY IN most are the ones that already exist,
         // so a re-run REPAIRS rather than only seeding a fresh checkout
@@ -136,7 +136,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     }
     // the .gitignore policy block (contract git policy) — same fixer as
     // `shipkit check --fix SK004`, one code path
-    const g = await gitignorePolicy.fix!(CheckCtx.open({ root, config: defineRepo({ name }) }))
+    const g = await gitignorePolicy.repair!(CheckCtx.open({ root, config: defineRepo({ name }) }))
     p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     await repairOneWayIn(root, defineRepo({ name }), p)
     await furnishEditor(root, { name }, p)
@@ -194,7 +194,7 @@ async function furnishEditor(root: string, cfg: { name?: string; serve?: { port?
             // a file SK017 cannot read is still the repo's own: it is never
             // reported as missing, and it is never rewritten
             let hub: { changed: boolean; summary: string }
-            try { hub = await vscodeHubTask.fix!(CheckCtx.open({ root, config: defineRepo({ name }) })) } catch (e) {
+            try { hub = await vscodeHubTask.repair!(CheckCtx.open({ root, config: defineRepo({ name }) })) } catch (e) {
                 p('ok: .vscode/ is this repo\'s own, left untouched')
                 return void p(`WARN .vscode/tasks.json does not parse (${e instanceof Error ? e.message : String(e)}): the hub task gets no problem matcher until it does`)
             }
@@ -208,14 +208,14 @@ async function furnishEditor(root: string, cfg: { name?: string; serve?: { port?
 }
 
 /** ONE WAY IN, both halves, through the SAME fixers `shipkit check --fix` runs
- *  (build/shipkit.md). Nothing here is a second implementation: rule SK001
+ *  (build/shipkit/one-way-in.md). Nothing here is a second implementation: rule SK001
  *  routes the package.json scripts, rule SK013 writes the harness policy, and
  *  init just calls them so a wired repo is born enforced and a re-run repairs
  *  one that was not. The deny is a RESTRICTION, which is why it lands
  *  unconditionally where the scaffold's allow list stays opt in. */
 async function repairOneWayIn(root: string, config: Parameters<typeof defineRepo>[0], p: (line: string) => void): Promise<void> {
-    const pkg = await packageJsonShape.fix!(CheckCtx.open({ root, config }))
+    const pkg = await packageJsonShape.repair!(CheckCtx.open({ root, config }))
     if (pkg.changed) p(`ok: package.json — ${pkg.summary}`)
-    const policy = await oneWayInPolicy.fix!(CheckCtx.open({ root, config }))
+    const policy = await oneWayInPolicy.repair!(CheckCtx.open({ root, config }))
     p(policy.changed ? `ok: ${policy.summary}` : `ok: .claude/settings.json already closes every raw runner`)
 }

package/src/ledger/gate-checks.ts

@@ -19,11 +19,12 @@ import { discoverLegacyChecks } from '../core/discover-legacy-checks.ts'
 import { checkFileRunBy } from '../core/legacy-shapes.ts'
 import { ruleCacheExtra } from '../rules/rule.ts'
 import { discoverChecks } from '../core/discover-checks.ts'
-import { checkCacheExtra, describeFirst, type TaskDef, type CheckFrom, type CheckEnv } from '../check.ts'
+import { checkCacheExtra, describeFirst, type TaskDef, type CheckFrom, type CheckEnv, type CheckDef } from '../check.ts'
 import { CHECK_TIMEOUT_MS, type RunnableCheck, type CheckBody } from '../core/check-runner.ts'
-import { ttlMsOf } from '../core/wire.ts'
+import { FOREVER, ttlMsOf } from '../core/wire.ts'
 import { budgetOf } from '../core/budget.ts'
-import { whenOfLegacyCheck, whenOfDisabledSlot, whenOfRule, whenOfTask, whenOfCheck, type WhenDecl } from '../core/when.ts'
+import { repoOff, withRepoOff, whenSummary, type WhenDecl } from '../core/when.ts'
+import { cacheText, filesText, NOWHERE, sourced, type CacheDecl, type ResolvedRuns, type Runs } from '../core/runs.ts'
 import type { CheckDecl } from './git-key.ts'
 import { populationOf } from '../problems/problem-line.ts'
 import { rawAccessInClosure, rawAccessLine } from '../core/raw-access.ts'
@@ -31,7 +32,6 @@ import type { RvtConfig } from '../ts/config.ts'
 import { LIB_ROOT } from '../core/lib-root.ts'
 import type { DiscoveredCheck } from '../core/discover-checks.ts'
 import { declaredTestUnits, inputsOutsideUnits, isTestFile } from '../suite/test-units.ts'
-import type { PlanDecl } from '../plan/cadence.ts'
 
 /** why an undeclared `run` check cannot be keyed on its reads, or null when it
  *  can. A built-in is walked inside the toolkit, a repo check inside the repo
@@ -74,18 +74,6 @@ export async function allTasks(c: RepoConfig, root: string): Promise<FloorResolu
 /** one gate check with everything a reader asks about it, not only what the
  *  key layer asks. The cache half stays in `decl` so `CheckDecl` never grows
  *  fields the key layer must then decide to ignore. */
-/** a check's `planOff`, read now; one that throws stays planned, and says so */
-function planOffOf(id: string, fn: ((env: CheckEnv) => string | null) | undefined, env: CheckEnv): { planOff?: string } {
-    if (fn == null) return {}
-    try {
-        const why = fn(env)
-        return why == null ? {} : { planOff: why }
-    } catch (e) {
-        console.error(`WARN ${id} planOff threw, so it stays planned: ${(e as Error).message}`)
-        return {}
-    }
-}
-
 export type CheckRow = {
     decl: CheckDecl
     /** the display name an operator reads (its title, else the id) */
@@ -126,16 +114,16 @@ export type CheckRow = {
      *  then re-runs the check. `shipkit checks --fixable` is the catalog of
      *  everything in this repo that repairs itself. */
     fixable: boolean
-    /** WHERE IT RUNS, the one reading of the `when` key, of the three
-     *  spellings it replaces, and of a floor slot turned off (core/when.ts) */
+    /** WHERE IT RUNS, every context resolved: what the check file declared,
+     *  or what the code deriving the row wrote, with the repo's `off`
+     *  override laid over it (core/runs.ts, core/when.ts) */
+    runs: ResolvedRuns
+    /** how its answer is kept, as one short cell (core/runs.ts cacheText) */
+    cache: string
+    /** the coarse word the runs read as, for the surfaces that show one */
     when: WhenDecl
     /** what it waits on, null when it waits on nothing */
     deps: string[] | null
-    /** when the planner runs it on its own (check.ts `every`, `cron`,
-     *  `whenInactive`). Absent: nothing declared, the planner's defaults */
-    plan?: PlanDecl
-    /** why the plan leaves this check out in this repo (check.ts `planOff`) */
-    planOff?: string
     /** whose check it is: `shipkit` = it ships with the toolkit (a built-in
      *  SK check, the contracts pass, a floor slot nothing in the repo filled),
      *  `repo` = this repo declared it (a package.json script behind a floor
@@ -178,7 +166,7 @@ function runnableOf(row: CheckRow, body: CheckBody, o: { fix?: unknown; pointer?
         owner: row.owner ?? row.decl.id,
         blocking: row.blocking,
         build: row.build,
-        when: row.when,
+        runs: row.runs,
         deps: row.deps ?? [],
         group: row.group,
         timeoutMs: row.timeoutMs ?? (row.build ? BUILD_TIMEOUT_MS : CHECK_TIMEOUT_MS),
@@ -211,6 +199,59 @@ function rootTestKey(root: string, c: RepoConfig, floor: FloorResolution): { inp
 const taskDescription = (t: TaskDef): string =>
     describeFirst(t.description, t.cmd == null ? null : `\`${t.cmd.join(' ')}\` exits 0`, `the ${t.id} task ${t.cmd == null ? 'passes' : 'exits 0'}`)
 
+/** the default range a repo row nothing can key runs on, so it is asked
+ *  about once a day and never in step with its siblings */
+const DAILY: [string, string] = ['20h', '28h']
+
+/** the runs of a row with no file to declare them in (a floor slot, a config
+ *  task, a legacy rule or script), written out in full with the reason. It
+ *  keeps what the planner and the gate did with such a row before the
+ *  declaration was explicit: a ttl is the cadence ('once' for a forever
+ *  fact), a save moves a keyed row or a fact, a gate build step nothing keys
+ *  reruns after every save burst, and any other row nothing keys runs about
+ *  once a day */
+function derivedRuns(o: { gate: boolean; build: boolean; inputs?: string[]; ttl?: string; kind: string; repair: boolean }): ResolvedRuns {
+    const keyed = o.inputs != null
+    const ttl = o.ttl != null && o.ttl !== '' ? o.ttl : null
+    const fact = ttl === FOREVER
+    const parked = o.build && !o.gate
+    const onClock: Runs['onClock'] = parked ? false : fact ? 'once' : ttl != null ? { every: ttl, inactive: 'wait' } : o.build || keyed ? false : { every: DAILY, inactive: 'wait' }
+    const onSave: Runs['onSave'] = parked ? false : fact || (keyed && ttl == null) ? 'moved' : ttl == null && o.build ? 'burst' : false
+    const r: Runs = { ...NOWHERE, onCi: o.gate, onFull: o.gate, onRelease: o.gate, onHealth: !o.build, onSave, onClock }
+    const fix = !o.repair ? 'none' : o.gate ? 'ci' : 'manual'
+    const clock = onClock === false ? '' : onClock === 'once' ? ', once while its fact is unknown' : `, on the clock every ${ttl ?? DAILY.join('..')}`
+    const save = onSave === 'moved' ? ', the daemon when its key moves' : onSave === 'burst' ? ', the daemon after every save burst since nothing keys it' : ''
+    const where = parked ? 'parked: only --with or --only names it' : `${o.gate ? 'every gate' : 'no gate'}${o.build ? ', never the health pass' : ' and the health pass'}${save}${clock}`
+    return sourced(r, fix, 'derived', `${o.kind}: ${where}`)
+}
+
+/** the cache half of a check file, as the key layer reads it */
+function declOfCache(cache: CacheDecl, env: CheckEnv): { inputs?: string[]; ttl?: string; never?: string; key?: string; reads?: boolean } {
+    switch (cache.by) {
+        case 'files': return { inputs: cache.inputs, key: cache.key?.(env) }
+        case 'reads': return { reads: true }
+        case 'ttl': return { ttl: cache.span, key: cache.key?.(env) }
+        case 'fact': return { ttl: FOREVER, key: cache.key(env) }
+        case 'never': return { never: cache.why }
+    }
+}
+
+/** a legacy row's cache, as one cell */
+const legacyCacheText = (d: { inputs?: string[]; ttl?: string; never?: string }): string =>
+    d.inputs != null ? filesText(d.inputs) : d.ttl != null && d.ttl !== '' ? (d.ttl === FOREVER ? 'fact' : `ttl ${d.ttl}`) : d.never != null ? `never: ${d.never}` : 'never: nothing declared'
+
+/** a check file's own runs, resolved: its declaration, n/a where it does not
+ *  apply, then the repo's override */
+function fileRuns(def: CheckDef, id: string, c: RepoConfig, env: CheckEnv): ResolvedRuns {
+    const own = sourced(def.runs, def.fix, 'check file')
+    let na: string | null = null
+    if (typeof def.applies === 'function') {
+        try { na = def.applies(env) } catch (e) { console.error(`WARN ${id} applies threw, so it applies: ${(e as Error).message}`) }
+    }
+    const base = na == null ? own : { ...own, off: `n/a here: ${na}` }
+    return withRepoOff(base, repoOff(c, id))
+}
+
 /** THE enumeration. Everything below reads it, nothing else walks. */
 export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts = {}): Promise<GateCheck[]> {
     const out: GateCheck[] = []
@@ -252,10 +293,13 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
     for (const raw of [...floor.tasks, ...(c.tasks ?? []).filter((t) => foldedInto.get(t.id) !== t)]) {
         const t: TaskDef = full ? { ...raw, env: { ...raw.env, [FULL_TESTS_ENV]: '1' } } : raw
         const own = t.id === 'test' && floor.tasks.includes(raw) ? rootTest : null
+        const inputs = own?.inputs ?? t.inputs
+        const kind = floor.tasks.includes(raw) ? 'a floor slot' : 'a repo.config.ts task'
+        const runs = withRepoOff(derivedRuns({ gate: t.optIn !== true, build: true, inputs, ttl: t.ttl, kind, repair: false }), repoOff(c, t.id))
         const row: CheckRow = {
             decl: {
                 id: t.id,
-                inputs: own?.inputs ?? t.inputs,
+                inputs,
                 ttl: t.ttl,
                 never: t.never,
                 argv: t.cmd,
@@ -266,7 +310,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             description: taskDescription(t),
             // 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,
+            gate: runs.off == null && runs.onCi,
             build: true,
             // a build step IS the build: it has no non-blocking mode
             blocking: true,
@@ -278,7 +322,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             // a build step runs a TOOL, and repairing what a tool reports is
             // that tool's own job (a formatter, a codemod), never the gate's
             fixable: false,
-            when: whenOfTask(c, t),
+            runs,
+            cache: legacyCacheText({ inputs, ttl: t.ttl, never: t.never }),
+            when: whenSummary(runs, repoOff(c, t.id), false),
             deps: t.deps ?? null,
             from: taskFrom(t.id),
         }
@@ -293,6 +339,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
     // no command, which is why it declares `never` rather than joining the
     // burn-down of checks nobody has keyed yet.
     for (const id of floor.disabled) {
+        const runs = sourced(NOWHERE, 'none', 'repo.config.ts', null, `defaults.${id}: false`)
         const row: CheckRow = {
             decl: { id, never: `turned off by defaults.${id}: false, so there is no command to key` },
             title: id,
@@ -306,7 +353,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             budgetMs: budgetOf(id, undefined, { build: true, cmd: false, world: false }, c.budgets),
             optIn: false,
             fixable: false,
-            when: whenOfDisabledSlot(id),
+            runs,
+            cache: `never: turned off by defaults.${id}: false`,
+            when: whenSummary(runs, { reason: `defaults.${id}: false`, source: 'defaults' }, false),
             deps: null,
             // the repo wrote the line that turned it off
             from: 'repo',
@@ -319,46 +368,44 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
     const configs = new Map<string, RvtConfig>()
     const texts = new Map<string, string>()
     for (const u of checks) {
-        const w = whenOfCheck(c, u)
-        // an in process body declaring nothing is keyed on what it reads
-        // through its context (git-key.ts READS). The tier is part of that
-        // question: a body can read the env, and a quick answer must never
-        // stand in for a full one
-        const undeclared = u.def.run != null && u.def.inputs == null && u.def.ttl == null && u.def.never == null
-        // conservative: any module its body can reach that touches the disk or
-        // a process around `c` keeps it off its reads (core/raw-access.ts)
-        const raw = undeclared ? rawAccessOf(root, u, configs, texts) : null
-        const reads = undeclared && raw == null
-        const extra = checkCacheExtra({ id: u.id, cacheKey: u.def.cacheKey }, env, w)
+        const runs = fileRuns(u.def, u.id, c, env)
+        const cache = declOfCache(u.def.cache, env)
+        // a body keyed on what it reads through its context (git-key.ts
+        // READS). The tier is part of that question: a body can read the env,
+        // and a quick answer must never stand in for a full one. Any module
+        // its body can reach that touches the disk or a process around `c`
+        // contradicts the declaration (core/raw-access.ts), and says so loud
+        const raw = cache.reads === true && u.def.run != null ? rawAccessOf(root, u, configs, texts) : null
+        const extra = checkCacheExtra(cache.key, runs.off)
         const row: CheckRow = {
             decl: {
                 id: u.id,
-                inputs: u.def.inputs,
+                inputs: cache.inputs,
                 code: u.rel == null ? undefined : [u.rel],
-                ttl: u.def.ttl,
-                never: u.def.never,
+                ttl: cache.ttl,
+                never: cache.never,
                 argv: u.def.cmd,
-                extra: reads ? `${extra ?? ''}|tier=${full ? 'full' : 'quick'}` : extra,
+                extra: cache.reads === true ? `${extra ?? ''}|tier=${full ? 'full' : 'quick'}` : extra,
                 writes: u.def.writes,
-                ...(reads ? { reads: true } : {}),
-                ...(raw != null ? { uncacheable: raw } : {}),
+                ...(cache.reads === true && raw == null ? { reads: true } : {}),
+                ...(raw != null ? { declError: `declares cache reads, but ${raw}` } : {}),
             },
             title: u.title,
             description: u.description,
-            gate: w.at !== 'health',
+            gate: runs.off == null && runs.onCi,
             build: u.def.build === true,
             blocking: u.def.blocking,
             owner: u.owner,
             group: u.def.group ?? null,
             timeoutMs: u.def.timeoutMs ?? null,
-            budgetMs: budgetOf(u.id, u.def.budgetMs, { build: u.def.build === true, cmd: u.def.cmd != null, world: u.def.ttl != null || u.def.never != null }, c.budgets),
+            budgetMs: budgetOf(u.id, u.def.budgetMs, { build: u.def.build === true, cmd: u.def.cmd != null, world: cache.ttl != null || cache.never != null }, c.budgets),
             optIn: false,
-            fixable: u.def.fix != null,
-            when: w,
+            fixable: u.def.repair != null,
+            runs,
+            cache: cacheText(u.def.cache),
+            when: whenSummary(runs, repoOff(c, u.id), true),
             deps: u.def.deps ?? null,
             from: u.from,
-            ...(u.def.every !== undefined || u.def.cron != null || u.def.whenInactive != null ? { plan: { every: u.def.every, cron: u.def.cron, whenInactive: u.def.whenInactive } } : {}),
-            ...planOffOf(u.id, u.def.planOff, env),
         }
         const body: CheckBody = {
             ...(u.def.cmd == null ? {} : { cmd: u.def.cmd }),
@@ -367,11 +414,12 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             // relative to the root, and an absolute one stands as written
             ...(u.def.cwd == null ? {} : { cwd: resolve(root, u.def.cwd) }),
         }
-        out.push({ row, runnable: runnableOf(row, body, { fix: u.def.fix, pointer: u.def.cmd?.join(' ') ?? null }) })
+        out.push({ row, runnable: runnableOf(row, body, { fix: u.def.repair, pointer: u.def.cmd?.join(' ') ?? null }) })
     }
     // LEGACY: `rules: []`, read as a check whose body is its lint. Dies with
     // that config key once `shipkit fleet` shows no repo below 0.40.
     for (const r of c.rules ?? []) {
+        const runs = withRepoOff(derivedRuns({ gate: true, build: false, inputs: r.inputs, ttl: r.ttl, kind: 'a legacy repo.config.ts rule', repair: r.fix != null }), repoOff(c, r.id))
         const row: CheckRow = {
             decl: {
                 id: r.id,
@@ -383,7 +431,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             },
             title: r.title,
             description: describeFirst(r.title, `rule ${r.id} holds`),
-            gate: true,
+            gate: runs.off == null && runs.onCi,
             build: false,
             blocking: r.blocking,
             owner: r.owner,
@@ -392,7 +440,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             budgetMs: budgetOf(r.id, undefined, { build: false, cmd: false, world: r.ttl != null || r.never != null }, c.budgets),
             optIn: false,
             fixable: r.fix != null,
-            when: whenOfRule(c, r.id),
+            runs,
+            cache: legacyCacheText(r),
+            when: whenSummary(runs, repoOff(c, r.id), false),
             deps: null,
             from: 'repo',
         }
@@ -409,12 +459,14 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
         // file's own cache declaration wins over the task's
         const d = task == null ? found : { ...found, gate: found.gate || task.optIn !== true }
         const cached = d.inputs != null || d.ttl != null || d.never != null
+        const li = { inputs: d.inputs ?? (cached ? undefined : task?.inputs), ttl: d.ttl ?? (cached ? undefined : task?.ttl), never: d.never ?? (cached ? undefined : task?.never) }
+        const runs = withRepoOff(derivedRuns({ gate: d.gate, build: false, inputs: li.inputs, ttl: li.ttl, kind: 'a legacy check script', repair: false }), repoOff(c, d.name))
         const row: CheckRow = {
             decl: {
                 id: d.name,
-                inputs: d.inputs ?? (cached ? undefined : task?.inputs),
-                ttl: d.ttl ?? (cached ? undefined : task?.ttl),
-                never: d.never ?? (cached ? undefined : task?.never),
+                inputs: li.inputs,
+                ttl: li.ttl,
+                never: li.never,
                 code: [rel],
                 argv: ['bun', rel],
                 // no `extra`, so WHERE it runs stays out of a legacy check's
@@ -425,7 +477,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             },
             title: d.name,
             description: describeFirst(`\`bun ${rel}\` exits 0`, `${d.name} exits 0`),
-            gate: d.gate,
+            gate: runs.off == null && runs.onCi,
             build: false,
             // the file wins, then the repo default, then nothing: an
             // unclassified check is an error, never a guess
@@ -437,7 +489,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             optIn: false,
             // the reader is a source scanner, so it cannot carry a function
             fixable: false,
-            when: whenOfLegacyCheck(c, d),
+            runs,
+            cache: legacyCacheText(li),
+            when: whenSummary(runs, repoOff(c, d.name), false),
             deps: task?.deps ?? null,
             from: 'repo',
         }

package/src/ledger/git-key.ts

@@ -85,6 +85,9 @@ export type CheckDecl = {
     /** why an undeclared `run` check stays uncached: the first module its body
      *  can reach that touches the disk or a process around the context */
     uncacheable?: string
+    /** the check's cache declaration contradicts its body (`reads` on a body
+     *  that touches the disk around its context): a registration failure */
+    declError?: string
 }
 
 export type CheckKey = {
@@ -121,6 +124,7 @@ export type Registration = {
  *  `inputs` on a `ttl` check is a registration FAIL: a check cannot both be
  *  described by files on disk and be un-describable by them. */
 export function classify(d: CheckDecl): { population: Population; error?: string; reason?: string; decided?: boolean } {
+    if (d.declError != null) return { population: 'none', error: `check '${d.id}': ${d.declError}` }
     const hasInputs = (d.inputs ?? []).length > 0
     const hasTtl = d.ttl != null && d.ttl !== ''
     const hasNever = d.never != null && d.never !== ''
@@ -230,7 +234,7 @@ export class KeyLayer {
         // no key at all
         let toolchain: { id: string; uncacheable: string[] }
         try {
-            toolchain = toolchainIdentity(root, o.cliEntry)
+            toolchain = { ...toolchainIdentity(root, o.cliEntry), uncacheable: [] }
         } catch (e) {
             toolchain = { id: 'unresolved', uncacheable: [`gate binary unreadable at ${o.cliEntry}: ${e instanceof Error ? e.message : String(e)}`] }
         }

package/src/ledger/ledger.ts

@@ -156,7 +156,7 @@ export class Ledger {
         return k
     }
 
-    private read(k: CheckKey): { payload: Stored } | null {
+    private read(k: CheckKey): { payload: Stored; at: number } | null {
         return this.answers.read<Stored>(NS, k.id, k.key!)
     }
 
@@ -168,7 +168,7 @@ export class Ledger {
 
     /** 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): CheckOutcome | null {
+    replay(id: string): (CheckOutcome & { at: number }) | null {
         const k = this.key(id)
         if (k.key == null) { this.unkeyed++; return null }
         if (!this.reading) { this.misses++; return null }
@@ -177,7 +177,7 @@ export class Ledger {
         if (k.population === 'reads' && (e.payload.reads == null || this.driftOf(e.payload.reads, () => this.view()) != null)) { this.misses++; return null }
         this.hits++
         this.replayed.push({ ns: NS, name: k.id, key: k.key })
-        return e.payload
+        return { ...e.payload, at: e.at }
     }
 
     /** the stored read set of a READS check, as the last store wrote it */
@@ -305,6 +305,6 @@ export function inflightSlot(dir: string, ns: string, id: string, key: string):
 /** 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))
+export function stampCached(lines: Line[], measuredMs: number, at: number, now: number = Date.now()): Line[] {
+    return lines.map((l, i) => (i === 0 ? { ...l, text: `${l.text} ${cachedStamp(measuredMs, now - at)}` } : l))
 }