rvlib-shipkit 1.3.0 → 1.5.0

package/src/home/pm.ts

@@ -27,6 +27,10 @@ export type ChildView = ProcView & { tail: string[] }
 /** where pm, the daemon and the web listen */
 export type CorePorts = { pm: number; daemon: number; web: number }
 
+/** a child whose pid lives but has not answered for this long is hung and
+ *  gets killed: a healthy daemon answers within about 20 s of its start */
+export const CHILD_HANG_MS = 90_000
+
 /** how many log lines each of shipkit's own processes hands the page */
 const CORE_TAIL = 20
 
@@ -61,6 +65,8 @@ export type PmDeps = {
     /** runs a stop or restart of the web once its answer is out: the web
      *  proxies that very request (default: 200 ms later) */
     later?: (f: () => void) => void
+    /** where pm says what it did on its own, a hung child killed */
+    say?: (line: string) => void
 }
 
 const WEB_ANSWER_MS = 200
@@ -79,6 +85,8 @@ export class Pm {
             probe: () => d.probe(role),
             // a crash loop while its code is being edited heals itself
             neverGiveUp: true,
+            hangMs: CHILD_HANG_MS,
+            say: d.say,
         }, d.deps ?? realDeps)]))
     }
 
@@ -154,9 +162,9 @@ export class Pm {
             if (act === 'start') report(r.set('up'))
             else if (act === 'stop') report(r.set('down'))
             else if (act === 'restart') report(r.restart())
-            else if (act === 'open' || act === 'app') {
+            else if (act === 'open' || act === 'chrome' || act === 'app') {
                 if (r.decl.url == null) return new Response(`${r.decl.id} declares no url to open`, { status: 400 })
-                report(r.open(act === 'app' ? 'app' : 'browser'))
+                report(r.open(act === 'open' ? 'browser' : act))
             } else if (act === 'takeover') {
                 const v = r.takeOverView
                 if (v == null) return new Response(`${r.decl.id} does not run outside the supervisor: nothing to take over`, { status: 409 })
@@ -166,7 +174,7 @@ export class Pm {
                 if (!r.decl.actions.some((a) => a.id === b.action)) return new Response(`${r.decl.id} declares no action '${String(b.action)}'`, { status: 404 })
                 if (r.running != null) return new Response(`${r.decl.id} is already running its action '${r.running}'`, { status: 409 })
                 report(r.action(String(b.action)))
-            } else return new Response('act must be start, stop, restart, open, app, takeover or action', { status: 400 })
+            } else return new Response('act must be start, stop, restart, open, chrome, app, takeover or action', { status: 400 })
             return Response.json(r.view())
         }
         return new Response('not found', { status: 404 })

package/src/home/process-rows.ts

@@ -9,8 +9,9 @@ import type { CorePorts, PmAnswer } from './pm.ts'
 import type { ProcessIcon, ResourceView } from './resources.ts'
 import type { ProcStatus } from './supervise.ts'
 
-/** a status as pm reports it, or unknown while pm does not answer */
-export type RowStatus = ProcStatus | 'unknown'
+/** a status as pm reports it, unknown while pm does not answer, silent
+ *  while pm runs it but the page gets no answer from it */
+export type RowStatus = ProcStatus | 'unknown' | 'silent'
 
 /** the dot a row wears: green up, red crashed, grey stopped or unknown, orange on its way */
 export type RowDot = 'up' | 'crashed' | 'down' | 'starting' | 'unknown'
@@ -46,6 +47,8 @@ export type ProcessRow = {
     actions: { id: string; label: string }[]
     running: string | null
     icon: ProcessIcon | null
+    /** its own app is being built or opened */
+    appBusy: boolean
 }
 
 /** a repo's processes, or shipkit's own (`core`, always the first group) */
@@ -55,7 +58,7 @@ export type ProcessGroup = { repo: string; core?: true; rows: ProcessRow[] }
 export const CORE_GROUP = 'shipkit'
 
 export const dotOf = (s: RowStatus): RowDot =>
-    s === 'up' ? 'up' : s === 'crashed' ? 'crashed' : s === 'starting' || s === 'stopping' ? 'starting' : s === 'down' ? 'down' : 'unknown'
+    s === 'up' ? 'up' : s === 'crashed' || s === 'silent' ? 'crashed' : s === 'starting' || s === 'stopping' ? 'starting' : s === 'down' ? 'down' : 'unknown'
 
 const hostOf = (url: string | null): string | null => (url == null ? null : url.replace(/^https?:\/\//, '').replace(/\/$/, ''))
 
@@ -85,6 +88,7 @@ export function rowOf(r: ResourceView): ProcessRow {
         actions: r.actions,
         running: r.running,
         icon: r.icon,
+        appBusy: r.appBusy === true,
     }
 }
 
@@ -113,6 +117,7 @@ export function declaredRow(d: GlobalProcessDecl): ProcessRow {
         takeOver: null,
         actions: d.actions.map((a) => ({ id: a.id, label: a.label })),
         running: null,
+        appBusy: false,
         // an image is pm's to serve, and pm does not answer
         icon: d.icon == null || /\.[a-z0-9]+$/i.test(d.icon) ? null : { text: d.icon },
     }
@@ -143,6 +148,10 @@ export type CoreOpts = {
     daemonVersion?: string | null
     /** where each listens, when pm does not say (an older pm, or pm down) */
     ports?: CorePorts | null
+    /** one of shipkit's own not answering the page, and why: its row says
+     *  no answer whatever pm last reported. pm silent, every other row is
+     *  the last answer's with its state unknown, so the table keeps its lines */
+    silent?: Partial<Record<'pm' | 'daemon' | 'web', string>>
 }
 
 function coreRow(id: 'pm' | 'daemon' | 'web', o: { status: RowStatus; pid: number | null; since: number | null; note: string | null; tail: string[]; version: string | null; port: number | null; restart: boolean }): ProcessRow {
@@ -150,7 +159,7 @@ function coreRow(id: 'pm' | 'daemon' | 'web', o: { status: RowStatus; pid: numbe
     return {
         id, label: id, repo: CORE_GROUP, file: '', status: o.status, dot: dotOf(o.status), url, host: hostOf(url), pid: o.pid, since: o.since, note: o.note,
         description: CORE_ABOUT[id], where: null, lastLog: o.tail.at(-1) ?? null, tail: o.tail,
-        canStop: false, canRestart: o.restart, core: true, version: o.version, takeOver: null, actions: [], running: null, icon: null,
+        canStop: false, canRestart: o.restart, core: true, version: o.version, takeOver: null, actions: [], running: null, icon: null, appBusy: false,
     }
 }
 
@@ -171,13 +180,20 @@ export function coreGroup(pm: PmAnswer | null, o: CoreOpts = {}): ProcessGroup {
             rows.push(coreRow(id, { status: c.status, pid: c.pid, since: c.since, note: note === '' ? null : note, tail: c.tail, version, port, restart: true }))
         }
     }
-    return { repo: CORE_GROUP, core: true, rows }
+    const s = o.silent ?? {}
+    return { repo: CORE_GROUP, core: true, rows: rows.map((r) => {
+        const why = s[r.id as 'pm' | 'daemon' | 'web']
+        return why != null && why !== '' ? { ...r, status: 'silent', dot: 'crashed', note: why } : s.pm ? stale(r) : r
+    }) }
 }
 
 /** what the page's table holds, from pm's answer: the core group, then the
  *  global processes by repo */
 export const processGroups = (pm: PmAnswer | null, order: string[], o: CoreOpts = {}): ProcessGroup[] =>
-    [coreGroup(pm, o), ...groupRows((pm?.resources ?? []).map(rowOf), order)]
+    [coreGroup(pm, o), ...groupRows((pm?.resources ?? []).map((r) => (o.silent?.pm ? stale(rowOf(r)) : rowOf(r))), order)]
+
+/** a row from an answer pm can no longer confirm: its state unknown, nothing to click */
+const stale = (r: ProcessRow): ProcessRow => ({ ...r, status: 'unknown', dot: 'unknown', canStop: false, canRestart: false, takeOver: null, running: null, appBusy: false })
 
 /** the declared icon, else the repo's own, else none */
 export const processIcon = (r: { icon: ProcessIcon | null }, repoIcon: string | null): ProcessIcon | null =>
@@ -200,6 +216,7 @@ export function stateWords(r: Pick<ProcessRow, 'status' | 'since'>, now: number)
         case 'crashed': return age == null ? 'crashed' : `crashed ${age} ago`
         case 'down': return 'stopped'
         case 'unknown': return 'unknown (pm down)'
+        case 'silent': return 'no answer'
         default: return r.status
     }
 }

package/src/home/resources.ts

@@ -1,14 +1,15 @@
 // the machine's global processes (ComfyUI, a TTS server, an app panel), each
 // declared once in a repo's `<name>.shipkit.ts` as `globalProcess({...})`
 // (shipkit-files.ts) and owned by pm: a switch, a restart, its log, its
-// action buttons, and its url opened in the default browser or as a shipkit
-// app window.
+// action buttons, and its url opened in the default browser, in Chrome, or
+// as its own app (home/gui-app.ts builds that app in its repo on first use).
 //
 // two kinds: with no `down`, the command IS the service, supervised like a
 // hub (restarted on a crash, signalled on stop). With `down`, the command is
 // a bring-up that exits (an idempotent ladder script), `down` its reverse,
 // and the probe is the only truth.
-import { mkdirSync, openSync, closeSync } from 'fs'
+import { closeSync, existsSync, mkdirSync, openSync } from 'fs'
+import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import type { GlobalProcessDecl } from './global-units.ts'
@@ -47,8 +48,14 @@ export type ResourceView = {
     actions: { id: string; label: string }[]
     /** the action running now, or null */
     running: string | null
+    /** its own app is being built or opened: the page shows a spinner on
+     *  that button. Absent from an older pm */
+    appBusy?: boolean
 }
 
+/** where a url opens: the default browser, Chrome, or the process's own app */
+export type OpenHow = 'browser' | 'chrome' | 'app'
+
 /** an emoji, or the url pm serves a declared image file at */
 export type ProcessIcon = { text: string } | { src: string }
 
@@ -83,17 +90,19 @@ export const runOnce: RunOnce = async (cmd, cwd, log) => {
     }
 }
 
-/** opens a shipkit app window on a url; what it did lands in the log */
-export type OpenApp = (url: string, log: string) => void
+/** opens a process's own app, building it first when it is missing or
+ *  stale; what it did lands in the log. Resolves with the exit code */
+export type OpenApp = (d: GlobalProcessDecl, log: string) => Promise<number>
 
 /** its own process: what building the app needs never loads in pm */
 const OPEN_APP = fileURLToPath(new URL('./open-app.ts', import.meta.url))
 
-const openApp: OpenApp = (url, log) => {
+const openApp: OpenApp = async (d, log) => {
     mkdirSync(dirname(log), { recursive: true })
     const fd = openSync(log, 'a')
     try {
-        Bun.spawn([process.execPath, OPEN_APP, url], { stdio: ['ignore', fd, fd] })
+        const spec = { id: d.id, label: d.label, url: d.url, icon: d.icon, root: d.root }
+        return await Bun.spawn([process.execPath, OPEN_APP, '--process', JSON.stringify(spec)], { stdio: ['ignore', fd, fd] }).exited
     } finally {
         closeSync(fd)
     }
@@ -113,6 +122,26 @@ const browse: Browse = (url, log) => {
     }
 }
 
+const CHROME_APPS = ['/Applications/Google Chrome.app', join(homedir(), 'Applications', 'Google Chrome.app')]
+
+/** the command that opens a url in Chrome, else in the default browser */
+export function chromeCmd(url: string, o: { platform?: string; has?: (path: string) => boolean } = {}): string[] {
+    const platform = o.platform ?? process.platform
+    const has = o.has ?? existsSync
+    if (platform === 'darwin') return CHROME_APPS.some(has) ? ['open', '-a', 'Google Chrome', url] : ['open', url]
+    return platform === 'win32' ? ['cmd', '/c', 'start', 'chrome', url] : ['xdg-open', url]
+}
+
+const chrome: Browse = (url, log) => {
+    mkdirSync(dirname(log), { recursive: true })
+    const fd = openSync(log, 'a')
+    try {
+        Bun.spawn(chromeCmd(url), { stdio: ['ignore', fd, fd] })
+    } finally {
+        closeSync(fd)
+    }
+}
+
 /** the function action runner: imports the unit file, calls the action */
 const ACTION_RUNNER = fileURLToPath(new URL('./run-unit-action.ts', import.meta.url))
 
@@ -120,10 +149,12 @@ export type ResourceOpts = {
     probe?: HttpProbe
     run?: RunOnce
     deps?: SuperviseDeps
-    /** the app window */
+    /** the process's own app */
     open?: OpenApp
     /** the default browser */
     browse?: Browse
+    /** Chrome */
+    chrome?: Browse
     /** the pids listening on a local port, and the process group of a pid */
     holders?: (port: number) => number[]
     groupOf?: (pid: number) => number | null
@@ -150,8 +181,10 @@ export class Resource {
     private busy = false
     /** the last bring-up exited non zero */
     private failed = false
-    /** open it once it answers: in the default browser, or as an app window */
-    private openWhenUp: 'browser' | 'app' | null = null
+    /** open it once it answers */
+    private openWhenUp: OpenHow | null = null
+    /** its own app is being built or opened */
+    appBusy = false
     /** the status a tick last saw, and since when, for the bring-up kind */
     private seen: ProcStatus = 'down'
     private seenAt: number
@@ -248,9 +281,9 @@ export class Resource {
         await this.set('up')
     }
 
-    /** its url in the default browser, or as a shipkit app window: at once
+    /** its url in the default browser, in Chrome, or as its own app: at once
      *  while it answers, else it starts and opens once it does */
-    async open(how: 'browser' | 'app'): Promise<void> {
+    async open(how: OpenHow): Promise<void> {
         if (this.decl.url == null) throw new Error(`${this.decl.id} declares no url to open`)
         if (this.status === 'up') {
             this.show(how, this.decl.url)
@@ -260,9 +293,27 @@ export class Resource {
         await this.set('up')
     }
 
-    private show(how: 'browser' | 'app', url: string): void {
-        if (how === 'app') (this.o.open ?? openApp)(url, this.log)
-        else (this.o.browse ?? browse)(url, this.log)
+    private show(how: OpenHow, url: string): void {
+        if (how === 'browser') (this.o.browse ?? browse)(url, this.log)
+        else if (how === 'chrome') (this.o.chrome ?? chrome)(url, this.log)
+        else if (!this.appBusy) void this.showApp()
+    }
+
+    /** off the request path: the build takes seconds the first time, and
+     *  the page follows `appBusy` on its poll */
+    private async showApp(): Promise<void> {
+        this.appBusy = true
+        let failed: string | null = null
+        try {
+            const code = await (this.o.open ?? openApp)(this.decl, this.log)
+            if (code !== 0) failed = `opening ${this.decl.label} as an app exited ${code}: see the log`
+        } catch (e) {
+            failed = `opening ${this.decl.label} as an app: ${(e as Error).message}`
+        } finally {
+            this.appBusy = false
+        }
+        // kept beside what the supervisor says, like an action's outcome
+        if (failed != null) this.note = this.actionNote = failed
     }
 
     /** one declared button. A function action runs in its own bun process
@@ -328,6 +379,7 @@ export class Resource {
             icon: processIconOf(d),
             actions: d.actions.map((a) => ({ id: a.id, label: a.label })),
             running: this.running,
+            appBusy: this.appBusy,
         }
     }
 }

package/src/home/run-daemon.ts

@@ -23,6 +23,7 @@ import { Planner } from '../plan/planner.ts'
 import { machineCatchUp } from '../plan/catch-up.ts'
 import { serveDaemon } from './serve-daemon.ts'
 import { startSweeps } from './machine-stores.ts'
+import { landMotherhome } from '../core/motherhome.ts'
 import { Widgets } from './widgets.ts'
 
 const CLI = fileURLToPath(new URL('../cli.ts', import.meta.url))
@@ -109,7 +110,11 @@ export async function runDaemon(root: string, io: HomeIo, o: { port?: number } =
         // nothing grows unbound: every store of every repo it loads, and the
         // machine's, swept on boot and hourly (core/retention.ts)
         const only = onlyRepos()
-        const sweeps = startSweeps({ roots: () => house.repos.filter((r) => only == null || only.has(r.name)).map((r) => r.path), dir, printErr: io.printErr })
+        const sweeps = startSweeps({
+            roots: () => house.repos.filter((r) => only == null || only.has(r.name)).map((r) => r.path), dir, printErr: io.printErr,
+            // the rows every gate filed land here, one commit a day at most
+            also: (now) => { for (const n of landMotherhome({ now })) io.printErr(n) },
+        })
         const code = reloadOnOwnCode({ role: 'daemon', entry: fileURLToPath(import.meta.url), busy: () => hubs.busy(), before: () => { sweeps.stop(); home.stop() }, io })
         io.print(`  ${house.repos.length} repos, state in ${dir}, reloads on ${code.files} lib files`)
         for (const sig of ['SIGINT', 'SIGTERM'] as const)

package/src/home/run-pm.ts

@@ -11,16 +11,37 @@ import { reloadOnOwnCode } from './lib-watch.ts'
 import { Pm, PM_TICK_MS, type Role } from './pm.ts'
 import { Resources } from './resources.ts'
 import type { HomeIo } from './run-daemon.ts'
-import type { PmConfig } from './pm-config.ts'
+import { stampOf, type PmConfig } from './pm-inputs.ts'
 
 const CLI = fileURLToPath(new URL('../cli.ts', import.meta.url))
 const PM_CONFIG = fileURLToPath(new URL('./pm-config.ts', import.meta.url))
 
 const RUN_PM = fileURLToPath(import.meta.url)
 
-/** how often pm reads the house repos' global processes again */
+/** how often pm stats what its last read of the house side saw */
 export const PM_RESCAN_MS = 15_000
 
+/** pm's reread of the house side: the child runs again only once a stat of
+ *  a path the last answer read moved. A few ms of stats per poll, against a
+ *  child that imports every unit file */
+export class PmConfigWatch {
+    private last: PmConfig | null = null
+
+    constructor(private readonly read: () => Promise<PmConfig>) {}
+
+    seed(c: PmConfig): void {
+        this.last = c
+    }
+
+    /** the new answer, or null when nothing it read moved */
+    async poll(): Promise<PmConfig | null> {
+        if (this.last != null && stampOf(this.last.inputs) === this.last.stamp) return null
+        const c = await this.read()
+        this.last = c
+        return c
+    }
+}
+
 /** replace this process's image with pm run from this file: same pid, same
  *  cwd, same env, none of cli.ts loaded. False when the runtime has no
  *  execve, and the caller runs pm in process */
@@ -79,6 +100,7 @@ export async function runPm(root: string, io: HomeIo, o: { port?: number } = {})
         cmd: (role) => [process.execPath, CLI, role],
         probe: roleAnswers,
         resources: new Resources(c.processes, dir),
+        say: io.printErr,
     })
     let server: Bun.Server<unknown>
     try {
@@ -98,13 +120,16 @@ export async function runPm(root: string, io: HomeIo, o: { port?: number } = {})
     pm.resources.errors = c.errors
     for (const e of c.errors) io.printErr(`WARN ${e}`)
     // a unit file added, edited or removed in any house repo: read again,
-    // in its child process, and the unchanged processes keep their state
+    // in its child process, and the unchanged processes keep their state.
+    // Nothing moved, no child
+    const watch = new PmConfigWatch(() => readPmConfig(root))
+    watch.seed(c)
     let reading = false
     const reread = setInterval(() => {
         if (reading) return
         reading = true
-        void readPmConfig(root)
-            .then((n) => pm.resources.sync(n.processes, n.errors))
+        void watch.poll()
+            .then((n) => { if (n != null) pm.resources.sync(n.processes, n.errors) })
             .catch((e) => io.printErr(`WARN pm could not read the global processes again: ${(e as Error).message}`))
             .finally(() => { reading = false })
     }, PM_RESCAN_MS)

package/src/home/serve-web.ts

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

package/src/home/supervise.ts

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

package/src/home/widgets.ts

@@ -2,7 +2,8 @@
 // rendered by the daemon on each one's own clock and kept as html the page
 // reads at /api/home/widgets.json. The files are read again every
 // WIDGET_RESCAN_MS, a walk of every repo that costs a few tens of ms, and an
-// unchanged file is never imported twice.
+// unchanged file is never imported twice. All of it only while a reader
+// asked within WIDGET_WATCH_MS: nobody looking, nothing scans or renders.
 //
 // the one constraint a reader breaks first: a render runs in the daemon, so
 // it is bounded (WIDGET_RENDER_MS) and never awaited by the daemon's tick.
@@ -11,6 +12,8 @@ import { scanGlobalUnits, type LoadedWidget, type RepoRef } from './global-units
 export const WIDGET_EVERY_MS = 5_000
 export const WIDGET_RENDER_MS = 5_000
 export const WIDGET_RESCAN_MS = 15_000
+/** a read within this long keeps the clocks running */
+export const WIDGET_WATCH_MS = 30_000
 
 export type WidgetView = {
     repo: string
@@ -38,6 +41,8 @@ export class Widgets {
     private slots = new Map<string, Slot>()
     private scannedAt = -Infinity
     private scanning = false
+    private readAt: number | null = null
+    private rendering = new Set<Promise<void>>()
     /** the unit files that would not load */
     errors: string[] = []
 
@@ -47,9 +52,14 @@ export class Widgets {
         return (this.d.now ?? Date.now)()
     }
 
+    private get watched(): boolean {
+        return this.readAt != null && this.now() - this.readAt < WIDGET_WATCH_MS
+    }
+
     /** one look: read the files again when due, render every widget due. Never
-     *  waits on a render */
+     *  waits on a render, and does nothing while no reader is watching */
     async tick(repos: RepoRef[]): Promise<void> {
+        if (!this.watched) return
         const now = this.now()
         if (!this.scanning && now - this.scannedAt >= WIDGET_RESCAN_MS) {
             this.scanning = true
@@ -73,7 +83,24 @@ export class Widgets {
                 this.scanning = false
             }
         }
-        for (const s of this.slots.values()) if (!s.busy && this.now() >= s.due) void this.render(s)
+        for (const s of this.slots.values()) {
+            if (s.busy || this.now() < s.due) continue
+            const p = this.render(s)
+            this.rendering.add(p)
+            void p.finally(() => this.rendering.delete(p))
+        }
+    }
+
+    /** a reader's views: the first one in a while waits on a scan and on the
+     *  renders it starts (each bounded), so it never reads hours old html */
+    async look(repos: RepoRef[]): Promise<WidgetView[]> {
+        const cold = !this.watched
+        this.readAt = this.now()
+        if (cold) {
+            await this.tick(repos)
+            await Promise.all(this.rendering)
+        }
+        return this.views()
     }
 
     /** one render, bounded, its result or its error kept */
@@ -96,7 +123,9 @@ export class Widgets {
         }
     }
 
+    /** the last html of each; a read that keeps the clocks running */
     views(): WidgetView[] {
+        this.readAt = this.now()
         return [...this.slots.values()].map((s) => s.view)
     }
 }

package/src/hooks/commit-message.ts

@@ -1,6 +1,5 @@
-// the commit-message predicate, shared by the commit-msg hook (blocks at
-// write time) and SK009 (audits history). one implementation, or the two
-// drift and the drift only shows when a repo goes public.
+// the commit-message predicate of the commit-msg hook, which blocks at write
+// time: the one guard against AI attribution (SK009 checks it is armed).
 //
 // mechanical text rules only, so this stays publishable.