rvlib-shipkit 0.33.0 → 0.34.0

package/src/core/locked-write.ts

@@ -3,7 +3,7 @@
 // whole read-modify-write, the write lands via tmp + rename so a killed
 // process can never leave a torn file, and the loser of a race SKIPS —
 // never corrupts, never blocks.
-import { renameSync, rmSync, statSync, writeFileSync } from 'fs'
+import { linkSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'fs'
 import { basename, dirname, join } from 'path'
 
 // a writer that died without unlocking must not wedge the file forever
@@ -37,3 +37,172 @@ export function atomicWrite(path: string, content: string): void {
     writeFileSync(tmpPath, content)
     renameSync(tmpPath, path)
 }
+
+// ---------------------------------------------------------------------------
+// the MUTATE LEASE — the second concurrency shape, and the only other one.
+//
+// withFileLock guards ONE file and the loser SKIPS: right for a render that
+// re-renders next run. The lease guards a PHASE that rewrites the worktree
+// (the fix pass, SK005's `bun update --latest`, hooks arming, the asks
+// archive), where skipping means the repair never happens and overlapping
+// means two processes rewrite the same file at once. So the loser WAITS.
+//
+// TWO PRIMITIVES, both atomic, and both were measured before they were
+// trusted. `writeFileSync(..., 'wx')` creates the NAME first and writes the
+// body second, so a racer that reads in between sees an empty file, calls the
+// lock corrupt, and steals a lease whose holder is very much alive: 5 of 15
+// synchronized starts overlapped. So the body is written to a private name and
+// `linkSync`d into place, one step that fails when the name exists and never
+// exposes a half lock. And a steal of `read, rmSync, grab` is three steps, so
+// every racer wins it: 31 of 40 synchronized starts overlapped after a crash.
+// So a steal is a single `renameSync` of the lock out of the way, which
+// exactly one racer can perform; everyone else gets ENOENT and goes back to
+// grabbing.
+//
+// Bounded in every direction, because a gate that hangs is worse than a gate
+// that overlaps. A holder is stale when its pid is not running OR when the
+// lock has not been touched for LOCK_STALE_MS, so a pid reused by a long
+// lived process cannot wedge a repo forever. A holder that is genuinely still
+// working HEARTBEATS the lock while it holds it, so the age rule only ever
+// fires on a run that is gone or wedged. A waiter gives up after maxWaitMs and
+// says so by name, path and escape hatch. Every line it prints carries a
+// FROZEN wire prefix (wire.ts), so a lease that waits or steals inside
+// `shipkit ci` cannot break that contract.
+
+const LEASE_POLL_MS = 100
+const LEASE_ANNOUNCE_MS = 1_000
+const LEASE_REANNOUNCE_MS = 15_000
+const LEASE_HEARTBEAT_MS = 20_000
+/** shorter than the shortest caller timeout (a discovered check is killed at
+ *  120s), so a waiter always gets to PRINT its refusal rather than being
+ *  SIGTERMed mid wait with no cause on screen */
+const LEASE_MAX_WAIT_MS = 60_000
+
+type Holder = { pid: number; at: number; label: string }
+
+let leaseSeq = 0
+
+const readHolder = (lockPath: string): Holder | null => {
+    try {
+        const h = JSON.parse(readFileSync(lockPath, 'utf8')) as Partial<Holder>
+        return typeof h.pid === 'number' ? { pid: h.pid, at: typeof h.at === 'number' ? h.at : 0, label: String(h.label ?? '?') } : null
+    } catch { return null }
+}
+
+/** is that pid still running? signal 0 asks without delivering anything.
+ *  EPERM means alive and owned by another user, which still counts as alive. */
+const alive = (pid: number): boolean => {
+    if (!Number.isInteger(pid) || pid <= 0) return false
+    try { process.kill(pid, 0); return true } catch (e) { return (e as { code?: string }).code === 'EPERM' }
+}
+
+/** publish a COMPLETE lock under a name that did not exist a moment ago */
+const grabLease = (lockPath: string, label: string): boolean => {
+    const tmp = `${lockPath}.tmp-${process.pid}-${leaseSeq++}`
+    try {
+        writeFileSync(tmp, JSON.stringify({ pid: process.pid, at: Date.now(), label } satisfies Holder))
+        linkSync(tmp, lockPath)
+        return true
+    } catch { return false }
+    finally { rmSync(tmp, { force: true }) }
+}
+
+const sameHolder = (a: Holder | null, b: Holder | null): boolean =>
+    a == null ? b == null : b != null && a.pid === b.pid && a.at === b.at
+
+/** move the lock aside, and ONLY the lock we judged dead. Exactly one racer
+ *  can win the rename; the rest see ENOENT and go back to grabbing.
+ *
+ *  The identity check on both sides is the whole point, and it is a measured
+ *  bug, not a precaution. Reading the holder and stat'ing the file are two
+ *  syscalls, so a racer that read the DEAD holder, then lost the steal, then
+ *  stat'ed the WINNER's fresh lock, judged a live holder dead and threw its
+ *  lease away: 1 in 40 four-process starts against a stale lock. So the holder
+ *  is re-read immediately before the rename, and the moved file is checked
+ *  after it. A lock that turns out to belong to somebody else goes straight
+ *  back and this round is lost. */
+const stealLease = (lockPath: string, expect: Holder | null): boolean => {
+    if (!sameHolder(readHolder(lockPath), expect)) return false
+    const grave = `${lockPath}.dead-${process.pid}-${leaseSeq++}`
+    try { renameSync(lockPath, grave) } catch { return false }
+    if (sameHolder(readHolder(grave), expect)) { rmSync(grave, { force: true }); return true }
+    // it was not the lock we judged: put it back before the name can be taken
+    try { linkSync(grave, lockPath) } catch { /* taken in the gap: the new holder owns it now */ }
+    rmSync(grave, { force: true })
+    return false
+}
+
+/** drop the lock, but only while it is still OURS: a lease that was stolen
+ *  belongs to whoever stole it, and deleting it would hand a third process a
+ *  lease two others believe they hold */
+const releaseLease = (lockPath: string): void => {
+    const h = readHolder(lockPath)
+    if (h == null || h.pid === process.pid) rmSync(lockPath, { force: true })
+}
+
+export type LeaseOutcome<T> = { ok: true; value: T; waitedMs: number } | { ok: false; warn: string }
+
+/** hold `<path>.lock` for the duration of fn. Blocking, stolen from a holder
+ *  that is gone or wedged, refused (never hung) past maxWaitMs. */
+export async function withMutateLease<T>(
+    path: string,
+    o: { label: string; print?: (line: string) => void; maxWaitMs?: number; escape?: string },
+    fn: () => T | Promise<T>,
+): Promise<LeaseOutcome<T>> {
+    const lockPath = `${path}.lock`
+    const print = o.print ?? ((l: string) => console.log(l))
+    const maxWait = o.maxWaitMs ?? LEASE_MAX_WAIT_MS
+    const start = Date.now()
+    // the first announcement is due at LEASE_ANNOUNCE_MS, every later one a
+    // re-announce interval after it
+    let announced = -LEASE_REANNOUNCE_MS
+    mkdirSync(dirname(lockPath), { recursive: true })
+
+    for (;;) {
+        if (grabLease(lockPath, o.label)) break
+        const holder = readHolder(lockPath)
+        let ageMs = 0
+        // the lock vanished between grab and stat: the holder just finished,
+        // so go straight back and take it
+        try { ageMs = Date.now() - statSync(lockPath).mtimeMs } catch { continue }
+        // gone (no such process), or wedged (nothing has touched it for the
+        // stale window, and a live holder heartbeats), or a body no reader can
+        // make sense of that is old enough not to be a write in flight
+        const dead = holder == null ? ageMs > 2_000 : !alive(holder.pid) || ageMs > LOCK_STALE_MS
+        if (dead) {
+            if (stealLease(lockPath, holder)) print(`ok: stole the ${o.label} lease from a holder that is gone (pid ${holder?.pid ?? '?'}, untouched ${Math.round(ageMs / 1000)}s) — a run died mid phase`)
+            continue
+        }
+        const waited = Date.now() - start
+        if (waited > maxWait)
+            return {
+                ok: false,
+                warn: `${o.label} lease held by ${holder == null ? 'an unreadable lock' : `pid ${holder.pid} (${holder.label})`} for ${Math.round(ageMs / 1000)}s — gave up after ${Math.round(waited / 1000)}s rather than run two of these at once. Lock: ${lockPath}${o.escape == null ? '' : `; skip this phase with ${o.escape}`}`,
+            }
+        if (waited >= LEASE_ANNOUNCE_MS && waited - announced >= LEASE_REANNOUNCE_MS) {
+            announced = waited
+            print(`ok: waiting ${Math.round(waited / 1000)}s for the ${o.label} lease — ${holder == null ? 'an unreadable lock holds it' : `pid ${holder.pid} holds it (${holder.label})`}, lock ${lockPath}`)
+        }
+        await Bun.sleep(LEASE_POLL_MS)
+    }
+
+    // a phase that legitimately outlives the stale window must keep proving it
+    // is working, or the age rule steals from it. unref'd, so a held lease
+    // never keeps a process alive on its own
+    const beat = setInterval(() => { try { utimesSync(lockPath, new Date(), new Date()) } catch { /* stolen or gone: the finally sorts it out */ } }, LEASE_HEARTBEAT_MS)
+    beat.unref()
+    try {
+        return { ok: true, value: await fn(), waitedMs: Date.now() - start }
+    } finally {
+        clearInterval(beat)
+        releaseLease(lockPath)
+    }
+}
+
+/** where a repo's mutate leases live. Under the gitignored tmp/ dir so a lease
+ *  file can never enter a commit, and per WORKTREE, because the phases it
+ *  guards rewrite worktree-local files. The NAME is the concern: two phases
+ *  that cannot corrupt each other take different leases, so `asks` never
+ *  blocks a `fix`. `git config` is the one shared-across-worktrees write and
+ *  carries its own retry (hooks/run-hooks.ts). */
+export const mutateLease = (root: string, name: string): string => join(root, 'tmp', `shipkit-${name}`)

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

@@ -29,8 +29,8 @@ export type RawRunner = {
     use: string
     /** the narrower way in, when there is one: iterating on a single repro
      *  test while you fix a bug is not a verification and stays normal. A
-     *  FILTER, not a path: `bun run` quotes what it forwards, and bun reads a
-     *  quoted path as a name filter that then matches nothing */
+     *  FILE filter (measured): bun's positional argument matches the test FILE
+     *  path, and a test NAME needs `-- -t "<name>"` forwarded through bun run */
     iterate?: string
 }
 
@@ -38,12 +38,12 @@ export type RawRunner = {
 // carrying. Kept tight on purpose: a deny an agent hits for no good reason
 // teaches it to route around the whole file.
 export const RAW_RUNNERS: readonly RawRunner[] = [
-    { head: 'bun test', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'bunx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'npx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'npx jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
-    { head: 'jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <name filter>' },
+    { head: 'bun test', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'bunx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'npx vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'vitest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'npx jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
+    { head: 'jest', slot: 'test', use: 'shipkit ci --only test', iterate: 'bun run test:raw <test file>' },
     { head: 'bunx tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
     { head: 'npx tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
     { head: 'tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },

package/src/core/run-ci.ts

@@ -18,6 +18,8 @@ import { rmSync } from 'fs'
 import { SHARE_ENV } from '../release/releases-share.ts'
 import { collectReports } from '../release/run-releases.ts'
 import { withContractsScope } from '../contracts/contracts-once.ts'
+import { gateUnits } from '../ledger/gate-units.ts'
+import { validateRegistration } from '../ledger/git-key.ts'
 
 export type CiOpts = {
     bail?: boolean
@@ -130,6 +132,28 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
         : `skip: full test tier (quick run — \`shipkit ci --full\` or ${FULL_TESTS_ENV}=1 includes it)`)
     for (const t of all.tasks) if (skipIds.has(t.id)) sink(`skip: ${t.id} (not part of this release, the unit's own gate covers it)`)
     for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
+    // the cache-declaration state, once per run. NO git work happens here and
+    // nothing is cached yet: this is the REGISTRATION half, which is pure, and
+    // it has to be loud in the gate rather than only in `shipkit keys`,
+    // because a unit declaring two contradictory populations is a bug in what
+    // binds every repo. The burn-down is one line, never a wall.
+    let registrationFailed = false
+    try {
+        const reg = validateRegistration(gateUnits(root, c))
+        for (const e of reg.errors) { registrationFailed = true; sink(`FAIL: ${e}`) }
+        if (registrationFailed) sink('      fix: a unit declares `inputs` (content), or `ttl` (world), or `never: <reason>`, and never two of them')
+        // both counts, always. Printing only the burn-down made `never:` the
+        // cheap way to shrink the visible number, and that field carries no
+        // verification at all: a growing decided population has to be as
+        // visible as a shrinking undeclared one. No causal clause either,
+        // because nothing is cached yet and "so nothing can replay them"
+        // implies the rest are being replayed.
+        const decided = reg.units - reg.burnDown.length - reg.declared
+        if (reg.burnDown.length > 0 || decided > 0)
+            sink(`skip: cache declarations — ${reg.declared}/${reg.units} declared, ${decided} decided uncacheable, ${reg.burnDown.length} undeclared (shipkit keys --burn-down)`)
+    } catch (e) {
+        sink(`WARN cache declarations unreadable (${String(e).slice(0, 160)}) — nothing is cached, so the gate is unaffected`)
+    }
     // a floor slot nothing could fill is VISIBLE — a thin gate must never
     // look like a full one (the fresh-repo floor gap)
     for (const u of unfilled) {
@@ -195,7 +219,7 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
             sink('      fix: shipkit check')
         } else sink(`WARN ${checks.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${checks.advisoryFailures.join(', ')}`)
     }
-    const code = summary.ok && !fixFailed && !checks.blocked && !advisoryFatal && checks.undeclared.length === 0 ? 0 : 1
+    const code = summary.ok && !fixFailed && !registrationFailed && !checks.blocked && !advisoryFatal && checks.undeclared.length === 0 ? 0 : 1
     // motherhome row (docsBase wiki on this disk) — never affects the gate,
     // and never fires under frozen: a bump/release gate must not re-dirty
     // the tree it just proved clean (field wart 2026-08-05, second head)

package/src/core/run-fixers.ts

@@ -15,6 +15,7 @@ import { armHooks } from '../hooks/run-hooks.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { runFix } from '../rules/run-fix.ts'
 import { routesToShipkit } from './canonical-scripts.ts'
+import { mutateLease, withMutateLease } from './locked-write.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
 
 const FIXER_TIMEOUT_MS = 120_000
@@ -72,37 +73,47 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
     if (offByConfig('imports:fix')) { /* the repo said no, in the one place that governs both directions */ }
     else if (scripts['imports:fix'] != null) slots.push({ id: 'imports:fix', cmd: ['bun', 'run', 'imports:fix'], source: 'package.json script' })
     else {
-        let cli: string | null = null
-        cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/source-graph-cli.ts'))
+        const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/source-graph-cli.ts'))
         slots.push({ id: 'imports:fix', cmd: ['bun', cli, 'imports', '--fix'], source: 'built-in (shipkit)' })
     }
     return { slots, unfilled, disabled }
 }
 
-/** worktree fingerprint: every dirty path mapped to `<status>:<content hash>`,
- *  or null outside a git repo. The fix pass diffs this before and after so the
- *  report names real files instead of asserting "fixed" and hoping.
+/** worktree fingerprint: every dirty path mapped to its CONTENT hash, or null
+ *  outside a git repo. The fix pass diffs this before and after so the report
+ *  names real files instead of asserting "fixed" and hoping.
  *
- *  The hash is load-bearing, not decoration. Status alone is blind to the most
- *  common case there is: a file the agent already edited (` M`) that a fixer
- *  then reformats stays ` M`, so a status-only compare reports "nothing to
- *  rewrite" while the tree changed under it, and in verify mode that is a
- *  silent green on unformatted code. Hashing is confined to the dirty set,
- *  which is small by construction. */
+ *  The hash is the whole comparison, and the porcelain STATUS is deliberately
+ *  not part of it. Status alone is blind to the commonest case there is: a
+ *  file the agent already edited (` M`) that a fixer then reformats stays
+ *  ` M`, so a status-only compare reports "nothing to rewrite" while the tree
+ *  changed under it, and in verify mode that is a silent green on unformatted
+ *  code. The reverse is just as wrong with three agents in one checkout: a
+ *  second agent staging or committing a file during the pass moves its status,
+ *  or drops it out of porcelain entirely, with the bytes untouched. Comparing
+ *  bytes attributes only what a fixer can actually have done.
+ *
+ *  It watches the WHOLE tree on purpose. A narrower porcelain was tried and
+ *  deleted: the only fixer whose targets are declarable is the formatter, and
+ *  the same pass also runs the rule fixers, which rewrite package.json,
+ *  .gitignore, CLAUDE.md and .claude/, none of them inside a formatter's
+ *  scope. Narrowing to the formatter's paths therefore hid real rewrites from
+ *  the verify mode, which is a silent green on a tree a fixer changed. What
+ *  actually stops another agent's work being reported here is the lease plus
+ *  the byte comparison, not a path list. */
 function treeState(root: string): Map<string, string> | null {
     const p = Bun.spawnSync(['git', 'status', '--porcelain'], { cwd: root })
     if (p.exitCode !== 0) return null
     const m = new Map<string, string>()
     for (const l of p.stdout.toString().split('\n')) {
         if (l.trim() === '') continue
-        const status = l.slice(0, 2)
         // rename entries read `R  old -> new`; the new path is what exists
         const path = l.slice(3).trim().split(' -> ').at(-1) ?? ''
         if (path === '') continue
         const abs = join(root, path.replace(/^"|"$/g, ''))
         let hash = 'absent'
         try { if (existsSync(abs)) hash = String(Bun.hash(readFileSync(abs))) } catch { hash = 'unreadable' }
-        m.set(path, `${status}:${hash}`)
+        m.set(path, hash)
     }
     return m
 }
@@ -119,7 +130,7 @@ export type FixPassOpts = {
 
 export type FixPassResult = {
     ran: boolean
-    /** paths whose git status changed across the pass */
+    /** paths whose CONTENT changed across the pass */
     touched: string[]
     /** verify mode only: a fixer had to rewrite something, so the commit is not clean */
     failed: boolean
@@ -129,6 +140,30 @@ export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpt
     // verify mode: same fixers, but rewriting anything means the COMMIT was
     // not clean, and the gate says so instead of quietly repairing it
     const verify = process.env.CI != null && process.env.CI !== ''
+    // EVERY write this function makes sits inside one lease. Three agents in
+    // one checkout is the normal case, and two formatters rewriting the same
+    // file at once, or two runs arming hooks and rewriting package.json
+    // together, is the one hazard a snapshot diff cannot even detect. The
+    // loser waits rather than skipping, because a skipped repair never
+    // happens; a live holder that outlasts the cap is REFUSED by name rather
+    // than overlapped, and the gate below still runs, unrepaired and saying so.
+    const lease = await withMutateLease(mutateLease(root, 'fix'), { label: 'fix pass', print: o.print, escape: '--no-fix' }, () => fixPassBody(root, config, o, verify))
+    if (lease.ok) return lease.value
+    // in VERIFY mode the fix pass is the whole check: reporting "not run" and
+    // exiting 0 would pass a commit nobody verified, which is the one failure
+    // this gate exists to prevent. Locally it is a WARN, because the tasks and
+    // checks below still ran and still mean what they say.
+    if (verify) {
+        o.print(`FAIL: fixers never ran — ${lease.warn}`)
+        o.print('      fix: nothing was verified. re-run once that process finishes, or pass --no-fix to state that on purpose')
+        return { ran: false, touched: [], failed: true }
+    }
+    o.print(`WARN fix pass skipped — ${lease.warn}`)
+    o.print('      fix: nothing was repaired this run; the gate below reports the tree as it stands')
+    return { ran: false, touched: [], failed: false }
+}
+
+async function fixPassBody(root: string, config: RepoConfig, o: FixPassOpts, verify: boolean): Promise<FixPassResult> {
     // commit gates arm themselves on the interactive gate: a repo.config with
     // dark hooks is the half-wired state that let a whole drill session
     // commit ungated (2026-08-04). Runs BEFORE the tree snapshot: arming is
@@ -157,10 +192,18 @@ export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpt
     const after = treeState(root)
     const touched: string[] = []
     if (before != null && after != null) {
-        for (const [path, st] of after) if (before.get(path) !== st) touched.push(path)
-        // a file the fixer restored to its committed state disappears from
-        // porcelain entirely, that is still a change worth naming
-        for (const path of before.keys()) if (!after.has(path)) touched.push(path)
+        for (const [path, hash] of after) if (before.get(path) !== hash) touched.push(path)
+        // a path that left porcelain either got RESTORED to its committed
+        // bytes by a fixer, which is a rewrite worth naming, or was committed
+        // by another agent mid-pass, which is not this pass's doing. Only the
+        // bytes tell the two apart, so read them.
+        for (const [path, hash] of before) {
+            if (after.has(path)) continue
+            const abs = join(root, path.replace(/^"|"$/g, ''))
+            let now = 'absent'
+            try { if (existsSync(abs)) now = String(Bun.hash(readFileSync(abs))) } catch { now = 'unreadable' }
+            if (now !== hash) touched.push(path)
+        }
     }
     const list = `${touched.slice(0, 8).join(' ')}${touched.length > 8 ? ` … +${touched.length - 8}` : ''}`
     if (before == null) {

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/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/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
+}