rvlib-shipkit 1.2.0 → 1.3.0

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 */
@@ -345,6 +358,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             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 }),

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
@@ -137,6 +138,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 +178,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,8 +31,8 @@
 // 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 { FOREVER_MS, fmtStamp, type Line } from '../core/wire.ts'
+import { FRESH_ENV, withAnswers, type Answers, type Stored } from './store.ts'
 import { CACHED, RAN } from '../core/outcome-words.ts'
 
 /** the longest a MEASURED NEGATIVE is remembered, whatever TTL was declared.
@@ -40,6 +40,15 @@ import { CACHED, RAN } from '../core/outcome-words.ts'
  *  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 +63,31 @@ 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 = old.payload.map((l, i): Line => (i !== 0 ? l : { ...l, text: l.text.replace(new RegExp(`\\((${CACHED} at [^)]*?) until [^)]*\\)$`), '($1 until its declaration changes)') }))
+    a.write([{ ns, name, key, payload, at: old.at, keeps: FOREVER_MS }], { now: old.at })
+    return { ...old, key, keeps: FOREVER_MS, payload }
+}
+
+/** 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,7 +97,7 @@ 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
     })
@@ -88,6 +122,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. */
@@ -106,7 +151,9 @@ export function rememberWorld(c: WorldCache, name: string, key: string, ttlMs: n
     }
     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,
+        i !== 0 ? l
+        : keepsFor >= FOREVER_MS ? { ...l, text: `${l.text} (${CACHED} at ${fmtStamp(now)} until its declaration changes)` }
+        : { ...l, text: `${l.text} (${m.clean ? `${CACHED} at ${fmtStamp(now)} until` : `${RAN} at ${fmtStamp(now)}, kept until`} ${fmtStamp(now + keepsFor)})` },
     )
     withAnswers(c.db, (a) => a.write([{ ns: c.ns, name, key, payload: lines, at: now, keeps: keepsFor }], { now }))
     return lines

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)

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
+}