rvlib-shipkit 1.2.0 → 1.3.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,6 +13,7 @@ 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'
 
 export type WiredRepo = { name: string; path: string; icon: string | null }
 
@@ -72,11 +73,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 +295,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/shipkit-files.ts

@@ -49,9 +49,9 @@ export type GlobalProcessDef = {
     probe?: string
     /** a button each beside the switch, by key */
     actions?: Record<string, ProcessAction>
-    /** with `url`: open it as a shipkit app window. Starting it from the
-     *  page opens that window once it answers, in one go */
-    app?: boolean
+    /** what its card wears: an emoji, or a repo-relative image path
+     *  (png, svg, ico, jpg, webp). Absent: the declaring repo's own icon */
+    icon?: string
 }
 
 export type WidgetDef = {
@@ -74,6 +74,19 @@ const KEBAB = /^[a-z0-9][a-z0-9-]*$/
 const words = (v: unknown): boolean => Array.isArray(v) && v.length > 0 && v.every((w) => typeof w === 'string')
 const httpUrl = (v: unknown): boolean => typeof v === 'string' && /^https?:\/\//.test(v)
 
+/** the image types an icon file can be, by extension */
+export const ICON_IMAGE_TYPES: Record<string, string> = { png: 'image/png', svg: 'image/svg+xml', ico: 'image/x-icon', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp' }
+
+/** the image an icon names (its extension), or null when it is text */
+export const iconImageType = (icon: string): string | null => ICON_IMAGE_TYPES[/\.([a-z]+)$/i.exec(icon)?.[1]?.toLowerCase() ?? ''] ?? null
+
+function iconProblem(icon: unknown): string | null {
+    if (typeof icon !== 'string' || icon.trim() === '') return 'icon is an emoji or a repo relative image path'
+    if (iconImageType(icon) != null) return icon.startsWith('/') || icon.split(/[\\/]/).includes('..') ? `icon '${icon}' must be a repo relative path` : null
+    if (/[\\/.]/.test(icon) || [...icon].length > 8) return `icon '${icon}' is neither an emoji nor an image path (${Object.keys(ICON_IMAGE_TYPES).join(', ')})`
+    return null
+}
+
 /** why a global process declaration cannot run, or null */
 export function globalProcessProblem(d: GlobalProcessDef): string | null {
     const at = `globalProcess '${String(d.id)}'`
@@ -83,7 +96,10 @@ export function globalProcessProblem(d: GlobalProcessDef): string | null {
     if (d.url != null && !httpUrl(d.url)) return `${at}: url must be an http url`
     if (d.probe != null && !httpUrl(d.probe)) return `${at}: probe must be an http url`
     if (d.down != null && d.probe == null && d.url == null) return `${at}: a bring-up (one with down) needs probe or url, the only truth of whether it is up`
-    if (d.app === true && d.url == null) return `${at}: app needs a url to open`
+    if (d.icon !== undefined) {
+        const why = iconProblem(d.icon)
+        if (why != null) return `${at}: ${why}`
+    }
     for (const [k, a] of Object.entries(d.actions ?? {})) {
         if (!KEBAB.test(k)) return `${at}: action '${k}' must be kebab-case`
         if ((a.cmd != null) === (a.run != null)) return `${at}: action '${k}' declares exactly one of cmd or run`

package/src/checks/SK023-stores-under-cap.check.ts

@@ -1,49 +0,0 @@
-// SK023 stores under cap (core/retention.ts owns the caps): every store shipkit
-// writes for this repo, and the machine's own when a home dir exists, is
-// inside its declared cap plus the drift one sweep interval allows. Red means
-// the daemon's hourly sweep stopped running, or a store grows faster than its
-// cap assumes. The fix runs the sweep.
-import { existsSync } from 'fs'
-import { check } from '../check.ts'
-import { fmtAge, fmtBytes, measureStores, repoStores, sweepStores, type Store } from '../core/retention.ts'
-import { homeDir } from '../home/home-paths.ts'
-import { machineStores } from '../home/machine-stores.ts'
-
-const storesOf = (root: string): Store[] => [...repoStores(root), ...(existsSync(homeDir()) ? machineStores(homeDir()) : [])]
-
-const capWords = (s: Store): string =>
-    [
-        s.cap.maxCount != null ? `${s.cap.maxCount} entries` : null,
-        s.cap.maxAgeMs != null ? fmtAge(s.cap.maxAgeMs) : null,
-        s.cap.maxFileBytes != null ? `${fmtBytes(s.cap.maxFileBytes)} a file` : null,
-        s.cap.maxBytes != null ? fmtBytes(s.cap.maxBytes) : null,
-    ].filter((x) => x != null).join(', ')
-
-export const storesUnderCap = check({
-    id: 'SK023',
-    blocking: false,
-    title: 'stores under cap',
-    description: 'every store shipkit writes (answers, run record, logs, jobs) is inside its cap',
-    owner: 'build/shipkit/built-in-checks.md',
-    when: 'health',
-    run: (c) => {
-        const all = measureStores(storesOf(c.root))
-        const over = all.filter((m) => m.over != null)
-        const unread = all.filter((m) => m.use == null)
-        for (const m of over) c.fail(`${m.store.id} over its cap: ${m.over} (${m.store.where})`, 'shipkit check --fix SK023 runs the sweep the daemon runs hourly')
-        for (const m of unread) c.warn(`${m.store.id} could not be read (${m.store.where})`)
-        if (over.length === 0) c.ok(`${all.length} stores inside their caps: ${all.map((m) => `${m.store.id} ${m.use?.count ?? '?'} (cap ${capWords(m.store)})`).join(', ')}`)
-    },
-    fix: async (c) => {
-        const stores = storesOf(c.root)
-        const before = measureStores(stores).filter((m) => m.over != null)
-        const r = await sweepStores(stores)
-        const broke = r.filter((x) => x.error != null)
-        return {
-            changed: before.length > 0,
-            summary: `swept ${stores.length} stores${before.length > 0 ? `, ${before.map((m) => m.store.id).join(', ')} were over` : ''}${broke.length > 0 ? `; failed: ${broke.map((x) => `${x.id} (${x.error})`).join(', ')}` : ''}`,
-        }
-    },
-})
-
-export default storesUnderCap

package/src/checks/contracts.check.ts

@@ -1,20 +0,0 @@
-// the contracts check — `.shipkit/*` release-contract fulfillness. It shares ONE
-// evaluation with check SK002 (the `contractsResult` scan), and it tags with
-// that id, because the invariant has one owner and two surfaces report it. A
-// venue deploy step deps on it BY NAME, which needs nothing from this end.
-import { applyContractsResult, contractsResult } from '../contracts/apply-contracts.ts'
-import { check } from '../check.ts'
-import { contractsFulfillness } from './SK002-contracts-fulfillness.check.ts'
-
-export const contractsCheck = check({
-    id: 'contracts',
-    title: 'contracts',
-    description: 'every declared venue has the `.shipkit/*` release contract it demands',
-    owner: 'meta/contracts.md',
-    blocking: true,
-    run: async (c) => {
-        applyContractsResult(c, await c.use(contractsResult), contractsFulfillness)
-    },
-})
-
-export default contractsCheck