@tachikomagundam/abathur 0.2.5 → 0.2.7

package/dist/core/promote.js

@@ -9,13 +9,14 @@ import path from "node:path";
 import { ExitSignal, blocked, cannotAnswer } from "../exit.js";
 import { compileGlob } from "./glob.js";
 import { fastForwardIncumbent } from "./incumbent.js";
+import { effectiveRepoPath } from "./spec.js";
 import { buildManifest, kernelsDirOf, manifestPathFor, readManifestFile, serializeManifest, } from "./kernel.js";
-import { Ledger, ledgerPath } from "./ledger.js";
+import { acquireGenomeLock, acquireLock, LEDGER_KIND_PROMOTE, Ledger, ledgerPath } from "./ledger.js";
 import { gitOpts, requireSha } from "./genome-paths.js";
 import { snapshotCommit } from "./snapshot.js";
 import { tryGit } from "../util/git.js";
 import { decodeGenerationRecord } from "./evolve/run-bench.js";
-export const LEDGER_KIND_PROMOTE = "promote";
+export { LEDGER_KIND_PROMOTE };
 /** Ledger/display-safe flattening of untrusted text (todo-8 sealMessage discipline). */
 function display(value, max = 96) {
     const flat = value.replace(/[^ -~]/g, " ").replace(/\s+/g, " ").trim();
@@ -65,55 +66,70 @@ async function sealedPathCheck(genId, nom, matchers, sealedPaths, cwd, opts) {
 }
 export async function promoteGeneration(req) {
     const { entry, configDir } = req;
-    const repo = entry.spec.repoPath;
+    const repo = effectiveRepoPath(entry.spec.repoPath);
     const shown = display(req.genId);
     const opts = req.env === undefined ? {} : { env: req.env };
     const ledger = Ledger.open(repo);
-    const records = ledger.readAll();
-    const genRows = records.filter((r) => r.kind === "generation_complete" && r.genId === req.genId);
-    const lastRow = genRows.at(-1);
-    if (lastRow === undefined) {
-        blocked(`promote: no generation_complete ledger row for gen '${shown}' of '${entry.label}'`, `state is read only from ${ledgerPath(repo)} — check candidates with \`abathur status ${entry.label}\``);
-    }
-    if (records.some((r) => r.kind === LEDGER_KIND_PROMOTE && r.genId === req.genId)) {
-        blocked(`promote: gen '${shown}' is already promoted (promote row in ledger) — nothing to do`);
-    }
-    const nom = nominatedGeneration(decodeGenerationRecord(lastRow), shown);
-    const manifestFile = manifestPathFor(configDir, entry.fingerprint);
-    let manifestEntries;
+    // the human gate is a state mutation: single-flight it against the run loop
+    // and any concurrent gate, same class as graft (postmortem 2026-09-28 retract
+    // review — the gate read→check→mutate→append sequence must not interleave).
+    const lease = acquireGenomeLock({ ledger, configDir, genomeFp: entry.fingerprint });
     try {
-        manifestEntries = readManifestFile(manifestFile);
+        const repoLease = acquireLock({ configDir: path.join(repo, ".state", "abathur"), key: "gate", label: "gate lock" });
+        try {
+            const records = ledger.readAll();
+            const genRows = records.filter((r) => r.kind === "generation_complete" && r.genId === req.genId);
+            const lastRow = genRows.at(-1);
+            if (lastRow === undefined) {
+                blocked(`promote: no generation_complete ledger row for gen '${shown}' of '${entry.label}'`, `state is read only from ${ledgerPath(repo)} — check candidates with \`abathur status ${entry.label}\``);
+            }
+            if (records.some((r) => r.kind === LEDGER_KIND_PROMOTE && r.genId === req.genId)) {
+                blocked(`promote: gen '${shown}' is already promoted (promote row in ledger) — nothing to do`);
+            }
+            const nom = nominatedGeneration(decodeGenerationRecord(lastRow), shown);
+            const manifestFile = manifestPathFor(configDir, entry.fingerprint);
+            let manifestEntries;
+            try {
+                manifestEntries = readManifestFile(manifestFile);
+            }
+            catch (cause) {
+                if (cause instanceof ExitSignal)
+                    throw cause;
+                const message = cause instanceof Error ? cause.message : String(cause);
+                cannotAnswer(`promote: kernel manifest unreadable, refusing to gate: ${message}`);
+            }
+            const sealedPaths = new Set(manifestEntries.map((e) => e.path));
+            const matchers = entry.spec.kernel.immutableGlobs.map((glob) => compileGlob(glob));
+            await sealedPathCheck(req.genId, nom, matchers, sealedPaths, repo, opts);
+            const genome = { repoPath: repo, genomeFp: entry.fingerprint };
+            const ff = await fastForwardIncumbent(genome, nom.commitSha, opts);
+            // regeneration happens ONLY here, after the human-invoked diff passed:
+            // manifest reborn from the new incumbent's committed tree, not the worktree.
+            const snap = await snapshotCommit(genome, nom.commitSha, opts);
+            const fresh = buildManifest(snap.snapshotPath, entry.spec.kernel.immutableGlobs);
+            mkdirSync(kernelsDirOf(configDir), { recursive: true });
+            writeFileSync(manifestFile, serializeManifest(fresh), "utf8");
+            ledger.append({
+                kind: LEDGER_KIND_PROMOTE,
+                genId: req.genId,
+                data: { actor: "cli", genId: req.genId, from: ff.fromSha, to: ff.toSha },
+            });
+            return {
+                genId: req.genId,
+                fromSha: ff.fromSha,
+                toSha: ff.toSha,
+                lines: [
+                    `promoted '${entry.label}' (${entry.fingerprint}): ${ff.fromSha === null ? "incumbent branch created" : short(ff.fromSha)} -> ${short(ff.toSha)} (gen ${shown})`,
+                    `manifest: rewrote ${path.relative(process.cwd(), manifestFile) || manifestFile} from tree ${short(nom.commitSha)} (${String(fresh.length)} sealed ${fresh.length === 1 ? "entry" : "entries"})`,
+                    `ledger: appended '${LEDGER_KIND_PROMOTE}' row (actor: cli) to ${ledgerPath(repo)}`,
+                ],
+            };
+        }
+        finally {
+            repoLease.release();
+        }
     }
-    catch (cause) {
-        if (cause instanceof ExitSignal)
-            throw cause;
-        const message = cause instanceof Error ? cause.message : String(cause);
-        cannotAnswer(`promote: kernel manifest unreadable, refusing to gate: ${message}`);
+    finally {
+        lease.release();
     }
-    const sealedPaths = new Set(manifestEntries.map((e) => e.path));
-    const matchers = entry.spec.kernel.immutableGlobs.map((glob) => compileGlob(glob));
-    await sealedPathCheck(req.genId, nom, matchers, sealedPaths, repo, opts);
-    const genome = { repoPath: repo, genomeFp: entry.fingerprint };
-    const ff = await fastForwardIncumbent(genome, nom.commitSha, opts);
-    // regeneration happens ONLY here, after the human-invoked diff passed:
-    // manifest reborn from the new incumbent's committed tree, not the worktree.
-    const snap = await snapshotCommit(genome, nom.commitSha, opts);
-    const fresh = buildManifest(snap.snapshotPath, entry.spec.kernel.immutableGlobs);
-    mkdirSync(kernelsDirOf(configDir), { recursive: true });
-    writeFileSync(manifestFile, serializeManifest(fresh), "utf8");
-    ledger.append({
-        kind: LEDGER_KIND_PROMOTE,
-        genId: req.genId,
-        data: { actor: "cli", genId: req.genId, from: ff.fromSha, to: ff.toSha },
-    });
-    return {
-        genId: req.genId,
-        fromSha: ff.fromSha,
-        toSha: ff.toSha,
-        lines: [
-            `promoted '${entry.label}' (${entry.fingerprint}): ${ff.fromSha === null ? "incumbent branch created" : short(ff.fromSha)} -> ${short(ff.toSha)} (gen ${shown})`,
-            `manifest: rewrote ${path.relative(process.cwd(), manifestFile) || manifestFile} from tree ${short(nom.commitSha)} (${String(fresh.length)} sealed ${fresh.length === 1 ? "entry" : "entries"})`,
-            `ledger: appended '${LEDGER_KIND_PROMOTE}' row (actor: cli) to ${ledgerPath(repo)}`,
-        ],
-    };
 }

package/dist/core/readjudicate.js

@@ -0,0 +1,247 @@
+// re-adjudicate (institutional addition 2026-09-28, born of the c17 silent-downgrade
+// incident): when the GATE code that judged a generation is later found to have been
+// the wrong binary (or any honest cause), the corrected verdict must be able to enter
+// machine state WITHOUT touching the immutable ledger files: this command replays the
+// CURRENT evaluate() over the archived rows and APPENDS a fresh generation_complete
+// row carrying the corrected verdict plus full provenance. Promote already reads the
+// LAST row for a gen, so a corrected nomination unlocks the human gate; a corrected
+// cull stays honest too — this tool re-judges, it never flips.
+//
+// Replay contract (mirrors scripts/backtest-acceptance.mjs, the established approach):
+//  - gate-time counters = lifetime sum over the epoch (all rows sharing the runId)
+//    MINUS the candidate row's own spend (its slot was already committed by the
+//    session clamp — feeding it back would self-trip the cap, run-loop.ts:316-318);
+//  - the score bank excludes THIS candidate's own tree groups (its verdict-time
+//    draws must not price its own noise — excludeCandidateTrees is the built hook);
+//  - nPairs = 1 (one finalist pair per re-judged epoch).
+// Fail-closed: no candidate row / no incumbent row for the same runId / an existing
+// promote row for the gen ⇒ refusal before any state read becomes a mutation.
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { blocked, cannotAnswer } from "../exit.js";
+import { effectiveRepoPath } from "./spec.js";
+import { evaluate, needsExit } from "./stats.js";
+import { acquireGenomeLock, acquireLock, Ledger, ledgerPath, ledgerRecordSchema, LEDGER_KIND_GENERATION_COMPLETE, LEDGER_KIND_PROMOTE } from "./ledger.js";
+import { asReplicates, decodeGenerationRecord } from "./evolve/run-bench.js";
+import { effectiveCaps } from "./evolve/run-plan.js";
+import { loadScoreBank } from "./evolve/score-bank.js";
+const LIVE_LEDGER = "ledger.jsonl";
+function isRotatedArchive(name) {
+    return name.startsWith("ledger.") && name.endsWith(".jsonl") && name !== LIVE_LEDGER && !name.startsWith("ledger.corrupt-");
+}
+/** Same read discipline as the score bank: schema-invalid lines are skipped with a notice, never a crash. */
+function collectRows(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return { rows: [], notices: [] };
+    }
+    const files = names.filter((n) => n === LIVE_LEDGER || isRotatedArchive(n)).sort();
+    const rows = [];
+    const notices = [];
+    for (const file of files) {
+        let text;
+        try {
+            text = readFileSync(path.join(dir, file), "utf8");
+        }
+        catch {
+            notices.push(`${file}: unreadable — skipped`);
+            continue;
+        }
+        for (const [index, raw] of text.split("\n").entries()) {
+            const line = raw.trim();
+            if (line.length === 0)
+                continue;
+            let candidate;
+            try {
+                candidate = JSON.parse(line);
+            }
+            catch {
+                notices.push(`${file}:${String(index + 1)}: not JSON — row skipped`);
+                continue;
+            }
+            const parsed = ledgerRecordSchema.safeParse(candidate);
+            if (!parsed.success) {
+                notices.push(`${file}:${String(index + 1)}: schema-invalid — row skipped`);
+                continue;
+            }
+            rows.push({ file, ts: parsed.data.ts, record: parsed.data });
+        }
+    }
+    return { rows, notices };
+}
+function display(value, max = 96) {
+    const flat = value.replace(/[^ -~]/g, " ").replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+export function readjudicateGeneration(req) {
+    const { entry, genId } = req;
+    const shown = display(genId);
+    const repo = effectiveRepoPath(entry.spec.repoPath);
+    const dir = path.dirname(ledgerPath(repo));
+    const { rows, notices } = collectRows(dir);
+    // locate the candidate row: the LAST generation_complete row for this gen that is a
+    // candidate arm; if it already carries readjudication provenance, this is the second pass.
+    const genRows = rows.filter((r) => r.record.kind === LEDGER_KIND_GENERATION_COMPLETE && r.record.genId === genId);
+    let incumbent = null;
+    let candidate = null;
+    for (const r of genRows) {
+        let data;
+        try {
+            data = decodeGenerationRecord(r.record);
+        }
+        catch {
+            continue; // not a decodable generation row — skip like the bank does
+        }
+        if (data.source === "candidate")
+            candidate = { row: r, data };
+    }
+    if (candidate === null) {
+        blocked(`re-adjudicate: no candidate generation_complete row for gen '${shown}' (searched live ledger + rotated archives in ${dir})`, `state is read only from the ledger files — check candidates with \`abathur status ${entry.label}\``);
+    }
+    if (candidate.data.verdict === undefined) {
+        blocked(`re-adjudicate: candidate row for gen '${shown}' has no verdict — nothing to re-judge`);
+    }
+    // non-null alias: TS narrowing does not survive let-assignment inside loops
+    const cand = candidate;
+    if (rows.some((r) => r.record.kind === LEDGER_KIND_PROMOTE && r.record.genId === genId)) {
+        blocked(`re-adjudicate: gen '${shown}' is already promoted — a corrected verdict cannot and need not move it`);
+    }
+    // incumbent row: same runId, candidate's epoch — search ALL rows, archives included.
+    const runId = cand.row.record.runId;
+    if (runId === undefined)
+        cannotAnswer(`re-adjudicate: candidate row for gen '${shown}' lacks runId — cannot pair it with its incumbent baseline`);
+    for (const r of rows) {
+        if (r.record.kind !== LEDGER_KIND_GENERATION_COMPLETE || r.record.runId !== runId)
+            continue;
+        if (r.record.genId === genId)
+            continue; // same gen never supplies the incumbent arm
+        let data;
+        try {
+            data = decodeGenerationRecord(r.record);
+        }
+        catch {
+            continue;
+        }
+        if (data.source === "incumbent") {
+            if (incumbent !== null && incumbent.row.record.genId !== r.record.genId) {
+                cannotAnswer(`re-adjudicate: multiple incumbent rows for runId '${display(runId)}' with differing gens — ambiguous epoch, refusing`);
+            }
+            incumbent = { row: r, data };
+        }
+    }
+    if (incumbent === null) {
+        blocked(`re-adjudicate: no incumbent baseline row for runId '${display(runId)}' (candidate gen '${shown}') — cannot re-judge an unpaired epoch`);
+    }
+    const inc = incumbent; // non-null alias (incumbent guarded above; narrowing dies in the loop)
+    // gate-time counters mirror the backtest: lifetime epoch sum minus the candidate's own slot.
+    let tokens = 0;
+    let modelCalls = 0;
+    let wallS = 0;
+    for (const r of rows) {
+        if (r.record.runId !== runId)
+            continue;
+        if (r === cand.row)
+            continue;
+        let data;
+        try {
+            data = decodeGenerationRecord(r.record);
+        }
+        catch {
+            continue;
+        }
+        tokens += data.counters.tokens;
+        modelCalls += data.counters.modelCalls;
+        wallS += data.counters.wallS;
+    }
+    const counters = { candidates: 0, modelCalls, tokens, wallS: Number(wallS.toFixed(3)) };
+    const bank = loadScoreBank(repo, { excludeCandidateTrees: cand.data.treeSha === undefined ? [] : [cand.data.treeSha] });
+    const gate = evaluateWith(entry, cand.data, inc.data, counters, runId, bank);
+    const lines = [];
+    for (const n of notices)
+        lines.push(`notice: ${n}`);
+    lines.push(`replay: gen ${shown} verdict-time ${gate.candidateVerdictBefore} -> current gate '${gate.verdict}' (gain ${gate.gain === null ? "null" : gate.gain.toFixed(4)}, bank ${bank === null ? "absent → legacy gate" : `${String(bank.units.size)} units, prior sigma ${bank.priorSigma.toFixed(4)}, pooled df ${String(bank.totalDf)}`})`);
+    if (gate.verdict === cand.data.verdict && cand.data.readjudication === undefined) {
+        lines.push(`no-op: current gate already agrees with the row verdict '${gate.verdict}' — nothing appended`);
+        return { appended: false, verdict: gate.verdict, lines };
+    }
+    if (cand.data.readjudication !== undefined && gate.verdict === cand.data.verdict) {
+        lines.push(`no-op: gen already carries a readjudication row with verdict '${gate.verdict}' — nothing appended`);
+        return { appended: false, verdict: gate.verdict, lines };
+    }
+    const ledger = Ledger.open(repo);
+    const lease = acquireGenomeLock({ ledger, configDir: req.configDir, genomeFp: entry.fingerprint });
+    try {
+        const repoLease = acquireLock({ configDir: path.join(repo, ".state", "abathur"), key: "gate", label: "re-adjudicate lock" });
+        try {
+            // re-read under lock: a promote or younger row may have landed while we computed.
+            const fresh = collectRows(dir).rows.filter((r) => r.record.kind === LEDGER_KIND_GENERATION_COMPLETE && r.record.genId === genId);
+            const lastData = [...fresh].reverse().map((r) => {
+                try {
+                    return decodeGenerationRecord(r.record);
+                }
+                catch {
+                    return null;
+                }
+            }).find((d) => d !== null);
+            if (lastData === undefined) {
+                blocked(`re-adjudicate: gen '${shown}' rows vanished under lock — state moved, nothing appended`);
+            }
+            if (lastData.verdict === gate.verdict) {
+                lines.push(`no-op (under lock): last row already reads '${gate.verdict}'`);
+                return { appended: false, verdict: gate.verdict, lines };
+            }
+            if (lastData.readjudication !== undefined) {
+                blocked(`re-adjudicate: gen '${shown}' already has a readjudication row verdict '${lastData.verdict}' disagreeing with replay '${gate.verdict}' — a second correction would erase the first; hand the ledger a ruling instead`);
+            }
+            if (fresh.some((r) => r.record.kind === LEDGER_KIND_PROMOTE)) {
+                blocked(`re-adjudicate: gen '${shown}' was promoted while this command computed — refusing to amend a promoted epoch`);
+            }
+            const replayExit = needsExit(gate.verdict);
+            const data = {
+                ...cand.data,
+                verdict: gate.verdict,
+                exitCode: replayExit === 0 ? 0 : replayExit === 1 ? 1 : 2,
+                gain: gate.gain,
+                gateFailures: [...gate.failures],
+                readjudication: {
+                    at: req.now().toISOString(),
+                    specFingerprint: entry.fingerprint,
+                    gate: bank === null ? "legacy" : "acceptance",
+                    bank: bank === null ? null : { units: bank.units.size, priorSigma: bank.priorSigma, pooledDf: bank.totalDf },
+                    sourceRows: {
+                        candidate: { file: cand.row.file, ts: cand.row.ts },
+                        incumbent: { file: inc.row.file, ts: inc.row.ts },
+                    },
+                    replacedVerdict: cand.data.verdict ?? "none",
+                },
+            };
+            ledger.append({ kind: LEDGER_KIND_GENERATION_COMPLETE, genId, ...(runId === undefined ? {} : { runId }), data });
+            lines.push(`ledger: appended corrected generation_complete row (verdict '${gate.verdict}', actor: re-adjudicate) to ${ledgerPath(repo)}`);
+            lines.push(`files are immutable — the original '${cand.data.verdict}' row remains in ${cand.row.file} as history`);
+            for (const f of gate.failures)
+                lines.push(`  gate: ${f}`);
+        }
+        finally {
+            repoLease.release();
+        }
+    }
+    finally {
+        lease.release();
+    }
+    return { appended: true, verdict: gate.verdict, lines };
+}
+// the replay itself — kept tiny and explicit so the counters/bank/nPairs contract above is auditable.
+function evaluateWith(entry, candidate, incumbent, counters, runId, bank) {
+    const verdict = evaluate({
+        candidate: { runId: runId ?? "re-adjudicate", units: asReplicates(candidate.units), counters },
+        incumbent: { units: asReplicates(incumbent.units) },
+        stats: entry.spec.bench.stats,
+        budgetCaps: effectiveCaps(entry.spec, undefined),
+        nPairs: 1,
+        ...(bank === null ? {} : { bank: bank.units }),
+    });
+    return { verdict: verdict.verdict, gain: verdict.gain, failures: verdict.failures, candidateVerdictBefore: String(candidate.verdict) };
+}

package/dist/core/retract.js

@@ -0,0 +1,166 @@
+// retractGeneration — the human gate that undoes a promote (design gap found
+// 2026-09-28 when the human ordered a rollback of self-cli and the engine had
+// no path: tombstone refuses promoted gens by design, incumbent.ts moves the
+// ref forward-only). Doctrine:
+// - History is append-only: the promote row STAYS; retract appends its own
+//   row. No commit moves, no lineage deletes (retract ≠ delete).
+// - LIFO only: a later LIVE promote must be retracted first.
+// - Descendant guard: a generation seeded FROM this incumbent (a
+//   generation_complete row appended after the promote row) blocks the
+//   retract unless its lineage is dead (tombstoned or retracted).
+// - ref-absent is NOT fail-open: when the incumbent ref is already gone (a
+//   documented manual rollback), the retract is recordable only when the gen
+//   being retracted is the ONLY live promote — anything else is a divergence
+//   the human must resolve first. The row then carries refState:"absent".
+// - The incumbent branch must be idle in EVERY worktree (worktree list
+//   --porcelain), not just the primary checkout.
+// - The whole read→guard→mutate→append sequence runs under the genome lock
+//   plus a repo-local gate lock (cross-config-home safety). The descendant
+//   guard is point-in-time BY DESIGN: a run seeded from this incumbent before
+//   the retract may still append its generation_complete afterwards — that row
+//   is honest and its commits are preserved (retract ≠ delete); what the lock
+//   guarantees is that no decision RACES the retract, not that no lineage
+//   outlives it.
+// Import policy mirrors core/promote.ts: this module is imported ONLY by
+// src/commands/retract.ts (pinned by the structural test in promote.test.ts).
+// No force flag: every refusal is a bug report, not a flag.
+import { existsSync, rmSync } from "node:fs";
+import path from "node:path";
+import { blocked, cannotAnswer } from "../exit.js";
+import { tryGit } from "../util/git.js";
+import { gitOpts } from "./genome-paths.js";
+import { INCUMBENT_BRANCH } from "./incumbent.js";
+import { manifestPathFor } from "./kernel.js";
+import { acquireGenomeLock, acquireLock, LEDGER_KIND_PROMOTE, LEDGER_KIND_TOMBSTONE, Ledger } from "./ledger.js";
+import { effectiveRepoPath } from "./spec.js";
+export const LEDGER_KIND_RETRACT = "retract";
+/** Every worktree (primary + linked) that has the incumbent branch checked out. */
+async function incumbentCheckouts(repo, opts) {
+    const run = await tryGit(["worktree", "list", "--porcelain"], gitOpts(opts, repo));
+    if (!run.ok)
+        cannotAnswer(`retract: cannot enumerate worktrees in ${repo}: ${run.error.kind}`);
+    // entries are blank-line-separated blocks; attributes (branch, prunable …)
+    // come AFTER the worktree line, so evaluate whole blocks, not a line stream
+    const busy = [];
+    for (const block of run.stdout.split("\n\n")) {
+        const lines = block.split("\n");
+        const wt = lines.find((l) => l.startsWith("worktree "));
+        if (wt === undefined)
+            continue;
+        // "prunable <reason>" = stale metadata for a deleted directory — it must
+        // not permanently block the rollback valve
+        if (lines.some((l) => l.startsWith("prunable")))
+            continue;
+        if (lines.some((l) => l === `branch refs/heads/${INCUMBENT_BRANCH}`))
+            busy.push(wt.slice("worktree ".length));
+    }
+    return busy;
+}
+export async function retractGeneration(req) {
+    const repo = effectiveRepoPath(req.entry.spec.repoPath);
+    const opts = req.env === undefined ? {} : { env: req.env };
+    const gopts = gitOpts(opts, repo);
+    const ledger = Ledger.open(repo);
+    const lease = acquireGenomeLock({ ledger, configDir: req.configDir, genomeFp: req.entry.fingerprint });
+    try {
+        // the genome lock is keyed (configDir, fingerprint): two registry entries or two
+        // config homes pointing at the SAME repo hold different locks. The ledger and the
+        // incumbent ref are repo-global, so the gate sequence also takes a REPO-local
+        // lock — same lock regardless of which config home the caller came through.
+        // Nested inside the genome-lock try so a contended repo lock never strands it.
+        const repoLease = acquireLock({ configDir: path.join(repo, ".state", "abathur"), key: "gate", label: "gate lock" });
+        try {
+            const records = ledger.readAll();
+            const promoteIndex = records.findIndex((r) => r.kind === LEDGER_KIND_PROMOTE && r.genId === req.genId);
+            if (promoteIndex < 0) {
+                blocked(`retract: no promote ledger row for gen '${req.genId}' of '${req.entry.label}' — nothing to retract`, "retract undoes a promote; for a never-promoted candidate use `abathur tombstone`");
+            }
+            const promoteRow = records[promoteIndex];
+            if (records.some((r) => r.kind === LEDGER_KIND_RETRACT && r.genId === req.genId)) {
+                blocked(`retract: gen '${req.genId}' is already retracted — nothing to do`);
+            }
+            // a lineage is dead once tombstoned (never promoted) or retracted (promoted,
+            // then undone): it no longer sits on the incumbent chain.
+            const released = new Set(records.filter((r) => r.kind === LEDGER_KIND_TOMBSTONE || r.kind === LEDGER_KIND_RETRACT).map((r) => r.genId));
+            const livePromotes = records.filter((r) => r.kind === LEDGER_KIND_PROMOTE && !released.has(r.genId));
+            const later = records.slice(promoteIndex + 1);
+            if (later.some((r) => r.kind === LEDGER_KIND_PROMOTE && !released.has(r.genId))) {
+                blocked(`retract: a later promote exists for '${req.entry.label}' — retract is LIFO`, "retract the later generation first, then re-run this retract");
+            }
+            const orphans = later.filter((r) => r.kind === "generation_complete" && !released.has(r.genId));
+            if (orphans.length > 0) {
+                blocked(`retract: ${String(orphans.length)} generation(s) were seeded from this incumbent after the promote — retracting would orphan them`, "let them conclude and tombstone the culled ones first, then re-run this retract");
+            }
+            const to = promoteRow.data.to;
+            if (typeof to !== "string" || !/^[0-9a-f]{40}$/.test(to)) {
+                cannotAnswer(`retract: promote row for '${req.genId}' lacks a full commit sha — ledger inconsistent, refusing`);
+            }
+            const busy = await incumbentCheckouts(repo, opts);
+            if (busy.length > 0) {
+                blocked(`retract: ${INCUMBENT_BRANCH} is checked out in ${busy.join(", ")} — retract needs it idle`, "switch that worktree to another branch first; if the listing is stale, run `git worktree prune` in the genome repo");
+            }
+            // for-each-ref: ok+empty = genuinely absent; ok+sha = present; !ok = git
+            // itself failed (corruption/lock) — never launder a git failure into "absent"
+            const ref = await tryGit(["for-each-ref", "--format=%(objectname)", `refs/heads/${INCUMBENT_BRANCH}`], gopts);
+            if (!ref.ok) {
+                cannotAnswer(`retract: cannot read ${INCUMBENT_BRANCH} in ${repo}: ${ref.error.kind} — nothing was touched`);
+            }
+            let refState;
+            let removedSha = null;
+            const current = ref.stdout.trim();
+            if (current !== "") {
+                if (current !== to) {
+                    blocked(`retract: ${INCUMBENT_BRANCH} now points at ${current.slice(0, 12)} but the promote row recorded ${to.slice(0, 12)} — state diverged, refusing`, "investigate with `git -C <repo> log abathur/incumbent` and the ledger before any manual surgery");
+                }
+                // compare-and-delete: the old value pins what we verified, so a ref moved
+                // between the check and the delete makes git refuse instead of clobbering
+                const del = await tryGit(["update-ref", "-d", `refs/heads/${INCUMBENT_BRANCH}`, current], gopts);
+                if (!del.ok) {
+                    blocked(`retract: ${INCUMBENT_BRANCH} moved between verification and deletion — refusing rather than deleting an unverified ref`, "re-run the retract; if it keeps failing, inspect the ref with git directly");
+                }
+                removedSha = current;
+                refState = "deleted";
+            }
+            else {
+                // Manual-rollback path (documented 2026-09-28): recordable ONLY when this
+                // gen is the sole live promote — otherwise the absent ref means a
+                // divergence retract must not launder into an official-looking row.
+                if (livePromotes.length !== 1) {
+                    blocked(`retract: ${INCUMBENT_BRANCH} is absent but ${String(livePromotes.length)} live promotes exist — cannot verify what the retract undoes`, "restore the ref to the promoted commit (or resolve the divergence) before retracting");
+                }
+                refState = "absent";
+            }
+            const manifestFile = manifestPathFor(req.configDir, req.entry.fingerprint);
+            const manifestBefore = existsSync(manifestFile);
+            rmSync(manifestFile, { force: true });
+            const manifestGone = !existsSync(manifestFile);
+            // verbatim in the ledger (JSON-escaped on disk); printable-ASCII echo only
+            ledger.append({
+                kind: LEDGER_KIND_RETRACT,
+                genId: req.genId,
+                data: { actor: "cli", genId: req.genId, reason: req.reason, retractedTo: to, refState },
+            });
+            const flat = req.reason.replace(/[^ -~]/g, " ").replace(/\s+/g, " ").trim();
+            const echoReason = flat.length > 120 ? `${flat.slice(0, 120)}…` : flat;
+            const lines = [
+                `retract recorded: '${req.genId}' (reason: ${echoReason})`,
+                removedSha === null
+                    ? `${INCUMBENT_BRANCH} was already absent (manual rollback) — recorded with refState=absent`
+                    : `${INCUMBENT_BRANCH} removed (was ${removedSha.slice(0, 12)}) — genome returns to incumbent: none`,
+                manifestBefore && manifestGone
+                    ? `kernel manifest cleared: ${manifestFile}`
+                    : !manifestBefore && manifestGone
+                        ? `kernel manifest already absent: ${manifestFile}`
+                        : `kernel manifest REMOVAL UNVERIFIED: ${manifestFile} still exists — investigate`,
+                `the promote row remains in the append-only ledger; candidate commit ${to.slice(0, 12)} preserved (retract ≠ delete)`,
+            ];
+            return { genId: req.genId, lines };
+        }
+        finally {
+            repoLease.release();
+        }
+    }
+    finally {
+        lease.release();
+    }
+}

package/dist/core/stats-math.js

@@ -74,6 +74,45 @@ function betai(a, b, x) {
         return (front * betacf(a, b, x)) / a;
     return 1 - (front * betacf(b, a, 1 - x)) / b;
 }
+/**
+ * Standard normal CDF Φ(x): Abramowitz-Stegun 7.1.26 erf approximation,
+ * |error| < 1.5e-7 — far tighter than the 4-decimal P values the acceptance
+ * gate reports. ±∞ map to 1/0; NaN maps to NaN (callers branch on se===0
+ * before dividing, so 0/0 NaN never reaches here by design).
+ */
+export function normalCdf(x) {
+    if (Number.isNaN(x))
+        return Number.NaN;
+    if (x === Number.POSITIVE_INFINITY)
+        return 1;
+    if (x === Number.NEGATIVE_INFINITY)
+        return 0;
+    const z = Math.abs(x) / Math.SQRT2;
+    const t = 1 / (1 + 0.3275911 * z);
+    const poly = t * (0.254829592 + t * (-0.284496736 + t * (1.421413741 + t * (-1.453152027 + t * 1.061405429))));
+    const erf = 1 - poly * Math.exp(-z * z);
+    return 0.5 * (1 + (x < 0 ? -erf : erf));
+}
+/**
+ * Inverse standard normal Φ⁻¹(p), bisection against normalCdf above — the two
+ * are mutually consistent by construction (a band built from normalQuantile(q)
+ * and tested through normalCdf lands exactly at probability q). Same shape as
+ * studentTQuantile's bisection; |error| < 1e-13.
+ */
+export function normalQuantile(p) {
+    if (!(p > 0 && p < 1))
+        throw new RangeError(`normalQuantile: p=${String(p)} must be in (0, 1)`);
+    let lo = -40;
+    let hi = 40;
+    for (let i = 0; i < 80; i += 1) {
+        const mid = (lo + hi) / 2;
+        if (normalCdf(mid) < p)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return (lo + hi) / 2;
+}
 /**
  * Two-sided Student-t critical value: the t such that P(|T| ≤ t) = 1 − alpha
  * with T ~ t(df). Planned accuracy: matches t-table values to < 1e-3 for the