rvlib-shipkit 0.33.0 → 0.35.0

package/src/core/run-ci.ts

@@ -11,13 +11,15 @@ import { reportToMotherhome } from './motherhome.ts'
 import { collectChecks } from './run-check.ts'
 import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
-import { runTasks, type TaskResult } from './task-runner.ts'
+import { runTasks, selectTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
 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 { envTier, FULL_TESTS_ENV, gateUnits, type TestTier } from '../ledger/gate-units.ts'
+import { Ledger, stampReplayed, type UnitOutcome } from '../ledger/ledger.ts'
 
 export type CiOpts = {
     bail?: boolean
@@ -59,6 +61,14 @@ export type CiOpts = {
      *  loads of repo.config.ts can disagree, and the release path classifies
      *  rule-vs-probe severity from the config it holds. */
     config?: RepoConfig
+    /** re-measure everything: no unit replays from the ledger, and what this
+     *  run measures is stored fresh. Travels to child checks as SHIPKIT_FRESH. */
+    fresh?: boolean
+    /** read the ledger at all. The release path passes false, unconditionally
+     *  and not configurably: every remaining hole in the key is then capped at
+     *  "an agent saw a stale local green", never "a stale green authorised a
+     *  publish" (ledger/ledger.ts rule 4). */
+    ledgerRead?: boolean
     /** which test tier the run asks the repo's suite for. 'quick' is the
      *  working default; 'full' sets SHIPKIT_TEST_FULL=1 for every task, which
      *  a suite reads to include the slow, real-world tiers it otherwise skips.
@@ -68,12 +78,8 @@ export type CiOpts = {
     tests?: TestTier
 }
 
-export type TestTier = 'quick' | 'full'
-
-/** the env var a repo's own suite reads to widen itself. Named here because
- *  the gate is what sets it, and a suite that invents its own name is a tier
- *  the release path cannot reach. */
-export const FULL_TESTS_ENV = 'SHIPKIT_TEST_FULL'
+export type { TestTier } from '../ledger/gate-units.ts'
+export { FULL_TESTS_ENV } from '../ledger/gate-units.ts'
 
 /** what STATUS.md may claim about this run. `--with` ADDS a task, so it stays
  *  the full gate; `--only`, `--skip` and skipChecks each remove coverage, and
@@ -116,7 +122,7 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     const all = allTasks(c, root)
     const { disabled, unfilled } = all
     const skipIds = new Set(o.skipTaskIds ?? [])
-    const tier: TestTier = o.tests ?? (process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick')
+    const tier: TestTier = o.tests ?? envTier()
     const tasks = all.tasks
         .filter((t) => !skipIds.has(t.id))
         // the whole run carries the flag rather than one task id: a repo names
@@ -130,6 +136,38 @@ 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 LEDGER, opened once per run and AFTER the fix pass: the fixers
+    // rewrite source, and a scan taken before them would have every unit
+    // discarded by its own gate's repair work.
+    //
+    // Registration is validated on the way in, and it is 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
+    let ledger: Ledger | null = null
+    try {
+        ledger = Ledger.open(root, gateUnits(root, c, tasks), {
+            cliEntry: new URL('../cli.ts', import.meta.url).pathname,
+            read: o.ledgerRead,
+            fresh: o.fresh,
+        })
+        const reg = ledger.layer.registration
+        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.
+        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, so they are measured every run (shipkit keys --burn-down)`)
+        if (ledger.layer.failure != null)
+            sink(`WARN the git scan failed, so NOTHING replays and nothing is stored this run — ${ledger.layer.failure}`)
+    } catch (e) {
+        ledger = null
+        sink(`WARN ledger unavailable (${String(e).slice(0, 160)}) — every unit is measured this run, so the gate is correct and slower`)
+    }
     // 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) {
@@ -152,22 +190,77 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     // paying a 4s network survey to answer it is the same bug --only was
     // fixed for
     const willRunChecks = o.skipChecks !== true && (o.onlyIds ?? []).length === 0
-    const survey = willRunChecks ? collectReports(root, c).catch(() => null) : null
-    const summary = await runTasks({
-        tasks,
+    // REPLAY, before the DAG sees the list. A replayed task is removed from
+    // the run entirely, which is also what makes its dependents correct: the
+    // runner treats a filtered dep as satisfied, and only a GREEN is ever
+    // stored, so a dependent can never start on the back of a red nobody saw.
+    const selectable = new Set(selectTasks({ tasks, logDir: '', skipGroups: o.skipGroups ?? [], withIds: o.withIds ?? [], onlyIds: o.onlyIds ?? [] }).selected.map((t) => t.id))
+    const replayedTasks = new Map<string, UnitOutcome>()
+    const toRun = tasks
+        .filter((t) => {
+            if (ledger == null || !selectable.has(t.id)) return true
+            const hit = ledger.replay(t.id)
+            if (hit == null) return true
+            replayedTasks.set(t.id, hit)
+            for (const l of stampReplayed(hit.lines, hit.measuredMs)) sink(formatLine(l, false))
+            return false
+        })
+        // a dep ON a replayed task is DROPPED, not left dangling. The runner
+        // validates every dep against the list it was handed and dies with
+        // `unknown dep` otherwise, and dropping is the honest edge here: only a
+        // GREEN is ever replayed, so the dependent's precondition is met and
+        // this is the same "a filtered dep counts as satisfied" the runner
+        // already applies to --skip and opt-in tasks.
+        .map((t) => (t.deps?.some((d) => replayedTasks.has(d)) === true ? { ...t, deps: t.deps.filter((d) => !replayedTasks.has(d)) } : t))
+    // the pre-warm exists to hide the survey behind the TASKS. When every task
+    // replayed there is nothing to hide it behind, and starting it anyway is a
+    // 4s network call the run may never need: the five checks that want it
+    // fetch it themselves, and when they replay too, nobody pays for it at all.
+    const survey = willRunChecks && toRun.length > 0 ? collectReports(root, c).catch(() => null) : null
+    // a NAMED task that replayed leaves the list, so its name has to leave the
+    // filters with it: the runner validates `--only`/`--with` against the list
+    // it was handed and answers `unknown task id`. `bun run typecheck` and
+    // `bun run test` route through `--only`, so this is the reflex verb every
+    // agent in every wired repo types, going red on a warm store.
+    const onlyIds = (o.onlyIds ?? []).filter((id) => !replayedTasks.has(id))
+    const withIds = (o.withIds ?? []).filter((id) => !replayedTasks.has(id))
+    // narrowed to nothing is NOT the same as "no filter": an empty --only would
+    // widen the run to every task
+    const nothingToRun = replayedTasks.size > 0 && (toRun.length === 0 || ((o.onlyIds ?? []).length > 0 && onlyIds.length === 0))
+    // every asked-for task replayed: the DAG has nothing to schedule, and
+    // running it anyway would print `all 0 tasks green`, which reads as a gate
+    // that measured nothing rather than one that already knew the answer
+    const summary = nothingToRun
+        ? { ok: true, results: [], interrupted: false }
+        : await runTasks({
+        tasks: toRun,
         logDir: c.logDir ?? join(root, 'tmp/shipkit-ci'),
         cwd: root,
         bail: o.bail ?? false,
         skipGroups: o.skipGroups ?? [],
-        withIds: o.withIds ?? [],
-        onlyIds: o.onlyIds ?? [],
+        withIds,
+        onlyIds,
         print: sink,
         onTaskFinish: o.onTaskFinish,
     })
+    if (nothingToRun) sink(`ok: all ${replayedTasks.size} task(s) asked for replayed, none measured`)
     // what the suite ACTUALLY ran, from its own summary line. A flag that was
     // set proves the intent; the count proves the tests
-    const ranTests = summary.results
-        .map((r) => /Ran (\d+) tests?/.exec(r.lastLine ?? '')?.[1])
+    for (const r of summary.results) {
+        if (ledger == null || r.status !== 'pass') continue
+        const surfaced = r.lines.filter((l) => l.kind === 'warn' || l.kind === 'fix-warn' || l.kind === 'skip')
+        ledger.record(r.id, {
+            status: surfaced.some((l) => l.kind === 'warn' || l.kind === 'fix-warn') ? 'warn' : 'pass',
+            // the headline is REBUILT rather than captured: the runner renders
+            // the wall time into it, and a duration baked into a stored line
+            // would be replayed as if this run had measured it
+            lines: [{ kind: 'ok', text: r.id }, ...surfaced],
+            lastLine: r.lastLine,
+            measuredMs: r.durationMs,
+        })
+    }
+    const ranTests = [...summary.results.map((r) => r.lastLine ?? ''), ...[...replayedTasks.values()].map((o) => o.lastLine ?? '')]
+        .map((l) => /Ran (\d+) tests?/.exec(l)?.[1])
         .find((n) => n != null)
     if (ranTests != null) sink(`ok: test tier ${tier}: ${ranTests} tests ran`)
     // the checks, in the SAME command. there is no second surface: a check
@@ -178,7 +271,7 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     if (survey != null) await survey
     const checks = o.skipChecks === true
         ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
-        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds })
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds, fresh: o.fresh, ledger, reportHome: false })
     if (priorShare == null) delete process.env[SHARE_ENV]; else process.env[SHARE_ENV] = priorShare
     for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
@@ -195,7 +288,12 @@ 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
+    // the post-run re-hash, then the store. NOTHING was written while the gate
+    // ran: a unit whose inputs moved under it answered about a tree that no
+    // longer exists, and this is where that result is thrown away instead of
+    // stored under a key that describes the file as it was before the edit.
+    if (ledger != null) for (const l of ledger.header(ledger.commit())) sink(formatLine(l, false))
+    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,8 +30,28 @@ 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
 }
 
+/** every field a `TaskDef` may carry. Declared as a value so `defineRepo` can
+ *  refuse a typo inside a `defaults` slot: a slot with no `cmd` DECORATES the
+ *  resolved task, so a misspelled field is not a type error at the call site
+ *  and would land as a task that is quietly never cached. Add a field above,
+ *  add it here. */
+export const TASK_DEF_KEYS = ['id', 'cmd', 'logic', 'deps', 'env', 'cwd', 'group', 'optIn', 'timeoutMs', 'inputs', 'ttl', 'never'] as const
+
 export type TaskResult = {
     id: string
     status: 'pass' | 'fail' | 'skipped'
@@ -113,6 +133,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 +179,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,84 @@
+// 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 type { TaskDef } from '../core/task-runner.ts'
+import { discoverChecks } from '../core/discover-checks.ts'
+import { RULES } from '../rules/rule-registry.ts'
+import type { UnitDecl } from './git-key.ts'
+
+/** the env var a repo's own suite reads to widen itself. It lives HERE because
+ *  it rewrites every task's env, which is part of the key: a run that asked for
+ *  the quick tier and one that asked for the full tier are different questions,
+ *  and a surface that renders keys without applying it renders a tier nobody
+ *  ran. */
+export const FULL_TESTS_ENV = 'SHIPKIT_TEST_FULL'
+
+export type TestTier = 'quick' | 'full'
+
+/** the tier this process is asking for, absent an explicit choice */
+export function envTier(): TestTier {
+    return process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick'
+}
+
+/** the repo's tasks as the gate will actually run them at `tier`. */
+export function tieredTasks(c: RepoConfig, root: string, tier: TestTier): TaskDef[] {
+    const tasks = allTasks(c, root).tasks
+    return tier === 'full' ? tasks.map((t) => ({ ...t, env: { ...t.env, [FULL_TESTS_ENV]: '1' } })) : tasks
+}
+
+/** every task, rule and discovered check, in the order the gate meets them.
+ *
+ *  `tasks` overrides what the repo resolves to, and the gate MUST pass what it
+ *  is actually about to run: `--full` rewrites every task's env, and a key
+ *  built from the unmodified list would let a quick run replay into a full one
+ *  under one identity. */
+export function gateUnits(root: string, c: RepoConfig, tasks?: TaskDef[]): UnitDecl[] {
+    const out: UnitDecl[] = []
+    for (const t of tasks ?? 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
+}