rvlib-shipkit 0.32.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

@@ -0,0 +1,183 @@
+// ONE WAY IN, the harness half (build/shipkit.md). The package.json half
+// (rule SK001) routes `bun run test` into shipkit, but `bun test` is a bun
+// BUILTIN: no script can intercept it, so a package.json alone leaves the
+// reflex wide open. Claude Code permission rules can close it.
+//
+// ONE table, two renderings, because two hand-kept lists drift:
+//   - `permissions.deny` in .claude/settings.json — declarative, unbypassable
+//     (deny beats allow at every settings level, and bypassPermissions mode
+//     does not lift it), and it survives a missing bun.
+//   - a PreToolUse hook — the only thing that can put a REASON in front of the
+//     model. A bare deny says "Permission to use Bash with command bun test
+//     has been denied." and nothing else, so the agent goes looking for
+//     another way in, which is the failure this whole file exists to prevent.
+// The deny is the floor and the hook is the messenger. When the hook cannot
+// run, enforcement degrades to terse rather than to nothing.
+//
+// Subprocesses are NOT intercepted (verified): shipkit spawning oxlint or
+// `bun run test:raw` from inside a permitted `shipkit ci` is invisible to
+// these rules, which is exactly what makes the gate itself still work.
+
+export type RawRunner = {
+    /** the command head as an agent types it — the deny rule is this + `*` */
+    head: string
+    /** the floor slot it answers, so ONE exemption governs the script name and
+     *  the shell command together: a repo that keeps `test` raw is not then
+     *  refused `bun test` */
+    slot: 'test' | 'lint' | 'typecheck'
+    /** the shipkit command that answers the same question, cache and all */
+    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
+     *  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
+}
+
+// the house stack, plus the foreign runners a wired repo is actually found
+// 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 <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' },
+    { head: 'bunx oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
+    { head: 'npx oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
+    { head: 'oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
+    { head: 'npx eslint', slot: 'lint', use: 'shipkit ci --only lint' },
+    { head: 'eslint', slot: 'lint', use: 'shipkit ci --only lint' },
+]
+
+// the FORMATTER is deliberately absent, and that is not an oversight. It
+// answers no cached question and produces no green anyone could mistake for a
+// verification, shipkit's own fix pass runs it BY SCRIPT (`bun run fmt`), and
+// denying the bare binary while that stays open would be theatre. `shipkit ci`
+// formats before it gates, which is the only reason the reflex matters at all.
+
+/** the `permissions.deny` entries, in the syntax Claude Code matches:
+ *  `Bash(<head>*)` is a prefix match, and a compound command is checked one
+ *  segment at a time, so `cd x && bun test` is caught too */
+export const denyRules = (exemptSlots: Iterable<string> = []): string[] => {
+    const off = new Set(exemptSlots)
+    return RAW_RUNNERS.filter((r) => !off.has(r.slot)).map((r) => `Bash(${r.head}*)`)
+}
+
+/** what a refusal says. Never just the ban: a refusal with no replacement
+ *  sends the agent hunting for another runner. `segment` is the part of the
+ *  command that offended, shown only when it says more than the head already
+ *  does: a long compound refused on `CI=1 bun test --timeout 5` otherwise
+ *  leaves the reader guessing which of its clauses was the problem */
+export function refusal(r: RawRunner, segment?: string): string {
+    const alt = r.iterate == null ? '' : `, or \`${r.iterate}\` to iterate on ONE suite while you fix a bug`
+    const which = segment == null || segment.trim() === '' || segment.trim() === r.head ? '' : ` (refused on \`${segment.trim().slice(0, 80)}\`)`
+    return `\`${r.head}\`${which} bypasses shipkit, so nothing is cached and no other agent's run can be attached to. Use \`${r.use}\`${alt}. Lifting this for good: delete the "Bash(${r.head}*)" line from .claude/settings.json permissions.deny (build/shipkit.md, ONE WAY IN).`
+}
+
+/** shell wrappers that do not change what is being run */
+const WRAPPERS = new Set(['time', 'timeout', 'nice', 'nohup', 'stdbuf', 'command', 'builtin', 'sudo', 'env'])
+
+/** the heads a settings file actually denies. The guard asks THE FILE rather
+ *  than the table, so deleting a `Bash(...)` line lifts the deny AND the
+ *  hook's refusal in one edit: two mechanisms an agent has to find and lift
+ *  separately is the deny it cannot escape, which is worse than the disease */
+export function deniedHeads(settings: unknown): Set<string> {
+    const deny = (settings as { permissions?: { deny?: unknown } } | null)?.permissions?.deny
+    const out = new Set<string>()
+    if (!Array.isArray(deny)) return out
+    for (const rule of deny) {
+        const m = typeof rule === 'string' ? /^Bash\((.+?)\*?\)$/.exec(rule) : null
+        if (m != null) out.add(m[1]!.trim())
+    }
+    return out
+}
+
+/** a word that could be the name of a program. Anything carrying a quote, a
+ *  parenthesis or a bracket is prose or code, not an invocation, and matching
+ *  it is how a guard earns a reputation for crying wolf */
+const PROGRAM_WORD = /^[\w./@+-]+$/
+
+/** split a command line on the shell operators, at QUOTE DEPTH ZERO only.
+ *  Without that, `git commit -m "why cd x && bun test is refused"` splits
+ *  inside the message and the second half reads as a command. House commit
+ *  bodies are dense and multi-line, so this is not a corner case here, it is
+ *  the most common shape of command an agent runs. */
+export function shellSegments(command: string): string[] {
+    // everything after a heredoc opener is the document, never a command
+    const shell = command.split(/<<-?\s*['"]?\w+/)[0] ?? command
+    const out: string[] = []
+    let cur = ''
+    let quote: '"' | "'" | null = null
+    for (let i = 0; i < shell.length; i++) {
+        const ch = shell[i]!
+        if (quote != null) {
+            cur += ch
+            if (ch === '\\' && quote === '"') { cur += shell[++i] ?? ''; continue }
+            if (ch === quote) quote = null
+            continue
+        }
+        if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue }
+        if (ch === '\n' || ch === ';' || ch === '|' || ch === '&') {
+            // `&&` and `||` are one operator, and a lone `&` backgrounds
+            if ((ch === '&' || ch === '|') && shell[i + 1] === ch) i++
+            out.push(cur)
+            cur = ''
+            continue
+        }
+        cur += ch
+    }
+    out.push(cur)
+    return out
+}
+
+/** the raw runner this shell command reaches for, plus the segment that
+ *  offended, or null.
+ *
+ *  Deliberately conservative in BOTH directions. It must catch the forms a
+ *  prefix deny rule misses (a leading `CI=1`, `./node_modules/.bin/tsc`), and
+ *  it must never fire on a command that merely CONTAINS the words: a heredoc
+ *  body is data and so is a quoted commit message, and a false refusal teaches
+ *  an agent to route around the whole file. So: the heredoc body is dropped,
+ *  segments are cut at quote depth zero, each is reduced to its first program
+ *  word, and that word must match a head exactly or as the basename of a path.
+ *  Longest head first, so `bunx tsc` is never reported as `tsc`. `only`
+ *  narrows to the heads this repo really denies. */
+export function rawRunnerIn(command: string, only?: ReadonlySet<string>): RawRunner | null {
+    return rawRunnerHit(command, only)?.runner ?? null
+}
+
+export function rawRunnerHit(command: string, only?: ReadonlySet<string>): { runner: RawRunner; segment: string } | null {
+    const heads = [...RAW_RUNNERS]
+        .filter((r) => only == null || only.has(r.head))
+        .sort((a, b) => b.head.length - a.head.length)
+    for (const seg of shellSegments(command)) {
+        let s = seg.trim().replace(/^[(){}\s]+/, '')
+        // leading VAR=value assignments, then a wrapper word, repeatedly. A
+        // wrapper's own flags and durations go with it (`timeout 60 bun test`)
+        let wrapped = false
+        for (;;) {
+            const next = s.replace(/^\w+=(?:"[^"]*"|'[^']*'|\S*)\s+/, '')
+            if (next !== s) { s = next; continue }
+            const w = /^(\S+)\s+/.exec(s)
+            if (w != null && WRAPPERS.has(w[1]!.split('/').pop() ?? '')) { s = s.slice(w[0].length); wrapped = true; continue }
+            if (wrapped && w != null && /^(?:-\S*|\d+[smhd]?)$/.test(w[1]!)) { s = s.slice(w[0].length); continue }
+            break
+        }
+        const words = s.split(/\s+/).filter((w) => w !== '')
+        const first = words[0]
+        if (first == null || !PROGRAM_WORD.test(first)) continue
+        // a path-qualified binary counts: ./node_modules/.bin/tsc IS tsc
+        const program = first.split('/').pop() ?? first
+        for (const r of heads) {
+            const parts = r.head.split(' ')
+            if (parts[0] !== program) continue
+            if (parts.length === 1 || words[1] === parts[1]) return { runner: r, segment: seg }
+        }
+    }
+    return null
+}

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
@@ -102,8 +104,16 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     const c = o.config ?? (await loadRepoConfig(root))
     // mechanical failures are not information, so they never cost a round trip
     let fixFailed = false
+    // a NARROWED run repairs only the mechanical slots. The structural rule
+    // fixers rewrite package.json and repo config, and arming rewrites hooks/:
+    // that is the right price for the full gate and the wrong one for
+    // `bun run test`, which routes here and must answer the one question its
+    // name promises without leaving files in the agent's diff that it never
+    // wrote. Under CI it is worse than surprising, a formatting rewrite comes
+    // back as a test failure.
+    const narrowed = (o.onlyIds ?? []).length > 0
     if (o.fix !== false)
-        fixFailed = (await runFixPass(root, c, { rules: o.fixRules !== false, armHooks: o.armHooks === true, print: sink })).failed
+        fixFailed = (await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink })).failed
     else sink('skip: fix pass (--no-fix)')
     const all = allTasks(c, root)
     const { disabled, unfilled } = all
@@ -122,9 +132,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 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) sink(`skip: ${u.id} (${u.reason})`)
+    for (const u of unfilled) {
+        sink(`skip: ${u.id} (${u.reason})`)
+        // asked for BY NAME and unfillable: this is where an agent lands after
+        // the harness refused it the raw runner, so the line says what to add
+        // rather than leaving it with `unknown task id` and no next move
+        if ((o.onlyIds ?? []).includes(u.id))
+            sink(`      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
+    }
     // the release survey is ~4s of network that five discovered checks need
     // and the TASKS do not. Started HERE it overlaps lint/typecheck/test and
     // costs the run nothing; started inside the first check that wants it, it
@@ -180,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) {