rvlib-shipkit 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,49 @@
+## 1.6.0
+
+- **lint, typecheck, test and every task that declares nothing are cached now.** Such a task is keyed on the whole work tree, plus the gitignored paths the new `ignoredInputs` lists for it (`{ test: ['dist/**'] }`, `'*'` for every task; a path by content, `dir/**` by the names under it), and the lockfile, the installed packages, the bun and node versions and the toolkit code behind it. `sk trace-audit` runs each gate task once under a file tracer and names the gitignored paths it reads that its key misses. Tracing is on wherever it can run (Apple silicon macOS): SK031 audits about daily, `sk trace-audit --disable` opts a machine out and `SHIPKIT_TRACE=0` one run, and each finding joins the key of the task that read it at once, in every worktree of the repo. SK032 and the fix pass of `sk ci` then write the findings into their own block of `repo.config.ts`, once the repo pins 1.6.0 or later. The tracer never decides a verdict. It needs Apple silicon macOS: on Linux and in CI nothing audits, and SK030's daily sample is the only net there.
+
+- **Every check that did not replay says why**, one line per reason: `ran: src/a.ts changed (lint, typecheck)`, `ran: nothing stored for it yet`, `ran, not kept: it reached the world through …`. A check its author declared never cached says so only under `--verbose`.
+
+- **A cache key carries the code behind the answer, not the whole toolkit.** A check is keyed on its own module graph and the runner's, and a repo task on the toolkit modules the repo's config imports, so a toolkit edit re-runs only the checks it can change.
+
+- **A command loads the image and comfy libraries only when it runs**: `sk --help` went from 540 ms to 220 ms.
+
+- **SK030 audits the cache.** About once a day, while somebody works in the repo, it re-runs a sample of the checks the cache would answer right now, fresh, and compares. A cached green that a fresh run disagrees with fails, naming the check whose key misses a path its body reads, and the stale answer is dropped so it is never served again. `sk cache-audit` is the same audit on demand (`--sample <n>`, `--only <id>`, `--json`).
+
+## Unreleased (patch)
+
+- **The hub tree groups assets by kit category.** Under media, each category is a row that folds, and its label opens the category page. An asset row reads by its kit label (`mon/brindon/front`), never its file id.
+
+- **SK001 no longer asks a comfy repo for a `comfy:up` script.** The box is a global process that `sk gp start comfyui` starts from any repo, so a per-repo script only copied that command. A `.shipkit/comfy/` folder now asks for nothing, and SK001 no longer probes it.
+
+- **Every repo's tree has the same top rows.** A section the repo has nothing in (no process, no contract, no secret, no asks, no reflections, no tests, no media, no wiki) stays in the list, greyed, its title saying why. The processes row still opens its page, which says the repo declares none. The others open nothing, and the arrows step over them. Plan, git and admin still exist only on the home.
+
+- **Every command starts faster.** A command that draws images or talks to ComfyUI loads canvas, sharp and comfy-ts when it runs, instead of every command loading them at startup (canvas alone read the system fonts). A fully cached `sk ci` drops from about 1.2s to 0.7s, `sk --help` from 540ms to 220ms.
+
+- **Every check that did not come from the cache says why.** Above the verdict, one line per reason: `ran: src changed (lint, test)` names what moved since the last stored answer, `ran: nothing stored for it yet`, `ran, not kept: it reached the world through \`git check-ignore -q\`` for an answer that can never be stored, and `never cached: <reason>` for a check no key describes. A check that can never be kept was counted like a key that moved.
+
+- **Every repo's media page loads its comfy workflows, not only the first one's.** comfy-ts keeps one instance per process, rooted at one repo, and the daemon serves every repo from one process: the second repo to load its workflows got "conflicts with the existing instance". The instance is now the first repo's, holding only the host caches every repo on that host shares, and each repo's drafts resolve under its own `.comfy-ts/drafts/`.
+
+- **Editing shipkit no longer re-runs every check in every repo.** The cache key hashed the toolkit's whole source, and a repo that links it hashed the linked package again, tests included, so a css tweak of the hub or a new test re-ran every cached check everywhere. A key now carries the runner (the modules that run a check and store its answer, and the templates a check reads), the check's own module closure (modules it runs by path included), and for a check running the repo's code, the toolkit modules the repo imports. An edit no answer depends on moves no key, and `sk keys --why` lists the toolkit files behind a key.
+
+- **⌘↑ and ⌘↓ open the repo above or below in the project list**, from any page, round both ends. In a text field they still move the caret. The list's foot hints them, and its sort button now just says sort, the order it is in moving to its title.
+
+- **An app icon fills its tile, on the repo's colour.** The shipkit app and every process app drew the repo's mark as it was, transparent margin included, so a small mark was a dot on the dock. The icon now cuts the mark to its own box (faint alpha noise, which generated images carry over the whole canvas, counts as margin) and sets it on a rounded plate in the identity colour it stands out on most, on the macOS icon grid. A mark that already fills its box, a photo or a tile, becomes the plate. New colours rebuild the app at its next open.
+
+- **The identity colours moved to the admin page, with a preview of the app icon.** The two pickers left the strip. The admin page opens on an identity card: the app icon drawn in the colours being picked (`/api/projects/app-icon/<repo>`, the same drawing the app build uses), and the repo name on a dark and on a light page. The card reads a repo by the name the project list knows, so a repo whose config names it otherwise (screenplay, named screenplay-shed) shows its own colours and icon.
+
+- **A broken comfy setup no longer takes the whole media page down.** The workflows load only when a kind generates with comfy. When they fail to load, the media API still mounts: the rolls, the picks and every other kind stay served, and the reason shows in the page errors and in every comfy roll that fails.
+
+- **`@napi-rs/canvas` and `comfy-ts` are one copy per process, like the toolkit.** A repo file that imports its own install gets the host copy. A brand that loaded an image with its own canvas copy and drew it on the toolkit's canvas failed ("Value is not one of these types"), and workflows written against an older comfy-ts failed to load.
+
+- **A failing test no longer paints the last test file red.** Bun repeats every failure in a recap after the last file of its report, and the hub read those lines as failures of that file: the tests page and the problems pane blamed an innocent suite. The recap now closes the report.
+
+- **The arrows walk the repo tree from anywhere on the page.** Up and down move to the next row and open its page at once, with no need to click the tree first. Left and right fold, unfold and climb as before. In the filter box, up and down walk the rows the filter keeps, and left and right stay the text caret's. With no cursor yet, they start from the section of the page shown. A branch with no page of its own only takes the cursor. A walk with the arrows is one history entry, so a held arrow never floods the browser history and back returns to where the walk started. While an asset is open, left and right stay the atelier's roll keys.
+
+- **No repo page is a card grid.** Every collection without a table of its own (contracts, reflections, posts, workflows) is now a list, one line per item, red first. The processes page is the overview's process table for that repo, with the opened process's description and log under it. The tables sit on a panel box for contrast, and the page title and group headers are larger and in plain ink.
+
+- **The secrets page is a list.** One line per secret, never a card: a dot, the name, missing, minor or present, and its sentence. Missing ones come first.
+
 ## 1.5.0
 
 - **Every check declares where it runs and how it caches, with no default.** A check file carries `runs` (`onPreCommit`, `onCi`, `onFull`, `onRelease`, `onHealth`, `onSave`, `onClock`), `cache` (`files`, `reads`, `ttl`, `fact` or `never`, each with its one parameter), `fix` (`none`, `ci` or `manual`, the function itself is now `repair`) and `applies`. `check()` refuses a missing key, a retired key (`when`, `inputs`, `ttl`, `never`, `every`, `cron`, `whenInactive`, `planOff`, `cacheKey`) and the combinations that contradict each other. The gate, the fix pass, the release preflight and the planner read the declared axes; a release never applies a check repair. Every built-in carries its own placement: SK024, SK017 and SK028 run in the health pass only, and SK005, SK006, SK011, SK014, SK016 and SK022 are out of the quick gate. A check file that does not load is one failing row instead of a dead inventory.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "1.5.0",
+    "version": "1.6.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",

package/src/assets/gen/comfyts-gen.ts

@@ -12,7 +12,8 @@ import { ComfyTS, type AnyVar, type ComfyExecution, type DefinedWorkflow, type M
 export type GenProgress = { value: number; max: number; node: string | null }
 export type OnProgress = (p: GenProgress) => void
 
-export type LoadedWorkflow = { id: string; file: string; wf: DefinedWorkflow }
+/** root: the repo the workflow belongs to, which holds its drafts */
+export type LoadedWorkflow = { id: string; root: string; file: string; wf: DefinedWorkflow }
 export type ComfyTsRuntime = { workflows: Map<string, LoadedWorkflow>; heal?: string }
 
 // function declaration, not const — TS only narrows on never-calls to
@@ -47,9 +48,11 @@ export async function loadCflowWorkflows(root: string, dir: string): Promise<Map
     // explicit COMFY_TS_QUIET=0 from the caller.
     process.env.COMFY_TS_QUIET ??= '1'
     // before the first module import: a bare ComfyTS.create() inside the
-    // module then returns this same instance. A pre-existing instance with a
-    // different root throws loud — a real misconfiguration.
-    ComfyTS.create({ rootPath: root })
+    // module then returns this same instance. comfy-ts keeps ONE instance per
+    // process, and the daemon serves every repo from one process, so only the
+    // first repo roots it. What it roots is the host caches, shared by every
+    // repo on the same host; each repo's drafts resolve from its own root
+    if ((globalThis as { comfyts?: unknown }).comfyts == null) ComfyTS.create({ rootPath: root })
     if (!existsSync(dir)) fail(`${dir}/ missing — ship at least one <id>.cflow.ts comfy-ts workflow module (copy from the rv-comfy template)`)
     const out = new Map<string, LoadedWorkflow>()
     for (const f of readdirSync(dir).filter((x) => x.endsWith('.cflow.ts')).sort()) {
@@ -65,7 +68,7 @@ export async function loadCflowWorkflows(root: string, dir: string): Promise<Map
         const vars = varsOf(wf)
         if (vars.prompt?.kind !== 'prompt' || vars.seed?.kind !== 'seed')
             fail(`workflow '${id}' must declare vars.prompt (v.prompt) and vars.seed (v.seed) — shipkit drives both`)
-        out.set(id, { id, file, wf })
+        out.set(id, { id, root, file, wf })
     }
     if (out.size === 0) fail(`${dir}/ has no *.cflow.ts workflow modules — seed one from the rv-comfy template`)
     return out
@@ -96,8 +99,9 @@ export function applyVarValues(wf: DefinedWorkflow, vars: Record<string, unknown
     }
 }
 
-// ── drafts — comfy-ts disk format, path rule taken from the ComfyTS instance
-// so it cannot drift: .comfy-ts/drafts/<wfId>/<draftId>.json.
+// ── drafts — comfy-ts disk format, .comfy-ts/drafts/<wfId>/<draftId>.json
+// under the workflow's own repo, never the process instance's root (which is
+// the first repo's in the daemon).
 //
 // The draft id is the KIND, never the asset: ONE `creature` draft behind all
 // 107 creatures, so tuning the loras once tunes them for the whole kind. The
@@ -107,7 +111,7 @@ export function applyVarValues(wf: DefinedWorkflow, vars: Record<string, unknown
 //
 // Shipkit does its own IO here because comfy-ts exports no drafts API yet;
 // swap when it lands.
-const draftDir = (lw: LoadedWorkflow): string => ComfyTS.create().resolveFromDrafts(lw.id)
+const draftDir = (lw: LoadedWorkflow): string => join(lw.root, '.comfy-ts', 'drafts', lw.id)
 export const draftPath = (lw: LoadedWorkflow, name: string): string => join(draftDir(lw), `${name}.json`)
 
 export function readAssetDraft(lw: LoadedWorkflow, draftId: string): Record<string, unknown> | null {

package/src/assets/server/studio-server.ts

@@ -49,7 +49,18 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
     const workspace = join(root, kit.workspace)
     const dirOf = (id: string): string => assetDir(workspace, id)
     let workflows: Map<string, LoadedWorkflow> | null = null
-    if (kit.comfy != null) workflows = await loadCflowWorkflows(root, join(root, kit.comfy.workflows))
+    // only a comfy kind needs them, and a broken load costs only comfy
+    // generation: the rolls, the picks and every other kind stay served, and
+    // the reason rides in /api/state errors and in every comfy roll that fails
+    let comfyErr: string | null = null
+    if (kit.comfy != null && kit.kinds.some((k) => k.generate.backend === 'comfy')) {
+        try {
+            workflows = await loadCflowWorkflows(root, join(root, kit.comfy.workflows))
+        } catch (e) {
+            comfyErr = `comfy workflows not loaded: ${(e as Error).message}`
+            console.log(`WARN ${comfyErr}`)
+        }
+    }
 
     // custom panel scripts fail-fast here too (tests/embedders may bypass loadKit)
     const missingPanels = missingPanelScripts(kit, root)
@@ -111,6 +122,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
     // workflows are pre-loaded above (fail-fast for a comfy studio); the
     // resolver just hands the shared roll generator the ready runtime.
     const resolveComfy = async (): Promise<ComfyTsRuntime> => {
+        if (comfyErr != null) throw new Error(comfyErr)
         if (kit.comfy == null || workflows == null) throw new Error('kit has no comfy config — only canvas kinds can generate')
         return { workflows, heal: kit.comfy.heal }
     }
@@ -243,7 +255,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
                     derived: parentIdsOf(f).length > 0, stale: await isStale(kit, workspace, f),
                 }
             }))
-            return json({ ...queue.state, queued: queue.queuedCount, pending: queue.pendingIds(), errors: queue.errors.slice(-5), assets })
+            return json({ ...queue.state, queued: queue.queuedCount, pending: queue.pendingIds(), errors: [...(comfyErr == null ? [] : [comfyErr]), ...queue.errors.slice(-5)], assets })
         }
 
         if (pathname === '/api/asset') {

package/src/check.ts

@@ -238,14 +238,11 @@ export type TaskDef = {
     timeoutMs?: number
     /** CONTENT population: the repo-relative paths this task reads. Declaring
      *  them is what makes it keyable (ledger/git-key.ts). Undeclared is the
-     *  DEFAULT and means never cached, so forgetting one costs speed and
-     *  never correctness. A list MISSING a path the command reads is the one
-     *  that costs correctness: the key cannot move when that path changes, so
-     *  a cached answer comes back over a tree it no longer describes. `['.']` is the
-     *  whole TRACKED tree, and it is NOT a catch-all: an ignored path enters a
-     *  key by name and never by content, so a task reading a gitignored
-     *  fixture, a built dir or a .env under declares with `['.']` exactly as
-     *  it would with a narrow list. */
+     *  DEFAULT: the task is keyed on the whole work tree plus the repo's
+     *  `ignoredInputs` (build/shipkit/cache.md). A list MISSING a path
+     *  the command reads is the one that costs correctness: the key cannot
+     *  move when that path changes, so a cached answer comes back over a tree
+     *  it no longer describes. */
     inputs?: string[]
     /** WORLD population: it reads the network, a keychain, $PATH or the clock,
      *  so nothing on disk describes its answer and a clean pass is remembered

package/src/checks/SK001-package-json-shape.check.ts

@@ -125,13 +125,14 @@ export function evaluatePackageJson(t: CheckCtx): void {
 //
 // a shipkit verb is never on this list. `shipkit ci`, `check`, `contracts`,
 // `tui`, `mv`, `assets`, `asks` are typed as themselves, and a package.json
-// row that only forwards to one is a second name for one capability
+// row that only forwards to one is a second name for one capability. nor is
+// a global process (ComfyUI, TTS): `shipkit gp start <id>` starts it from any
+// repo, so a per repo script would only copy it
 function requiredScripts(c: CheckCtx): Array<{ name: string; why: string }> {
     const required: Array<{ name: string; why: string }> = [
         // watch-mode serve — the ONE shipkit surface the bare verb cannot give
         { name: 'hub', why: 'shipkit repo' },
     ]
-    if (c.exists('.shipkit/comfy')) required.push({ name: 'comfy:up', why: '.shipkit/comfy/ exists' })
     if (c.exists('deploy.sh')) required.push({ name: 'up', why: 'deploy.sh exists' })
     return required
 }
@@ -203,8 +204,8 @@ export const packageJsonShape = check({
     applies: 'always',
     run: (c) => evaluatePackageJson(c),
     // mechanical repairs only: field flips + scripts whose canonical body the
-    // vocabulary page states. Bodies it does NOT state (assets, comfy:up) are
-    // named in the summary, never invented. rvlib-* roots untouched — their
+    // vocabulary page states. A body it does NOT state is named in the
+    // summary, never invented. rvlib-* roots untouched — their
     // license/private are publish decisions.
     repair: (c): FixResult => {
         const raw = c.read('package.json')

package/src/checks/SK003-claude-md-shape.check.ts

@@ -18,8 +18,8 @@ export const claudeMdShape = check({
     title: 'CLAUDE.md',
     description: 'CLAUDE.md loads the house wiki into every session',
     owner: 'meta/agent-folder.md',
-    // keyed on what it reads: CLAUDE.md and whether agent/index.md exists. The
-    // gitignore probe runs git, so an answer that took it is never stored
+    // keyed on what it reads: CLAUDE.md, whether agent/index.md exists, and
+    // the ignore files git read for the gitignore probe (c.exec runs traced)
     runs: { onPreCommit: { budgetMs: 40 }, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     cache: { by: 'reads' },
     fix: 'ci',

package/src/checks/SK030-cache-audit.check.ts

@@ -0,0 +1,34 @@
+// SK030 cache audit (build/shipkit/runs.md owns the cache): a sample of the
+// checks the cache answers is re-run fresh about once a day, and a cached
+// green a fresh run disagrees with fails, naming the check whose key misses a
+// path. The work is `sk cache-audit` (core/cache-audit.ts), in its own
+// process, because it runs other checks.
+import { join } from 'path'
+import { check } from '../check.ts'
+
+const CLI = join(import.meta.dir, '../cli.ts')
+
+export const cacheAudit = check({
+    id: 'SK030',
+    title: 'cache audit',
+    description: 'a sample of cached answers matches what a fresh run of each check says',
+    owner: 'build/shipkit/runs.md',
+    blocking: true,
+    // never a gate: it re-runs other checks. The daemon asks it about once a
+    // day, and only while somebody works in the repo
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: false, onClock: { every: ['20h', '28h'], inactive: 'wait' } },
+    cache: { by: 'never', why: 'it runs other checks fresh, so its answer is that run itself' },
+    fix: 'none',
+    applies: 'always',
+    run: async (c) => {
+        const r = await c.exec([process.execPath, CLI, 'cache-audit', '--json'], { cwd: c.root, timeoutMs: 600_000 })
+        let out: { pool: number; rows: { id: string; cached: string; fresh: string; keyedOn: string }[]; stale: { id: string; cached: string; fresh: string; keyedOn: string }[] }
+        try { out = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') } catch { return c.fail(`sk cache-audit did not answer (exit ${r.code}: ${r.out.trim().slice(0, 160)})`) }
+        if (out.rows.length === 0) return c.note(`nothing to audit: the cache answers none of this repo's checks right now`)
+        for (const s of out.stale)
+            c.fail(`${s.id}: the cache said ${s.cached}, a fresh run says ${s.fresh}, so its key misses something it reads`, `${s.keyedOn === 'files' ? 'add the path to its cache.inputs' : 'move the read through c'}, then sk keys --why ${s.id}`)
+        if (out.stale.length === 0) c.ok(`${out.rows.map((x) => x.id).join(', ')}: every cached answer is what a fresh run says (${out.rows.length} of ${out.pool} cached)`)
+    },
+})
+
+export default cacheAudit

package/src/checks/SK031-trace-audit.check.ts

@@ -0,0 +1,39 @@
+// SK031 traced audit (build/shipkit/cache.md owns the key): about once a day
+// each gate task runs under the tracer, and a gitignored path it reads that
+// its key misses joins that task's key from the kept answer. SK032 carries the
+// kept proposals into repo.config.ts in the gate's fix pass. The work is
+// `sk trace-audit` (core/trace-audit.ts), in its own process, because it runs
+// the gate's tasks. On wherever the tracer runs, unless the machine opted out.
+import { join } from 'path'
+import { check } from '../check.ts'
+import { traceUnavailable } from '../trace/tracer.ts'
+
+const CLI = join(import.meta.dir, '../cli.ts')
+
+export const traceAuditCheck = check({
+    id: 'SK031',
+    title: 'traced audit',
+    description: 'every gitignored path a gate task reads is in its key',
+    owner: 'build/shipkit/cache.md',
+    blocking: false,
+    // never a gate: it runs the gate's tasks. The daemon asks it about once a
+    // day, and only while somebody works in the repo
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: false, onClock: { every: ['20h', '28h'], inactive: 'wait' } },
+    cache: { by: 'never', why: 'it runs the gate tasks under the tracer, so its answer is that run itself' },
+    fix: 'none',
+    applies: () => traceUnavailable(),
+    run: async (c) => {
+        const r = await c.exec([process.execPath, CLI, 'trace-audit', '--json'], { cwd: c.root, timeoutMs: 1_200_000 })
+        let out: { skipped?: string; tasks: { id: string; status: string; why?: string; uncovered: string[]; propose: string[] }[] }
+        try { out = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') } catch { return c.fail(`sk trace-audit did not answer (exit ${r.code}: ${r.out.trim().slice(0, 160)})`) }
+        if (out.skipped != null) return c.note(`nothing traced: ${out.skipped}`)
+        for (const t of out.tasks.filter((x) => x.status === 'unaudited')) c.warn(`${t.id} could not be audited: ${t.why}`)
+        const missing = out.tasks.filter((x) => x.uncovered.length > 0)
+        // a finding joins its task's key at once (core/audit-report.ts), so it
+        // is news, never a failure: SK032 carries it into repo.config.ts
+        for (const t of missing) c.ok(`${t.id} reads ${t.uncovered.length} gitignored path(s) the config does not name, keyed from this audit: ${t.propose.join(', ')}`)
+        if (missing.length === 0) c.ok(`${out.tasks.filter((x) => x.status === 'audited').length} gate task(s) audited: every gitignored path they read is in their key`)
+    },
+})
+
+export default traceAuditCheck

package/src/checks/SK032-ignored-inputs.check.ts

@@ -0,0 +1,79 @@
+// SK032 ignored inputs current (build/shipkit/cache.md owns the key): what the
+// last traced audit (SK031) found a task reading outside its key is in
+// repo.config.ts ignoredInputs, so other machines and clones key it too. The repair writes the missing entries into
+// the managed block, so the gate's fix pass carries each finding into the
+// config. Nothing is traced here: it reads the audit SK031 kept.
+import { join } from 'path'
+import { check } from '../check.ts'
+import { describeByTask, pendingByTask, type AuditReport } from '../core/ignored-inputs.ts'
+
+const CLI = join(import.meta.dir, '../cli.ts')
+
+/** the first rvlib-shipkit release whose `defineRepo` knows `ignoredInputs`.
+ *  A repo whose pin allows an older one loads its config elsewhere (a CI job
+ *  installing from npm, a fresh clone) with that older copy, which refuses
+ *  the unknown key: so nothing is written until the pin says at least this */
+export const IGNORED_INPUTS_SINCE = '1.6.0'
+
+const parts = (v: string): number[] => v.split('.').map((n) => Number.parseInt(n, 10) || 0)
+const atLeast = (v: string, min: string): boolean => {
+    const a = parts(v), b = parts(min)
+    for (let i = 0; i < 3; i++) if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0)
+    return true
+}
+
+/** why the repo's pin cannot carry the key yet, or null. No pin (the repo
+ *  that hosts the toolkit, or one running it from source) can carry it */
+function pinTooOld(pkg: string | null): string | null {
+    if (pkg == null) return null
+    let range: string | undefined
+    try {
+        const j = JSON.parse(pkg) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        range = j.devDependencies?.['rvlib-shipkit'] ?? j.dependencies?.['rvlib-shipkit']
+    } catch {
+        return null
+    }
+    const min = range == null ? null : /(\d+\.\d+\.\d+)/.exec(range)?.[1] ?? null
+    if (min == null || range!.startsWith('link:') || range!.startsWith('file:') || range!.startsWith('workspace:')) return null
+    return atLeast(min, IGNORED_INPUTS_SINCE) ? null : `package.json pins rvlib-shipkit ${range}, which allows a release before ${IGNORED_INPUTS_SINCE} that refuses ignoredInputs: raise the pin to ^${IGNORED_INPUTS_SINCE} first`
+}
+
+/** the kept audit, read through c so the reads key follows it */
+function kept(text: string | null): AuditReport | null {
+    try { return text == null ? null : (JSON.parse(text) as AuditReport) } catch { return null }
+}
+
+export const ignoredInputsCheck = check({
+    id: 'SK032',
+    title: 'ignored inputs current',
+    description: 'every gitignored path the traced audit saw a task read is in ignoredInputs',
+    owner: 'build/shipkit/cache.md',
+    blocking: false,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: false, onHealth: true, onSave: false, onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
+    run: (c) => {
+        const missing = pendingByTask(kept(c.state('trace-audit.json')), c.config.ignoredInputs ?? {})
+        const n = Object.values(missing).flat().length
+        if (n === 0) return c.ok('repo.config.ts ignoredInputs covers what the last traced audit found')
+        // the keys on this machine already read the kept audit (core/audit-report.ts),
+        // so what is missing here is the copy other machines and clones see
+        const old = pinTooOld(c.read('package.json'))
+        if (old != null) return c.ok(`${n} path(s) the traced audit found are keyed on this machine only: ${old}`)
+        c.warn(`the traced audit found ${describeByTask(missing)}: keyed on this machine, not yet in repo.config.ts ignoredInputs`, 'sk ci writes them, and sk trace-audit --fix says why when it cannot')
+    },
+    repair: async (c) => {
+        const missing = pendingByTask(kept(c.state('trace-audit.json')), c.config.ignoredInputs ?? {})
+        if (Object.keys(missing).length === 0) return { changed: false, summary: 'nothing to add' }
+        const old = pinTooOld(c.read('package.json'))
+        if (old != null) return { changed: false, summary: old }
+        // the managed block writer loads repo.config.ts, which no read through
+        // c can stand for, so it runs in its own process
+        const r = await c.exec([process.execPath, CLI, 'trace-audit', '--fix'], { cwd: c.root, timeoutMs: 60_000 })
+        if (r.code !== 0) return { changed: false, summary: `sk trace-audit --fix failed: ${r.out.trim().split('\n').at(-1) ?? `exit ${r.code}`}` }
+        return { changed: true, summary: `repo.config.ts ignoredInputs gained ${describeByTask(missing)}` }
+    },
+})
+
+export default ignoredInputsCheck

package/src/cli/cmd_Assets.ts

@@ -2,7 +2,11 @@
 // (ComfyUI or procedural canvas), curate in the studio, ship with metadata
 // write-through. Thin clipanion surfaces; logic in assets/run-assets.ts.
 import { Command, Option } from 'clipanion'
-import { runAssetsCheck, runAssetsGen, runAssetsIdentity, runAssetsTopUp, type AssetsIo } from '../assets/run-assets.ts'
+import type { AssetsIo } from '../assets/run-assets.ts'
+
+// loaded when an assets command RUNS: it pulls in canvas, sharp and comfy-ts,
+// which every other command would otherwise pay for at startup
+const assets = (): Promise<typeof import('../assets/run-assets.ts')> => import('../assets/run-assets.ts')
 
 const ioOf = (cmd: Command): AssetsIo => ({
     print: (l) => cmd.context.stdout.write(`${l}\n`),
@@ -33,7 +37,7 @@ export class AssetsFillCommand extends Command {
             this.context.stderr.write(`FAIL: '${this.n}' is not a positive roll count — usage: shipkit assets fill <N> [category…]\n`)
             return 1
         }
-        return runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'fill', n, categories: this.categories })
+        return (await assets()).runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'fill', n, categories: this.categories })
     }
 }
 
@@ -55,7 +59,7 @@ export class AssetsAddCommand extends Command {
             this.context.stderr.write(`FAIL: '${this.n}' is not a positive roll count — usage: shipkit assets add <N> [category…]\n`)
             return 1
         }
-        return runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'add', n, categories: this.categories })
+        return (await assets()).runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'add', n, categories: this.categories })
     }
 }
 
@@ -76,7 +80,7 @@ export class AssetsGenCommand extends Command {
 
     async execute(): Promise<number> {
         const n = Math.max(1, Number(this.n) || 1)
-        return runAssetsGen(process.cwd(), ioOf(this), { assetId: this.assetId, n })
+        return (await assets()).runAssetsGen(process.cwd(), ioOf(this), { assetId: this.assetId, n })
     }
 }
 
@@ -90,7 +94,7 @@ export class AssetsIdentityCommand extends Command {
     })
 
     async execute(): Promise<number> {
-        return runAssetsIdentity(process.cwd(), ioOf(this))
+        return (await assets()).runAssetsIdentity(process.cwd(), ioOf(this))
     }
 }
 
@@ -104,6 +108,6 @@ export class AssetsCheckCommand extends Command {
     })
 
     async execute(): Promise<number> {
-        return runAssetsCheck(process.cwd(), ioOf(this))
+        return (await assets()).runAssetsCheck(process.cwd(), ioOf(this))
     }
 }

package/src/cli/cmd_CacheAudit.ts

@@ -0,0 +1,43 @@
+// sk cache-audit — re-runs a sample of the checks the cache would answer right
+// now, fresh, and compares: a cached green a fresh run disagrees with is a
+// key that misses something its check reads (core/cache-audit.ts).
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { auditCache } from '../core/cache-audit.ts'
+
+export class CacheAuditCommand extends Command {
+    static override paths = [['cache-audit']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'is a cached green still true: re-run a sample of cached checks fresh and compare',
+        details: 'Picks checks the cache would answer right now (keyed on files or on reads), a different stable sample each day, runs each one fresh and compares its verdict with the cached one. A mismatch means the check key misses a path its body reads: the fresh answer replaces the stale one, and the line names the check. Exit 1 on a mismatch.',
+        examples: [
+            ['audit three cached checks', 'sk cache-audit'],
+            ['a bigger sample', 'sk cache-audit --sample 10'],
+            ['one check, by id', 'sk cache-audit --only SK004'],
+            ['machine-readable', 'sk cache-audit --json'],
+        ],
+    })
+
+    sample = Option.String('--sample', '3', { description: 'how many cached checks to re-run fresh (default 3)' })
+    only = Option.Array('--only', { description: 'audit these check ids instead of a sample' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable { pool, rows, stale }' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const n = Number(this.sample)
+        if (!Number.isInteger(n) || n < 1) { this.context.stdout.write(`FAIL: --sample takes a whole number above 0, got '${this.sample}'\n`); return 1 }
+        const r = await auditCache(root, await loadRepoConfig(root), { sample: n, only: this.only })
+        if (this.json) { this.context.stdout.write(`${JSON.stringify(r)}\n`); return r.stale.length > 0 ? 1 : 0 }
+        if (r.rows.length === 0) { this.context.stdout.write(`skip: nothing to audit, the cache answers none of ${this.only?.join(', ') ?? 'the checks'} right now\n`); return 0 }
+        for (const row of r.rows) {
+            const same = row.fresh === row.cached || row.fresh === 'skip'
+            this.context.stdout.write(same
+                ? `ok: ${row.id} cached ${row.cached}, fresh ${row.fresh} (${row.ms}ms)\n`
+                : `FAIL: ${row.id} cached ${row.cached}, but a fresh run says ${row.fresh}: its key misses something it reads\n      fix: ${row.keyedOn === 'files' ? `add the path its body reads to its cache.inputs` : 'move the read through c, or declare cache files or never'}, then sk keys --why ${row.id}\n`)
+        }
+        this.context.stdout.write(r.stale.length === 0 ? `ok: ${r.rows.length} of ${r.pool} cached check(s) audited, every cached answer is what a fresh run says\n` : `FAIL: ${r.stale.length} of ${r.rows.length} audited check(s) served a stale answer\n`)
+        return r.stale.length > 0 ? 1 : 0
+    }
+}

package/src/cli/cmd_CrossRepoActivity.ts

@@ -8,7 +8,6 @@ import { homedir } from 'os'
 import { Command, Option } from 'clipanion'
 import { activityOf, type Declared } from '../home/activity.ts'
 import { ageShort, clampCap, DEFAULT_CAP, DEFAULT_MINUTES, dirtWords, idleRow, upstreamWords, type ActivityAnswer, type ActivityCommit, type ActivityRow } from '../home/activity-shape.ts'
-import { railRepos } from '../serve/project-gutter-route.ts'
 
 /** a span as typed: `10m`, `1h`, `3d`, `90` (minutes); null when it is none */
 export function spanMinutes(v: string): number | null {
@@ -108,6 +107,8 @@ export class CrossRepoActivityCommand extends Command {
         const cap = clampCap(this.maxCommit ?? DEFAULT_CAP)
         const declared = await daemonDeclared()
         // HOME as the shell has it now: the house include names `~`
+        // the hub route module draws app icons, so it loads only when this runs
+        const { railRepos } = await import('../serve/project-gutter-route.ts')
         const a = await activityOf(railRepos(process.cwd(), process.env.HOME || homedir()), minutes, Date.now(), declared)
         if (this.json) {
             this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)

package/src/cli/cmd_GlobalProcesses.ts

@@ -13,7 +13,6 @@ import type { ResourceView } from '../home/resources.ts'
 import { coreGroup, declaredRow, groupRows, processGroups, stateWords, type ProcessGroup } from '../home/process-rows.ts'
 import type { PmConfig } from '../home/pm-config.ts'
 import { readPmConfig } from '../home/run-pm.ts'
-import { railRepos } from '../serve/project-gutter-route.ts'
 
 export type GlobalProcessesAnswer = {
     /** pm as it answered, null when it did not */
@@ -75,11 +74,13 @@ export async function askPm(url = pmUrl()): Promise<PmAnswer | null> {
 
 /** the project list's order and the declared units, read from disk the way
  *  pm reads them: what the table falls back on while pm does not answer */
-export function localProcessDeps(cwd: string): Pick<GlobalProcessesDeps, 'declared' | 'order'> {
+export async function localProcessDeps(cwd: string): Promise<Pick<GlobalProcessesDeps, 'declared' | 'order'>> {
     // HOME as the shell has it now: the house include names `~`
     const home = process.env.HOME || homedir()
     let order: string[] = []
     try {
+        // the hub route module draws app icons: loaded only when this runs
+        const { railRepos } = await import('../serve/project-gutter-route.ts')
         order = railRepos(cwd, home).map((r) => r.name)
     } catch {
         // no rail from here: the groups sort by name
@@ -146,7 +147,7 @@ export class GlobalProcessesCommand extends Command {
     json = Option.Boolean('--json', false, { description: 'the rows as json: { pm, now, groups, errors, house }, groups exactly as the overview draws them' })
 
     async execute(): Promise<number> {
-        const a = await globalProcessesAnswer({ ...localProcessDeps(process.cwd()), pm: () => askPm(), daemon: () => askDaemon(), now: Date.now() })
+        const a = await globalProcessesAnswer({ ...(await localProcessDeps(process.cwd())), pm: () => askPm(), daemon: () => askDaemon(), now: Date.now() })
         if (this.json) {
             this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
             return 0

package/src/cli/cmd_Home.ts

@@ -10,7 +10,6 @@ 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))
@@ -71,6 +70,8 @@ export class DaemonCommand extends Command {
     async execute(): Promise<number> {
         const port = portOf(this, this.port)
         if (port === null) return 1
+        // the daemon hosts every hub, image tools included: loaded when it runs
+        const { runDaemon } = await import('../home/run-daemon.ts')
         return runDaemon(process.cwd(), io(this), { port })
     }
 }
@@ -169,7 +170,7 @@ export class GuiCommand extends Command {
         // `.` = 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 })
+        const cmd = await 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/cmd_Keys.ts

@@ -75,6 +75,14 @@ export class KeysCommand extends Command {
                 return 0
             }
             out(`      key ${k.key}`)
+            // a lib hash names nothing by itself: the files behind it are what
+            // an edit has to touch to move this key
+            const lib = k.libFiles ?? []
+            if (lib.length > 0) {
+                out(`      toolkit files in its lib components: ${lib.length}`)
+                for (const f of lib.slice(0, 12)) out(`        ${f}`)
+                if (lib.length > 12) out(`        … ${lib.length - 12} more (shipkit keys --json)`)
+            }
             if (k.population === 'reads') {
                 for (const comp of k.components) out(`      ${comp}`)
                 // the rest of its identity is what it READ, stored with the
@@ -89,12 +97,15 @@ export class KeysCommand extends Command {
                 const lists = Object.entries(set.lists)
                 const dirs = Object.entries(set.dirs ?? {})
                 const links = Object.entries(set.links ?? {})
-                out(`      read set: ${files.length} file(s), ${exists.length} existence probe(s), ${lists.length} listing(s), ${dirs.length} dir read(s)${links.length > 0 ? `, ${links.length} link probe(s)` : ''}`)
+                // outside the repo a traced read is keyed on stat alone
+                const outside = Object.keys(set.sigs ?? {}).filter((p) => !(p in set.files))
+                out(`      read set: ${files.length} file(s), ${exists.length} existence probe(s), ${lists.length} listing(s), ${dirs.length} dir read(s)${links.length > 0 ? `, ${links.length} link probe(s)` : ''}${outside.length > 0 ? `, ${outside.length} file(s) outside the repo, by stat` : ''}`)
                 for (const [p, oid] of files) out(`        read ${p}=${oid ?? 'absent'}`)
                 for (const [p, kind] of exists) out(`        exists ${p}=${kind ?? 'absent'}`)
                 for (const [g, h] of lists) out(`        list ${g}=${h}`)
                 for (const [d, h] of dirs) out(`        entries ${d}=${h ?? 'absent'}`)
                 for (const [p, is] of links) out(`        link ${p}=${is ? 'yes' : 'no'}`)
+                for (const p of outside) out(`        stat ${p}=${set.sigs![p]}`)
                 return 0
             }
             // the excluded block is 44 lines here and it buries the component

package/src/cli/cmd_Overview.ts

@@ -88,7 +88,7 @@ export class OverviewCommand extends Command {
     json = Option.Boolean('--json', false, { description: 'the answers as json: { now, pm, daemon, processes, widgets }, processes as `shipkit gp --json`, widgets the daemon route\'s payload' })
 
     async execute(): Promise<number> {
-        const a = await overviewAnswer({ ...localProcessDeps(process.cwd()), pm: () => askPm(), daemon: () => askDaemon(), widgets: () => askWidgets(), now: Date.now() })
+        const a = await overviewAnswer({ ...(await localProcessDeps(process.cwd())), pm: () => askPm(), daemon: () => askDaemon(), widgets: () => askWidgets(), now: Date.now() })
         if (this.json) {
             this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
             return 0

package/src/cli/cmd_Serve.ts

@@ -1,7 +1,6 @@
 // shipkit serve — the ONE hub server per repo (one vscode folder-open task,
 // clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
 import { Command, Option } from 'clipanion'
-import { runServe } from '../serve/run-serve.ts'
 
 export class ServeCommand extends Command {
     static override paths = [['serve']]
@@ -27,6 +26,8 @@ export class ServeCommand extends Command {
                 return 1
             }
         }
+        // the hub runtime carries the image tools: loaded when it serves
+        const { runServe } = await import('../serve/run-serve.ts')
         return runServe(process.cwd(), {
             print: (l) => this.context.stdout.write(`${l}\n`),
             printErr: (l) => this.context.stderr.write(`${l}\n`),