rvlib-shipkit 0.32.0 → 0.34.0

package/src/core/task-runner.ts

@@ -4,7 +4,7 @@
 // - a dep must PASS to unblock; a filtered-out dep counts as satisfied;
 //   a failed/skipped dep skips dependents transitively (note says why).
 //   Deps double as serialization guards (document racy edges at the def).
-// - subprocess tasks: full log streamed to <logDir>/<id>.log, last non-empty
+// - subprocess tasks: full log streamed to <logDir>/run-<pid>-<ts>/<id>.log, last non-empty
 //   line kept for the FAIL summary; SIGTERM at timeoutMs, SIGKILL +2s.
 // - logic tasks run in-process against a CheckCtx: WARN never flips the
 //   exit code, FAIL does. Their lines print under the task line.
@@ -13,8 +13,8 @@
 // - sharp edge, by design: `onlyIds` on a task whose race-guard dep is
 //   optIn/skipped-group drops that dep (filtered = satisfied) — explicit
 //   filters win over guards.
-import { createWriteStream, mkdirSync, rmSync, type WriteStream } from 'fs'
-import { join } from 'path'
+import { createWriteStream, mkdirSync, readdirSync, rmSync, type WriteStream } from 'fs'
+import { basename, join } from 'path'
 import { CheckCtx } from './check-ctx.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
 import { formatLine, type Line } from './wire.ts'
@@ -30,6 +30,19 @@ export type TaskDef = {
     /** excluded unless listed in RunOpts.withIds */
     optIn?: boolean
     timeoutMs?: number
+    /** CONTENT population: the repo-relative paths this task reads. Declaring
+     *  them is what makes the task keyable (ledger/git-key.ts). Undeclared is
+     *  the DEFAULT and means never cached, so forgetting costs speed and never
+     *  correctness. Declaring both this and `ttl` is a registration failure. */
+    inputs?: string[]
+    /** WORLD population: this task reads the network, a keychain, $PATH or the
+     *  clock, so nothing on disk describes its answer and a clean pass is
+     *  remembered for this long (e.g. '24h'). */
+    ttl?: string
+    /** a DECIDED never-cacheable, with the reason. Says somebody looked and
+     *  nothing can describe this task, which takes it off the burn-down list
+     *  that undeclared units land on. */
+    never?: string
 }
 
 export type TaskResult = {
@@ -113,6 +126,43 @@ export function selectTasks(o: RunOpts): { selected: TaskDef[]; errors: string[]
     return { selected, errors }
 }
 
+/** THIS run's log dir. It used to be `logDir` itself, wiped with rmSync at the
+ *  top of every run: a second agent starting a gate deleted the log files the
+ *  first was still streaming into, so the surviving FAIL line pointed at a
+ *  path that no longer existed. Now each run owns `run-<pid>-<started>/` and
+ *  writes nowhere else.
+ *
+ *  Old run dirs are swept on the way in, and only ones nothing can be using:
+ *  the pid must not be running AND the dir must be older than the grace
+ *  window, so a recycled pid cannot cost a live run its logs. */
+function openRunDir(base: string): string {
+    // the pid plus the millisecond separates two PROCESSES; the counter
+    // separates two runTasks calls inside one (the TUI can start a second
+    // before the clock ticks), so no run ever writes into another's dir
+    const dir = join(base, `run-${process.pid}-${Date.now()}-${runSeq++}`)
+    mkdirSync(dir, { recursive: true })
+    const cutoff = Date.now() - RUN_DIR_KEEP_MS
+    try {
+        for (const name of readdirSync(base)) {
+            // run dirs AND the per-run release survey files, which a killed
+            // run leaves behind: both carry the pid and the start time, so one
+            // sweep covers both rather than one path leaking forever
+            const m = /^(?:run|releases)-(\d+)-(\d+)(?:-\d+)?(?:\.json(?:\.lock)?)?$/.exec(name)
+            if (m == null || name === basename(dir)) continue
+            if (Number(m[2]) > cutoff) continue
+            try { process.kill(Number(m[1]), 0); continue } catch (e) { if ((e as { code?: string }).code === 'EPERM') continue }
+            rmSync(join(base, name), { recursive: true, force: true })
+        }
+    } catch {
+        // an unreadable log base is a housekeeping miss, never a gate failure
+    }
+    return dir
+}
+
+/** how long a finished run's logs stay readable, and the pid-reuse guard */
+const RUN_DIR_KEEP_MS = 6 * 60 * 60 * 1000
+let runSeq = 0
+
 export async function runTasks(o: RunOpts): Promise<RunSummary> {
     const print = o.print ?? ((l: string) => console.log(l))
     const color = o.color ?? (process.stdout.isTTY && process.env.NO_COLOR == null)
@@ -122,13 +172,12 @@ export async function runTasks(o: RunOpts): Promise<RunSummary> {
         return { ok: false, results: [], interrupted: false }
     }
     const selectedIds = new Set(sel.selected.map((t) => t.id))
-    rmSync(o.logDir, { recursive: true, force: true })
-    mkdirSync(o.logDir, { recursive: true })
+    const runDir = openRunDir(o.logDir)
 
     const tasks: Live[] = sel.selected.map((t) => ({
         ...t,
         status: 'skipped', exitCode: null, durationMs: 0, startedAt: 0,
-        logPath: t.cmd != null ? join(o.logDir, `${t.id.replace(/[^a-zA-Z0-9-]/g, '_')}.log`) : null,
+        logPath: t.cmd != null ? join(runDir, `${t.id.replace(/[^a-zA-Z0-9-]/g, '_')}.log`) : null,
         lastLine: '', note: '', lines: [],
     }))
     const byId = new Map(tasks.map((t) => [t.id, t]))

package/src/hooks/one-way-in-guard.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env bun
+// the PreToolUse guard for ONE WAY IN (core/one-way-in-policy.ts owns the
+// table and the wording). Its ONE job is to refuse a raw runner with the
+// shipkit command to type instead: `permissions.deny` already blocks these,
+// but a bare deny tells the model only that it was denied, and a refusal with
+// no replacement just sends it looking for another way in.
+//
+// It runs before EVERY Bash call, so it stays a leaf: one tiny import, one
+// small json read, no clipanion, no repo config. Anything it cannot decide it
+// waves through, because a guard that fails closed on its own bugs would wedge
+// a repo with no way to tell why, and `permissions.deny` is still the floor
+// underneath it. Measured at ~10ms per call.
+import { deniedHeads, rawRunnerHit, refusal } from '../core/one-way-in-policy.ts'
+
+const input = await Bun.stdin.text()
+let command = ''
+try {
+    const ev = JSON.parse(input) as { tool_name?: string; tool_input?: { command?: string } }
+    if (ev.tool_name !== 'Bash') process.exit(0)
+    command = ev.tool_input?.command ?? ''
+} catch {
+    process.exit(0)
+}
+// the settings file is the authority on WHICH runners this repo refuses, so
+// deleting one `Bash(...)` line lifts the deny and this refusal together
+const settingsPath = `${process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd()}/.claude/settings.json`
+let denied: Set<string>
+try {
+    denied = deniedHeads(await Bun.file(settingsPath).json())
+} catch {
+    process.exit(0)
+}
+const hit = command === '' || denied.size === 0 ? null : rawRunnerHit(command, denied)
+if (hit == null) process.exit(0)
+// exit 2 is the block: stderr becomes the reason the model reads
+// naming the segment earns its place only when the command had MORE in it:
+// on a bare call it repeats the head back at the reader
+console.error(refusal(hit.runner, hit.segment.trim() === command.trim() ? undefined : hit.segment))
+process.exit(2)

package/src/hooks/run-hooks.ts

@@ -75,6 +75,27 @@ export function armHooks(root: string, config: RepoConfig): ArmHooksResult {
     return { state: 'armed', detail: `wrote ${r.written.join(', ') || 'nothing'}, ${r.note}` }
 }
 
+/** `git config` takes `.git/config.lock` for the write, and a linked worktree
+ *  shares that file with its main checkout: two agents arming at the same
+ *  moment, which is the normal case here, make one of them exit non zero and
+ *  report "hooks will not fire" on a repo whose hooks are perfectly fine. The
+ *  contention window is one file write, so a short backoff clears it. The
+ *  retries are bounded and the last failure is reported with git's own words,
+ *  never swallowed. */
+function setHooksPath(root: string): { code: number; detail: string } {
+    let last = { code: -1, detail: '' }
+    for (let attempt = 0; attempt < 5; attempt++) {
+        if (attempt > 0) Bun.sleepSync(20 * 2 ** (attempt - 1))
+        const p = Bun.spawnSync(['git', 'config', 'core.hooksPath', HOOK_DIR], { cwd: root })
+        if (p.exitCode === 0) return { code: 0, detail: '' }
+        last = { code: p.exitCode, detail: p.stderr.toString().trim().split('\n')[0]?.slice(0, 120) ?? '' }
+        // only lock contention is worth retrying; anything else is a real
+        // refusal and retrying it just makes the failure slower
+        if (!/could not lock|file exists|another git process/i.test(last.detail)) return last
+    }
+    return last
+}
+
 /** 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 } {
@@ -89,12 +110,12 @@ export function installHooks(root: string, binInvocation: string, keywordFile?:
         const prev = existsSync(path) ? readFileSync(path, 'utf8') : ''
         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 cfg = setHooksPath(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`,
+        note: cfg.code === 0 ? `core.hooksPath=${HOOK_DIR}` : `WARN could not set core.hooksPath (exit ${cfg.code}) — hooks will not fire${cfg.detail === '' ? '' : `: ${cfg.detail}`}`,
     }
 }
 

package/src/init-repo.ts

@@ -9,7 +9,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { canonicalBodies } from './core/canonical-scripts.ts'
-import { hasTestFiles } from './rules/SK001-package-json-shape.ts'
+import { hasTestFiles, packageJsonShape } from './rules/SK001-package-json-shape.ts'
+import { oneWayInPolicy } from './rules/SK013-one-way-in-policy.ts'
 import { reportToMotherhome } from './core/motherhome.ts'
 import { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
@@ -67,6 +68,9 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         const cfg = await loadRepoConfig(root)
         const g = await gitignorePolicy.fix!({ root, config: cfg })
         p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+        // the repos that need ONE WAY IN most are the ones that already exist,
+        // so a re-run REPAIRS rather than only seeding a fresh checkout
+        await repairOneWayIn(root, cfg, p)
         const mh = reportToMotherhome(root, cfg)
         if (mh.note != null) p(mh.note)
         if (wired && opts.noPublish !== true) await publishRepo(root, { github: opts.github, gh: opts.gh, print: p })
@@ -99,6 +103,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     // `shipkit check --fix SK004`, one code path
     const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
     p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+    await repairOneWayIn(root, defineRepo({ name }), p)
     // what the gate actually runs, in ONE line: a thin floor must be seen at
     // init time rather than discovered after a bad commit slipped through.
     // The per-task resolution is diagnostics, and a `skip:` naming a script
@@ -128,3 +133,16 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     if (opts.noPublish !== true) p('next: `shipkit ci` is the gate — run it to check your work')
     return 0
 }
+
+/** ONE WAY IN, both halves, through the SAME fixers `shipkit check --fix` runs
+ *  (build/shipkit.md). Nothing here is a second implementation: rule SK001
+ *  routes the package.json scripts, rule SK013 writes the harness policy, and
+ *  init just calls them so a wired repo is born enforced and a re-run repairs
+ *  one that was not. The deny is a RESTRICTION, which is why it lands
+ *  unconditionally where the scaffold's allow list stays opt in. */
+async function repairOneWayIn(root: string, config: Parameters<typeof defineRepo>[0], p: (line: string) => void): Promise<void> {
+    const pkg = await packageJsonShape.fix!({ root, config })
+    if (pkg.changed) p(`ok: package.json — ${pkg.summary}`)
+    const policy = await oneWayInPolicy.fix!({ root, config })
+    p(policy.changed ? `ok: ${policy.summary}` : `ok: .claude/settings.json already closes every raw runner`)
+}

package/src/ledger/gate-units.ts

@@ -0,0 +1,58 @@
+// EVERY UNIT THE GATE RUNS, with what it declared about its own cacheability.
+//
+// Three registries feed one list, because a key layer that can only see tasks
+// would leave the 25 checks and the 32 rules uncached forever, and those are
+// most of the wall time. The declaration lives with the unit (a `TaskDef`
+// field, a `Rule` field, an `export const inputs` in a check file), never in a
+// table over here: a table beside the registry is a second source of truth
+// that drifts the first time somebody adds a check.
+import { relative } from 'path'
+import { allTasks, type RepoConfig } from '../repo-config.ts'
+import { discoverChecks } from '../core/discover-checks.ts'
+import { RULES } from '../rules/rule-registry.ts'
+import type { UnitDecl } from './git-key.ts'
+
+/** every task, rule and discovered check, in the order the gate meets them. */
+export function gateUnits(root: string, c: RepoConfig): UnitDecl[] {
+    const out: UnitDecl[] = []
+    for (const t of allTasks(c, root).tasks) {
+        out.push({
+            id: t.id,
+            kind: 'task',
+            inputs: t.inputs,
+            ttl: t.ttl,
+            never: t.never,
+            argv: t.cmd,
+            // the env a task SETS is part of what it runs, not something read
+            // off the ambient environment, so it rides as an identity string
+            extra: t.env == null ? undefined : JSON.stringify(Object.entries(t.env).sort()),
+        })
+    }
+    for (const r of [...RULES, ...(c.rules ?? [])]) {
+        out.push({
+            id: r.id,
+            kind: 'rule',
+            inputs: r.inputs,
+            code: r.code,
+            ttl: r.ttl,
+            never: r.never,
+            extra: r.cacheKey?.({ root, config: c }),
+        })
+    }
+    for (const d of discoverChecks(root)) {
+        const rel = relative(root, d.path).replace(/\\/g, '/')
+        out.push({
+            id: d.name,
+            kind: 'check',
+            inputs: d.inputs ?? undefined,
+            ttl: d.ttl ?? undefined,
+            never: d.never ?? undefined,
+            // a check IS a file, so its own code needs no declaration: the
+            // module graph walks from here through every helper it imports,
+            // which is what makes fixing a shared helper move the check's key
+            code: [rel],
+            argv: ['bun', rel],
+        })
+    }
+    return out
+}

package/src/ledger/git-key.ts

@@ -0,0 +1,330 @@
+// THE KEY. What question did this unit answer, and is that still the same
+// question? Nothing in this file caches anything: it produces the identity a
+// later ledger will store results under, and it refuses to produce one
+// whenever the answer would be a guess.
+//
+// THREE POPULATIONS, declared at registration, never inferred:
+//
+//   CONTENT  declares `inputs` — the paths it reads. Keyed on their git object
+//            ids, plus the unit's own code (module graph), plus the toolchain
+//            (which content-hashes the gate binary, so editing shipkit moves
+//            every key in every repo), plus argv and declared env. No TTL: a
+//            content key is either the same question or a different one.
+//   WORLD    declares `ttl` — it reads the network, the keychain, $PATH, a git
+//            remote or the clock. Nothing on disk describes its answer, so it
+//            keeps the existing clean-pass TTL and its `cacheKey`, unchanged.
+//   NEITHER  declares nothing. Never cached. This is the DEFAULT, and it is
+//            the whole safety story: forgetting to declare costs speed, never
+//            correctness, so the burn-down list below is a to-do rather than a
+//            hazard. Declaring BOTH is a registration failure, loud, because
+//            the two answers contradict each other.
+//
+// CROSS WORKTREE. Every component here is content addressed or a version
+// string; not one of them is an absolute path. Two worktrees of one repo
+// holding the same content and the same install therefore produce the same
+// key, and a worktree whose node_modules differs produces a different one.
+// Measured on this disk: main and two worktrees, main's install id
+// e55a7fd4ae252e5a against fd0e2908d222fe2e shared by both worktrees, which
+// differ from main by two top-level packages. That is what makes a shared
+// ledger safe rather than a stale green in a checkout nobody looked at.
+import { createHash } from 'crypto'
+import { loadConfig, type RvtConfig } from '../ts/config.ts'
+import { importClosure } from '../ts/source-graph.ts'
+import { GitScanError, hashFiles, normalizeInput, scanPaths, type ScanResult } from './git-scan.ts'
+import { toolchainIdentity } from './toolchain-identity.ts'
+
+/** the key format. Bumped when a component is added or its rendering changes,
+ *  so an old ledger can never answer a new question. */
+export const KEY_VERSION = 1
+
+export type Population = 'content' | 'world' | 'none'
+
+/** what one gate unit (a task, a rule, a discovered check) declares about its
+ *  own cacheability. `gate-units.ts` builds these from the live registries. */
+export type UnitDecl = {
+    /** the id an operator types: a task id, a rule id, a check name */
+    id: string
+    kind: 'task' | 'rule' | 'check'
+    /** CONTENT: repo-relative paths this unit reads. Presence declares the population. */
+    inputs?: string[]
+    /** WORLD: clean-pass duration, e.g. '24h'. Presence declares the population. */
+    ttl?: string
+    /** repo-relative entry files of the unit's OWN code — the module-graph
+     *  roots. A discovered check gets its own file for free. */
+    code?: string[]
+    /** the argv a subprocess unit runs */
+    argv?: string[]
+    /** env var NAMES whose values belong in the key */
+    env?: string[]
+    /** anything else that identifies the question (a rule's `cacheKey`) */
+    extra?: string
+    /** a DECIDED never-cacheable, with the reason. Not the same thing as an
+     *  undeclared unit: this one has been looked at and cannot be described
+     *  (it reads git history, a path outside the repo, the wall clock), so it
+     *  leaves the burn-down list. Declaring it beside inputs or ttl is a
+     *  registration failure, because those say the opposite. */
+    never?: string
+}
+
+export type UnitKey = {
+    id: string
+    kind: UnitDecl['kind']
+    population: Population
+    /** the content key, or null for world/none/refused */
+    key: string | null
+    /** why there is no content key. Always set when key is null. */
+    reason: string | null
+    /** every component that went into the key, in key order — this is what a
+     *  human reads when a key moved and nobody knows why */
+    components: string[]
+    /** the input paths this unit was keyed on, with their object ids */
+    inputOids: [string, string][]
+    /** the identity of the unit's OWN code, module graph included. Set for
+     *  every unit that has code, WORLD ones too: a TTL'd probe whose source
+     *  changed must not replay its previous answer, and this is the value that
+     *  busts it. null when the unit has no code entry or git could not hash it. */
+    codeKey: string | null
+}
+
+export type Registration = {
+    /** loud, blocking: a unit that declared two contradictory populations */
+    errors: string[]
+    /** the default-deny burn-down, one line per undeclared unit */
+    burnDown: string[]
+    /** every unit that was classified */
+    units: number
+    /** units in a cacheable population (content or world) */
+    declared: number
+}
+
+/** which population a declaration puts a unit in, before any git work.
+ *  `inputs` on a `ttl` unit is a registration FAIL: a unit cannot both be
+ *  described by files on disk and be un-describable by them. */
+export function classify(d: UnitDecl): { population: Population; error?: string; reason?: string; decided?: boolean } {
+    const hasInputs = (d.inputs ?? []).length > 0
+    const hasTtl = d.ttl != null && d.ttl !== ''
+    const hasNever = d.never != null && d.never !== ''
+    if (hasInputs && hasTtl)
+        return {
+            population: 'none',
+            error: `${d.kind} '${d.id}' declares BOTH inputs (CONTENT) and ttl (WORLD) — a unit reads files or it reads the world, never both`,
+        }
+    if (hasNever && (hasInputs || hasTtl))
+        return {
+            population: 'none',
+            error: `${d.kind} '${d.id}' declares never:'${d.never}' AND ${hasInputs ? 'inputs' : 'ttl'} — never means nothing can describe this unit, which the other declaration contradicts`,
+        }
+    if (hasInputs) return { population: 'content' }
+    if (hasTtl) return { population: 'world' }
+    if (hasNever) return { population: 'none', reason: d.never, decided: true }
+    return { population: 'none', reason: 'declares neither inputs nor ttl' }
+}
+
+export function validateRegistration(decls: UnitDecl[]): Registration {
+    const errors: string[] = []
+    const burnDown: string[] = []
+    let declared = 0
+    for (const d of decls) {
+        const c = classify(d)
+        if (c.error != null) errors.push(c.error)
+        // a DECIDED never leaves the list: the burn-down is what nobody has
+        // looked at yet, and mixing the two turns it into wallpaper
+        else if (c.population !== 'none') declared++
+        else if (c.decided !== true) burnDown.push(`${d.kind} ${d.id} — ${c.reason ?? 'undeclared'}`)
+        // a declaration that cannot even be turned into a repo-relative path
+        // is a registration bug, not a cache miss: it would key the unit on a
+        // path in another repo, or on the repo root
+        for (const raw of [...(d.inputs ?? []), ...(d.code ?? [])]) {
+            try {
+                normalizeInput(raw)
+            } catch (e) {
+                errors.push(`${d.kind} '${d.id}': ${e instanceof Error ? e.message : String(e)}`)
+            }
+        }
+    }
+    return { errors, burnDown, units: decls.length, declared }
+}
+
+export type KeyLayerOpts = {
+    /** the cli entry actually driving this run — toolchain identity needs to
+     *  know whether the gate binary lives inside the repo being gated */
+    cliEntry: string
+    /** module-graph config; loaded from the repo when omitted */
+    cfg?: RvtConfig
+}
+
+/**
+ * one scan, N keys. Build it once per run: the git work is shared across every
+ * unit, and building two of them in one run would pay for the scan twice and
+ * could straddle an edit.
+ */
+export class KeyLayer {
+    private constructor(
+        readonly root: string,
+        readonly decls: UnitDecl[],
+        readonly registration: Registration,
+        private readonly scan: ScanResult | null,
+        private readonly scanError: string | null,
+        private readonly closureByUnit: Map<string, string[]>,
+        private readonly codeOids: Map<string, string>,
+        private readonly toolchain: { id: string; uncacheable: string[] },
+        private readonly scanPathsUsed: string[],
+        /** wall time of the WHOLE layer: toolchain identity, the module-graph
+         *  closures, the git scan and the closure hashing. Reported rather
+         *  than the scan alone, because the scan alone is the flattering
+         *  number and the caller pays all of it. */
+        readonly openMs: number,
+    ) {}
+
+    /** wall time the GIT half alone cost, ms — `openMs` is what a run pays */
+    get scanMs(): number {
+        return this.scan?.ms ?? 0
+    }
+
+    get failure(): string | null {
+        return this.scanError
+    }
+
+    static open(root: string, decls: UnitDecl[], o: KeyLayerOpts): KeyLayer {
+        const started = performance.now()
+        const registration = validateRegistration(decls)
+        const cfg = o.cfg ?? loadConfig(root)
+        // a gate binary that cannot be resolved is not a crash, it is a run
+        // whose program nobody can name — and the only safe answer to that is
+        // no key at all
+        let toolchain: { id: string; uncacheable: string[] }
+        try {
+            toolchain = toolchainIdentity(root, o.cliEntry)
+        } catch (e) {
+            toolchain = { id: 'unresolved', uncacheable: [`gate binary unreadable at ${o.cliEntry}: ${e instanceof Error ? e.message : String(e)}`] }
+        }
+
+        // the unit's OWN code, resolved through the same module graph the
+        // `cycles` task walks. A check that imports a shared helper carries
+        // that helper, so fixing the helper moves the check's key.
+        const closureByUnit = new Map<string, string[]>()
+        // computed for EVERY unit with code, not only the content ones: a
+        // world unit's TTL cache must break when the probe itself is rewritten
+        for (const d of decls) {
+            const entries = d.code ?? []
+            if (entries.length > 0) closureByUnit.set(d.id, importClosure(cfg, entries))
+        }
+
+        // ONE scan for the declared inputs plus shipkit's own source: those
+        // are mostly directories, mostly unchanged, and git's stat cache
+        // answers them without reading a byte.
+        const paths = new Set<string>()
+        for (const d of decls) {
+            if (classify(d).population !== 'content') continue
+            for (const p of d.inputs ?? []) paths.add(p)
+        }
+
+        // the closure is INDIVIDUAL FILES belonging to no declared path, so it
+        // goes through one `hash-object --stdin-paths` instead of one `git
+        // add` spawn per file (measured: 15ms for the whole set)
+        const closureFiles = new Set<string>()
+        for (const files of closureByUnit.values()) for (const f of files) closureFiles.add(f)
+
+        let scan: ScanResult | null = null
+        let codeOids = new Map<string, string>()
+        let scanError: string | null = null
+        try {
+            scan = scanPaths(root, [...paths])
+            codeOids = hashFiles(root, [...closureFiles]).oids
+        } catch (e) {
+            // a scan that failed may have left a STALE tree behind, so nothing
+            // downstream may key on it. Loud, and the whole run goes uncached.
+            scanError = e instanceof GitScanError ? e.message : String(e)
+        }
+        return new KeyLayer(root, decls, registration, scan, scanError, closureByUnit, codeOids, toolchain, [...paths].sort(), performance.now() - started)
+    }
+
+    /** the key for one unit, or the reason there is none. */
+    keyFor(id: string): UnitKey {
+        const d = this.decls.find((u) => u.id === id)
+        if (d == null) throw new Error(`keyFor: no unit '${id}' in this layer`)
+        const c = classify(d)
+        const own = (this.closureByUnit.get(d.id) ?? []).slice().sort()
+        const ownReadable = own.every((p) => this.codeOids.get(p) != null)
+        const codeLines = own.map((p) => `code:${p}=${this.codeOids.get(p)!}`)
+        const base: UnitKey = {
+            id: d.id, kind: d.kind, population: c.population, key: null, reason: null, components: [], inputOids: [],
+            codeKey: own.length === 0 || !ownReadable ? null : createHash('sha256').update(codeLines.join('\n')).digest('hex').slice(0, 16),
+        }
+        if (c.error != null) return { ...base, reason: c.error }
+        if (c.population === 'world') return { ...base, reason: `world unit — TTL ${d.ttl}, no content key` }
+        if (c.population === 'none') return { ...base, reason: c.reason ?? 'undeclared' }
+        if (this.scanError != null) return { ...base, reason: `git scan failed, nothing may be keyed: ${this.scanError}` }
+        const scan = this.scan!
+        if (this.toolchain.uncacheable.length > 0)
+            return { ...base, reason: `toolchain not describable: ${this.toolchain.uncacheable.join('; ')}` }
+
+        let inputs: string[]
+        try {
+            inputs = (d.inputs ?? []).map(normalizeInput).sort()
+        } catch (e) {
+            return { ...base, reason: e instanceof Error ? e.message : String(e) }
+        }
+        const stale = inputs.filter((p) => scan.missing.includes(p))
+        if (stale.length > 0) return { ...base, reason: `declared input(s) not on disk: ${stale.join(', ')}` }
+        const hidden = inputs.flatMap((p) => scan.excluded.get(p) ?? [])
+        const inputOids: [string, string][] = inputs.map((p) => [p, scan.oidByPath.get(p) ?? ''])
+        if (inputOids.some(([, oid]) => oid === '')) return { ...base, reason: 'git could not name one of the declared inputs' }
+
+        if (!ownReadable) return { ...base, reason: `git could not hash this unit's own source: ${own.filter((p) => this.codeOids.get(p) == null).join(', ')}` }
+        const components: string[] = [
+            `v=${KEY_VERSION}`,
+            `unit=${d.kind}:${d.id}`,
+            `bun=${Bun.version}`,
+            `toolchain=${this.toolchain.id}`,
+            `argv=${JSON.stringify(d.argv ?? [])}`,
+            ...(d.env ?? []).slice().sort().map((n) => `env:${n}=${process.env[n] ?? '<unset>'}`),
+            ...inputOids.map(([p, oid]) => `in:${p}=${oid}`),
+            ...codeLines,
+            ...(d.extra != null ? [`extra=${d.extra}`] : []),
+            // ignored content nobody keyed on is part of the key's MEANING:
+            // two runs that excluded different things answered different
+            // questions, and a silently narrowed key is the false green
+            ...hidden.sort().map((p) => `excluded=${p}`),
+        ]
+        const key = createHash('sha256').update(components.join('\n')).digest('hex').slice(0, 32)
+        return { ...base, key, components, inputOids }
+    }
+
+    keys(): UnitKey[] {
+        return this.decls.map((d) => this.keyFor(d.id))
+    }
+
+    /**
+     * POST RUN RE HASH. Re-scan exactly what this layer keyed on and report
+     * every path whose object id moved while the units were running.
+     *
+     * This is the answer to the poisoning class: a unit reads a file, an agent
+     * in the next window edits it, and the result gets stored under a key that
+     * describes the file as it was BEFORE the edit. Any drift here means the
+     * run's results describe a tree that no longer exists, and the caller
+     * discards them rather than storing a lie. Measured at ~140ms, which is
+     * the price of never having to explain a hit that was wrong.
+     */
+    rescan(): { drifted: string[]; error: string | null; ms: number } {
+        if (this.scanError != null) return { drifted: [], error: this.scanError, ms: 0 }
+        const started = performance.now()
+        try {
+            const after = scanPaths(this.root, this.scanPathsUsed)
+            const drifted: string[] = []
+            for (const [p, oid] of this.scan!.oidByPath) if (after.oidByPath.get(p) !== oid) drifted.push(p)
+            for (const [p] of after.oidByPath) if (!this.scan!.oidByPath.has(p)) drifted.push(p)
+            // the unit's own code drifts the same way a declared input does: an
+            // agent fixing a check WHILE that check runs would otherwise store
+            // the old verdict under the new code's key
+            const files = [...this.codeOids.keys()]
+            if (files.length > 0) {
+                const now = hashFiles(this.root, files)
+                for (const [p, oid] of this.codeOids) if (now.oids.get(p) !== oid) drifted.push(p)
+            }
+            return { drifted: [...new Set(drifted)].sort(), error: null, ms: performance.now() - started }
+        } catch (e) {
+            return { drifted: [], error: e instanceof GitScanError ? e.message : String(e), ms: performance.now() - started }
+        }
+    }
+}