rvlib-shipkit 1.2.0 → 1.3.0

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.

package/src/release/unit-resolve.ts

@@ -165,9 +165,7 @@ export function resolveUnits(root: string, config: RepoConfig, io: UnitReader):
             tagTemplate: rc.tag ?? ROOT_TAG,
             changelogRel: rc.changelog ?? 'CHANGELOG.md',
             npm: rc.npm,
-            // the root IS the repo: its package.json private flag is the whole
-            // declaration, and a public root package publishes by default
-            npmWhenUndeclared: 'from-private-flag',
+            undeclaredFix: 'add `release: { npm: true }` to repo.config.ts to publish it',
             githubRelease: rc.githubRelease ?? true,
             tsconfigRel: rc.tsconfig,
             checkFolderName: false,
@@ -204,7 +202,7 @@ export function resolveUnits(root: string, config: RepoConfig, io: UnitReader):
             tagTemplate: decl.tag ?? SUB_TAG,
             changelogRel: decl.changelog ?? `${decl.dir}/CHANGELOG.md`,
             npm: decl.npm,
-            npmWhenUndeclared: 'refuse',
+            undeclaredFix: 'add `npm: true` to this units[] entry to publish it',
             githubRelease: decl.githubRelease ?? false,
             tsconfigRel: decl.tsconfig,
             // only the DEFAULT tag renders the package name into a git tag, so
@@ -226,11 +224,9 @@ function build(p: {
     tagTemplate: string
     changelogRel: string
     npm: boolean | undefined
-    /** how an UNDECLARED npm target resolves. The root IS the repo, so its
-     *  package.json private flag is the whole declaration. A sub-unit has no
-     *  such declaration, so a non-private package with no `npm` key is
-     *  ambiguous and REFUSES. */
-    npmWhenUndeclared: 'from-private-flag' | 'refuse'
+    /** where this unit's npm declaration goes, for the refusal a non-private
+     *  package with no `npm` key gets */
+    undeclaredFix: string
     githubRelease: boolean
     tsconfigRel: string | undefined
     checkFolderName: boolean
@@ -256,10 +252,10 @@ function build(p: {
     // about must refuse, not quietly resolve to no-publish. A silent false
     // here is a lib that bumps, tags and cuts a release while publishing
     // nothing, and the only trace is one note line in a long log.
-    if (p.npm == null && !isPrivate && p.npmWhenUndeclared === 'refuse')
-        errors.push(at('package.json is not private and this units[] entry does not say `npm` — add `npm: true` to publish it, or `private: true` to its package.json to keep it internal'))
+    if (p.npm == null && !isPrivate)
+        errors.push(at(`package.json is not private and no npm target is declared: ${p.undeclaredFix}, or \`private: true\` to its package.json to keep it internal`))
     if (errors.length > 0) return { error: errors }
-    const declaredNpm = p.npm ?? (p.npmWhenUndeclared === 'from-private-flag' && !isPrivate)
+    const declaredNpm = p.npm === true
     const tsconfig = p.tsconfigRel != null ? join(p.root, p.tsconfigRel) : join(p.dir, 'tsconfig.json')
     return {
         unit: {

package/src/repo-config.ts

@@ -185,8 +185,16 @@ export type RepoConfig = {
      *  lint and prints a skip line carrying the reason. `defineRepo` throws on
      *  an unknown id or a blank reason */
     ruleExempt?: Record<string, string>
-    /** declared github visibility INTENT (absent = 'private') — rule SK007
-     *  fails loud when `gh repo view` disagrees in either direction */
+    /** the repo is done for now: nothing processes it. The house discovery
+     *  leaves it out, so it has no rail row, no hub (no file watch, no plan
+     *  rows, no automatic gates), no processes or widgets, no identity fill,
+     *  no activity row, and fleet skips it. Only the archived page lists it.
+     *  The button in the repo header and the page's unarchive toggle it, and
+     *  only this key moves (core/archived.ts) */
+    archived?: boolean
+    /** declared github visibility INTENT (absent = 'private'): public means
+     *  strangers read the tracked tree. What each check does with it:
+     *  wiki/build/shipkit/built-in-checks.md */
     visibility?: 'private' | 'public'
     /** the reviewer agent type this repo declares: `.claude/agents/<name>.md`,
      *  whose system prompt points at `brief` (an md file holding the standing
@@ -287,7 +295,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'budgets', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
 
 const KEBAB = /^[a-z0-9][a-z0-9-]*$/
 const words = (v: unknown): boolean => Array.isArray(v) && v.length > 0 && v.every((w) => typeof w === 'string')

package/src/serve/house-runs.ts

@@ -0,0 +1,53 @@
+// The dock's data on the server: every house repo's record, read for the
+// live window and shaped into one view (ledger/house-runs.ts). One instance
+// serves every page that asks, the home's daemon and a hub serving on its own
+// alike.
+//
+// the one constraint a reader breaks first: this is asked every few seconds
+// while a dock is open, so nothing here may cost a record read when nothing
+// moved. A repo's record is opened only when its db or its write ahead log
+// changed since the last read (the window only slides, and the shaping drops
+// what slid out), and one shaped answer serves every request inside SHARE_MS.
+import { existsSync } from 'fs'
+import { parallelCap } from '../core/parallel.ts'
+import { shapeHouse, type HouseRecord, type HouseView } from '../ledger/house-runs.ts'
+import { LIVE_HISTORY_MS } from '../ledger/live-timeline.ts'
+import { readWindowReadonly } from '../ledger/run-log.ts'
+import { recordOf, recordStamp } from './project-gutter.ts'
+
+/** how long one shaped answer serves every page that asks */
+export const SHARE_MS = 1_000
+
+export type HouseRepo = { name: string; path: string }
+
+export class HouseRuns {
+    private records = new Map<string, { stamp: string; rec: HouseRecord }>()
+    private shaped: { at: number; view: HouseView } | null = null
+    /** records opened since this instance was built: what a test measures */
+    reads = 0
+
+    constructor(private list: () => HouseRepo[], private now: () => number = Date.now, private cap: () => number = parallelCap) {}
+
+    view(): HouseView {
+        const now = this.now()
+        if (this.shaped != null && now - this.shaped.at < SHARE_MS) return this.shaped.view
+        const since = now - LIVE_HISTORY_MS
+        const next = new Map<string, { stamp: string; rec: HouseRecord }>()
+        for (const r of this.list()) {
+            const path = recordOf(r.path)
+            if (path == null || !existsSync(path)) continue
+            const stamp = recordStamp(path)
+            let hit = this.records.get(r.path)
+            if (hit == null || hit.stamp !== stamp) {
+                this.reads++
+                hit = { stamp, rec: { repo: r.name, ...readWindowReadonly(path, since) } }
+            } else if (hit.rec.repo !== r.name) hit = { stamp, rec: { ...hit.rec, repo: r.name } }
+            next.set(r.path, hit)
+        }
+        // a repo gone from the list takes its rows with it
+        this.records = next
+        const view = shapeHouse({ now, cap: this.cap(), repos: [...next.values()].map((x) => x.rec) })
+        this.shaped = { at: now, view }
+        return view
+    }
+}