rvlib-shipkit 0.17.2 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.19.0
+
+- **The attribution tell list covers session trailers and assistant share urls.** `<assistant>-Session:` trailers (claude, chatgpt, copilot, cursor, aider, devin, gemini, codex) and claude.ai/claude.com/chatgpt.com/chat.openai.com urls now trip the shared predicate (commit-msg hook + SK009 history scan). Field case: 162 session links sat in a history both gates called clean.
+- **SK009 scans ref names too**, local and remote-tracking. A checkpoint tag named after an assistant (`FABLE-checkpoint-3`) outs the agent as loudly as a trailer. Bare match only for names with no other meaning (claude, chatgpt, copilot, aider, devin); vendor and codename words (cursor, openai, gemini, fable, sonnet, haiku, opus) name legitimate branches, so they only match in a `-checkpoint`/`-session` shape.
+- **The leak guard reads a machine-global list.** Every run also scans `~/.rv-private/banned-keywords.txt` when it exists: one private list per machine, armed in every repo at once, never copied into a repo (a copy rots and a copy can leak). `hooks install` seeds the repo's own configured keyword file with generic secret-shape starters, never touching an existing one. Both files absent stays a loud skip.
+- **The itch listing answered-check catches empty fields.** A `## field` heading with no body line under it is an unanswered field wearing no `<placeholder>`; the contract names it now. Prose-level open decisions stay a human read.
+
+## 0.18.0
+
+- **The comfy backend runs on comfy-ts.** `.rv-comfy/workflows/` holds `*.cflow.ts` workflow modules (one `host.defineWorkflow` per graph family, plus a `_host.ts` the modules import). Exported json graphs and `.ts` sidekick pairs are gone, and the raw HTTP engine (`comfy-gen.ts`) and pair loader (`workflow-loader.ts`) are deleted with them. Every module must declare `vars.prompt` (`v.prompt`) and `vars.seed` (`v.seed`), shipkit drives both.
+- **One comfy-ts draft per asset.** Shipkit seeds `.comfy-ts/drafts/<workflowId>/<assetId>.json` once and never overwrites it, so `bunx comfy-ts tui` lists every asset as a tweakable row under its workflow. At generation: reset vars → kit `vars` → asset draft → prompt and seed pinned programmatically. The kit + studio overlay stay the prompt source of truth.
+- **BREAKING: `comfy({ workflow, vars })` replaces `bg`.** `vars` is a record of workflow var values applied before the draft, an unknown var name fails loud.
+- **BREAKING: `KitConfig.comfy.host` is removed.** The workflow's `_host.ts` module owns the box connection; `comfy:` keeps `{ workflows, heal }`.
+- **BREAKING: removed exports** `generate`, `submit`, `waitFor`, `applyInputs`, `expectNode`, `ComfyOpts`, `loadWorkflows`, and the pair types `Workflow`, `Sidekick`, `Binding`, `Graph`. New surface: `generateComfyTs`, `loadCflowWorkflows`, `workflowFor` (same resolution semantics, cflow-backed), `applyVarValues`, `ensureAssetDraft`, `readAssetDraft`, `draftPath`, `disconnectAll`, plus types `ComfyTsRuntime`, `LoadedWorkflow`, `GenProgress`, `OnProgress`. `randomSeed` and `batchFolderName` survive unchanged.
+- **The `.comfy-ts/` privacy rule is universal, not one repo's.** The SK004 gitignore policy now carries `.comfy-ts/` and `*.loras.local.txt` into every repo's managed block (shipkit itself writes `.comfy-ts/drafts/` at hub boot, so every consumer needs both ignored before its first commit), and `shipkit init` scaffolds `hooks: { blockedPaths: ['.comfy-ts/'] }`. `validateKit` rejects unknown `comfy:` keys, so a kit still passing the removed `host` gets the migration message instead of silence.
+- **The leak guard scans added lines only.** Deleting a file that carries a banned name used to block the deletion, because the guard read the whole staged diff. Removed and context lines are already in history, so only what the commit ADDS to the object store is scanned. Staged paths and the commit message are scanned as before.
+- **New pre-commit gate `blocked-paths`.** `repo.config.ts hooks: { blockedPaths: ['.comfy-ts/'] }` fails a commit on any staged path under a blocked prefix. Gitignore is advisory and editable; local state that must never enter git (schema dumps naming a private model collection) gets a gate instead. Listed by `shipkit hooks list`.
+- **`assets check` now validates graphs offline.** Modules import with the box off (schema cache or loud base-type fallback), each workflow prints its `.cflow.ts` provenance and vars, kind `workflow`/`vars` resolve dry, drafts are ensured per asset, and a loaded schema cache runs `build()` and fails on graph problems. A missing cache or an unreachable box stays a WARN with the fix command.
+
 ## 0.17.2
 
 - **A release no longer probes the world.** The release gate runs only the checks that can BLOCK. A check declaring `blocking: false` cannot change the outcome, so running it spent time and a third party API call per publish to learn whether a DNS provider was reachable. `release.requireHealthy` still makes those failures fatal, and then they run.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.17.2",
+    "version": "0.19.0",
     "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",
     "type": "module",
@@ -27,6 +27,7 @@
     "dependencies": {
         "@napi-rs/canvas": "^1.0.2",
         "clipanion": "^4.0.0-rc.4",
+        "comfy-ts": "^2.4.2",
         "ink": "^7.1.1",
         "marked": "^18.0.7",
         "mobx": "^6.16.1",

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

@@ -0,0 +1,202 @@
+// the ONE comfy engine: comfy-ts *.cflow.ts workflow modules in the kit's
+// workflows dir, one draft per asset (the TUI's tweakable entry), rolls
+// written from in-memory buffers. Every CLI path that resolves a runtime
+// must disconnectAll() in a finally, or the host websocket keeps bun alive.
+// Workflows are discriminated by duck-typing, never instanceof: a consumer's
+// .cflow.ts may hold a second copy of comfy-ts in its module graph.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs'
+import { basename, join } from 'path'
+import { pathToFileURL } from 'url'
+import { ComfyTS, type AnyVar, type ComfyExecution, type DefinedWorkflow, type MediaImage } from 'comfy-ts'
+
+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 }
+export type ComfyTsRuntime = { workflows: Map<string, LoadedWorkflow>; heal?: string }
+
+// function declaration, not const — TS only narrows on never-calls to
+// directly-declared functions
+function fail(msg: string): never { throw new Error(msg) }
+
+// same duck predicate the comfy-ts TUI and serve bind to: a module valid
+// for shipkit is valid for `bunx comfy-ts tui` and vice versa
+function findDefinedWorkflow(mod: Record<string, unknown>): DefinedWorkflow | null {
+    const isDefined = (x: unknown): x is DefinedWorkflow =>
+        typeof x === 'object' && x != null && 'spec' in x &&
+        typeof (x as DefinedWorkflow).run === 'function' &&
+        typeof (x as DefinedWorkflow).entries === 'function'
+    return [mod.default, ...Object.values(mod)].find(isDefined) ?? null
+}
+
+const varsOf = (wf: DefinedWorkflow): Record<string, AnyVar> => wf.vars as Record<string, AnyVar>
+
+/** true when the image belongs in a roll. Preview-family nodes (PreviewImage,
+ *  PreviewBridge, …) emit raw temp images that comfy-ts downloads like any
+ *  output, in completion order, and MediaImage drops the server-side
+ *  'temp' marker, so the producing node's class_type is the only signal left.
+ *  no node json (SaveImageWebsocket frames) = deliberate output, kept. */
+export const isRollImage = (img: Pick<MediaImage, 'ComfyNode'>): boolean =>
+    !/preview/i.test(img.ComfyNode?.class_type ?? '')
+
+/** 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>> {
+    // shipkit is a driver like the TUI: comfy-ts INFO chatter would pollute
+    // the wire output (and STATUS.md). Errors still print. Respect an
+    // 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 })
+    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()) {
+        const file = join(dir, f)
+        const id = basename(f, '.cflow.ts')
+        const mod = (await import(pathToFileURL(file).href)) as Record<string, unknown>
+        const wf = findDefinedWorkflow(mod)
+        if (wf == null) fail(`${file}: exports no DefinedWorkflow — export default host.defineWorkflow({...})`)
+        // the file name IS the id: it is also the comfy-ts draft folder key,
+        // 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, 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`)
+}
+
+/** Apply a name→value record onto a workflow's vars: strings go through
+ *  parse (validated), everything else through loadJSON (the drafts setter).
+ *  Unknown names throw listing what the workflow has. */
+export function applyVarValues(wf: DefinedWorkflow, vars: Record<string, unknown>, source: string): void {
+    const defs = varsOf(wf)
+    for (const [name, value] of Object.entries(vars)) {
+        const varDef = defs[name]
+        if (varDef == null) fail(`${source}: unknown var '${name}' on workflow '${wf.spec.id ?? '?'}' (has: ${wf.entries().map(([n, d]) => `${n}:${d.kind}`).join(', ')})`)
+        if (typeof value === 'string') {
+            if (!varDef.parse(value)) fail(`${source}: var '${name}' (${varDef.kind}) rejected '${value}'`)
+        } else varDef.loadJSON(value)
+    }
+}
+
+// ── per-asset drafts — comfy-ts disk format, path rule taken from the
+// ComfyTS instance so it cannot drift: .comfy-ts/drafts/<wfId>/<assetId>.json.
+// 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)
+export const draftPath = (lw: LoadedWorkflow, name: string): string => join(draftDir(lw), `${name}.json`)
+
+export function readAssetDraft(lw: LoadedWorkflow, assetId: string): Record<string, unknown> | null {
+    const p = draftPath(lw, assetId)
+    if (!existsSync(p)) return null
+    try {
+        return JSON.parse(readFileSync(p, 'utf8')) as Record<string, unknown>
+    } catch (e) {
+        throw new Error(`draft ${p} is not valid JSON (${(e as Error).message}) — fix or delete it`)
+    }
+}
+
+/** Seed `{ prompt }` ONLY when the draft is absent (hand-tuned state is never
+ *  overwritten). The stored prompt is TUI context; generation overrides it.
+ *  Returns true when just seeded. */
+export function ensureAssetDraft(lw: LoadedWorkflow, assetId: string, prompt: string): boolean {
+    const p = draftPath(lw, assetId)
+    if (existsSync(p)) return false
+    mkdirSync(draftDir(lw), { recursive: true })
+    writeFileSync(p, JSON.stringify({ prompt }, null, 2) + '\n')
+    return true
+}
+
+/**
+ * Run one generation through a cflow workflow: reset vars → kit vars → asset
+ * draft → prompt/seed override, run WITHOUT save (in-memory buffers), write
+ * <destDir>/<name>.<ext> (suffix -2, -3… on extra images). The kit prompt +
+ * studio overlay stay the prompt source of truth; the draft owns every other var.
+ */
+export async function generateComfyTs(
+    rt: ComfyTsRuntime,
+    lw: LoadedWorkflow,
+    args: { prompt: string; seed: number; assetId: string; destDir: string; name: string; vars?: Record<string, unknown>; onProgress?: OnProgress },
+): Promise<string[]> {
+    ensureAssetDraft(lw, args.assetId, args.prompt)
+    const defs = varsOf(lw.wf)
+    // modules are import-cached: a previous asset's values must not leak
+    for (const [, varDef] of lw.wf.entries()) varDef.reset()
+    if (args.vars != null) applyVarValues(lw.wf, args.vars, `asset '${args.assetId}' kit vars`)
+    const draft = readAssetDraft(lw, args.assetId)
+    if (draft != null) {
+        for (const [key, value] of Object.entries(draft)) {
+            const varDef = defs[key]
+            if (varDef == null) { console.log(`WARN draft '${args.assetId}': stale var '${key}' not on workflow '${lw.id}' — ignored`); continue }
+            varDef.loadJSON(value)
+        }
+    }
+    defs.prompt!.parse(args.prompt)
+    // '= N' pins mode AND value, neutralizing any ?/+ mode a draft restored,
+    // so the v<seed> file name stays truthful
+    defs.seed!.parse(`= ${args.seed}`)
+    mkdirSync(args.destDir, { recursive: true })
+    const healHint = rt.heal != null ? ` — is the backend up? (${rt.heal})` : ''
+    let execution: ComfyExecution
+    try {
+        execution = await lw.wf.run({
+            onProgress: args.onProgress == null ? undefined : (p) => args.onProgress!({ value: Math.round(p.percent), max: 100, node: p.nodeName }),
+        })
+    } catch (e) {
+        throw new Error(`workflow '${lw.id}' run failed on ${lw.wf.host.getServerHostHTTP()}: ${(e as Error).message}${healHint}`)
+    }
+    if (execution.status === 'Failure')
+        throw new Error(`workflow '${lw.id}' failed: ${String(execution.data.error ?? 'unknown error')}${healHint}`)
+    const rolls = execution.images.filter(isRollImage)
+    const saved: string[] = []
+    for (const [i, img] of rolls.entries()) {
+        const ext = img.metadata.type ?? 'png'
+        const dest = join(args.destDir, `${args.name}${i > 0 ? `-${i + 1}` : ''}.${ext}`)
+        await Bun.write(dest, img.buffer as Uint8Array<ArrayBuffer>)
+        saved.push(dest)
+    }
+    const errSummary = execution.imageErrors.length === 0 ? '' : ` (${execution.imageErrors.length} image retrieval(s) failed)`
+    const previewSummary = execution.images.length === rolls.length ? '' : ` (${execution.images.length - rolls.length} preview image(s) skipped)`
+    if (saved.length === 0) throw new Error(`workflow '${lw.id}' produced no images — does the graph end in a SaveImage node?${previewSummary}${errSummary}`)
+    // partial output stays visible on disk, the failure stays loud
+    if (execution.imageErrors.length > 0)
+        throw new Error(`workflow '${lw.id}': ${saved.length} image(s) written, ${execution.imageErrors.length} retrieval(s) failed`)
+    return saved
+}
+
+/** Close every loaded workflow's host websocket — CLI paths call this in a
+ *  finally or the process never exits. */
+export function disconnectAll(rt: ComfyTsRuntime): void {
+    const seen = new Set<unknown>()
+    for (const lw of rt.workflows.values()) {
+        if (seen.has(lw.wf.host)) continue
+        seen.add(lw.wf.host)
+        lw.wf.host.disconnect()
+    }
+}
+
+export const randomSeed = (): number => Math.floor(Math.random() * 2_000_000_000) + 1
+
+/** Shell-stamped batch folder name — the one-shot output convention. */
+export function batchFolderName(slug: string): string {
+    const d = new Date()
+    const p = (n: number) => String(n).padStart(2, '0')
+    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}-${slug}`
+}

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

@@ -1,22 +1,20 @@
 // The ONE roll generator — canvas (procedural, in-process via @napi-rs/canvas)
-// or comfy (HTTP through a workflow pair). The studio worker AND the
-// fill/add/gen CLI both call this, so a canvas kit rolls the SAME way 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.
+// or comfy (comfy-ts through a .cflow.ts workflow module). The studio worker
+// AND the fill/add/gen CLI both call this, so a canvas kit rolls the SAME way
+// 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 { join } from 'path'
 import type { FoundAsset } from '../kit-config.ts'
-import { generate, type OnProgress } from './comfy-gen.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'
-import { loadWorkflows, workflowFor, type Workflow } from './workflow-loader.ts'
 
 /** roll canvas master size (square) — favicon/logo/sprites derive from it */
 export const CANVAS_SIZE = 1024
 
-export type ComfyRuntime = { workflows: Map<string, Workflow>; host: string; heal?: string }
-export type ComfyResolver = () => Promise<ComfyRuntime>
+export type ComfyResolver = () => Promise<ComfyTsRuntime>
 
 /** 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. */
@@ -46,24 +44,23 @@ export async function generateRoll(
         return
     }
     const rt = await resolveComfy()
-    const wf = workflowFor(rt.workflows, { workflow: gen.workflow, assetId: found.asset.id })
-    await generate({ host: rt.host, heal: rt.heal }, wf, { prompt: args.prompt, seed: args.seed, destDir: args.destDir, name: `v${args.seed}`, onProgress: args.onProgress })
+    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, destDir: args.destDir, name: `v${args.seed}`, vars: gen.vars, onProgress: args.onProgress })
 }
 
-/** Memoized lazy comfy runtime for a resolved kit — loads the workflow pairs on
+/** Memoized lazy comfy runtime for a resolved kit — loads the cflow modules on
  *  the FIRST comfy roll only. `onMissing` is called (never returns) if a comfy
  *  asset needs it but the kit declares no comfy config. */
 export function comfyResolver(
     root: string,
-    kit: { comfy?: { host: string; workflows: string; heal?: string } },
+    kit: { comfy?: { workflows: string; heal?: string } },
     onMissing: () => never,
 ): ComfyResolver {
-    let cached: Promise<ComfyRuntime> | null = null
+    let cached: Promise<ComfyTsRuntime> | null = null
     return () => {
         if (kit.comfy == null) onMissing()
         return (cached ??= (async () => ({
-            workflows: await loadWorkflows(join(root, kit.comfy!.workflows)),
-            host: kit.comfy!.host,
+            workflows: await loadCflowWorkflows(root, join(root, kit.comfy!.workflows)),
             heal: kit.comfy!.heal,
         }))())
     }

package/src/assets/kit-config.ts

@@ -21,7 +21,9 @@ export type AssetSpec = {
     ship?: unknown
 }
 
-export type ComfyGen = { backend: 'comfy'; workflow?: string; bg?: string }
+/** comfy-ts backend: workflow = a .cflow.ts module id in the kit's workflows
+ *  dir; vars = kind-level var baseline applied before the asset draft */
+export type ComfyGen = { backend: 'comfy'; workflow?: string; vars?: Record<string, unknown> }
 export type CanvasGen = { backend: 'canvas'; draw: (ctx: unknown, asset: AssetSpec) => void | Promise<void> }
 /** Human-provided assets (any media): the studio's upload mints rolls, a
  *  manual asset with no rolls is RED + FAILs `shipkit assets check`. The
@@ -30,7 +32,7 @@ export type ManualGen = { backend: 'manual' }
 /** Gemini image backend (edit-from-parent flows; comfy stays for from-scratch). */
 export type GeminiGen = { backend: 'gemini'; model?: 'flash' | 'pro' }
 export type GeneratorSpec = ComfyGen | CanvasGen | ManualGen | GeminiGen
-export const comfy = (p?: { workflow?: string; bg?: string }): ComfyGen => ({ backend: 'comfy', workflow: p?.workflow, bg: p?.bg })
+export const comfy = (p?: { workflow?: string; vars?: Record<string, unknown> }): ComfyGen => ({ backend: 'comfy', workflow: p?.workflow, vars: p?.vars })
 export const canvas = (draw: CanvasGen['draw']): CanvasGen => ({ backend: 'canvas', draw })
 export const manual = (): ManualGen => ({ backend: 'manual' })
 export const gemini = (p?: { model?: 'flash' | 'pro' }): GeminiGen => ({ backend: 'gemini', model: p?.model })
@@ -114,7 +116,9 @@ export type Kind = {
 export type KitConfig = {
     /** roll workspace root, repo-root-relative; gitignored */
     workspace?: string
-    comfy?: { host: string; workflows: string; heal?: string }
+    /** 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 }
     kinds: Kind[]
 }
 
@@ -123,6 +127,9 @@ 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')
+    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)" : ''}`)
     const kindIds = new Set<string>()
     const assetIds = new Set<string>()
     for (const kind of k.kinds ?? []) {
@@ -130,6 +137,8 @@ export function validateKit(k: KitConfig): string[] {
         if (kindIds.has(kind.id)) errs.push(`duplicate kind id '${kind.id}'`)
         kindIds.add(kind.id)
         if (kind.generate?.backend === 'comfy' && k.comfy == null) errs.push(`kind '${kind.id}' uses the comfy backend but the kit has no comfy config`)
+        if (kind.generate?.backend === 'comfy' && kind.generate.vars != null && (typeof kind.generate.vars !== 'object' || Array.isArray(kind.generate.vars)))
+            errs.push(`kind '${kind.id}': comfy vars must be a plain object`)
         if (kind.media != null && !(kind.media in MEDIA_EXTS))
             errs.push(`kind '${kind.id}': unknown media '${String(kind.media)}' (${Object.keys(MEDIA_EXTS).join('/')})`)
         if (kind.media === 'audio' && kind.generate?.backend !== 'manual')

package/src/assets/roll-workspace.ts

@@ -16,7 +16,8 @@ export type PromptOverlay = { prompt: string | null }
 export const PROMPT_INIT: PromptOverlay = { prompt: null }
 
 // extension list mirrors kit-config MEDIA_EXTS (audio added 0.6.0)
-export const isRollFile = (f: string): boolean => /^v\d+\.(webp|png|mp3|wav|ogg|m4a)$/.test(f)
+// -N suffix: a run that returned several images (batch_size, second save node)
+export const isRollFile = (f: string): boolean => /^v\d+(-\d+)?\.(webp|png|mp3|wav|ogg|m4a)$/.test(f)
 export const isAudioRoll = (f: string): boolean => /\.(mp3|wav|ogg|m4a)$/.test(f)
 
 export const assetDir = (workspace: string, assetId: string): string => join(workspace, 'studio', assetId)

package/src/assets/run-assets.ts

@@ -3,11 +3,10 @@
 // sinks, and return exit codes — 0 ok · 1 fail).
 import { existsSync } from 'fs'
 import { join, relative } from 'path'
-import { randomSeed } from './gen/comfy-gen.ts'
+import { applyVarValues, disconnectAll, ensureAssetDraft, loadCflowWorkflows, randomSeed, workflowFor, type ComfyTsRuntime, type LoadedWorkflow } from './gen/comfyts-gen.ts'
 import { comfyResolver, generateRoll, type ComfyResolver } from './gen/generate-roll.ts'
 import { parentIdsOf, resolveParentContext, topoSort, type ParentContext } from './gen/derived.ts'
-import { loadWorkflows } from './gen/workflow-loader.ts'
-import { allAssets, findAsset, loadKit, type ResolvedKit } from './kit-config.ts'
+import { allAssets, findAsset, loadKit, type ComfyGen, type ResolvedKit } from './kit-config.ts'
 import { NO_PICK_FIX, renderIdentity, type Brand } from './kits/identity-kit.ts'
 import { assetDir, listRolls, readPick, readPromptOverlay } from './roll-workspace.ts'
 
@@ -19,8 +18,17 @@ const die = (msg: string): never => { throw new AssetsFail(msg) }
 
 // Lazy comfy runtime — a canvas-only kit (no comfy: block) never loads
 // workflows or needs the box; only a real comfy roll triggers resolution.
-const comfyFor = (root: string, kit: ResolvedKit): ComfyResolver =>
-    comfyResolver(root, kit, () => die('this kit has no comfy config — add comfy: { host, workflows } to fill comfy assets'))
+// The wrapper keeps a handle on the resolved runtime: a CLI path that ran a
+// roll holds an open host websocket and must disconnect or bun never exits.
+type ComfyHandle = { resolve: ComfyResolver; disconnect: () => void }
+function comfyFor(root: string, kit: ResolvedKit): ComfyHandle {
+    const inner = comfyResolver(root, kit, () => die('this kit has no comfy config — add comfy: { workflows } to fill comfy assets'))
+    let rt: ComfyTsRuntime | null = null
+    return {
+        resolve: async () => (rt = await inner()),
+        disconnect: () => { if (rt != null) disconnectAll(rt) },
+    }
+}
 
 async function rollOnce(root: string, io: AssetsIo, kit: ResolvedKit, resolveComfy: ComfyResolver, assetId: string, count: number): Promise<number> {
     const f = findAsset(kit, assetId)
@@ -62,29 +70,38 @@ async function guarded(io: AssetsIo, body: () => Promise<number>): Promise<numbe
 export const runAssetsTopUp = (root: string, io: AssetsIo, o: { mode: 'fill' | 'add'; n: number; categories: string[] }): Promise<number> =>
     guarded(io, async () => {
         const kit = await loadKit(root)
-        const resolveComfy = comfyFor(root, kit)
-        // canvas AND comfy kinds top up (A30 — canvas kinds draw in-process);
-        // manual kinds have nothing to generate — visible skip, never silence
-        const inScope = allAssets(kit).filter((f) => o.categories.length === 0 || o.categories.includes(f.kind.category))
-        const manualCount = inScope.filter((f) => f.kind.generate.backend === 'manual').length
-        if (manualCount > 0) io.print(`skip: ${manualCount} manual asset(s) — upload in the studio`)
-        // topo (parents-first) replaced sparsest-first: derived children need
-        // their parents' rolls to exist before they can ever generate
-        const targets = topoSort(inScope.filter((f) => f.kind.generate.backend !== 'manual'))
-            .map((f) => ({ f, have: listRolls(assetDir(join(root, kit.workspace), f.asset.id)).length }))
-            .map((t) => ({ ...t, want: o.mode === 'add' ? o.n : Math.max(0, o.n - t.have) }))
-            .filter((t) => t.want > 0)
-        let failed = 0
-        for (const t of targets) failed += await rollOnce(root, io, kit, resolveComfy, t.f.asset.id, t.want)
-        io.print(`${o.mode}: ${targets.length} asset(s) topped up${failed > 0 ? ` — ${failed} roll(s) FAILED` : ''}`)
-        return failed > 0 ? 1 : 0
+        const comfy = comfyFor(root, kit)
+        try {
+            // canvas AND comfy kinds top up (A30 — canvas kinds draw in-process);
+            // manual kinds have nothing to generate — visible skip, never silence
+            const inScope = allAssets(kit).filter((f) => o.categories.length === 0 || o.categories.includes(f.kind.category))
+            const manualCount = inScope.filter((f) => f.kind.generate.backend === 'manual').length
+            if (manualCount > 0) io.print(`skip: ${manualCount} manual asset(s) — upload in the studio`)
+            // topo (parents-first) replaced sparsest-first: derived children need
+            // their parents' rolls to exist before they can ever generate
+            const targets = topoSort(inScope.filter((f) => f.kind.generate.backend !== 'manual'))
+                .map((f) => ({ f, have: listRolls(assetDir(join(root, kit.workspace), f.asset.id)).length }))
+                .map((t) => ({ ...t, want: o.mode === 'add' ? o.n : Math.max(0, o.n - t.have) }))
+                .filter((t) => t.want > 0)
+            let failed = 0
+            for (const t of targets) failed += await rollOnce(root, io, kit, comfy.resolve, t.f.asset.id, t.want)
+            io.print(`${o.mode}: ${targets.length} asset(s) topped up${failed > 0 ? ` — ${failed} roll(s) FAILED` : ''}`)
+            return failed > 0 ? 1 : 0
+        } finally {
+            comfy.disconnect()
+        }
     })
 
 export const runAssetsGen = (root: string, io: AssetsIo, o: { assetId: string; n: number }): Promise<number> =>
     guarded(io, async () => {
         const kit = await loadKit(root)
-        const failed = await rollOnce(root, io, kit, comfyFor(root, kit), o.assetId, o.n)
-        return failed > 0 ? 1 : 0
+        const comfy = comfyFor(root, kit)
+        try {
+            const failed = await rollOnce(root, io, kit, comfy.resolve, o.assetId, o.n)
+            return failed > 0 ? 1 : 0
+        } finally {
+            comfy.disconnect()
+        }
     })
 
 // ── identity: ONE render path + a brand.ts content hash so drift is
@@ -148,23 +165,82 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
         if (kit == null) return 1
         io.print(`ok: kit loads — ${kit.kinds.length} kind(s), ${allAssets(kit).length} asset(s), workspace ${kit.workspace}`)
         if (kit.comfy != null) {
+            // modules import offline (schema cache, or a loud base-type
+            // fallback inside comfy-ts) — no box needed for any FAIL below
+            let wfs: Map<string, LoadedWorkflow> | null = null
             try {
-                const wfs = await loadWorkflows(join(root, kit.comfy.workflows))
-                io.print(`ok: ${wfs.size} workflow pair(s) bound`)
-                // provenance: where each pair lives + that both halves validated
-                // (loadWorkflows throws on any invalid pair, so reaching here = valid).
-                // There is no global workflow store — git owns each repo's pairs; the
-                // house library (wiki/build/comfyui/references) is the copy-from source.
-                for (const wf of wfs.values()) {
-                    const rel = relative(root, wf.jsonPath).replace(/\.json$/, '')
-                    io.print(`ok: workflow '${wf.id}' → ${rel}.{json,ts} (pair valid)`)
-                }
+                wfs = await loadCflowWorkflows(root, join(root, kit.comfy.workflows))
+                io.print(`ok: ${wfs.size} comfy-ts workflow(s) loaded`)
+                // provenance: where each module lives + its declared knobs.
+                // Git owns each repo's modules; the house library
+                // (wiki/build/comfyui/references) is the copy-from source.
+                for (const lw of wfs.values())
+                    io.print(`ok: workflow '${lw.id}' → ${relative(root, lw.file)} (vars: ${lw.wf.entries().map(([n, d]) => `${n}:${d.kind}`).join(', ')})`)
             } catch (e) {
                 io.print(`FAIL: ${(e as Error).message}`)
                 bad++
             }
-            const up = await fetch(`${kit.comfy.host}/system_stats`, { signal: AbortSignal.timeout(3000) }).then((r) => r.ok).catch(() => false)
-            io.print(up ? `ok: comfy backend reachable (${kit.comfy.host})` : `WARN comfy backend unreachable (${kit.comfy.host})${kit.comfy.heal != null ? ` — ${kit.comfy.heal}` : ''}`)
+            if (wfs != null) {
+                // every comfy kind's workflow + vars resolve (dry pass, vars reset after)
+                for (const kind of kit.kinds) {
+                    const gen = kind.generate
+                    if (gen.backend !== 'comfy') continue
+                    try {
+                        const lw = workflowFor(wfs, { workflow: gen.workflow, 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}'`)
+                            for (const [, d] of lw.wf.entries()) d.reset()
+                        }
+                    } catch (e) {
+                        io.print(`FAIL: ${(e as Error).message}`)
+                        bad++
+                    }
+                }
+                // one draft per comfy asset — the TUI's tweakable entry.
+                // ONE aggregate line: per-asset rows would drown the check
+                let draftCount = 0
+                let draftSeeded = 0
+                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 })
+                    } catch {
+                        continue // an unresolvable workflow already FAILed on its kind above
+                    }
+                    const prompt = (await readPromptOverlay(assetDir(join(root, kit.workspace), f.asset.id))).prompt ?? f.asset.prompt
+                    if (ensureAssetDraft(lw, f.asset.id, prompt)) draftSeeded++
+                    draftCount++
+                }
+                if (draftCount > 0) io.print(`ok: drafts ensured for ${draftCount} comfy asset(s) in .comfy-ts/drafts/${draftSeeded > 0 ? ` (${draftSeeded} seeded now)` : ''}`)
+                // offline graph validation when the host has a schema cache;
+                // a missing cache is world state → WARN, never a repo FAIL
+                const hostsWarned = new Set<string>()
+                for (const lw of wfs.values()) {
+                    // schema.size counts real spec entries; .nodes always
+                    // carries the injected UnknownNodeXX even with no cache
+                    if (lw.wf.host.schema.size > 0) {
+                        try {
+                            const built = await lw.wf.build()
+                            if (built.problems.length > 0) { io.print(`FAIL: workflow '${lw.id}' graph problems: ${built.problems.map((p) => p.title).join('; ')}`); bad++ }
+                        } catch (e) {
+                            io.print(`FAIL: workflow '${lw.id}' build failed: ${(e as Error).message}`)
+                            bad++
+                        }
+                    } else if (!hostsWarned.has(lw.wf.host.data.id)) {
+                        hostsWarned.add(lw.wf.host.data.id)
+                        io.print(`WARN no schema cache for host '${lw.wf.host.data.id}' — bunx comfy-ts gen --id ${lw.wf.host.data.id} --host ${lw.wf.host.getServerHostHTTP()}`)
+                    }
+                }
+                try {
+                    for (const url of new Set([...wfs.values()].map((lw) => lw.wf.host.getServerHostHTTP()))) {
+                        const up = await fetch(`${url}/system_stats`, { signal: AbortSignal.timeout(3000) }).then((r) => r.ok).catch(() => false)
+                        io.print(up ? `ok: comfy backend reachable (${url})` : `WARN comfy backend unreachable (${url})${kit.comfy.heal != null ? ` — ${kit.comfy.heal}` : ''}`)
+                    }
+                } finally {
+                    disconnectAll({ workflows: wfs })
+                }
+            }
         }
         // machine-clearable red clears itself: drifted/missing identity
         // outputs re-render HERE; only a missing pick (taste) reaches a human

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

@@ -1,9 +1,9 @@
 // Generation queue: single worker, IN-MEMORY (never run the studio with
 // --watch — a restart drops every queued roll; the fill CLI is the recovery
 // path), errors surfaced in a ring buffer, never fatal. Per-step progress
-// (comfy /ws) lives on state; cancel drops the CURRENT job's remaining
-// rolls — queued jobs are `clear()`'s business.
-import type { GenProgress } from '../gen/comfy-gen.ts'
+// lives on state; cancel drops the CURRENT job's remaining rolls — queued
+// jobs are `clear()`'s business.
+import type { GenProgress } from '../gen/comfyts-gen.ts'
 
 export type Job = { assetId: string; prompt: string; count: number }
 export type QueueState = { generating: boolean; current: string | null; done: number; total: number; progress: GenProgress | null }

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

@@ -8,10 +8,9 @@
 import { existsSync, mkdirSync, unlinkSync } from 'fs'
 import { join, relative } from 'path'
 import { findAsset, allAssets, mediaOf, missingPanelScripts, MEDIA_EXTS, type CustomPanelSpec, type FoundAsset, type GeometryPanelSpec, type ResolvedKit, type ShipFn } from '../kit-config.ts'
-import { interrupt, randomSeed, type OnProgress } from '../gen/comfy-gen.ts'
+import { ensureAssetDraft, loadCflowWorkflows, randomSeed, workflowFor, type ComfyTsRuntime, type LoadedWorkflow, type OnProgress } from '../gen/comfyts-gen.ts'
 import { isStale, parentIdsOf, resolveParentContext, type ParentContext } from '../gen/derived.ts'
-import { generateRoll, type ComfyRuntime } from '../gen/generate-roll.ts'
-import { loadWorkflows, type Workflow } from '../gen/workflow-loader.ts'
+import { generateRoll } from '../gen/generate-roll.ts'
 import { alphaHeight, toPng } from '../image-ops.ts'
 import { readJson, updateJson } from '../json-store.ts'
 import { assetDir, isRollFile, listRolls, metaPath, readPick, readPromptOverlay, updatePick, updatePromptOverlay } from '../roll-workspace.ts'
@@ -31,7 +30,7 @@ export type AssetInfo = {
     backend: 'canvas' | 'comfy' | 'manual' | 'gemini'
     /** canvas rolls have no seed input — every roll is identical */
     deterministic: boolean
-    /** comfy only: resolved workflow id + its .rv-comfy path (note = why unresolved) */
+    /** comfy only: resolved workflow id + its .cflow.ts path (note = why unresolved) */
     workflow: { id: string | null; path: string | null; note?: string } | null
     ship: { mode: 'built-in' | 'hook' | 'record'; path?: string; note?: string }
     /** live write-through target (kind.meta.file), repo-root-relative */
@@ -49,8 +48,8 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
     const { kit, root } = deps
     const workspace = join(root, kit.workspace)
     const dirOf = (id: string): string => assetDir(workspace, id)
-    let workflows: Map<string, Workflow> | null = null
-    if (kit.comfy != null) workflows = await loadWorkflows(join(root, kit.comfy.workflows))
+    let workflows: Map<string, LoadedWorkflow> | null = null
+    if (kit.comfy != null) workflows = await loadCflowWorkflows(root, join(root, kit.comfy.workflows))
 
     // custom panel scripts fail-fast here too (tests/embedders may bypass loadKit)
     const missingPanels = missingPanelScripts(kit, root)
@@ -76,9 +75,9 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
                 if (workflows != null && workflows.size === 1) id = [...workflows.keys()][0]!
                 else if (workflows != null) note = `names no workflow; ${workflows.size} loaded — set workflow on the kind`
             }
-            const wf = id != null && workflows != null ? workflows.get(id) : undefined
-            if (id != null && wf == null && note == null) note = `workflow '${id}' not loaded`
-            const path = wf != null ? relOf(wf.jsonPath) : id != null && kit.comfy != null ? join(kit.comfy.workflows, `${id}.json`) : null
+            const lw = id != null && workflows != null ? workflows.get(id) : undefined
+            if (id != null && lw == null && note == null) note = `workflow '${id}' not loaded`
+            const path = lw != null ? relOf(lw.file) : id != null && kit.comfy != null ? join(kit.comfy.workflows, `${id}.cflow.ts`) : null
             workflow = { id, path, note }
         }
         let ship: AssetInfo['ship']
@@ -94,11 +93,25 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
     const promptOf = async (f: FoundAsset): Promise<string> =>
         (await readPromptOverlay(dirOf(f.asset.id))).prompt ?? f.asset.prompt
 
+    // one draft per comfy asset, seeded at boot so `bunx comfy-ts tui` lists
+    // every asset as a tweakable entry under its workflow
+    if (workflows != null) {
+        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 })
+                if (ensureAssetDraft(lw, f.asset.id, await promptOf(f))) console.log(`ok: draft '${f.asset.id}' seeded → .comfy-ts/drafts/${lw.id}/${f.asset.id}.json`)
+            } catch (e) {
+                console.log(`WARN draft for '${f.asset.id}' not seeded — ${(e as Error).message}`)
+            }
+        }
+    }
+
     // 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<ComfyRuntime> => {
+    const resolveComfy = async (): Promise<ComfyTsRuntime> => {
         if (kit.comfy == null || workflows == null) throw new Error('kit has no comfy config — only canvas kinds can generate')
-        return { workflows, host: kit.comfy.host, heal: kit.comfy.heal }
+        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))
@@ -359,9 +372,14 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
             // only touch the box when the RUNNING job is a comfy kind — the
             // box is shared, an unrelated prompt must never be interrupted
             const running = queue.state.current != null ? findAsset(kit, queue.state.current) : null
-            if (kit.comfy != null && running?.kind.generate.backend === 'comfy')
-                await interrupt({ host: kit.comfy.host, heal: kit.comfy.heal }).catch((e: Error) =>
-                    queue.pushError(`interrupt: ${e.message} — current roll will finish, its job is still dropped`))
+            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()
+                } catch (e) {
+                    queue.pushError(`interrupt: ${(e as Error).message} — current roll will finish, its job is still dropped`)
+                }
+            }
             return json({ ok: true })
         }
         if (pathname === '/api/pick') {

package/src/cli/cmd_Assets.ts

@@ -99,7 +99,7 @@ export class AssetsCheckCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Assets',
-        description: 'kit loads, kinds valid, workflows bound, backend reachable, identity outputs present',
+        description: 'kit loads, kinds valid, cflow workflows load, drafts present, backend reachable, identity outputs present',
         examples: [['health-check the asset pipeline', 'shipkit assets check']],
     })
 

package/src/cli/cmd_Hooks.ts

@@ -20,7 +20,8 @@ export class HooksInstallCommand extends Command {
     bin = Option.String('--bin', 'bunx rvlib-shipkit', { description: 'how the hook body invokes shipkit (in-repo consumers pass `bun <path to cli.ts>`)' })
 
     async execute(): Promise<number> {
-        const r = installHooks(process.cwd(), this.bin)
+        const config = await loadRepoConfig(process.cwd()).catch(() => null)
+        const r = installHooks(process.cwd(), this.bin, config?.hooks?.keywordFile)
         for (const w of r.written) this.context.stdout.write(`ok: wrote ${w}\n`)
         if (r.written.length === 0) this.context.stdout.write('ok: hook bodies already current\n')
         this.context.stdout.write(`${r.note.startsWith('WARN') ? r.note : `ok: ${r.note}`}\n`)

package/src/contracts/manifests/itch.contract.ts

@@ -21,8 +21,24 @@ export default defineContract({
         custom('.rv-itch/listing.md answered', (env) => {
             const p = join(env.root, '.rv-itch/listing.md')
             if (!existsSync(p)) return []
-            const left = [...readFileSync(p, 'utf8').matchAll(/<[a-z][^<>\n]{2,60}>/g)].map((m) => m[0])
-            return left.length === 0 ? [] : [`.rv-itch/listing.md still holds ${left.length} unanswered placeholder(s): ${[...new Set(left)].slice(0, 3).join(' ')} — it is pasted into the store form as-is`]
+            const text = readFileSync(p, 'utf8')
+            const out: string[] = []
+            const left = [...text.matchAll(/<[a-z][^<>\n]{2,60}>/g)].map((m) => m[0])
+            if (left.length > 0) out.push(`.rv-itch/listing.md still holds ${left.length} unanswered placeholder(s): ${[...new Set(left)].slice(0, 3).join(' ')} — it is pasted into the store form as-is`)
+            // a heading with an EMPTY body is an unanswered field wearing no
+            // placeholder (prose-level open decisions stay a human read).
+            // fenced blocks stripped first (a ## inside one is not a field),
+            // and an inline `## Field: answer` heading counts as answered
+            const sections = text.replace(/^```[\s\S]*?^```/gm, '').split(/^## /m).slice(1)
+            const empty = sections
+                .filter((s) => {
+                    const [head = '', ...body] = s.split('\n')
+                    const inline = head.includes(':') && head.slice(head.indexOf(':') + 1).trim() !== ''
+                    return !inline && body.every((l) => l.trim() === '')
+                })
+                .map((s) => s.split('\n')[0]!.trim())
+            if (empty.length > 0) out.push(`.rv-itch/listing.md field(s) with no answer under the heading: ${empty.slice(0, 3).join(', ')}${empty.length > 3 ? ' …' : ''}`)
+            return out
         }),
         // itch DISPLAYS 630x500 and accepts larger — atLeast, never exact-size
         png('.rv-itch/cover.png', 630, 500, { atLeast: true }),

package/src/hooks/commit-message.ts

@@ -7,9 +7,12 @@
 export type OffenseKind = 'dash' | 'attribution'
 export type Offense = { line: number; text: string; kind: OffenseKind; why: string }
 
-/** trailers and footers that name an assistant, plus the robot emoji. */
+/** trailers and footers that name an assistant, assistant session trailers,
+ *  assistant share-domain urls (a session link is a louder tell than any
+ *  trailer), plus the robot emoji. the session/url family lists every
+ *  assistant, not just the one that bit first. */
 export const AI_ATTRIBUTION =
-    /(?:co-authored-by|assisted-by|signed-off-by):[^\n]*\b(?:claude|anthropic|copilot|chatgpt|openai|cursor|aider|devin|gemini)\b|generated with[^\n]*\b(?:claude|copilot|chatgpt|gemini)\b|🤖/i
+    /(?:co-authored-by|assisted-by|signed-off-by):[^\n]*\b(?:claude|anthropic|copilot|chatgpt|openai|cursor|aider|devin|gemini)\b|generated with[^\n]*\b(?:claude|copilot|chatgpt|gemini)\b|\b(?:claude|chatgpt|copilot|cursor|aider|devin|gemini|codex)-session:|\b(?:claude\.(?:ai|com)|chatgpt\.com|chat\.openai\.com)\b|🤖/i
 
 /** everything below git's scissors line is the verbose-mode diff, which git
  *  strips before committing, diff content is not ours to police. */
@@ -33,7 +36,7 @@ export function commitMessageOffenses(message: string): Offense[] {
         if (body.includes(' - '))
             offenses.push({ line: i + 1, text: raw, kind: 'dash', why: 'inline " - " separator: same fix' })
         if (AI_ATTRIBUTION.test(raw))
-            offenses.push({ line: i + 1, text: raw, kind: 'attribution', why: 'AI attribution: no assistant trailer, "Generated with" footer, or robot emoji' })
+            offenses.push({ line: i + 1, text: raw, kind: 'attribution', why: 'AI attribution: no assistant trailer, session trailer, claude.ai/chatgpt.com url, "Generated with" footer, or robot emoji' })
     })
     return offenses
 }

package/src/hooks/run-hooks.ts

@@ -4,9 +4,9 @@
 // while its next commit is already doomed, and nothing can enumerate what
 // the hooks enforce. `shipkit hooks list` answers that without reading shell.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
-import { join } from 'path'
+import { dirname, join } from 'path'
 import { commitMessageOffenses } from './commit-message.ts'
-import { runLeakGuard } from './leak-guard.ts'
+import { globalKeywordFile, runLeakGuard } from './leak-guard.ts'
 import { runRootIdentity } from './root-identity.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -20,6 +20,9 @@ export type HooksConfig = {
     commitMsg?: { id: string; cmd: string[] }[]
     /** keyword file for the leak guard (default '.rv-private/banned-keywords.txt') */
     keywordFile?: string
+    /** staged-path prefixes that may never enter git (local state like
+     *  '.comfy-ts/'). gitignore is advisory and editable; this gate is not. */
+    blockedPaths?: string[]
     /** disable a built-in gate, visible in `hooks list`, never silent */
     disable?: ('leak-guard' | 'commit-message' | 'root-identity')[]
 }
@@ -27,8 +30,9 @@ export type HooksConfig = {
 const HOOK_DIR = 'hooks'
 const HOOKS = ['pre-commit', 'commit-msg'] as const
 
-/** wire `core.hooksPath` and write the two hook bodies. Idempotent. */
-export function installHooks(root: string, binInvocation: string): { written: string[]; note: string } {
+/** wire `core.hooksPath` and write the two hook bodies. Idempotent.
+ *  `keywordFile` = the repo's configured leak-guard file, seeding target. */
+export function installHooks(root: string, binInvocation: string, keywordFile?: string): { written: string[]; note: string } {
     const dir = join(root, HOOK_DIR)
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
     const written: string[] = []
@@ -41,12 +45,41 @@ export function installHooks(root: string, binInvocation: string): { written: st
         if (prev !== body) { writeFileSync(path, body, { mode: 0o755 }); written.push(`${HOOK_DIR}/${h}`) }
     }
     const cfg = Bun.spawnSync(['git', 'config', 'core.hooksPath', HOOK_DIR], { cwd: root })
+    const seeded = seedKeywordFile(root, keywordFile)
+    if (seeded != null) written.push(seeded)
     return {
         written,
         note: cfg.exitCode === 0 ? `core.hooksPath=${HOOK_DIR}` : `WARN could not set core.hooksPath (exit ${cfg.exitCode}) — hooks will not fire`,
     }
 }
 
+// a starter so the leak guard bites from day one instead of skipping forever:
+// generic secret shapes only. private names live in the machine-global
+// ~/.rv-private/banned-keywords.txt, which the guard reads on every run
+// (never copied into a repo: a copy rots and a copy can leak)
+const KEYWORD_STARTER = `# banned-keywords — the leak guard greps every commit (added lines, paths,
+# message) for these rows. one row = one case-insensitive substring, or
+# re:<regex>. add repo-specific names here; machine-wide private names go in
+# ~/.rv-private/banned-keywords.txt, read automatically alongside this file.
+# this file is gitignored on purpose: the list itself is private.
+re:-----BEGIN [A-Z ]*PRIVATE KEY-----
+re:AKIA[0-9A-Z]{16}
+re:sk-[A-Za-z0-9_-]{20,}
+re:ghp_[A-Za-z0-9]{36}
+re:xox[baprs]-[A-Za-z0-9-]{10,}
+`
+
+/** seed the configured keyword file with the generic starter so the guard is
+ *  ARMED, not a skip. an existing file is never touched. */
+function seedKeywordFile(root: string, keywordFile?: string): string | null {
+    const rel = keywordFile ?? '.rv-private/banned-keywords.txt'
+    const dest = join(root, rel)
+    if (existsSync(dest)) return null
+    mkdirSync(dirname(dest), { recursive: true })
+    writeFileSync(dest, KEYWORD_STARTER)
+    return `${rel} (starter shapes)`
+}
+
 export type GateOutcome = { id: string; ok: boolean; lines: string[] }
 
 /** the pre-commit gate: built-in leak guard, then the repo's own commands. */
@@ -67,6 +100,22 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
             ],
         })
     }
+    if ((h.blockedPaths ?? []).length > 0) {
+        const names = Bun.spawnSync(['git', 'diff', '--cached', '--name-only'], { cwd: root })
+        const staged = names.stdout.toString().split('\n').filter(Boolean)
+        const blocked = staged.filter((f) => h.blockedPaths!.some((p) => f.startsWith(p)))
+        out.push(blocked.length === 0
+            ? { id: 'blocked-paths', ok: true, lines: [`ok: blocked-paths clean (${h.blockedPaths!.join(', ')})`] }
+            : {
+                id: 'blocked-paths',
+                ok: false,
+                lines: [
+                    `FAIL: ${blocked.length} staged file(s) under a blocked path — this local state never enters git`,
+                    ...blocked.slice(0, 10).map((f) => `      ${f}`),
+                    `      fix: git reset -- ${[...new Set(blocked.map((f) => h.blockedPaths!.find((p) => f.startsWith(p))))].join(' ')}`,
+                ],
+            })
+    }
     if (!(h.disable ?? []).includes('root-identity')) {
         const r = runRootIdentity(root)
         if (r.status === 'skipped') out.push({ id: 'root-identity', ok: true, lines: [`skip: root-identity (${r.reason})`] })
@@ -137,9 +186,10 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
     const kw = h.keywordFile ?? '.rv-private/banned-keywords.txt'
     // a gate listed as active but unable to fire is worse than no listing:
     // this surface exists so nobody has to guess
-    const leakState = off.has('leak-guard') ? ' (DISABLED by config)' : existsSync(join(root, kw)) ? '' : ` (INACTIVE, ${kw} absent)`
+    const leakState = off.has('leak-guard') ? ' (DISABLED by config)' : existsSync(join(root, kw)) || globalKeywordFile() != null ? '' : ` (INACTIVE, ${kw} absent and no ~/.rv-private list)`
     return [
-        `pre-commit  leak-guard${leakState} — staged content + paths vs ${kw}`,
+        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.rv-private/banned-keywords.txt`,
+        ...((h.blockedPaths ?? []).length > 0 ? [`pre-commit  blocked-paths — nothing under ${h.blockedPaths!.join(', ')} enters git`] : []),
         `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),
         `commit-msg  commit-message${off.has('commit-message') ? ' (DISABLED by config)' : ''} — dash punctuation + AI attribution`,

package/src/init-repo.ts

@@ -21,6 +21,9 @@ export default defineRepo({
     venues: [], // e.g. ['itch', 'steam'] — selects which .rv-<venue>/ contracts are REQUIRED
     social: [], // e.g. ['x', 'discord'] — .rv-social/<channel>/ post folders (+ .rv-discord/)
     tasks: [],  // repo commit-gate tasks; deps double as race guards
+    // .comfy-ts/ holds schema dumps naming a private model collection —
+    // gitignore (SK004) is advisory, this pre-commit gate is not
+    hooks: { blockedPaths: ['.comfy-ts/'] },
     // the mandated reviewer agent type (rule SK008) — uncomment with YOUR
     // standing brief, then \`shipkit check --fix SK008\` writes the agent file:
     // reviewer: { name: 'my-reviewer', brief: '~/path/to/reviewer-brief.md' },

package/src/release/run-release.ts

@@ -15,6 +15,8 @@ import { npmPublishArgv, unitBlockers } from './unit-gate.ts'
 import { formatUnitError, resolveUnits, unitById, type ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
+// adding a FOURTH knob here is the signal that this shape wants rethinking
+// rather than another key (meta/gaps.md, release-path config keys accreting)
 export type ReleaseConfig = {
     /** releases ship from this branch only (default 'main') */
     branch?: string

package/src/rules/SK004-gitignore-policy.ts

@@ -32,6 +32,11 @@ const POLICY_LINES = [
     '.rv-discord/',
     'CLAUDE.local.md',
     'tmp/',
+    // comfy-ts state (schema dumps, drafts) and per-workflow lora tags name a
+    // private model collection; shipkit itself writes .comfy-ts/ at hub boot,
+    // so every consumer repo needs both ignored before its first commit
+    '.comfy-ts/',
+    '*.loras.local.txt',
 ]
 
 export function expectedBlock(config: RepoConfig): string {

package/src/rules/SK009-commit-ai-tells.ts

@@ -53,14 +53,25 @@ export const commitAiTells: Rule = {
         const sample = (hits: { hash: string }[]): string => hits.slice(0, 5).map((h) => h.hash).join(' ') + (hits.length > 5 ? ' …' : '')
         const attributed = commits.filter((c) => hasAiAttribution(c.body))
         const dashed = commits.filter((c) => hasDashPunctuation(c.body))
+        // ref NAMES tell too (a FABLE-checkpoint-3 tag outs the agent as
+        // loudly as a trailer). bare match only for names with no other
+        // meaning; vendor and codename words (cursor, openai, gemini, opus,
+        // fable, …) name legitimate branches and features, they only match in
+        // a checkpoint/session shape
+        const refTell = /\b(?:claude|chatgpt|copilot|aider|devin)\b|(?:^|[-_/])(?:fable|sonnet|haiku|opus|gemini|codex)[-_](?:checkpoint|session|ckpt)/i
+        const refs = await t.exec(['git', 'for-each-ref', '--format=%(refname:short)', 'refs/tags', 'refs/heads', 'refs/remotes'], { cwd: env.root, timeoutMs: 30_000 })
+        if (refs.code !== 0) t.lines.push({ kind: 'skip', text: `ref names unverifiable — git for-each-ref exit ${refs.code}` })
+        const tellRefs = refs.code === 0 ? refs.out.split('\n').map((r) => r.trim()).filter((r) => r !== '' && refTell.test(r)) : []
+        if (tellRefs.length > 0)
+            t.fail(`${tellRefs.length} ref name(s) carry an AI tell in a declared-public repo (${tellRefs.slice(0, 5).join(' ')}${tellRefs.length > 5 ? ' …' : ''}) — rename or delete the refs before the flip; a pushed tag also needs the remote delete`)
         if (attributed.length > 0)
-            t.fail(`${attributed.length}/${commits.length} commits carry AI attribution (a trailer naming an assistant / "Generated with" / 🤖) in a declared-public repo — e.g. ${sample(attributed)}; ${remedy}`)
+            t.fail(`${attributed.length}/${commits.length} commits carry AI attribution (a trailer naming an assistant / a session trailer or claude.ai url / "Generated with" / 🤖) in a declared-public repo — e.g. ${sample(attributed)}; ${remedy}`)
         if (dashed.length > 0)
             t.fail(`${dashed.length}/${commits.length} commit messages carry dash punctuation (em/en dash or inline " - ") in a declared-public repo — e.g. ${sample(dashed)}; ${remedy} (identity/writing-voice.md owns the punctuation rule)`)
         const silenced = attributionSilenced(env.root)
         if (!silenced)
             t.fail(`.claude/settings.json does not silence AI attribution — track it with {"attribution": {"commit": "", "pr": ""}} so no agent's harness ever writes the trailer or the PR footer`)
-        if (attributed.length === 0 && dashed.length === 0 && silenced)
-            t.ok(`${commits.length} commits scanned, attribution silenced in .claude/settings.json — no AI tells`)
+        if (attributed.length === 0 && dashed.length === 0 && tellRefs.length === 0 && silenced)
+            t.ok(`${commits.length} commits + ${refs.code === 0 ? refs.out.split('\n').filter((r) => r.trim() !== '').length : 0} ref names scanned, attribution silenced in .claude/settings.json — no AI tells`)
     },
 }

package/src/shipkit.ts

@@ -60,10 +60,8 @@ export { StudioQueue } from './assets/server/studio-queue.ts'
 export type { Job, QueueState } from './assets/server/studio-queue.ts'
 export { cleanRect, liveRect, defaultLegs } from './assets/panels/geometry-rects.ts'
 export type { GroundRect, LegRect } from './assets/panels/geometry-rects.ts'
-export { generate, submit, waitFor, applyInputs, expectNode, randomSeed, batchFolderName } from './assets/gen/comfy-gen.ts'
-export type { ComfyOpts } from './assets/gen/comfy-gen.ts'
-export { loadWorkflows, workflowFor } from './assets/gen/workflow-loader.ts'
-export type { Workflow, Sidekick, Binding, Graph } from './assets/gen/workflow-loader.ts'
+export { generateComfyTs, loadCflowWorkflows, workflowFor, applyVarValues, ensureAssetDraft, readAssetDraft, draftPath, disconnectAll, randomSeed, batchFolderName } from './assets/gen/comfyts-gen.ts'
+export type { ComfyTsRuntime, LoadedWorkflow, GenProgress, OnProgress } from './assets/gen/comfyts-gen.ts'
 export { toPng, alphaHeight } from './assets/image-ops.ts'
 export { updateJson, readJson } from './assets/json-store.ts'
 export { assetDir, listRolls, isRollFile, isAudioRoll, readPick, updatePick, metaPath, pickPath, readPromptOverlay, updatePromptOverlay, promptPath } from './assets/roll-workspace.ts'

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

@@ -1,157 +0,0 @@
-// ComfyUI HTTP engine — post/wait/fetch plumbing, zero node-id knowledge
-// (node ids live in each workflow's .ts sidekick).
-import { mkdirSync } from 'fs'
-import { extname, join } from 'path'
-import type { Graph, Sidekick, Workflow } from './workflow-loader.ts'
-
-export type ComfyOpts = {
-    /** e.g. 'http://127.0.0.1:8085' */
-    host: string
-    /** shell command that heals the backend (tunnel/boot) — shown in error hints, never executed by the lib */
-    heal?: string
-    waitTimeoutMs?: number
-    pollMs?: number
-}
-
-const WAIT_TIMEOUT_MS = 10 * 60_000 // covers cold model loads
-const POLL_MS = 1500
-
-const healHint = (o: ComfyOpts): string => (o.heal != null ? ` — is the backend up? (${o.heal})` : '')
-
-/** Loud guard for setInputs escape hatches: the node must exist and match. */
-export function expectNode(graph: Graph, id: string, classType: string): Graph[string] {
-    const n = graph[id]
-    if (n == null) throw new Error(`graph has no node '${id}' (expected ${classType})`)
-    if (n.class_type !== classType) throw new Error(`node '${id}' is ${n.class_type}, expected ${classType}`)
-    return n
-}
-
-export function applyInputs(graph: Graph, sk: Sidekick, args: { prompt: string; seed: number; prefix: string }): void {
-    if (sk.setInputs != null) return sk.setInputs(graph, args)
-    for (const [role, value] of [['prompt', args.prompt], ['seed', args.seed], ['prefix', args.prefix]] as const) {
-        const b = sk.bindings[role]
-        graph[b.node]!.inputs[b.input] = value
-    }
-}
-
-export async function submit(o: ComfyOpts, graph: Graph, clientId?: string): Promise<string> {
-    const res = await fetch(`${o.host}/prompt`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ prompt: graph, client_id: clientId ?? crypto.randomUUID() }),
-    })
-    if (!res.ok) throw new Error(`POST /prompt → ${res.status}: ${(await res.text()).slice(0, 300)} — bad graph or server mid-boot${healHint(o)}`)
-    return ((await res.json()) as { prompt_id: string }).prompt_id
-}
-
-// ── live progress over ComfyUI's native /ws ────────────────────────────────
-// ADDITIVE by contract: a dead socket degrades to no-progress, completion
-// truth stays the /history poll. The clientId MUST match the /prompt body
-// or the server sends nothing.
-export type GenProgress = { value: number; max: number; node: string | null }
-export type OnProgress = (p: GenProgress) => void
-
-const wsWarned = new Set<string>() // one WARN per host per process, not per roll
-export function subscribeProgress(o: ComfyOpts, clientId: string, on: OnProgress): { close: () => void } {
-    const url = `${o.host.replace(/^http/, 'ws')}/ws?clientId=${encodeURIComponent(clientId)}`
-    const warnOnce = (detail: string): void => {
-        if (wsWarned.has(o.host)) return
-        wsWarned.add(o.host)
-        console.log(`WARN comfy /ws unavailable — per-step progress disabled${detail}`)
-    }
-    let node: string | null = null
-    let ws: WebSocket | null = null
-    try {
-        ws = new WebSocket(url)
-        ws.onmessage = (ev) => {
-            if (typeof ev.data !== 'string') return // binary preview frames — not consumed
-            let msg: { type?: string; data?: { value?: number; max?: number; node?: string | null } }
-            try { msg = JSON.parse(ev.data) as typeof msg } catch { return }
-            if (msg.type === 'executing') { node = msg.data?.node ?? null; on({ value: 0, max: 0, node }) }
-            else if (msg.type === 'progress') on({ value: msg.data?.value ?? 0, max: msg.data?.max ?? 0, node })
-        }
-        // progress is a bonus — a refused/dropped ws warns once and stays quiet
-        ws.onerror = () => warnOnce('')
-    } catch (e) {
-        warnOnce(` (${(e as Error).message})`)
-    }
-    return { close: () => { try { ws?.close() } catch {} } }
-}
-
-/** Cancel the RUNNING prompt (queued ones are untouched). */
-export async function interrupt(o: ComfyOpts): Promise<void> {
-    const res = await fetch(`${o.host}/interrupt`, { method: 'POST' })
-    if (!res.ok) throw new Error(`POST /interrupt → ${res.status}${healHint(o)}`)
-}
-
-type HistoryOutputs = Record<string, { images?: { filename: string; subfolder?: string; type?: string }[] }>
-
-export async function waitFor(o: ComfyOpts, promptId: string): Promise<HistoryOutputs> {
-    const timeoutMs = o.waitTimeoutMs ?? WAIT_TIMEOUT_MS
-    const deadline = Date.now() + timeoutMs
-    while (Date.now() < deadline) {
-        const res = await fetch(`${o.host}/history/${promptId}`)
-        if (res.ok) {
-            const h = (await res.json()) as Record<string, { outputs: HistoryOutputs; status?: { status_str?: string } }>
-            const entry = h[promptId]
-            if (entry != null) {
-                if (entry.status?.status_str === 'error') throw new Error(`prompt ${promptId} errored on the server — open the ComfyUI UI (${o.host}) for the node error`)
-                return entry.outputs
-            }
-        }
-        await Bun.sleep(o.pollMs ?? POLL_MS)
-    }
-    throw new Error(`prompt ${promptId} still not done after ${Math.round(timeoutMs / 60000)} min — server stuck? check ${o.host} queue${healHint(o)}`)
-}
-
-async function fetchImage(o: ComfyOpts, img: { filename: string; subfolder?: string; type?: string }, dest: string): Promise<void> {
-    const q = new URLSearchParams({ filename: img.filename, subfolder: img.subfolder ?? '', type: img.type ?? 'output' })
-    const res = await fetch(`${o.host}/view?${q}`)
-    if (!res.ok) throw new Error(`GET /view ${img.filename} → ${res.status}`)
-    await Bun.write(dest, await res.arrayBuffer())
-}
-
-/**
- * Run one generation through a workflow pair: fresh graph copy, sidekick
- * bindings applied, submitted, waited, non-preview outputs saved as
- * <destDir>/<name>.<ext> (ONE clean file per asset — no _00001_ counter noise).
- */
-export async function generate(o: ComfyOpts, wf: Workflow, args: { prompt: string; seed: number; destDir: string; name: string; onProgress?: OnProgress }): Promise<string[]> {
-    const graph = structuredClone(wf.graph)
-    applyInputs(graph, wf.sidekick, { prompt: args.prompt, seed: args.seed, prefix: args.name })
-    mkdirSync(args.destDir, { recursive: true })
-    let outputs: HistoryOutputs
-    if (args.onProgress != null) {
-        const clientId = crypto.randomUUID()
-        const sub = subscribeProgress(o, clientId, args.onProgress)
-        try {
-            outputs = await waitFor(o, await submit(o, graph, clientId))
-        } finally {
-            sub.close()
-        }
-    } else {
-        outputs = await waitFor(o, await submit(o, graph))
-    }
-    const saved: string[] = []
-    for (const node of Object.values(outputs)) {
-        for (const img of node.images ?? []) {
-            if (img.type === 'temp') continue // PreviewImage — raw, non-transparent
-            // >1 saved image (batch_size, second Save node): suffix instead of silently overwriting
-            const ext = extname(img.filename) || '.webp'
-            const dest = join(args.destDir, `${args.name}${saved.length > 0 ? `-${saved.length + 1}` : ''}${ext}`)
-            await fetchImage(o, img, dest)
-            saved.push(dest)
-        }
-    }
-    if (saved.length === 0) throw new Error(`workflow '${wf.id}' produced no saved images (only previews?) — does the graph end in a Save node?`)
-    return saved
-}
-
-export const randomSeed = (): number => Math.floor(Math.random() * 2_000_000_000) + 1
-
-/** Shell-stamped batch folder name — the one-shot output convention. */
-export function batchFolderName(slug: string): string {
-    const d = new Date()
-    const p = (n: number) => String(n).padStart(2, '0')
-    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}-${slug}`
-}

package/src/assets/gen/workflow-loader.ts

@@ -1,67 +0,0 @@
-// Workflow pairs: <id>.json exported graph + <id>.ts sidekick (bindings +
-// optional expects/setInputs). Every violation THROWS loud with the fix in
-// the message — CLIs die, checkers turn it into a FAIL line.
-import { existsSync, readdirSync } from 'fs'
-import { basename, join } from 'path'
-
-export type Binding = { node: string; input: string }
-export type Sidekick = {
-    bindings: { prompt: Binding; seed: Binding; prefix: Binding }
-    expects?: Record<string, string>
-    requires?: { customNodes?: string[]; models?: string[] }
-    setInputs?: (graph: Graph, args: { prompt: string; seed: number; prefix: string }) => void
-}
-export type Graph = Record<string, { inputs: Record<string, unknown>; class_type: string }>
-export type Workflow = { id: string; jsonPath: string; graph: Graph; sidekick: Sidekick }
-
-// function declaration, not const — TS only narrows on never-calls to
-// directly-declared functions
-function fail(msg: string): never { throw new Error(msg) }
-
-/** dir = the folder holding the <id>.json + <id>.ts pairs */
-export async function loadWorkflows(dir: string): Promise<Map<string, Workflow>> {
-    const out = new Map<string, Workflow>()
-    if (!existsSync(dir)) fail(`${dir}/ missing — ship at least one <id>.json + <id>.ts workflow pair`)
-    for (const f of readdirSync(dir).filter((x) => x.endsWith('.json')).sort()) {
-        const id = basename(f, '.json')
-        const jsonPath = join(dir, f)
-        const tsPath = join(dir, `${id}.ts`)
-        if (!existsSync(tsPath)) fail(`workflow '${id}': ${f} has no sidekick ${id}.ts — every graph json ships with its adjacent .ts module`)
-        const graph = (await Bun.file(jsonPath).json()) as Graph
-        // ?rvload = a DISTINCT module instance: when a self-executing sidekick
-        // is the running script, importing its bare path would await its own
-        // in-flight top-level evaluation — a deadlock. NOTE the busted
-        // instance STILL sees import.meta.main=true (bun compares paths sans
-        // query), so its CLI tail runs too — the cliRunning guard in the
-        // sidekick runner is what keeps it inert. Never remove that guard.
-        const mod = (await import(`${tsPath}?rvload`)) as Partial<Sidekick>
-        const b = mod.bindings
-        if (b == null || !b.prompt?.node || !b.seed?.node || !b.prefix?.node) {
-            fail(`workflow '${id}': sidekick must export bindings = { prompt|seed|prefix: { node, input } }`)
-        }
-        for (const [role, bind] of Object.entries(b!) as [string, Binding][]) {
-            const n = graph[bind.node]
-            if (n == null) fail(`workflow '${id}': bindings.${role} points at node '${bind.node}' which is not in ${f} — graph re-exported with renumbered nodes? update the sidekick`)
-            if (!(bind.input in n!.inputs)) fail(`workflow '${id}': node '${bind.node}' (${n!.class_type}) has no input '${bind.input}' (has: ${Object.keys(n!.inputs).join(', ')})`)
-        }
-        for (const [node, cls] of Object.entries(mod.expects ?? {})) {
-            const n = graph[node]
-            if (n == null) fail(`workflow '${id}': expects node '${node}' missing from ${f}`)
-            if (n.class_type !== cls) fail(`workflow '${id}': node '${node}' is ${n.class_type}, sidekick expects ${cls} — graph changed under the sidekick, re-check bindings`)
-        }
-        out.set(id, { id, jsonPath, graph, sidekick: mod as Sidekick })
-    }
-    if (out.size === 0) fail(`${dir}/ has no <id>.json graphs`)
-    return out
-}
-
-/** Resolve a workflow: explicit id, else the sole loaded workflow. */
-export function workflowFor(workflows: Map<string, Workflow>, ref: { workflow?: string; assetId?: string }): Workflow {
-    if (ref.workflow != null) {
-        const w = workflows.get(ref.workflow)
-        if (w == null) fail(`asset '${ref.assetId ?? '?'}': unknown workflow '${ref.workflow}' (have: ${[...workflows.keys()].join(', ')})`)
-        return w!
-    }
-    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`)
-}