@tachikomagundam/abathur 0.1.0

package/dist/core/graft-rebench.js

@@ -0,0 +1,187 @@
+// Graft re-bench (todo 13): the all-green path. Apply the bundle's contained
+// primary tree as byte-truth into a FRESH todo-3 worktree off the local
+// incumbent HEAD, seal with the harness-fixed identity, then run the LOCAL
+// bench at LOCAL reps/thresholds through the same adapter + bench-sandbox root
+// the run-loop uses (<configDir>/bench-sandboxes/<invId>/..., so todo-12
+// evidence export walks graft transcripts too). todo-7 stats decide; the
+// bundle's numbers never touch this file.
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { cannotAnswer } from "../exit.js";
+import { compactUtc, fingerprint, genId } from "./ids.js";
+import { LEDGER_KIND_GENERATION_COMPLETE } from "./ledger.js";
+import { newGeneration, openGenome, sealGeneration, snapshotCommit } from "./worktree.js";
+import { git, tryGit } from "../util/git.js";
+import { asReplicates, benchTarget, cloneMatrixRow, copyProvenance } from "./evolve/run-bench.js";
+import { addCounters, readResume } from "./evolve/run-rows.js";
+import { ChildTracker, reapOrphans } from "./evolve/child-track.js";
+import { clampReps, evaluate, VERDICT_EXIT } from "./stats.js";
+import { echo, sha12 } from "./graft-support.js";
+export async function graftAndBench(req, ctx) {
+    const { ledger, spec, manifest, tree, bundleSha256, now, env } = withClock(req, ctx);
+    const lines = [];
+    // reap only under the genome lock (todo-9 discipline): leftovers are dead-run children
+    reapOrphans(spec.repoPath);
+    const opened = await openGenome(spec.repoPath, [], { env });
+    if (opened.dirtyWorktree.length > 0) {
+        lines.push(`notice: ${String(opened.dirtyWorktree.length)} unrelated dirty path(s) in the genome repo — graft benches the SEALED bundle tree only`);
+    }
+    const genome = { repoPath: spec.repoPath, genomeFp: ctx.genomeFp };
+    const graftGenId = genId(fingerprint({ graft: bundleSha256, sourceGenome: manifest.genome.fingerprint, parent: opened.headCommit }), now());
+    const gen = await newGeneration(genome, opened.headCommit, graftGenId, { env });
+    await applyBundleTree(gen.worktreePath, tree);
+    const sealed = await sealGraftedTree(genome, graftGenId, gen.worktreePath, opened.headCommit, bundleSha256, env);
+    lines.push(`graft applied: bundle ${sha12(bundleSha256)} → fresh worktree ${graftGenId} (commit ${sealed.commitSha.slice(0, 12)}, tree ${sealed.treeSha.slice(0, 12)})`);
+    const reps = clampReps(undefined, spec.bench.stats.nReps); // LOCAL initial — bundle reps are peerClaim only
+    const caps = {
+        maxCandidates: spec.budget.maxCandidates,
+        maxModelCalls: spec.budget.maxModelCalls,
+        maxTokens: spec.budget.maxTokens,
+        maxWallS: spec.budget.maxWallS,
+    };
+    const resume = readResume(ledger);
+    const invId = `graft-${compactUtc(now())}-${bundleSha256.slice(0, 8)}`;
+    const sandboxBase = path.join(req.configDir, "bench-sandboxes", invId);
+    const tracker = new ChildTracker(spec.repoPath);
+    const configEnv = env;
+    let counters = resume.counters;
+    const storedInc = resume.incumbentByHead.get(opened.headCommit);
+    let incUnits;
+    if (storedInc !== undefined) {
+        incUnits = storedInc.units;
+        lines.push(`incumbent baseline @ ${opened.headCommit.slice(0, 12)} already benched — reusing ${String(incUnits.length)} unit rows`);
+    }
+    else {
+        // committed bytes of the incumbent HEAD, never the possibly-dirty worktree
+        const snap = await snapshotCommit(genome, opened.headCommit, { env });
+        const incGen = genId(fingerprint({ graftIncumbent: opened.headCommit, at: now().getTime() }), now());
+        const out = await benchTarget({
+            spec: { ...spec, repoPath: snap.snapshotPath },
+            genId: incGen,
+            reps,
+            caps,
+            countersBefore: counters,
+            sandboxRoot: path.join(sandboxBase, "incumbent"),
+            source: "incumbent",
+            tracker,
+            configDir: req.configDir,
+            env: configEnv,
+        });
+        counters = addCounters(counters, out.spent);
+        const data = {
+            source: "incumbent",
+            headCommit: opened.headCommit,
+            complete: out.complete,
+            reps,
+            units: out.units.map(cloneMatrixRow),
+            counters: out.spent,
+            manifest: out.manifest.map((m) => ({ glob: m.glob, path: m.path, sha256: m.sha256 })),
+            benchProvenance: copyProvenance(out.provenance),
+            ...(opened.dirtyWorktree.length === 0 ? {} : { dirtyWorktree: opened.dirtyWorktree.map((d) => ({ xy: d.xy, file: d.file })) }),
+        };
+        ledger.append({ kind: LEDGER_KIND_GENERATION_COMPLETE, genId: incGen, data });
+        incUnits = out.units;
+    }
+    const out = await benchTarget({
+        spec: { ...spec, repoPath: gen.worktreePath },
+        genId: graftGenId,
+        reps,
+        caps,
+        countersBefore: counters,
+        sandboxRoot: path.join(sandboxBase, graftGenId),
+        source: "candidate",
+        tracker,
+        configDir: req.configDir,
+        ...(configEnv === undefined ? {} : { env: configEnv }),
+    });
+    counters = addCounters(counters, out.spent);
+    // the candidate's own slot must not self-trip the cap inside evaluate (todo-9 rule)
+    const evalCounters = { ...counters, candidates: counters.candidates - out.spent.candidates };
+    const gate = evaluate({
+        candidate: { runId: invId, units: asReplicates(out.units), counters: evalCounters },
+        incumbent: { units: asReplicates(incUnits) },
+        stats: spec.bench.stats,
+        budgetCaps: caps,
+        nPairs: 1,
+    });
+    // EXACTLY ONE graft_import decision row lands BEFORE any further writes.
+    ctx.recordDecision(gate.verdict, localScoreReason(gate, manifest, reps), { graftGenId, ...sealed });
+    const data = {
+        source: "candidate",
+        candidateId: `graft-${bundleSha256.slice(0, 12)}`,
+        rationale: `graft of bundle ${sha12(bundleSha256)} from source genome ${manifest.genome.fingerprint.slice(0, 16)}… (peer claim: ${manifest.stats.verdict ?? "n/a"})`,
+        headCommit: opened.headCommit,
+        commitSha: sealed.commitSha,
+        treeSha: sealed.treeSha,
+        complete: out.complete,
+        reps,
+        units: out.units.map(cloneMatrixRow),
+        counters: out.spent,
+        manifest: out.manifest.map((m) => ({ glob: m.glob, path: m.path, sha256: m.sha256 })),
+        verdict: gate.verdict,
+        exitCode: gate.exitCode,
+        gain: Number.isFinite(gate.gain) ? gate.gain : null,
+        gateFailures: [...gate.failures],
+        benchProvenance: copyProvenance(out.provenance),
+    };
+    ledger.append({ kind: LEDGER_KIND_GENERATION_COMPLETE, genId: graftGenId, data });
+    await tracker.drain();
+    const gain = gate.gain === null ? "n/a (truncated)" : gate.gain.toFixed(4);
+    lines.push(`graft ${gate.verdict}: local score is authoritative (gain ${gain}, reps ${String(reps)}, LOCAL thresholds) — peer claimed ${manifest.stats.verdict ?? "n/a"} @ nRepeats ${String(manifest.benchProvenance.nRepeats ?? "?")}; imported:true + source ${manifest.genome.fingerprint.slice(0, 16)}… booked`);
+    for (const failure of gate.failures)
+        lines.push(`  gate: ${echo(failure)}`);
+    if (gate.verdict === "nominated") {
+        lines.push(`  human gate: 'abathur promote ${echo(req.genomeLabel, 80)} ${graftGenId}' — graft itself never promotes`);
+    }
+    return { exitCode: VERDICT_EXIT[gate.verdict], lines };
+}
+function localScoreReason(gate, manifest, reps) {
+    return `local re-bench: verdict ${gate.verdict}, gain ${gate.gain === null ? "n/a" : gate.gain.toFixed(4)}, reps ${String(reps)} (LOCAL spec) — peer claimed ${manifest.stats.verdict ?? "n/a"} @ nRepeats ${String(manifest.benchProvenance.nRepeats ?? "?")}`;
+}
+function withClock(req, ctx) {
+    return {
+        ...ctx,
+        now: req.now ?? (() => new Date()),
+        env: req.env ?? process.env,
+    };
+}
+/** Tree bytes are the byte-truth: overwrite every member, remove tracked files the bundle lacks. */
+async function applyBundleTree(worktreePath, tree) {
+    const wt = path.resolve(worktreePath);
+    const listed = await tryGit(["ls-tree", "-r", "--name-only", "-z", "HEAD"], { cwd: wt });
+    if (!listed.ok)
+        cannotAnswer(`graft: cannot list the incumbent tree in ${wt}: ${echo(listed.error.stderr, 160)}`);
+    for (const rel of listed.stdout.split("\0").filter((entry) => entry.length > 0)) {
+        if (!tree.has(rel))
+            rmSync(safeJoin(wt, rel), { force: true });
+    }
+    for (const [rel, content] of tree) {
+        const abs = safeJoin(wt, rel);
+        mkdirSync(path.dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+    }
+}
+/** readTar refused traversal/absolute names already; this is the write-side belt. */
+function safeJoin(root, rel) {
+    const bad = () => cannotAnswer(`graft: unsafe bundle member path '${echo(rel, 80)}'`);
+    if (rel.length === 0 || path.isAbsolute(rel) || rel.includes("\\") || rel.includes("\0"))
+        bad();
+    for (const segment of rel.split("/")) {
+        if (segment === ".." || segment === "")
+            bad();
+    }
+    const abs = path.resolve(root, rel);
+    if (!abs.startsWith(`${root}${path.sep}`) || abs === path.join(root, ".git"))
+        bad();
+    return abs;
+}
+async function sealGraftedTree(genome, graftGenId, worktreePath, headCommit, bundleSha256, env) {
+    const porcelain = await git(["status", "--porcelain", "--untracked-files=all"], { cwd: worktreePath });
+    if (porcelain.stdout.trim().length === 0) {
+        // bundle tree == incumbent HEAD content: the graft generation IS this commit
+        const tree = await git(["rev-parse", "HEAD^{tree}"], { cwd: worktreePath });
+        return { commitSha: headCommit, treeSha: tree.stdout.trim() };
+    }
+    // harness-authored message + fixed committer identity (todo-3 sealGeneration)
+    return sealGeneration(genome, graftGenId, `graft: import crystallization from bundle ${sha12(bundleSha256)} (see docs/federation.md)`, { env });
+}

package/dist/core/graft-support.js

@@ -0,0 +1,181 @@
+// Graft support (todo 13): the pending-bench queue file convention, the
+// `graft_import` ledger-row shape, and the echo sanitizer shared by `graft`
+// and `status`. Kept deliberately dependency-light (fs + text only, no git,
+// no bench, no ledger class) so `status` can render graft state WITHOUT ever
+// calling Ledger.open — the todo-10 rule: status side-effects must not poison
+// the genome-rm ledgerless check. The queue file IS the graft_import record
+// when no local repo exists to hold a ledger.
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { cannotAnswer } from "../exit.js";
+export const LEDGER_KIND_GRAFT_IMPORT = "graft_import";
+/** <configDir>/graft-queue/<bundle-sha256>.json — one explicit entry per
+ *  pending-bench bundle (plan todo 13: "explicit queue entry in status"). */
+export const GRAFT_QUEUE_DIRNAME = "graft-queue";
+const HEX64 = /^[0-9a-f]{64}$/;
+const DECISIONS = [
+    "quarantined",
+    "pending-bench",
+    "nominated",
+    "culled",
+    "indeterminate",
+    "inconclusive",
+];
+function asDecision(value) {
+    return DECISIONS.find((decision) => decision === value) ?? null;
+}
+/** A terminal decision blocks re-grafting the same bundle; pending does not
+ *  (the plan's eligible path is "register genome then re-run graft"). */
+export const isTerminalDecision = (decision) => decision !== "pending-bench";
+export function graftQueueDir(configDir) {
+    return path.join(configDir, GRAFT_QUEUE_DIRNAME);
+}
+export function graftQueuePath(configDir, bundleSha256) {
+    if (!HEX64.test(bundleSha256)) {
+        cannotAnswer(`graft: queue key '${bundleSha256}' is not a 64-char sha256 hex`);
+    }
+    return path.join(graftQueueDir(configDir), `${bundleSha256}.json`);
+}
+export function writeGraftQueueEntry(configDir, entry) {
+    const file = graftQueuePath(configDir, entry.bundleSha256);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(entry, null, 2)}\n`, "utf8");
+    return file;
+}
+/** Idempotent consume: the success-path decision retires the queue entry. */
+export function removeGraftQueueEntry(configDir, bundleSha256) {
+    rmSync(graftQueuePath(configDir, bundleSha256), { force: true });
+}
+function parseQueueFile(file, name) {
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (cause) {
+        return cannotAnswer(`graft queue: ${file} is not readable JSON — refusing to render a partial truth: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const raw = (typeof doc === "object" && doc !== null && !Array.isArray(doc) ? doc : undefined);
+    const bad = () => cannotAnswer(`graft queue: ${file} violates the queue-entry shape — fix or remove the file by hand`);
+    if (raw === undefined)
+        bad();
+    const body = raw;
+    const str = (key) => {
+        const value = body[key];
+        return typeof value === "string" && value.length > 0 ? value : bad();
+    };
+    const bundleSha256 = str("bundleSha256");
+    // the filename is the address: a foreign key inside is tampering, not data
+    if (!HEX64.test(bundleSha256) || `${bundleSha256}.json` !== name)
+        bad();
+    const fp = body.sourceGenomeFingerprint;
+    if (fp !== undefined && (typeof fp !== "string" || !HEX64.test(fp)))
+        bad();
+    return {
+        bundleSha256,
+        bundlePath: str("bundlePath"),
+        genomeLabel: str("genomeLabel"),
+        reason: str("reason"),
+        queuedAt: str("queuedAt"),
+        ...(typeof fp === "string" ? { sourceGenomeFingerprint: fp } : {}),
+    };
+}
+/** Sorted, fail-closed read of the whole queue (status + graft dedup view). */
+export function listGraftQueue(configDir) {
+    const dir = graftQueueDir(configDir);
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => n.endsWith(".json")).sort();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return []; // no queue yet = empty, not an error
+        throw error; // unreadable-but-present (EACCES/EIO) must never render as an empty queue
+    }
+    return names.map((name) => parseQueueFile(path.join(dir, name), name));
+}
+const asStr = (value) => (typeof value === "string" ? value : null);
+const asStrOrNull = (value) => value === null || typeof value === "string" ? value : undefined;
+/** Lenient read of a graft_import row (ledger data is record<string,unknown>). */
+export function decodeGraftImport(data) {
+    const decision = asDecision(data.decision);
+    if (decision === null)
+        return null;
+    const genomeLabel = asStr(data.genomeLabel);
+    const bundleSha256 = asStr(data.bundleSha256);
+    const reason = asStr(data.reason);
+    if (genomeLabel === null || bundleSha256 === null || reason === null)
+        return null;
+    if (data.imported !== true)
+        return null;
+    const sourceGenomeFingerprint = asStrOrNull(data.sourceGenomeFingerprint);
+    const sourceBenchDigest = asStrOrNull(data.sourceBenchDigest);
+    const graftGenId = asStrOrNull(data.graftGenId);
+    const commitSha = asStrOrNull(data.commitSha);
+    const treeSha = asStrOrNull(data.treeSha);
+    const bundlePath = asStr(data.bundlePath) ?? "";
+    if (sourceGenomeFingerprint === undefined || sourceBenchDigest === undefined)
+        return null;
+    if (graftGenId === undefined || commitSha === undefined || treeSha === undefined)
+        return null;
+    const rawClaim = data.peerClaim;
+    let peerClaim = null;
+    if (typeof rawClaim === "object" && rawClaim !== null && !Array.isArray(rawClaim)) {
+        const claim = rawClaim;
+        const verdict = asStrOrNull(claim.verdict);
+        const nRepeats = claim.nRepeats;
+        const opencodeVersion = asStrOrNull(claim.opencodeVersion);
+        const agentModel = asStrOrNull(claim.agentModel);
+        const judgeModel = asStrOrNull(claim.judgeModel);
+        const statsConfigDigest = asStrOrNull(claim.statsConfigDigest);
+        const rationale = asStr(claim.rationale);
+        if (verdict !== undefined &&
+            (nRepeats === null || (typeof nRepeats === "number" && Number.isInteger(nRepeats))) &&
+            opencodeVersion !== undefined &&
+            agentModel !== undefined &&
+            judgeModel !== undefined &&
+            statsConfigDigest !== undefined &&
+            rationale !== null) {
+            peerClaim = {
+                verdict,
+                nRepeats: typeof nRepeats === "number" ? nRepeats : null,
+                opencodeVersion,
+                agentModel,
+                judgeModel,
+                statsConfigDigest,
+                rationale,
+            };
+        }
+    }
+    return {
+        decision,
+        genomeLabel,
+        bundleSha256,
+        bundlePath,
+        sourceGenomeFingerprint,
+        sourceBenchDigest,
+        reason,
+        imported: true,
+        graftGenId,
+        commitSha,
+        treeSha,
+        peerClaim,
+    };
+}
+/** The quarantine/pending row's peerClaim projection of a bundle manifest. */
+export function peerClaimFromManifest(manifest) {
+    return {
+        verdict: manifest.stats.verdict,
+        nRepeats: manifest.benchProvenance.nRepeats,
+        opencodeVersion: manifest.benchProvenance.opencodeVersion,
+        agentModel: manifest.benchProvenance.agentModel,
+        judgeModel: manifest.benchProvenance.judgeModel,
+        statsConfigDigest: manifest.benchProvenance.statsConfigDigest,
+        rationale: manifest.rationale,
+    };
+}
+/** Single-line print sanitizer for untrusted echo content (todo-8 flat discipline). */
+export function echo(value, max = 140) {
+    const one = value.replace(/[^ -~]/g, " ").replace(/\s+/g, " ").trim();
+    return one.length > max ? `${one.slice(0, max)}…` : one;
+}
+export const sha12 = (sha) => (HEX64.test(sha) ? sha.slice(0, 12) : echo(sha, 12));

package/dist/core/graft.js

@@ -0,0 +1,218 @@
+// `graft` (plan todo 13): cross-instance crystallization merge with a LOCAL
+// re-bench. A lineage bundle is UNTRUSTED input — the bundle's scores, verdicts
+// and reps are recorded as `peerClaim` metadata and NEVER feed nomination math.
+// v1 trust model, byte-for-byte (docs/federation.md — todo 15):
+//
+//   inspect (todo 12) → genome-fingerprint gate → benchDigest gate →
+//   scoring-provenance gate → requires[] probes (todo 6) → fresh todo-3
+//   worktree from the LOCAL incumbent HEAD carrying the bundle's contained
+//   tree bytes → LOCAL bench at LOCAL reps/thresholds (NEVER the bundle's) →
+//   todo-7 stats decide: nominated (human promote gate only) or culled.
+//
+//   * integrity/provenance mismatch ⇒ quarantined — exactly one graft_import
+//     ledger row, NO worktree, NO bench; `status` lists it.
+//   * genome unregistered ⇒ pending-bench — explicit queue entry under
+//     <configDir>/graft-queue/, zero bench runs; the operator registers the
+//     genome and re-runs graft to resolve the entry. Probes failing is the
+//     same pending-bench shape (prerequisite repair, then re-run).
+//   * the same bundle + genome never grafts twice (terminal-row refusal).
+//
+// No noise-tolerance band: byte-equality is the rule. No --force, no
+// quarantine/pending-bench bypass, no merge of two incumbent branches, no
+// auto-promote (core/promote.js is never imported here). Single-shot by design
+// — graft is NOT a resumable run: the queue file + graft_import rows are the
+// durable state, and "resume" means re-running `abathur graft`.
+import path from "node:path";
+import { EXIT_BLOCKED, EXIT_CANNOT_ANSWER, ExitSignal } from "../exit.js";
+import { inspectBundle } from "./bundle-inspect.js";
+import { bundleGenIds, primaryGenId, sha256Hex, treeOf } from "./bundle-common.js";
+import { fingerprint16 } from "./genome.js";
+import { fingerprint } from "./ids.js";
+import { acquireGenomeLock, Ledger } from "./ledger.js";
+import { LEDGER_KIND_GRAFT_IMPORT, echo, peerClaimFromManifest, removeGraftQueueEntry, sha12, writeGraftQueueEntry, } from "./graft-support.js";
+import { assertNotGrafted, bestEffortClaim, localBenchDigest, parseBundleBytes, probeGraftPrerequisites, provenanceGateFailures, readBundleBytes, } from "./graft-gates.js";
+import { graftAndBench } from "./graft-rebench.js";
+export async function graftBundle(req) {
+    const now = req.now ?? (() => new Date());
+    const bundlePath = path.resolve(req.bundlePath);
+    const bytes = readBundleBytes(bundlePath);
+    const bundleSha256 = sha256Hex(bytes);
+    // ---- STEP 1: FULL inspect first (todo 12). Integrity failures are decided,
+    // not negotiated: quarantine-booked, then the inspect wording is echoed.
+    // Cannot-answer-class failures (garbage container / unreadable manifest)
+    // leave no state to book — a refusal line is the whole story.
+    try {
+        inspectBundle({ bundlePath, home: req.home });
+    }
+    catch (cause) {
+        if (cause instanceof ExitSignal && cause.code === EXIT_BLOCKED) {
+            const claim = bestEffortClaim(bytes);
+            return quarantine(req, bundleSha256, bundlePath, claim, `integrity: ${cause.message}`);
+        }
+        throw cause;
+    }
+    const { manifest, members } = parseBundleBytes(bytes);
+    // ---- STEP 2: genome not registered locally ⇒ pending-bench. There is no
+    // repo to hold a ledger, so the queue file IS the graft_import record.
+    if (req.entry === null) {
+        const reason = `genome '${req.genomeLabel}' is not registered locally`;
+        const file = writeGraftQueueEntry(req.configDir, {
+            bundleSha256,
+            bundlePath,
+            genomeLabel: req.genomeLabel,
+            reason,
+            queuedAt: now().toISOString(),
+            sourceGenomeFingerprint: manifest.genome.fingerprint,
+        });
+        return pendingOutcome(req, bundleSha256, reason, file, EXIT_BLOCKED);
+    }
+    const entry = req.entry;
+    const spec = entry.spec;
+    const ledger = Ledger.open(spec.repoPath, { now });
+    assertNotGrafted(ledger, bundleSha256, req.genomeLabel);
+    // ---- STEP 3: the byte-exact gates; any miss quarantines before state or spawns.
+    const localFingerprint = fingerprint(spec);
+    if (localFingerprint !== manifest.genome.fingerprint) {
+        return quarantineLedger(ledger, req, bundleSha256, bundlePath, manifest, `genome fingerprint mismatch — local spec fingerprints to ${localFingerprint}, bundle claims ${manifest.genome.fingerprint}`);
+    }
+    const primary = primaryGenId(bundleGenIds(members));
+    const tree = treeOf(members, primary);
+    const digest = localBenchDigest(spec, tree, primary);
+    if (digest !== manifest.benchDigest) {
+        return quarantineLedger(ledger, req, bundleSha256, bundlePath, manifest, `benchDigest mismatch — recomputed from the contained tree under the LOCAL spec: local ${digest}, bundle claims ${manifest.benchDigest}`);
+    }
+    const provenanceFailures = provenanceGateFailures(manifest, spec, tree, primary, ledger);
+    if (provenanceFailures.length > 0) {
+        return quarantineLedger(ledger, req, bundleSha256, bundlePath, manifest, `scoring provenance not comparable — ${provenanceFailures.join("; ")}`);
+    }
+    // ---- STEP 4: requires[] probes BEFORE any worktree or bench (todo-6 machinery).
+    try {
+        await probeGraftPrerequisites(spec, req.opencodeBin);
+    }
+    catch (cause) {
+        if (cause instanceof ExitSignal && cause.code === EXIT_CANNOT_ANSWER) {
+            const reason = `requires[] probe failed: ${cause.message}`;
+            appendGraftImport(ledger, req, bundleSha256, bundlePath, manifest, {
+                decision: "pending-bench",
+                reason,
+                sourceGenomeFingerprint: manifest.genome.fingerprint,
+            });
+            const file = writeGraftQueueEntry(req.configDir, {
+                bundleSha256,
+                bundlePath,
+                genomeLabel: req.genomeLabel,
+                reason,
+                queuedAt: now().toISOString(),
+                sourceGenomeFingerprint: manifest.genome.fingerprint,
+            });
+            return pendingOutcome(req, bundleSha256, reason, file, EXIT_CANNOT_ANSWER);
+        }
+        throw cause;
+    }
+    // ---- STEP 5: all green ⇒ fresh worktree + LOCAL re-bench under the genome lock.
+    const lease = acquireGenomeLock({ ledger, configDir: req.configDir, genomeFp: fingerprint16(spec), now });
+    try {
+        return await graftAndBench(req, {
+            ledger,
+            spec,
+            genomeFp: entry.fingerprint,
+            manifest,
+            tree,
+            bundleSha256,
+            recordDecision: (decision, reason, sealed) => {
+                // EXACTLY ONE graft_import decision row, booked before the candidate
+                // generation row; the terminal decision retires any pending-bench entry.
+                appendGraftImport(ledger, req, bundleSha256, bundlePath, manifest, {
+                    decision,
+                    reason,
+                    sourceGenomeFingerprint: manifest.genome.fingerprint,
+                    graftGenId: sealed.graftGenId,
+                    commitSha: sealed.commitSha,
+                    treeSha: sealed.treeSha,
+                });
+                removeGraftQueueEntry(req.configDir, bundleSha256);
+            },
+        });
+    }
+    finally {
+        lease.release();
+    }
+}
+function appendGraftImport(ledger, req, bundleSha256, bundlePath, manifest, detail) {
+    ledger.append({
+        kind: LEDGER_KIND_GRAFT_IMPORT,
+        ...(detail.graftGenId === undefined ? {} : { genId: detail.graftGenId }),
+        data: {
+            decision: detail.decision,
+            genomeLabel: req.genomeLabel,
+            bundleSha256,
+            bundlePath,
+            sourceGenomeFingerprint: detail.sourceGenomeFingerprint,
+            sourceBenchDigest: manifest?.benchDigest ?? null,
+            reason: detail.reason,
+            imported: true,
+            graftGenId: detail.graftGenId ?? null,
+            commitSha: detail.commitSha ?? null,
+            treeSha: detail.treeSha ?? null,
+            peerClaim: manifest === null ? null : peerClaimFromManifest(manifest),
+        },
+    });
+}
+/** Inspect-time integrity failure: quarantine on the LOCAL ledger when a repo
+ *  exists; refuse clean (exit 1, no state) when the genome is unknown — the
+ *  pending-bench queue records bundles AWAITING setup, not garbage. */
+function quarantine(req, bundleSha256, bundlePath, claim, reason) {
+    if (req.entry === null) {
+        throw new ExitSignal(EXIT_BLOCKED, `graft: quarantined — ${reason}`, "nothing was applied or benched; 'abathur bundle inspect' names the failing member");
+    }
+    const ledger = Ledger.open(req.entry.spec.repoPath);
+    assertNotGrafted(ledger, bundleSha256, req.genomeLabel);
+    ledger.append({
+        kind: LEDGER_KIND_GRAFT_IMPORT,
+        data: {
+            decision: "quarantined",
+            genomeLabel: req.genomeLabel,
+            bundleSha256,
+            bundlePath,
+            sourceGenomeFingerprint: claim.fingerprint,
+            sourceBenchDigest: claim.benchDigest,
+            reason,
+            imported: true,
+            graftGenId: null,
+            commitSha: null,
+            treeSha: null,
+            peerClaim: null,
+        },
+    });
+    return quarantineOutcome(req, bundleSha256, reason);
+}
+function quarantineLedger(ledger, req, bundleSha256, bundlePath, manifest, reason) {
+    appendGraftImport(ledger, req, bundleSha256, bundlePath, manifest, {
+        decision: "quarantined",
+        reason,
+        sourceGenomeFingerprint: manifest.genome.fingerprint,
+    });
+    return quarantineOutcome(req, bundleSha256, reason);
+}
+function quarantineOutcome(req, bundleSha256, reason) {
+    return {
+        exitCode: EXIT_BLOCKED,
+        lines: [
+            `graft: quarantined — bundle ${sha12(bundleSha256)} refused under genome '${echo(req.genomeLabel, 80)}'`,
+            `  gate: ${echo(reason, 400)}`,
+            `  decision booked to the ledger as ${LEDGER_KIND_GRAFT_IMPORT} (imported:true); review with 'abathur status ${echo(req.genomeLabel, 80)}'`,
+            `  NEVER applied, NEVER benched — v1 has no noise-tolerance band and no bypass flag (docs/federation.md)`,
+        ],
+    };
+}
+function pendingOutcome(req, bundleSha256, reason, queueFile, exitCode) {
+    return {
+        exitCode,
+        lines: [
+            `graft: pending-bench — bundle ${sha12(bundleSha256)} queued for genome '${echo(req.genomeLabel, 80)}'`,
+            `  reason: ${echo(reason, 300)}`,
+            `  queue: ${echo(queueFile, 200)}`,
+            `  zero bench runs launched; the eligible path is to register/repair the local genome, then re-run 'abathur graft <this bundle> --genome ${echo(req.genomeLabel, 80)}'`,
+        ],
+    };
+}