rvlib-shipkit 1.4.0 → 1.6.0

package/src/core/discover-checks.ts

@@ -110,7 +110,7 @@ export function isLegacyCheckFile(path: string): boolean {
 /** every built-in id, from the file names alone. Sync and import free, so
  *  `defineRepo` can read the namespace at config load. Read once per
  *  process: the toolkit's own files cannot appear mid run, and `defineRepo`
- *  asks for the list once per `when` entry. */
+ *  asks for the list once per `off` entry. */
 let builtinIds: string[] | null = null
 export function builtinCheckIds(): string[] {
     if (builtinIds != null) return builtinIds
@@ -144,6 +144,20 @@ async function load(path: string): Promise<CheckDef | null> {
     }
 }
 
+/** the stand in for a check file that does not load: it fails in every
+ *  context with the load error, so the file cannot drop out of a gate unseen */
+function unloadable(path: string, message: string): CheckDef {
+    return {
+        description: 'the check file loads',
+        blocking: true,
+        runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: false, onClock: false },
+        cache: { by: 'never', why: 'the file does not load' },
+        fix: 'none',
+        applies: 'always',
+        run: (c) => c.fail(`${basename(path)} does not load: ${message.replace(`${path}: `, '')}`, 'shipkit check --fix SK029 ports a retired check file with the values it ran on, and shipkit ci does it in its fix pass'),
+    }
+}
+
 /** every check this repo can run: its own files, plus the toolkit's. Throws
  *  on a registration nobody can act on (a duplicate id, a repo check squatting
  *  the reserved prefix, a built-in with no owner page), so a broken
@@ -170,7 +184,14 @@ export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
     const ids = new Set<string>()
     for (const f of [...builtins, ...own, ...units]) {
         const isBuiltin = builtins.includes(f)
-        const def = await load(f)
+        let def: CheckDef | null
+        try {
+            def = await load(f)
+        } catch (e) {
+            // a file that does not load is ONE red row, never a dead inventory:
+            // every other check still runs, and this one says why in every run
+            def = unloadable(f, (e as Error).message)
+        }
         if (def == null) continue
         const rel = isBuiltin ? null : relative(root, f).replace(/\\/g, '/')
         const fallback = isBuiltin

package/src/core/floor-resolve.ts

@@ -201,9 +201,9 @@ function builtinFloorTask(id: string, root: string, io: FloorReader): { task: Ta
     return `no package.json '${id}' script`
 }
 
-// NOTHING here declares a read set on a repo's behalf, and that is a decision
-// rather than an omission. A floor slot with no `inputs` is measured every run,
-// which costs speed and never correctness (ledger/git-key.ts owns that default).
+// NOTHING here declares a read set on a repo's behalf. The composer keys a
+// floor slot with no `inputs` on the whole work tree plus the repo's
+// `ignoredInputs` (ledger/gate-checks.ts), and the traced audit fills those.
 //
 // The tempting shortcut is `['.']`, on the reasoning that the whole tree cannot
 // under declare. It can. `['.']` is the TRACKED tree: git-scan force-adds only a
@@ -214,10 +214,8 @@ function builtinFloorTask(id: string, root: string, io: FloorReader): { task: Ta
 // gate print `ok: test (replayed)` over a suite that exits 1
 // (tests/floor-cache-safety.test.ts holds the repro).
 //
-// Speed here is bought by a REPO saying what its own tasks read, in
-// `defaults`, which is the only declaration with a real hit rate anyway.
-// `shipkit init` scaffolds the line, `shipkit keys --burn-down` names what is
-// still undeclared, and the gate prints the cost of it once per run.
+// A narrower key is bought by a REPO saying what its own tasks read, in
+// `defaults`.
 
 export function resolveFloor(c: RepoConfig, root: string, io: FloorReader): FloorResolution {
     const pkg = io.text('package.json')

package/src/core/git-root.ts

@@ -8,6 +8,7 @@
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'fs'
 import { dirname, join, resolve } from 'path'
 import { gitBin } from './git-bin.ts'
+import { LAYOUT } from './layout.ts'
 
 export type GitRoot = {
     /** absolute git dir of this work tree (per worktree) */
@@ -130,3 +131,15 @@ export const gitRoot = (dir: string): GitRoot | null => probeGitRoot(dir).root
 export function isLinkedWorktree(root: string): boolean {
     try { return statSync(join(root, '.git')).isFile() } catch { return false }
 }
+
+/** the one dir everything this repo remembers hangs off.
+ *
+ *  `--git-common-dir` rather than `--git-dir`: a linked worktree has its own
+ *  git dir but shares the common one, and that sharing is safe because every
+ *  key component is content or a version string. A tree that is not a git
+ *  repo at all still gets one, under `.shipkit/cache/`, because a scaffold in
+ *  progress must not crash on it. */
+export function shipkitRoot(root: string): string {
+    const dir = gitRoot(root)?.commonDir
+    return dir == null ? join(root, LAYOUT.cache) : join(dir, 'shipkit')
+}

package/src/core/ignored-block.ts

@@ -0,0 +1,94 @@
+// THE IGNORED INPUTS BLOCK in `repo.config.ts`: the one place the traced
+// audit (core/trace-audit.ts) writes the gitignored paths each task reads.
+//
+// Its own markers, apart from the gate block (core/when-block.ts), so a repo
+// that writes `off` or `tests` by hand, with its comments, keeps them exactly
+// as they are. The same paranoia as the gate block:
+//   1. `ignoredInputs` declared OUTSIDE the markers is refused, because a
+//      second declaration is a duplicate key rather than a merge
+//   2. a block that no longer renders what the config loads was hand edited,
+//      and is refused rather than overwritten
+//   3. the result is read back through the loader the cli uses, and the
+//      previous bytes go back when it does not round trip
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { atomicWrite } from './locked-write.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import type { IgnoredInputs } from './audit-report.ts'
+
+export const IGNORED_BEGIN = '// >>> shipkit ignored inputs — managed block, the traced audit writes it, edit outside the markers'
+export const IGNORED_END = '// <<< shipkit ignored inputs'
+
+const isBegin = (l: string): boolean => l.trim().startsWith('// >>> shipkit ignored inputs')
+const isEnd = (l: string): boolean => l.trim().startsWith('// <<< shipkit ignored inputs')
+const q = (s: string): string => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+const key = (s: string): string => (/^[A-Za-z_$][\w$]*$/.test(s) ? s : q(s))
+
+/** the same map, tasks and paths sorted, empty tasks dropped */
+export function normalizeIgnored(ii: IgnoredInputs): IgnoredInputs {
+    const out: IgnoredInputs = {}
+    for (const t of Object.keys(ii).sort()) if ((ii[t] ?? []).length > 0) out[t] = [...new Set(ii[t])].sort()
+    return out
+}
+
+/** the bytes between the markers, markers included */
+export function renderIgnoredBlock(ii: IgnoredInputs, pad: string): string[] {
+    const n = normalizeIgnored(ii)
+    return [
+        `${pad}${IGNORED_BEGIN}`,
+        `${pad}ignoredInputs: {`,
+        ...Object.entries(n).flatMap(([t, ps]) => [`${pad}${pad}${key(t)}: [`, ...ps.map((p) => `${pad}${pad}${pad}${q(p)},`), `${pad}${pad}],`]),
+        `${pad}},`,
+        `${pad}${IGNORED_END}`,
+    ]
+}
+
+function indentOf(lines: string[]): string {
+    for (const l of lines) {
+        const m = /^([ \t]+)\S/.exec(l)
+        if (m != null) return m[1]!
+    }
+    return '    '
+}
+
+export const validIgnoredInput = (p: unknown): p is string => typeof p === 'string' && p !== '' && !p.startsWith('/') && !p.split('/').includes('..')
+
+/** add `add` (task id → paths) to the repo's ignoredInputs, through the
+ *  managed block; the map after the write */
+export async function addIgnoredInputs(root: string, add: IgnoredInputs): Promise<IgnoredInputs> {
+    const file = join(root, 'repo.config.ts')
+    if (!existsSync(file)) throw new Error(`no repo.config.ts in ${root} — run: shipkit init`)
+    for (const p of Object.values(add).flat()) if (!validIgnoredInput(p)) throw new Error(`ignoredInputs '${String(p)}' must be a repo-relative path inside the repo`)
+    const text = readFileSync(file, 'utf8')
+    const lines = text.split('\n')
+    const c = await loadRepoConfig(root, { fresh: true })
+    const have = c.ignoredInputs ?? {}
+    const b = lines.findIndex(isBegin)
+    const e = lines.findIndex(isEnd)
+    if (b === -1 || e === -1 || e < b) {
+        if (Object.keys(have).length > 0) throw new Error('repo.config.ts declares `ignoredInputs` outside the managed block — move it between the markers first, or the audit would write a duplicate key')
+    } else {
+        const pad = /^([ \t]*)/.exec(lines[b]!)?.[1] ?? ''
+        if (lines.slice(b, e + 1).join('\n') !== renderIgnoredBlock(have, pad).join('\n'))
+            throw new Error('the shipkit ignored inputs block in repo.config.ts no longer matches what the config loads, so it was hand edited — reconcile it by hand, then run the audit fix again')
+    }
+    const merged: IgnoredInputs = { ...have }
+    for (const [t, ps] of Object.entries(add)) merged[t] = [...(merged[t] ?? []), ...ps]
+    const next = normalizeIgnored(merged)
+    let out: string[]
+    if (b !== -1 && e > b) out = [...lines.slice(0, b), ...renderIgnoredBlock(next, /^([ \t]*)/.exec(lines[b]!)?.[1] ?? ''), ...lines.slice(e + 1)]
+    else {
+        const anchor = lines.findIndex((l) => /defineRepo\(\s*\{\s*$/.test(l))
+        if (anchor === -1) throw new Error(`repo.config.ts has no \`defineRepo({\` line to write into — paste this block inside the config object by hand:\n${renderIgnoredBlock(next, indentOf(lines)).join('\n')}`)
+        out = [...lines.slice(0, anchor + 1), ...renderIgnoredBlock(next, indentOf(lines)), ...lines.slice(anchor + 1)]
+    }
+    atomicWrite(file, out.join('\n'))
+    try {
+        const after = await loadRepoConfig(root, { fresh: true })
+        if (JSON.stringify(normalizeIgnored(after.ignoredInputs ?? {})) !== JSON.stringify(next)) throw new Error(`the loader read ignoredInputs ${JSON.stringify(after.ignoredInputs ?? {})}`)
+    } catch (err) {
+        atomicWrite(file, text)
+        throw new Error(`repo.config.ts was left as it was: ${(err as Error).message}`)
+    }
+    return next
+}

package/src/core/ignored-inputs.ts

@@ -0,0 +1,47 @@
+// IGNORED INPUTS, the pure half: the kept audit's shape and what a task's key
+// takes from it and from `repo.config.ts ignoredInputs`. No fs here, so a
+// check keyed on its reads can import it (core/audit-report.ts reads the file).
+
+export type AuditTask = {
+    id: string
+    /** `audited` when its trace had no hole, else why it could not be */
+    status: 'audited' | 'unaudited'
+    why?: string
+    /** ignored paths it read that its key does not cover */
+    uncovered: string[]
+    /** the fewest `ignoredInputs` entries that cover them */
+    propose: string[]
+}
+
+export type AuditReport = {
+    at: number
+    /** why nothing was traced on this machine, when nothing was */
+    skipped?: string
+    tasks: AuditTask[]
+}
+
+/** what the kept audit says this task reads outside its key */
+export function auditedExtras(r: AuditReport | null, id: string): string[] {
+    if (r == null || r.skipped != null) return []
+    return r.tasks.find((x) => x.id === id)?.propose ?? []
+}
+
+/** the audit's entries that `have` does not carry yet, per task */
+export function pendingByTask(r: AuditReport | null, have: IgnoredInputs): IgnoredInputs {
+    const out: IgnoredInputs = {}
+    if (r == null || r.skipped != null) return out
+    for (const t of r.tasks) {
+        const missing = (t.propose ?? []).filter((p) => !(have['*'] ?? []).includes(p) && !(have[t.id] ?? []).includes(p))
+        if (missing.length > 0) out[t.id] = missing
+    }
+    return out
+}
+
+/** `ignoredInputs`: task id → gitignored paths it reads, `'*'` for every task */
+export type IgnoredInputs = Record<string, string[]>
+
+/** the entries that join one task's key */
+export const ignoredFor = (ii: IgnoredInputs | undefined, id: string): string[] => [...(ii?.['*'] ?? []), ...(ii?.[id] ?? [])]
+
+/** `task: a, b; other: c`, for a line */
+export const describeByTask = (by: IgnoredInputs): string => Object.entries(by).map(([t, ps]) => `${t}: ${ps.join(', ')}`).join('; ')

package/src/core/jobs.ts

@@ -58,7 +58,14 @@ let seq = 0
 /** what a job the daemon starts carries beside its flags: the run's options
  *  as the runner takes them, one lib copy for the repo config, and the
  *  machine's one background turn for a run nobody waits on */
-export type JobOpts = { opts: Record<string, unknown>; oneLib?: boolean; turn?: boolean }
+export type JobOpts = {
+    opts: Record<string, unknown>
+    oneLib?: boolean
+    turn?: boolean
+    /** the switches the asking terminal had set (home/via-hub.ts): the job
+     *  starts from the daemon's env, which never saw them */
+    env?: Record<string, string>
+}
 
 /** start `shipkit <kind> <args> --job <id>` detached from this process and
  *  its terminal, and return at once */
@@ -69,7 +76,7 @@ export function startJob(root: string, o: { cli: string; kind: JobKind; args: st
     mkdirSync(dir, { recursive: true })
     if (o.job != null) atomicWrite(jobOpts(root, id), JSON.stringify(o.job))
     const out = openSync(join(dir, 'out.log'), 'a')
-    const child = spawn(process.execPath, [o.cli, o.kind, ...o.args, '--job', id], { cwd: root, detached: true, stdio: ['ignore', out, out], env: process.env })
+    const child = spawn(process.execPath, [o.cli, o.kind, ...o.args, '--job', id], { cwd: root, detached: true, stdio: ['ignore', out, out], env: { ...process.env, ...o.job?.env } })
     closeSync(out)
     child.unref()
     const pid = child.pid ?? 0

package/src/core/legacy-shapes.ts

@@ -22,6 +22,7 @@ import { fallbackNames, isCheckFilePath, readLegacyCheck, type LegacyCheck } fro
 import type { ScanCtx } from './check-ctx.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { descriptionProblem, type TaskDef } from '../check.ts'
+import { deriveExplicit, type Derived } from './port-check-file.ts'
 
 /** the narrow module every rewritten file imports `check` from, and the ONE
  *  spelling: the barrel costs 400ms of module load and discovery imports
@@ -130,16 +131,34 @@ export const PLACEHOLDER_MARK = 'TODO: state what must be true'
  *  drops none of them. */
 export function scriptPort(read: LegacyCheck, fallbackBlocking: boolean | undefined): string {
     const blocking = read.blocking ?? fallbackBlocking
+    // what the ported `run` body resolves to: the script's own declarations,
+    // read as the gate read them, on a body keyed on what it reads
+    const d = explicitOf(deriveExplicit({
+        when: read.gate ? null : 'health',
+        build: false,
+        body: 'run',
+        ...(read.inputs != null ? { inputs: `[${read.inputs.map(q).join(', ')}]` } : {}),
+        ...(read.ttl != null ? { ttl: q(read.ttl) } : {}),
+        ...(read.never != null ? { never: q(read.never) } : {}),
+        repair: false,
+        rawAccess: null,
+    }, q))
     const fields = [
         blocking == null ? 'blocking: <true | false, it declares none>' : `blocking: ${blocking}`,
-        ...(read.inputs != null ? [`inputs: [${read.inputs.map(q).join(', ')}]`] : []),
-        ...(read.ttl != null ? [`ttl: ${q(read.ttl)}`] : []),
-        ...(read.never != null ? [`never: ${q(read.never)}`] : []),
-        ...(read.gate ? [] : [`when: 'health'`]),
+        `runs: ${d.runs}`,
+        `cache: ${d.cache}`,
+        `fix: ${q(d.fix)}`,
+        `applies: ${d.applies}`,
     ]
     return `a check script, run as its own process: port it by hand into \`export default check({ description, ${fields.join(', ')}, run: (c) => … })\`, each print a call on c (c.ok, c.warn, c.fail)`
 }
 
+/** a derivation that cannot fail on what a script or a task can declare */
+function explicitOf(d: Derived | { error: string }): Derived {
+    if ('error' in d) throw new Error(`the legacy declaration has no explicit form: ${d.error}`)
+    return d
+}
+
 /** the check file a task's argv runs through bun, `bun <file>` or `bun run
  *  <file>`, relative, `./` prefixed or absolute, resolved against the task's
  *  cwd. `rest` is what the argv passes after the file: a task that passes its
@@ -159,16 +178,24 @@ export function checkFileRunBy(t: Pick<TaskDef, 'cmd' | 'cwd'>, root: string): {
  *  always was: the gate runs it and the health pass leaves it out. */
 export function taskCheckSource(t: TaskDef, root: string): string {
     const own = t.description != null && descriptionProblem(t.description) == null ? t.description.trim() : null
-    const fields = [`id: ${q(t.id)},`, `description: ${q(own ?? descriptionPlaceholder())},`, 'blocking: true,', 'build: true,', `cmd: [${t.cmd!.map(q).join(', ')}],`]
+    // where it ran and how it was kept, as the gate and the planner read a
+    // task: an optIn one ran only by name
+    const d = explicitOf(deriveExplicit({
+        when: t.optIn === true ? 'health' : null,
+        build: true,
+        body: 'cmd',
+        ...(t.inputs != null ? { inputs: `[${t.inputs.map(q).join(', ')}]` } : {}),
+        ...(t.ttl != null ? { ttl: q(t.ttl) } : {}),
+        ...(t.never != null ? { never: q(t.never) } : {}),
+        repair: false,
+        rawAccess: null,
+    }, q))
+    const fields = [`id: ${q(t.id)},`, `description: ${q(own ?? descriptionPlaceholder())},`, 'blocking: true,', 'build: true,', `runs: ${d.runs},`, `cache: ${d.cache},`, `fix: ${q(d.fix)},`, `applies: ${d.applies},`, `cmd: [${t.cmd!.map(q).join(', ')}],`]
     if (t.deps != null && t.deps.length > 0) fields.push(`deps: [${t.deps.map(q).join(', ')}],`)
-    if (t.inputs != null) fields.push(`inputs: [${t.inputs.map(q).join(', ')}],`)
-    if (t.ttl != null) fields.push(`ttl: ${q(t.ttl)},`)
-    if (t.never != null) fields.push(`never: ${q(t.never)},`)
     if (t.group != null) fields.push(`group: ${q(t.group)},`)
     if (t.timeoutMs != null) fields.push(`timeoutMs: ${t.timeoutMs},`)
     if (t.env != null) fields.push(`env: { ${Object.entries(t.env).map(([k, v]) => `${q(k)}: ${q(v)}`).join(', ')} },`)
     if (t.cwd != null) fields.push(`cwd: ${q(t.cwd)},`)
-    if (t.optIn === true) fields.push(`when: 'health',`)
     const w = checkWrapper(root)
     return [...w.head, w.open, ...fields.map((f) => `    ${f}`), w.close, ''].join('\n')
 }
@@ -189,6 +216,8 @@ export function dropConfigKey(text: string, key: string): string | null {
     const start = at[0]!
     const end = statementEnd(lines, start)
     let from = start
-    while (from > 0 && lines[from - 1]!.trim().startsWith('//')) from--
+    // the comment block above the key goes with it, never a managed block
+    // marker (`// >>> shipkit …`): the key may be the first line inside one
+    while (from > 0 && lines[from - 1]!.trim().startsWith('//') && !/^\/\/ (>>>|<<<) shipkit/.test(lines[from - 1]!.trim())) from--
     return [...lines.slice(0, from), ...lines.slice(end + 1)].join('\n')
 }

package/src/core/one-lib.ts

@@ -2,11 +2,14 @@
 // (the home) makes every `rvlib-shipkit` import, from any repo config or check
 // file, land on its OWN copy. A repo's install is never loaded, so there is one
 // module instance per lib file: one mobx, one class identity, one version.
+// The same holds for a package whose objects cross between a repo file and
+// the toolkit (SHARED): a repo's brand draws on a canvas the toolkit made,
+// and a native class only accepts instances of its own copy.
 //
 // the one constraint a reader breaks first: register it BEFORE the first repo
 // config is imported. A module already loaded keeps the copy it resolved.
-import { readFileSync, realpathSync } from 'fs'
-import { extname, join } from 'path'
+import { existsSync, readFileSync, realpathSync } from 'fs'
+import { dirname, extname, join } from 'path'
 import { LIB_ROOT } from './lib-root.ts'
 
 const NAME = 'rvlib-shipkit'
@@ -54,6 +57,46 @@ const real = (p: string): string => {
     }
 }
 
+/** packages a repo file and the toolkit hand objects of to each other */
+export const SHARED: readonly string[] = ['@napi-rs/canvas', 'comfy-ts']
+
+/** a file of ANOTHER copy of a shared package, as the path inside that copy,
+ *  else null. `host` is the root of the copy this process loads */
+export function foreignSharedPath(path: string, name: string, host: string | null): string | null {
+    const at = path.lastIndexOf(`/node_modules/${name}/`)
+    if (at === -1) return null
+    const root = path.slice(0, at + `/node_modules/${name}`.length)
+    if (host == null || root === host || real(root) === real(host)) return null
+    return path.slice(root.length + 1)
+}
+
+const hostRoot = (name: string, from: string): string | null => {
+    try {
+        return dirname(Bun.resolveSync(`${name}/package.json`, from))
+    } catch {
+        return null
+    }
+}
+
+/** where a foreign copy's file lands in the host copy: its entry on the
+ *  host's entry (the two can name different files), any other file on the
+ *  same path, else on the entry */
+const sharedTarget = (path: string, sub: string, name: string, host: string): string => {
+    const entry = Bun.resolveSync(name, host)
+    const foreignDir = path.slice(0, path.length - sub.length - 1)
+    try {
+        if (real(Bun.resolveSync(name, foreignDir)) === real(path)) return entry
+    } catch {
+        /* a foreign copy with no entry of its own: its files map by path */
+    }
+    return existsSync(join(host, sub)) ? join(host, sub) : entry
+}
+
+const reexport = (target: string): { contents: string; loader: 'ts' } => {
+    const t = JSON.stringify(target)
+    return { contents: `export * from ${t}\nimport * as own from ${t}\nexport default (own as { default?: unknown }).default\n`, loader: 'ts' }
+}
+
 const LOADERS: Record<string, 'ts' | 'tsx' | 'js' | 'jsx'> = { '.ts': 'ts', '.tsx': 'tsx', '.js': 'js', '.mjs': 'js', '.jsx': 'jsx' }
 
 let installed = false
@@ -77,9 +120,21 @@ export function useOneLib(root: string = LIB_ROOT): void {
                 const loader = LOADERS[extname(a.path)] ?? 'ts'
                 const sub = foreignLibPath(a.path, root)
                 if (sub == null) return { contents: readFileSync(a.path, 'utf8'), loader }
-                const target = JSON.stringify(join(root, sub))
-                return { contents: `export * from ${target}\nimport * as own from ${target}\nexport default (own as { default?: unknown }).default\n`, loader: 'ts' }
+                return reexport(join(root, sub))
             })
+            for (const name of SHARED) {
+                const host = hostRoot(name, root)
+                if (host == null) continue
+                // the host copy never matches: a CommonJS file read back here
+                // loses the named exports bun infers for it
+                const esc = (s: string): string => s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+                const skip = [...new Set([host, real(host)])].map((h) => `(?!${esc(h)}/)`).join('')
+                build.onLoad({ filter: new RegExp(`^${skip}.*/node_modules/${esc(name)}/`) }, (a) => {
+                    const sub = foreignSharedPath(a.path, name, host)
+                    if (sub == null) return { contents: readFileSync(a.path, 'utf8'), loader: LOADERS[extname(a.path)] ?? 'js' }
+                    return reexport(sharedTarget(a.path, sub, name, host))
+                })
+            }
         },
     })
 }

package/src/core/one-way-in-policy.ts

@@ -1,4 +1,4 @@
-// ONE WAY IN, the harness half (build/shipkit.md). The package.json half
+// ONE WAY IN, the harness half (build/shipkit/one-way-in.md). The package.json half
 // (rule SK001) routes `bun run test` into shipkit, but `bun test` is a bun
 // BUILTIN: no script can intercept it, so a package.json alone leaves the
 // reflex wide open. Claude Code permission rules can close it.
@@ -76,7 +76,7 @@ export const denyRules = (exemptSlots: Iterable<string> = []): string[] => {
 export function refusal(r: RawRunner, segment?: string): string {
     const alt = r.iterate == null ? '' : `, or \`${r.iterate}\` to iterate on ONE suite while you fix a bug`
     const which = segment == null || segment.trim() === '' || segment.trim() === r.head ? '' : ` (refused on \`${segment.trim().slice(0, 80)}\`)`
-    return `\`${r.head}\`${which} bypasses shipkit, so nothing is cached and no other agent's run can be attached to. Use \`${r.use}\`${alt}. Lifting this for good: delete the "Bash(${r.head}*)" line from .claude/settings.json permissions.deny (build/shipkit.md, ONE WAY IN).`
+    return `\`${r.head}\`${which} bypasses shipkit, so nothing is cached and no other agent's run can be attached to. Use \`${r.use}\`${alt}. Lifting this for good: delete the "Bash(${r.head}*)" line from .claude/settings.json permissions.deny (build/shipkit/one-way-in.md).`
 }
 
 /** shell wrappers that do not change what is being run */

package/src/core/outcome-words.ts

@@ -38,8 +38,24 @@ export const checkVerdictWords = (status: 'pass' | 'warn' | 'fail' | 'skip' | nu
             : status === 'skip' ? 'skipped'
                 : status === 'pass' ? (o.replayed ? `passed, ${CACHED}` : 'passed') : 'never ran here'
 
-/** the stamp on the first line of a cached check: `(cached, 5.6s saved)` */
-export const cachedStamp = (savedMs: number): string => `(${CACHED}, ${(savedMs / 1000).toFixed(1)}s saved)`
+/** a span in its one biggest unit: `45s`, `12m`, `3h`, `2d` */
+export function spanShort(ms: number): string {
+    const s = Math.max(0, Math.round(ms / 1000))
+    if (s < 60) return `${s}s`
+    if (s < 3600) return `${Math.floor(s / 60)}m`
+    if (s < 86400) return `${Math.floor(s / 3600)}h`
+    return `${Math.floor(s / 86400)}d`
+}
+
+/** what a run cost: `12ms` under a second, `6.4s` past it */
+export const costShort = (ms: number): string => (ms < 1000 ? `${Math.max(0, Math.round(ms))}ms` : `${(ms / 1000).toFixed(1)}s`)
+
+/** the stamp on the first line of a cached check: how old the answer is and
+ *  what measuring it cost, `(cached, 3h old, 5.6s saved)` */
+export const cachedStamp = (savedMs: number, ageMs: number): string => `(${CACHED}, ${spanShort(ageMs)} old, ${costShort(savedMs)} saved)`
+
+/** the stamp on the first line of a check that ran in this run: `(ran 6.4s)` */
+export const ranStamp = (ms: number): string => `(${RAN} ${costShort(ms)})`
 
 /** the stamp on the first line of an attached check */
 export const attachedStamp = (pid: number, ranMs: number): string => `(${ATTACHED} to pid ${pid}, ${RAN} there in ${(ranMs / 1000).toFixed(1)}s)`

package/src/core/port-check-cli.ts

@@ -0,0 +1,52 @@
+// THE WRITE HALF of the check file port (core/port-check-file.ts), in its own
+// process: whether an undeclared `run` body can be keyed on its reads is a walk
+// of its import closure on disk (core/raw-access.ts), which no check context
+// read can stand for, so SK029's repair reaches it through `c.exec`.
+//
+//   bun port-check-cli.ts <root> <rel> [<rel> …]   → one json line on stdout
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { atomicWrite } from './locked-write.ts'
+import { LIB_ROOT } from './lib-root.ts'
+import { rawAccessInClosure } from './raw-access.ts'
+import { findCheckObject, portCheckSource, retiredKeysIn } from './port-check-file.ts'
+import { plainDefaultFor } from './port-check-files.ts'
+
+export type PortRun = { did: string[]; hand: string[] }
+
+/** why an undeclared `run` body cannot be keyed on its reads, or null */
+function rawAccessOf(root: string, rel: string, src: string): string | null {
+    const obj = findCheckObject(src, { plainDefault: plainDefaultFor(rel) })
+    const keys = new Set(obj?.props.map((p) => p.key) ?? [])
+    if (!keys.has('run') || keys.has('inputs') || keys.has('ttl') || keys.has('never')) return null
+    const r = rawAccessInClosure(root, join(root, rel), { skip: LIB_ROOT })
+    return r == null ? null : `its imports reach the disk around c (${r.file}:${r.line}, ${r.what})`
+}
+
+export function portFiles(root: string, rels: string[]): PortRun {
+    const did: string[] = []
+    const hand: string[] = []
+    for (const rel of rels) {
+        const abs = join(root, rel)
+        let src: string
+        try { src = readFileSync(abs, 'utf8') } catch (e) { hand.push(`${rel}: unreadable (${(e as Error).message})`); continue }
+        const plainDefault = plainDefaultFor(rel)
+        const keys = retiredKeysIn(src, { plainDefault })
+        if (keys.length === 0) continue
+        const r = portCheckSource(src, { plainDefault, rawAccess: rawAccessOf(root, rel, src) })
+        if ('error' in r) { hand.push(`${rel}: ${r.error}`); continue }
+        if (!r.changed) continue
+        atomicWrite(abs, r.source)
+        did.push(`${rel} declares runs, cache, fix and applies (was: ${keys.join(', ')})${r.notes.length > 0 ? `. Note: ${r.notes.join('; ')}` : ''}`)
+    }
+    return { did, hand }
+}
+
+if (import.meta.main) {
+    const [root, ...rels] = process.argv.slice(2)
+    if (root == null) {
+        console.error('usage: bun port-check-cli.ts <root> <rel> [<rel> …]')
+        process.exit(2)
+    }
+    console.log(JSON.stringify(portFiles(root, rels)))
+}