@tachikomagundam/abathur 0.2.6 → 0.2.7

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/worktree.js

@@ -23,7 +23,7 @@ export { snapshotCommit } from "./snapshot.js";
 export { INCUMBENT_BRANCH, fastForwardIncumbent } from "./incumbent.js";
 const DAY_MS = 86_400_000;
 /** Fixed committer identity for sealed generations (repo config is never trusted or touched). */
-const SEAL_IDENTITY = ["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local"];
+const SEAL_IDENTITY = ["-c", "user.name=abathur", "-c", "user.email=agent@host.example"];
 // ------------------------------------------------------------------ openGenome
 /** Porcelain v1 with -z: "XY path" records; rename/copy records carry the source as an extra NUL field. */
 function parsePorcelain(raw) {

package/dist/genomes/toy-smoke/init.mjs

@@ -47,7 +47,7 @@ if (!existsSync(path.join(dest, ".git"))) {
   git(["add", "-A"]);
   // identity pinned via -c BEFORE the subcommand (global gitconfig immune;
   // `git init` itself rejects -c after the subcommand — learnings todo 3).
-  git(["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "commit", "-m", "toy-smoke fixture seed"]);
+  git(["-c", "user.name=abathur", "-c", "user.email=agent@host.example", "commit", "-m", "toy-smoke fixture seed"]);
 }
 
 process.stdout.write(`${dest}\n`);

package/dist/test/bundle.test.js

@@ -81,7 +81,7 @@ async function bundleFixture(t, opts = {}) {
         writeFileSync(path.join(repo, "genome.jsonc"), `${JSON.stringify({ ...spec, bundle: { maskLiterals: [...opts.maskLiterals] } }, null, 2)}\n`, "utf8");
         // commit the edit: export self-describes from the gen COMMIT tree, so the
         // registry spec and the committed spec must agree by construction.
-        gitC(repo, "-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "commit", "-am", "bundle: declare maskLiterals");
+        gitC(repo, "-c", "user.name=abathur", "-c", "user.email=agent@host.example", "commit", "-am", "bundle: declare maskLiterals");
     }
     registerGenome(configDir, path.join(repo, "genome.jsonc"));
     const entry = requireGenomesByLabel(configDir, "toy-smoke").entries[0];

package/dist/test/fixture-loop.test.js

@@ -149,7 +149,7 @@ async function fixtureLoop(t) {
     git(repo, ["init", "-b", "main"]);
     git(repo, ["add", "-A"]);
     // identity pinned via -c BEFORE the subcommand (toy init.mjs convention)
-    git(repo, ["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "commit", "-m", "fixloop seed"]);
+    git(repo, ["-c", "user.name=abathur", "-c", "user.email=agent@host.example", "commit", "-m", "fixloop seed"]);
     registerGenome(configDir, specPath);
     const entry = requireGenomesByLabel(configDir, "fixloop-germ").entries[0];
     if (entry === undefined)

package/dist/test/fixtures-self.js

@@ -42,7 +42,7 @@ test("self-sanity: stub mutators deterministic", () => {
 });
 `;
 function git(cwd, ...args) {
-    return execFileSync("git", ["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "-C", cwd, ...args], {
+    return execFileSync("git", ["-c", "user.name=abathur", "-c", "user.email=agent@host.example", "-C", cwd, ...args], {
         encoding: "utf8",
         env: { ...process.env, LC_ALL: "C" },
     }).trim();

package/dist/test/fixtures-wt.js

@@ -13,7 +13,7 @@ export const GIT_ID = [
     "-c",
     "user.name=abathur-test",
     "-c",
-    "user.email=test@abathur.local",
+    "user.email=ci@host.example",
     "-c",
     "commit.gpgsign=false",
 ];

package/dist/test/friction.test.js

@@ -250,7 +250,7 @@ test("AC-2: canary planted in the val unit NEVER appears in the friction queue",
     assert.deepEqual(val, { count: 1, aliases: ["val-1"], samples: 4 }, "scrubbed val material is present as counts/aliases");
 });
 function gitIn(repo, ...args) {
-    execFileSync("git", ["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "-C", repo, ...args], { stdio: "pipe" });
+    execFileSync("git", ["-c", "user.name=abathur", "-c", "user.email=agent@host.example", "-C", repo, ...args], { stdio: "pipe" });
 }
 test("friction: run CLI on drifted kernel records cause cli-error (spawned exit 1)", (t) => {
     const root = mkdtempSync(path.join(os.tmpdir(), "abathur-drift-"));
@@ -264,8 +264,8 @@ test("friction: run CLI on drifted kernel records cause cli-error (spawned exit
     touchSeal(repo, ["units/add.mjs", "units/mul.mjs", "units/explode.mjs", "units/sub.mjs", "grader.mjs"]);
     writeFileSync(path.join(repo, "genome.jsonc"), toySpec(repo), "utf8");
     execFileSync("git", ["init", "-b", "main", repo], { stdio: "pipe" });
-    execFileSync("git", ["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "-C", repo, "add", "-A"], { stdio: "pipe" });
-    execFileSync("git", ["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "-C", repo, "commit", "-m", "genome"], { stdio: "pipe" });
+    execFileSync("git", ["-c", "user.name=abathur", "-c", "user.email=agent@host.example", "-C", repo, "add", "-A"], { stdio: "pipe" });
+    execFileSync("git", ["-c", "user.name=abathur", "-c", "user.email=agent@host.example", "-C", repo, "commit", "-m", "genome"], { stdio: "pipe" });
     registerGenome(configDir, path.join(repo, "genome.jsonc"));
     // drift the sealed grader AFTER registration:
     writeFileSync(path.join(repo, "grader.mjs"), "// tampered\n", "utf8");

package/dist/test/graft.test.js

@@ -96,7 +96,7 @@ async function makeInstance(s, name, opts = {}) {
             ...(opts.requires === undefined ? {} : { requires: opts.requires }),
         };
         writeFileSync(path.join(repo, "genome.jsonc"), `${JSON.stringify(edited, null, 2)}\n`, "utf8");
-        gitC(repo, "-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "commit", "-am", "graft fixture: spec edit");
+        gitC(repo, "-c", "user.name=abathur", "-c", "user.email=agent@host.example", "commit", "-am", "graft fixture: spec edit");
     }
     registerGenome(configDir, path.join(repo, "genome.jsonc"));
     const entry = requireGenomesByLabel(configDir, "toy-smoke").entries[0];

package/dist/test/historian-run-scenario.test.js

@@ -188,12 +188,12 @@ test("model pin: ABATHUR_AGENT_MODEL set ⇒ argv carries --model <value>, brief
     const argvFile = path.join(path.dirname(h.promptFile), "argv-pinned.txt");
     await runScenario(h, {
         argvFile,
-        env: { ABATHUR_AGENT_MODEL: "test-provider/test-model" },
+        env: { ABATHUR_AGENT_MODEL: "fake-provider/fake-model" },
     });
     const tokens = argvTokens(argvFile);
     const i = tokens.indexOf("--model");
     assert.notEqual(i, -1, `--model missing from argv: ${JSON.stringify(tokens)}`);
-    assert.equal(tokens[i + 1], "test-provider/test-model");
+    assert.equal(tokens[i + 1], "fake-provider/fake-model");
     assert.equal(tokens.at(-2), "--message", "pin must not disturb the brief channel");
     assert.equal(prompt(h), BRIEF_TEXT);
 });

package/dist/test/promote.test.js

@@ -11,13 +11,13 @@
 // real seals via todo-3 worktree APIs, commands driven through the real CLI.
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from "node:fs";
 import { mkdtemp } from "node:fs/promises";
 import * as os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import test, {} from "node:test";
-import { Ledger } from "../core/ledger.js";
+import { acquireGenomeLock, acquireLock, Ledger } from "../core/ledger.js";
 import { fingerprint, genId } from "../core/ids.js";
 import { newGeneration, openGenome, sealGeneration } from "../core/worktree.js";
 import { manifestPathFor, readManifestFile } from "../core/kernel.js";
@@ -315,6 +315,196 @@ test("tombstone fail-closed + prompt_injection hygiene", async (t) => {
     const tombPromoted = cli(f, "tombstone", "toy-smoke", promoted.genId, "--reason", "too late");
     assert.equal(tombPromoted.status, 1, "promoted gens cannot be tombstoned");
 });
+// -------------------------------------------------------------------- retract
+test("AC(r1): retract undoes a fresh promote — ref deleted, manifest cleared, ledger append-only", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "retract-happy", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    assert.equal(incumbentSha(f), gen.commitSha);
+    const manifestFile = manifestPathFor(f.configDir, f.entry.fingerprint);
+    assert.ok(existsSync(manifestFile), "manifest exists after promote");
+    const before = readFileSync(path.join(f.repo, ".state", "abathur", "ledger.jsonl"), "utf8");
+    const run = cli(f, "retract", "toy-smoke", gen.genId, "--reason", "zero-gain change, human-ordered rollback");
+    assert.equal(run.status, 0, `retract: ${run.stderr}`);
+    assert.equal(incumbentSha(f), null, "incumbent ref deleted");
+    assert.ok(!existsSync(manifestFile), "kernel manifest cleared");
+    const retractRows = rowsOfKind(f, "retract");
+    assert.equal(retractRows.length, 1);
+    const data = retractRows[0]?.data;
+    assert.equal(data.genId, gen.genId);
+    assert.equal(data.retractedTo, gen.commitSha);
+    assert.equal(data.reason, "zero-gain change, human-ordered rollback");
+    assert.equal(rowsOfKind(f, "promote").length, 1, "promote row remains (history never rewritten)");
+    const after = readFileSync(path.join(f.repo, ".state", "abathur", "ledger.jsonl"), "utf8");
+    assert.ok(after.startsWith(before), "ledger stays append-only");
+    const cat = spawnSync("git", ["-C", f.repo, "cat-file", "-e", `${gen.commitSha}^{commit}`], { encoding: "utf8" });
+    assert.equal(cat.status, 0, "candidate commit preserved (retract ≠ delete)");
+    const st = cli(f, "status", "toy-smoke");
+    assert.equal(st.status, 0);
+    assert.match(st.stdout, /incumbent: none/);
+    assert.match(st.stdout, /ref is missing/, "status honestly warns about the retracted target");
+});
+test("retract fail-closed: missing reason, unknown gen, never-promoted, double retract", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "retract-guards", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "retract", "toy-smoke", gen.genId).status, 2, "--reason is required");
+    assert.equal(cli(f, "retract", "toy-smoke", "g-nope", "--reason", "x").status, 1);
+    const neverPromoted = cli(f, "retract", "toy-smoke", gen.genId, "--reason", "not promoted yet");
+    assert.equal(neverPromoted.status, 1);
+    assert.match(neverPromoted.stderr + neverPromoted.stdout, /no promote ledger row/);
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    assert.equal(cli(f, "retract", "toy-smoke", gen.genId, "--reason", "undo").status, 0);
+    const twice = cli(f, "retract", "toy-smoke", gen.genId, "--reason", "again");
+    assert.equal(twice.status, 1);
+    assert.match(twice.stderr + twice.stdout, /already retracted/);
+});
+test("retract LIFO + descendant guard: live descendant blocks, released descendant frees", async (t) => {
+    const f = await gateFixture(t);
+    const genA = await handSeal(f, "retract-A", { file: "units/mul.mjs", append: "\n// A\n" }, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", genA.genId).status, 0);
+    // handSeal forks from the repo HEAD, so fast-forward main onto the new
+    // incumbent first — the child must be a descendant of A or its own promote
+    // would hit the not-an-ancestor stale_state guard.
+    git(f, "merge", "--ff-only", "-q", genA.commitSha);
+    const genChild = await handSeal(f, "retract-child", { file: "units/add.mjs", append: "\n// child\n" }, "nominated");
+    const blockedByChild = cli(f, "retract", "toy-smoke", genA.genId, "--reason", "too late");
+    assert.equal(blockedByChild.status, 1);
+    assert.match(blockedByChild.stderr + blockedByChild.stdout, /orphan/);
+    assert.equal(incumbentSha(f), genA.commitSha, "refusal leaves the ref where it was");
+    assert.equal(cli(f, "promote", "toy-smoke", genChild.genId).status, 0);
+    const lifo = cli(f, "retract", "toy-smoke", genA.genId, "--reason", "out of order");
+    assert.equal(lifo.status, 1);
+    assert.match(lifo.stderr + lifo.stdout, /LIFO/);
+    assert.equal(cli(f, "retract", "toy-smoke", genChild.genId, "--reason", "child first").status, 0);
+    assert.equal(incumbentSha(f), null);
+    // child retracted ⇒ its lineage released ⇒ A retracts without a tombstone
+    assert.equal(cli(f, "retract", "toy-smoke", genA.genId, "--reason", "now clear").status, 0);
+    assert.equal(incumbentSha(f), null);
+});
+test("retract ref-absent: sole live promote records refState=absent; two live promotes refuse", async (t) => {
+    const f = await gateFixture(t);
+    const genA = await handSeal(f, "absent-A", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", genA.genId).status, 0);
+    // documented manual-rollback shape: ref deleted out-of-band, sole live promote
+    git(f, "update-ref", "-d", `refs/heads/${INCUMBENT_BRANCH}`);
+    const ok = cli(f, "retract", "toy-smoke", genA.genId, "--reason", "manual rollback already done");
+    assert.equal(ok.status, 0, `retract: ${ok.stderr}`);
+    const row = rowsOfKind(f, "retract")[0]?.data;
+    assert.equal(row.refState, "absent", "row honestly marks the ref was already gone");
+});
+test("retract ref-absent with two live promotes refuses (no laundering of divergence)", async (t) => {
+    const f = await gateFixture(t);
+    const genA = await handSeal(f, "absent2-A", { file: "units/mul.mjs", append: "\n// A\n" }, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", genA.genId).status, 0);
+    git(f, "merge", "--ff-only", "-q", genA.commitSha);
+    const genB = await handSeal(f, "absent2-B", { file: "units/add.mjs", append: "\n// B\n" }, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", genB.genId).status, 0);
+    git(f, "update-ref", "-d", `refs/heads/${INCUMBENT_BRANCH}`); // out-of-band divergence
+    const run = cli(f, "retract", "toy-smoke", genB.genId, "--reason", "try to launder");
+    assert.equal(run.status, 1);
+    assert.match(run.stderr + run.stdout, /cannot verify what the retract undoes/);
+    assert.equal(rowsOfKind(f, "retract").length, 0, "no row written on refusal");
+});
+test("retract refuses while a LINKED worktree has the incumbent branch checked out", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "retract-wt", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    const wt2 = path.join(f.root, "wt2");
+    git(f, "worktree", "add", "-q", wt2, INCUMBENT_BRANCH);
+    const run = cli(f, "retract", "toy-smoke", gen.genId, "--reason", "x");
+    assert.equal(run.status, 1);
+    assert.match(run.stderr + run.stdout, /checked out/);
+    assert.equal(incumbentSha(f), gen.commitSha, "ref untouched while a linked worktree holds the branch");
+});
+test("retract echo hygiene: control bytes never reach stdout or the ledger file", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "retract-evil", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    const evil = cli(f, "retract", "toy-smoke", gen.genId, "--reason", "evil\n\u001b[31mred\u001b[0m reason");
+    assert.equal(evil.status, 0, `evil reason: ${evil.stderr}`);
+    assert.ok(!evil.stdout.includes("\u001b"), "raw ANSI never reaches stdout");
+    const raw = readFileSync(path.join(f.repo, ".state", "abathur", "ledger.jsonl"), "utf8");
+    assert.ok(!raw.includes("\u001b"), "no raw ESC byte in ledger text");
+    const stored = rowsOfKind(f, "retract")[0]?.data;
+    assert.equal(stored.reason, "evil\n\u001b[31mred\u001b[0m reason", "ledger stores verbatim (JSON-escaped on disk)");
+});
+test("gate locks: a live genome-lock holder blocks promote with a named pid (exit 2)", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "lock-holder", CLEAN_MUTATION, "nominated");
+    const lease = acquireGenomeLock({ ledger: Ledger.open(f.repo), configDir: f.configDir, genomeFp: f.entry.fingerprint });
+    t.after(() => lease.release());
+    const run = cli(f, "promote", "toy-smoke", gen.genId);
+    assert.equal(run.status, 2, `promote while locked: ${run.stderr}`);
+    assert.match(run.stderr + run.stdout, /held by live pid/);
+    assert.equal(incumbentSha(f), null, "no ref movement while locked out");
+});
+test("gate locks: the repo-scoped gate lock contends across config homes", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "repo-lock", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    // a second config home registering the SAME repo (different genome lock, same gate lock)
+    const configDir2 = path.join(f.root, "config2");
+    mkdirSync(configDir2, { recursive: true });
+    writeFileSync(path.join(configDir2, "config.jsonc"), '{ "opencodeBin": null }\n', "utf8");
+    const doc = JSON.parse(readFileSync(path.join(f.repo, "genome.jsonc"), "utf8"));
+    doc["label"] = "toy-smoke";
+    const spec2 = path.join(f.root, "private2.jsonc");
+    writeFileSync(spec2, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+    registerGenome(configDir2, spec2);
+    const repoLease = acquireLock({ configDir: path.join(f.repo, ".state", "abathur"), key: "gate", label: "gate lock" });
+    t.after(() => repoLease.release());
+    const run = spawnSync(process.execPath, [CLI, "retract", "toy-smoke", gen.genId, "--reason", "x"], {
+        env: { ...process.env, ABATHUR_CONFIG: path.join(configDir2, "config.jsonc"), HOME: path.join(f.root, "home") },
+        encoding: "utf8",
+        cwd: f.root,
+    });
+    assert.equal(run.status, 2, `retract via second config while gate-locked: ${run.stderr}`);
+    assert.match(run.stderr + run.stdout, /gate lock 'gate' is held by live pid/);
+    assert.equal(incumbentSha(f), gen.commitSha, "ref untouched while gate-locked");
+    assert.equal(rowsOfKind(f, "retract").length, 0, "no row appended by the locked-out process");
+});
+test("retract refuses when the incumbent ref moved out-of-band after the promote", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "diverge", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    git(f, "update-ref", `refs/heads/${INCUMBENT_BRANCH}`, gen.parent); // rewind out-of-band
+    const run = cli(f, "retract", "toy-smoke", gen.genId, "--reason", "x");
+    assert.equal(run.status, 1);
+    assert.match(run.stderr + run.stdout, /state diverged/);
+    assert.equal(incumbentSha(f), gen.parent, "the moved ref is NOT deleted");
+});
+test("promote after retract refuses — a retracted gen stays dead (no re-promote lockup)", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "re-promote", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    assert.equal(cli(f, "retract", "toy-smoke", gen.genId, "--reason", "undo").status, 0);
+    const again = cli(f, "promote", "toy-smoke", gen.genId);
+    assert.equal(again.status, 1);
+    assert.match(again.stderr + again.stdout, /already promoted/);
+});
+test("retract: a PRUNABLE worktree (deleted directory) does not block the rollback valve", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "retract-prunable", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    const wt2 = path.join(f.root, "wt-stale");
+    git(f, "worktree", "add", "-q", wt2, INCUMBENT_BRANCH);
+    rmSync(wt2, { recursive: true, force: true }); // directory gone, metadata stale ⇒ porcelain marks it prunable
+    const list = spawnSync("git", ["-C", f.repo, "worktree", "list", "--porcelain"], { encoding: "utf8" });
+    assert.match(list.stdout, /prunable/, "fixture sanity: git itself marks the stale worktree prunable");
+    const run = cli(f, "retract", "toy-smoke", gen.genId, "--reason", "stale worktree must not block");
+    assert.equal(run.status, 0, `retract: ${run.stderr}`);
+    assert.equal(incumbentSha(f), null);
+});
+test("retract refuses while the incumbent branch is checked out", async (t) => {
+    const f = await gateFixture(t);
+    const gen = await handSeal(f, "retract-checkout", CLEAN_MUTATION, "nominated");
+    assert.equal(cli(f, "promote", "toy-smoke", gen.genId).status, 0);
+    git(f, "checkout", "-q", INCUMBENT_BRANCH);
+    const run = cli(f, "retract", "toy-smoke", gen.genId, "--reason", "x");
+    assert.equal(run.status, 1);
+    assert.match(run.stderr + run.stdout, /checked out/i);
+    assert.equal(incumbentSha(f), gen.commitSha, "ref untouched while checked out");
+});
 // -------------------------------------------------------------------- status
 test("AC(d): status renders incumbent, generations, quarantine depth, budget; never fabricates", async (t) => {
     const f = await gateFixture(t);
@@ -368,7 +558,7 @@ test("genome rm: ledgerless genomes unregister (manifest stays), ledger history
     assert.equal(empty.status, 0, "no ledger rows ⇒ still removable");
 });
 // -------------------------------------------------------------- structural
-test("structural: promote core is CLI-only; no auto-promote import path; no --force anywhere", () => {
+test("structural: promote/retract cores are CLI-only; no auto-gate import path; no --force anywhere", () => {
     const importers = [];
     const scan = (dir) => {
         for (const ent of readdirSync(dir, { withFileTypes: true })) {
@@ -386,9 +576,36 @@ test("structural: promote core is CLI-only; no auto-promote import path; no --fo
     scan(path.join(REPO_ROOT, "src"));
     const relative = importers.map((p) => path.relative(REPO_ROOT, p).split(path.sep).join("/")).sort();
     assert.deepEqual(relative, ["src/commands/promote.ts"], "core/promote imported ONLY by commands/promote");
+    const retractImporters = [];
+    const scanRetract = (dir) => {
+        for (const ent of readdirSync(dir, { withFileTypes: true })) {
+            const p = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                if (ent.name !== "node_modules")
+                    scanRetract(p);
+            }
+            else if (ent.name.endsWith(".ts")) {
+                const src = readFileSync(p, "utf8");
+                if (/(?:from\s+|import\(\s*)["'](?:[^"']*\/)?core\/retract\.js["']|from\s+["']\.\/retract\.js["']/.test(src))
+                    retractImporters.push(p);
+            }
+        }
+    };
+    scanRetract(path.join(REPO_ROOT, "src"));
+    const relRetract = retractImporters.map((p) => path.relative(REPO_ROOT, p).split(path.sep).join("/")).sort();
+    assert.deepEqual(relRetract, ["src/commands/retract.ts"], "core/retract imported ONLY by commands/retract");
     for (const rel of ["src/core/evolve/run-loop.ts", "src/core/evolve/reflect.ts", "src/core/evolve/candidate.ts"]) {
         assert.doesNotMatch(readFileSync(path.join(REPO_ROOT, rel), "utf8"), /from\s+"[^"]*promote\.js"/, `${rel} must not import promote`);
+        assert.doesNotMatch(readFileSync(path.join(REPO_ROOT, rel), "utf8"), /from\s+"[^"]*retract\.js"/, `${rel} must not import retract`);
+    }
+    for (const gateFile of ["src/core/promote.ts", "src/core/retract.ts"]) {
+        assert.doesNotMatch(readFileSync(path.join(REPO_ROOT, gateFile), "utf8"), /--force/, `no force flag in ${gateFile}`);
+    }
+    // the plugin tool allowlist must never grow a human gate (terminal-only class)
+    const pluginSrc = readFileSync(path.join(REPO_ROOT, "plugin", "abathur.ts"), "utf8");
+    const allowBlock = pluginSrc.match(/const ALLOWED_COMMANDS[\s\S]*?;/)?.[0] ?? "";
+    assert.ok(allowBlock.length > 0, "ALLOWED_COMMANDS block must be found — a vacuous match tests nothing");
+    for (const gate of ['"promote"', '"tombstone"', '"retract"']) {
+        assert.ok(!allowBlock.includes(gate), `${gate} must NOT be plugin-reachable`);
     }
-    const gate = readFileSync(path.join(REPO_ROOT, "src/core/promote.ts"), "utf8");
-    assert.doesNotMatch(gate, /--force/, "no force flag in the gate");
 });