@tachikomagundam/abathur 0.1.0

package/dist/core/genome-paths.js

@@ -0,0 +1,76 @@
+// Shared path scheme + input discipline for the generation store (todo 3).
+//
+//   $XDG_CACHE_HOME/abathur/worktrees/<genomeFp>/<genId>          generation worktrees
+//   $XDG_CACHE_HOME/abathur/worktrees/<genomeFp>/snapshots/<sha>  read-only commit copies
+//   fallback root when XDG_CACHE_HOME is unset/empty/relative: ~/.cache/abathur/worktrees
+//
+// All ids arrive as plain strings (todo 2's ids.ts owns their generation — no
+// import here). Segments are validated to a conservative charset so a hostile
+// or buggy id can never escape the cache dir ("../"), start with "-" (argv
+// option injection), or contain shell metacharacters (irrelevant to execFile
+// argv, but such paths break every downstream tool that does use a shell).
+import path from "node:path";
+import os from "node:os";
+import { cannotAnswer } from "../exit.js";
+/** Reserved child name inside <genomeFp>/ — generation ids may not use it. */
+export const SNAPSHOTS_DIR = "snapshots";
+/** One safe path segment: alnum start, then [A-Za-z0-9._-] — no "/", no "..", no leading "-". */
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** sha/ref spelling a caller may hand to rev-parse/worktree add: alnum start, no leading "-". */
+const REV = /^[A-Za-z0-9][A-Za-z0-9._/@{}^~-]*$/;
+const HEX_SHA = /^[0-9a-f]{7,64}$/i;
+function requireSegment(value, what) {
+    if (!SAFE_SEGMENT.test(value)) {
+        cannotAnswer(`worktree: unsafe ${what} "${value}" — expected a single safe path segment`, "fingerprints and generation ids come from ids.ts / CLI args; refuse traversal or option-like values");
+    }
+    return value;
+}
+/** Validate a commit sha (hex, 7..64) and normalize to lowercase (dir names are content-addressed). */
+export function requireSha(value, what = "commit sha") {
+    if (!HEX_SHA.test(value)) {
+        cannotAnswer(`worktree: unsafe ${what} "${value}" — expected a hex object id`);
+    }
+    return value.toLowerCase();
+}
+/** Validate a revision spelling (sha or simple ref name) safe for argv. */
+export function requireRev(value) {
+    if (!REV.test(value)) {
+        cannotAnswer(`worktree: unsafe parent revision "${value}" — expected a sha or plain ref name`);
+    }
+    return value;
+}
+function resolveHome(env) {
+    return env.HOME === undefined || env.HOME.length === 0 ? os.homedir() : env.HOME;
+}
+/** Root for all generation worktrees/snapshots: $XDG_CACHE_HOME/abathur/worktrees else ~/.cache/... */
+export function cacheRoot(env = process.env) {
+    const xdg = env.XDG_CACHE_HOME;
+    const base = xdg !== undefined && xdg.length > 0 && path.isAbsolute(xdg)
+        ? xdg
+        : path.join(resolveHome(env), ".cache");
+    return path.join(base, "abathur", "worktrees");
+}
+/** <cacheRoot>/<genomeFp> (fingerprint validated). */
+export function genomeDir(env, genome) {
+    return path.join(cacheRoot(env), requireSegment(genome.genomeFp, "genome fingerprint"));
+}
+/** <cacheRoot>/<genomeFp>/<genId> (both validated; reserved snapshot dir name refused). */
+export function generationPath(env, genome, genId) {
+    const id = requireSegment(genId, "generation id");
+    if (id === SNAPSHOTS_DIR) {
+        cannotAnswer(`worktree: "${SNAPSHOTS_DIR}" is a reserved generation id`);
+    }
+    return path.join(genomeDir(env, genome), id);
+}
+/** <cacheRoot>/<genomeFp>/snapshots (fingerprint validated). */
+export function snapshotsDir(env, genome) {
+    return path.join(genomeDir(env, genome), SNAPSHOTS_DIR);
+}
+/** Narrow WorktreeOptions to GitRunOptions for one cwd (exactOptionalPropertyTypes-friendly). */
+export function gitOpts(o, cwd) {
+    return {
+        cwd,
+        ...(o.timeoutMs === undefined ? {} : { timeoutMs: o.timeoutMs }),
+        ...(o.bin === undefined ? {} : { bin: o.bin }),
+    };
+}

package/dist/core/genome.js

@@ -0,0 +1,176 @@
+// Genome registry (todo 4): <configDir>/genomes/<fingerprint16>.jsonc + kernel
+// manifests under <configDir>/kernels/<fingerprint16>.json — structurally outside
+// every genome repo tree, so evolution can never mutate its own identity store.
+// Identity is ONLY the content fingerprint (sha256 of canonical spec JSON via
+// todo 2's ids.ts); labels are free and may repeat across distinct genomes.
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { blocked, cannotAnswer } from "../exit.js";
+import { parseJsonc } from "../jsonc.js";
+import { canonicalJson, fingerprint } from "./ids.js";
+import { filesMatching } from "./glob.js";
+import { buildManifest, compareManifest, manifestPathFor, parseManifestText, readManifestFile, serializeManifest, } from "./kernel.js";
+import { effectiveRepoPath, errorText, formatZodIssues, genomeSpecSchema, loadGenomeSpecFile, } from "./spec.js";
+export function registryDirOf(configDir) {
+    return path.join(configDir, "genomes");
+}
+/** Stable 16-char content fingerprint of a parsed spec (ids.ts sha256, truncated). */
+export function fingerprint16(spec) {
+    return fingerprint(spec).slice(0, 16);
+}
+function requireRepoPath(spec) {
+    const root = effectiveRepoPath(spec.repoPath);
+    let isDirectory = false;
+    try {
+        isDirectory = statSync(root).isDirectory();
+    }
+    catch {
+        isDirectory = false;
+    }
+    if (!isDirectory) {
+        cannotAnswer(`genome: repoPath '${spec.repoPath}' is not a readable directory`);
+    }
+    return root;
+}
+/** Fail-closed: a seal pattern covering zero existing files is a spec error (exit 2). */
+function requireSealedCoverage(repoRoot, spec) {
+    for (const glob of spec.kernel.immutableGlobs) {
+        if (filesMatching(repoRoot, [glob]).length === 0) {
+            cannotAnswer(`genome: kernel.immutableGlobs pattern '${glob}' matches no existing file under ${repoRoot} — ` +
+                "fail-closed: every seal pattern must cover at least one file");
+        }
+    }
+}
+/**
+ * Superset rule (plan round-2 #2). EXACT semantics: for every registered genome whose
+ * repoPath resolves to the same directory (any label, any fingerprint except this
+ * one), every file that each of its existing globs matches IN THE CURRENT WORKING
+ * TREE must be matched by at least one glob of the incoming spec. Resolved-pattern
+ * comparison means vacuous/stale patterns (matching nothing now) pass trivially, and
+ * equivalence is judged by file coverage, not string equality.
+ */
+function enforceGlobSuperset(configDir, spec, repoRoot) {
+    const incoming = new Set(filesMatching(repoRoot, spec.kernel.immutableGlobs));
+    const self = fingerprint16(spec);
+    const weakened = [];
+    for (const entry of readRegistry(configDir).entries) {
+        if (entry.fingerprint === self)
+            continue; // same-fp re-add ⇒ manifest byte-compare
+        if (effectiveRepoPath(entry.spec.repoPath) !== repoRoot)
+            continue;
+        for (const existing of entry.spec.kernel.immutableGlobs) {
+            const uncovered = filesMatching(repoRoot, [existing]).filter((f) => !incoming.has(f));
+            if (uncovered.length > 0 && !weakened.some((w) => w.startsWith(`'${existing}'`))) {
+                weakened.push(`'${existing}' (no longer seals e.g. ${uncovered.slice(0, 3).join(", ")})`);
+            }
+        }
+    }
+    if (weakened.length > 0) {
+        blocked(`genome add refused: incoming kernel.immutableGlobs weaken existing seals for ${repoRoot}: ` +
+            `${weakened.join("; ")} — sealed globs may only grow until a promote reseals`);
+    }
+}
+/**
+ * Re-add of an EXISTING fingerprint: byte-compare the recomputed kernel manifest
+ * against the stored one. Equal ⇒ clean no-op; anything else ⇒ exit 1. This path
+ * NEVER writes — tampering is resolved only at promote (todo 10), never by
+ * resealing through `genome add`.
+ */
+function refuseReseal(configDir, fp, spec, freshManifestText) {
+    const filePath = manifestPathFor(configDir, fp);
+    let saved;
+    try {
+        saved = readManifestFile(filePath);
+    }
+    catch (cause) {
+        blocked(`genome add refused: ${errorText(cause)} — refusing to reseal '${spec.label}' (${fp}); ` +
+            "kernel resealing happens only at promote");
+    }
+    const drifted = compareManifest(saved, parseManifestText(freshManifestText, filePath));
+    if (drifted.length > 0) {
+        const listed = drifted.map((d) => `${d.path} (${d.kind})`);
+        const more = listed.length > 10 ? ` (+${String(listed.length - 10)} more)` : "";
+        blocked(`genome add refused: kernel drifted for '${spec.label}' (${fp}): ` +
+            `${listed.slice(0, 10).join(", ")}${more} — re-add never reseals; ` +
+            "restore the tampered files or resolve drift at promote");
+    }
+}
+export function registerGenome(configDir, specFilePath) {
+    const spec = loadGenomeSpecFile(specFilePath);
+    const repoRoot = requireRepoPath(spec);
+    requireSealedCoverage(repoRoot, spec);
+    enforceGlobSuperset(configDir, spec, repoRoot);
+    const fp = fingerprint16(spec);
+    const registryFile = path.join(registryDirOf(configDir), `${fp}.jsonc`);
+    const manifestText = serializeManifest(buildManifest(repoRoot, spec.kernel.immutableGlobs));
+    if (existsSync(registryFile)) {
+        refuseReseal(configDir, fp, spec, manifestText);
+        return { kind: "already-sealed", fingerprint: fp, label: spec.label };
+    }
+    mkdirSync(registryDirOf(configDir), { recursive: true });
+    mkdirSync(path.dirname(manifestPathFor(configDir, fp)), { recursive: true });
+    writeFileSync(registryFile, `${canonicalJson(spec)}\n`, "utf8");
+    writeFileSync(manifestPathFor(configDir, fp), manifestText, "utf8");
+    return { kind: "registered", fingerprint: fp, label: spec.label };
+}
+/** Parse one registry file into an entry, or return the warning describing why not. */
+function scanRegistryFile(filePath, fp) {
+    let text;
+    let document;
+    try {
+        text = readFileSync(filePath, "utf8");
+        document = parseJsonc(text);
+    }
+    catch (cause) {
+        return `malformed JSONC (${errorText(cause)})`;
+    }
+    const result = genomeSpecSchema.safeParse(document);
+    if (!result.success) {
+        return `does not validate as GenomeSpec: ${formatZodIssues(result.error.issues).join("; ")}`;
+    }
+    if (fingerprint16(result.data) !== fp) {
+        return "content does not match its filename fingerprint (registry edited out-of-band)";
+    }
+    return {
+        fingerprint: fp,
+        label: result.data.label,
+        spec: result.data,
+        registryFile: filePath,
+        storedText: text,
+    };
+}
+/**
+ * Read every registry entry. Corrupt / foreign entries degrade to warnings — stale
+ * or meddled state must never crash `list`/`show`/`audit`.
+ */
+export function readRegistry(configDir) {
+    const dir = registryDirOf(configDir);
+    let names;
+    try {
+        names = readdirSync(dir)
+            .filter((name) => name.endsWith(".jsonc"))
+            .sort();
+    }
+    catch {
+        return { entries: [], warnings: [] }; // no registry yet = empty, not an error
+    }
+    const entries = [];
+    const warnings = [];
+    for (const name of names) {
+        const scanned = scanRegistryFile(path.join(dir, name), name.slice(0, -".jsonc".length));
+        if (typeof scanned === "string")
+            warnings.push(`${name}: ${scanned}`);
+        else
+            entries.push(scanned);
+    }
+    return { entries, warnings };
+}
+/** Labels are non-unique: returns EVERY genome registered under `label`, exit 2 if none. */
+export function requireGenomesByLabel(configDir, label) {
+    const scan = readRegistry(configDir);
+    const matches = scan.entries.filter((entry) => entry.label === label);
+    if (matches.length === 0) {
+        cannotAnswer(`genome: no registered genome with label '${label}'`, "check 'abathur genome list'; if the registry was deleted out-of-band, re-add the spec");
+    }
+    return { entries: matches, warnings: scan.warnings };
+}

package/dist/core/glob.js

@@ -0,0 +1,106 @@
+// Dependency-free glob matcher + working-tree walker for the kernel seal (todo 4).
+// minimatch would be a new runtime dep, which the plan forbids; this covers the
+// documented subset the registry needs:
+//   **   zero or more whole path segments (must occupy a full segment)
+//   *    zero or more chars WITHIN one segment (never '/')
+//   ?    exactly one char within one segment
+//   [..] char class; leading '!' or '^' negates; a-z ranges supported
+// Anything else is literal (regex metachars escaped, '.' included). Patterns match
+// repo-root-relative POSIX-style paths, anchored as a full match. The `.git`
+// directory and symlinks are never walked: seals cover working-tree FILE content.
+import { lstatSync, readdirSync } from "node:fs";
+import path from "node:path";
+function escapeLiteral(char) {
+    return char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function segmentToRegExpSource(segment) {
+    let out = "";
+    let i = 0;
+    while (i < segment.length) {
+        const char = segment[i];
+        if (char === "*") {
+            out += "[^/]*";
+            i += 1;
+        }
+        else if (char === "?") {
+            out += "[^/]";
+            i += 1;
+        }
+        else if (char === "[") {
+            const close = segment.indexOf("]", i + 1);
+            if (close === -1) {
+                out += "\\["; // unterminated class: literal bracket
+                i += 1;
+                continue;
+            }
+            let body = segment.slice(i + 1, close);
+            const negated = body.startsWith("!") || body.startsWith("^");
+            if (negated)
+                body = body.slice(1);
+            const safe = body.replace(/[\\\]^]/g, (m) => `\\${m}`);
+            out += negated ? `[^/${safe}]` : `[${safe}]`;
+            i = close + 1;
+        }
+        else {
+            out += escapeLiteral(char);
+            i += 1;
+        }
+    }
+    return out;
+}
+export function compileGlob(glob) {
+    const segments = glob.split("/");
+    let source = "^";
+    for (let i = 0; i < segments.length; i += 1) {
+        const segment = segments[i];
+        const isLast = i === segments.length - 1;
+        if (segment === "**") {
+            if (segments.length === 1)
+                source += ".*"; // bare ** matches every path
+            else if (i === 0)
+                source += "(?:[^/]+/)*"; // **/x ⇒ x, a/x, a/b/x
+            else if (isLast)
+                source += "/.*"; // x/** ⇒ everything strictly under x/
+            else
+                source += "/(?:[^/]+/)*"; // x/**/y ⇒ x/y, x/a/y, x/a/b/y
+            continue; // each ** branch already consumed its leading separator
+        }
+        if (i > 0 && segments[i - 1] !== "**")
+            source += "/";
+        source += segmentToRegExpSource(segment);
+    }
+    return new RegExp(`${source}$`);
+}
+function walk(absDir, rel, out) {
+    let names;
+    try {
+        names = readdirSync(absDir).sort();
+    }
+    catch {
+        return; // unreadable subdirectory: nothing sealable there
+    }
+    for (const name of names) {
+        if (name === ".git")
+            continue; // VCS metadata is never genome content
+        const abs = path.join(absDir, name);
+        const relPath = rel.length === 0 ? name : `${rel}/${name}`;
+        const stat = lstatSync(abs);
+        if (stat.isSymbolicLink())
+            continue; // never follow links out of the tree
+        if (stat.isDirectory())
+            walk(abs, relPath, out);
+        else if (stat.isFile())
+            out.push(relPath);
+    }
+}
+/** Every regular file under `root` (excluding .git and symlinks), sorted POSIX paths. */
+export function listFiles(root) {
+    const out = [];
+    walk(root, "", out);
+    return out;
+}
+/** Files matching at least one glob, in listFiles() (sorted) order. */
+export function filesMatching(root, globs) {
+    const matchers = globs.map(compileGlob);
+    return listFiles(root).filter((file) => matchers.some((re) => re.test(file)));
+}

package/dist/core/graft-gates.js

@@ -0,0 +1,184 @@
+// Graft gates (todo 13): bundle IO + the four byte-exact pre-conditions —
+// genome fingerprint, benchDigest, scoring provenance, requires[] probes —
+// plus the duplicate-graft refusal. All mismatch messages carry the FULL
+// expected vs actual digests (misleading_success_output guard: quarantine must
+// always state WHICH gate failed). The trust narrative lives in
+// docs/federation.md (todo 15); v1 has no noise-tolerance band.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { gunzipSync } from "node:zlib";
+import { EXIT_BLOCKED, ExitSignal, cannotAnswer } from "../exit.js";
+import { runChild } from "../bench/adapter.js";
+import { probeEngines, resolveOpencodeBin } from "../bench/fixture-probe.js";
+import { compareSemver, parseSemver } from "../bench/fixture-support.js";
+import { benchDigestFor, containedSpec } from "./bundle-common.js";
+import { bundleManifestSchema, deriveBenchProvenance } from "./bundle-manifest.js";
+import { readTar } from "./bundle-tar.js";
+import { clampReps } from "./stats.js";
+import { emptyCounters, readResume } from "./evolve/run-rows.js";
+import { Ledger } from "./ledger.js";
+import { decodeGraftImport, isTerminalDecision, sha12, LEDGER_KIND_GRAFT_IMPORT } from "./graft-support.js";
+const BUNDLE_MAX_BYTES = 256 * 1024 * 1024;
+const PROBE_TIMEOUT_S = 30;
+export function readBundleBytes(bundlePath) {
+    let bytes;
+    try {
+        bytes = readFileSync(bundlePath);
+    }
+    catch {
+        return cannotAnswer(`graft: cannot read bundle ${bundlePath}`);
+    }
+    if (bytes.byteLength > BUNDLE_MAX_BYTES) {
+        cannotAnswer(`graft: bundle ${bundlePath} is ${String(bytes.byteLength)} bytes — exceeds the ${String(BUNDLE_MAX_BYTES)} byte ceiling`);
+    }
+    return bytes;
+}
+/** Manifest + members under the EXACT todo-12 schema — export/inspect/graft share
+ *  one parser, so the verification can never drift from what `inspect` proved. */
+export function parseBundleBytes(bytes) {
+    let members;
+    try {
+        members = readTar(new Uint8Array(gunzipSync(bytes)));
+    }
+    catch (cause) {
+        return cannotAnswer(`graft: bundle bytes unreadable after inspect passed: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const raw = members.find((m) => m.path === "manifest.json");
+    if (raw === undefined)
+        return cannotAnswer("graft: manifest.json vanished from the bundle");
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder().decode(raw.content));
+    }
+    catch (cause) {
+        return cannotAnswer(`graft: manifest.json is not valid JSON: ${cause instanceof Error ? cause.message.split("\n")[0] : String(cause)}`);
+    }
+    const parsed = bundleManifestSchema.safeParse(document);
+    if (!parsed.success) {
+        return cannotAnswer(`graft: manifest.json failed schema v1: ${String(parsed.error.issues[0]?.message ?? "schema")}`);
+    }
+    return { manifest: parsed.data, members };
+}
+/** Best-effort manifest claim extraction when inspect itself failed on a
+ *  pinned-member integrity problem — the ledger row should still name the source
+ *  genome if the manifest parses; unparseable garbage yields nulls. */
+export function bestEffortClaim(bytes) {
+    try {
+        const { manifest } = parseBundleBytes(bytes);
+        return { fingerprint: manifest.genome.fingerprint, benchDigest: manifest.benchDigest };
+    }
+    catch {
+        return { fingerprint: null, benchDigest: null };
+    }
+}
+/** Gate 2 anchor: the digest recomputed from the bundle's contained primary tree
+ *  against the LOCAL registered spec (identities matching is gate 1's job; this
+ *  gate pins the bench SURFACE the peer actually measured). */
+export function localBenchDigest(spec, tree, primary) {
+    return benchDigestFor(spec, tree, primary);
+}
+/**
+ * Gate 3: scoring-provenance subset {agentModel, judgeModel, statsConfigDigest,
+ * opencodeVersion-compatible} — byte-equal on the spec-recomputable fields,
+ * semver-normalized on opencodeVersion (toy: both-null is the honest equality).
+ * The peer side is re-derived from the bundle's OWN contained spec where
+ * recomputable: manifest claims alone are never the word (adapterConfigDigest
+ * and fixtureSeedId ride along as bonus recomputables).
+ */
+export function provenanceGateFailures(manifest, spec, tree, primary, ledger) {
+    const claim = manifest.benchProvenance;
+    const peerSpec = containedSpec(tree, primary);
+    const localVersions = latestIncumbentVersions(ledger);
+    const local = deriveBenchProvenance(provenanceRow(localVersions, clampReps(undefined, spec.bench.stats.nReps), spec), spec);
+    const peer = deriveBenchProvenance(provenanceRow(claim.opencodeVersion === null ? [] : [{ bin: "opencode", version: claim.opencodeVersion }], claim.nRepeats ?? 1, peerSpec), peerSpec);
+    const failures = [];
+    const keys = ["agentModel", "judgeModel", "statsConfigDigest", "adapterConfigDigest", "fixtureSeedId"];
+    for (const key of keys) {
+        if (peer[key] !== local[key]) {
+            failures.push(`${key}: local '${String(local[key] ?? "null")}' vs peer-derived '${String(peer[key] ?? "null")}'`);
+        }
+        if (claim[key] !== peer[key]) {
+            failures.push(`${key}: manifest claims '${String(claim[key] ?? "null")}' but the contained spec derives '${String(peer[key] ?? "null")}'`);
+        }
+    }
+    if (!opencodeVersionCompatible(local.opencodeVersion, claim.opencodeVersion)) {
+        failures.push(`opencodeVersion: local '${local.opencodeVersion ?? "null"}' not semver-equal to peer '${claim.opencodeVersion ?? "null"}'`);
+    }
+    return failures;
+}
+function opencodeVersionCompatible(local, peer) {
+    if (local === null && peer === null)
+        return true;
+    if (local === null || peer === null)
+        return false;
+    const a = parseSemver(local);
+    const b = parseSemver(peer);
+    if (a === null || b === null)
+        return false; // unparsable provenance is not comparable evidence
+    return compareSemver(a, b) === 0;
+}
+/** Schema-valid row so deriveBenchProvenance (which reads .reps + .benchProvenance.versions)
+ *  gets a real GenerationRowData, never a cast. */
+function provenanceRow(versions, reps, spec) {
+    return {
+        source: "incumbent",
+        headCommit: "0".repeat(40),
+        complete: true,
+        reps,
+        units: [],
+        counters: emptyCounters(),
+        manifest: [],
+        benchProvenance: { benchType: spec.bench.type, versions: versions.map((v) => ({ bin: v.bin, version: v.version })) },
+    };
+}
+function latestIncumbentVersions(ledger) {
+    let versions = [];
+    for (const row of readResume(ledger).incumbentByHead.values())
+        versions = row.benchProvenance.versions;
+    return versions;
+}
+/**
+ * Gate 4 — requires[] probes via the todo-6 machinery BEFORE any worktree or
+ * bench. Fixture genomes go through probeEngines (opencode --version +
+ * minVersion + requires[]). Toy benches never spawn opencode, so probeEngines'
+ * mandatory bin probe would be wrong there; the requires[] loop below mirrors
+ * fixture-probe's runChild discipline exactly (argv spawn, 30s, exit-2-before-
+ * any-unit on spawn_failed / probeExit mismatch).
+ */
+export async function probeGraftPrerequisites(spec, opencodeBin) {
+    const repoRoot = path.resolve(spec.repoPath);
+    if (spec.bench.type === "opencode-fixture-scenarios") {
+        const env = process.env;
+        const bin = resolveOpencodeBin(opencodeBin === null || opencodeBin === undefined ? { env } : { opencodeBin, env });
+        await probeEngines(spec, bin, repoRoot);
+        return;
+    }
+    for (const prereq of spec.requires ?? []) {
+        const outcome = await runChild({
+            argv: [prereq.cmd, ...(prereq.args ?? ["--version"])],
+            cwd: repoRoot,
+            timeoutS: PROBE_TIMEOUT_S,
+        });
+        if (outcome.kind === "spawn_failed") {
+            cannotAnswer(`graft: required prerequisite '${prereq.cmd}' is missing: ${outcome.reason}`, "install it or fix spec.requires before grafting");
+        }
+        if (outcome.kind !== "exited" || outcome.exitCode !== prereq.probeExit) {
+            cannotAnswer(`graft: prerequisite '${prereq.cmd}' probe expected exit ${String(prereq.probeExit)}, got ${outcome.reason}`);
+        }
+    }
+}
+/** stale_state pin: the same bundle + genome never grafts twice — a terminal
+ *  decision row (quarantined/nominated/culled/…) refuses re-entry. Pending
+ *  rows do NOT: the plan's eligible path is "register genome then re-run". */
+export function assertNotGrafted(ledger, bundleSha256, genomeLabel) {
+    for (const record of ledger.readAll()) {
+        if (record.kind !== LEDGER_KIND_GRAFT_IMPORT)
+            continue;
+        const row = decodeGraftImport(record.data);
+        if (row === null || row.bundleSha256 !== bundleSha256 || row.genomeLabel !== genomeLabel)
+            continue;
+        if (!isTerminalDecision(row.decision))
+            continue;
+        throw new ExitSignal(EXIT_BLOCKED, `graft: bundle ${sha12(bundleSha256)} already grafted under genome '${genomeLabel}' (decision '${row.decision}') — the ledger is append-only`, "export a newer bundle for new work; re-running the same bundle never re-benches");
+    }
+}