rvlib-shipkit 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,70 @@
+## 1.2.0
+
+- **Fix: SK024 read back only an `identity` key that starts a line.** On a one line config its own fix wrote the key inline, the check kept warning, and every fix pass added the key again, so a release gate always rewrote `repo.config.ts`. The key is now found at the top level of `defineRepo({…})` wherever it sits, bare or quoted, and a nested `identity` (an SK002 exemption) or one in a string or comment is not it.
+
+- **A filled bar for widgets.** `<span class="wbar" style="--p:51%"><i></i></span>` draws a bar in the page's state colours (`mid`, `hi`); widget rows stay on one line; the overview's shipkit section is a card.
+
+- **The planned page is one list ordered by time.** Three small labels inside it (now, late, next) and three columns per row: when (`now`, `late 2h`, `in 4m`), project · check (the project in its identity colour opens its repo, the check opens its own page), and one mark (a spinner while it runs, an orange dot and `waits: repo inactive` when late, a hollow circle when upcoming, a red ✕ `last failed`). A check that only runs on change is not listed. The rule, the reason, the last result, the inactive policy, an error and `run now` sit in a card that floats over the row on hover. One text filter matches the project or the check, and `/planned?q=` carries it. `Tip` takes `fallbacks`, the sides it tries when its placement does not fit. `bun tests/browser/planned-check.ts` measures it against a running home.
+- **A project list replaces the icon rail.** One row per repo, an 18px icon and the name beside it, the shown repo marked in its identity colour, in a panel whose width is dragged with a separator and kept per browser (`react-resizable-panels`). A repo's resource sidebar is resizable the same way. The rail's three sizes and their button are gone.
+- **Everything that floats is placed by `@floating-ui/react`.** The hover card, the help `(?)`, a process log on hover and the chart tooltip open after a short delay beside their trigger, flipped and shifted into the window, in a portal (`src/serve/hub-app/floating.tsx`).
+- **Command keys.** ⌘1 to ⌘9 select the nth repo of the list (by physical key, any layout), ⌘J the overview, ⌘P the plan, ⌘K the picker. The overview and the plan are two buttons on top of the list, each with its shortcut in its corner.
+- **Fix: a hub serving on its own showed an empty page beside its list.**
+- **Fix: a dark band between the list and the page in the macOS app.** A panel's own scrollbar, which WebKit draws; no panel scrolls itself now.
+
+- **The whole home page paints at once on a refresh.** Each repo's first screen is kept per browser in IndexedDB and read before the first paint, the machine is kept for the overview, and every region holds its size from the first paint, so a refresh measures a cumulative layout shift of 0.
+- **One quiet top strip, the places in the rail and the picker.** The strip holds the shown repo (or the page's name) and machine trouble only, no link and no button. A house at the top of the rail opens the overview, and `home` and `planned` lead the `⌘K`/`⌘J` picker.
+- **The overview: shipkit, then one card per global process, then the monitor.** `shipkit` (pm, daemon, web; was `machine`) and the processes under headers with a line icon; each process a card with its switch, state, declaring file, url and buttons. No repo list: the project list is it.
+- **Take over a global process started elsewhere.** One click: pm stops the process group listening on the process's local port (SIGTERM, then SIGKILL after 5 s) and starts its own supervised copy. Not offered without a local url or probe port, and the row says why. `POST /api/pm/resource` takes `act: 'takeover'`.
+- **`open` opens a global process's url in the default browser.** `open as app` is its own button, only for `app: true` (`act: 'app'`).
+
+- **A refresh of the home moves nothing.** The rail frame renders from the first paint at the size the browser keeps, and the last rail list (`localStorage` `hub:rail-list`) paints at once while the daemon is asked again, so the page no longer jumps right when the list arrives. `bun run home:shift` measures the cumulative layout shift of a first load and a refresh in headless Chrome.
+
+- **`<name>.shipkit.ts` unit files: checks, global processes and widgets.** A repo drops one anywhere and default-exports `check({...})`, `globalProcess({...})` or `widget({...})` (`rvlib-shipkit/src/shipkit-files.ts`). Discovery reads a `check` there beside the `.check.ts` files. A `globalProcess` is a long running process for the whole machine, supervised by pm whichever house repo declares it: pm reads the files at boot and every 15 s, and the overview shows a switch each, its log on hover, restart, one button per declared action (argv, or a function of the file run in its own bun process), and for `app: true` with a `url` an `open` that opens a shipkit app window, or `start and open` in one go on a process that is down. A `widget` returns html the daemon renders on its own clock (`everyMs`, default 5 s, bounded at 5 s) and serves at `/api/home/widgets.json`, and the overview mounts each in its monitor area. BREAKING: the `home.resources` key is removed; `defineRepo` refuses `home` and names the unit file that replaces it. pm's `/api/pm/resource` takes `act`: start, stop, restart, open or action.
+
+- **Switching repos on the home is instant.** Each hub keeps its rows (`/api/resources.json`), its runs page (`/api/timeline.json`) and its wiki graphs warm in memory (`WarmCell`, `src/serve/warm-cell.ts`): computed when the hub loads, one hub after another, recomputed in the background after a save burst settles, when the config or the run record stamp moves, or past `WARM_MAX_AGE_MS` (2 minutes), and served from memory, so a request never walks the repo. `?fresh=1` waits on a walk that includes a change the page just made, and the page asks it after an act, a run that ended and a config write. The page reads ahead the first screen of every other repo whose hub is up, one repo and one step at a time, once the shown repo has its own, and a repo read ahead mounts nothing until it shows. The tree, the page links, the runs page, the wiki frame and the wait line show a spinner where they will be. `HubHandler` gains `invalidate()` and `warm()`, `HubDeps` gains `stamp`. Measured on the live home: a first visit went from 80 to 380ms to 38 to 80ms, the runs page from 1.6 to 3.0s to under 110ms.
+
+- **Every repo has identity colours, and the home strip holds only what it should.** `repo.config.ts` declares `identity: { colorLight, colorDark }`, one `#rrggbb` each. New rule SK024 (`identity colors`, non-blocking) warns when they are missing or malformed; `shipkit check --fix SK024` derives them from the dominant hue of the repo icon, else from a hue hashed from the name, and writes that one key as one line, every other byte kept. The daemon fills each repo it loads the same way and never commits. A repo whose installed copy does not know the key is never written into. The home strip now holds `home` and `planned` (always there, the current one marked), the shown repo's icon and its name in its colour with two swatches that write the colours back (`POST /api/projects/identity`), and on its right only machine trouble: pm or the daemon down, a child or a resource crashed. Restart, the active flag, VS Code and modernize moved to the repo's own header, the resource switches and `new window` to the overview. The rail frames the shown repo's tile in its colour. `⌘K` opens the same picker as `⌘J`, which now lists the shown repo's targets, then `home`, `planned` and every other house repo.
+
+- **The home page is one app over one state tree.** A rail click shows another repo in place: no page load, the rail and the strip stay mounted, and a repo you come back to shows the page, filter, search and scroll it had. `HomeSt` is the root (`window.app`) for `/`, `/planned` and `/r/<repo>/`, with one `RepoSt` per repo visited, and only the shown repo polls. Every request of a repo goes through `RepoSt.url()`. The web serves one page at all three routes (`serveWeb({ page })`), and a hub of its own renders the same app with one repo and no machine.
+
+- **`shipkit gui` is its own macOS app.** Built once with swiftc into `~/Applications/Shipkit.app`, with the house repo's mark as its icon, so the dock and cmd-tab show shipkit instead of a second Chrome. Chrome's app mode stays the fallback.
+
+- **A boot never fires everything at once.** Work overdue when the plan starts is spread over the next 2 hours, and a check with no cadence runs at a stable point of 20h to 28h.
+
+- **The json answer import proves every file against its own hash.** Two check ids that slug alike can no longer share one row, and the import never overwrites a fresher row.
+
+- **Machine state lives in one machine database.** The repos flagged active and the pid records pm, the resources and a repo's dev servers are adopted from now live in `~/.config/shipkit/shipkit.sqlite` (beside `SHIPKIT_HOME_DIR` when it is set, or at `SHIPKIT_MACHINE_DB`). The json and pid files an older version wrote are read once and deleted, so a running pm adopts its children across the update. `ProcSpec.pidFile` is renamed `pidKey`.
+- **Nothing shipkit writes grows unbound.** Every store has a declared cap: the answers and the run record in the repo db, the attach slots, the run logs (40 runs, 6 hours), the job folders (100, 7 days), the scratch git indexes, the dev server logs, and on a machine with a home its logs and the gui window's Chrome profile. The daemon sweeps them all on boot and hourly, and a gate still sweeps what it writes. New rule SK023 (`stores under cap`, health) fails when a store is past its cap plus one sweep's drift; `shipkit check --fix SK023` runs the sweep. The old json answers are imported once (the last day's) and deleted.
+- **Cached answers live in the repo's database.** The one json file per cached answer under `.git/shipkit/store` is replaced by an `answers` table in the same `shipkit.sqlite` as the run record. Anything that makes the table unreadable (a corrupt or locked file, a missing row) means the check runs, never a replay and never a red. Answers nobody used for 14 days are dropped, and a repo keeps at most 5,000. The run record keeps 30 days and at most 200,000 rows per table.
+- **A repo's installed copy hands the command to the house source.** `node_modules/.bin/shipkit` and the `.shipkit/hooks` run a repo's own `rvlib-shipkit` cli directly, past the machine launcher. That cli now replaces itself (same pid, same argv) with the house cli the launcher runs, so every repo runs one version. A house checkout runs its own source, and CI, `SHIPKIT_NO_HOME` or a machine with no house run the installed copy. The page no longer says "daily pass": a health check runs each time the plan runs it.
+- **One shipkit version per machine, and any command starts pm.** The cli routes every `rvlib-shipkit` import a repo config makes to the copy that runs, so a repo's own install is never loaded beside it, and new rule SK022 warns when a repo pins or installed a version newer than the running one: the pin is a minimum. Before any command the cli probes pm on its port and, when it is down, kicks its LaunchAgent, or installs it from the house repo the first time. Skipped under CI, `SHIPKIT_NO_HOME=1`, inside a process pm started, off macOS, and after `shipkit pm uninstall`, which stays in force until `shipkit pm install`. `SHIPKIT_LAUNCH_AGENTS_DIR` moves where the agent is written.
+- **The plan replaces the daily pass and the save trigger.** A check declares when it runs beside what it reads: `every: '24h'`, a range `every: ['10h', '12h']` (each repo and check lands on a stable point inside it, so checks spread out), `cron: '0 9 * * 1'`, null for on change only, or a pure function of its last result (`status`, `at`, `streak`) and whether the repo is active, returning any of those. `whenInactive: 'run' | 'wait'` (default wait, also a lambda) says what a due check does while its repo is inactive: wait turns it late and runs it once an agent works in the repo, VS Code has it open, or it is flagged active. With nothing declared, a `ttl` reads as its `every`, a build step runs on change only, and any other check runs every 24h. A bad value dies when the check file loads; a lambda that throws is an error on its row, and the check runs on change only. The daemon keeps ONE plan for the machine: every repo and check pair with its next due time and why (`changed`, `scheduled`, `late`, `asked`), and runs what is due as one background batch per repo through the gate jobs. A save makes due only the checks whose cached answer would not replay. The page `/planned` (the `planned` link in the header strip) shows the whole plan, filterable by repo: running, due, late, next with its time, each row with its reason and the rule that planned it (for a lambda, the value it returned and the state that chose it); a click runs it now. The check page's `next run` reads the same row. `HealthSchedule`, `GateTrigger` and `lastHealthPassAt` are deleted; the save watch lives in `serve/tracked-watch.ts`.
+- **Every gate in the daemon is a detached job, so a daemon reload never kills one.** A terminal `shipkit ci` or `shipkit check`, a save trigger, the daily pass and a button on the page each start `shipkit ci --job <id>` (or `check --job <id>`) in the background, the same mechanism as `--detach`, with its options in the job folder. The daemon runs one job at a time per repo, a background one takes the machine's one background turn inside the job, and it follows the job's `out.log` and `checks.ndjson` into the terminal, the page and the problems pane. A new daemon image follows the jobs still running when it boots, and queues behind them. A terminal whose stream the daemon cut (a reload, `kill -9`) reads the rest from the job folder and exits with the gate's own code; a cut before the job started sends the run again once the daemon is back. The daemon now reloads on its own code at once, gates or not. `SHIPKIT_DAEMON_ONLY=a,b` loads only those house repos.
+- **A hub that crashed on a broken `repo.config.ts` loads again once the file is edited**, as a working hub reloads on an edit. It stayed crashed until a restart by hand.
+- **`shipkit pm`, the machine's process manager.** It runs `shipkit daemon` and `shipkit web` as detached children with pid files, starts one again when it dies (backoff, left down after 5 crashes in 5 minutes), and owns the machine resources (`home.resources`), which moved out of the daemon. Its api answers on port 4797 (`SHIPKIT_PM_PORT`): the status of each child and resource, start, stop and restart of a child, the resource switches. The web proxies `/api/pm/*` to it, and the overview shows pm, the daemon and the web with a restart button each. pm killed or restarted leaves its children running, and the next pm adopts them; a stop asked of pm (SIGTERM, `shipkit pm uninstall`) stops them. `shipkit pm install` writes the LaunchAgent `com.shipkit.pm`, which runs `bun <cli> pm` and replaces the `com.shipkit.home` agent. `shipkit home`, `home install` and `home uninstall` stay as names of the pm commands. `shipkit gui` starts pm when the web does not answer and waits for the web.
+- **pm, the daemon and the web each reload alone.** None runs under a bun watch, which follows every command through `cli.ts`. Each watches the lib files its own runner imports and restarts in place, same pid, on an edit of one of them: a page edit restarts the web, a runner edit the daemon (a gate in flight keeps running, see gate jobs), a supervisor edit pm, which adopts its children.
+- **pm stays small.** It reads the house repo's `home.resources` in a child process and never loads the repo config, and `shipkit pm` replaces its own image with pm's entry file, so pm runs in about 35 MB and reloads only on its own few files. Its boot lines say `adopted` for a child it took from a pid file. A stop or restart of the web asked from the page answers before the web goes down, so the page no longer shows a fetch error for a restart that worked.
+- **A supervised process is started through a shell that exits at once**, so it belongs to init from its start, in its own process group. A process started before its supervisor restarted in place stayed a zombie of the new image and read alive forever, so a crash was never restarted. A pid file whose pid a process started after the record now holds is no longer adopted.
+- **A daemon that hangs reads as down on the page: the web waits 5s for the home api and 30s for a repo request, runs excepted, and the page's poll gives up at 8s. The web learns the repo pages once the daemon first answers, and follows the list after that. A failed poll with the daemon up shows its error and no longer reloads the page.
+- **One app for every repo on the machine: `shipkit daemon` and `shipkit web`.** Run from the repo that hosts the house wiki. `shipkit daemon` loads every repo's hub and answers every api on an internal port (4798, `SHIPKIT_DAEMON_PORT`); `shipkit web` serves the page on port 4799 (`SHIPKIT_HOME_PORT`) and proxies every `/api/*` and `/r/<repo>/…` request to the daemon, run streams included, so a browser only ever sees one origin. `shipkit pm` runs both. A daemon that is down reads as a clear error on the page, which reloads itself once the daemon answers again. A terminal gate talks to the daemon directly, so it never depends on the web. The daemon loads every house repo's hub at boot, one after the other, and serves each under `/r/<repo>/` of its one server: the page, `/api/*`, `/graph/*`, `/media/*` and `/hub.json`. A boot runs no gate: a repo's background gate starts on a save in it, and the daily pass and the RED pings run for ACTIVE repos only (an agent works in it, or it is flagged active). A repo whose config fails to load reads crashed with its error while the others serve. The page has no frames: `/` is the overview of every resource and repo with its state, and `/r/<repo>/` is that repo's own hub page carrying the rail (read from the machine wide `/api/projects.json`) and a home strip over its header, with the resource switches and, for the shown repo, restart, the active flag, VS Code and modernize. A rail click goes to that repo's page, a double click opens VS Code. A repo whose hub cannot load shows why and the fix in place of its page. The home repo declares the machine resources in `home.resources`. `shipkit pm install` adds a macOS LaunchAgent that keeps it alive. Resources and repo processes run detached with a pid file, so the next pm or daemon adopts them.
+- **`shipkit serve` attaches to a running home.** It hands the hub to the home and streams its log, the last problem frame first, so a VS Code folder-open task keeps its problems pane with no change to `tasks.json`. A worktree, `--port` and `SHIPKIT_NO_HOME=1` serve in process as before.
+- **`serve.processes`: a repo's dev servers, supervised by its hub.** One switch each in the hub header, crash restart with backoff, adopted across a hub restart. **`serve.uses`** names the machine resources a repo needs, and the home rail marks it while one is off.
+- **`shipkit gui [repo|.]`: the home in its own window.** A Chrome app window on its own profile (the default browser when Chrome is absent), one more per call and per `new window` in the header. It starts the home when none runs, installing its LaunchAgent the first time from the house repo.
+- **On a machine with the home, no hub runs outside it.** `shipkit serve` hands off, starting an installed home that is down, and never serves in process there. A process the home started, linked worktrees, machines without a home and `SHIPKIT_NO_HOME=1` serve as before. `SHIPKIT_USE_HOME=1` sends hubs and gates to the home on `SHIPKIT_HOME_PORT` on a machine with no LaunchAgent.
+- **The daemon reloads one repo at a time.** An edit of a repo's `repo.config.ts` reloads that hub alone, once its gate is done, its processes kept. The daemon warns while it runs under a bun watch.
+- **A hub stopped by hand stays down** until a restart: its page no longer loads it again, and a stop during a load wins over the load. `/r/<name>/` answers 404 for a name that is not a house repo, never a page whose every call fails. The home's view of a hub drops its dead `external` and `restarts` fields.
+- **One copy of the lib in the home.** Before any repo config loads, a Bun resolver hook routes every `rvlib-shipkit` import (the bare name, an export alias, a subpath) to the home's own copy, so a repo's own install is never loaded and each lib module has one instance.
+- **The hub page works under a base path.** Every request it makes goes through one helper that reads `/r/<repo>` from its own address, so the same page serves standalone at `/` and in the home.
+- **On a machine with the home, `shipkit ci` and `shipkit check` run in the repo's hub, in the home.** They POST to `/r/<repo>/api/run`, and the terminal streams the hub's lines and takes its exit code, so every gate of a repo runs in one process and feeds one problems pane. What runs in process: a process the home started (a check's child, a script calling shipkit), CI, a linked worktree, `SHIPKIT_NO_HOME=1`, a machine without the home, a repo the home cannot load, and `check --fix`, `bump`, `release`. An unreachable home is a loud failure, never a quiet local run.
+- **Background gates take turns on the whole machine.** The save trigger and the daily pass of every hub wait for one shared turn, so several hubs never gate at once. A gate someone asks for never waits for it. A hub start feeds the same quiet window as a save, so a burst of restarts is one run.
+- **The rail: a single click selects, a double click opens VS Code.** On a hub serving on its own, a click opens that repo's page on the home when one serves.
+
+- **The project rail has three sizes.** A button pinned to the foot of the rail shows three dots, the current size lit, and a click cycles small (44px rail, 24px icons), medium (76px, 56px) and large (132px, 112px). The browser keeps the choice in `localStorage` `hub:rail`. Every size is a literal of the rail's class in `project-gutter.css`, never an inline value, and each icon carries its size as `width` and `height` attributes with `object-fit: contain`, so a 512px icon file never draws at its natural size, even when the sheet does not apply. `tests/browser/hub-layout-check.ts` measures all of it in headless Chrome.
+
+## 1.1.1
+
+- **The project rail reads `.shipkit/identity/icon.png` first.** A repo with no public surface has no favicon, so the rail showed its initial. `ICON_FILES` now starts with `.shipkit/identity/icon.png`, ahead of `public/favicon.png`, so a repo can carry a rail icon without shipping a public folder.
+
 ## 1.1.0
 
 - **`shipkit ask` scaffolds a walkthrough, not a one line body.** A new ask used to carry `**Ask**: <title>` and nothing a human could follow. A step ask (every kind but `decision`) now starts with numbered `## N.` sections, each opening with a bold link slot and a `field | value` table, and ends with a `Tell the agent "done"` section. A `decision` ask starts with numbered options, the recommended one first. An HTML comment, invisible in the hub, states the shape, and `shipkit ask` reminds the author to fill every `{{placeholder}}` (braces, since the hub markdown hides an unknown `<tag>`). The `**Why**` line and `--why` are unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
@@ -33,6 +33,7 @@
         "test:raw": "bun test"
     },
     "dependencies": {
+        "@floating-ui/react": "^0.27.20",
         "@napi-rs/canvas": "^1.0.2",
         "clipanion": "^4.0.0-rc.4",
         "comfy-ts": "^2.9.0",
@@ -42,6 +43,7 @@
         "mobx-react-lite": "^5.0.0",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",
+        "react-resizable-panels": "^4.13.3",
         "sanitize-html": "^2.17.6",
         "sharp": "^0.35.3"
     }

package/src/check.ts

@@ -20,6 +20,7 @@
 // its cache key automatically, so nothing declares its own code.
 import type { CheckCtx } from './core/check-ctx.ts'
 import { parseWhen } from './core/when.ts'
+import { planDeclProblem, type Every, type WhenInactiveDecl } from './plan/cadence.ts'
 import type { Line } from './core/wire.ts'
 import type { RepoConfig } from './repo-config.ts'
 
@@ -108,6 +109,27 @@ export type CheckDef = {
      *  key, and every other check shares one answer between a frozen run and
      *  a normal one. Declared, never guessed from the body. */
     writes?: boolean
+    /** WHEN the planner runs it on its own, beside the save that moved what
+     *  it reads: a span since its last run (`'24h'`), a range (`['10h',
+     *  '12h']`, each repo and check on a stable point inside it, so checks
+     *  spread out), a cron expression (`'0 9 * * 1'`), or null for on change
+     *  only. Or a PURE function of its last result (`status`, `at`, `streak`
+     *  of that same status) and whether the repo is active, returning any of
+     *  those: `(last) => (last?.status === 'fail' ? '1h' : '7d')`. A lambda
+     *  that throws is an error row on the planned page, and the check runs on
+     *  change only. Absent: its `ttl`, else a build step waits for a save and
+     *  any other check runs every 24h. */
+    every?: Every
+    /** a time of day or week for the rare check that needs one, as five cron
+     *  fields in local time (`'0 9 * * 1'`, Mondays at 9). Never with `every`. */
+    cron?: string
+    /** what a due check does while its repo is inactive (no agent session in
+     *  it, VS Code does not have it open, it is not flagged active): `'wait'`
+     *  turns it late and runs it once the repo is active again, `'run'` runs
+     *  it on time anyway (a credential probe, an api key that must keep
+     *  working). A pure function of the last result may choose. Default
+     *  `'wait'`. */
+    whenInactive?: WhenInactiveDecl
     /** cache-identity contribution for a `ttl` check whose verdict depends on
      *  config: a changed key busts the answer instantly instead of serving
      *  a stale cached assertion for the rest of the TTL. */
@@ -179,6 +201,8 @@ export function check(d: CheckDef): CheckDef {
     const populations = (['inputs', 'ttl', 'never'] as const).filter((k) => has(k))
     if (populations.length > 1)
         throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: ${populations.join(' and ')} contradict each other — a check reads files, or the world, or nothing can describe it`)
+    const planBad = planDeclProblem({ every: d.every, cron: d.cron, whenInactive: d.whenInactive })
+    if (planBad != null) throw new Error(`check${name}: ${planBad}`)
     if (d.when != null) {
         const w = parseWhen(d.when)
         if (typeof w === 'string') throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: when ${w}`)

package/src/checks/SK022-machine-runs-the-pin.check.ts

@@ -0,0 +1,43 @@
+// SK022 machine runs the pin (build/shipkit.md): on a machine with a house
+// every shipkit runs the house copy, whatever a repo installed, so a repo's
+// rvlib-shipkit pin is a minimum. It warns when the repo asks for a version
+// newer than the one this process runs: a rule or an api that pin relies on
+// is absent here until the house copy catches up.
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { check } from '../check.ts'
+
+type Pkg = { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+
+const NAME = 'rvlib-shipkit'
+
+/** the lowest version a semver range admits (`^0.30.1` → 0.30.1), null when
+ *  it names no version (link:, workspace:*, a tag) */
+export function pinFloor(spec: string): string | null {
+    const m = /^\s*(?:\^|~|>=|=|v)?\s*(\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(spec)
+    return m?.[1] ?? null
+}
+
+export const machineRunsThePin = check({
+    id: 'SK022',
+    blocking: false,
+    title: 'machine runs the pin',
+    description: 'the shipkit this machine runs is at least the version this repo pins',
+    owner: 'build/shipkit.md',
+    // the running version is no file of the repo
+    cacheKey: () => LIB_VERSION,
+    run: (c) => {
+        const pkg = c.json<Pkg>('package.json')
+        const spec = pkg?.devDependencies?.[NAME] ?? pkg?.dependencies?.[NAME]
+        if (spec == null) return c.ok(`no ${NAME} pin, this machine runs ${LIB_VERSION}`)
+        const wants: Array<{ v: string; from: string }> = []
+        const floor = pinFloor(spec)
+        if (floor != null) wants.push({ v: floor, from: `package.json pins ${spec}` })
+        const installed = c.json<Pkg>(`node_modules/${NAME}/package.json`)?.version
+        if (installed != null) wants.push({ v: installed, from: `node_modules has ${installed}` })
+        const ahead = wants.filter((w) => Bun.semver.order(w.v, LIB_VERSION) > 0)
+        if (ahead.length === 0) return c.ok(`${NAME} ${spec}: this machine runs ${LIB_VERSION}, at least that`)
+        c.warn(`${NAME}: ${ahead.map((w) => w.from).join(', ')}, newer than the ${LIB_VERSION} this machine runs. Update the house copy (git pull in the repo that hosts the house wiki), or run this repo's own install: bun node_modules/${NAME}/src/cli.ts`)
+    },
+})
+
+export default machineRunsThePin

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

@@ -0,0 +1,49 @@
+// 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/SK024-identity-colors.check.ts

@@ -0,0 +1,49 @@
+// SK024 identity colors (core/identity.ts owns the derivation): repo.config.ts
+// declares `identity: { colorLight, colorDark }`, two #rrggbb hex, so every
+// surface that shows the repo (the home page header, its rail tile) draws it
+// in its own colour. The fix derives them from the repo icon, or from a hue
+// hashed from the name, and writes that one key, every other byte kept.
+import { check } from '../check.ts'
+import { configName, CONFIG_FILE, deriveIdentity, identityRefusal, INSTALLED_CONFIG_SRC } from '../core/identity.ts'
+import { declaresIdentity, identityOfText, identityProblem, setIdentityText } from '../core/identity-color.ts'
+
+
+const FIX = 'shipkit check --fix SK024 derives them from the repo icon, or from its name'
+
+export const identityColors = check({
+    id: 'SK024',
+    blocking: false,
+    title: 'identity colors',
+    description: 'repo.config.ts declares identity colours: colorLight and colorDark, two hex',
+    owner: 'build/shipkit/built-in-checks.md',
+    run: (c) => {
+        const text = c.read(CONFIG_FILE)
+        if (text == null) return c.note(`no ${CONFIG_FILE}`)
+        const declared = declaresIdentity(text)
+        const id = identityOfText(text)
+        const why = id == null ? (declared ? 'identity is declared but its two colours cannot be read as #rrggbb hex' : 'no identity colours') : identityProblem(id)
+        const refused = why == null ? null : identityRefusal(c.read(INSTALLED_CONFIG_SRC))
+        if (refused != null) return c.note(`${CONFIG_FILE}: ${why}, and ${refused}`)
+        if (why != null) return c.warn(`${CONFIG_FILE}: ${why}`, FIX)
+        c.ok(`identity ${id!.colorLight} on light, ${id!.colorDark} on dark`)
+    },
+    fix: async (c) => {
+        const text = c.read(CONFIG_FILE)
+        if (text == null) return { changed: false, summary: `no ${CONFIG_FILE}` }
+        const have = identityOfText(text)
+        if (have != null && identityProblem(have) == null) return { changed: false, summary: 'identity colours already declared' }
+        const refused = identityRefusal(c.read(INSTALLED_CONFIG_SRC))
+        if (refused != null) return { changed: false, summary: refused }
+        const { id, from } = await deriveIdentity(c.root, configName(text, c.root), (rel) => c.bytes(rel))
+        let next: string
+        try {
+            next = setIdentityText(text, id)
+        } catch (e) {
+            return { changed: false, summary: (e as Error).message }
+        }
+        c.write(CONFIG_FILE, next)
+        return { changed: true, summary: `identity ${id.colorLight} / ${id.colorDark}, from ${from}` }
+    },
+})
+
+export default identityColors

package/src/cli/cmd_Check.ts

@@ -2,6 +2,9 @@
 // autofixes then re-lints. Thin clipanion surface; logic in
 // core/run-check.ts and core/run-fix.ts. ci NEVER fixes.
 import { Command, Option } from 'clipanion'
+import { runViaHub } from '../home/via-hub.ts'
+import { readJobOpts, recordExit } from '../core/jobs.ts'
+import { runJob } from '../core/job-run.ts'
 import { runCheck } from '../core/run-check.ts'
 import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
 import { runFix } from '../core/run-fix.ts'
@@ -27,8 +30,25 @@ export class CheckCommand extends Command {
     fix = Option.Boolean('--fix', false, { description: 'apply check autofixes (every fixable check, or only the listed ids), then re-run them' })
     frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for the self-maintaining checks (SK005 never touches package.json)' })
     fixIds = Option.Rest()
+    job = Option.String('--job', { hidden: true })
 
     async execute(): Promise<number> {
+        // a gate job the daemon started: its options are in the job folder
+        if (this.job != null) {
+            const root = process.cwd()
+            const job = readJobOpts(root, this.job)
+            let code = 1
+            if (job == null) this.context.stderr.write(`FAIL: gate job ${this.job} has no options in its folder\n`)
+            else {
+                try {
+                    code = await runJob(root, this.job, 'check', job, (l) => { this.context.stdout.write(`${l}\n`) })
+                } catch (e) {
+                    this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+                }
+            }
+            recordExit(root, this.job, code)
+            return code
+        }
         // a stale toolkit updates itself and restarts this exact invocation
         // (loop-guarded, skipped under CI/frozen/source consumption)
         await maybeSelfUpdateAndRestart(process.cwd(), { fresh: this.fresh })
@@ -43,7 +63,12 @@ export class CheckCommand extends Command {
             }
             if (this.fix)
                 return await runFix(process.cwd(), { ids: this.fixIds, print: (l) => this.context.stdout.write(`${l}\n`) })
-            return await runCheck(process.cwd(), { json: this.json, fresh: this.fresh, frozen: this.frozen, print: (l) => this.context.stdout.write(`${l}\n`) })
+            const opts = { json: this.json, fresh: this.fresh, frozen: this.frozen }
+            const print = (l: string): void => { this.context.stdout.write(`${l}\n`) }
+            // on a machine with the home, the repo's hub runs it (home/via-hub.ts)
+            const via = await runViaHub(process.cwd(), 'check', opts, { print, printErr: (l) => this.context.stderr.write(`${l}\n`) })
+            if (via != null) return via
+            return await runCheck(process.cwd(), { ...opts, print })
         } catch (e) {
             this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
             return 1

package/src/cli/cmd_Ci.ts

@@ -2,8 +2,10 @@
 // core/run-ci.ts.
 import { Command, Option } from 'clipanion'
 import { join } from 'path'
-import { recordExit, startDetached } from '../core/jobs.ts'
+import { readJobOpts, recordExit, startDetached } from '../core/jobs.ts'
+import { runJob } from '../core/job-run.ts'
 import { runCi } from '../core/run-ci.ts'
+import { runViaHub } from '../home/via-hub.ts'
 import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
 
 export class CiCommand extends Command {
@@ -46,7 +48,13 @@ export class CiCommand extends Command {
             for (const l of d.lines) this.context.stdout.write(`${l}\n`)
             return 0
         }
-        const code = await this.gate(root)
+        const job = this.job != null ? readJobOpts(root, this.job) : null
+        let code = 1
+        try {
+            code = this.job != null && job != null ? await runJob(root, this.job, 'ci', job, (l) => { this.context.stdout.write(`${l}\n`) }) : await this.gate(root)
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+        }
         if (this.job != null) recordExit(root, this.job, code)
         return code
     }
@@ -72,7 +80,7 @@ export class CiCommand extends Command {
         // (loop-guarded, skipped under CI/frozen/source consumption)
         await maybeSelfUpdateAndRestart(root, { fresh: this.fresh })
         try {
-            return await runCi(root, {
+            const opts = {
                 bail: this.bail,
                 json: this.json,
                 fix: this.fix,
@@ -84,8 +92,13 @@ export class CiCommand extends Command {
                 onlyIds: this.only,
                 fresh: this.fresh,
                 ...(this.full ? { tests: 'full' as const } : {}),
-                print: (l) => this.context.stdout.write(`${l}\n`),
-            })
+            }
+            const print = (l: string): void => { this.context.stdout.write(`${l}\n`) }
+            // on a machine with the home, the repo's hub runs it (home/via-hub.ts)
+            // a job is already the run, wherever it was started from
+            const via = this.job != null ? null : await runViaHub(root, 'ci', opts, { print, printErr: (l) => this.context.stderr.write(`${l}\n`) })
+            if (via != null) return via
+            return await runCi(root, { ...opts, print })
         } catch (e) {
             this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
             return 1

package/src/cli/cmd_Home.ts

@@ -0,0 +1,170 @@
+// shipkit pm, daemon, web and gui: the machine's one app. Thin clipanion surface; logic in home/.
+import { Command, Option } from 'clipanion'
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { fileURLToPath } from 'url'
+import { basename } from 'path'
+import { markAutostart } from '../home/autostart.ts'
+import { installHome, uninstallHome } from '../home/home-launchd.ts'
+import { homeInstalled, houseCli, houseRootOf, openWindow, startHome } from '../home/home-start.ts'
+import { homeUp, homeUrl, hubBase } from '../home/home-paths.ts'
+import { homeRepo, houseIndex } from '../serve/project-gutter.ts'
+import { homedir } from 'os'
+import { execPm, runPm } from '../home/run-pm.ts'
+import { runDaemon } from '../home/run-daemon.ts'
+import { runWeb } from '../home/run-web.ts'
+
+const OWN_CLI = fileURLToPath(new URL('../cli.ts', import.meta.url))
+
+const io = (c: Command) => ({
+    print: (l: string) => c.context.stdout.write(`${l}\n`),
+    printErr: (l: string) => c.context.stderr.write(`${l}\n`),
+})
+
+/** the --port value, undefined when absent, null when it is not a port */
+function portOf(c: Command, raw: string | undefined): number | undefined | null {
+    if (raw == null) return undefined
+    const port = Number(raw)
+    if (Number.isInteger(port) && port > 0) return port
+    c.context.stderr.write(`FAIL --port '${raw}' is not a port number\n`)
+    return null
+}
+
+export class PmCommand extends Command {
+    // `home` is the name agents installed before pm still run
+    static override paths = [['pm'], ['home']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'the machine\'s process manager: runs `shipkit daemon` and `shipkit web` as detached children, starts one again when it dies, owns the global processes every house repo declares in its .shipkit.ts files, and serves its api on port 4797 (SHIPKIT_PM_PORT). A pm restarted or killed leaves its children running and the next one adopts them. Run from the repo that hosts the house wiki',
+        examples: [
+            ['run pm in this terminal', 'shipkit pm'],
+            ['on test ports', 'SHIPKIT_PM_PORT=4887 SHIPKIT_HOME_PORT=4889 SHIPKIT_DAEMON_PORT=4888 SHIPKIT_HOME_DIR=/tmp/home shipkit pm'],
+        ],
+    })
+
+    port = Option.String('--port', { required: false, description: 'pm port (default 4797, or SHIPKIT_PM_PORT)' })
+
+    async execute(): Promise<number> {
+        const port = portOf(this, this.port)
+        if (port === null) return 1
+        if (execPm({ port })) return 0
+        return runPm(process.cwd(), io(this), { port })
+    }
+}
+
+export class DaemonCommand extends Command {
+    static override paths = [['daemon']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'the home\'s daemon: loads every house repo hub in this one process and serves their api, their run streams and the home api under /r/<repo>/ on an internal port. No page: `shipkit web` serves it. Run from the repo that hosts the house wiki',
+        examples: [
+            ['the daemon alone', 'shipkit daemon'],
+            ['on another port', 'shipkit daemon --port 4888'],
+        ],
+    })
+
+    port = Option.String('--port', { required: false, description: 'daemon port (default 4798, or SHIPKIT_DAEMON_PORT)' })
+
+    async execute(): Promise<number> {
+        const port = portOf(this, this.port)
+        if (port === null) return 1
+        return runDaemon(process.cwd(), io(this), { port })
+    }
+}
+
+export class WebCommand extends Command {
+    static override paths = [['web']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'the home\'s page: one server on the home port that serves the page and proxies every api request to the daemon, so a browser only sees this origin. It loads no repo',
+        examples: [
+            ['the page alone', 'shipkit web'],
+            ['on another port', 'shipkit web --port 4889'],
+        ],
+    })
+
+    port = Option.String('--port', { required: false, description: 'home port (default 4799, or SHIPKIT_HOME_PORT)' })
+
+    async execute(): Promise<number> {
+        const port = portOf(this, this.port)
+        if (port === null) return 1
+        return runWeb(io(this), { port })
+    }
+}
+
+export class PmInstallCommand extends Command {
+    static override paths = [['pm', 'install'], ['home', 'install']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'keep pm running, and through it the daemon and the web: a macOS LaunchAgent starts it now and at every login, and restarts it when it dies. Idempotent',
+        examples: [['install from the house repo', 'shipkit pm install']],
+    })
+
+    async execute(): Promise<number> {
+        markAutostart(true)
+        return installHome({ root: process.cwd(), cli: houseCli(process.cwd(), OWN_CLI), print: io(this).print })
+    }
+}
+
+export class PmUninstallCommand extends Command {
+    static override paths = [['pm', 'uninstall'], ['home', 'uninstall']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'stop pm, the daemon and the web, and remove the LaunchAgent. The resources and repo processes keep running. No later command starts pm on its own until `shipkit pm install`',
+        examples: [['remove the agent', 'shipkit pm uninstall']],
+    })
+
+    async execute(): Promise<number> {
+        // a machine that said no: no later command starts pm again on its own
+        markAutostart(false)
+        return uninstallHome({ print: io(this).print })
+    }
+}
+
+export class GuiCommand extends Command {
+    static override paths = [['gui']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'open the home in its own window, outside VS Code and the browser, starting pm first when the web does not answer (and installing its LaunchAgent the first time). Every call opens one more window',
+        examples: [
+            ['a window on the home', 'shipkit gui'],
+            ['a window on one repo', 'shipkit gui my-app'],
+            ['a window on the repo you stand in', 'shipkit gui .'],
+        ],
+    })
+
+    repo = Option.String({ required: false, name: 'repo' })
+
+    async execute(): Promise<number> {
+        const out = io(this)
+        if (!(await homeUp())) {
+            // pm runs the web: ensure pm, then wait for the web
+            try {
+                if (!homeInstalled()) {
+                    const root = houseRootOf(process.cwd())
+                    if (root == null) {
+                        out.printErr(`FAIL: no pm runs, and ${process.cwd()} is not a house repo, so there is none to install it from. Run \`shipkit gui\` once from any repo whose CLAUDE.md includes the house wiki`)
+                        return 1
+                    }
+                    const code = await installHome({ root, cli: houseCli(root, OWN_CLI), print: out.print })
+                    if (code !== 0) return code
+                }
+                await startHome({ need: 'web' })
+            } catch (e) {
+                out.printErr(`FAIL: ${(e as Error).message}`)
+                return 1
+            }
+        }
+        // `.` = the repo you stand in, named the way the rail names it
+        const name = this.repo === '.' && houseIndex(homeRepo(process.cwd()), homedir()) != null ? basename(homeRepo(process.cwd())) : this.repo
+        const url = `${homeUrl()}${name != null && name !== '.' ? `${hubBase(name)}/` : '/'}`
+        const cmd = openWindow(url, { version: LIB_VERSION, warn: out.printErr })
+        out.print(`ok: a home window on ${url}${cmd[0] === 'open' ? ' (the shipkit app)' : ''}`)
+        return 0
+    }
+}

package/src/cli.ts

@@ -13,6 +13,7 @@ import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
 import { FleetCommand } from './cli/cmd_Fleet.ts'
+import { DaemonCommand, GuiCommand, PmCommand, PmInstallCommand, PmUninstallCommand, WebCommand } from './cli/cmd_Home.ts'
 import { HooksCommitMsgCommand, HooksInstallCommand, HooksListCommand, HooksPreCommitCommand } from './cli/cmd_Hooks.ts'
 import { InitCommand } from './cli/cmd_Init.ts'
 import { KeysCommand } from './cli/cmd_Keys.ts'
@@ -59,6 +60,12 @@ export function buildCli(): Cli {
     cli.register(CheckCommand)
     cli.register(TuiCommand)
     cli.register(ServeCommand)
+    cli.register(PmCommand)
+    cli.register(DaemonCommand)
+    cli.register(WebCommand)
+    cli.register(PmInstallCommand)
+    cli.register(PmUninstallCommand)
+    cli.register(GuiCommand)
     cli.register(ContractsCommand)
     cli.register(AsksCommand)
     cli.register(AsksCheckCommand)
@@ -87,5 +94,18 @@ export function buildCli(): Cli {
     return cli
 }
 
-// only when this file IS the process, so importing it costs nothing
-if (import.meta.main) void buildCli().runExit(process.argv.slice(2))
+// only when this file IS the process, so importing it costs nothing. A repo's
+// installed copy first hands the command to the house source (handoff.ts). One copy
+// of the lib per process: a repo config that imports its own install lands on
+// this one (one-lib.ts), so the machine's version runs in every repo. Then pm
+// is started when it is down (autostart.ts), before the command runs
+if (import.meta.main) {
+    const argv = process.argv.slice(2)
+    const { handoff } = await import('./home/handoff.ts')
+    handoff(argv)
+    const { useOneLib } = await import('./core/one-lib.ts')
+    useOneLib()
+    const { autostart } = await import('./home/autostart.ts')
+    await autostart(argv)
+    void buildCli().runExit(argv)
+}