rvlib-shipkit 1.1.0 → 1.2.0

package/src/serve/hub-runtime.ts

@@ -0,0 +1,542 @@
+// one repo's hub, alive: its deps resolved from repo.config.ts, its request
+// handler, the save watch over its tracked files, its declared processes,
+// and its RED pings. No server and nothing process wide: `shipkit serve` puts
+// one behind a Bun.serve of its own (run-serve.ts), the daemon runs one per
+// house repo behind /r/<repo>/ of its one server (home/hubs.ts).
+//
+// the one constraint a reader breaks first: a hub starts no run on its own.
+// It joins the host's plan (plan/planner.ts), which decides what runs when,
+// and a save only tells the plan that something moved.
+//
+// what mounts comes from convention + repo.config's `serve` block: the wiki
+// graph is always on (custom provider via serve.wikiGraph, else the generic md
+// scan), the base-context wiki when a CLAUDE.md include names one, agent/
+// graph when the dir exists, the studio when .shipkit/assets/kit.ts loads.
+// Port of a hub serving on its own: --port > serve.port > a deterministic
+// house-range default (4800-4979, hashed from the repo name, stable across
+// launches; pin serve.port when two repos collide).
+import { existsSync, readFileSync, statSync } from 'fs'
+import { homedir } from 'os'
+import { basename, dirname, join, resolve, sep } from 'path'
+import { loadKit, type ResolvedKit } from '../assets/kit-config.ts'
+import { studioRoutes, type StudioRoutes } from '../assets/server/studio-server.ts'
+import { projectNeeds } from '../collections/collection-types.ts'
+import { comfyCollection } from '../collections/comfy.ts'
+import { ComfyPanel, comfyBox, defaultComfyPanelPort, scanComfyWorkflows } from '../comfy/comfy-panel.ts'
+import { wikisCollection } from '../collections/wikis.ts'
+import { pingTick } from '../collections/pings.ts'
+import { buildCollections } from '../collections/providers.ts'
+import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
+import { CheckCtx } from '../core/check-ctx.ts'
+import { proseView } from '../prose/prose-view.ts'
+import { allTasks, gateInventory } from '../ledger/gate-checks.ts'
+import { runCheck, type CheckEvent } from '../core/run-check.ts'
+import { runCi, type CiOpts } from '../core/run-ci.ts'
+import type { GraphMount } from '../wiki/graph-mount.ts'
+import { scanMdGraph } from '../wiki/scan-md.ts'
+import { readInvocations, readLive, readRuns, readRunsSince, runsPath, sweepLive } from '../ledger/run-log.ts'
+import { LIVE_HISTORY_MS, shapeLive, type LiveView } from '../ledger/live-timeline.ts'
+import { parallelCap } from '../core/parallel.ts'
+import { autoGatePool, takeSlot } from '../core/slots.ts'
+import { liveJobs, startJob } from '../core/jobs.ts'
+import { followJob } from '../core/job-follow.ts'
+import { RUN_JOB } from '../home/home-words.ts'
+import { OtherRepos } from './other-repos.ts'
+import { recordStamp } from './project-gutter.ts'
+import { RepoProcesses } from './repo-processes.ts'
+import { shapeTimeline } from '../ledger/run-timeline.ts'
+import { readSuiteRuns, readSuites } from '../ledger/suite-log.ts'
+import { shapeTestCheck, shapeTestsRoot } from '../collections/test-time.ts'
+import type { TestFacts } from '../collections/collection-types.ts'
+import { declaredSlowFiles } from '../suite/test-units.ts'
+import { BUILD_TIMEOUT_MS, CHECK_TIMEOUT_MS } from '../collections/checks.ts'
+import { watchTracked } from './tracked-watch.ts'
+import { repoSource } from '../plan/repo-source.ts'
+import type { PlanSource, Planner } from '../plan/planner.ts'
+import { ProblemBoard } from '../problems/problem-board.ts'
+import { HubProblems } from './hub-problems.ts'
+import { hubHandler, type CheckTap, type HubDeps, type HubHandler } from './serve-hub.ts'
+import type { projectGutter } from './project-gutter-route.ts'
+import { defaultHubPort } from './hub-port.ts'
+import { LAYOUT } from '../core/layout.ts'
+export { defaultHubPort }
+
+export type ServeIo = { print: (l: string) => void; printErr: (l: string) => void }
+
+
+// the BASE-CONTEXT wiki: the shared wiki this repo's CLAUDE.md include chain
+// points at (`@~/dev/<other-repo>/wiki/index.md`). It lives in ANOTHER repo and
+// binds every agent working here, so the hub makes it browsable. Never linted
+// from here. The local-include forms (`@./agent/index.md`,
+// `@./CLAUDE.local.md`) and any index inside this repo are skipped: those are
+// already their own mounts.
+export function baseWikiRoot(root: string): string | null {
+    const abs = resolve(root)
+    for (const f of ['CLAUDE.md', 'CLAUDE.local.md', 'CLAUDE.private.md']) {
+        const p = join(abs, f)
+        if (!existsSync(p)) continue
+        for (const line of readFileSync(p, 'utf8').split('\n')) {
+            const m = line.trim().match(/^@(\S+\.md)$/)
+            if (m == null) continue
+            const raw = m[1]!
+            const target = resolve(abs, raw.startsWith('~/') ? join(homedir(), raw.slice(2)) : raw)
+            const dir = dirname(target)
+            if (!existsSync(target)) continue
+            if (dir === abs || dir.startsWith(abs + sep)) continue
+            return dir
+        }
+    }
+    return null
+}
+
+// `~/dev/<repo>/wiki` reads as "<repo> wiki" — a dir literally named wiki says
+// nothing on its own, so the owning repo names the card
+/** the tab of the repo's own wiki, beside the house wiki named for its repo */
+const WIKI_LABEL = "this repo's wiki"
+const wikiLabel = (dir: string): string => (basename(dir) === 'wiki' ? `${basename(dirname(dir))} wiki` : basename(dir))
+
+/** the config file's bytes, cheaply: a re-read costs a new module instance,
+ *  so it happens only when the file really moved */
+export function configStamp(root: string): string {
+    try {
+        const st = statSync(join(root, 'repo.config.ts'))
+        return `${st.mtimeMs}:${st.size}`
+    } catch {
+        return ''
+    }
+}
+
+/** a host that runs every gate as a detached job (the daemon): the cli the
+ *  job runs, so a reload of the host never kills a gate in flight */
+export type GateJobs = { cli: string; pollMs?: number }
+
+export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo, o?: { port?: number; base?: string; jobs?: GateJobs; planName?: string }): Promise<HubDeps & { plan: PlanSource }> {
+    // THE SWITCH WRITES repo.config.ts, so the surfaces built on the config
+    // read the one on disk rather than the one this process booted with. A
+    // toggle that never reached the rows would read as a toggle that did
+    // nothing. What is resolved ONCE stays once: the kit, the graphs, the
+    // studio and the comfy panel are mounts, and remounting a server under a
+    // live page is a different question from re-reading a declaration.
+    let c = boot
+    let stamp = configStamp(root)
+    const refresh = async (): Promise<void> => {
+        const now = configStamp(root)
+        if (now === stamp || now === '') return
+        stamp = now
+        try {
+            c = await loadRepoConfig(root, { fresh: true })
+        } catch (e) {
+            io.print(`WARN repo.config.ts did not load, so the page is reading the one this process booted with — ${(e as Error).message}`)
+        }
+    }
+
+    // ONE list: the routes, the /hub.json tools and the wikis section all
+    // read it, so nothing can advertise a graph the server does not serve.
+    // The repo's OWN wiki mounts when it has one (a game repo's hub
+    // advertising an empty wiki route was startup noise), a config-declared
+    // provider always mounts, and the base-context wiki (the shared one named
+    // by the CLAUDE.md include chain) mounts wherever it is reachable: an
+    // agent working here obeys that wiki, so a reader can open it.
+    const graphs: GraphMount[] = []
+    if (c.serve?.wikiGraph != null)
+        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load, lint: c.serve.wikiGraph.lint != null ? { checks: c.serve.wikiGraph.lint } : { root } })
+    else if (existsSync(join(root, 'wiki')))
+        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: `${c.name} wiki`, load: () => scanMdGraph({ root }), lint: { root } })
+    const baseWiki = baseWikiRoot(root)
+    if (baseWiki != null)
+        graphs.push({ id: 'base', label: wikiLabel(baseWiki), title: wikiLabel(baseWiki), load: () => scanMdGraph({ root: baseWiki }), lint: null })
+    const agentRoot = join(root, 'agent')
+    if (existsSync(agentRoot))
+        graphs.push({ id: 'agent', label: 'agent/', title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }), lint: { root: agentRoot, index: c.serve?.agentIndex } })
+    // ONE page for every repo: the studio ALWAYS
+    // mounts — kit-less repos get an empty media section, never a second
+    // page. A broken kit degrades to the same empty kit, loudly.
+    let kit: ResolvedKit | null = null
+    if (existsSync(join(root, '.shipkit/assets/kit.ts'))) {
+        try {
+            kit = await loadKit(root)
+        } catch (e) {
+            io.print(`WARN kit not loaded (media section empty): ${(e as Error).message}`)
+        }
+    }
+    const emptyKit: ResolvedKit = { kinds: [], workspace: '.shipkit/assets/out' }
+    let studio: StudioRoutes | null = null
+    try {
+        studio = await studioRoutes({ kit: kit ?? emptyKit, root })
+    } catch (e) {
+        io.print(`WARN media API not mounted: ${(e as Error).message}`)
+    }
+    // a repo with no workflow module gets NO comfy section and no panel
+    // process: an empty section header is a surface that teaches nothing
+    const hasComfy = scanComfyWorkflows(root).length > 0
+    const panel = hasComfy ? new ComfyPanel({ root, port: c.serve?.comfyPort ?? defaultComfyPanelPort(c.name) }) : null
+    const allCollections = () => [
+        ...buildCollections(root, c, kit),
+        ...(hasComfy ? [comfyCollection(root)] : []),
+        wikisCollection(graphs, root),
+    ]
+    const port = o?.port ?? c.serve?.port ?? defaultHubPort(c.name)
+    // every run this process has going, whoever started it
+    let active = 0
+    // ONE run at a time, whoever asked: two gates over one tree would measure
+    // the same checks twice and race each other's repair pass
+    let chain: Promise<unknown> = Promise.resolve()
+    // the latest verdict of every check, printed as one problem frame after
+    // each run for the vscode problems pane (problems/problem-line.ts)
+    const board = new ProblemBoard()
+    // what is wrong with the hub itself rides the same frame, the moment it
+    // moves, so the pane never reads 0 while the page shows a hub red
+    const hubProblems = new HubProblems((all) => {
+        if (board.setHub(all)) for (const l of board.frame()) io.print(l)
+    })
+    const jobs = o?.jobs ?? null
+    // the frame the problems pane reads: one per verdict that moved the board
+    const onBoard = (e: CheckEvent): void => { if (board.take(e)) for (const l of board.frame()) io.print(l) }
+    // ONE way a run executes. In process for a hub of its own; as a detached
+    // job in the daemon, which follows it: its lines and verdicts reach the
+    // same taps, and a reload of the daemon leaves it running
+    const exec = async (kind: 'ci' | 'check', opts: Record<string, unknown>, tap: CheckTap, background: boolean): Promise<number> => {
+        if (jobs == null) {
+            const turn = background ? await takeSlot(autoGatePool(), { repo: c.name, check: 'auto gate' }, { pollMs: 250 }) : null
+            try {
+                if (kind === 'ci') return await runCi(root, { ...(opts as CiOpts), print: tap.line, config: c, onCheck: tap.check })
+                return await runCheck(root, { ...(opts as Parameters<typeof runCheck>[1]), print: tap.line, config: c, onCheck: tap.check })
+            } finally {
+                turn?.release()
+            }
+        }
+        // a job still running here, started before this image or by a terminal's --detach
+        while (liveJobs(root).length > 0) await Bun.sleep(jobs.pollMs ?? 250)
+        const j = startJob(root, { cli: jobs.cli, kind, args: [], job: { opts, oneLib: true, turn: background } })
+        tap.job?.(j.id)
+        return (await followJob(root, j.id, tap, { pollMs: jobs.pollMs })) ?? 1
+    }
+    const runChecks: HubDeps['runChecks'] = (tap, o) => {
+        const run = chain.then(async () => {
+            active++
+            // a run the hub starts on its own takes the machine's background
+            // turn, once it is this hub's turn, never while it queues
+            const background = o?.auto === true
+            try {
+                return await runIn({
+                    ...tap,
+                    check: (e) => {
+                        // a frame per verdict that moved the board, so a tsc
+                        // error reaches the pane when typecheck ends rather
+                        // than when the whole gate does
+                        onBoard(e)
+                        tap.check(e)
+                    },
+                }, o, background)
+            } finally {
+                active--
+                // and one per run, so every run ends on a frame
+                for (const l of board.frame()) io.print(l)
+            }
+        })
+        chain = run.catch(() => {})
+        return run
+    }
+    // a `shipkit ci` or `shipkit check` from a terminal, run HERE (home/via-hub.ts):
+    // in the same one-at-a-time chain as the hub's own runs, feeding the same
+    // problems frame, recorded as the cli's
+    const runCli: HubDeps['runCli'] = (kind, opts, print) => {
+        // never on a --json run: its output is the json and nothing else
+        if ((active > 0 || (jobs != null && liveJobs(root).length > 0)) && opts.json !== true) print('note: this hub has a run in flight, so this one starts when it ends')
+        const run = chain.then(async () => {
+            active++
+            try {
+                await refresh()
+                return await exec(kind, { ...opts, invokedBy: 'cli' }, { line: print, check: onBoard, job: (id) => print(`${RUN_JOB}${id}`) }, false)
+            } finally {
+                active--
+                for (const l of board.frame()) io.print(l)
+            }
+        })
+        chain = run.catch(() => {})
+        return run
+    }
+    const runIn = async (tap: CheckTap, o: Parameters<HubDeps['runChecks']>[1], background: boolean): Promise<number> => {
+        const only = o?.only != null && o.only.length > 0 ? o.only : undefined
+        const by = o?.by ?? 'hub'
+        const buildIds = new Set((await allTasks(c, root)).tasks.map((t) => t.id))
+        const namedTasks = (only ?? []).filter((id) => buildIds.has(id))
+        // ONE runner, two questions: a build step is the gate's, so
+        // anything naming one (or asking for the gate itself) goes through
+        // runCi, and a set of everything else takes the health pass
+        if (o?.gate === true || namedTasks.length > 0)
+            return exec('ci', { ...hubGateOpts({ only, auto: o?.auto === true }), buildOnly: only != null && namedTasks.length === only.length, invokedBy: by }, tap, background)
+        // a NARROWED check run must not stamp STATUS.md: that file carries
+        // the verdict of a whole run, and one check is not one
+        return exec('check', { only, status: only == null, invokedBy: by }, tap, background)
+    }
+    // a daemon image that boots while a job of its previous image still runs
+    // follows it to its end: its verdicts reach the problems pane, and the
+    // next run queues behind it
+    if (jobs != null) {
+        const adopted = liveJobs(root)
+        if (adopted.length > 0) {
+            io.print(`ok: following ${adopted.length} gate job(s) still running: ${adopted.map((j) => j.id).join(', ')}`)
+            active++
+            const run = Promise.all(adopted.map((j) => followJob(root, j.id, { line: () => {}, check: onBoard }, { pollMs: jobs.pollMs }))).finally(() => {
+                active--
+                for (const l of board.frame()) io.print(l)
+            })
+            chain = run.catch(() => {})
+        }
+    }
+    // resolved once: it shells out to git, and the page asks on every poll
+    let record = ''
+    try { record = runsPath(root) } catch { record = '' }
+    // nothing runs in this process yet, so a live row holding its pid was
+    // left by an earlier image of it: `bun --watch` restarts in place
+    if (record !== '') sweepLive(record, Date.now(), { ownPid: process.pid })
+    // the live strip asks every second, from every open tab: the record is
+    // read only when its files moved, and one shaped answer serves every
+    // request inside LIVE_SHARE_MS
+    const others = new OtherRepos(root)
+    let local: { stamp: string; at: number; live: ReturnType<typeof readLive>; runs: ReturnType<typeof readRunsSince>; invocations: ReturnType<typeof readInvocations> } | null = null
+    let shaped: { at: number; view: LiveView } | null = null
+    const LIVE_SHARE_MS = 500
+    const live = (): LiveView => {
+        const now = Date.now()
+        if (shaped != null && now - shaped.at < LIVE_SHARE_MS) return shaped.view
+        const stamp = recordStamp(record)
+        // the window slides even when nothing is written, so the history is
+        // re-read at least every few seconds
+        if (local == null || local.stamp !== stamp || now - local.at > 5_000) {
+            const since = now - LIVE_HISTORY_MS
+            local = { stamp, at: now, live: readLive(record), runs: readRunsSince(record, since), invocations: readInvocations(record, since) }
+        }
+        const view = shapeLive({ now, cap: parallelCap(), live: local.live, runs: local.runs, invocations: local.invocations, others: others.read() })
+        shaped = { at: now, view }
+        return view
+    }
+    // what the plan asks of this repo: its checks, their last results, what
+    // a save moved, and a batch through this runner, in the background
+    const plan = repoSource({
+        repo: o?.planName ?? c.name,
+        root,
+        config: () => c,
+        record,
+        run: (ids, g, why) => runChecks({ line: () => {}, check: () => {} }, { only: ids, gate: g.gate, by: why === 'asked' ? 'hub' : 'schedule', auto: true }),
+    })
+    return {
+        root,
+        name: c.name,
+        uses: c.serve?.uses ?? [],
+        processes: new RepoProcesses(root, c.serve?.processes ?? []),
+        port,
+        graphs,
+        studio,
+        refresh,
+        // the config and the run record, by their stats: what the warm rows
+        // and the runs page read besides the tracked files the watch sees
+        stamp: () => `${configStamp(root)}|${record === '' ? '' : recordStamp(record)}`,
+        runCli,
+        // the run happens IN THIS PROCESS, so every check result reaches the
+        // page as it finishes. A shelled run could only ever deliver one wall
+        // of text, which is what made seventy checks share one destination
+        runChecks,
+        plan,
+        // every run in flight, whoever started it: they all write the same
+        // record, so a terminal gate shows here the same as a button's
+        live,
+        repoHub: (repo) => others.hubOf(repo),
+        timeline: async () => {
+            const ceilings: Record<string, number> = {}
+            const budgets: Record<string, number> = {}
+            const inventory = await gateInventory(root, c)
+            for (const row of inventory) {
+                ceilings[row.decl.id] = row.timeoutMs ?? (row.build ? BUILD_TIMEOUT_MS : CHECK_TIMEOUT_MS)
+                budgets[row.decl.id] = row.budgetMs
+            }
+            return shapeTimeline({
+                runs: readRuns(record),
+                invocations: readInvocations(record),
+                suites: readSuites(record),
+                ceilings,
+                budgets,
+                inventory: inventory.map((row) => row.decl.id),
+                declaredSlow: declaredSlowFiles(c),
+                cap: parallelCap(),
+            })
+        },
+        tests: async (check) => {
+            // the SAME test files the tree lists, from the same provider
+            const col = allCollections().find((x) => x.id === 'tests')
+            const facts = col == null ? [] : (await col.list()).flatMap((i): TestFacts[] => (i.test == null ? [] : [i.test]))
+            const input = { facts, runs: readRuns(record), suiteRuns: readSuiteRuns(record) }
+            return check == null || check === '' ? shapeTestsRoot(input) : shapeTestCheck(check, input)
+        },
+        prose: async () => proseView(CheckCtx.open({ root, config: c }), c),
+        needs: () => projectNeeds(allCollections(), hubProblems.collector),
+        hubProblems,
+        // a job outlives this image, so only an in process run holds a reload back
+        busy: () => jobs == null && active > 0,
+        collections: allCollections,
+        asksDir: c.asks?.dir ?? LAYOUT.asks,
+        comfy: panel == null ? null : { ensure: () => panel.ensure(), restart: () => panel.restart(), box: () => comfyBox(root), stop: () => panel.stop() },
+        // RED-only pings while serving; notify command is repo config data.
+        // Delivery failure must be LOUD — a silently broken notify path means
+        // a silent one reads as no blockers at all
+        pingTick: (needs) =>
+            pingTick(root, c.asks?.dir ?? LAYOUT.asks, needs, {
+                link: c.serve?.publicHost != null ? `http://${c.serve.publicHost}:${port}${o?.base ?? ''}/?f=needs` : undefined,
+                run: (cmd) => {
+                    const p = Bun.spawn(cmd, { stdout: 'ignore', stderr: 'pipe' })
+                    void p.exited.then(async (code) => {
+                        if (code !== 0) io.printErr(`WARN ping delivery failed (exit ${code}): ${await new Response(p.stderr).text().then((s) => s.trim().slice(0, 160))}`)
+                    })
+                },
+                notifyCommand: c.notifyCommand,
+            }),
+    }
+}
+
+/** a run the hub starts on its own waits for the machine's one background
+ *  turn (autoGatePool), so several hubs never gate at once */
+export async function inAutoTurn<T>(repo: string, run: () => Promise<T>, pool = autoGatePool()): Promise<T> {
+    const turn = await takeSlot(pool, { repo, check: 'auto gate' }, { pollMs: 250 })
+    try {
+        return await run()
+    } finally {
+        turn?.release()
+    }
+}
+
+/** how a gate the hub starts differs from `shipkit ci`. The gate repairs and
+ *  stamps STATUS.md, a narrowed run does neither: one check is not the verdict
+ *  of a gate. A run the hub starts ON ITS OWN never mutates the tree someone
+ *  is editing: no repair pass, frozen (SK005 never updates a dependency), no
+ *  status files, and the quick tier */
+export function hubGateOpts(o: { only?: string[]; auto: boolean }): Pick<CiOpts, 'onlyIds' | 'fix' | 'status' | 'frozen' | 'tests'> {
+    const whole = o.only == null
+    if (o.auto) return { onlyIds: o.only, fix: false, status: false, frozen: true, tests: 'quick' }
+    return { onlyIds: o.only, fix: whole, status: whole }
+}
+
+/** how often the RED ping looks, on a hub that owns its timers */
+export const PING_EVERY_MS = 60_000
+
+export type HubRuntime = {
+    name: string
+    config: RepoConfig
+    deps: HubDeps
+    handler: HubHandler
+    /** the live half: the save watch, its place in the plan, the declared
+     *  processes, and the ping interval when the runtime owns it. Nothing
+     *  runs before it, so a hub that could not bind its port started nothing */
+    start: () => void
+    /** one RED ping tick */
+    ping: () => Promise<void>
+    /** a run is in flight: a reload now would kill it */
+    busy: () => boolean
+    /** everything this runtime started stops, and it leaves the plan. `procs`
+     *  also stops the repo's declared processes: a real stop of the hub,
+     *  never a process restart */
+    stop: (o?: { procs?: boolean }) => void
+}
+
+export type LoadHubOpts = {
+    /** where the page sits on the server that answers: '' or '/r/<repo>' */
+    base?: string
+    port?: number
+    /** the rail, shared when one process serves many repos */
+    projects?: ReturnType<typeof projectGutter>
+    /** the plan this hub joins: the daemon's one for the machine, or a hub
+     *  of its own's one for its repo. It decides every run nobody asked for */
+    plan: Planner
+    /** the repo's name in that plan, which the activity signals use */
+    planName?: string
+    /** a start counts as a save: the checks whose answer would not replay
+     *  run once it settles. Off where one process loads many repos */
+    gateAtStart: boolean
+    /** the ping interval runs here. Off = the host calls ping() itself */
+    ownTimers: boolean
+    /** re-import repo.config.ts rather than reuse the module already loaded */
+    fresh?: boolean
+    /** overrides where a lane click of the live strip sends another repo */
+    repoHub?: HubDeps['repoHub']
+    /** every gate runs as a detached job this host follows */
+    jobs?: GateJobs
+}
+
+/** how long a save burst settles before the warm answers recompute */
+export const WARM_SETTLE_MS = 800
+
+/** the hubs of this process warm one after the other: twenty repos walking
+ *  at once would slow the one a page is waiting on */
+let warming: Promise<void> = Promise.resolve()
+
+export async function loadHub(root: string, io: ServeIo, o: LoadHubOpts): Promise<HubRuntime> {
+    const c = await loadRepoConfig(root, { fresh: o.fresh === true })
+    const deps = await resolveHubDeps(root, c, io, { port: o.port, base: o.base, jobs: o.jobs, planName: o.planName })
+    if (o.repoHub != null) deps.repoHub = o.repoHub
+    const name = deps.plan.repo
+    deps.planned = () => o.plan.rows(name)
+    deps.ask = (check) => {
+        const ok = o.plan.ask(name, check)
+        if (ok) o.plan.tick()
+        return ok
+    }
+    const handler = hubHandler(deps, { base: o.base, projects: o.projects })
+    const procs = deps.processes
+    // tick failures are LOUD (the hub's own lines), never swallowed
+    const ping = async (): Promise<void> => {
+        if (deps.pingTick == null) return
+        try {
+            deps.pingTick(await deps.needs())
+        } catch (e) {
+            io.printErr(`WARN ping tick broke: ${(e as Error).message}`)
+        }
+    }
+    const live: { stop: () => void }[] = []
+    const start = (): void => {
+        // the plan hears every save burst and asks the ledger what it moved.
+        // The watch decides nothing: the runner measures or replays like any run
+        void o.plan.add(deps.plan).then(() => {
+            // a start is a change like a save
+            if (o.gateAtStart) o.plan.touched(name)
+        })
+        // a burst of saves is one recompute of the warm answers, once it settles
+        let settle: ReturnType<typeof setTimeout> | null = null
+        const watcher = watchTracked(root, () => {
+            o.plan.touched(name)
+            if (settle != null) clearTimeout(settle)
+            settle = setTimeout(() => handler.invalidate(), WARM_SETTLE_MS)
+        }, { onError: (e) => io.printErr(`WARN the file watch stopped, so the plan hears no save until the hub reloads: ${e.message}`) })
+        if (watcher.error != null) io.printErr(`WARN no file watch (${watcher.error}), so the plan hears no save in this repo`)
+        live.push({ stop: () => watcher.close() }, { stop: () => o.plan.remove(name) }, { stop: () => { if (settle != null) clearTimeout(settle) } })
+        // the answers a page waits on, computed now, one hub at a time
+        // across the process, so a first visit reads them from memory
+        warming = warming.then(() => handler.warm())
+        // the repo's own processes: the auto ones start, a restart adopts the
+        // ones still running from their pid records
+        void procs?.startAuto()
+        if (procs != null && procs.size > 0) {
+            const t = setInterval(() => void procs.tick(), 2_000)
+            live.push({ stop: () => clearInterval(t) })
+        }
+        if (o.ownTimers) {
+            // one tick now (the state file guarantees a restart never re-fires), then every minute
+            void ping()
+            const t = setInterval(() => void ping(), PING_EVERY_MS)
+            live.push({ stop: () => clearInterval(t) })
+        }
+    }
+    return {
+        name: c.name,
+        config: c,
+        deps,
+        handler,
+        start,
+        ping,
+        busy: () => deps.busy?.() === true,
+        stop: (s) => {
+            for (const l of live.splice(0)) l.stop()
+            if (s?.procs === true) procs?.stopAll()
+            handler.stop()
+        },
+    }
+}

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

@@ -19,6 +19,8 @@ import {
     recordOf, recordStamp, RELEASE_TAGS, renderOrder, versionOf, vscodeStoragePath, type Gate, 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'
 
 export type { Gate }
 
@@ -63,6 +65,8 @@ export type ProjectRow = {
     release: Release
     /** the deployed url `smoke.base` declares, or null */
     live: string | null
+    /** the colours its repo.config.ts declares (SK024), null when it declares none */
+    identity: Identity | null
     /** 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
@@ -278,6 +282,7 @@ export function projectGutter(d: GutterDeps) {
                 gate: gateOfRepo(r.path),
                 release: facts[i]!.release,
                 live: liveUrlOf(config),
+                identity: identityOfText(config),
                 activity: lastActivity(facts[i]!.commitAt, lastRunAt(r.path), transcripts.get(r.path)),
             }
         })
@@ -321,6 +326,22 @@ export function projectGutter(d: GutterDeps) {
                 headers: { 'content-type': ICON_TYPES[r.icon.split('.').pop()!] ?? 'application/octet-stream', 'cache-control': 'max-age=86400' },
             })
         }
+        if (path === '/api/projects/identity' && req.method === 'POST') {
+            if (repos.length === 0) await answer()
+            const b = (await req.json().catch(() => ({}))) as { name?: unknown; colorLight?: unknown; colorDark?: unknown }
+            const r = find(String(b.name))
+            if (r == null) return new Response(`not a house repo: ${String(b.name)}`, { status: 404 })
+            // a colour left out keeps the config's own, so only the sent ones are checked
+            const bad = identityProblem({ colorLight: b.colorLight ?? '#000000', colorDark: b.colorDark ?? '#000000' })
+            if (bad != null) return new Response(bad, { status: 400 })
+            try {
+                const id = writeIdentity(r.path, { colorLight: b.colorLight as string | undefined, colorDark: b.colorDark as string | undefined })
+                if (last != null) last = { ...last, projects: last.projects.map((p) => (p.name === r.name ? { ...p, identity: id } : p)) }
+                return Response.json({ identity: id })
+            } 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 }

package/src/serve/project-gutter.ts

@@ -46,8 +46,9 @@ export function houseIndex(repo: string, home: string): string | null {
     return targets.find((t) => !inside(t, repo)) ?? targets.find((t) => !basename(t).startsWith('CLAUDE')) ?? null
 }
 
-/** a repo's own icon, first hit wins. The identity kit writes the first one */
-export const ICON_FILES = ['public/favicon.png', 'public/favicon.svg', 'public/favicon.ico', 'favicon.ico', 'public/logo.png']
+/** a repo's own icon, first hit wins. `.shipkit/identity/icon.png` is the rail
+ *  icon a repo with no public surface carries, the identity kit writes public/ */
+export const ICON_FILES = ['.shipkit/identity/icon.png', 'public/favicon.png', 'public/favicon.svg', 'public/favicon.ico', 'favicon.ico', 'public/logo.png']
 
 export const ICON_TYPES: Record<string, string> = { png: 'image/png', svg: 'image/svg+xml', ico: 'image/x-icon' }