rvlib-shipkit 1.2.0 → 1.4.0

package/src/hooks/run-hooks.ts

@@ -43,14 +43,18 @@ export type HooksConfig = {
      *  hooks/leak-guard.ts */
     leakAllow?: LeakAllowEntry[]
     /** staged-path prefixes that can never enter git (local state like
-     *  '.comfy-ts/'). A gitignore line is advisory and editable. This gate is not. */
+     *  '.comfy-ts/'). A gitignore line is advisory and editable. This gate is not.
+     *  A repo declaring `visibility: 'private'` still commits
+     *  '.comfy-ts/drafts/' through a broader prefix. Public and undeclared
+     *  repos block it. */
     blockedPaths?: string[]
     /** words the commit-message language gate never counts as French
      *  (proper nouns that carry accents without being a language choice) */
     languageAllow?: string[]
     /** disable a built-in gate, visible in `hooks list`, never silent.
      *  'commit-language' lifts ONLY the French check, keeping the dash and
-     *  AI-attribution guards armed. */
+     *  AI-attribution guards armed. 'commit-message' lifts the dash and French
+     *  checks; the AI-attribution guard is never lifted. */
     disable?: ('leak-guard' | 'commit-message' | 'root-identity' | 'commit-language')[]
 }
 
@@ -191,6 +195,20 @@ function waivedLines(waived: LeakWaiver[]): string[] {
     )
 }
 
+const COMFY_DRAFTS = '.comfy-ts/drafts/'
+
+/** the staged files the `blocked-paths` gate refuses. A repo DECLARED private
+ *  (never by default) commits its comfy drafts through a
+ *  broader block: a draft names private loras, which a private tree may hold.
+ *  A prefix naming the drafts folder itself keeps them blocked. */
+export function blockedStaged(staged: string[], config: RepoConfig): string[] {
+    const prefixes = config.hooks?.blockedPaths ?? []
+    const open = draftsOpen(config)
+    return staged.filter((f) => prefixes.some((p) => f.startsWith(p) && !(open && f.startsWith(COMFY_DRAFTS) && !p.startsWith(COMFY_DRAFTS))))
+}
+
+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
  *  over budget WARNs naming the fix, so drift back to slow commits is loud. */
@@ -226,7 +244,7 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
     if ((h.blockedPaths ?? []).length > 0) {
         const names = Bun.spawnSync([gitBin(), 'diff', '--cached', '--name-only'], { cwd: root })
         const staged = names.stdout.toString().split('\n').filter(Boolean)
-        const blocked = staged.filter((f) => h.blockedPaths!.some((p) => f.startsWith(p)))
+        const blocked = blockedStaged(staged, config)
         out.push(blocked.length === 0
             ? { id: 'blocked-paths', ok: true, lines: [`ok: blocked-paths clean (${h.blockedPaths!.join(', ')})`] }
             : {
@@ -292,6 +310,13 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
                     ...offenses.map((o) => `      line ${o.line}: ${o.text.slice(0, 100)}\n        ${o.why}`),
                 ],
             })
+    } else {
+        // AI attribution is the one message rule no config lifts: this hook is
+        // the guard against it in every repo (identity/how-we-commit.md)
+        const offenses = commitMessageOffenses(message).filter((o) => o.kind === 'attribution')
+        out.push(offenses.length === 0
+            ? { id: 'ai-attribution', ok: true, lines: ['ok: no AI attribution in the commit message'] }
+            : { id: 'ai-attribution', ok: false, lines: [`FAIL: commit message carries AI attribution`, ...offenses.map((o) => `      line ${o.line}: ${o.text.slice(0, 100)}\n        ${o.why}`)] })
     }
     // the leak guard also reads the MESSAGE, a private name pasted into a
     // commit body is as public as one pasted into a file
@@ -327,10 +352,12 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
     const leakAllowState = waivers === 0 ? '' : `, ${(h.leakAllow ?? []).length} repo waiver(s)${globalAllowFile() == null ? '' : ' + ~/.shipkit/private/leak-allow.json'}`
     return [
         `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`] : []),
+        ...((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`,
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),
-        `commit-msg  commit-message${off.has('commit-message') ? ' (DISABLED by config)' : ''} — dash punctuation + AI attribution + French${off.has('commit-language') ? ' (commit-language DISABLED by config)' : ''}`,
+        off.has('commit-message')
+            ? `commit-msg  commit-message (DISABLED by config) — dash punctuation + French; ai-attribution stays on, never disabled`
+            : `commit-msg  commit-message — dash punctuation + AI attribution (never disabled) + French${off.has('commit-language') ? ' (commit-language DISABLED by config)' : ''}`,
         `commit-msg  leak-guard${leakState} — the message text`,
         ...(h.commitMsg ?? []).map((c) => `commit-msg  ${c.id} — ${c.cmd.join(' ')}`),
     ]

package/src/ledger/db.ts

@@ -287,7 +287,7 @@ function migrate(db: Database): void {
 /** give the file back its free pages once more than half of it is free and
  *  that is worth it: a DELETE frees pages for reuse but never shrinks the
  *  file. VACUUM holds the write lock while it runs: a gate that asks then
- *  measures instead of waiting. The daemon's sweep and `check --fix SK023`
+ *  measures instead of waiting. The daemon's sweep and `check --fix stores-under-cap` (house repo)
  *  call it. True when it ran */
 export function compactDb(path: string, o: { minFreeBytes?: number } = {}): boolean {
     const opened = openDb(path, { create: false })

package/src/ledger/gate-checks.ts

@@ -19,9 +19,9 @@ 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 } from '../check.ts'
+import { checkCacheExtra, describeFirst, type TaskDef, type CheckFrom, type CheckEnv } from '../check.ts'
 import { CHECK_TIMEOUT_MS, type RunnableCheck, type CheckBody } from '../core/check-runner.ts'
-import { parseDuration } from '../core/wire.ts'
+import { ttlMsOf } from '../core/wire.ts'
 import { budgetOf } from '../core/budget.ts'
 import { whenOfLegacyCheck, whenOfDisabledSlot, whenOfRule, whenOfTask, whenOfCheck, type WhenDecl } from '../core/when.ts'
 import type { CheckDecl } from './git-key.ts'
@@ -74,6 +74,18 @@ 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) */
@@ -122,6 +134,8 @@ export type CheckRow = {
     /** 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
@@ -154,7 +168,6 @@ function taskBody(t: TaskDef): CheckBody {
     }
 }
 
-const ttlMsOf = (ttl: string | undefined): number => (ttl == null || ttl === '' ? 0 : parseDuration(ttl))
 
 /** the runnable half of a row: everything the runner needs, and nothing it
  *  has to look up again */
@@ -338,13 +351,14 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             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 }, c.budgets),
+            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),
             optIn: false,
             fixable: u.def.fix != null,
             when: w,
             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 }),
@@ -375,7 +389,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             owner: r.owner,
             group: null,
             timeoutMs: null,
-            budgetMs: budgetOf(r.id, undefined, { build: false, cmd: false, world: r.ttl != null }, c.budgets),
+            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),
@@ -419,7 +433,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             owner: rel,
             group: task?.group ?? null,
             timeoutMs: task?.timeoutMs ?? null,
-            budgetMs: budgetOf(d.name, undefined, { build: false, cmd: true, world: d.ttl != null }, c.budgets),
+            budgetMs: budgetOf(d.name, undefined, { build: false, cmd: true, world: d.ttl != null || d.never != null }, c.budgets),
             optIn: false,
             // the reader is a source scanner, so it cannot carry a function
             fixable: false,

package/src/ledger/house-runs.ts

@@ -0,0 +1,43 @@
+// THE HOUSE'S RUNS: what the dock at the bottom of the page draws, every
+// house repo's recent runs side by side on one clock. Each repo is shaped the
+// way its own live view is (live-timeline.ts), so a run looks the same
+// wherever it is drawn, and a repo that ran nothing in the window has no group.
+//
+// Pure, on a clock the caller passes. The reads are the caller's
+// (serve/house-runs.ts), which opens a record only when its files moved.
+import type { LiveRow } from './live-runs.ts'
+import type { InvocationRow, RunRow } from './run-log.ts'
+import type { TimelineInvocation } from './run-timeline.ts'
+import { LIVE_HISTORY_MS, shapeLive, type RunSummary } from './live-timeline.ts'
+
+/** one repo's record, as read for the window */
+export type HouseRecord = { repo: string; live: LiveRow[]; runs: RunRow[]; invocations: InvocationRow[] }
+
+/** one repo that ran something in the window: its runs, newest first, and
+ *  what it has in flight */
+export type HouseGroup = { repo: string; invocations: TimelineInvocation[]; busy: number; runs: RunSummary[] }
+
+export type HouseView = {
+    now: number
+    historyMs: number
+    /** the runner's cap, drawn over the concurrency band */
+    cap: number
+    /** checks in flight across every repo */
+    busy: number
+    /** by repo name, so a group keeps its place from one answer to the next */
+    groups: HouseGroup[]
+    /** what holds the machine's plan back, when the host has one (Planner.held) */
+    held?: string[]
+}
+
+export function shapeHouse(o: { now: number; cap: number; repos: HouseRecord[]; alive?: (pid: number) => boolean; historyMs?: number }): HouseView {
+    const historyMs = o.historyMs ?? LIVE_HISTORY_MS
+    const groups = o.repos
+        .map((r): HouseGroup => {
+            const v = shapeLive({ now: o.now, cap: o.cap, live: r.live, runs: r.runs, invocations: r.invocations, alive: o.alive, historyMs })
+            return { repo: r.repo, invocations: v.invocations, busy: v.busy, runs: v.runs }
+        })
+        .filter((g) => g.invocations.length > 0)
+        .sort((a, b) => a.repo.localeCompare(b.repo))
+    return { now: o.now, historyMs, cap: o.cap, busy: groups.reduce((a, g) => a + g.busy, 0), groups }
+}

package/src/ledger/live-timeline.ts

@@ -1,7 +1,7 @@
-// THE LIVE TIMELINE: what the strip under the hub header draws. The same
+// THE LIVE TIMELINE: one repo's recent runs and its runs in flight. The same
 // shape the runs page reads (ledger/run-timeline.ts), cut to a rolling
-// window that ends now, with the runs still going in it, plus one collapsed
-// lane per OTHER repo that has something in flight.
+// window that ends now, with the runs still going in it. Every house repo's
+// view side by side is the dock at the bottom of the page (house-runs.ts).
 //
 // Pure, on a clock the caller passes, so every rule is pinned on a fake one.
 // A run still in the live table is drawn from there, its running checks
@@ -12,12 +12,9 @@ import { liveRowsOf, type LiveRow, type LiveWait } from './live-runs.ts'
 import type { InvocationRow, RunRow } from './run-log.ts'
 import { invocationsOf, type TimelineBar, type TimelineInvocation } from './run-timeline.ts'
 
-/** how far back the server looks: the unfolded strip's widest window */
+/** how far back the server looks: the widest window a live chart draws */
 export const LIVE_HISTORY_MS = 600_000
 
-/** another repo with something in flight, collapsed to one lane */
-export type RepoLane = { repo: string; label: string; by: string; start: number; running: number; checks: string[] }
-
 /** a run in flight here, for the header's one line */
 export type RunSummary = { runId: string; label: string; by: string; done: number; total: number; reds: number }
 
@@ -31,7 +28,6 @@ export type LiveView = {
     /** every invocation touching the window, newest first, the ones in flight
      *  marked running */
     invocations: TimelineInvocation[]
-    repos: RepoLane[]
     runs: RunSummary[]
     /** of the newest run in flight: checks ready for a slot, and checks
      *  waiting on another one */
@@ -53,15 +49,6 @@ export function invocationOfLive(r: LiveRow, now: number): TimelineInvocation {
     }
 }
 
-/** another repo, collapsed: one lane while it has anything running, from
- *  its earliest running check to now. null when nothing runs there */
-export function repoLane(repo: string, rows: LiveRow[], now: number, alive?: (pid: number) => boolean): RepoLane | null {
-    const going = liveRowsOf(rows, now, alive).filter((r) => r.ended == null && r.running.length > 0)
-    if (going.length === 0) return null
-    const running = going.flatMap((r) => r.running)
-    return { repo, label: going[0]!.label, by: going[0]!.by, start: Math.min(...running.map((c) => c.started)), running: running.length, checks: running.map((c) => c.id) }
-}
-
 export function shapeLive(o: {
     now: number
     cap: number
@@ -69,7 +56,6 @@ export function shapeLive(o: {
     /** the run record's rows that finished inside the window */
     runs: RunRow[]
     invocations: InvocationRow[]
-    others?: { repo: string; rows: LiveRow[] }[]
     alive?: (pid: number) => boolean
     historyMs?: number
 }): LiveView {
@@ -89,7 +75,6 @@ export function shapeLive(o: {
         cap: o.cap,
         busy: inFlight.reduce((a, r) => a + r.running.length, 0),
         invocations,
-        repos: (o.others ?? []).map((x) => repoLane(x.repo, x.rows, o.now, o.alive)).filter((x) => x != null).sort((a, b) => a.repo.localeCompare(b.repo)),
         runs: inFlight.map((r) => ({ runId: r.runId, label: r.label, by: r.by, done: r.done, total: r.total, reds: r.reds })),
         queued: newest?.waiting.filter((w) => w.deps.length === 0).length ?? 0,
         blocked: newest?.waiting.filter((w) => w.deps.length > 0) ?? [],

package/src/ledger/run-log.ts

@@ -266,20 +266,23 @@ export function recordUse(path: string): { count: number; oldest: number | null
     }
 }
 
+type RawInvocation = { runId: string; kind: string; label: string; by: string; narrowed: number; started: number; ended: number }
+
+const INVOCATIONS_SINCE = 'select run_id as runId, kind, label, by, narrowed, started, ended from invocations where ended >= ? order by started asc'
+
+const invocationRow = (r: RawInvocation): InvocationRow => ({
+    runId: String(r.runId), kind: r.kind === 'ci' ? 'ci' : 'check', label: String(r.label),
+    by: r.by === 'hub' || r.by === 'schedule' ? r.by : 'cli', narrowed: Number(r.narrowed) === 1,
+    started: Number(r.started), ended: Number(r.ended),
+})
+
 /** every invocation on record that ended at or after `since`, oldest
  *  first. An unreadable db is none. */
 export function readInvocations(path: string, since = 0): InvocationRow[] {
     const opened = openDb(path, { create: false })
     if (opened == null) return []
     try {
-        const rows = opened.db.query('select run_id as runId, kind, label, by, narrowed, started, ended from invocations where ended >= ? order by started asc').all(since) as {
-            runId: string; kind: string; label: string; by: string; narrowed: number; started: number; ended: number
-        }[]
-        return rows.map((r): InvocationRow => ({
-            runId: String(r.runId), kind: r.kind === 'ci' ? 'ci' : 'check', label: String(r.label),
-            by: r.by === 'hub' || r.by === 'schedule' ? r.by : 'cli', narrowed: Number(r.narrowed) === 1,
-            started: Number(r.started), ended: Number(r.ended),
-        }))
+        return (opened.db.query(INVOCATIONS_SINCE).all(since) as RawInvocation[]).map(invocationRow)
     } catch {
         return []
     } finally {
@@ -339,14 +342,17 @@ export function readLiveReadonly(path: string): LiveRow[] {
 
 /** every check's last outcome in a record, read only, for a hub that shows
  *  ANOTHER repo's gate: `[]` when the record or the table is missing */
-export function readLastStatusReadonly(path: string): { id: string; status: string }[] {
+export function readLastStatusReadonly(path: string): { id: string; status: string; at: number }[]
+/** with `lines`: what each check last printed too, as its raw json */
+export function readLastStatusReadonly(path: string, o: { lines: true }): { id: string; status: string; at: number; lines: string }[]
+export function readLastStatusReadonly(path: string, o: { lines?: boolean } = {}): { id: string; status: string; at: number; lines?: string }[] {
     if (!existsSync(path)) return []
     let db: Database | null = null
     try {
         db = new Database(path, { readonly: true })
         db.exec('pragma busy_timeout = 50')
         if (db.query("select 1 from sqlite_master where type = 'table' and name = 'check_last'").get() == null) return []
-        return db.query('select id, status from check_last').all() as { id: string; status: string }[]
+        return db.query(`select id, status, at${o.lines === true ? ', lines' : ''} from check_last`).all() as { id: string; status: string; at: number; lines?: string }[]
     } catch {
         return []
     } finally {
@@ -389,6 +395,29 @@ export function readRunsSince(path: string, since: number): RunRow[] {
     }
 }
 
+/** what a live chart of ANOTHER repo draws from its record, strictly read
+ *  only and in one open: its live rows, and the runs and invocations that
+ *  finished at or after `since`. A table the record does not have yet is
+ *  none, and so is a record that cannot be opened */
+export function readWindowReadonly(path: string, since: number): { live: LiveRow[]; runs: RunRow[]; invocations: InvocationRow[] } {
+    const out = { live: [] as LiveRow[], runs: [] as RunRow[], invocations: [] as InvocationRow[] }
+    if (!existsSync(path)) return out
+    let db: Database | null = null
+    try {
+        db = new Database(path, { readonly: true })
+        db.exec('pragma busy_timeout = 50')
+        const has = (t: string): boolean => db!.query("select 1 from sqlite_master where type = 'table' and name = ?").get(t) != null
+        if (has('live')) out.live = (db.query(LIVE_SELECT).all() as RawLive[]).map(liveRowOf).filter((r) => r != null)
+        if (has('invocations')) out.invocations = (db.query(INVOCATIONS_SINCE).all(since) as RawInvocation[]).map(invocationRow)
+        if (has('runs') && has('invocations')) out.runs = (db.query(`${RUN_ROWS} where r.at >= ? order by r.at asc, r.rowid asc`).all(since) as RawRow[]).map(runRow)
+        return out
+    } catch {
+        return out
+    } finally {
+        try { db?.close() } catch { /* already gone */ }
+    }
+}
+
 /** every row the record holds, oldest first. A db that cannot be read is no
  *  rows at all: it feeds a dashboard, and an empty history beats a crash. */
 export function readRuns(path: string): RunRow[] {

package/src/ledger/store.ts

@@ -17,6 +17,7 @@
 import type { Database } from 'bun:sqlite'
 import { readdirSync, readFileSync, rmSync, statSync } from 'fs'
 import { join } from 'path'
+import { FOREVER_MS } from '../core/wire.ts'
 import { BUSY_MS, dbPath, openDb, shipkitRoot } from './db.ts'
 
 /** the envelope FORMAT, stored per row. Bumped when the envelope changes, so
@@ -104,6 +105,17 @@ export class Answers {
         this.h = null
     }
 
+    /** the busy timeout sqlite holds on the open handle, in ms: how long its
+     *  last statement could wait on a writer. Null with no handle */
+    busyTimeout(): number | null {
+        try {
+            const r = this.h?.query('pragma busy_timeout').get() as Record<string, number> | null | undefined
+            return r == null ? null : (Object.values(r)[0] ?? null)
+        } catch {
+            return null
+        }
+    }
+
     /** the stored answer, or null when the check must run */
     read<T>(ns: string, name: string, key: string): Stored<T> | null {
         const row = this.with(READ_BUSY_MS, (h) => h.query('select v, at, keeps, payload from answers where ns = ? and name = ? and key = ?').get(ns, name, key) as Row | null)
@@ -137,6 +149,21 @@ export class Answers {
         )
     }
 
+    /** every stored answer of one check, newest first: what adopting an
+     *  answer written under an older key shape reads */
+    readAll<T>(ns: string, name: string): Stored<T>[] {
+        const rows = this.with(READ_BUSY_MS, (h) => h.query('select v, key, at, keeps, payload from answers where ns = ? and name = ? order by at desc').all(ns, name) as (Row & { key: string })[]) ?? []
+        return rows.flatMap((row) => {
+            try {
+                const payload = JSON.parse(row.payload) as T
+                if (Number(row.v) !== STORE_VERSION || typeof row.at !== 'number' || payload == null) return []
+                return [{ v: Number(row.v), key: row.key, at: row.at, keeps: row.keeps ?? undefined, payload }]
+            } catch {
+                return []
+            }
+        })
+    }
+
     drop(ns: string, name: string, key: string): void {
         this.with(BUSY_MS, (h) => h.query('delete from answers where ns = ? and name = ? and key = ?').run(ns, name, key))
     }
@@ -162,8 +189,9 @@ export class Answers {
      *  runs is kept. How many went, null when the db could not be opened. */
     sweep(now: number, o: { keepMs?: number; max?: number } = {}): number | null {
         return this.with(BUSY_MS, (h) => {
-            let n = h.query('delete from answers where used < ?').run(now - (o.keepMs ?? KEEP_MS)).changes
-            n += h.query('delete from answers where rowid in (select rowid from answers order by used desc limit -1 offset ?)').run(o.max ?? MAX_ANSWERS).changes
+            // a forever answer is a decided fact: dropping it re-asks the world
+            let n = h.query('delete from answers where used < ? and coalesce(keeps, 0) < ?').run(now - (o.keepMs ?? KEEP_MS), FOREVER_MS).changes
+            n += h.query('delete from answers where rowid in (select rowid from answers where coalesce(keeps, 0) < ? order by used desc limit -1 offset ?)').run(FOREVER_MS, o.max ?? MAX_ANSWERS).changes
             return n
         })
     }

package/src/ledger/world-cache.ts

@@ -31,15 +31,23 @@
 // A measured negative may be kept only for a check about the WORLD. One about
 // THIS REPO is fixed by a human and the next run goes green, so replaying its
 // red would be the cache lying about work already done.
-import { fmtStamp, type Line } from '../core/wire.ts'
-import { FRESH_ENV, withAnswers } from './store.ts'
-import { CACHED, RAN } from '../core/outcome-words.ts'
+import { FOREVER_MS, type Line, type Stamp } from '../core/wire.ts'
+import { FRESH_ENV, withAnswers, type Answers, type Stored } from './store.ts'
 
 /** the longest a MEASURED NEGATIVE is remembered, whatever TTL was declared.
  *  Long enough to stop a re-ask storm inside one working session, short
  *  enough that the world being fixed is noticed the same day. */
 export const NEGATIVE_TTL_CAP_MS = 60 * 60 * 1000
 
+/** what a world answer is stored under. A timed answer follows the program
+ *  that measured it (toolchain, probe code); a forever one is the declared
+ *  value alone, or a shipkit release would ask every decided fact again */
+export function worldKeyOf(k: { ttlMs: number; toolchain: string; code: string; rotation: string; frozen: boolean | null }): string {
+    const frozen = k.frozen == null ? '' : `\0frozen=${k.frozen}`
+    if (k.ttlMs >= FOREVER_MS) return `forever\0${k.rotation}${frozen}`
+    return `tc=${k.toolchain}\0code=${k.code}\0${k.rotation}${frozen}`
+}
+
 export type WorldCache = {
     /** the repo's db file (ledger/store.ts answersDb) */
     db: string
@@ -54,6 +62,41 @@ export type WorldCache = {
 }
 
 
+const FOREVER_PREFIX = 'forever\0'
+/** the timed key a check wrote before it declared `ttl: 'forever'`:
+ *  `tc=<toolchain>\0code=<code>\0` then the same declared value */
+const TIMED_HEAD = /^tc=[^\0]*\0code=[^\0]*\0/
+
+/** a decided fact with no row under its forever key takes the newest CLEAN
+ *  answer its timed key shape stored for the same declared value, once: the
+ *  value it checks did not move, so the fact is still known. Written under
+ *  the forever key; the timed rows age out with the store's sweep */
+function adoptTimed(a: Answers, ns: string, name: string, key: string): Stored<Line[]> | null {
+    if (!key.startsWith(FOREVER_PREFIX)) return null
+    const rest = key.slice(FOREVER_PREFIX.length)
+    const old = a.readAll<Line[]>(ns, name).find((e) => {
+        const head = TIMED_HEAD.exec(e.key)
+        return head != null && e.key.slice(head[0].length) === rest && Array.isArray(e.payload) && e.payload.length > 0 && e.payload.every((l) => l.kind === 'ok' || l.kind === 'note')
+    })
+    if (old == null) return null
+    const payload = unbake(old.payload)
+    a.write([{ ns, name, key, payload, at: old.at, keeps: FOREVER_MS }], { now: old.at })
+    return { ...old, key, keeps: FOREVER_MS, payload }
+}
+
+/** the times an older build wrote into the first line's text, as `(cached at
+ *  <stamp> until <stamp>)` or `(ran at <stamp>, kept until <stamp>)`: the
+ *  entry holds them as data, so the text drops them */
+const BAKED = / \((?:cached|ran) at \d{4}-\d\d-\d\d \d\d:\d\d:\d\d,? (?:kept )?until [^)]*\)$/
+const unbake = (lines: Line[]): Line[] => lines.map((l, i) => (i === 0 ? { ...l, text: l.text.replace(BAKED, '') } : l))
+
+/** the first line, stamped with when its answer was measured and until when it keeps */
+const stamped = (lines: Line[], stamp: Stamp): Line[] => lines.map((l, i) => (i === 0 ? { ...l, stamp } : l))
+const untilOf = (at: number, keeps: number): number | null => (keeps >= FOREVER_MS ? null : at + keeps)
+
+/** the answer for this key, or the one a forever key adopts */
+const readOrAdopt = (a: Answers, ns: string, name: string, key: string): Stored<Line[]> | null => a.read<Line[]>(ns, name, key) ?? adoptTimed(a, ns, name, key)
+
 /** the stored answer for this exact question, or null when it must be
  *  measured. An entry may keep for LESS than the declared TTL: a measured
  *  negative wrote its own shorter window, so the run after a fix sees the fix
@@ -63,18 +106,16 @@ export function replayWorld(c: WorldCache, name: string, key: string, ttlMs: num
     if (process.env[c.freshEnv ?? FRESH_ENV] != null) return null
     const now = c.now()
     const entry = withAnswers(c.db, (a) => {
-        const e = a.read<Line[]>(c.ns, name, key)
+        const e = readOrAdopt(a, c.ns, name, key)
         if (e != null) a.write([], { touched: [{ ns: c.ns, name, key }], now })
         return e
     })
     if (entry == null || !Array.isArray(entry.payload)) return null
     const keeps = entry.keeps ?? ttlMs
     if (now - entry.at >= keeps || now < entry.at) return null
-    // the stamp was baked in when the answer was MEASURED (below): a replay
-    // prints the stored lines VERBATIM, so the live run and every later replay
-    // render the same string. Annotating replays but not live runs diffed on
-    // every fresh-vs-cached alternation, so neither side annotates.
-    return entry.payload
+    // the times ride as data on the first line, rendered by whoever prints it
+    // against its own clock, so a line read a day later says how old it is
+    return stamped(unbake(entry.payload), { at: entry.at, until: untilOf(entry.at, keeps), cached: true })
 }
 
 export type Measured = {
@@ -88,6 +129,17 @@ export type Measured = {
     keepNegative: boolean
 }
 
+/** is an answer stored for this exact question, without stamping it used:
+ *  what the plan asks of a forever check */
+export function hasWorld(c: WorldCache, name: string, key: string, ttlMs: number): boolean {
+    if (ttlMs <= 0) return false
+    const now = c.now()
+    const entry = withAnswers(c.db, (a) => readOrAdopt(a, c.ns, name, key))
+    if (entry == null || !Array.isArray(entry.payload)) return false
+    const keeps = entry.keeps ?? ttlMs
+    return now - entry.at < keeps && now >= entry.at
+}
+
 /** what a measured answer leaves behind, and the lines to report for it. This
  *  check writes its OWN row and only its own, so a racing runner can lose
  *  nothing. */
@@ -105,9 +157,6 @@ export function rememberWorld(c: WorldCache, name: string, key: string, ttlMs: n
         return m.lines
     }
     const now = c.now()
-    const lines = m.lines.map((l, i): Line =>
-        i === 0 ? { ...l, text: `${l.text} (${m.clean ? `${CACHED} at ${fmtStamp(now)} until` : `${RAN} at ${fmtStamp(now)}, kept until`} ${fmtStamp(now + keepsFor)})` } : l,
-    )
-    withAnswers(c.db, (a) => a.write([{ ns: c.ns, name, key, payload: lines, at: now, keeps: keepsFor }], { now }))
-    return lines
+    withAnswers(c.db, (a) => a.write([{ ns: c.ns, name, key, payload: m.lines, at: now, keeps: keepsFor }], { now }))
+    return stamped(m.lines, { at: now, until: untilOf(now, keepsFor) })
 }

package/src/plan/cadence.ts

@@ -10,15 +10,25 @@ import { parseDuration } from '../core/wire.ts'
 
 export type LastStatus = 'pass' | 'warn' | 'fail' | 'skip'
 
-/** a check's last result on record: its status, when it finished, and how
- *  many runs in a row ended on that same status */
-export type LastResult = { status: LastStatus; at: number; streak: number }
+/** a check's last result on record: its status, when it finished, how many
+ *  runs in a row ended on that same status, and its last MEASURED run (a
+ *  replay costs nothing, so it never counts) */
+export type LastResult = {
+    status: LastStatus
+    at: number
+    streak: number
+    cost?: { at: number; ms: number }
+    /** a decided fact with no answer for its key, whose last run skipped (its
+     *  probe could not answer): it retries on a backoff from `at` */
+    unknown?: boolean
+}
 
 /** what a lambda sees beside the last result */
 export type CadenceState = { active: boolean }
 
 /** a span (`'24h'`), a range (`['10h', '12h']`), a cron expression
- *  (`'0 9 * * 1'`), or null for on change only */
+ *  (`'0 9 * * 1'`), `'once'` (only while it has no answer: what a
+ *  `ttl: 'forever'` reads as), or null for on change only */
 export type EveryValue = string | readonly [string, string] | null
 
 export type Every = EveryValue | ((last: LastResult | null, s: CadenceState) => EveryValue)
@@ -33,6 +43,7 @@ export type PlanDecl = { every?: Every; cron?: string; whenInactive?: WhenInacti
 /** one resolved cadence */
 export type Cadence =
     | { kind: 'change' }
+    | { kind: 'once' }
     | { kind: 'every'; ms: number }
     | { kind: 'range'; min: number; max: number; point: number }
     | { kind: 'cron'; expr: string; cron: Cron }
@@ -40,6 +51,9 @@ export type Cadence =
 /** the cadence a check runs on, and the words saying what chose it */
 export type Resolved = { cadence: Cadence; rule: string; error: string | null }
 
+/** runs while it has no answer, never on a clock */
+export const ONCE = 'once'
+
 const isCron = (s: string): boolean => s.trim().split(/\s+/).length === 5
 
 /** a stable fraction in [0, 1) for one repo and check: the same pair always
@@ -56,6 +70,7 @@ export function stablePoint(seed: string): number {
 /** one value to a cadence, or the reason it is not one */
 export function cadenceOf(v: EveryValue, seed: string): Cadence | string {
     if (v == null) return { kind: 'change' }
+    if (v === ONCE) return { kind: 'once' }
     if (Array.isArray(v)) {
         if (v.length !== 2) return `a range is two spans, as in ['10h', '12h']`
         try {
@@ -99,7 +114,7 @@ export function planDeclProblem(d: PlanDecl): string | null {
     return null
 }
 
-const words = (v: EveryValue): string => (v == null ? 'on change' : Array.isArray(v) ? `every ${v[0]}..${v[1]}` : isCron(v as string) ? `cron ${v}` : `every ${v}`)
+const words = (v: EveryValue): string => (v == null ? 'on change' : v === ONCE ? 'once, while its answer is unknown' : Array.isArray(v) ? `every ${v[0]}..${v[1]}` : isCron(v as string) ? `cron ${v}` : `every ${v}`)
 
 const stateWords = (last: LastResult | null, s: CadenceState): string =>
     `${last == null ? 'never ran' : `last ${last.status} x${last.streak}`}, ${s.active ? 'active' : 'inactive'}`
@@ -151,6 +166,7 @@ export function resolveWhenInactive(d: PlanDecl, last: LastResult | null, s: Cad
  *  for its next slot */
 export function nextDue(c: Cadence, last: number | null, now: number): number | null {
     if (c.kind === 'change') return null
+    if (c.kind === 'once') return last == null ? now : null
     if (c.kind === 'every') return last == null ? now : last + c.ms
     if (c.kind === 'range') return last == null ? now : last + c.point
     return cronNext(c.cron, last ?? now)