@tachikomagundam/abathur 0.2.6 → 0.2.8

package/README.md

@@ -30,7 +30,7 @@ instance learn from another's evidence; nothing in v1 talks to a network.
   `peerClaim` metadata and never feed nomination math.
 - **run loop** — incumbent → brief (failure observations) → mutator session →
   candidate diffs → seal → re-bench → verdicts. Nominated generations sit in
-  the quarantine queue until a human runs `promote`; `tombstone` buries them.
+  the quarantine queue until a human runs `promote`; `tombstone` buries them; `retract` undoes a promote (LIFO, descendant-guarded).
   Both are append-only ledger decisions; nothing is ever deleted.
 
 ### Install
@@ -289,7 +289,7 @@ table are [docs/federation.md](docs/federation.md).
   same historian genome against one wiki will clobber each other mid-run.
   Cross-machine serialization of historian benches is the operator's
   responsibility (schedule, lockbox, one-wiki-one-bench rule — your call).
-- Promotion and burial are yours alone: `promote`/`tombstone` carry no
+- Promotion, burial and retraction are yours alone: `promote`/`tombstone`/`retract` carry no
   `--confirm` because the CLI invocation **is** the gate; there is no
   `--force` anywhere in the binary. Review `abathur status` quarantine depth
   and the `graft decisions` rows before promoting.
@@ -476,7 +476,7 @@ opencode 会在启动时自行从 npm 把包下载到它自己的缓存
   `self-eval`、`kernel`、`--help`），120 秒超时、64 KB 输出封顶。二进制从
   `PATH` 解析，除非用 `ABATHUR_BIN` 覆盖。诚实的权限说明：该工具具备与
   bash 等同的权限——`run` 与 `genome` 按设计就会 spawn 变异器/引擎二进制——
-  所以允许清单限制的是笔误与体验，而非能力。`promote` 与 `tombstone` 刻意
+  所以允许清单限制的是笔误与体验，而非能力。`promote`、`tombstone` 与 `retract` 刻意
   不可经由工具触达：它们是人类闸门，必须在终端里运行。
 - 用户命令 **`/abathur <参数…>`**——斜杠命令，指示智能体把参数
   翻译成工具调用并回报退出码。路线 A 由复制的 `commands/abathur.md`

package/dist/cli.js

@@ -12,10 +12,12 @@ import { graftCommand } from "./commands/graft.js";
 import { kernelCommand } from "./commands/kernel.js";
 import { opencodeCommand } from "./commands/opencode.js";
 import { promoteCommand } from "./commands/promote.js";
+import { readjudicateCommand } from "./commands/readjudicate.js";
 import { runCommand } from "./commands/run.js";
 import { selfEvalCommand } from "./commands/self-eval.js";
 import { statusCommand } from "./commands/status.js";
 import { tombstoneCommand } from "./commands/tombstone.js";
+import { retractCommand } from "./commands/retract.js";
 import { ConfigError, loadConfig } from "./config.js";
 import { EXIT_CANNOT_ANSWER, EXIT_OK, ExitSignal, cannotAnswer, renderExitSignal, } from "./exit.js";
 // Router order mirrors the plan; summaries appear verbatim in --help.
@@ -24,7 +26,9 @@ export const COMMANDS = [
     runCommand,
     statusCommand,
     promoteCommand,
+    readjudicateCommand,
     tombstoneCommand,
+    retractCommand,
     bundleCommand,
     graftCommand,
     selfEvalCommand,

package/dist/commands/readjudicate.js

@@ -0,0 +1,28 @@
+// `abathur re-adjudicate <label> <genId>` — replay the CURRENT gate over an epoch's
+// archived rows and append a corrected verdict row (with provenance). Re-judges, never
+// flips by hand; promote continues to read the LAST row. See core/readjudicate.ts for
+// the replay contract (counters minus own slot, bank excludes this candidate's trees).
+import { resolveConfigDir } from "../config.js";
+import { EXIT_OK, EXIT_CANNOT_ANSWER, cannotAnswer } from "../exit.js";
+import { readjudicateGeneration } from "../core/readjudicate.js";
+import { writeStdout } from "../out.js";
+import { resolveUniqueEntry } from "./run.js";
+const USAGE = "usage: abathur re-adjudicate <label> <genId>";
+function runReadjudicate(args) {
+    const [label, genId] = args;
+    if (label === undefined || genId === undefined || args.length !== 2)
+        cannotAnswer(`re-adjudicate: expected exactly <label> <genId>`, USAGE);
+    const configDir = resolveConfigDir();
+    const entry = resolveUniqueEntry(configDir, label, "re-adjudicate");
+    const outcome = readjudicateGeneration({ entry, configDir, genId, now: () => new Date() });
+    for (const line of outcome.lines)
+        writeStdout(line);
+    // an inconclusive replay means the gate cannot answer — surface it in the exit code,
+    // matching the VERDICT_EXIT semantics of run/promote consumers.
+    return outcome.verdict === "inconclusive" ? EXIT_CANNOT_ANSWER : EXIT_OK;
+}
+export const readjudicateCommand = {
+    name: "re-adjudicate",
+    summary: "replay the current gate over a gen's archived rows; append corrected verdict + provenance (files stay immutable)",
+    run: ({ args }) => Promise.resolve(runReadjudicate(args)),
+};

package/dist/commands/retract.js

@@ -0,0 +1,53 @@
+// `abathur retract <label> <genId> --reason <text>` — the human gate that
+// undoes a promote (core in core/retract.ts, imported ONLY here — the
+// import-policy pin lives in src/test/promote.test.ts). Terminal-only like
+// promote/tombstone: the opencode plugin tool must never reach it. No --force:
+// every refusal is a bug report, not a flag.
+import { resolveConfigDir } from "../config.js";
+import { EXIT_OK, cannotAnswer } from "../exit.js";
+import { retractGeneration } from "../core/retract.js";
+import { writeStdout } from "../out.js";
+import { resolveUniqueEntry } from "./run.js";
+const USAGE = "usage: abathur retract <label> <genId> --reason <text>";
+const MAX_REASON_CHARS = 500;
+async function runRetract(args) {
+    const positional = [];
+    let reason = null;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--reason") {
+            const value = args[(i += 1)];
+            if (value === undefined || value.startsWith("--"))
+                cannotAnswer("retract: --reason requires a value", USAGE);
+            if (reason !== null)
+                cannotAnswer("retract: --reason given twice", USAGE);
+            reason = value;
+        }
+        else if (arg.startsWith("--")) {
+            cannotAnswer(`retract: unknown flag ${arg}`, USAGE);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    const [label, genId] = positional;
+    if (label === undefined || genId === undefined || positional.length !== 2) {
+        cannotAnswer("retract: expected exactly <label> <genId> --reason <text>", USAGE);
+    }
+    if (reason === null || reason.trim().length === 0) {
+        cannotAnswer("retract: --reason <text> is required (why is this promote being undone?)", USAGE);
+    }
+    if (reason.length > MAX_REASON_CHARS)
+        cannotAnswer(`retract: --reason exceeds ${String(MAX_REASON_CHARS)} chars`, USAGE);
+    const configDir = resolveConfigDir();
+    const entry = resolveUniqueEntry(configDir, label, "retract");
+    const outcome = await retractGeneration({ entry, configDir, genId, reason });
+    for (const line of outcome.lines)
+        writeStdout(line);
+    return EXIT_OK;
+}
+export const retractCommand = {
+    name: "retract",
+    summary: "human gate: undo a promote (LIFO, descendant-guarded; append-only row, ref deleted, manifest cleared)",
+    run: ({ args }) => runRetract(args),
+};

package/dist/commands/tombstone.js

@@ -3,13 +3,13 @@
 // row survive; the reason is stored verbatim (canonicalJson escapes control
 // bytes) but NEVER echoed raw — the confirmation line is sanitized like todo-8's
 // sealMessage so untrusted text cannot forge terminal output.
-import { Ledger } from "../core/ledger.js";
+import path from "node:path";
+import { acquireGenomeLock, acquireLock, LEDGER_KIND_TOMBSTONE, Ledger } from "../core/ledger.js";
 import { effectiveRepoPath } from "../core/spec.js";
 import { resolveConfigDir } from "../config.js";
 import { EXIT_OK, blocked, cannotAnswer } from "../exit.js";
 import { writeStdout } from "../out.js";
 import { resolveUniqueEntry } from "./run.js";
-const LEDGER_KIND_TOMBSTONE = "tombstone";
 const MAX_REASON_CHARS = 4000;
 const USAGE = "usage: abathur tombstone <label> <genId> --reason <text>";
 function echoed(reason) {
@@ -50,21 +50,34 @@ function runTombstone(args) {
     const configDir = resolveConfigDir();
     const entry = resolveUniqueEntry(configDir, label, "tombstone");
     const ledger = Ledger.open(effectiveRepoPath(entry.spec.repoPath));
-    const records = ledger.readAll();
-    if (!records.some((r) => r.kind === "generation_complete" && r.genId === genId)) {
-        blocked(`tombstone: no generation_complete ledger row for gen '${genId}' of '${label}' — nothing to bury`);
-    }
-    const promoted = records.find((r) => r.kind === "promote" && r.genId === genId);
-    if (promoted !== undefined) {
-        blocked(`tombstone: gen '${genId}' was already promoted at ${promoted.ts} — cull is for candidates the human never accepted`);
+    // single-flight with the run loop and sibling gates (same postmortem as promote)
+    const lease = acquireGenomeLock({ ledger, configDir, genomeFp: entry.fingerprint });
+    try {
+        const repoLease = acquireLock({ configDir: path.join(effectiveRepoPath(entry.spec.repoPath), ".state", "abathur"), key: "gate", label: "gate lock" });
+        try {
+            const records = ledger.readAll();
+            if (!records.some((r) => r.kind === "generation_complete" && r.genId === genId)) {
+                blocked(`tombstone: no generation_complete ledger row for gen '${genId}' of '${label}' — nothing to bury`);
+            }
+            const promoted = records.find((r) => r.kind === "promote" && r.genId === genId);
+            if (promoted !== undefined) {
+                blocked(`tombstone: gen '${genId}' was already promoted at ${promoted.ts} — cull is for candidates the human never accepted`);
+            }
+            const buried = records.find((r) => r.kind === LEDGER_KIND_TOMBSTONE && r.genId === genId);
+            if (buried !== undefined) {
+                blocked(`tombstone: gen '${genId}' is already tombstoned at ${buried.ts}`);
+            }
+            ledger.append({ kind: LEDGER_KIND_TOMBSTONE, genId, data: { genId, reason, actor: "cli" } });
+            writeStdout(`tombstone recorded: '${genId}' (reason: ${echoed(reason)}) — commits and lineage preserved (cull ≠ delete)`);
+            return EXIT_OK;
+        }
+        finally {
+            repoLease.release();
+        }
     }
-    const buried = records.find((r) => r.kind === LEDGER_KIND_TOMBSTONE && r.genId === genId);
-    if (buried !== undefined) {
-        blocked(`tombstone: gen '${genId}' is already tombstoned at ${buried.ts}`);
+    finally {
+        lease.release();
     }
-    ledger.append({ kind: LEDGER_KIND_TOMBSTONE, genId, data: { genId, reason, actor: "cli" } });
-    writeStdout(`tombstone recorded: '${genId}' (reason: ${echoed(reason)}) — commits and lineage preserved (cull ≠ delete)`);
-    return EXIT_OK;
 }
 export const tombstoneCommand = {
     name: "tombstone",

package/dist/core/evolve/run-bench.js

@@ -138,7 +138,13 @@ export async function benchTarget(o) {
                     continue;
                 }
                 const score = await bundle.adapter.score(unit);
-                if (score.kind === "scored") {
+                if (score.kind === "scored" && !Number.isFinite(score.result.score)) {
+                    // r21 injury ticket: a NaN/Inf score is a BROKEN RULER, not a number —
+                    // it must never become a replicate (vacuous aggregates minted bogus
+                    // nominations: stats saw finite-looking rows and judged on nothing).
+                    row.failures.push(`${unit.id} rep ${String(rep)}: grader score not finite (${String(score.result.score)}) — ruler failure, never counts as evidence`);
+                }
+                else if (score.kind === "scored") {
                     row.scores.push(score.result.score);
                     row.runIds.push(runId(o.genId, unit.id, rep));
                     if (!score.result.pass) {

package/dist/core/evolve/run-rows.js

@@ -49,6 +49,20 @@ export const generationRowDataSchema = z
     gateFailures: z.array(z.string()).optional(),
     /** Unrelated worktree dirtiness notices (todo 3 contract: todo 9 books them). */
     dirtyWorktree: z.array(z.strictObject({ xy: z.string(), file: z.string() })).optional(),
+    /** Present only on rows appended by `abathur re-adjudicate`: the corrected verdict with
+     *  full replay provenance (source rows, bank state, replaced verdict). The original row
+     *  stays in the files untouched — this field documents the amendment, never hides it. */
+    readjudication: z.strictObject({
+        at: z.string().min(1),
+        specFingerprint: z.string().min(1),
+        gate: z.enum(["legacy", "acceptance"]),
+        bank: z.strictObject({ units: z.number().int().nonnegative(), priorSigma: z.number(), pooledDf: z.number() }).nullable(),
+        sourceRows: z.strictObject({
+            candidate: z.strictObject({ file: z.string().min(1), ts: z.string().min(1) }),
+            incumbent: z.strictObject({ file: z.string().min(1), ts: z.string().min(1) }),
+        }),
+        replacedVerdict: z.string().min(1),
+    }).optional(),
     benchProvenance: z.strictObject({
         benchType: z.enum(["toy", "opencode-fixture-scenarios"]),
         versions: z.array(z.strictObject({ bin: z.string().min(1), version: z.string() })),

package/dist/core/ledger.js

@@ -14,6 +14,8 @@ import { acquireLock } from "./locks.js";
 export { acquireLock, lockDirFor } from "./locks.js";
 export const LEDGER_KIND_LOCK_TAKEOVER = "lock_takeover";
 export const LEDGER_KIND_GENERATION_COMPLETE = "generation_complete";
+export const LEDGER_KIND_PROMOTE = "promote";
+export const LEDGER_KIND_TOMBSTONE = "tombstone";
 export const ledgerRecordSchema = z.strictObject({
     v: z.literal(1),
     ts: z.string().min(1),

package/dist/core/promote.js

@@ -11,12 +11,12 @@ 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();
@@ -70,51 +70,66 @@ export async function promoteGeneration(req) {
     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) };
+}