rvlib-shipkit 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+## 1.9.0
+
+- **A commit in a linked worktree passes the pre-commit hook.** git sets GIT_DIR for a hook there, and the installed copy then asked git where the house sits and got the worktree back, so it never handed off to the house source. Then it ran itself and failed every built-in check with ENOENT on a `?v=` stamped path. A directory with its own `.git` is now asked with the locating variables stripped, and an installed copy that runs itself (CI, `SHIPKIT_NO_HOME`) loads its own check files.
+- **A broken built-in check no longer aborts every repo's gate.** In a repo that only consumes the toolkit, a built-in that does not load or is refused is one non-blocking WARN that names the file. The repo that hosts the toolkit source still fails on it. Before, it threw a misleading "names the page that OWNS the invariant" error before any check ran.
+- **`sk gp open <id>` probes before it trusts "up".** A process that died since pm last looked now starts before its window opens, instead of a window on a dead port.
+- **A linked worktree of a house repo is no longer a house repo of its own.** The home, the global context and pm skip a sibling whose `.git` is a file, so its global processes no longer collide with the main checkout's ids and ports.
+- **`sk ci --only <check>` leaves the tree alone.** A narrowed run no longer runs the fix pass unless `--fix` is named, so `bun run test`, `lint` and `typecheck`, which route through `--only`, never reformat a shared tree. Before, the formatter ran on every narrowed run and rewrote 478 files of one checkout, other agents' uncommitted work included. A whole gate still repairs first, and `--no-fix` still turns it off.
+
+- **The machine pool admits fewer checks on a loaded machine.** A slot is a check, and a check is often a whole multi core tool, so eight slots on eight cores could put several times the cores to work. Past a 1 minute load of one per core the pool now admits slots in proportion to the load, never fewer than one: at load 20 on 8 cores it admits 3 of 8. A slot already held is never taken back. A waiting check prints the load and what the pool admits.
+
+- **The plan holds save runs while someone gates the repo.** A check a save moved now also waits 10 minutes after the latest run a terminal, an agent or a click started in its repo. On one repo with several agents, most of the plan's test runs had started within those 10 minutes and measured a tree the agents were gating themselves. The run is held, not dropped, so the tree still gets one verdict once they stop. `sk planned` shows the hold as a `deferred:` line.
+- **A suite over the CPU budget in its lone run runs alone once more, and the smaller figure stands.** On a busy Apple silicon machine the scheduler can spill a lone run onto the efficiency cores, where the same work burns up to 4x the CPU time, so a suite inside its budget failed one run in three and passed a minute later. A spill only raises CPU time, so the second run can clear a false red and never hide a real one. A wait or a suite with no CPU figure keeps its one run, and a green gate pays nothing.
+
+- **The gate's test line says the command the suite runner ran.** A plain `bun test` body does not run as written under `sk ci`: the runner adds `--parallel=<n>` and `--no-isolate`. The line now reads `ok: test 412 tests (ran 1.5s) as \`bun test --parallel=7 --no-isolate\` (added --parallel=7 --no-isolate)`, so a reader of package.json knows that `bun run test` outside the gate runs another way. Per file ignores stay out of it.
+
+- **A test phase killed at its ceiling names the suite that hung, and both things that hang a worker.** bun lists the suites still running when a phase is killed, and the parallel phase now reads that list, so the line says `with tests/x.test.ts still running`. It names a synchronous loop and `expect(p).resolves` or `.rejects` on a promise that never settles: bun's per test timeout stops neither, while a plain `await` of such a promise fails at the per test timeout. And a red suite is no longer judged on time: its time is its failure's, so a test that timed out no longer runs again alone and no longer adds a budget FAIL.
+- **The gate typecheck keeps its own incremental cache, and a release can publish with bun.** The built-in typecheck passes `--incremental --tsBuildInfoFile <project dir>/node_modules/.cache/shipkit/<config>.tsbuildinfo` for every project, so a `tsc --watch` task or a raw script on the same tsconfig no longer writes the cache the gate reads. A config without `incremental` gets it too: rvlib-shipkit's own typecheck went from 0.81 s to 0.35 s warm. `release.publisher: 'bun'` makes `sk release` and `sk bump` run `bun publish --access public`, with the token from `release.npmTokenCommand` in `NPM_CONFIG_TOKEN`, for a repo that tests its tarball with `bun pm pack`. The default stays npm, and an unknown publisher fails `defineRepo`.
+
+- **`alert`, `confirm` and `prompt` work in the shipkit app and in every process app.** The app window answered each one at once with no panel: `confirm` returned false and `prompt` null, so a page button behind one did nothing. Each now shows as a sheet on its window. The prompt's text field holds the default text, selected. Return is OK and Esc is Cancel. An app picks it up the next time `sk gui` or `sk gp open <id> --app` opens it, because a changed source rebuilds the app and quits the running copy.
+
+- **The `prompt` and `seed` vars contract binds only the workflows a kit kind drives.** Loading the workflows folder no longer refuses a module that lacks them, so a workflow the repo drives with its own tools (portraits, voice, music) names its vars freely. The check runs when the atelier resolves the workflow for a kind, and the error names that kind.
+
+- **`sk assets gen` works on a repo whose comfy-ts is newer than shipkit's.** The one comfy-ts instance of the process is now created through the copy the repo's workflow modules import, so a module gets the vars builder of its own version. Before, shipkit's older copy rooted it, and a module using a newer var kind failed every roll (`v.model is not a function`).
+
+- **The og card draws accented names.** The default card names a font family list (Helvetica, Arial, DejaVu Sans, Liberation Sans, Noto Sans, then sans-serif). The generic sans-serif alone resolved on macOS to a face with no Latin-1 accents, so a French name rendered with a missing glyph box.
+
+- **`sk smoke` serves canvas apps: a route takes `minChars`**, the visible text a settled route needs (default 40). A game that draws into one canvas declares `{ path: '/', waitFor: 'canvas', minChars: 0 }`, and a missing canvas still fails the route.
+
+- **`serve: { assets: false }` hides the asset kit from the hub page and from `sk needs`**, for a repo whose own tool mounts `studioRoutes` and owns the picking. Workflows and posts stay.
+
+- **`defineKit({ rollFormat: 'webp-lossless' })` stores new image rolls as lossless webp**, the same pixels at about 60 percent of the png bytes, encoded with sharp. Existing png rolls stay readable beside them.
+
+## 1.8.0
+
+- **The quick tier can run only the suites a change reaches** (opt in: `tests: { select: true }`, or `SHIPKIT_TEST_SELECT=1` for one run). It keeps the snapshot of the last run and its red suites, and runs those plus every suite whose import closure, or whose recorded runtime reads, a change since then reaches. What it cannot see it runs: an unclaimed change under a code root, a spawn it does not know, a module that threw while loading, a run config file. The full tier still runs every suite.
+
+- **Runs of one repo in the home share, then overlap.** A terminal `sk ci` or `sk check` identical to one in flight on the same tree attaches to it, prints its lines and exits with its code. Runs without the repair pass start at once beside the runs in flight, bounded by the machine slot pool. A run with the repair pass still goes alone. Before, every run of a repo queued behind the one in flight, so a one second gate could wait minutes.
+
+- **The house context: one generated file every house agent loads.** `sk global-context` builds `generated/global-context.md` beside the house index. It lists every global process with the commands that drive it, every house repo, and each repo's `agent/global-contribution.md`. The daemon rewrites it within a minute of a source moving. A process or repo description joins by its first line only, and every item is scanned with the banned keywords of the commit leak guard: a hit leaves it out and says so. It exists only for a house whose index includes `@generated/global-context.md`. `--write` writes it and `--check` fails when it is stale.
+
+- **SK033: every house repo carries `agent/global-contribution.md`.** It is what the repo offers every other agent, capped at 40 lines and 3 KB with no heading above `####`, and `sk ci` writes a comment-only stub when it is missing. It applies only where the house index loads the generated context. It is cached on the file, so the check body runs again only when the file moves. SK027 no longer calls the file an orphan, because the house index links it.
+
+- **`sk gp open <id>` opens a global process's url** in the default browser, in Chrome (`--chrome`) or as its own app (`--app`), the overview's open buttons in the console. A process that is down starts first.
+
+- **The quick tier honours the worker count a repo names.** A `--parallel=<n>` in the repo's own `bun test` body is now a ceiling over the machine pool's share: the parallel phase takes the smaller of the two, as the one `--parallel` on its line. Before, the runner appended its own count after the body, and bun reads the last one, so a repo that measured fewer workers as faster still ran on every core of an idle machine. A bare `--parallel` keeps the pool's count.
+
+- **Declared serial suites and the full tier stay one at a time when the repo's body names `--parallel`.** The runner passed the body as written to the serial phase, to the full tier and to a suspect's alone rerun. So a body naming `--parallel=7` ran its declared serial suites, the ones that cannot share a run, in seven workers, and its full tier too, which runs one suite at a time because its suites spawn git and whole gates. Only the quick tier's parallel phase names a worker count now, and the runner keeps the body's `--parallel` off every other line.
+
 ## 1.7.0
 
 - **Cmd-F in the shipkit app shows a find bar now.** Since the app shipped, the Find menu did nothing visible: NSTextFinder never shows its bar for a web view. The app now draws its own bar on WebKit's find API. Return and cmd-G go to the next match, shift-return and shift-cmd-G to the previous one, Esc closes the bar, and it says "no match" when the page does not hold the text. Rebuilt apps pick it up at their next launch.

package/package.json

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

@@ -40,6 +40,19 @@ const varsOf = (wf: DefinedWorkflow): Record<string, AnyVar> => wf.vars as Recor
 export const isRollImage = (img: Pick<MediaImage, 'ComfyNode'>): boolean =>
     !/preview/i.test(img.ComfyNode?.class_type ?? '')
 
+/** the ComfyTS class of the comfy-ts a bare import from `dir` reaches,
+ *  shipkit's own when the repo carries none */
+async function comfyTsOf(dir: string): Promise<typeof ComfyTS> {
+    let path: string
+    try {
+        path = Bun.resolveSync('comfy-ts', dir)
+    } catch {
+        return ComfyTS
+    }
+    const mod = (await import(path)) as { ComfyTS?: typeof ComfyTS }
+    return typeof mod.ComfyTS?.create === 'function' ? mod.ComfyTS : ComfyTS
+}
+
 /** dir = the flat folder holding the <id>.cflow.ts workflow modules.
  *  root pins `.comfy-ts/` (drafts, hosts cache) to the repo, cwd-independent. */
 export async function loadCflowWorkflows(root: string, dir: string): Promise<Map<string, LoadedWorkflow>> {
@@ -51,9 +64,12 @@ export async function loadCflowWorkflows(root: string, dir: string): Promise<Map
     // 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 })
+    // repo on the same host; each repo's drafts resolve from its own root.
+    // The instance is created through the copy the modules import, never
+    // shipkit's own: a host hands its vars builder to defineWorkflow, so an
+    // older copy gives a newer module a v without its newer var kinds
     if (!existsSync(dir)) fail(`${dir}/ missing — ship at least one <id>.cflow.ts comfy-ts workflow module (copy from the rv-comfy template)`)
+    if ((globalThis as { comfyts?: unknown }).comfyts == null) (await comfyTsOf(dir)).create({ rootPath: root })
     const out = new Map<string, LoadedWorkflow>()
     for (const f of readdirSync(dir).filter((x) => x.endsWith('.cflow.ts')).sort()) {
         const file = join(dir, f)
@@ -65,24 +81,25 @@ export async function loadCflowWorkflows(root: string, dir: string): Promise<Map
         // so letting them diverge would strand every per-asset draft
         if (wf.spec.id != null && wf.spec.id !== id) fail(`workflow file '${f}' declares id '${wf.spec.id}' — the file name IS the id, rename one`)
         wf.spec.id ??= id
-        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, root, file, wf })
     }
     if (out.size === 0) fail(`${dir}/ has no *.cflow.ts workflow modules — seed one from the rv-comfy template`)
     return out
 }
 
-/** Resolve a workflow: explicit id, else the sole loaded workflow. */
-export function workflowFor(workflows: Map<string, LoadedWorkflow>, ref: { workflow?: string; assetId?: string }): LoadedWorkflow {
-    if (ref.workflow != null) {
-        const lw = workflows.get(ref.workflow)
-        if (lw == null) fail(`asset '${ref.assetId ?? '?'}': unknown workflow '${ref.workflow}' (have: ${[...workflows.keys()].join(', ')})`)
-        return lw
-    }
-    if (workflows.size === 1) return [...workflows.values()][0]!
-    return fail(`asset '${ref.assetId ?? '?'}' names no workflow and ${workflows.size} are loaded (${[...workflows.keys()].join(', ')}) — set workflow on the kind`)
+/** Resolve the workflow a kit kind drives: explicit id, else the sole loaded
+ *  workflow. The atelier writes prompt and seed, so the contract binds here,
+ *  never at folder load: a workflow no kind drives names its vars freely. */
+export function workflowFor(workflows: Map<string, LoadedWorkflow>, ref: { workflow?: string; kind?: string; assetId?: string }): LoadedWorkflow {
+    const lw = ref.workflow != null
+        ? (workflows.get(ref.workflow) ?? fail(`asset '${ref.assetId ?? '?'}': unknown workflow '${ref.workflow}' (have: ${[...workflows.keys()].join(', ')})`))
+        : workflows.size === 1
+          ? [...workflows.values()][0]!
+          : fail(`asset '${ref.assetId ?? '?'}' names no workflow and ${workflows.size} are loaded (${[...workflows.keys()].join(', ')}) — set workflow on the kind`)
+    const vars = varsOf(lw.wf)
+    if (vars.prompt?.kind !== 'prompt' || vars.seed?.kind !== 'seed')
+        fail(`kind '${ref.kind ?? '?'}' drives workflow '${lw.id}', which must declare vars.prompt (v.prompt) and vars.seed (v.seed) — the atelier writes both`)
+    return lw
 }
 
 /** Apply a name→value record onto a workflow's vars: strings go through

package/src/assets/gen/generate-roll.ts

@@ -4,9 +4,9 @@
 // in both (before this, canvas draw lived only in the studio and the CLI
 // refused canvas kinds — A30). Comfy context is resolved LAZILY: canvas-only
 // kits never touch a comfy config or the box.
-import { mkdirSync } from 'fs'
+import { mkdirSync, unlinkSync } from 'fs'
 import { join } from 'path'
-import type { FoundAsset } from '../kit-config.ts'
+import type { FoundAsset, RollFormat } from '../kit-config.ts'
 import { generateComfyTs, loadCflowWorkflows, workflowFor, type ComfyTsRuntime, type OnProgress } from './comfyts-gen.ts'
 import { recordParents, type ParentContext } from './derived.ts'
 import { generateGemini } from './gemini-gen.ts'
@@ -16,11 +16,22 @@ export const CANVAS_SIZE = 1024
 
 export type ComfyResolver = () => Promise<ComfyTsRuntime>
 
+/** re-encode freshly written png rolls in the kit's roll format, before any
+ *  sidecar names them. `exact` keeps the colour under transparent pixels */
+async function encodeRolls(saved: string[], format: RollFormat | undefined): Promise<void> {
+    if (format !== 'webp-lossless') return
+    const { default: sharp } = await import('sharp')
+    for (const png of saved.filter((p) => p.endsWith('.png'))) {
+        await sharp(png).webp({ lossless: true, exact: true }).toFile(png.replace(/\.png$/, '.webp'))
+        unlinkSync(png)
+    }
+}
+
 /** Draw/generate one roll for `found` into destDir as v<seed>.png (canvas) or
  *  v<seed>.<ext> (comfy). `resolveComfy` is only awaited for comfy backends. */
 export async function generateRoll(
     found: FoundAsset,
-    args: { prompt: string; seed: number; destDir: string; onProgress?: OnProgress; context?: ParentContext },
+    args: { prompt: string; seed: number; destDir: string; onProgress?: OnProgress; context?: ParentContext; rollFormat?: RollFormat },
     resolveComfy: ComfyResolver,
 ): Promise<void> {
     const gen = found.kind.generate
@@ -31,7 +42,7 @@ export async function generateRoll(
         // resolves them (queue/CLI) so a blocker names the parent, loud
         if ((found.asset.from?.length ?? 0) > 0 && args.context == null)
             throw new Error(`'${found.asset.id}' derives from ${found.asset.from!.join(', ')} — parent context missing (are the parents picked?)`)
-        await generateGemini({}, { prompt: args.prompt, model: gen.model, destDir: args.destDir, name: `v${args.seed}`, context: args.context?.images ?? [] })
+        await encodeRolls(await generateGemini({}, { prompt: args.prompt, model: gen.model, destDir: args.destDir, name: `v${args.seed}`, context: args.context?.images ?? [] }), args.rollFormat)
         if (args.context != null) await recordParents(args.destDir, args.seed, args.context.parents)
         return
     }
@@ -40,12 +51,14 @@ export async function generateRoll(
         const c = createCanvas(CANVAS_SIZE, CANVAS_SIZE)
         await gen.draw(c.getContext('2d'), { ...found.asset, prompt: args.prompt })
         mkdirSync(args.destDir, { recursive: true })
-        await Bun.write(join(args.destDir, `v${args.seed}.png`), c.toBuffer('image/png'))
+        const png = join(args.destDir, `v${args.seed}.png`)
+        await Bun.write(png, c.toBuffer('image/png'))
+        await encodeRolls([png], args.rollFormat)
         return
     }
     const rt = await resolveComfy()
-    const lw = workflowFor(rt.workflows, { workflow: gen.workflow, assetId: found.asset.id })
-    await generateComfyTs(rt, lw, { prompt: args.prompt, seed: args.seed, assetId: found.asset.id, draftId: found.kind.id, destDir: args.destDir, name: `v${args.seed}`, vars: gen.vars, onProgress: args.onProgress })
+    const lw = workflowFor(rt.workflows, { workflow: gen.workflow, kind: found.kind.id, assetId: found.asset.id })
+    await encodeRolls(await generateComfyTs(rt, lw, { prompt: args.prompt, seed: args.seed, assetId: found.asset.id, draftId: found.kind.id, destDir: args.destDir, name: `v${args.seed}`, vars: gen.vars, onProgress: args.onProgress }), args.rollFormat)
 }
 
 /** Memoized lazy comfy runtime for a resolved kit — loads the cflow modules on

package/src/assets/kit-config.ts

@@ -127,14 +127,23 @@ export type KitConfig = {
     /** workflows = dir of comfy-ts .cflow.ts modules (each module owns its
      *  host); heal = shell command shown in error hints, never executed */
     comfy?: { workflows: string; heal?: string }
+    /** absent: an image roll lands in the format its backend produced (png
+     *  from comfy and canvas). 'webp-lossless' re-encodes every new image
+     *  roll as lossless webp, the same pixels at about 60% of the bytes */
+    rollFormat?: RollFormat
     kinds: Kind[]
 }
 
+export const ROLL_FORMATS = ['webp-lossless'] as const
+export type RollFormat = (typeof ROLL_FORMATS)[number]
+
 export type ResolvedKit = KitConfig & { workspace: string }
 
 export function validateKit(k: KitConfig): string[] {
     const errs: string[] = []
     if (!Array.isArray(k.kinds) || k.kinds.length === 0) errs.push('kinds must be a non-empty array')
+    if (k.rollFormat != null && !(ROLL_FORMATS as readonly string[]).includes(k.rollFormat))
+        errs.push(`unknown rollFormat '${String(k.rollFormat)}' (${ROLL_FORMATS.join(' | ')}, or absent for the backend's own format)`)
     for (const key of Object.keys(k.comfy ?? {}))
         if (key !== 'workflows' && key !== 'heal')
             errs.push(`comfy config has unknown key '${key}'${key === 'host' ? " — host is gone, the workflow's _host.ts owns the box (comfy-ts migration)" : ''}`)

package/src/assets/kits/identity-kit.ts

@@ -51,10 +51,16 @@ export function identityKinds(brand: Brand): Kind[] {
     ]
 }
 
+// named faces first: the generic sans-serif can resolve to a face with no
+// Latin-1 accents (macOS). Each family below carries them, and an absent one
+// is skipped (macOS, Windows, then the common Linux faces)
+const OG_FAMILIES = 'Helvetica, Arial, "DejaVu Sans", "Liberation Sans", "Noto Sans", sans-serif'
+export const ogFont = (px: number, bold = false): string => `${bold ? 'bold ' : ''}${px}px ${OG_FAMILIES}`
+
 // shrink px until text fits maxW (og cards must never clip the tagline)
 const fitFont = (ctx: SKRSContext2D, text: string, px: number, maxW: number, bold = false): void => {
     for (; px > 12; px -= 2) {
-        ctx.font = `${bold ? 'bold ' : ''}${px}px sans-serif`
+        ctx.font = ogFont(px, bold)
         if (ctx.measureText(text).width <= maxW) return
     }
 }

package/src/assets/run-assets.ts

@@ -50,7 +50,7 @@ async function rollOnce(root: string, io: AssetsIo, kit: ResolvedKit, resolveCom
     for (let i = 0; i < count; i++) {
         const seed = randomSeed()
         try {
-            await generateRoll(f!, { prompt, seed, destDir: dir, context }, resolveComfy)
+            await generateRoll(f!, { prompt, seed, destDir: dir, context, rollFormat: kit.rollFormat }, resolveComfy)
             io.print(`ok: ${assetId} v${seed}`)
         } catch (e) {
             failed++
@@ -196,7 +196,7 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
                     const gen = kind.generate
                     if (gen.backend !== 'comfy') continue
                     try {
-                        const lw = workflowFor(wfs, { workflow: gen.workflow, assetId: kind.assets[0]?.id })
+                        const lw = workflowFor(wfs, { workflow: gen.workflow, kind: kind.id, assetId: kind.assets[0]?.id })
                         if (gen.vars != null) {
                             for (const [, d] of lw.wf.entries()) d.reset()
                             applyVarValues(lw.wf, gen.vars, `kind '${kind.id}'`)
@@ -215,7 +215,7 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
                 for (const f of allAssets(kit).filter((x) => x.kind.generate.backend === 'comfy')) {
                     let lw: LoadedWorkflow
                     try {
-                        lw = workflowFor(wfs, { workflow: (f.kind.generate as ComfyGen).workflow, assetId: f.asset.id })
+                        lw = workflowFor(wfs, { workflow: (f.kind.generate as ComfyGen).workflow, kind: f.kind.id, assetId: f.asset.id })
                     } catch {
                         continue // an unresolvable workflow already FAILed on its kind above
                     }

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

@@ -110,7 +110,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
         for (const f of allAssets(kit).filter((x) => x.kind.generate.backend === 'comfy')) {
             try {
                 const gen = f.kind.generate as { workflow?: string }
-                const lw = workflowFor(workflows, { workflow: gen.workflow, assetId: f.asset.id })
+                const lw = workflowFor(workflows, { workflow: gen.workflow, kind: f.kind.id, assetId: f.asset.id })
                 // the KIND's draft, shared by every asset of that kind
                 if (ensureAssetDraft(lw, f.kind.id, await promptOf(f))) console.log(`ok: draft '${f.kind.id}' seeded → .comfy-ts/drafts/${lw.id}/${f.kind.id}.json`)
             } catch (e) {
@@ -127,7 +127,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
         return { workflows, heal: kit.comfy.heal }
     }
     const generateOne = deps.generateOne ?? ((found, prompt, seed, destDir, onProgress, context?: ParentContext) =>
-        generateRoll(found, { prompt, seed, destDir, onProgress, context }, resolveComfy))
+        generateRoll(found, { prompt, seed, destDir, onProgress, context, rollFormat: kit.rollFormat }, resolveComfy))
 
     const queue = new StudioQueue(async (job, seed, onProgress) => {
         const found = findAsset(kit, job.assetId)
@@ -388,7 +388,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
             const rgen = running?.kind.generate
             if (workflows != null && rgen?.backend === 'comfy') {
                 try {
-                    await workflowFor(workflows, { workflow: rgen.workflow, assetId: running!.asset.id }).wf.host.interrupt()
+                    await workflowFor(workflows, { workflow: rgen.workflow, kind: running!.kind.id, assetId: running!.asset.id }).wf.host.interrupt()
                 } catch (e) {
                     queue.pushError(`interrupt: ${(e as Error).message} — current roll will finish, its job is still dropped`)
                 }

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -3,9 +3,11 @@
 // a dangling ref there fails. A link that leaves agent/ but stays in the repo
 // is checked on disk; a pointer out of the repo (a house wiki) is backticked,
 // never a bare → or @. A repo without agent/index.md skips.
+// agent/global-contribution.md is no orphan: the house index links it (SK033).
 import { existsSync, readFileSync } from 'fs'
 import { basename, join } from 'path'
 import { check } from '../check.ts'
+import { CONTRIBUTION_FILE } from '../core/global-contribution.ts'
 import { lintMd } from '../wiki/lint-md.ts'
 
 export const agentWikiLinks = check({
@@ -22,8 +24,10 @@ export const agentWikiLinks = check({
     run: (c) => {
         if (!existsSync(join(c.root, 'agent/index.md'))) return void c.lines.push({ kind: 'skip', text: 'no agent/ wiki in this repo' })
         const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md', boundary: c.root })
-        const linked = lint.pages.filter((p) => !lint.orphans.includes(p))
-        for (const f of lint.orphans) {
+        // the global contribution is the house index's to link (SK033), never agent/'s
+        const orphans = lint.orphans.filter((f) => `agent/${f}` !== CONTRIBUTION_FILE)
+        const linked = lint.pages.filter((p) => !orphans.includes(p))
+        for (const f of orphans) {
             const by = namingPage(c.root, f, linked)
             const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
             c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`)

package/src/checks/SK033-global-contribution.check.ts

@@ -0,0 +1,47 @@
+// SK033 global contribution (meta/agent-folder.md): every house repo carries
+// agent/global-contribution.md, what it offers every agent of every house
+// repo (a house whose index loads @generated/global-context.md), which the house concatenates into the context each session loads
+// (home/global-context.ts). A new one is a comment only, so it contributes
+// nothing until an agent writes to it. Keyed on the file itself: once it is
+// there, the body runs again only when the file moves. Its page is linked from
+// the house index, never from agent/index.md, so SK027 leaves it out.
+import { homedir } from 'os'
+import { check, type FixResult } from '../check.ts'
+import { CONTRIBUTION_FILE, CONTRIBUTION_STUB, CONTEXT_INCLUDE, contributionBody, contributionOver, loadsContext } from '../core/global-contribution.ts'
+import { homeRepo, houseIndex } from '../serve/project-gutter.ts'
+
+/** why a repo gives SK033 nothing to do, or null in a repo whose house
+ *  index loads the generated context */
+export function notHouse(root: string, home: string = homedir()): string | null {
+    const index = houseIndex(homeRepo(root), home)
+    if (index == null) return 'this repo includes no house index, so no house context reads it'
+    if (!loadsContext(index)) return `its house index does not load the generated context (no ${CONTEXT_INCLUDE} line), so nothing reads a contribution`
+    return null
+}
+
+export const globalContribution = check({
+    id: 'SK033',
+    blocking: true,
+    title: 'global contribution',
+    description: 'agent/global-contribution.md exists and fits in the house context',
+    owner: 'meta/agent-folder.md',
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'files', inputs: [CONTRIBUTION_FILE], key: null },
+    fix: 'ci',
+    applies: (env) => notHouse(env.root),
+    run: (c) => {
+        const text = c.read(CONTRIBUTION_FILE)
+        if (text == null) return void c.fail(`${CONTRIBUTION_FILE} is missing: every house repo carries one, empty until it has something to offer`, 'shipkit ci writes the empty one')
+        const body = contributionBody(text)
+        const over = contributionOver(body)
+        if (over != null) return void c.fail(`${CONTRIBUTION_FILE} is ${over}: every session of every house repo loads it, so the house context cuts it`, 'keep what another repo\'s agent can act on, move the rest to agent/')
+        c.ok(body === '' ? `${CONTRIBUTION_FILE} is there, contributing nothing yet` : `${CONTRIBUTION_FILE} contributes ${body.split('\n').length} line(s)`)
+    },
+    repair: (c): FixResult => {
+        if (c.read(CONTRIBUTION_FILE) != null) return { changed: false, summary: `${CONTRIBUTION_FILE} is there: its size is the author's to fix` }
+        c.write(CONTRIBUTION_FILE, CONTRIBUTION_STUB)
+        return { changed: true, summary: `wrote the empty ${CONTRIBUTION_FILE}` }
+    },
+})
+
+export default globalContribution

package/src/cli/cmd_Ci.ts

@@ -20,7 +20,8 @@ export class CiCommand extends Command {
             ['gate without the repair pass (checks can still write)', 'sk ci --no-fix'],
             ['leave repo config files alone', 'sk ci --no-fix-rules'],
             ['stop at the first failure', 'sk ci --bail'],
-            ['one check + its dep closure', 'sk ci --only typecheck'],
+            ['one check + its dep closure, the tree left alone', 'sk ci --only typecheck'],
+            ['one check, repairing the mechanical slots first', 'sk ci --only typecheck --fix'],
             ['every check declaring one group', 'sk ci --only wiki'],
             ['run everything, take nothing from the cache', 'sk ci --fresh'],
             ['include an opt in check', 'sk ci --with up:itch'],
@@ -31,12 +32,12 @@ export class CiCommand extends Command {
 
     bail = Option.Boolean('--bail', false, { description: 'stop at the first failure' })
     json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
-    fix = Option.Boolean('--fix', true, { description: 'repair the mechanical slots before gating. Default on. --no-fix skips the repair pass, the checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
+    fix = Option.Boolean('--fix', { description: 'repair the mechanical slots before gating. Default on for a whole gate and off for a --only run, which leaves the tree alone unless --fix is named. --no-fix skips the repair pass, the checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
     fixRules = Option.Boolean('--fix-rules', true, { description: 'apply the structural autofixes of the built-in checks too. Default on. --no-fix-rules leaves repo config alone' })
     frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining checks: SK005 never touches package.json, and generated paths are never untracked. STATUS.md is still refreshed on disk, but it is gitignored, so a run leaves the tree clean' })
     skip = Option.Array('--skip', [], { description: 'skip a check group (repeatable)' })
     withIds = Option.Array('--with', [], { description: 'include a check the quick gate leaves out (repeatable)' })
-    only = Option.Array('--only', [], { description: 'run only this check + its dep closure (repeatable). A group name runs every check declaring that group' })
+    only = Option.Array('--only', [], { description: 'run only this check + its dep closure (repeatable). A group name runs every check declaring that group. No repair pass unless --fix is named' })
     fresh = Option.Boolean('--fresh', false, { description: 'run every check: no answer comes from the cache, and what this run finds is stored fresh' })
     full = Option.Boolean('--full', false, { description: `run the FULL test tier: every suite the repo declares, the slow ones it skips while you work included. What the release path always runs. Same as SHIPKIT_TEST_FULL=1` })
 
@@ -68,7 +69,7 @@ export class CiCommand extends Command {
         return [
             ...(this.bail ? ['--bail'] : []),
             ...(this.json ? ['--json'] : []),
-            ...(this.fix ? [] : ['--no-fix']),
+            ...(this.fix === true ? ['--fix'] : this.fix === false ? ['--no-fix'] : []),
             ...(this.fixRules ? [] : ['--no-fix-rules']),
             ...(this.frozen ? ['--frozen'] : []),
             ...this.skip.flatMap((v) => ['--skip', v]),

package/src/cli/cmd_GlobalContext.ts

@@ -0,0 +1,47 @@
+// shipkit global-context: the house's generated context, printed, written, or
+// checked against the file on disk. houseContext is the one computation, the
+// daemon's writer calls it too.
+import { existsSync, readFileSync } from 'fs'
+import { Command, Option } from 'clipanion'
+import { houseContext, writeIfChanged } from '../home/global-context.ts'
+
+export class GlobalContextCommand extends Command {
+    static override paths = [['global-context']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'the context every house agent loads: global processes, house repos, each repo\'s global contribution',
+        details: 'one md file beside the house index (generated/global-context.md), which the index includes, gitignored. The daemon rewrites it when a source moves; this command prints it, writes it, or fails when the file on disk is stale',
+        examples: [
+            ['print what the file would hold', 'sk global-context'],
+            ['write it beside the house index', 'sk global-context --write'],
+            ['fail when the file on disk is stale', 'sk global-context --check'],
+        ],
+    })
+
+    write = Option.Boolean('--write', false, { description: 'write it beside the house index, only when it changed' })
+    check = Option.Boolean('--check', false, { description: 'exit 1 when the file on disk differs from what the sources give' })
+
+    async execute(): Promise<number> {
+        const c = await houseContext(process.cwd())
+        if (c == null) {
+            this.context.stderr.write('FAIL: this repo includes no house index in its CLAUDE.md, so there is no house to read\n')
+            return 1
+        }
+        if (this.check) {
+            const now = existsSync(c.path) ? readFileSync(c.path, 'utf8') : null
+            if (now === c.text) {
+                this.context.stdout.write(`ok: ${c.path} is current\n`)
+                return 0
+            }
+            this.context.stdout.write(`FAIL: ${c.path} is ${now == null ? 'missing' : 'stale'}\n      fix: shipkit global-context --write\n`)
+            return 1
+        }
+        if (this.write) {
+            this.context.stdout.write(writeIfChanged(c.path, c.text) ? `ok: wrote ${c.path}\n` : `ok: ${c.path} unchanged\n`)
+            return 0
+        }
+        this.context.stdout.write(c.text)
+        return 0
+    }
+}

package/src/cli/cmd_GlobalProcesses.ts

@@ -161,7 +161,7 @@ export type SwitchAct = 'start' | 'stop' | 'restart'
 
 export type SwitchDeps = {
     /** pm's answer to the switch: null when it took it, else why not */
-    post: (id: string, act: SwitchAct) => Promise<string | null>
+    post: (id: string, act: SwitchAct | 'open' | 'chrome' | 'app') => Promise<string | null>
     /** the process as pm sees it now, null when pm does not answer */
     view: (id: string) => Promise<ResourceView | null>
     sleep: (ms: number) => Promise<void>
@@ -266,3 +266,40 @@ export class GlobalProcessRestartCommand extends SwitchCommand {
         examples: [['restart ComfyUI, so it rescans its models', 'sk gp restart comfyui']],
     })
 }
+
+/** where `sk gp open` sends the url, by flag, as pm's resource api names it */
+export const openAct = (o: { chrome: boolean; app: boolean }): 'open' | 'chrome' | 'app' => (o.app ? 'app' : o.chrome ? 'chrome' : 'open')
+
+export class GlobalProcessOpenCommand extends Command {
+    static override paths = [['global-processes', 'open'], ['gp', 'open']]
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'open a global process\'s url in the browser, Chrome or its app, starting it first when down',
+        details: 'the overview\'s open buttons in the console. pm opens the url at once while the process answers, else starts it and opens once its probe answers. Exit 1 when pm refuses (no such process, no url declared)',
+        examples: [
+            ['the comfy panel in the default browser', 'sk gp open comfy-panel'],
+            ['in Chrome', 'sk gp open comfy-panel --chrome'],
+            ['as its own app in the dock', 'sk gp open comfy-panel --app'],
+        ],
+    })
+
+    id = Option.String({ required: true, name: 'id' })
+    chrome = Option.Boolean('--chrome', false, { description: 'open it in Chrome' })
+    app = Option.Boolean('--app', false, { description: 'open it as its own app, built on first use' })
+
+    async execute(): Promise<number> {
+        if (this.chrome && this.app) {
+            this.context.stderr.write('--chrome and --app name two places: pick one\n')
+            return 2
+        }
+        const act = openAct(this)
+        const refused = await pmSwitchDeps(() => {}).post(this.id, act)
+        if (refused != null) {
+            this.context.stdout.write(`FAIL open ${this.id}: ${refused}\n`)
+            return 1
+        }
+        const where = act === 'app' ? 'as its own app' : act === 'chrome' ? 'in Chrome' : 'in the default browser'
+        this.context.stdout.write(`ok: ${this.id} opens ${where}; a process that was down starts first (shipkit gp shows it)\n`)
+        return 0
+    }
+}

package/src/cli.ts

@@ -11,9 +11,10 @@ import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
 import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
-import { GlobalProcessesCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
+import { GlobalProcessesCommand, GlobalProcessOpenCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
 import { PlannedCommand } from './cli/cmd_Planned.ts'
 import { InsightsCommand } from './cli/cmd_Insights.ts'
+import { GlobalContextCommand } from './cli/cmd_GlobalContext.ts'
 import { OverviewCommand } from './cli/cmd_Overview.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
@@ -98,9 +99,11 @@ export function buildCli(): Cli {
     cli.register(GlobalProcessStartCommand)
     cli.register(GlobalProcessStopCommand)
     cli.register(GlobalProcessRestartCommand)
+    cli.register(GlobalProcessOpenCommand)
     cli.register(CrossRepoActivityCommand)
     cli.register(PlannedCommand)
     cli.register(InsightsCommand)
+    cli.register(GlobalContextCommand)
     cli.register(OverviewCommand)
     cli.register(ChecksCommand)
     cli.register(WhenCommand)

package/src/collections/providers.ts

@@ -413,7 +413,7 @@ export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit |
         contractsCollection(root, c),
         asksCollection(root, c),
         credsCollection(root, c, { verdicts: () => verdictsOf(checks) }),
-        mediaKitCollection(root, kit),
+        mediaKitCollection(root, c.serve?.assets === false ? null : kit),
         socialPostsCollection(root),
         reflectionsCollection(root),
         testsCollection(root, c),

package/src/core/check-runner.ts

@@ -248,6 +248,12 @@ export function testsRan(lastLine: string): number | null {
     return m == null ? null : Number(m[1])
 }
 
+/** the command the suite runner says it ran, read off the same headline
+ *  (`…, as \`bun test --parallel=8\` (added --parallel=8)`, judge-suites ranAs) */
+export function testsCommand(lastLine: string): string | null {
+    return /, (as `[^`]+`(?: \(added [^)]+\))?)/.exec(lastLine)?.[1] ?? null
+}
+
 export type Selection = {
     /** what this run measures */
     selected: RunnableCheck[]
@@ -580,9 +586,12 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         const ran = u.status === 'pass' || u.status === 'warn' ? testsRan(u.lastLine) : null
         const counted = ran != null && head != null && head.kind === 'ok' && (head.text === u.id || head.text.startsWith(`${u.id} (`))
         const id = counted ? `${u.id} ${ran} test${ran === 1 ? '' : 's'}` : u.id
+        // and the command the suite runner ran, which can differ from the script's body
+        const how = counted ? testsCommand(u.lastLine) : null
+        const as = how == null ? '' : ` ${how}`
         const composed = u.synthetic && !u.replayed && head != null
-            ? [{ ...head, text: `${id} ${ranStamp(u.ms)}${u.tail}` }, ...u.lines.slice(1)]
-            : counted ? [{ ...head, text: `${id}${head.text.slice(u.id.length)}` }, ...u.lines.slice(1)] : u.lines
+            ? [{ ...head, text: `${id} ${ranStamp(u.ms)}${u.tail}${as}` }, ...u.lines.slice(1)]
+            : counted ? [{ ...head, text: `${id}${head.text.slice(u.id.length)}${as}` }, ...u.lines.slice(1)] : u.lines
         // every line says where its answer came from: a replay carries its
         // cached stamp already, so one that ran here says so and what it cost
         const shown = u.synthetic || u.replayed || u.attached || u.startedAt === 0 || composed[0] == null
@@ -798,11 +807,11 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         // attached wait runs nothing, so it holds none
         const slot = pool == null ? null : await takeSlot(pool, { repo: o.config.name, check: u.id }, {
             abort: () => interrupted || bailed,
-            onWait: (held) => {
+            onWait: (held, why) => {
                 if (slotWaitSaid) return
                 slotWaitSaid = true
                 const who = held.slice(0, 3).map((h) => `${h.repo}/${h.check} pid ${h.pid}`).join(', ')
-                emit({ kind: 'ok', text: `waiting for a machine slot: ${held.length} of ${pool.size} held${who === '' ? '' : ` (${who}${held.length > 3 ? ', …' : ''})`}` })
+                emit({ kind: 'ok', text: `waiting for a machine slot: ${held.length} held, ${why}${who === '' ? '' : ` (${who}${held.length > 3 ? ', …' : ''})`}` })
             },
         })
         if (pool != null && slot == null) { u.status = 'skip'; u.note = bailed ? 'bailed' : 'interrupted'; u.lines = []; u.unmeasured = true; return }