rvlib-shipkit 1.1.1 → 1.3.0

package/src/serve/serve-hub.ts

@@ -1,8 +1,9 @@
-// shipkit serve — the repo's ONE Bun.serve, serving the ONE page (one server per repo, one surface, mobx+react). `/` is
-// the hub app (Bun HTML import — media studio + asks + creds + posts +
-// health + wikis as sections); the studio route table mounts as the media
-// API under /media/*; graph canvases stay as drill-down pages. Route logic
-// only — resolving WHAT to mount from repo.config is run-serve.ts's job.
+// the hub's routes: ONE page (the hub app, a Bun HTML import: media studio,
+// asks, creds, posts, health, wikis as sections), the studio route table as
+// the media API under /media/*, graph canvases as drill-down pages. hubHandler
+// is the routing alone, under a base path; serveHub puts it behind a
+// Bun.serve of its own. Resolving WHAT to mount from repo.config is
+// hub-runtime.ts's job.
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { positionsFile } from 'rvlib-shipkit/src/wiki/graph-positions.ts'
@@ -19,21 +20,27 @@ import type { ProseView } from '../prose/prose-view.ts'
 import type { Timeline } from '../ledger/run-timeline.ts'
 import type { TestCheckView, TestsRootView } from '../collections/test-time.ts'
 import type { LiveView } from '../ledger/live-timeline.ts'
+import type { HouseView } from '../ledger/house-runs.ts'
 
 export type { LiveView }
-import type { HealthSchedule } from './health-schedule.ts'
+import type { PlanRow } from '../plan/planner.ts'
 import type { HubProblems } from './hub-problems.ts'
 import hubIndex from './hub-app/index.html'
+import { homePort, homeUp } from '../home/home-paths.ts'
+import { RUN_EXIT } from '../home/home-words.ts'
+import type { RepoProcesses } from './repo-processes.ts'
 import { projectGutter } from './project-gutter-route.ts'
 import { sameOrigin } from './same-origin.ts'
 import { LAYOUT } from '../core/layout.ts'
+import { WarmCell } from './warm-cell.ts'
+import { readmeRoutes } from './readme-route.ts'
 
 export { sameOrigin }
 
 export type HubTool = { path: string; label: string; desc: string }
 
 /** what a running gate streams back to the page */
-export type CheckTap = { line: (l: string) => void; check: (e: CheckEvent) => void }
+export type CheckTap = { line: (l: string) => void; check: (e: CheckEvent) => void; job?: (id: string) => void }
 /** the comfy panel, as the hub needs it: the child process it embeds and the
  *  box those workflows generate on (src/comfy/comfy-panel.ts owns both) */
 export type ComfyDeps = {
@@ -45,6 +52,12 @@ export type ComfyDeps = {
 export type HubDeps = {
     root: string
     name: string
+    /** the machine resources the repo declares in serve.uses */
+    uses?: string[]
+    /** the long running processes the repo declares in serve.processes */
+    processes?: RepoProcesses
+    /** a terminal's `shipkit ci` or `check`, run in this process; resolves to its exit code */
+    runCli?: (kind: 'ci' | 'check', opts: Record<string, unknown>, print: (l: string) => void) => Promise<number>
     /** 0 = random (tests); real launches pass repo.config/default */
     port: number
     /** every md graph this hub serves, in card order: /graph/<id>. run-serve
@@ -62,20 +75,23 @@ export type HubDeps = {
      *  into a tree someone is editing. run-serve owns the routing between the
      *  two engines. */
     runChecks: (tap: CheckTap, o?: { only?: string[]; gate?: boolean; by?: InvokedBy; auto?: boolean }) => Promise<number>
-    /** the daily health pass timer (health-schedule.ts). The page reads its
-     *  state to say when a health check runs next; absent = no timer */
-    schedule?: HealthSchedule | null
+    /** this repo's rows of the plan (plan/planner.ts): the page reads them to
+     *  say when a check runs next and why; absent = no plan */
+    planned?: () => PlanRow[]
+    /** a click: this check runs next, through the plan. false = the plan
+     *  does not know it */
+    ask?: (check: string) => boolean
     /** every run on record, shaped for the timeline page. Absent = the page
      *  says there is no record rather than drawing an empty one */
     timeline?: () => Promise<Timeline>
     /** where the test checks' time goes: the `tests` page (check null) or one
      *  test check's page (collections/test-time.ts). Absent = 404 */
     tests?: (check: string | null) => Promise<TestsRootView | TestCheckView>
-    /** the live strip's view: the recent runs and the ones in flight, here
-     *  and in the other house repos, shaped on the server clock */
+    /** this repo's live view: the recent runs and the ones in flight, shaped
+     *  on the server clock */
     live?: () => LiveView
-    /** another house repo's hub url when it serves, null when it does not */
-    repoHub?: (repo: string) => Promise<string | null>
+    /** the dock's view: every house repo's recent runs (house-runs.ts) */
+    house?: () => HouseView
     /** every human-action item, red/yellow, gathered per request from the
      *  collection providers (run-serve builds it) */
     needs: () => Promise<NeedItem[]>
@@ -99,11 +115,40 @@ export type HubDeps = {
      *  file, so every surface built on the config asks for this first, or a
      *  toggle reads as a toggle that did nothing until the next restart */
     refresh?: () => Promise<void>
-    /** RED-only ping tick, called on an interval while serving (null = off) */
+    /** a cheap fingerprint of what the rows and the run record read (file
+     *  stats): a new one marks the warm answers stale. Absent = only a save
+     *  and their age refresh them */
+    stamp?: () => string
+    /** RED-only ping tick, called on an interval by the hub runtime (null = off) */
     pingTick?: ((needs: NeedItem[]) => void) | null
 }
 export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; liveReload: boolean; stop: () => void }
 
+/** one repo's request handling, apart from any server: `shipkit serve` puts it
+ *  behind a Bun.serve of its own, the home behind /r/<repo>/ of its one */
+export type HubHandler = {
+    tools: HubTool[]
+    /** a request whose path is relative to the hub's base ('/api/…', '/hub.json') */
+    handle: (req: Request, path: string, srv: Server) => Promise<Response>
+    /** a tracked file of the repo moved: every warm answer recomputes behind */
+    invalidate: () => void
+    /** compute the warm answers now, the rows first: the hub's load */
+    warm: () => Promise<void>
+    stop: () => void
+}
+
+/** past this age a warm answer recomputes in the background even when no
+ *  save and no stamp said it moved: what no watch sees (a clock, a wiki in
+ *  another repo, a file git ignores). Long, because a recompute holds the
+ *  one process every repo answers from */
+export const WARM_MAX_AGE_MS = 120_000
+
+/** the one flat list of the repo, as /api/resources.json carries it before
+ *  the plan rows and the hub problems, which are read live */
+type Rows = { collections: { id: string; title: string; media: string }[]; resources: Awaited<ReturnType<typeof projectResources>> }
+type Server = ReturnType<typeof Bun.serve>
+type Gutter = ReturnType<typeof projectGutter>
+
 /** the tab refreshes ITSELF through bun's hot reload client, which rides in
  *  the served page: it swaps a hub-app edit in, and reconnects across the
  *  process restart a source edit triggers under `bun --watch`. Bun puts that
@@ -124,27 +169,79 @@ export function hubTools(d: Pick<HubDeps, 'graphs'>): HubTool[] {
 }
 
 // drill-down pages (graph canvases) get one fixed home link back to THE page
-const HOME_LINK = `<style>.skhome{position:fixed;left:10px;top:10px;z-index:9999;font-size:17px;text-decoration:none;
- background:#141619;border:1px solid #282c31;border-radius:3px;padding:5px 9px}</style><a class=skhome href="/" title="hub — THE page">⌂</a>`
-const withHome = (html: string): string => html.replace(/<body([^>]*)>/, `<body$1>${HOME_LINK}`)
+const homeLink = (base: string): string => `<style>.skhome{position:fixed;left:10px;top:10px;z-index:9999;font-size:17px;text-decoration:none;
+ background:#141619;border:1px solid #282c31;border-radius:3px;padding:5px 9px}</style><a class=skhome href="${base}/" title="hub — THE page">⌂</a>`
+const withHome = (html: string, base: string): string => html.replace(/<body([^>]*)>/, `<body$1>${homeLink(base)}`)
 
-export function serveHub(d: HubDeps): Hub {
+/** the hub's routes under `base` ('' on a server of its own, '/r/<repo>' in
+ *  the home). `projects` is the rail, shared when one process serves many */
+export function hubHandler(d: HubDeps, o: { base?: string; projects?: Gutter } = {}): HubHandler {
+    const base = o.base ?? ''
     const tools = hubTools(d)
-    const projects = projectGutter({ root: d.root })
-    const server: ReturnType<typeof Bun.serve> = Bun.serve({
-        hostname: '127.0.0.1',
-        port: d.port,
-        // `/` IS the page — the react app; there is no other surface
-        routes: { '/': hubIndex },
-        async fetch(req): Promise<Response> {
-            const path = new URL(req.url).pathname
+    const projects = o.projects ?? projectGutter({ root: d.root })
+    // the answers a page waits on when a repo shows, kept warm in memory: a
+    // request answers from here and never walks the repo (warm-cell.ts)
+    const warmOpts = { stamp: d.stamp, maxAgeMs: WARM_MAX_AGE_MS }
+    const rows = new WarmCell<Rows>(async () => {
+        await d.refresh?.()
+        const cols = d.collections()
+        return { collections: cols.map((c) => ({ id: c.id, title: c.title, media: c.media })), resources: await projectResources(cols, d.hubProblems?.collector) }
+    }, warmOpts)
+    // the run record and the config are all it reads, and the stamp sees both
+    const timeline = d.timeline == null ? null : new WarmCell(d.timeline, { stamp: d.stamp })
+    const graphs = new Map(d.graphs.map((g) => [g.id, new WarmCell(async () => g.load(), { maxAgeMs: WARM_MAX_AGE_MS })]))
+    const fresh = (req: Request): boolean => new URL(req.url).searchParams.get('fresh') === '1'
+    return {
+        tools,
+        invalidate: () => {
+            rows.invalidate()
+            timeline?.invalidate()
+            for (const g of graphs.values()) g.invalidate()
+        },
+        warm: async () => {
+            await rows.warm()
+            await timeline?.warm()
+            for (const g of graphs.values()) await g.warm()
+        },
+        stop: () => { d.comfy?.stop() },
+        async handle(req, path, srv): Promise<Response> {
             if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the hub page', { status: 403 })
             // identity probe: lets a second launch tell "same repo, another
             // window" from "a DIFFERENT repo hashed onto my port"
             // `root` rides with it so a page can put a file link into his
             // editor: only the server knows where this repo sits on disk
-            if (path === '/hub.json') return Response.json({ hub: 'shipkit', name: d.name, root: d.root, tools })
+            // `uses` tells the home which machine resources this repo needs,
+            // `base` where this hub's page sits on the server that answers
+            if (path === '/hub.json') return Response.json({ hub: 'shipkit', name: d.name, root: d.root, base, tools, uses: d.uses ?? [] })
             if (path.startsWith('/api/projects')) return (await projects.handle(req, path)) ?? new Response('not found', { status: 404 })
+            // where the machine's home serves, and whether it does: a rail
+            // click opens the home on that repo, or VS Code while none runs
+            if (path === '/api/home-url') return Response.json({ port: homePort(), up: await homeUp() })
+            if (path === '/api/run' && req.method === 'POST' && d.runCli != null) {
+                const b = (await req.json().catch(() => ({}))) as { kind?: string; opts?: Record<string, unknown> }
+                if (b.kind !== 'ci' && b.kind !== 'check') return new Response('kind must be ci or check', { status: 400 })
+                const runCli = d.runCli
+                // a gate can stay silent for minutes (queued, or one long tsc):
+                // Bun would cut the connection after its idle timeout
+                srv.timeout(req, 0)
+                // wire lines as they come, then one EXIT line the client ends on
+                const stream = new ReadableStream<string>({
+                    start(ctl) {
+                        const put = (l: string): void => { try { ctl.enqueue(`${l}\n`) } catch { /* the terminal went away: the run finishes anyway */ } }
+                        void runCli(b.kind as 'ci' | 'check', b.opts ?? {}, put)
+                            .then((code) => put(`${RUN_EXIT}${code}`), (e: Error) => { put(`FAIL: ${e.message}`); put(`${RUN_EXIT}1`) })
+                            .finally(() => { try { ctl.close() } catch { /* closed */ } })
+                    },
+                })
+                return new Response(stream, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
+            }
+            if (path === '/api/processes.json') return Response.json({ processes: d.processes?.views() ?? [] })
+            if (path === '/api/processes/act' && req.method === 'POST') {
+                const b = (await req.json().catch(() => ({}))) as { id?: string; act?: string }
+                if (b.act !== 'start' && b.act !== 'stop' && b.act !== 'restart') return new Response('act must be start, stop or restart', { status: 400 })
+                const v = d.processes?.act(b.id ?? '', b.act)
+                return v == null ? new Response(`no process '${b.id ?? ''}' in serve.processes`, { status: 404 }) : Response.json(v)
+            }
             // the three surfaces built on the config read the config on disk
             if (path === '/api/needs.json' || path === '/api/resources.json' || path === '/api/checks.json' || path === '/api/collections.json') await d.refresh?.()
             if (path === '/api/needs.json') {
@@ -155,11 +252,11 @@ export function serveHub(d: HubDeps): Hub {
                 // ONE flat list for the whole repo: the page groups it by
                 // path and by type, and a second endpoint would be a second
                 // answer to drift from this one
-                const cols = d.collections()
+                const r = await rows.get({ fresh: fresh(req) })
                 return Response.json({
-                    collections: cols.map((c) => ({ id: c.id, title: c.title, media: c.media })),
-                    resources: await projectResources(cols, d.hubProblems?.collector),
-                    schedule: d.schedule?.state() ?? null,
+                    collections: r.collections,
+                    resources: r.resources,
+                    planned: d.planned?.() ?? null,
                     hub: d.hubProblems?.list() ?? [],
                 })
             }
@@ -228,17 +325,17 @@ export function serveHub(d: HubDeps): Hub {
                 }
             }
             if (path === '/api/live.json') {
-                if (d.live == null) return Response.json({ now: Date.now(), historyMs: 0, cap: 0, busy: 0, invocations: [], repos: [], runs: [], queued: 0, blocked: [] } satisfies LiveView)
+                if (d.live == null) return Response.json({ now: Date.now(), historyMs: 0, cap: 0, busy: 0, invocations: [], runs: [], queued: 0, blocked: [] } satisfies LiveView)
                 return Response.json(d.live(), { headers: { 'cache-control': 'no-store' } })
             }
-            if (path === '/api/repo-hub') {
-                const repo = new URL(req.url).searchParams.get('repo') ?? ''
-                return Response.json({ url: d.repoHub == null ? null : await d.repoHub(repo) })
+            if (path === '/api/house-runs.json') {
+                if (d.house == null) return new Response('this hub draws no house runs', { status: 404 })
+                return Response.json(d.house(), { headers: { 'cache-control': 'no-store' } })
             }
             if (path === '/api/timeline.json') {
-                if (d.timeline == null) return new Response('this hub keeps no run record', { status: 404 })
+                if (timeline == null) return new Response('this hub keeps no run record', { status: 404 })
                 try {
-                    return Response.json(await d.timeline())
+                    return Response.json(await timeline.get({ fresh: fresh(req) }))
                 } catch (e) {
                     return new Response(`the run record could not be shaped: ${(e as Error).message}`, { status: 500 })
                 }
@@ -252,6 +349,9 @@ export function serveHub(d: HubDeps): Hub {
                     return new Response(`the test times could not be shaped: ${(e as Error).message}`, { status: 500 })
                 }
             }
+            // the empty page shows the README, its images served from the repo
+            const readme = await readmeRoutes(d.root, path)
+            if (readme != null) return readme
             if (path === '/api/status.json') {
                 const p = join(d.root, LAYOUT.status)
                 return Response.json({ statusMd: existsSync(p) ? await Bun.file(p).text() : null })
@@ -319,30 +419,33 @@ export function serveHub(d: HubDeps): Hub {
                 })
                 return new Response(stream, { headers: { 'content-type': 'application/x-ndjson; charset=utf-8', 'cache-control': 'no-store' } })
             }
-            const page = (s: string): Response => new Response(withHome(s), { headers: { 'content-type': 'text/html; charset=utf-8' } })
+            const page = (s: string): Response => new Response(withHome(s, base), { headers: { 'content-type': 'text/html; charset=utf-8' } })
             for (const g of d.graphs) {
                 if (!path.startsWith(`/graph/${g.id}`)) continue
-                const routes = graphRoutes({ load: g.load, title: g.title, file: positionsFile(d.root, g.id), saveUrl: `/graph/${g.id}/positions` })
+                // the graph as the warm cell holds it: a page open never rescans the wiki
+                const held = await graphs.get(g.id)!.get()
+                const routes = graphRoutes({ load: () => held, title: g.title, file: positionsFile(d.root, g.id), saveUrl: `${base}/graph/${g.id}/positions` })
                 if (path === `/graph/${g.id}`) return page(routes.page())
-                if (path === `/graph/${g.id}/graph.json`) return Response.json(g.load())
+                if (path === `/graph/${g.id}/graph.json`) return Response.json(held)
                 if (path === `/graph/${g.id}/positions`) return routes.save(req)
             }
             // the media API namespace — the studio route table, ONE prefix strip
             if (d.studio != null && path.startsWith('/media/')) return d.studio.handle(req, path.slice('/media'.length))
             // stale bookmarks (/assets/, /status, …) land here — name the way home
-            return new Response('not found — the hub page is at /', { status: 404 })
+            return new Response(`not found — the hub page is at ${base}/`, { status: 404 })
         },
-    })
-    // RED-only pings ride the serving process: one tick now (state file
-    // guarantees a restart never re-fires), then every minute
-    let pingTimer: ReturnType<typeof setInterval> | null = null
-    if (d.pingTick != null) {
-        // tick failures are LOUD (console = the serve terminal), never swallowed
-        const tick = (): void => void d.needs().then((n) => d.pingTick?.(n)).catch((e: Error) => console.error(`WARN ping tick broke: ${e.message}`))
-        tick()
-        pingTimer = setInterval(tick, 60_000)
     }
+}
+
+export function serveHub(d: HubDeps, h: HubHandler = hubHandler(d)): Hub {
+    const server: Server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: d.port,
+        // `/` IS the page — the react app; there is no other surface
+        routes: { '/': hubIndex },
+        fetch: (req, srv) => h.handle(req, new URL(req.url).pathname, srv),
+    })
     // the panel process belongs to this hub: leaving it behind means the next
     // launch adopts a server holding the previous run's modules
-    return { server, tools, liveReload: canLiveReload(), stop: () => { if (pingTimer != null) clearInterval(pingTimer); d.schedule?.stop(); d.comfy?.stop(); server.stop(true) } }
+    return { server, tools: h.tools, liveReload: canLiveReload(), stop: () => { h.stop(); server.stop(true) } }
 }

package/src/serve/stale-restart.ts

@@ -20,6 +20,9 @@ export type StaleRestartOpts = {
     /** why the file table leaked, null while it did not. Default: this
      *  process's own table (core/fd-table.ts) */
     leak?: () => string | null
+    /** one line on source that moved under a process with no bun watch, null
+     *  while nothing moved */
+    moved?: () => string | null
     /** a run is in flight: a restart now would kill it */
     busy: () => boolean
     /** never returns when it works. `why` is one line on what went stale */
@@ -62,6 +65,8 @@ export class StaleRestart {
         const disk = this.o.disk()
         // a package.json half written by a bump reads as `?`, and is no verdict
         if (disk !== '?' && disk !== this.o.boot) return { why: `this hub runs shipkit ${this.o.boot} but ${disk} is on disk`, leak: false }
+        const moved = this.o.moved?.() ?? null
+        if (moved != null) return { why: moved, leak: false }
         const leak = (this.o.leak ?? fdTableLeak)()
         return leak == null ? null : { why: leak, leak: true }
     }

package/src/serve/{gate-trigger.ts → tracked-watch.ts}

@@ -1,72 +1,13 @@
-// when the hub runs the quick gate on its own: once at start, then after the
-// tracked files have been quiet for QUIET_MS. The trigger only STARTS ordinary
-// gate runs. Every answer comes out of the one runner, measured or replayed
-// from the ledger like any other run, so nothing here owns a verdict: a missed
-// file event costs a stale problems pane until the next save, never a green.
-//
-// never two runs at once: a request during a run queues exactly one more, run
-// after it ends, however many saves landed meanwhile.
-import { watch, type FSWatcher } from 'fs'
+// the save watch: which files moving under a repo count as the owner's edit.
+// It only says THAT something moved; the plan (plan/planner.ts) then asks the
+// ledger which checks that moved, so a missed file event costs a stale
+// problems pane until the next save, never a green.
+import { statSync, watch, type FSWatcher } from 'fs'
+import { join } from 'path'
 import { GENERATED_IGNORE_LINES } from '../rules/untrack-generated.ts'
 import { gitBin } from '../core/git-bin.ts'
 import { LAYOUT } from '../core/layout.ts'
 
-export const QUIET_MS = 2000
-
-export type Timers = {
-    set: (fn: () => void, ms: number) => unknown
-    clear: (handle: unknown) => void
-}
-
-const realTimers: Timers = {
-    set: (fn, ms) => setTimeout(fn, ms),
-    clear: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
-}
-
-export class GateTrigger {
-    private timer: unknown = null
-    private running: Promise<void> | null = null
-    private pending = false
-    private readonly timers: Timers
-    private readonly quietMs: number
-
-    constructor(private readonly o: { run: () => Promise<unknown>; quietMs?: number; timers?: Timers; onError?: (e: Error) => void }) {
-        this.timers = o.timers ?? realTimers
-        this.quietMs = o.quietMs ?? QUIET_MS
-    }
-
-    /** a tracked file moved: the run starts once nothing has moved for the
-     *  quiet window, so a save burst is one run */
-    touched(): void {
-        if (this.timer != null) this.timers.clear(this.timer)
-        this.timer = this.timers.set(() => {
-            this.timer = null
-            this.request()
-        }, this.quietMs)
-    }
-
-    /** run now, or once more after the run in flight */
-    request(): void {
-        if (this.running != null) { this.pending = true; return }
-        this.running = (async () => {
-            do {
-                this.pending = false
-                try { await this.o.run() } catch (e) { this.o.onError?.(e instanceof Error ? e : new Error(String(e))) }
-            } while (this.pending)
-        })().finally(() => { this.running = null })
-    }
-
-    /** resolves when no run is in flight or queued */
-    async idle(): Promise<void> {
-        while (this.running != null) await this.running
-    }
-
-    stop(): void {
-        if (this.timer != null) this.timers.clear(this.timer)
-        this.timer = null
-    }
-}
-
 /** every path a run of the gate or the hub itself writes, whatever the repo
  *  ignores: the status files, the per run logs under the scratch dir, an atomic write's
  *  temp file, the comfy state the hub writes at boot. A save there is the
@@ -106,6 +47,13 @@ export async function gitIgnored(root: string, paths: string[]): Promise<Set<str
     }
 }
 
+/** a commit, a fetch or a tag moved a ref: the one write inside .git a check
+ *  keyed on the refs (SK009) must hear. Lock files are git mid write */
+export function isRefMove(rel: string): boolean {
+    if (rel.endsWith('.lock')) return false
+    return rel === '.git/HEAD' || rel === '.git/packed-refs' || rel.startsWith('.git/refs/')
+}
+
 /** calls onChange whenever a file the owner edits moves under root: tracked,
  *  or untracked and not ignored. What the gate itself writes (GATE_WRITES,
  *  the ledger in .git) never counts, ignored or not, so a run never triggers
@@ -134,6 +82,7 @@ export function watchTracked(root: string, onChange: () => void, o: { ignored?:
         w = watch(root, { recursive: true }, (_event, name) => {
             if (name == null) return onChange()
             const rel = String(name).replace(/\\/g, '/')
+            if (isRefMove(rel)) return onChange()
             if (rel === '.git' || rel.startsWith('.git/') || rel.split('/').includes('node_modules') || isGateWrite(rel)) return
             pending.add(rel)
             void flush()
@@ -146,3 +95,26 @@ export function watchTracked(root: string, onChange: () => void, o: { ignored?:
     }
     return { close: () => w?.close(), error }
 }
+
+/** did the owner edit anything after `since`: a tracked file, or an untracked
+ *  one git does not ignore, written later, or a ref that moved. What the gate
+ *  writes never counts. A boot asks it once per repo, so a burst the previous
+ *  image had not asked about is picked up (plan/repo-source.ts pending) */
+export async function movedSince(root: string, since: number): Promise<boolean> {
+    let out = ''
+    try {
+        const p = Bun.spawn([gitBin(), 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+        out = await new Response(p.stdout).text()
+        if ((await p.exited) !== 0) return false
+    } catch {
+        return false
+    }
+    const later = (rel: string): boolean => {
+        try { return statSync(join(root, rel)).mtimeMs > since } catch { return false }
+    }
+    for (const rel of out.split('\0')) {
+        if (rel === '' || rel.split('/').includes('node_modules') || isGateWrite(rel)) continue
+        if (later(rel)) return true
+    }
+    return later('.git/HEAD') || later('.git/packed-refs')
+}

package/src/serve/warm-cell.ts

@@ -0,0 +1,95 @@
+// one answer of a hub kept warm in memory: computed when the hub loads,
+// recomputed in the background when something says it moved (a save, a
+// stamp, its age), and served from memory. A request never pays for the
+// walk behind it, except the very first one and one that asks for `fresh`.
+//
+// the one constraint a reader breaks first: `get()` answers what is in
+// memory even when it is known stale. Whoever just changed the truth (an
+// act, the end of a run) asks for `fresh`, which waits on a compute that
+// started after its call.
+
+export type WarmCellOpts = {
+    /** a cheap fingerprint of what the answer reads (file stats): a new one
+     *  marks the answer stale */
+    stamp?: () => string
+    /** past this age the answer is recomputed in the background even when
+     *  nothing said it moved: what no watch sees (a clock, another repo) */
+    maxAgeMs?: number
+    now?: () => number
+}
+
+export class WarmCell<T> {
+    private value: { v: T; at: number; stamp: string } | null = null
+    private running: Promise<T> | null = null
+    /** bumped by invalidate: a compute that started before it is stale */
+    private gen = 0
+    private runGen = -1
+
+    constructor(private readonly compute: () => Promise<T>, private readonly o: WarmCellOpts = {}) {}
+
+    private now(): number {
+        return this.o.now?.() ?? Date.now()
+    }
+
+    /** a compute, shared by every caller while it runs */
+    private run(): Promise<T> {
+        if (this.running != null) return this.running
+        const gen = this.gen
+        const stamp = this.o.stamp?.() ?? ''
+        this.runGen = gen
+        const p = (async (): Promise<T> => {
+            try {
+                // never synchronously: `running` is set before this settles
+                const v = await Promise.resolve().then(() => this.compute())
+                this.value = { v, at: this.now(), stamp }
+                return v
+            } finally {
+                this.running = null
+                // what said it moved while this ran is not in this answer
+                if (this.gen !== gen) this.kick()
+            }
+        })()
+        this.running = p
+        return p
+    }
+
+    /** a compute in the background: on a failure the last answer stays */
+    private kick(): void {
+        void this.run().catch(() => {})
+    }
+
+    get stale(): boolean {
+        const v = this.value
+        if (v == null) return true
+        if (this.o.maxAgeMs != null && this.now() - v.at > this.o.maxAgeMs) return true
+        return this.o.stamp != null && this.o.stamp() !== v.stamp
+    }
+
+    /** the answer in memory, a stale one kicking a recompute behind it. With
+     *  nothing in memory yet, or `fresh`, it waits on a compute */
+    async get(o: { fresh?: boolean } = {}): Promise<T> {
+        if (o.fresh === true) {
+            // a compute that started before this call may miss what the
+            // caller just changed: wait for it, then for one of our own
+            if (this.running != null) await this.running.catch(() => {})
+            return this.run()
+        }
+        const v = this.value
+        // nothing in memory, a failed compute included: wait on a new one
+        if (v == null) return this.run()
+        if (this.running == null && (this.stale || this.gen !== this.runGen)) this.kick()
+        return v.v
+    }
+
+    /** something this answer reads moved: recompute in the background */
+    invalidate(): void {
+        this.gen++
+        if (this.running == null) this.kick()
+    }
+
+    /** compute now unless an answer is already in memory: the hub's load */
+    async warm(): Promise<void> {
+        if (this.value != null) return
+        await this.run().catch(() => {})
+    }
+}