rvlib-shipkit 1.2.0 → 1.4.0

package/src/serve/project-gutter-route.ts

@@ -5,22 +5,23 @@
 // the index moved, a few repos per poll, and a repo's run record is opened
 // only when it moved, so a steady poll spawns ps and lsof and nothing else. The icon route
 // serves only the icon files a discovered repo carries, and POST
-// /api/projects/open opens a discovered repo in VS Code: a request names a
-// repo, never a path. The rail ORDER is one text file for the whole machine
+// /api/projects/open opens a discovered repo in VS Code, POST
+// /api/projects/fork in Fork: a request names a repo, never a path. The rail ORDER is one text file for the whole machine
 // (ORDER_FILE), so every hub shows the same order and a hand edit is seen
 // within one poll; POST /api/projects/order writes it.
-import { mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
 import { readFile, stat } from 'fs/promises'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import {
-    asksDirOf, branchOf, countSessions, descriptionOf, dirtyCount, gateOf, gitStamp, houseRepos, iconStamp, ICON_TYPES, lastActivity,
+    asksDirOf, branchOf, countSessions, descriptionOf, dirtyCount, gateFrom, checkStateOf, gitStamp, houseRepos, iconStamp, ICON_TYPES, lastActivity,
     lastRunAt, lastSessionAt, liveUrlOf, mergeOrder, openAsks, openFolders, parseClaudePids, parseDescribe, parseLsofCwd, parseOrder,
-    recordOf, recordStamp, RELEASE_TAGS, renderOrder, versionOf, vscodeStoragePath, type Gate, type WiredRepo,
+    recordOf, recordStamp, RELEASE_TAGS, renderOrder, versionOf, vscodeStoragePath, type CheckState, type Gate, type LastRow, type WiredRepo,
 } from './project-gutter.ts'
 import { readLastStatusReadonly } from '../ledger/run-log.ts'
 import { identityOfText, identityProblem, type Identity } from '../core/identity-color.ts'
 import { writeIdentity } from '../core/identity.ts'
+import { writeArchived } from '../core/archived.ts'
 
 export type { Gate }
 
@@ -62,6 +63,8 @@ export type ProjectRow = {
     dirty: number | null
     /** the last gate its own run record holds */
     gate: Gate
+    /** every check's last outcome as one colour, warnings included */
+    checks: CheckState
     release: Release
     /** the deployed url `smoke.base` declares, or null */
     live: string | null
@@ -70,8 +73,13 @@ export type ProjectRow = {
     /** epoch ms of the newest of: the last commit, the last shipkit run, the
      *  newest Claude Code transcript. null when none of them exists */
     activity: number | null
+    /** epoch ms of the last commit on HEAD, null when git cannot say */
+    commit: number | null
 }
-export type ProjectsAnswer = { projects: ProjectRow[]; ms: number; at: number }
+/** a repo whose repo.config.ts says `archived: true`: only the archived page lists it */
+export type ArchivedRow = { name: string; icon: string | null }
+
+export type ProjectsAnswer = { projects: ProjectRow[]; archived: ArchivedRow[]; ms: number; at: number }
 
 /** a command's exit code and stdout, or null when its binary is missing */
 export type Run = (cmd: string[], cwd?: string) => Promise<{ code: number; out: string } | null>
@@ -83,12 +91,18 @@ export type GutterDeps = {
     run?: Run
     /** opens a folder in VS Code; throws with the reason it could not */
     open?: (path: string) => void
+    /** opens a folder in Fork, the git client; throws with the reason it could not */
+    fork?: (path: string) => void
     warn?: (line: string) => void
     now?: () => number
     /** where the rail order lives, default ~/ORDER_FILE */
     orderFile?: string
     /** the Claude Code `projects` folders, default the `projects` folder of every ~/.claude config root */
     transcriptRoots?: string[]
+    /** the check ids a repo declares today (the daemon's plan), so a check
+     *  it no longer declares never colours it. Absent or null = not known,
+     *  every recorded check counts */
+    declared?: (name: string) => ReadonlySet<string> | null
 }
 
 const runCmd: Run = async (cmd, cwd) => {
@@ -111,6 +125,21 @@ function openInCode(path: string): void {
     throw new Error('the `code` command is not on PATH: in VS Code, run "Shell Command: Install \'code\' command in PATH"')
 }
 
+/** where Fork is installed, the places macOS keeps apps */
+export const FORK_APPS = ['/Applications/Fork.app', join(homedir(), 'Applications', 'Fork.app')]
+
+/** the command that opens a folder in Fork; throws when Fork is not installed */
+export function forkCommand(path: string, installed: (app: string) => boolean = existsSync, platform: string = process.platform): string[] {
+    if (platform !== 'darwin') throw new Error('opening in Fork is macOS only here')
+    const app = FORK_APPS.find(installed)
+    if (app == null) throw new Error(`Fork is not installed (looked in ${FORK_APPS.join(', ')})`)
+    return ['open', '-a', app, path]
+}
+
+function openInFork(path: string): void {
+    Bun.spawn(forkCommand(path), { stdio: ['ignore', 'ignore', 'ignore'] }).unref()
+}
+
 const epochMs = (out: string | undefined): number | null => {
     const secs = Number(out?.trim())
     return Number.isFinite(secs) && secs > 0 ? secs * 1000 : null
@@ -130,6 +159,15 @@ const readText = (file: string): string => {
     }
 }
 
+/** the house repos in the rail's order, archived ones left out: the rows of
+ *  the project list without the facts the list measures, for a caller that
+ *  needs only names and paths (`shipkit cross-repo-activity`) */
+export function railRepos(root: string, userHome: string = homedir(), orderFile: string = join(userHome, ORDER_FILE)): WiredRepo[] {
+    const repos = houseRepos(root, userHome).repos
+    const by = new Map(repos.map((r) => [r.name, r]))
+    return mergeOrder(parseOrder(readText(orderFile)), repos.map((r) => r.name)).map((n) => by.get(n)!)
+}
+
 export function projectGutter(d: GutterDeps) {
     let home = d.root
     const userHome = d.home ?? homedir()
@@ -145,21 +183,25 @@ export function projectGutter(d: GutterDeps) {
     }
 
     let repos: WiredRepo[] = []
+    let archivedRepos: WiredRepo[] = []
     let last: ProjectsAnswer | null = null
     let inFlight: Promise<ProjectsAnswer> | null = null
     let folders: { mtime: number; list: string[] } | null = null
     const releases = new Map<string, { stamp: string | null; at: number; release: Release; commitAt: number | null; dirty: number | null }>()
-    const gates = new Map<string, { stamp: string; gate: Gate }>()
-    /** a repo's last gate, its record opened only when it moved */
-    const gateOfRepo = (path: string): Gate => {
-        const record = recordOf(path)
-        if (record == null) return null
+    const records = new Map<string, { stamp: string; rows: LastRow[] }>()
+    /** a repo's last gate and check colour, its record opened only when it
+     *  moved, counted over the checks it declares today */
+    const gateOfRepo = (r: WiredRepo): { gate: Gate; checks: CheckState } => {
+        const record = recordOf(r.path)
+        if (record == null) return { gate: null, checks: null }
         const stamp = recordStamp(record)
-        const hit = gates.get(path)
-        if (hit != null && hit.stamp === stamp) return hit.gate
-        const gate = gateOf(readLastStatusReadonly(record))
-        gates.set(path, { stamp, gate })
-        return gate
+        let hit = records.get(r.path)
+        if (hit == null || hit.stamp !== stamp) {
+            hit = { stamp, rows: readLastStatusReadonly(record) }
+            records.set(r.path, hit)
+        }
+        const checks = checkStateOf(hit.rows, d.declared?.(r.name) ?? null)
+        return { gate: gateFrom(checks), checks }
     }
     const orderFile = d.orderFile ?? join(userHome, ORDER_FILE)
     const transcriptRoots = (): string[] => {
@@ -251,12 +293,15 @@ export function projectGutter(d: GutterDeps) {
         return paths.map((p) => ({ release: releases.get(p)?.release ?? null, commitAt: releases.get(p)?.commitAt ?? null, dirty: releases.get(p)?.dirty ?? null }))
     }
 
+    const iconUrl = (r: WiredRepo): string | null => (r.icon == null ? null : `/api/projects/icon/${encodeURIComponent(r.name)}?v=${iconStamp(join(r.path, r.icon))}`)
+
     async function measure(): Promise<ProjectsAnswer> {
         const t0 = performance.now()
         const house = houseRepos(d.root, userHome)
         home = house.home
         if (house.index == null) warnOnce('house', `WARN project gutter: ${home} includes no house wiki index, so no sibling shares one and the gutter is empty`)
         repos = house.repos
+        archivedRepos = house.archived
         const [open, cwds, facts] = await Promise.all([vscodeFolders(), sessionCwds(), gitFacts(repos.map((r) => r.path))])
         const transcripts = lastSessionAt(transcriptRoots(), repos.map((r) => r.path))
         const counts = cwds == null ? null : countSessions(cwds, repos.map((r) => r.path))
@@ -266,10 +311,11 @@ export function projectGutter(d: GutterDeps) {
             const asks = openAsks(join(r.path, asksDirOf(config, r.path)))
             // the README is read only when package.json says nothing
             const description = descriptionOf(pkg, '') ?? descriptionOf('', readText(join(r.path, 'README.md')))
+            const state = gateOfRepo(r)
             return {
                 name: r.name,
                 path: r.path,
-                icon: r.icon == null ? null : `/api/projects/icon/${encodeURIComponent(r.name)}?v=${iconStamp(join(r.path, r.icon))}`,
+                icon: iconUrl(r),
                 current: r.path === home,
                 vscode: open == null ? null : open.some((f) => f === r.path),
                 sessions: counts?.get(r.path) ?? null,
@@ -279,14 +325,17 @@ export function projectGutter(d: GutterDeps) {
                 version: versionOf(pkg),
                 branch: branchOf(readText(join(r.path, '.git', 'HEAD'))),
                 dirty: facts[i]!.dirty,
-                gate: gateOfRepo(r.path),
+                gate: state.gate,
+                checks: state.checks,
                 release: facts[i]!.release,
                 live: liveUrlOf(config),
                 identity: identityOfText(config),
                 activity: lastActivity(facts[i]!.commitAt, lastRunAt(r.path), transcripts.get(r.path)),
+                commit: facts[i]!.commitAt,
             }
         })
-        return { projects: inOrder(projects, parseOrder(readText(orderFile))), ms: Math.round(performance.now() - t0), at: now() }
+        const archived = archivedRepos.map((r) => ({ name: r.name, icon: iconUrl(r) }))
+        return { projects: inOrder(projects, parseOrder(readText(orderFile))), archived, ms: Math.round(performance.now() - t0), at: now() }
     }
 
     /** the last answer while it is younger than POLL_MS, one measure otherwise,
@@ -301,6 +350,8 @@ export function projectGutter(d: GutterDeps) {
     }
 
     const find = (name: string): WiredRepo | undefined => repos.find((r) => r.name === name)
+    /** a live repo or an archived one: the icon and the archive toggle reach both */
+    const findAny = (name: string): WiredRepo | undefined => find(name) ?? archivedRepos.find((r) => r.name === name)
 
     /** saves the rail order: the names given, then every discovered repo they
      *  leave out. Written whole through a temp file, so a reader never sees
@@ -320,7 +371,7 @@ export function projectGutter(d: GutterDeps) {
         if (path === '/api/projects.json') return Response.json(await answer())
         if (path.startsWith('/api/projects/icon/')) {
             if (repos.length === 0) await answer()
-            const r = find(decodeURIComponent(path.slice('/api/projects/icon/'.length)))
+            const r = findAny(decodeURIComponent(path.slice('/api/projects/icon/'.length)))
             if (r?.icon == null) return new Response('no icon', { status: 404 })
             return new Response(Bun.file(join(r.path, r.icon)), {
                 headers: { 'content-type': ICON_TYPES[r.icon.split('.').pop()!] ?? 'application/octet-stream', 'cache-control': 'max-age=86400' },
@@ -342,6 +393,21 @@ export function projectGutter(d: GutterDeps) {
                 return new Response((e as Error).message, { status: 409 })
             }
         }
+        if (path === '/api/projects/archived' && req.method === 'POST') {
+            if (repos.length === 0) await answer()
+            const b = (await req.json().catch(() => ({}))) as { name?: unknown; archived?: unknown }
+            const r = findAny(String(b.name))
+            if (r == null) return new Response(`not a house repo: ${String(b.name)}`, { status: 404 })
+            if (typeof b.archived !== 'boolean') return new Response('archived must be true or false', { status: 400 })
+            try {
+                const on = writeArchived(r.path, b.archived)
+                // the repo moves between the two lists: the next answer measures again
+                last = null
+                return Response.json({ archived: on })
+            } catch (e) {
+                return new Response((e as Error).message, { status: 409 })
+            }
+        }
         if (path === '/api/projects/order' && req.method === 'POST') {
             if (repos.length === 0) await answer()
             const b = (await req.json().catch(() => ({}))) as { names?: unknown }
@@ -352,6 +418,20 @@ export function projectGutter(d: GutterDeps) {
                 return new Response(`the order could not be saved to ${orderFile}: ${(e as Error).message}`, { status: 500 })
             }
         }
+        if (path === '/api/projects/fork' && req.method === 'POST') {
+            if (repos.length === 0) await answer()
+            const b = (await req.json().catch(() => ({}))) as { name?: unknown }
+            const name = typeof b.name === 'string' ? b.name : ''
+            if (archivedRepos.some((r) => r.name === name)) return new Response(`${name} is archived: unarchive it first`, { status: 409 })
+            const r = find(name)
+            if (r == null) return new Response(`not a house repo: ${JSON.stringify(b.name ?? '')}`, { status: 404 })
+            try {
+                ;(d.fork ?? openInFork)(r.path)
+            } catch (e) {
+                return new Response((e as Error).message, { status: 400 })
+            }
+            return Response.json({ ok: true })
+        }
         if (path === '/api/projects/open' && req.method === 'POST') {
             if (repos.length === 0) await answer()
             const b = (await req.json().catch(() => ({}))) as { name?: string }

package/src/serve/project-gutter.ts

@@ -2,7 +2,7 @@
 // read of each one: which folders VS Code has open, which Claude Code
 // sessions run in which repo, its open asks, its distance to the last
 // release, its declared live url, its run record and its hub port. The
-// project gutter and the live strip both list repos through houseRepos, so
+// project gutter and the dock both list repos through houseRepos, so
 // the two surfaces show the same repos by construction. The parsers read
 // text they are handed, so sample output pins them; project-gutter-route.ts
 // and other-repos.ts own the spawns, the reads and the caches.
@@ -13,11 +13,11 @@ import { gitRoot } from '../core/git-root.ts'
 import { DB_FILE } from '../ledger/db.ts'
 import { defaultHubPort } from './hub-port.ts'
 import { LAYOUT } from '../core/layout.ts'
+import { isArchived } from '../core/archived.ts'
+import { CLAUDE_FILES } from '../home/pm-inputs.ts'
 
 export type WiredRepo = { name: string; path: string; icon: string | null }
 
-/** the files a repo carries its includes in */
-const CLAUDE_FILES = ['CLAUDE.md', 'CLAUDE.local.md']
 
 /** the absolute md file of every `@<path>.md` include line a repo's CLAUDE
  *  files carry, in order. A sentence that mentions a path is no include */
@@ -72,11 +72,16 @@ export function wiredRepos(parent: string, index: string, home: string): WiredRe
 
 /** the house repos around the repo at `root`: its main checkout (`home`),
  *  the house index its own includes name, and every sibling that includes the
- *  same index, `home` among them. No index = no repos */
-export function houseRepos(root: string, userHome: string): { home: string; index: string | null; repos: WiredRepo[] } {
+ *  same index, `home` among them. No index = no repos. An archived repo
+ *  (`archived: true`, core/archived.ts) is never in `repos`, so nothing that
+ *  lists through here processes it: it is in `archived`, which only the
+ *  archived page reads */
+export function houseRepos(root: string, userHome: string): { home: string; index: string | null; repos: WiredRepo[]; archived: WiredRepo[] } {
     const home = homeRepo(root)
     const index = houseIndex(home, userHome)
-    return { home, index, repos: index == null ? [] : wiredRepos(dirname(home), index, userHome) }
+    const all = index == null ? [] : wiredRepos(dirname(home), index, userHome)
+    const archived = all.filter((r) => isArchived(r.path))
+    return { home, index, repos: all.filter((r) => !archived.includes(r)), archived }
 }
 
 /** the checkout a linked worktree belongs to, so a hub started in a worktree
@@ -289,15 +294,31 @@ export function branchOf(head: string): string | null {
 /** `git status --porcelain`: one line per changed or untracked path */
 export const dirtyCount = (porcelain: string): number => porcelain.split('\n').filter((l) => l.trim() !== '').length
 
-/** the last gate as its record holds it: green, or the checks whose last
- *  outcome failed. No row at all = unknown */
-export type Gate = 'green' | { reds: string[] } | null
-export function gateOf(rows: { id: string; status: string }[]): Gate {
-    if (rows.length === 0) return null
-    const reds = rows.filter((r) => r.status === 'fail').map((r) => r.id).sort()
-    return reds.length === 0 ? 'green' : { reds }
+/** a check's last outcome as the run record keeps it */
+export type LastRow = { id: string; status: string; at?: number }
+
+/** every check's last outcome in one colour: red when one failed, orange
+ *  when one only warned, green when all passed or skipped, with when each
+ *  red or warning was recorded. Only the ids the repo declares today count
+ *  (`declared`; null = not known, every row counts), so a renamed or deleted
+ *  check never holds a repo red. No row left = unknown */
+export type CheckState = { state: 'red' | 'orange' | 'green'; reds: string[]; warns: string[]; since: Record<string, number> } | null
+export function checkStateOf(rows: LastRow[], declared: ReadonlySet<string> | null = null): CheckState {
+    const live = declared == null ? rows : rows.filter((r) => declared.has(r.id))
+    if (live.length === 0) return null
+    const reds = live.filter((r) => r.status === 'fail').map((r) => r.id).sort()
+    const warns = live.filter((r) => r.status === 'warn').map((r) => r.id).sort()
+    const since: Record<string, number> = {}
+    for (const r of live) if ((r.status === 'fail' || r.status === 'warn') && typeof r.at === 'number') since[r.id] = r.at
+    return { state: reds.length > 0 ? 'red' : warns.length > 0 ? 'orange' : 'green', reds, warns, since }
 }
 
+/** the last gate: green, or the checks whose last outcome failed, read off
+ *  the same state. Unknown when no declared row is left */
+export type Gate = 'green' | { reds: string[] } | null
+export const gateFrom = (c: CheckState): Gate => (c == null ? null : c.reds.length === 0 ? 'green' : { reds: c.reds })
+export const gateOf = (rows: LastRow[], declared: ReadonlySet<string> | null = null): Gate => gateFrom(checkStateOf(rows, declared))
+
 /** the tag shapes a release leaves: `v1.2.3`, `name@1.2.3` (the shipkit
  *  defaults) and a bare `1.2.3`. A date or a merge marker is no release */
 export const RELEASE_TAGS = ['v[0-9]*', '*@[0-9]*', '[0-9]*.[0-9]*']

package/src/serve/readme-route.ts

@@ -0,0 +1,57 @@
+// the repo's README for the hub page's empty state, and the images it points
+// at. A file answers only when it is an image AND sits inside the repo root
+// once symlinks resolve: the route must never become a way to read the disk
+import { existsSync, realpathSync, statSync } from 'fs'
+import { extname, isAbsolute, join, relative, resolve } from 'path'
+
+const README_NAMES = ['README.md', 'readme.md', 'Readme.md', 'README.markdown', 'README']
+
+const IMAGE_TYPES: Record<string, string> = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+}
+
+/** the README file name at the root, null when the repo has none */
+export function findReadme(root: string): string | null {
+    return README_NAMES.find((n) => existsSync(join(root, n)) && statSync(join(root, n)).isFile()) ?? null
+}
+
+/** an image under the root, or null for anything else: another type, a
+ *  missing file, `..`, an absolute path, a symlink that leaves the root */
+export function readmeAsset(root: string, rel: string): { path: string; type: string } | null {
+    if (rel === '' || isAbsolute(rel) || rel.includes('\0')) return null
+    const type = IMAGE_TYPES[extname(rel).toLowerCase()]
+    if (type == null) return null
+    const abs = resolve(root, rel)
+    if (!existsSync(abs)) return null
+    const real = realpathSync(abs)
+    const inside = relative(realpathSync(root), real)
+    if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) return null
+    if (!statSync(real).isFile()) return null
+    return { path: real, type }
+}
+
+/** `/api/readme.json` and `/api/readme-file/<path>`, null for any other path */
+export async function readmeRoutes(root: string, path: string): Promise<Response | null> {
+    if (path === '/api/readme.json') {
+        const file = findReadme(root)
+        return Response.json({ file, md: file == null ? null : await Bun.file(join(root, file)).text() })
+    }
+    const prefix = '/api/readme-file/'
+    if (!path.startsWith(prefix)) return null
+    let rel: string
+    try {
+        rel = decodeURIComponent(path.slice(prefix.length))
+    } catch {
+        return new Response('bad path encoding', { status: 400 })
+    }
+    const asset = readmeAsset(root, rel)
+    if (asset == null) return new Response(`not an image inside this repo: ${rel}`, { status: 404 })
+    return new Response(Bun.file(asset.path), { headers: { 'content-type': asset.type, 'cache-control': 'no-cache' } })
+}

package/src/serve/serve-hub.ts

@@ -20,6 +20,7 @@ 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 { PlanRow } from '../plan/planner.ts'
@@ -32,6 +33,7 @@ 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 }
 
@@ -85,11 +87,11 @@ export type HubDeps = {
     /** 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[]>
@@ -323,12 +325,12 @@ export function hubHandler(d: HubDeps, o: { base?: string; projects?: Gutter } =
                 }
             }
             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 (timeline == null) return new Response('this hub keeps no run record', { status: 404 })
@@ -347,6 +349,9 @@ export function hubHandler(d: HubDeps, o: { base?: string; projects?: Gutter } =
                     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 })

package/src/serve/tracked-watch.ts

@@ -2,7 +2,8 @@
 // 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 { watch, type FSWatcher } from 'fs'
+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'
@@ -46,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
@@ -74,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()
@@ -86,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

@@ -1,12 +1,21 @@
 // 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`.
+// stamp, its age) while a page reads it, and served from memory. A cell
+// nobody read for WARM_WATCH_MS computes nothing on a save: its next reader
+// waits on one compute instead, so an unwatched repo costs no cpu per save.
 //
-// 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.
+// the one constraint a reader breaks first: `get()` from a watched cell
+// 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.
+
+/** a cell read within this long has a reader: a save recomputes it in the
+ *  background. Past it, nothing recomputes until a reader asks */
+export const WARM_WATCH_MS = 30_000
+
+/** a background recompute waits this many times the last compute's length
+ *  after it ended: a 1.5s answer at most every 15s, a 50ms one at once */
+export const WARM_SPACING = 10
 
 export type WarmCellOpts = {
     /** a cheap fingerprint of what the answer reads (file stats): a new one
@@ -20,6 +29,10 @@ export type WarmCellOpts = {
 
 export class WarmCell<T> {
     private value: { v: T; at: number; stamp: string } | null = null
+    /** when a reader last asked, null before any */
+    private readAt: number | null = null
+    /** when the last compute ended and how long it took */
+    private last: { end: number; ms: number } | null = null
     private running: Promise<T> | null = null
     /** bumped by invalidate: a compute that started before it is stale */
     private gen = 0
@@ -37,6 +50,7 @@ export class WarmCell<T> {
         const gen = this.gen
         const stamp = this.o.stamp?.() ?? ''
         this.runGen = gen
+        const start = this.now()
         const p = (async (): Promise<T> => {
             try {
                 // never synchronously: `running` is set before this settles
@@ -44,6 +58,8 @@ export class WarmCell<T> {
                 this.value = { v, at: this.now(), stamp }
                 return v
             } finally {
+                const end = this.now()
+                this.last = { end, ms: end - start }
                 this.running = null
                 // what said it moved while this ran is not in this answer
                 if (this.gen !== gen) this.kick()
@@ -53,11 +69,19 @@ export class WarmCell<T> {
         return p
     }
 
-    /** a compute in the background: on a failure the last answer stays */
+    /** a compute in the background, at most once per WARM_SPACING times the
+     *  last one: a kick too soon is dropped, and the next read past the gap
+     *  kicks again. On a failure the last answer stays */
     private kick(): void {
+        if (this.last != null && this.now() < this.last.end + WARM_SPACING * this.last.ms) return
         void this.run().catch(() => {})
     }
 
+    /** a reader asked within WARM_WATCH_MS */
+    private get watched(): boolean {
+        return this.readAt != null && this.now() - this.readAt < WARM_WATCH_MS
+    }
+
     get stale(): boolean {
         const v = this.value
         if (v == null) return true
@@ -68,23 +92,32 @@ export class WarmCell<T> {
     /** 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 watched = this.watched
+        this.readAt = this.now()
+        if (o.fresh === true) return this.fresh()
         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()
+        const moved = this.stale || this.gen !== this.runGen
+        // the first reader in a while: what is in memory may be hours old,
+        // and no save recomputed it meanwhile
+        if (moved && !watched) return this.running != null && this.runGen === this.gen ? this.running : this.fresh()
+        if (this.running == null && moved) this.kick()
         return v.v
     }
 
-    /** something this answer reads moved: recompute in the background */
+    /** a compute that started after this call: one that started before may
+     *  miss what the caller just changed, so wait for it, then for our own */
+    private async fresh(): Promise<T> {
+        if (this.running != null) await this.running.catch(() => {})
+        return this.run()
+    }
+
+    /** something this answer reads moved: recompute in the background while
+     *  a reader watches, else leave it to the next reader */
     invalidate(): void {
         this.gen++
-        if (this.running == null) this.kick()
+        if (this.running == null && this.watched) this.kick()
     }
 
     /** compute now unless an answer is already in memory: the hub's load */