@tachikomagundam/abathur 0.1.0

package/dist/bench/fixture.js

@@ -0,0 +1,236 @@
+// Opencode-fixture-scenarios bench adapter (plan todo 6, lines 117-124): the
+// real-surface path the evolution loop (todo 9) drives when bench.type is
+// "opencode-fixture-scenarios". Reuses the todo-5 plumbing verbatim (renderCommand
+// templates, runChild process-group discipline, grader JSON contract) and adds:
+//   - startup probes: `<opencodeBin> --version` enforced against
+//     spec.opencodeBinVersion.minVersion and every spec.requires[] binary probed via
+//     PATH (argv spawn, never shell); any failure is exit 2 BEFORE a unit runs, and
+//     the observed version strings land in EVERY RunResult.benchProvenance.
+//   - per-unit lifecycle reset → seed → run under a fingerprint-keyed
+//     single-flight genome lock (src/core/locks via acquireGenomeLock).
+//   - sandbox HOME discipline: ONLY .opencode/{plugin,skills,node_modules} is
+//     mirrored from the real HOME and the opencode config is copied-then-mutated
+//     per scenario (never symlinked, real HOME untouched).
+//   - train/val by SPLIT FIELD ONLY, with two INDEPENDENT axes (plan lines
+//     117-124 + 125-132): BENCHING authority — the loop's bench driver runs val
+//     replicates under loopValAuthority (the selection gate needs them), while a
+//     direct adapter consumer must pass includeVal; and EXPOSURE — val ids/paths
+//     enter the sandbox manifest only under includeVal, reachable ONLY via the
+//     operator CLI switch `abathur run --include-val`. Without it the manifest
+//     keeps val entries as opaque aliases, even while those units are benched.
+// Scenario content stays opaque — no harness-specific parsing anywhere here.
+//
+// Pure-LOC documented exception (F2 review, 2026-09-10): 253 pure LOC, above the
+// 250 ceiling — the LOOP_VAL_AUTHORITY benching seam must live in-fixture beside
+// the exposure axis it is deliberately independent from (F1-fix2 pins both through
+// this module's surface; a minimal seam was mandated over splitting). Accepted
+// exception: do not grow this file; split at the next real feature.
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { cannotAnswer, ExitSignal } from "../exit.js";
+import { resolveConfigDir } from "../config.js";
+import { fingerprint } from "../core/ids.js";
+import { acquireGenomeLock, Ledger } from "../core/ledger.js";
+import { childStatus, firstLine, inconclusive, parseGraderLine, renderCommand, runChild, sandboxVars, unitVars, ZERO_METRICS, } from "./adapter.js";
+import { buildManifest, gateVal, mirrorSandboxHome, parseRunMeta, sandboxHomeDir, transcriptPathFor, writeManifest, } from "./fixture-support.js";
+import { probeEngines, resolveOpencodeBin } from "./fixture-probe.js";
+export { buildManifest, compareSemver, manifestPathFor, mirrorSandboxHome, parseSemver, sandboxHomeDir, transcriptPathFor, writeManifest, } from "./fixture-support.js";
+export { probeEngines, resolveOpencodeBin } from "./fixture-probe.js";
+const HOOK_TIMEOUT_S = 60;
+export class FixtureScenariosAdapter {
+    spec;
+    opts;
+    repoRoot;
+    lease = null;
+    started = null;
+    versions = [];
+    activeSandbox = null;
+    constructor(spec, opts = {}) {
+        this.spec = spec;
+        this.opts = opts;
+        if (spec.bench.type !== "opencode-fixture-scenarios") {
+            cannotAnswer(`fixture adapter: bench.type '${spec.bench.type}' is not "opencode-fixture-scenarios"`, "use ToyBenchAdapter for bench.type 'toy'");
+        }
+        const root = path.resolve(spec.repoPath);
+        if (!statSync(root, { throwIfNoEntry: false })?.isDirectory()) {
+            cannotAnswer(`fixture: repoPath '${spec.repoPath}' is not a readable directory`);
+        }
+        this.repoRoot = root;
+    }
+    async reset(sandboxDir) {
+        await this.ensureStarted();
+        this.activeSandbox = sandboxDir;
+        mkdirSync(sandboxDir, { recursive: true });
+        await this.hook(this.spec.bench.resetCommand, sandboxDir, "resetCommand");
+        // the reset script owns scenario teardown and may replace the dir wholesale
+        mkdirSync(sandboxDir, { recursive: true });
+        mirrorSandboxHome(this.homeDir(), sandboxDir, this.agentModel());
+    }
+    async seed(sandboxDir) {
+        await this.ensureStarted();
+        this.activeSandbox = sandboxDir;
+        mkdirSync(sandboxDir, { recursive: true });
+        if (!existsSync(sandboxHomeDir(sandboxDir)))
+            mirrorSandboxHome(this.homeDir(), sandboxDir, this.agentModel());
+        writeManifest(sandboxDir, this.scenarioManifest());
+        await this.hook(this.spec.bench.seedCommand, sandboxDir, "seedCommand");
+    }
+    async run(unit, sandboxDir, timeoutS) {
+        await this.ensureStarted();
+        gateVal(unit, this.valRunAllowed());
+        this.activeSandbox = sandboxDir;
+        mkdirSync(sandboxDir, { recursive: true });
+        const transcript = transcriptPathFor(sandboxDir, unit.id);
+        mkdirSync(path.dirname(transcript), { recursive: true });
+        const outcome = await runChild({
+            argv: renderCommand(this.spec.bench.runCommand, unitVars(unit, sandboxDir)),
+            cwd: sandboxDir,
+            timeoutS,
+            env: this.sandboxEnv(sandboxDir, unit),
+            ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
+        });
+        const status = childStatus(outcome.kind);
+        return {
+            unitId: unit.id,
+            status,
+            metrics: status === "ok" ? parseRunMeta(outcome.stdout) : ZERO_METRICS,
+            benchProvenance: { benchType: "opencode-fixture-scenarios", versions: this.versions },
+            exitCode: outcome.exitCode,
+            note: status === "ok" && outcome.exitCode === 0 ? undefined : outcome.reason,
+            transcriptPath: status === "ok" && existsSync(transcript) ? transcript : undefined,
+        };
+    }
+    async score(unit) {
+        await this.ensureStarted();
+        gateVal(unit, this.valRunAllowed());
+        const sandbox = this.activeSandbox;
+        if (sandbox === null) {
+            cannotAnswer("fixture adapter: score() called before any reset()/seed()/run() — no sandbox yet", "drive the adapter in reset→seed→run→score order");
+        }
+        const outcome = await runChild({
+            argv: renderCommand(this.spec.bench.graderCommand, unitVars(unit, sandbox)),
+            cwd: sandbox,
+            timeoutS: this.spec.bench.timeoutS,
+            env: this.sandboxEnv(sandbox),
+            ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
+        });
+        if (outcome.kind !== "exited") {
+            return inconclusive(unit.id, `grader ${outcome.kind}: ${outcome.reason}`);
+        }
+        if (outcome.exitCode !== 0) {
+            return inconclusive(unit.id, `grader exited ${String(outcome.exitCode)}: ${firstLine(outcome.stderr) || firstLine(outcome.stdout) || "no output"}`);
+        }
+        const parsed = parseGraderLine(outcome.stdout);
+        if (parsed === null) {
+            return inconclusive(unit.id, `grader stdout is not a score JSON line: ${firstLine(outcome.stdout) || "no output"}`);
+        }
+        return { kind: "scored", result: { unitId: unit.id, ...parsed } };
+    }
+    /**
+     * Val units may be RUN/SCORED when the operator opened exposure (includeVal)
+     * OR the loop holds benching authority (loopValAuthority, F1-fix2); either
+     * way this never decides what the manifest EXPOSES.
+     */
+    valRunAllowed() {
+        return this.opts.includeVal === true || this.opts.loopValAuthority === true;
+    }
+    /**
+     * Sandbox view of the scenarios: val ids/paths surface only under operator
+     * includeVal. loopValAuthority deliberately does NOT open this — the loop may
+     * bench val units while their paths stay opaque aliases (plan line 118).
+     */
+    scenarioManifest() {
+        return buildManifest(this.spec.bench.units, this.opts.includeVal === true);
+    }
+    /** Free the single-flight lease (todo 9 calls this when the bench run ends). */
+    release() {
+        this.lease?.release();
+        this.lease = null;
+        this.started = null;
+        this.versions = [];
+    }
+    // ------------------------------------------------------- startup + locking
+    ensureStarted() {
+        if (this.started === null) {
+            this.started = this.startProbes().catch((cause) => {
+                this.started = null;
+                throw cause;
+            });
+        }
+        return this.started;
+    }
+    async startProbes() {
+        this.acquireFlight();
+        try {
+            this.versions = await probeEngines(this.spec, this.opencodeBinName(), this.repoRoot, {
+                ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
+            });
+        }
+        catch (cause) {
+            this.release();
+            throw cause;
+        }
+    }
+    acquireFlight() {
+        if (this.lease !== null)
+            return;
+        const configDir = this.opts.configDir ?? resolveConfigDir(this.opts.env ?? process.env);
+        const fp = fingerprint(this.spec);
+        const ledger = Ledger.open(this.repoRoot);
+        try {
+            this.lease = acquireGenomeLock({
+                ledger,
+                configDir,
+                genomeFp: fp,
+                waitMs: this.opts.lockWaitMs ?? 0,
+            });
+        }
+        catch (cause) {
+            if (cause instanceof ExitSignal) {
+                cannotAnswer(`fixture: another bench active for genome '${fp.slice(0, 16)}'`, cause.hint ?? cause.message);
+            }
+            throw cause;
+        }
+    }
+    // ----------------------------------------------------------------- sandbox
+    sandboxEnv(sandboxDir, unit) {
+        const env = {
+            HOME: sandboxHomeDir(sandboxDir),
+            ABATHUR_AGENT_MODEL: this.agentModel(),
+        };
+        const judge = this.spec.bench.judgeModel;
+        if (judge !== undefined)
+            env["ABATHUR_JUDGE_MODEL"] = judge;
+        if (unit !== undefined)
+            env["ABATHUR_TRANSCRIPT"] = transcriptPathFor(sandboxDir, unit.id);
+        return env;
+    }
+    /** seed/reset hooks are infrastructure: a failing hook is a tool error (exit 2). */
+    async hook(template, sandboxDir, label) {
+        if (template === undefined)
+            return;
+        const outcome = await runChild({
+            argv: renderCommand(template, sandboxVars(sandboxDir)),
+            cwd: sandboxDir,
+            timeoutS: HOOK_TIMEOUT_S,
+            env: this.sandboxEnv(sandboxDir),
+            ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
+        });
+        if (outcome.kind !== "exited" || outcome.exitCode !== 0) {
+            cannotAnswer(`fixture ${label} failed (${outcome.reason}): ${firstLine(outcome.stderr) || "no output"}`);
+        }
+    }
+    agentModel() {
+        return this.spec.bench.agentModel ?? cannotAnswer("fixture: bench.agentModel is required");
+    }
+    opencodeBinName() {
+        return resolveOpencodeBin(this.opts);
+    }
+    homeDir() {
+        if (this.opts.home !== undefined)
+            return this.opts.home;
+        const envHome = (this.opts.env ?? process.env).HOME;
+        return envHome === undefined || envHome.length === 0 ? os.homedir() : envHome;
+    }
+}

package/dist/bench/toy.js

@@ -0,0 +1,152 @@
+// Toy bench adapter (plan todo 5): the deterministic, model-free evolution
+// substrate. Units are tiny source files of the genome repo itself; the grader is
+// the repo's own `node grader.mjs {unit.path}`. The toy path never requires
+// opencode, network, or absolute machine paths (D7 generality proof): every binary
+// is a PATH name, every file reference is genome-relative, sandboxes are caller-chosen.
+//
+// Sandbox model: reset = wipe+recreate (determinism substrate), seed = copy the
+// genome working tree (minus .git/.state) into the sandbox. score() has no sandbox
+// parameter by iface contract, so the adapter remembers the last sandbox passed to
+// reset/seed/run and grades the unit copy inside it.
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { cannotAnswer } from "../exit.js";
+import { walkTree } from "../core/ids.js";
+import { childStatus, firstLine, inconclusive, parseGraderLine, renderCommand, runChild, sandboxVars, unitVars, ZERO_METRICS, } from "./adapter.js";
+/** Model-free token heuristic pinned by the grader too: 1 token ~ 4 source bytes. */
+const BYTES_PER_TOKEN = 4;
+const HOOK_TIMEOUT_S = 60;
+export class ToyBenchAdapter {
+    spec;
+    opts;
+    repoRoot;
+    activeSandbox = null;
+    constructor(spec, opts = {}) {
+        this.spec = spec;
+        this.opts = opts;
+        const root = path.resolve(spec.repoPath);
+        if (!statSync(root, { throwIfNoEntry: false })?.isDirectory()) {
+            cannotAnswer(`toy: repoPath '${spec.repoPath}' is not a readable directory`);
+        }
+        this.repoRoot = root;
+    }
+    async reset(sandboxDir) {
+        rmSync(sandboxDir, { recursive: true, force: true });
+        mkdirSync(sandboxDir, { recursive: true });
+        this.activeSandbox = sandboxDir;
+        await this.hook(this.spec.bench.resetCommand, sandboxDir, "resetCommand");
+    }
+    async seed(sandboxDir) {
+        mkdirSync(sandboxDir, { recursive: true });
+        for (const file of walkTree(this.repoRoot)) {
+            const top = file.path.split("/")[0];
+            if (top === ".git" || top === ".state")
+                continue;
+            const target = path.join(sandboxDir, file.path);
+            mkdirSync(path.dirname(target), { recursive: true });
+            writeFileSync(target, file.content);
+        }
+        this.activeSandbox = sandboxDir;
+        await this.hook(this.spec.bench.seedCommand, sandboxDir, "seedCommand");
+    }
+    async run(unit, sandboxDir, timeoutS) {
+        this.activeSandbox = sandboxDir;
+        const outcome = await runChild({
+            argv: renderCommand(this.spec.bench.runCommand, unitVars(unit, sandboxDir)),
+            cwd: sandboxDir,
+            timeoutS,
+            ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
+        });
+        const status = childStatus(outcome.kind);
+        return {
+            unitId: unit.id,
+            status,
+            metrics: status === "ok" ? this.runMetrics(unit, sandboxDir) : ZERO_METRICS,
+            benchProvenance: this.provenance(),
+            exitCode: outcome.exitCode,
+            // clean ok runs stay note-less; non-zero unit exits record the plain reason
+            note: status === "ok" && outcome.exitCode === 0 ? undefined : outcome.reason,
+        };
+    }
+    async score(unit) {
+        const sandbox = this.activeSandbox;
+        if (sandbox === null) {
+            cannotAnswer("toy adapter: score() called before any reset()/seed()/run() — no sandbox yet", "drive the adapter in reset→seed→run→score order");
+        }
+        const outcome = await runChild({
+            argv: renderCommand(this.spec.bench.graderCommand, unitVars(unit, sandbox)),
+            cwd: sandbox,
+            timeoutS: this.spec.bench.timeoutS,
+            ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
+        });
+        if (outcome.kind !== "exited") {
+            return inconclusive(unit.id, `grader ${outcome.kind}: ${outcome.reason}`);
+        }
+        if (outcome.exitCode !== 0) {
+            return inconclusive(unit.id, `grader exited ${String(outcome.exitCode)}: ${firstLine(outcome.stderr) || firstLine(outcome.stdout) || "no output"}`);
+        }
+        const parsed = parseGraderLine(outcome.stdout);
+        if (parsed === null) {
+            return inconclusive(unit.id, `grader stdout is not a score JSON line: ${firstLine(outcome.stdout) || "no output"}`);
+        }
+        return { kind: "scored", result: { unitId: unit.id, ...parsed } };
+    }
+    runMetrics(unit, sandboxDir) {
+        try {
+            const bytes = readFileSync(path.join(sandboxDir, unit.path)).length;
+            return { tokensEst: Math.ceil(bytes / BYTES_PER_TOKEN), turns: 1 };
+        }
+        catch {
+            return { tokensEst: 0, turns: 1 }; // unit vanished mid-run: still one measured turn
+        }
+    }
+    provenance() {
+        return { benchType: "toy", versions: [{ bin: "node", version: process.version }] };
+    }
+    /** seed/reset hooks are infrastructure: a failing hook is a tool error (exit 2). */
+    async hook(template, sandboxDir, label) {
+        if (template === undefined)
+            return;
+        const outcome = await runChild({
+            argv: renderCommand(template, sandboxVars(sandboxDir)),
+            cwd: sandboxDir,
+            timeoutS: HOOK_TIMEOUT_S,
+            ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
+        });
+        if (outcome.kind !== "exited" || outcome.exitCode !== 0) {
+            cannotAnswer(`toy ${label} failed (${outcome.reason}): ${firstLine(outcome.stderr) || "no output"}`);
+        }
+    }
+}
+// ------------------------------------------------------- fixture self-init
+/** Locates genomes/toy-smoke beside the compiled module (repo source or dist copy). */
+export function toyTemplateDir() {
+    for (const rel of ["../../genomes/toy-smoke/", "../genomes/toy-smoke/"]) {
+        const dir = fileURLToPath(new URL(rel, import.meta.url));
+        if (existsSync(path.join(dir, "genome.jsonc")))
+            return dir;
+    }
+    cannotAnswer("toy fixture: genomes/toy-smoke not found beside dist/bench/toy.js", "npm run build ships it to dist/genomes/toy-smoke via copy-assets");
+}
+/**
+ * Materialize an independent toy genome repo (git-initialized, repoPath rewritten)
+ * by running the fixture's own init.mjs — one implementation, shell-usable too.
+ */
+export async function prepareToyGenome(destDir, templateDir = toyTemplateDir()) {
+    const dest = path.resolve(destDir);
+    // init.mjs runs with cwd = parent of dest; a missing cwd surfaces as a
+    // misleading `spawn <bin> ENOENT`, so materialize the parent first.
+    mkdirSync(path.dirname(dest), { recursive: true });
+    const outcome = await runChild({
+        argv: [process.execPath, path.join(templateDir, "init.mjs"), dest],
+        cwd: path.dirname(dest),
+        timeoutS: HOOK_TIMEOUT_S,
+    });
+    if (outcome.kind !== "exited" || outcome.exitCode !== 0) {
+        cannotAnswer(`toy fixture init failed (${outcome.reason}): ${firstLine(outcome.stderr) || "no output"}`);
+    }
+    return dest;
+}
+// --------------------------------------------------------------- grader JSON
+// parseGraderLine + the score contract live in adapter.ts (shared with todo 6).

package/dist/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// CLI spine (todo 1). Every command group is a CommandSpec in COMMANDS (group
+// logic lives in src/commands/<group>.ts; this file stays a thin router).
+// Handlers return EXIT_OK or throw ExitSignal (see src/exit.ts) — never touch
+// process themselves, so they stay unit-testable.
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { bundleCommand } from "./commands/bundle.js";
+import { genomeCommand } from "./commands/genome.js";
+import { graftCommand } from "./commands/graft.js";
+import { kernelCommand } from "./commands/kernel.js";
+import { promoteCommand } from "./commands/promote.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 { 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.
+export const COMMANDS = [
+    genomeCommand,
+    runCommand,
+    statusCommand,
+    promoteCommand,
+    tombstoneCommand,
+    bundleCommand,
+    graftCommand,
+    selfEvalCommand,
+    kernelCommand,
+];
+export function usage() {
+    const width = Math.max(...COMMANDS.map((c) => c.name.length));
+    const lines = COMMANDS.map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`).join("\n");
+    return [
+        "abathur — OpenCode genome evolution harness",
+        "",
+        "usage: abathur <command> [args...]",
+        "",
+        "commands:",
+        lines,
+        "",
+        "exit codes:",
+        "  0  ok / pass",
+        "  1  blocked / failed (decision)",
+        "  2  cannot-answer (config error, malformed input, missing engine, unimplemented)",
+        "",
+        "config: $ABATHUR_CONFIG > ~/.config/abathur/config.jsonc > <package>/config/abathur.jsonc,",
+        "        with gitignored *.local.jsonc deep-merge overlay.",
+        "",
+    ].join("\n");
+}
+async function dispatch(argv) {
+    const [head, ...rest] = argv;
+    if (head === undefined) {
+        return cannotAnswer("no command given", "run 'abathur --help' for the command list");
+    }
+    if (head === "--help" || head === "-h" || head === "help") {
+        process.stdout.write(usage());
+        return EXIT_OK;
+    }
+    const command = COMMANDS.find((spec) => spec.name === head);
+    if (command === undefined) {
+        return cannotAnswer(`unknown command '${head}'`, "run 'abathur --help' for the command list");
+    }
+    let loaded;
+    try {
+        loaded = loadConfig();
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            return cannotAnswer(error.message);
+        throw error;
+    }
+    return await command.run({ loaded, args: rest });
+}
+async function main(argv) {
+    try {
+        process.exitCode = await dispatch(argv);
+    }
+    catch (error) {
+        if (error instanceof ExitSignal) {
+            process.stderr.write(`${renderExitSignal(error)}\n`);
+            process.exitCode = error.code;
+            return;
+        }
+        // Last-resort funnel: a crash is still a "cannot-answer", never a stack dump.
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`abathur: cannot answer: unexpected error: ${message}\n`);
+        if (process.env.ABATHUR_DEBUG !== undefined && error instanceof Error) {
+            process.stderr.write(`${error.stack ?? ""}\n`);
+        }
+        process.exitCode = EXIT_CANNOT_ANSWER;
+    }
+}
+// Node passes the symlink path (npm's global bin shim) as argv[1], so compare
+// realpaths — a plain resolve() made `npm i -g` installs silently no-op (todo 15
+// pack→install proof). realpathSync throws for missing files; the catch keeps
+// the guard false there, which is the pre-existing behavior.
+let invokedDirectly = false;
+try {
+    invokedDirectly =
+        process.argv[1] !== undefined &&
+            realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url);
+}
+catch {
+    invokedDirectly = false;
+}
+if (invokedDirectly)
+    await main(process.argv.slice(2));

package/dist/commands/bundle.js

@@ -0,0 +1,79 @@
+// `abathur bundle export|inspect` (todo 12) — thin router: flag parsing and the
+// registry lookup live here; all bundle mechanics in src/core/bundle*.ts.
+import { homedir } from "node:os";
+import { resolveConfigDir } from "../config.js";
+import { EXIT_OK, cannotAnswer } from "../exit.js";
+import { exportBundle } from "../core/bundle-export.js";
+import { inspectBundle } from "../core/bundle-inspect.js";
+import { writeStdout } from "../out.js";
+import { resolveUniqueEntry } from "./run.js";
+const USAGE = "usage: abathur bundle export <label> (--gen <genId> [--gen <genId> ...] | --last <N>) --out <dir>\n" +
+    "   or: abathur bundle inspect <path>";
+function parseExportFlags(args) {
+    const [label, ...rest] = args;
+    if (label === undefined || label.startsWith("--"))
+        cannotAnswer("bundle export: <label> required", USAGE);
+    const genIds = [];
+    let last = null;
+    let outDir = null;
+    for (let i = 0; i < rest.length; i += 1) {
+        const flag = rest[i];
+        const value = rest[i + 1];
+        if (flag === "--gen") {
+            if (value === undefined || value.startsWith("--"))
+                cannotAnswer("bundle export: --gen needs a genId", USAGE);
+            genIds.push(value);
+            i += 1;
+        }
+        else if (flag === "--last") {
+            if (value === undefined || !/^\d+$/.test(value))
+                cannotAnswer("bundle export: --last needs a positive integer", USAGE);
+            last = Number.parseInt(value, 10);
+            i += 1;
+        }
+        else if (flag === "--out") {
+            if (value === undefined || value.startsWith("--"))
+                cannotAnswer("bundle export: --out needs a directory", USAGE);
+            outDir = value;
+            i += 1;
+        }
+        else {
+            cannotAnswer(`bundle export: unknown argument '${String(flag)}'`, USAGE);
+        }
+    }
+    if (genIds.length > 0 && last !== null)
+        cannotAnswer("bundle export: choose --gen or --last, not both", USAGE);
+    if (genIds.length === 0 && last === null)
+        cannotAnswer("bundle export: pick generations with --gen <id> or --last <N>", USAGE);
+    if (outDir === null)
+        cannotAnswer("bundle export: --out <dir> is required", USAGE);
+    return { label, genIds: genIds.length > 0 ? genIds : null, last, outDir };
+}
+async function runBundle(args) {
+    const [sub, ...rest] = args;
+    if (sub === "export") {
+        const flags = parseExportFlags(rest);
+        const configDir = resolveConfigDir();
+        const entry = resolveUniqueEntry(configDir, flags.label, "bundle");
+        const select = flags.genIds !== null ? { genIds: flags.genIds } : { last: flags.last ?? 0 };
+        const outcome = await exportBundle({ entry, configDir, select, outDir: flags.outDir ?? "", home: homedir() });
+        for (const line of outcome.lines)
+            writeStdout(line);
+        return EXIT_OK;
+    }
+    if (sub === "inspect") {
+        const [bundlePath] = rest;
+        if (bundlePath === undefined || rest.length !== 1)
+            cannotAnswer("bundle inspect: expected exactly one bundle path", USAGE);
+        const outcome = inspectBundle({ bundlePath, home: homedir() });
+        for (const line of outcome.lines)
+            writeStdout(line);
+        return outcome.exitCode;
+    }
+    cannotAnswer(`bundle: unknown subcommand '${String(sub ?? "(none)")}'`, USAGE);
+}
+export const bundleCommand = {
+    name: "bundle",
+    summary: "export a genome + lineage as an offline bundle (or inspect one: re-hash, self-consistency, leak re-scan)",
+    run: ({ args }) => runBundle(args),
+};

package/dist/commands/genome.js

@@ -0,0 +1,94 @@
+// `abathur genome` — thin subcommand router (todo 1 seam); all logic lives in
+// src/core/{spec,genome,kernel,glob}.ts. `rm` (todo 10) is registry-only: a
+// genome with ledger history is refused outright — lineage is archive-not-delete.
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { resolveConfigDir } from "../config.js";
+import { readRegistry, registerGenome, requireGenomesByLabel } from "../core/genome.js";
+import { ledgerPath } from "../core/ledger.js";
+import { EXIT_OK, blocked, cannotAnswer } from "../exit.js";
+import { writeStdout } from "../out.js";
+import { resolveUniqueEntry } from "./run.js";
+function requireLabelArg(args, command) {
+    const label = args[0];
+    if (label === undefined || label.length === 0) {
+        cannotAnswer(`genome ${command}: missing <label> argument`);
+    }
+    return label;
+}
+function genomeAdd(configDir, args) {
+    const specPath = args[0];
+    if (specPath === undefined) {
+        cannotAnswer("genome add: missing <spec.jsonc> argument", "usage: abathur genome add <file.jsonc>");
+    }
+    const result = registerGenome(configDir, specPath);
+    writeStdout(result.kind === "registered"
+        ? `registered genome '${result.label}' (${result.fingerprint})`
+        : `genome '${result.label}' (${result.fingerprint}) already registered — kernel manifest byte-identical, nothing rewritten`);
+    return EXIT_OK;
+}
+function genomeList(configDir) {
+    const scan = readRegistry(configDir);
+    for (const warning of scan.warnings)
+        writeStdout(`warning: ${warning}`);
+    if (scan.entries.length === 0) {
+        writeStdout("no genomes registered");
+        return EXIT_OK;
+    }
+    for (const entry of scan.entries)
+        writeStdout(`${entry.fingerprint}  ${entry.label}`);
+    return EXIT_OK;
+}
+function genomeShow(configDir, label) {
+    const scan = requireGenomesByLabel(configDir, label);
+    for (const warning of scan.warnings)
+        writeStdout(`warning: ${warning}`);
+    for (const entry of scan.entries) {
+        writeStdout(`# ${entry.label} (${entry.fingerprint}) — ${entry.registryFile}`);
+        writeStdout(entry.storedText.trimEnd());
+    }
+    return EXIT_OK;
+}
+function genomeSeals(configDir, label) {
+    const scan = requireGenomesByLabel(configDir, label);
+    for (const warning of scan.warnings)
+        writeStdout(`warning: ${warning}`);
+    for (const entry of scan.entries) {
+        writeStdout(`# effective seal globs for '${entry.label}' (${entry.fingerprint}) under ${entry.spec.repoPath}`);
+        for (const glob of entry.spec.kernel.immutableGlobs)
+            writeStdout(glob);
+    }
+    return EXIT_OK;
+}
+function genomeRm(configDir, label) {
+    const entry = resolveUniqueEntry(configDir, label, "genome rm");
+    const file = ledgerPath(entry.spec.repoPath);
+    if (existsSync(file) && readFileSync(file, "utf8").trim().length > 0) {
+        blocked(`genome rm refused: '${entry.label}' (${entry.fingerprint}) has ledger history — archive instead`, `lineage lives in ${file}; unregistering a lived genome would orphan its evidence. Keep it registered or move the repo aside.`);
+    }
+    rmSync(entry.registryFile);
+    writeStdout(`unregistered genome '${entry.label}' (${entry.fingerprint}) — repo and kernel manifest left in place (cull ≠ delete)`);
+    return EXIT_OK;
+}
+function runGenome(args) {
+    const configDir = resolveConfigDir();
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case "add":
+            return genomeAdd(configDir, rest);
+        case "list":
+            return genomeList(configDir);
+        case "show":
+            return genomeShow(configDir, requireLabelArg(rest, "show"));
+        case "seals":
+            return genomeSeals(configDir, requireLabelArg(rest, "seals"));
+        case "rm":
+            return genomeRm(configDir, requireLabelArg(rest, "rm"));
+        default:
+            return cannotAnswer(`genome: unknown subcommand '${sub ?? "<none>"}'`, "usage: abathur genome add <spec.jsonc> | list | show <label> | seals <label> | rm <label>");
+    }
+}
+export const genomeCommand = {
+    name: "genome",
+    summary: "add/list/show/seals/rm genome specs and their kernel seals",
+    run: ({ args }) => runGenome(args),
+};