rvlib-shipkit 1.1.1 → 1.3.0

package/src/serve/run-serve.ts

@@ -1,426 +1,72 @@
-// shipkit serve — resolve the repo's toolbox and run the hub. 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: --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 } 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 { lastHealthPassAt, 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'
+// shipkit serve: the process around one repo's hub. On a machine with a home
+// it hands the hub to the home and streams its lines; else it serves the hub
+// runtime (hub-runtime.ts) behind a Bun.serve of its own, restarts in place
+// when the lib moved under it, and stops everything on a signal.
+import { basename } from 'path'
 import { reclaimPreviousImage } from '../core/instance.ts'
 import { isLinkedWorktree } from '../core/git-root.ts'
-import { OtherRepos } from './other-repos.ts'
-import { recordStamp } from './project-gutter.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 { HealthSchedule } from './health-schedule.ts'
-import { GateTrigger, watchTracked } from './gate-trigger.ts'
-import { ProblemBoard } from '../problems/problem-board.ts'
-import { HubProblems } from './hub-problems.ts'
-import { StaleRestart } from './stale-restart.ts'
-import { reexecBlocker, reexecSelf } from '../core/reexec.ts'
-import { serveHub, type HubDeps } from './serve-hub.ts'
-import { defaultHubPort } from './hub-port.ts'
-import { LAYOUT } from '../core/layout.ts'
 import { diskLibVersion, LIB_VERSION } from '../core/lib-version.ts'
-export { defaultHubPort }
-
-export type ServeIo = { print: (l: string) => void; printErr: (l: string) => void }
-
+import { reexecBlocker, reexecSelf } from '../core/reexec.ts'
+import { attachToHome } from '../home/attach.ts'
+import { daemonUp, WORKER_ENV } from '../home/home-paths.ts'
+import { homeWanted, startHome } from '../home/home-start.ts'
+import { loadHub, type ServeIo } from './hub-runtime.ts'
+import { homeRepo } from './project-gutter.ts'
+import { serveHub } from './serve-hub.ts'
+import { StaleRestart } from './stale-restart.ts'
+import { Planner } from '../plan/planner.ts'
 
-// 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
-}
+export type { ServeIo }
 
-// `~/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))
+/** how often a hub of its own looks at its plan */
+export const PLAN_TICK_MS = 2_000
 
-/** the config file's bytes, cheaply: a re-read costs a new module instance,
- *  so it happens only when the file really moved */
-function configStamp(root: string): string {
-    try {
-        const st = statSync(join(root, 'repo.config.ts'))
-        return `${st.mtimeMs}:${st.size}`
-    } catch {
-        return ''
-    }
+/** what a `shipkit serve` does with its hub. On a machine with a home, no
+ *  hub runs outside it: a home that answers takes it, and an installed one
+ *  that does not is started first. `serve` only inside the home, a linked
+ *  worktree (its hub is its own checkout), a machine with no home, and
+ *  SHIPKIT_NO_HOME=1, the one lift */
+export async function serveMode(root: string, env: Record<string, string | undefined> = process.env, o: { up?: () => Promise<boolean>; installed?: () => boolean } = {}): Promise<'serve' | 'attach' | 'start'> {
+    const set = (v: string | undefined): boolean => v != null && v !== ''
+    if (set(env[WORKER_ENV]) || set(env.SHIPKIT_NO_HOME)) return 'serve'
+    if (isLinkedWorktree(root)) return 'serve'
+    if (await (o.up ?? (() => daemonUp()))()) return 'attach'
+    return (o.installed ?? (() => homeWanted(env)))() ? 'start' : 'serve'
 }
 
-export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo, o?: { port?: number }): Promise<HubDeps> {
-    // 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'))) {
+export async function runServe(root: string, io: ServeIo, o?: { port?: number }): Promise<number> {
+    const mode = await serveMode(root)
+    if (mode === 'start') {
+        io.print(`the home is installed but not running: starting it`)
         try {
-            kit = await loadKit(root)
+            await startHome()
         } 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: the daily timer
-    // never stacks a pass on top of one
-    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 runChecks: HubDeps['runChecks'] = (tap, o) => {
-        const run = chain.then(async () => {
-            active++
-            try {
-                return await runIn({
-                    line: tap.line,
-                    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
-                        if (board.take(e)) for (const l of board.frame()) io.print(l)
-                        tap.check(e)
-                    },
-                }, o)
-            } 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
-    }
-    const runIn: HubDeps['runChecks'] = async (tap, o) => {
-        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 runCi(root, {
-                ...hubGateOpts({ only, auto: o?.auto === true }),
-                buildOnly: only != null && namedTasks.length === only.length,
-                print: tap.line,
-                config: c,
-                onCheck: tap.check,
-                invokedBy: by,
-            })
-        // 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 runCheck(root, { only, status: only == null, print: tap.line, config: c, onCheck: tap.check, invokedBy: by })
-    }
-    // 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) }
+            io.printErr(`FAIL: ${(e as Error).message}. No hub runs outside the home on this machine: SHIPKIT_NO_HOME=1 serves this one in process`)
+            return 1
         }
-        const view = shapeLive({ now, cap: parallelCap(), live: local.live, runs: local.runs, invocations: local.invocations, others: others.read() })
-        shaped = { at: now, view }
-        return view
     }
-    const schedule = new HealthSchedule({
-        now: Date.now,
-        lastPassAt: () => lastHealthPassAt(record),
-        busy: () => active > 0,
-        run: async () => {
-            const t0 = Date.now()
-            io.print(`health pass: the daily run starts`)
-            const code = await runChecks({ line: () => {}, check: () => {} }, { by: 'schedule' })
-            io.print(`health pass: the daily run ended, exit ${code}, ${Math.round((Date.now() - t0) / 1000)}s`)
-        },
-    })
-    return {
-        root,
-        name: c.name,
-        port,
-        graphs,
-        studio,
-        refresh,
-        // 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,
-        schedule,
-        // 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,
-        busy: () => 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}/?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,
-            }),
+    if (mode !== 'serve') {
+        // the home serves every repo on its one port, so a forced one cannot apply here
+        if (o?.port != null) io.printErr(`WARN --port ${o.port} is ignored: the home serves this hub on its own port. SHIPKIT_NO_HOME=1 serves it in process on ${o.port}`)
+        const r = await attachToHome(basename(homeRepo(root)), io)
+        if (r !== 'serve') return r
     }
-}
-
-/** 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 }
-}
-
-
-// the / dashboard's data now comes from the collection providers
-// (src/collections/providers.ts) — never a parallel projection.
-
-export async function runServe(root: string, io: ServeIo, o?: { port?: number }): Promise<number> {
     // `bun --watch` restarts the hub in the same pid: what its previous image
     // held is gone with it, and the check children it spawned are still ours
     // and still running, so they die here, before this image spawns anything
     const reclaimed = reclaimPreviousImage()
     if (reclaimed.killed.length > 0)
         io.print(`ok: this hub restarted in place: killed ${reclaimed.killed.length} check process(es) its previous image left running (pid ${reclaimed.killed.join(', ')})`)
-    const c = await loadRepoConfig(root)
-    const deps = await resolveHubDeps(root, c, io, o)
+    // a hub of its own plans its one repo, which counts as active: someone
+    // runs it. The interval below is that plan's clock
+    const plan = new Planner({ onError: (_repo, e) => io.printErr(`WARN the plan broke: ${e.message}`) })
+    const rt = await loadHub(root, io, { port: o?.port, plan, gateAtStart: true, ownTimers: true })
+    const { config: c, deps } = rt
+    let hub: ReturnType<typeof serveHub>
     try {
-        const hub = serveHub(deps)
-        const base = `http://localhost:${hub.server.port}`
-        // a banner, not a checklist: one clickable line, then what is inside,
-        // dimmed by indentation. Wire prefixes stay reserved for problems.
-        io.print(`${c.name} hub → ${base}`)
-        const routes = hub.tools.filter((t) => t.path !== '/').map((t) => `${t.label} ${t.path}`).join(' · ')
-        if (routes !== '') io.print(`  also: ${routes}`)
-        // a page that cannot refresh itself looks identical to a broken one,
-        // and the only tell is that every change needs a reload key
-        if (!hub.liveReload) io.print(`WARN the page will not refresh itself: NODE_ENV=production strips bun hot reload, unset it and restart the hub`)
-        // the off-machine door (phone, other machines) — publicHost is config
-        if (c.serve?.publicHost != null) io.print(`  phone: http://${c.serve.publicHost}:${hub.server.port}/`)
-        // said once at boot, so a silent phone is never mistaken for no blockers
-        if (c.notifyCommand != null && isLinkedWorktree(root)) io.print(`  pings: off, this is a linked worktree (only the main checkout's hub notifies)`)
-        // the daily health pass rides the serving process, and only it: a hub
-        // built for a test never starts a timer
-        deps.schedule?.start((e) => io.printErr(`WARN the daily health pass broke: ${e.message}`))
-        // the quick gate at start, then after every save burst, so the
-        // problems pane follows the code. It only asks the runner, which
-        // measures or replays like any run: the watch decides WHEN, never
-        // what is true
-        const trigger = new GateTrigger({
-            run: () => deps.runChecks({ line: () => {}, check: () => {} }, { gate: true, by: 'hub', auto: true }),
-            onError: (e) => io.printErr(`WARN the hub's own gate run broke: ${e.message}`),
-        })
-        const watcher = watchTracked(root, () => trigger.touched(), { onError: (e) => io.printErr(`WARN the file watch stopped, so the problems pane refreshes only on a hub run: ${e.message}`) })
-        if (watcher.error != null) io.printErr(`WARN no file watch (${watcher.error}), so the problems pane refreshes only on a hub run`)
-        // a lib that moved under this process (under bun --watch the version
-        // import already restarted it, so what is left is a plain serve), or
-        // a file table the watch restarts leaked: it re-executes itself in
-        // place (same pid, argv, port) once no run is in flight. Only a
-        // restart that throws is said, in the hub's own status
-        const stale = new StaleRestart({
-            boot: LIB_VERSION,
-            disk: diskLibVersion,
-            busy: () => deps.busy?.() === true,
-            restart: (why) => {
-                // a refusal throws while the hub still serves, so the page can say it
-                const blocked = reexecBlocker()
-                if (blocked != null) throw new Error(blocked)
-                io.print(`ok: ${why}: restarting in place`)
-                stale.stop()
-                trigger.stop()
-                watcher.close()
-                hub.stop()
-                try {
-                    reexecSelf()
-                } catch (e) {
-                    // the server is already down: nothing is left to show a status
-                    io.printErr(`FAIL: this hub stopped to restart and could not: ${(e as Error).message}. Restart the hub task`)
-                    process.exit(1)
-                }
-            },
-            say: (text) => deps.hubProblems?.set('stale', text == null ? null : { text, severity: 'red' }),
-        })
-        stale.start()
-        // a watch restart that leaked sheds it before the first run spawns anything
-        stale.tick()
-        trigger.request()
-        // a child process (the comfy panel) outlives a parent nobody stopped,
-        // and the next launch then adopts one holding the PREVIOUS run's
-        // modules. A hard kill still leaks one, which is why adoption exists
-        for (const sig of ['SIGINT', 'SIGTERM'] as const)
-            process.on(sig, () => {
-                stale.stop()
-                trigger.stop()
-                watcher.close()
-                hub.stop()
-                process.exit(0)
-            })
-        await new Promise(() => {}) // the hub owns the process — never resolve
-        return 0
+        hub = serveHub(deps, rt.handler)
     } catch (e) {
+        rt.stop()
         if (e instanceof Error && e.message.includes('in use')) {
             // same repo in another window is fine; a different repo hashed
             // onto this port is a real collision — never claim its hub
@@ -440,4 +86,66 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
         }
         throw e
     }
+    const base = `http://localhost:${hub.server.port}`
+    // a banner, not a checklist: one clickable line, then what is inside,
+    // dimmed by indentation. Wire prefixes stay reserved for problems.
+    io.print(`${c.name} hub → ${base}`)
+    const routes = hub.tools.filter((t) => t.path !== '/').map((t) => `${t.label} ${t.path}`).join(' · ')
+    if (routes !== '') io.print(`  also: ${routes}`)
+    // a page that cannot refresh itself looks identical to a broken one,
+    // and the only tell is that every change needs a reload key
+    if (!hub.liveReload) io.print(`WARN the page will not refresh itself: NODE_ENV=production strips bun hot reload, unset it and restart the hub`)
+    // the off-machine door (phone, other machines) — publicHost is config
+    if (c.serve?.publicHost != null) io.print(`  phone: http://${c.serve.publicHost}:${hub.server.port}/`)
+    // said once at boot, so a silent phone is never mistaken for no blockers
+    if (c.notifyCommand != null && isLinkedWorktree(root)) io.print(`  pings: off, this is a linked worktree (only the main checkout's hub notifies)`)
+    // a lib that moved under this process (under bun --watch the version
+    // import already restarted it, so what is left is a plain serve), or
+    // a file table the watch restarts leaked: it re-executes itself in
+    // place (same pid, argv, port) once no run is in flight. Only a
+    // restart that throws is said, in the hub's own status
+    const stale = new StaleRestart({
+        boot: LIB_VERSION,
+        disk: diskLibVersion,
+        busy: () => deps.busy?.() === true,
+        restart: (why) => {
+            // a refusal throws while the hub still serves, so the page can say it
+            const blocked = reexecBlocker()
+            if (blocked != null) throw new Error(blocked)
+            io.print(`ok: ${why}: restarting in place`)
+            stale.stop()
+            clearInterval(planClock)
+            rt.stop()
+            hub.stop()
+            try {
+                reexecSelf()
+            } catch (e) {
+                // the server is already down: nothing is left to show a status
+                io.printErr(`FAIL: this hub stopped to restart and could not: ${(e as Error).message}. Restart the hub task`)
+                process.exit(1)
+            }
+        },
+        say: (text) => deps.hubProblems?.set('stale', text == null ? null : { text, severity: 'red' }),
+    })
+    stale.start()
+    // a watch restart that leaked sheds it before the first run spawns anything
+    stale.tick()
+    // the save watch, the processes and the pings, and the checks whose
+    // answer would not replay once the start settles
+    rt.start()
+    const planClock = setInterval(() => plan.tick(), PLAN_TICK_MS)
+    // a child process (the comfy panel) outlives a parent nobody stopped,
+    // and the next launch then adopts one holding the PREVIOUS run's
+    // modules. A hard kill still leaks one, which is why adoption exists
+    for (const sig of ['SIGINT', 'SIGTERM'] as const)
+        process.on(sig, () => {
+            stale.stop()
+            clearInterval(planClock)
+            plan.stop()
+            rt.stop({ procs: true })
+            hub.stop()
+            process.exit(0)
+        })
+    await new Promise(() => {}) // the hub owns the process — never resolve
+    return 0
 }