rvlib-shipkit 1.2.0 → 1.4.0

package/src/plan/catch-up.ts

@@ -0,0 +1,37 @@
+// when the plan's catch up window started, kept across restarts in place: work
+// already overdue when the plan starts is spread over CATCH_UP_MS from this
+// start (planner.ts), so a daemon restarted every few minutes never pushes it
+// back into a fresh window.
+//
+// the one constraint a reader breaks first: only a real pause opens a new
+// window. The daemon beats while it runs, and a boot less than
+// CATCH_UP_GAP_MS after the last beat keeps the start it had.
+import { machineGet, machineSet } from '../core/machine-db.ts'
+
+/** a boot this long after the plan's last beat is a pause (a machine asleep,
+ *  pm stopped), and opens a new window. A restart in place takes seconds */
+export const CATCH_UP_GAP_MS = 10 * 60_000
+
+/** how often a running plan says it is alive */
+export const CATCH_UP_BEAT_MS = 60_000
+
+export type CatchUpMark = { start: number; seen: number }
+
+export type CatchUpStore = { get: () => CatchUpMark | null; set: (v: CatchUpMark) => void }
+
+const KEY = 'plan.catch-up'
+
+/** the machine db row (core/machine-db.ts): one per machine, like the plan */
+export const machineCatchUp: CatchUpStore = {
+    get: () => machineGet<CatchUpMark>(KEY),
+    set: (v) => void machineSet(KEY, v),
+}
+
+/** the start of the window this boot belongs to, written back with `now` as
+ *  its last beat */
+export function resumeCatchUp(now: number, store: CatchUpStore): number {
+    const m = store.get()
+    const start = m != null && Number.isFinite(m.start) && Number.isFinite(m.seen) && now - m.seen < CATCH_UP_GAP_MS && m.start <= now ? m.start : now
+    store.set({ start, seen: now })
+    return start
+}

package/src/plan/plan-timeline.ts

@@ -0,0 +1,99 @@
+// the planned page's words, pure: the one timeline (now, next), the checks
+// waiting for their repo to be active, the filter, and every word a row says. The page (planned-st.ts) and `shipkit
+// planned` both draw from these, so the two can never disagree.
+import type { LastStatus } from './cadence.ts'
+import type { PlanReason, PlanRow } from './planner.ts'
+
+export type Section = 'now' | 'next'
+
+/** the section a row sits in; null for a check with no time of its own, and
+ *  for one waiting for its repo to be active: it waits by design, so it is
+ *  counted on one line (waitingWords), never listed as late */
+export function sectionOf(r: PlanRow): Section | null {
+    if (r.state === 'running' || r.state === 'due') return 'now'
+    if (r.state === 'next') return 'next'
+    return null
+}
+
+/** the checks a `wait` rule holds until their repo is active, by repo then check */
+export function waitingRows(rows: PlanRow[], query = ''): PlanRow[] {
+    return rows.filter((r) => r.state === 'late' && matches(r, query)).sort((a, b) => a.repo.localeCompare(b.repo) || a.check.localeCompare(b.check))
+}
+
+/** their one line, or '' when none waits */
+export function waitingWords(rows: PlanRow[], query = ''): string {
+    const w = waitingRows(rows, query)
+    if (w.length === 0) return ''
+    const repos = new Set(w.map((r) => r.repo)).size
+    return `waiting for their repo to be active: ${w.length} check${w.length === 1 ? '' : 's'} in ${repos} repo${repos === 1 ? '' : 's'}`
+}
+
+/** a row matches a text filter when its project or check holds every word
+ *  of it, in any case */
+export function matches(r: PlanRow, query: string): boolean {
+    const words = query.toLowerCase().split(/\s+/).filter((w) => w !== '')
+    const hay = `${r.repo} ${r.check}`.toLowerCase()
+    return words.every((w) => hay.includes(w))
+}
+
+/** the one list: running first, then due, then the next ones soonest
+ *  first. Each row carries its section */
+export function timeline(rows: PlanRow[], query = ''): { section: Section; row: PlanRow }[] {
+    const rank = (r: PlanRow): number => (r.state === 'running' ? 0 : r.state === 'due' ? 1 : 2)
+    return rows
+        .filter((r) => sectionOf(r) != null && matches(r, query))
+        .sort((a, b) => rank(a) - rank(b) || (a.dueAt ?? Infinity) - (b.dueAt ?? Infinity) || a.repo.localeCompare(b.repo) || a.check.localeCompare(b.check))
+        .map((row) => ({ section: sectionOf(row)!, row }))
+}
+
+const MIN = 60_000
+const HOUR = 60 * MIN
+const DAY = 24 * HOUR
+
+/** a span in its largest unit: `<1m`, `25m`, `2h`, `3d` */
+export function spanShort(ms: number): string {
+    if (ms < MIN) return '<1m'
+    if (ms < HOUR) return `${Math.round(ms / MIN)}m`
+    if (ms < DAY) return `${Math.round(ms / HOUR)}h`
+    return `${Math.round(ms / DAY)}d`
+}
+
+/** when the row runs, relative to now: `now`, `in 4m`, or `when active`
+ *  for one waiting for its repo */
+export function whenWords(r: PlanRow, now: number): string {
+    if (r.state === 'late') return 'when active'
+    if (r.dueAt == null || r.state === 'running' || r.state === 'due') return 'now'
+    const d = r.dueAt - now
+    return d > 0 ? `in ${spanShort(d)}` : 'now'
+}
+
+export type Mark = 'running' | 'failed' | 'waiting' | 'due' | 'next'
+
+/** the one mark a row shows and its few words: running wins, then a failed
+ *  last result, then waiting for its repo */
+export function markOf(r: PlanRow): { mark: Mark; words: string } {
+    if (r.state === 'running') return { mark: 'running', words: 'running' }
+    if (r.last?.status === 'fail') return { mark: 'failed', words: 'last failed' }
+    if (r.state === 'late') return { mark: 'waiting', words: 'waits: repo inactive' }
+    if (r.state === 'due') return { mark: 'due', words: 'due' }
+    return { mark: 'next', words: '' }
+}
+
+/** why it is due or planned, in words */
+export const REASON_WORDS: Record<PlanReason, string> = {
+    changed: 'files changed',
+    scheduled: 'scheduled',
+    late: 'waits for its repo to be active',
+    asked: 'asked by hand',
+}
+
+export const reasonWords = (r: PlanRow): string => (r.reason == null ? '' : REASON_WORDS[r.reason])
+
+/** the tone of a last result: red failing, warn warning, ok passing */
+export const LAST_TONE: Record<LastStatus, 'red' | 'warn' | 'ok' | 'dim'> = { fail: 'red', warn: 'warn', pass: 'ok', skip: 'dim' }
+
+/** a title worth showing beside the id: a title that repeats the id loses it */
+export function titleWords(title: string | null, check: string): string | null {
+    const t = title?.startsWith(check) === true ? title.slice(check.length).replace(/^[\s:·]+/, '') : title
+    return t == null || t === '' ? null : t
+}

package/src/plan/planner.ts

@@ -8,6 +8,13 @@
 // calls tick() on its own beat (the daemon's tick, or one interval in a hub of
 // its own), and only the save debounce holds a timer, injected. It decides
 // WHEN, never what is true: every verdict comes from the repo's own runner.
+//
+// what keeps it off the cpu: a save burst is asked about once the repo is
+// quiet (QUIET_MS, or MAX_WAIT_MS into a burst that never stops), a check a
+// save moved waits COST_FACTOR times its last measured run, and nothing it
+// starts on its own starts while the load per core is above LOAD_MAX.
+import { availableParallelism, loadavg } from 'os'
+import { CATCH_UP_BEAT_MS, resumeCatchUp, type CatchUpStore } from './catch-up.ts'
 import { nextDue, resolveCadence, resolveWhenInactive, stablePoint, type EveryValue, type LastResult, type PlanDecl } from './cadence.ts'
 
 export type PlanReason = 'changed' | 'scheduled' | 'late' | 'asked'
@@ -15,6 +22,8 @@ export type PlanReason = 'changed' | 'scheduled' | 'late' | 'asked'
 /** one check as the plan sees it */
 export type PlanCheck = {
     id: string
+    /** the name an operator reads, when the host knows one */
+    title?: string
     plan: PlanDecl
     /** a save can make it due: its answer is keyed on the tree, or it is a
      *  gate check nothing can key */
@@ -34,6 +43,10 @@ export type PlanSource = {
     changed: () => Promise<string[]>
     /** run these checks now, in the background; resolves to the exit code */
     run: (ids: string[], why: PlanReason) => Promise<number>
+    /** at join: did the owner edit something after the repo's last run. A
+     *  yes counts as a save, so a burst a restart in place cut off settles
+     *  and is asked about like any other */
+    pending?: () => Promise<boolean>
 }
 
 export type PlanState = 'running' | 'due' | 'late' | 'next' | 'idle'
@@ -41,6 +54,8 @@ export type PlanState = 'running' | 'due' | 'late' | 'next' | 'idle'
 export type PlanRow = {
     repo: string
     check: string
+    /** the name an operator reads, when the host knows one */
+    title: string | null
     state: PlanState
     /** why it is due or planned, null for a check that waits for a save */
     reason: PlanReason | null
@@ -61,8 +76,32 @@ export type PlanTimers = { set: (fn: () => void, ms: number) => unknown; clear:
 
 const realTimers: PlanTimers = { set: (fn, ms) => setTimeout(fn, ms), clear: (h) => clearTimeout(h as ReturnType<typeof setTimeout>) }
 
-/** how long a save burst must be quiet before the plan asks what it moved */
-export const QUIET_MS = 250
+/** how long a repo must be quiet (no tracked write) before the plan asks
+ *  what a save burst moved: an agent's edit, test, edit loop stays inside it,
+ *  so the loop costs one question and one run */
+export const QUIET_MS = 60_000
+
+/** a repo written to without a pause is still asked this often */
+export const MAX_WAIT_MS = 10 * 60_000
+
+/** a check a save moved runs at most once per this many times its last
+ *  measured run: a 30s suite at most every 10 minutes, a 200ms lint at once */
+export const COST_FACTOR = 20
+
+/** above this 1 minute load average per core, the plan starts nothing on its
+ *  own: every core already has a process waiting for it */
+export const LOAD_MAX = 1
+
+/** the machine's 1 minute load average per core */
+export const machineLoad = (): number => loadavg()[0]! / Math.max(1, availableParallelism())
+
+/** a decided fact whose probe could not answer retries after this, doubled
+ *  per skip in a row, up to ONCE_RETRY_MAX_MS. From its run on record, so a
+ *  restart changes nothing */
+export const ONCE_RETRY_MS = 3_600_000
+export const ONCE_RETRY_MAX_MS = 24 * 3_600_000
+
+export const onceRetry = (streak: number): number => Math.min(ONCE_RETRY_MAX_MS, ONCE_RETRY_MS * 2 ** Math.max(0, Math.min(10, streak - 1)))
 
 /** how often the last results are read again when nothing ran here */
 export const LAST_EVERY_MS = 15_000
@@ -76,6 +115,10 @@ type Repo = {
     lastRead: number
     marks: Map<string, Mark>
     timer: unknown
+    /** when the save burst the timer waits on began */
+    burstAt: number | null
+    /** when that timer fires */
+    settleAt: number | null
     detecting: Promise<void> | null
     again: boolean
     error: string | null
@@ -92,17 +135,30 @@ export class Planner {
     private readonly now: () => number
     private readonly timers: PlanTimers
     private readonly quietMs: number
+    private readonly maxWaitMs: number
+    private readonly load: () => number
+    private readonly cores: number
+    private holdReason: string | null = null
+    private readonly catchUp: CatchUpStore | null
+    private beatAt: number
     /** is this repo active: an agent works in it, VS Code has it open, or it is flagged */
     active: (repo: string) => boolean = () => true
 
-    /** when this plan started: what was overdue then is spread, never fired at once */
+    /** when this plan's catch up window started: what was overdue then is
+     *  spread, never fired at once. With a store, a restart in place keeps
+     *  the window it had (catch-up.ts) */
     private readonly bootAt: number
 
-    constructor(private o: { now?: () => number; timers?: PlanTimers; quietMs?: number; onError?: (repo: string, e: Error) => void } = {}) {
+    constructor(private o: { now?: () => number; timers?: PlanTimers; quietMs?: number; maxWaitMs?: number; load?: () => number; cores?: number; catchUp?: CatchUpStore; onError?: (repo: string, e: Error) => void } = {}) {
         this.now = o.now ?? Date.now
-        this.bootAt = this.now()
+        this.catchUp = o.catchUp ?? null
+        this.bootAt = this.catchUp != null ? resumeCatchUp(this.now(), this.catchUp) : this.now()
+        this.beatAt = this.now()
+        this.cores = o.cores ?? availableParallelism()
         this.timers = o.timers ?? realTimers
         this.quietMs = o.quietMs ?? QUIET_MS
+        this.maxWaitMs = o.maxWaitMs ?? MAX_WAIT_MS
+        this.load = o.load ?? machineLoad
     }
 
     private fail(repo: string, e: unknown): void {
@@ -113,9 +169,14 @@ export class Planner {
     async add(src: PlanSource): Promise<void> {
         const old = this.repos.get(src.repo)
         if (old?.timer != null) this.timers.clear(old.timer)
-        const r: Repo = { src, checks: [], last: {}, lastRead: -Infinity, marks: old?.marks ?? new Map(), timer: null, detecting: null, again: false, error: null }
+        const r: Repo = { src, checks: [], last: {}, lastRead: -Infinity, marks: old?.marks ?? new Map(), timer: null, burstAt: null, settleAt: null, detecting: null, again: false, error: null }
         this.repos.set(src.repo, r)
         await this.reload(src.repo)
+        try {
+            if (this.repos.get(src.repo) === r && (await src.pending?.()) === true) this.touched(src.repo)
+        } catch (e) {
+            this.fail(src.repo, e)
+        }
     }
 
     /** read its checks again, after a config edit */
@@ -142,6 +203,20 @@ export class Planner {
         return this.repos.has(repo)
     }
 
+    /** the check ids a repo declares today; null while the plan does not
+     *  hold them (not loaded, still loading, or its checks failed to load) */
+    declared(repo: string): ReadonlySet<string> | null {
+        const r = this.repos.get(repo)
+        if (r == null || r.error != null || r.checks.length === 0) return null
+        return new Set(r.checks.map((c) => c.id))
+    }
+
+    /** each declared check's title by id, null while `declared` is */
+    titles(repo: string): ReadonlyMap<string, string> | null {
+        if (this.declared(repo) == null) return null
+        return new Map(this.repos.get(repo)!.checks.map((c) => [c.id, c.title ?? c.id]))
+    }
+
     private readLast(r: Repo, force = false): void {
         const now = this.now()
         if (!force && now - r.lastRead < LAST_EVERY_MS) return
@@ -163,13 +238,22 @@ export class Planner {
     }
 
     /** a file moved in this repo: once the burst is quiet, the checks whose
-     *  answer it moved turn `changed` */
+     *  answer it moved turn `changed`. A burst past the wait cap keeps the
+     *  timer it has, so a repo never quiet is still asked */
     touched(repo: string): void {
         const r = this.repos.get(repo)
         if (r == null) return
-        if (r.timer != null) this.timers.clear(r.timer)
+        const now = this.now()
+        r.burstAt ??= now
+        if (r.timer != null) {
+            if (now - r.burstAt >= this.maxWaitMs) return
+            this.timers.clear(r.timer)
+        }
+        r.settleAt = now + this.quietMs
         r.timer = this.timers.set(() => {
             r.timer = null
+            r.burstAt = null
+            r.settleAt = null
             void this.detect(repo)
         }, this.quietMs)
     }
@@ -224,12 +308,20 @@ export class Planner {
         const cad = resolveCadence(c.plan, c.fallback, last, s, `${r.src.repo}\0${c.id}`)
         const wi = resolveWhenInactive(c.plan, last, s)
         const error = cad.error ?? wi.error
-        const base = { repo: r.src.repo, check: c.id, rule: cad.rule, inactive: wi.rule, error, last, active }
+        const base = { repo: r.src.repo, check: c.id, title: c.title ?? null, rule: cad.rule, inactive: wi.rule, error, last, active }
         if (this.running?.repo === r.src.repo && this.running.ids.has(c.id)) return { ...base, state: 'running', reason: null, dueAt: this.running.since }
         if (m.askedAt != null) return { ...base, state: 'due', reason: 'asked', dueAt: m.askedAt }
-        if (m.changedAt != null) return { ...base, state: 'due', reason: 'changed', dueAt: m.changedAt }
+        if (m.changedAt != null) {
+            // a check pays for its own runs: one save cannot run it again
+            // before COST_FACTOR times its last measured run has passed
+            const spaced = last?.cost != null ? last.cost.at + COST_FACTOR * last.cost.ms : -Infinity
+            const at = Math.max(m.changedAt, spaced)
+            return { ...base, state: at > now ? 'next' : 'due', reason: 'changed', dueAt: at }
+        }
         const lastAt = Math.max(last?.at ?? -Infinity, m.attemptAt ?? -Infinity)
-        const raw = nextDue(cad.cadence, Number.isFinite(lastAt) ? lastAt : null, now)
+        // a decided fact that could not answer: its retry comes from its run
+        // on record, never from a boot
+        const raw = cad.cadence.kind === 'once' && last?.unknown === true ? Math.max(last.at + onceRetry(last.streak), m.attemptAt != null ? m.attemptAt + onceRetry(last.streak) : -Infinity) : nextDue(cad.cadence, Number.isFinite(lastAt) ? lastAt : null, now)
         // overdue before the plan started (a machine asleep, a day off): each
         // pair lands at its own stable point of the catch up window
         const due = raw != null && raw < this.bootAt ? this.bootAt + Math.round(stablePoint(`catch up\0${r.src.repo}\0${c.id}`) * CATCH_UP_MS) : raw
@@ -257,6 +349,17 @@ export class Planner {
         return [...this.repos.values()].filter((r) => r.error != null).map((r) => ({ repo: r.src.repo, error: r.error! }))
     }
 
+    /** what holds work back right now, one line each: the repos whose save
+     *  burst is settling, and the load that held the last look */
+    held(): string[] {
+        const now = this.now()
+        const out: string[] = []
+        for (const r of this.repos.values())
+            if (r.settleAt != null) out.push(`settling: ${r.src.repo}, ${Math.max(0, Math.ceil((r.settleAt - now) / 1_000))}s`)
+        if (this.holdReason != null) out.push(this.holdReason)
+        return out
+    }
+
     /** a batch is in flight */
     busy(): boolean {
         return this.running != null
@@ -266,9 +369,23 @@ export class Planner {
      *  runs every row of its that is due, as one background run. Resolves when
      *  that batch is started, never when it ends */
     tick(): { repo: string; ids: string[]; reason: PlanReason } | null {
+        this.beat()
         if (this.running != null) return null
-        const due = this.rows().filter((x) => x.state === 'due')
-        if (due.length === 0) return null
+        let due = this.rows().filter((x) => x.state === 'due')
+        if (due.length === 0) {
+            this.holdReason = null
+            return null
+        }
+        // a loaded machine runs only what someone asked for
+        const load = this.load()
+        if (load > LOAD_MAX) {
+            due = due.filter((x) => x.reason === 'asked')
+            if (due.length === 0) {
+                this.holdReason = `held: load ${(load * this.cores).toFixed(1)} on ${this.cores} cores`
+                return null
+            }
+        }
+        this.holdReason = null
         due.sort((a, b) => ORDER[a.reason!] - ORDER[b.reason!] || (a.dueAt ?? 0) - (b.dueAt ?? 0))
         const first = due[0]!
         const r = this.repos.get(first.repo)!
@@ -292,6 +409,14 @@ export class Planner {
         return { repo: first.repo, ids, reason: first.reason! }
     }
 
+    /** the catch up window's last beat, at most once a minute */
+    private beat(): void {
+        const now = this.now()
+        if (this.catchUp == null || now - this.beatAt < CATCH_UP_BEAT_MS) return
+        this.beatAt = now
+        this.catchUp.set({ start: this.bootAt, seen: now })
+    }
+
     /** resolves once no batch is in flight */
     async idle(): Promise<void> {
         while (this.running != null) await new Promise((res) => setTimeout(res, 5))

package/src/plan/repo-source.ts

@@ -9,9 +9,15 @@
 // save elsewhere never re-runs it.
 import { gateInventory, type CheckRow } from '../ledger/gate-checks.ts'
 import { Ledger } from '../ledger/ledger.ts'
+import { answersDb } from '../ledger/store.ts'
+import { hasWorld, worldKeyOf, type WorldCache } from '../ledger/world-cache.ts'
+import { FOREVER, FOREVER_MS } from '../core/wire.ts'
+import { ONCE, type LastResult } from './cadence.ts'
+import { openDb } from '../ledger/db.ts'
 import { readLastResults } from '../ledger/run-log.ts'
 import { gateBinary } from '../ledger/toolchain-identity.ts'
 import { populationOf } from '../problems/problem-line.ts'
+import { movedSince } from '../serve/tracked-watch.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { PlanCheck, PlanReason, PlanSource } from './planner.ts'
 
@@ -19,30 +25,100 @@ import type { PlanCheck, PlanReason, PlanSource } from './planner.ts'
  *  check, an off one and an opt in build step wait for whoever names them */
 export function plannable(row: CheckRow): boolean {
     if (row.when.at !== 'always' && row.when.at !== 'health') return false
+    // nothing to do in this repo on a clock (check.ts planOff)
+    if (row.planOff != null) return false
     if (row.optIn) return false
     return !(row.build && row.when.at === 'health')
 }
 
-/** one inventory row as a plan check. A world check keeps its ttl as its
- *  cadence; a build step waits for a save; any other check with no cadence
- *  runs about once a day, at its own stable point of a 20h to 28h range, so
- *  checks never fire together */
-/** a check that declares no cadence runs about once a day, never in step */
+/** a REPO check nothing can key and that declares no cadence runs about
+ *  once a day, never in step, until it declares what it depends on. No
+ *  built-in may land here (tests/plan-default-range.test.ts) */
 const DEFAULT_EVERY: [string, string] = ['20h', '28h']
 
+/** why the plan cannot tell when this check's answer moves, or null when it
+ *  can: a key, a ttl, a build step or a declared cadence says it */
+export function planGap(row: CheckRow): string | null {
+    const pop = populationOf(row.decl)
+    if (pop === 'content' || pop === 'reads' || pop === 'world' || row.build) return null
+    if (row.plan?.every !== undefined || row.plan?.cron != null) return null
+    const why = row.decl.never != null && row.decl.never !== '' ? `never cached (${row.decl.never})` : (row.decl.uncacheable ?? 'declares neither inputs nor ttl')
+    return `${why}, and no every: nothing says when its answer moves`
+}
+
+/** one inventory row as a plan check. A world check keeps its ttl as its
+ *  cadence; a build step and a check keyed on its files wait for a save (its
+ *  answer replays until a file moves, so a clock re-asks nothing); a repo
+ *  check with no cadence runs at its own stable point of the default range,
+ *  and a built-in with none waits for a save and shows on the burn-down */
 export function planCheckOf(row: CheckRow): PlanCheck {
     const pop = populationOf(row.decl)
     const keyed = pop === 'content' || pop === 'reads'
     const ttl = row.decl.ttl != null && row.decl.ttl !== '' ? row.decl.ttl : null
-    const fallback = ttl != null ? { value: ttl, why: 'its ttl' } : row.build ? { value: null, why: 'a build step' } : { value: DEFAULT_EVERY, why: 'the default range' }
+    const fallback =
+        ttl === FOREVER ? { value: ONCE, why: 'a decided fact: ttl forever' }
+        : ttl != null ? { value: ttl, why: 'its ttl' }
+        : row.build ? { value: null, why: 'a build step' }
+        : keyed ? { value: null, why: 'keyed on its files' }
+        : row.from === 'repo' ? { value: DEFAULT_EVERY, why: 'the default range' }
+        : { value: null, why: 'a built-in declaring nothing, see shipkit keys --burn-down' }
+    // a gate check nothing can key waits for a save only when no cadence
+    // says when to run it: a range or an every it declares is the rule
+    const clocked = fallback.value != null || row.plan?.every !== undefined || row.plan?.cron != null
     return {
         id: row.decl.id,
+        title: row.title,
         plan: row.plan ?? {},
-        onChange: pop !== 'world' && (keyed || row.gate),
+        // a decided fact is keyed on its declaration, so a save can move it
+        onChange: isForever(row) || (pop !== 'world' && (keyed || (row.gate && !clocked))),
         fallback,
     }
 }
 
+const isForever = (row: CheckRow): boolean => row.decl.ttl === FOREVER
+
+/** the key a decided fact's answer is stored under: its declared value */
+const factKey = (r: CheckRow): string => worldKeyOf({ ttlMs: FOREVER_MS, toolchain: '', code: '', rotation: r.decl.extra ?? '', frozen: r.decl.writes === true ? false : null })
+
+/** a decided fact with no answer stored for its current key: its declaration
+ *  moved, it never ran, or the db was lost. The plan runs these once */
+export function unknownFacts(rows: CheckRow[], cache: WorldCache): Set<string> {
+    const out = new Set<string>()
+    for (const r of rows) if (isForever(r) && !hasWorld(cache, r.decl.id, factKey(r), FOREVER_MS)) out.add(r.decl.id)
+    return out
+}
+
+/** each check's last MEASURED run from the record: when it finished and how
+ *  long it took. A replayed run is left out, it cost nothing */
+export function readLastCosts(path: string): Record<string, { at: number; ms: number }> {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return {}
+    const out: Record<string, { at: number; ms: number }> = {}
+    try {
+        const rows = opened.db.query(`select id, max(at) as at, ms from runs where replayed = 0 group by id`).all() as { id: string; at: number; ms: number }[]
+        for (const r of rows) out[r.id] = { at: Number(r.at), ms: Number(r.ms) }
+    } catch {
+        return {}
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+    return out
+}
+
+/** when the latest run on record started, whoever ran it, or null */
+export function lastStarted(path: string): number | null {
+    const opened = openDb(path, { create: false })
+    if (opened == null) return null
+    try {
+        const r = opened.db.query('select max(started) as at from invocations').get() as { at: number | null } | null
+        return r?.at == null ? null : Number(r.at)
+    } catch {
+        return null
+    } finally {
+        try { opened.db.close() } catch { /* already gone */ }
+    }
+}
+
 export type RepoSourceDeps = {
     repo: string
     root: string
@@ -59,13 +135,38 @@ export function repoSource(d: RepoSourceDeps): PlanSource {
     /** the content key each check had at the last question, so a red one
      *  counts as changed only when its key moves */
     const seen = new Map<string, string>()
+    /** the decided facts with no answer for their key, asked again at every
+     *  load and save: their last result counts as none, so they are due */
+    let unknown = new Set<string>()
+    /** the decided facts whose declaration moved since the last load */
+    const moved = new Set<string>()
+    const facts = new Map<string, string>()
+    const cache = (): WorldCache => ({ db: answersDb(d.root), ns: d.config().name, now: Date.now })
     return {
         repo: d.repo,
         checks: async () => {
             rows = (await gateInventory(d.root, d.config(), { tier: 'quick' })).filter(plannable)
+            unknown = rows.some(isForever) ? unknownFacts(rows, cache()) : new Set()
+            for (const r of rows.filter(isForever)) {
+                const k = factKey(r)
+                const before = facts.get(r.decl.id)
+                if (before != null && before !== k) moved.add(r.decl.id)
+                facts.set(r.decl.id, k)
+            }
             return rows.map(planCheckOf)
         },
-        last: () => (d.record === '' ? {} : readLastResults(d.record)),
+        last: () => {
+            const all: Record<string, LastResult> = d.record === '' ? {} : readLastResults(d.record)
+            // a fact with no answer runs; one whose probe could not answer
+            // retries on a backoff from its skip, never at each boot
+            for (const id of unknown) {
+                if (all[id]?.status === 'skip') all[id] = { ...all[id]!, unknown: true }
+                else delete all[id]
+            }
+            const costs = d.record === '' ? {} : readLastCosts(d.record)
+            for (const [id, cost] of Object.entries(costs)) if (all[id] != null) all[id] = { ...all[id]!, cost }
+            return all
+        },
         changed: async () => {
             const decls = rows.map((r) => r.decl)
             if (decls.length === 0) return []
@@ -74,6 +175,13 @@ export function repoSource(d: RepoSourceDeps): PlanSource {
             for (const r of rows) {
                 const c = planCheckOf(r)
                 if (!c.onChange) continue
+                if (isForever(r)) {
+                    // only an edited declaration: a probe that could not answer
+                    // (gh down) must not run again at every save
+                    if (moved.has(c.id) && unknown.has(c.id)) out.push(c.id)
+                    moved.delete(c.id)
+                    continue
+                }
                 const k = ledger.layer.keyFor(c.id)
                 if (k.key == null) {
                     out.push(c.id)
@@ -87,6 +195,10 @@ export function repoSource(d: RepoSourceDeps): PlanSource {
             }
             return out
         },
+        pending: async () => {
+            const since = d.record === '' ? null : lastStarted(d.record)
+            return since != null && (await movedSince(d.root, since))
+        },
         run: async (ids, why) => {
             const byId = new Map(rows.map((r) => [r.decl.id, r]))
             const gate = ids.filter((id) => byId.get(id)?.gate === true)

package/src/release/run-release.ts

@@ -27,8 +27,11 @@ export type ReleaseConfig = {
     tag?: string
     /** the ROOT unit's versioned changelog (default 'CHANGELOG.md') */
     changelog?: string
-    /** publish the ROOT unit to npm. Default: its package.json is not private.
-     *  A private package NEVER publishes, whatever this says. */
+    /** publish the ROOT unit to npm, declared and never inferred: a root whose
+     *  package.json is not private refuses to release until this says true or
+     *  false. A private package NEVER publishes, whatever this says. True makes
+     *  the root package.json a public contract. What each check does with it:
+     *  wiki/build/shipkit/built-in-checks.md */
     npm?: boolean
     /** argv printing an npm auth token on stdout, as in a secret-manager read.
      *  Absent = rely on ambient npm auth. Never put a token in config.
@@ -122,6 +125,10 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
         // real repositories) are exactly the ones a publish must not be wrong
         // about. Publishing behind a partial suite is a green nobody measured.
         tests: 'full',
+        // a release log is read once and kept as evidence: the tier it asked
+        // for, the cache reads it refused and the units it left to their own
+        // release are all part of what it proves
+        verbose: true,
         // a check that cannot block cannot change the outcome, so a release
         // never probes the world: publishing a lib does not depend on whether
         // a DNS provider answers, and asking spends an API call per publish.