rvlib-shipkit 1.5.0 → 1.7.0

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/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/read-set.ts

@@ -9,8 +9,8 @@
 // a millisecond later: the next run hashes the disk again, the two differ, and
 // the check runs. Nothing here can turn a mid-run edit into a replay.
 import { createHash } from 'crypto'
-import { lstatSync, readdirSync, readFileSync, statSync } from 'fs'
-import { join } from 'path'
+import { lstatSync, readdirSync, readFileSync, readlinkSync, statSync } from 'fs'
+import { isAbsolute, join } from 'path'
 
 /** `file` or `dir` when the path was there, null when it was not */
 export type PathKind = 'file' | 'dir' | null
@@ -29,6 +29,60 @@ export type ReadSet = {
     /** repo-relative path → whether a symlink stood there. Absent from a set
      *  stored before it existed */
     links?: Record<string, boolean>
+    /** path → its stat signature (`statSig`). For a path in `files` it is a
+     *  fast path: an unchanged signature skips the content hash. For an
+     *  absolute path outside the repo it is the whole record: a traced task
+     *  reads its runtime and its tools there, which are too big to hash on
+     *  every replay and never shared between checkouts anyway */
+    sigs?: Record<string, string>
+    /** local port → `closed`: a traced task met a refusal there, and its
+     *  answer holds only while nothing listens on it */
+    ports?: Record<string, 'closed'>
+    /** symlink → its target, null when no link stands there: what a traced
+     *  task learned from readlink or lstat */
+    targets?: Record<string, string | null>
+}
+
+/** the target a symlink at `abs` points to, null when none stands there */
+export function linkTarget(abs: string): string | null {
+    try {
+        return readlinkSync(abs)
+    } catch {
+        return null
+    }
+}
+
+let listenMemo: { at: number; ports: Set<string> } | null = null
+
+/** the TCP ports something listens on right now, on any local address. One
+ *  netstat per second at most: a replay asks for several at once */
+export function listeningPorts(now = Date.now()): Set<string> {
+    if (listenMemo != null && now - listenMemo.at < 1_000) return listenMemo.ports
+    const ports = new Set<string>()
+    const r = Bun.spawnSync(['/usr/sbin/netstat', '-an', '-p', 'tcp'], { stdout: 'pipe', stderr: 'pipe' })
+    for (const line of r.stdout.toString().split('\n')) {
+        if (!/\bLISTEN\b/.test(line)) continue
+        const local = line.trim().split(/\s+/)[3] ?? ''
+        const port = local.slice(local.lastIndexOf('.') + 1)
+        if (/^\d+$/.test(port)) ports.add(port)
+    }
+    listenMemo = { at: now, ports }
+    return ports
+}
+
+/** a path as recorded: repo-relative, or absolute for one outside the repo */
+const at = (root: string, p: string): string => (isAbsolute(p) ? p : join(root, p))
+
+/** what stat says about a file: size, modification time to the nanosecond
+ *  and inode, `-` when nothing is there. Content can change under an equal
+ *  signature only when a tool restores the mtime on purpose */
+export function statSig(abs: string): string {
+    try {
+        const s = statSync(abs, { bigint: true })
+        return `${s.size}:${s.mtimeNs}:${s.ino}`
+    } catch {
+        return '-'
+    }
 }
 
 /** one entry of a directory, as `c.entries` returns it */
@@ -103,6 +157,9 @@ export class Reads {
     readonly lists = new Map<string, string>()
     readonly dirs = new Map<string, string | null>()
     readonly links = new Map<string, boolean>()
+    readonly sigs = new Map<string, string>()
+    readonly ports = new Map<string, 'closed'>()
+    readonly targets = new Map<string, string | null>()
 
     file(path: string, oid: string | null): void { this.files.set(path, oid) }
     exist(path: string, kind: PathKind): void { this.exists.set(path, kind) }
@@ -116,11 +173,26 @@ export class Reads {
         for (const [k, v] of o.lists) this.lists.set(k, v)
         for (const [k, v] of o.dirs) this.dirs.set(k, v)
         for (const [k, v] of o.links) this.links.set(k, v)
+        for (const [k, v] of o.sigs) this.sigs.set(k, v)
+        for (const [k, v] of o.ports) this.ports.set(k, v)
+        for (const [k, v] of o.targets) this.targets.set(k, v)
+    }
+
+    /** a whole set, as a traced process read it (trace/read-trace.ts) */
+    mergeSet(s: ReadSet): void {
+        for (const [k, v] of Object.entries(s.files)) this.files.set(k, v)
+        for (const [k, v] of Object.entries(s.exists)) this.exists.set(k, v)
+        for (const [k, v] of Object.entries(s.lists)) this.lists.set(k, v)
+        for (const [k, v] of Object.entries(s.dirs ?? {})) this.dirs.set(k, v)
+        for (const [k, v] of Object.entries(s.links ?? {})) this.links.set(k, v)
+        for (const [k, v] of Object.entries(s.sigs ?? {})) this.sigs.set(k, v)
+        for (const [k, v] of Object.entries(s.ports ?? {})) this.ports.set(k, v)
+        for (const [k, v] of Object.entries(s.targets ?? {})) this.targets.set(k, v)
     }
 
     snapshot(): ReadSet {
         const sorted = <V>(m: Map<string, V>): Record<string, V> => Object.fromEntries([...m].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
-        return { files: sorted(this.files), exists: sorted(this.exists), lists: sorted(this.lists), dirs: sorted(this.dirs), links: sorted(this.links) }
+        return { files: sorted(this.files), exists: sorted(this.exists), lists: sorted(this.lists), dirs: sorted(this.dirs), links: sorted(this.links), ...(this.sigs.size > 0 ? { sigs: sorted(this.sigs) } : {}), ...(this.ports.size > 0 ? { ports: sorted(this.ports) } : {}), ...(this.targets.size > 0 ? { targets: sorted(this.targets) } : {}) }
     }
 }
 
@@ -128,25 +200,41 @@ export class Reads {
  *  does. `list` answers a glob the way `c.list` would right now, and returns
  *  null when it cannot answer honestly (no git scan), which counts as drift. */
 export function readSetDrift(root: string, set: ReadSet, list: (glob: string) => readonly string[] | null): string | null {
-    for (const [p, oid] of Object.entries(set.files)) {
-        const now = oidOnDisk(join(root, p))
-        if (now !== oid) return `${p} ${oid == null ? 'appeared' : now == null ? 'is gone' : 'changed'}`
+    const sigs = set.sigs ?? {}
+    for (const [p, sig] of Object.entries(sigs)) {
+        if (p in set.files) continue
+        const now = statSig(at(root, p))
+        if (now !== sig) return `${p} ${sig === '-' ? 'appeared' : now === '-' ? 'is gone' : 'changed'}`
     }
     for (const [p, kind] of Object.entries(set.exists)) {
-        const now = kindOf(join(root, p))
+        const now = kindOf(at(root, p))
         if (now !== kind) return `${p} ${kind == null ? 'appeared' : now == null ? 'is gone' : `is a ${now} now`}`
     }
+    for (const [p, oid] of Object.entries(set.files)) {
+        const abs = at(root, p)
+        if (sigs[p] != null && statSig(abs) === sigs[p]) continue
+        const now = oidOnDisk(abs)
+        if (now !== oid) return `${p} ${oid == null ? 'appeared' : now == null ? 'is gone' : 'changed'}`
+    }
     for (const [g, hash] of Object.entries(set.lists)) {
         const now = list(g)
         if (now == null) return `${g} cannot be listed without a git scan`
         if (listingHash(now) !== hash) return `the files matching ${g} changed`
     }
     for (const [d, hash] of Object.entries(set.dirs ?? {})) {
-        const now = entriesHash(dirEntries(join(root, d)))
+        const now = entriesHash(dirEntries(at(root, d)))
         if (now !== hash) return `${d}/ ${hash == null ? 'appeared' : now == null ? 'is gone' : 'changed its entries'}`
     }
+    for (const [p, t] of Object.entries(set.targets ?? {})) {
+        if (linkTarget(at(root, p)) !== t) return `${p} points elsewhere now`
+    }
+    const closed = Object.keys(set.ports ?? {})
+    if (closed.length > 0) {
+        const open = listeningPorts()
+        for (const port of closed) if (open.has(port)) return `a service listens on local port ${port} now`
+    }
     for (const [p, was] of Object.entries(set.links ?? {})) {
-        if (isLinkAt(join(root, p)) !== was) return `${p} ${was ? 'is no longer a link' : 'became a link'}`
+        if (isLinkAt(at(root, p)) !== was) return `${p} ${was ? 'is no longer a link' : 'became a link'}`
     }
     return null
 }

package/src/core/run-ci.ts

@@ -284,7 +284,12 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // stored under a key that describes the file as it was before the edit.
     // the counts line folds into the verdict; what else it says (a store
     // that failed, answers thrown away) is printed as it is
-    if (ledger != null) for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
+    if (ledger != null) {
+        for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
+        // why every check that did not replay ran, grouped: a re-run nobody
+        // can explain costs a reader more than the line does
+        for (const { line, quiet } of ledger.explain()) (quiet ? detail : sink)(formatLine(line, false))
+    }
     // one write for the whole gate, after everything has finished
     for (const l of runLog.flush()) sink(formatLine(l, false))
     const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownOff.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0

package/src/core/run-fixers.ts

@@ -9,7 +9,7 @@
 // mechanism, two modes, rather than a formatter plus a format:check that
 // drift apart.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
-import { dirname, join } from 'path'
+import { dirname, isAbsolute, join } from 'path'
 import { fileURLToPath } from 'url'
 import { armHooks } from '../hooks/run-hooks.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
@@ -136,7 +136,13 @@ function fixMemo(root: string, tree: Map<string, string>, cmds: string[][]): str
     const h = new Bun.CryptoHasher('sha256')
     h.update(`head=${head.stdout.toString().trim()}\n`)
     for (const [path, hash] of [...tree].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) h.update(`${path}\0${hash}\n`)
-    try { h.update(`toolchain=${toolchainIdentity(root, gateBinary()).id}\n`) } catch { return null }
+    // the runner, the install the fixer scripts run from, and the toolkit code
+    // this pass and its built-in fixers reach, never the toolkit as a whole
+    try {
+        const t = toolchainIdentity(root, gateBinary())
+        const own = [fileURLToPath(import.meta.url), ...cmds.flat().filter((a) => isAbsolute(a) && t.lib.owns(a))]
+        h.update(`toolchain=${t.id}:${t.install}:${t.lib.closureKey(own)}\n`)
+    } catch { return null }
     h.update(`cmds=${JSON.stringify(cmds)}\n`)
     return h.digest('hex')
 }

package/src/core/trace-audit.ts

@@ -0,0 +1,129 @@
+// THE TRACED AUDIT: which gitignored paths a task reads that its key cannot
+// see. A task's key covers the tracked tree and the paths `ignoredInputs`
+// names; a generated type or a local fixture it reads outside those is a
+// stale green waiting for its first edit. Each gate task runs once under the
+// tracer (trace/tracer.ts), and the ignored paths it touched that no key
+// covers become that task's proposals: the keys read them at once
+// (core/audit-report.ts), and `sk trace-audit --fix` writes them into their
+// own managed block of repo.config.ts (core/ignored-block.ts).
+//
+// The tracer never decides a verdict here. A hole in the trace (a child that
+// ran untraced) costs this audit that task, said out loud, and never a green.
+//
+// The tracing costs about one traced gate, so the answer is kept under the
+// git common dir and reused while it is young: rule SK031 in
+// the health pass pays for it, and the fix pass that applies it reads it.
+import { mkdirSync, writeFileSync } from 'fs'
+import { dirname, posix } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import { composeChecks } from '../ledger/gate-checks.ts'
+import { isNamesInput } from '../ledger/git-key.ts'
+import { readTrace } from '../trace/read-trace.ts'
+import { dropTrace, learnBlind, traceUnavailable, tracedCommand } from '../trace/tracer.ts'
+import { spawnWithTimeout } from './spawn-timeout.ts'
+import { gitBin } from './git-bin.ts'
+import { auditReportPath, ignoredFor, pendingByTask, readAuditReport, type AuditReport, type AuditTask, type IgnoredInputs } from './audit-report.ts'
+import { addIgnoredInputs } from './ignored-block.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+
+/** how long an audit answers for the tree: about a day, like SK030 */
+export const AUDIT_KEEP_MS = 20 * 60 * 60 * 1000
+
+export type { AuditReport, AuditTask } from './audit-report.ts'
+export { readAuditReport } from './audit-report.ts'
+
+/** the paths of `paths` git ignores */
+function gitIgnored(root: string, paths: string[]): Set<string> {
+    if (paths.length === 0) return new Set()
+    const p = Bun.spawnSync([gitBin(), 'check-ignore', '--stdin'], { cwd: root, stdin: Buffer.from(`${paths.join('\n')}\n`), stdout: 'pipe', stderr: 'pipe' })
+    return new Set(p.stdout.toString().split('\n').filter((l) => l !== ''))
+}
+
+const under = (p: string, dir: string): boolean => p === dir || p.startsWith(`${dir}/`)
+
+/** is this ignored path already in a key: bytes under a content entry, or a
+ *  listing or probe under a names entry */
+function covered(p: string, listing: boolean, extras: string[]): boolean {
+    return extras.some((e) => (isNamesInput(e) ? listing && under(p, e.slice(0, -3)) : under(p, e)))
+}
+
+/** the fewest entries that cover what was read: each file by itself, or a
+ *  dir by content once more than three files under it were read (its own
+ *  dir, or the outermost dir the task also listed); each listed dir as
+ *  `dir/**`, the outermost one only, unless a content entry covers it */
+export function proposeInputs(content: string[], listed: string[]): string[] {
+    const minimal = (xs: string[]): string[] => {
+        const sorted = [...new Set(xs)].sort()
+        return sorted.filter((x) => !sorted.some((y) => y !== x && under(x, y)))
+    }
+    const tops = minimal(listed)
+    const byDir = new Map<string, string[]>()
+    for (const f of content) {
+        const d = tops.find((t) => under(f, t)) ?? posix.dirname(f)
+        byDir.set(d, [...(byDir.get(d) ?? []), f])
+    }
+    // a listed dir holding three or fewer: each file under its own dir
+    const regroup = [...byDir].flatMap(([dir, files]) => (tops.includes(dir) && files.length <= 3 ? files.map((f) => [posix.dirname(f), f] as const) : files.map((f) => [dir, f] as const)))
+    const again = new Map<string, string[]>()
+    for (const [d, f] of regroup) again.set(d, [...(again.get(d) ?? []), f])
+    const bytes = minimal([...again].flatMap(([dir, files]) => (files.length > 3 && dir !== '.' ? [dir] : files)))
+    return [...bytes, ...tops.filter((d) => !bytes.some((b) => under(d, b))).map((d) => `${d}/**`)].sort()
+}
+
+/** trace every gate task of the repo once and report what its key misses */
+export async function traceAudit(root: string, config: RepoConfig, o: { fresh?: boolean; now?: number; env?: Record<string, string | undefined> } = {}): Promise<AuditReport> {
+    const now = o.now ?? Date.now()
+    const kept = readAuditReport(root)
+    if (o.fresh !== true && kept != null && kept.skipped == null && now - kept.at < AUDIT_KEEP_MS) return kept
+    const env = o.env ?? process.env
+    const off = traceUnavailable(env)
+    if (off != null) return { at: now, skipped: off, tasks: [] }
+    const tasks: AuditTask[] = []
+    for (const g of await composeChecks(root, config)) {
+        const u = g.runnable
+        if (u.body.cmd == null || g.row.runs.off != null || !g.row.runs.onCi || g.row.decl.inputs == null) continue
+        const cwd = u.body.cwd ?? root
+        const t = tracedCommand(u.body.cmd, cwd, env)
+        if ('reason' in t) { tasks.push({ id: u.id, status: 'unaudited', why: t.reason, uncovered: [], propose: [] }); continue }
+        try {
+            await spawnWithTimeout(t.cmd, { timeoutMs: u.timeoutMs, env: { ...process.env, ...u.body.env, ...t.env }, cwd })
+            const r = await readTrace(t.dir, root)
+            if (r.reads == null) {
+                const learned = r.blind.length > 0 ? learnBlind(r.blind) : null
+                tasks.push({ id: u.id, status: 'unaudited', why: [r.why, learned].filter((x) => x != null).join('; '), uncovered: [], propose: [] })
+                continue
+            }
+            // bytes: a file it opened or stat'ed, or found by a probe; a
+            // listing: a dir it read the entries of, or found by a probe
+            // Finder rewrites .DS_Store at will, and no tool's verdict reads it
+            const rel = (p: string): boolean => !p.startsWith('/') && p !== '.' && !p.split('/').includes('node_modules') && !p.startsWith('.git/') && posix.basename(p) !== '.DS_Store'
+            const files = [...new Set([...Object.keys(r.reads.files), ...Object.keys(r.reads.sigs ?? {}), ...Object.entries(r.reads.exists).filter(([, k]) => k === 'file').map(([p]) => p)])].filter(rel)
+            const dirs = [...new Set([...Object.keys(r.reads.dirs ?? {}), ...Object.entries(r.reads.exists).filter(([, k]) => k === 'dir').map(([p]) => p)])].filter(rel)
+            const ignored = gitIgnored(root, [...files, ...dirs])
+            const extras = ignoredFor(config.ignoredInputs, u.id)
+            const missF = files.filter((p) => ignored.has(p) && !covered(p, false, extras))
+            const missD = dirs.filter((p) => ignored.has(p) && !covered(p, true, extras))
+            tasks.push({ id: u.id, status: 'audited', uncovered: [...missF, ...missD].sort(), propose: proposeInputs(missF, missD) })
+        } finally {
+            dropTrace(t.dir)
+        }
+    }
+    const report: AuditReport = { at: now, tasks }
+    try {
+        mkdirSync(dirname(auditReportPath(root)), { recursive: true })
+        writeFileSync(auditReportPath(root), JSON.stringify(report, null, 2))
+    } catch { /* an audit that cannot be kept is measured again next time */ }
+    return report
+}
+
+/** write what the kept audit proposes into the managed block. Nothing is
+ *  traced here, so the fix pass can call it on every run */
+export async function applyAudit(root: string): Promise<{ added: IgnoredInputs; note: string | null }> {
+    const r = readAuditReport(root)
+    if (r == null || r.skipped != null) return { added: {}, note: r?.skipped ?? 'no audit yet: sk trace-audit runs one' }
+    const added = pendingByTask(r, (await loadRepoConfig(root, { fresh: true })).ignoredInputs ?? {})
+    if (Object.keys(added).length === 0) return { added, note: null }
+    await addIgnoredInputs(root, added)
+    return { added, note: null }
+}
+