@tachikomagundam/abathur 0.1.0

package/dist/commands/status.js

@@ -0,0 +1,186 @@
+// `abathur status <label>` — a READ-ONLY ledger view. It never opens the Ledger
+// class (that mkdirs on first sight) and never touches worktrees: everything is
+// parsed from the ledger file plus one rev-parse. Ledger-sourced strings are
+// untrusted free text — every one is flattened before printing, so a hostile
+// reason/candidateId cannot forge table rows or terminal escapes.
+import { existsSync, readFileSync } from "node:fs";
+import { resolveConfigDir } from "../config.js";
+import { EXIT_OK, cannotAnswer } from "../exit.js";
+import { writeStdout } from "../out.js";
+import { INCUMBENT_BRANCH } from "../core/incumbent.js";
+import { ledgerPath, ledgerRecordSchema } from "../core/ledger.js";
+import { gitOpts } from "../core/genome-paths.js";
+import { decodeGenerationRecord } from "../core/evolve/run-bench.js";
+import { tryGit } from "../util/git.js";
+import { readRegistry } from "../core/genome.js";
+import { LEDGER_KIND_GRAFT_IMPORT, decodeGraftImport, listGraftQueue, } from "../core/graft-support.js";
+import { resolveUniqueEntry } from "./run.js";
+const KIND_GENERATION = "generation_complete";
+const KIND_PROMOTE = "promote";
+const KIND_TOMBSTONE = "tombstone";
+const USAGE = "usage: abathur status <label> [--last N]";
+function flat(value, max = 64) {
+    const one = value.replace(/[^ -~]/g, " ").replace(/\s+/g, " ").trim();
+    return one.length > max ? `${one.slice(0, max)}…` : one;
+}
+function readLedgerRecords(file) {
+    if (!existsSync(file))
+        return [];
+    const text = readFileSync(file, "utf8");
+    return text.split("\n").filter((l) => l.length > 0).map((line, idx) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return cannotAnswer(`status: ledger row ${String(idx + 1)} in ${file} is not JSON — refusing to render a partial truth`);
+        }
+        const check = ledgerRecordSchema.safeParse(parsed);
+        if (!check.success) {
+            return cannotAnswer(`status: ledger row ${String(idx + 1)} in ${file} violates the envelope schema: ${String(check.error.issues[0]?.message ?? "schema")}`);
+        }
+        return check.data;
+    });
+}
+function generations(records) {
+    return records
+        .filter((r) => r.kind === KIND_GENERATION && r.genId !== undefined)
+        .map((r) => ({ genId: r.genId, data: decodeGenerationRecord(r) }));
+}
+function verdictCell(data) {
+    return `verdict=${data.verdict ?? "—"}`;
+}
+function gainCell(data) {
+    if (data.gain === undefined)
+        return "gain=—";
+    if (data.gain === null)
+        return "gain=n/a";
+    return `gain=${data.gain >= 0 ? "+" : ""}${data.gain.toFixed(3)}`;
+}
+function counterCell(d) {
+    return `cand=${String(d.counters.candidates)} model=${String(d.counters.modelCalls)} tok=${String(d.counters.tokens)} wall=${d.counters.wallS.toFixed(2)}s`;
+}
+// Quarantine depth = candidate generations the stats gate nominated that the human
+// has NEVER decided: latest generation_complete row per genId says verdict=nominated
+// and no promote or tombstone row exists for that genId. Todo-12 graft imports are
+// "quarantined" by the same ledger shape (logged, undecided ⇒ counted here).
+function quarantineEntries(gens, records) {
+    const latest = new Map();
+    for (const g of gens)
+        latest.set(g.genId, g.data);
+    const decided = new Set(records.filter((r) => r.kind === KIND_PROMOTE || r.kind === KIND_TOMBSTONE).map((r) => String(r.genId)));
+    return [...latest.entries()]
+        .filter(([id, d]) => d.source === "candidate" && d.verdict === "nominated" && !decided.has(id))
+        .map(([id]) => flat(id, 40));
+}
+function sha12(sha) {
+    return sha.slice(0, 12);
+}
+async function runStatus(args) {
+    const positional = [];
+    let last = 10;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--last") {
+            const raw = Number(args[(i += 1)]);
+            if (!Number.isInteger(raw) || raw < 1 || raw > 1000)
+                cannotAnswer(`status: --last expects an integer 1..1000`, USAGE);
+            last = raw;
+        }
+        else if (arg.startsWith("--")) {
+            cannotAnswer(`status: unknown flag ${arg}`, USAGE);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    const label = positional[0];
+    if (label === undefined || positional.length !== 1)
+        cannotAnswer("status: expected exactly <label>", USAGE);
+    const configDir = resolveConfigDir();
+    // Todo 13: the pending-bench graft queue is a raw <configDir>/graft-queue/*
+    // read (graft-support owns the convention; status never Ledger.opens). An
+    // unregistered label with queued bundles still gets a queue view — the
+    // operator's "is my graft waiting?" question must be answerable by label.
+    const queue = listGraftQueue(configDir).filter((q) => q.genomeLabel === label);
+    const matches = readRegistry(configDir).entries.filter((e) => e.label === label);
+    if (matches.length > 1 || (matches.length === 0 && queue.length === 0)) {
+        resolveUniqueEntry(configDir, label, "status"); // identical ambiguity / not-registered exits
+    }
+    const entry = matches[0] ?? null;
+    if (entry === null) {
+        writeStdout(`genome: ${flat(label)} — not registered locally (pending-bench graft queue view)`);
+        renderQueue(queue);
+        return EXIT_OK;
+    }
+    const repo = entry.spec.repoPath;
+    const records = readLedgerRecords(ledgerPath(repo));
+    const gens = generations(records);
+    writeStdout(`genome: ${flat(entry.label)} (${entry.fingerprint})  repo: ${flat(repo, 200)}`);
+    const ref = await tryGit(["rev-parse", "--verify", "-q", `refs/heads/${INCUMBENT_BRANCH}`], gitOpts({}, repo));
+    const refSha = ref.ok ? ref.stdout.trim() : null;
+    const promoteRows = records.filter((r) => r.kind === KIND_PROMOTE);
+    const lastPromote = promoteRows.at(-1);
+    if (refSha === null) {
+        writeStdout(lastPromote === undefined
+            ? "incumbent: none"
+            : `incumbent: none (warning: last promote targeted ${String(lastPromote.data.to).slice(0, 12)} — the ${INCUMBENT_BRANCH} ref is missing)`);
+    }
+    else {
+        writeStdout(`incumbent: ${sha12(refSha)} (${INCUMBENT_BRANCH})`);
+        if (lastPromote !== undefined) {
+            const data = lastPromote.data;
+            const from = data.from === null || data.from === undefined ? "new branch" : String(data.from).slice(0, 12);
+            writeStdout(`  last promote: ${flat(String(data.genId ?? "?"), 40)} ${from} -> ${String(data.to ?? "?").slice(0, 12)} at ${lastPromote.ts}`);
+            if (String(data.to ?? "") !== refSha)
+                writeStdout(`  warning: ref ${sha12(refSha)} differs from last promote target — lineage moved outside promote`);
+        }
+    }
+    const quarantine = quarantineEntries(gens, records);
+    writeStdout(`quarantine depth: ${String(quarantine.length)}`);
+    if (quarantine.length > 0)
+        writeStdout(`  pending: ${quarantine.slice(0, 10).join(", ")}${quarantine.length > 10 ? ` (+${String(quarantine.length - 10)} more)` : ""}`);
+    renderQueue(queue);
+    renderGraftDecisions(records);
+    writeStdout(`generations (last ${String(Math.min(last, gens.length))} of ${String(gens.length)}):`);
+    for (const g of gens.slice(-last)) {
+        const who = g.data.source === "candidate" ? `candidate ${flat(g.data.candidateId ?? "?", 40)}` : "incumbent-baseline";
+        writeStdout(`  # ${flat(g.genId, 40)}  ${who}  ${verdictCell(g.data)}  ${gainCell(g.data)}  ${counterCell(g.data)}`);
+    }
+    const spent = { candidates: 0, modelCalls: 0, tokens: 0, wallS: 0 };
+    for (const g of gens) {
+        spent.candidates += g.data.counters.candidates;
+        spent.modelCalls += g.data.counters.modelCalls;
+        spent.tokens += g.data.counters.tokens;
+        spent.wallS += g.data.counters.wallS;
+    }
+    const caps = entry.spec.budget;
+    writeStdout(`budget: candidates ${String(spent.candidates)}/${String(caps.maxCandidates)}, modelCalls ${String(spent.modelCalls)}/${String(caps.maxModelCalls)}, tokens ${String(spent.tokens)}/${String(caps.maxTokens)}, wallS ${spent.wallS.toFixed(2)}/${String(caps.maxWallS)}`);
+    return EXIT_OK;
+}
+function renderQueue(queue) {
+    writeStdout(`pending-bench graft queue: ${String(queue.length)}`);
+    for (const q of queue) {
+        writeStdout(`  # ${sha12(q.bundleSha256)} bundle ${flat(q.bundlePath, 160)} reason ${flat(q.reason, 80)} queued ${flat(q.queuedAt, 40)}`);
+    }
+}
+// Quarantine section extension (todo 13): graft_import decision rows render
+// under their own heading — the generation-based quarantine depth above keeps
+// its exact todo-10 semantics. Undecodable rows are announced, never fabricated.
+function renderGraftDecisions(records) {
+    const rows = records.filter((r) => r.kind === LEDGER_KIND_GRAFT_IMPORT);
+    const decisions = rows.map((r) => decodeGraftImport(r.data)).filter((d) => d !== null);
+    writeStdout(`graft decisions: ${String(decisions.length)}`);
+    if (decisions.length !== rows.length) {
+        writeStdout(`  warning: ${String(rows.length - decisions.length)} graft_import row(s) unreadable — shown as depth, never invented`);
+    }
+    for (const d of decisions.slice(-10)) {
+        const source = d.sourceGenomeFingerprint === null ? "?" : sha12(d.sourceGenomeFingerprint);
+        writeStdout(`  # ${sha12(d.bundleSha256)} ${d.decision} source ${source} ${flat(d.reason, 100)}`);
+    }
+}
+export const statusCommand = {
+    name: "status",
+    summary: "read-only ledger view: incumbent, generations, quarantine depth, budget consumption",
+    run: ({ args }) => runStatus(args),
+};

package/dist/commands/tombstone.js

@@ -0,0 +1,72 @@
+// `abathur tombstone <label> <genId> --reason <text>` — cull is NOT delete:
+// this command only appends one ledger row. Commits, worktrees, and every prior
+// row survive; the reason is stored verbatim (canonicalJson escapes control
+// bytes) but NEVER echoed raw — the confirmation line is sanitized like todo-8's
+// sealMessage so untrusted text cannot forge terminal output.
+import { Ledger } from "../core/ledger.js";
+import { resolveConfigDir } from "../config.js";
+import { EXIT_OK, blocked, cannotAnswer } from "../exit.js";
+import { writeStdout } from "../out.js";
+import { resolveUniqueEntry } from "./run.js";
+const LEDGER_KIND_TOMBSTONE = "tombstone";
+const MAX_REASON_CHARS = 4000;
+const USAGE = "usage: abathur tombstone <label> <genId> --reason <text>";
+function echoed(reason) {
+    const flat = reason.replace(/[^ -~]/g, " ").replace(/\s+/g, " ").trim();
+    return flat.length > 120 ? `${flat.slice(0, 120)}…` : flat;
+}
+function parseArgs(args) {
+    const positional = [];
+    let reason = null;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--reason") {
+            const value = args[(i += 1)];
+            if (value === undefined || value.startsWith("--"))
+                cannotAnswer("tombstone: --reason requires a value", USAGE);
+            if (reason !== null)
+                cannotAnswer("tombstone: --reason given twice", USAGE);
+            reason = value;
+        }
+        else if (arg.startsWith("--")) {
+            cannotAnswer(`tombstone: unknown flag ${arg}`, USAGE);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    const [label, genId] = positional;
+    if (label === undefined || genId === undefined || positional.length !== 2)
+        cannotAnswer("tombstone: expected exactly <label> <genId>", USAGE);
+    if (reason === null || reason.trim().length === 0)
+        cannotAnswer("tombstone: --reason <text> is required (why is this lineage culled?)", USAGE);
+    if (reason.length > MAX_REASON_CHARS)
+        cannotAnswer(`tombstone: --reason exceeds ${String(MAX_REASON_CHARS)} chars`, USAGE);
+    return { label, genId, reason };
+}
+function runTombstone(args) {
+    const { label, genId, reason } = parseArgs(args);
+    const configDir = resolveConfigDir();
+    const entry = resolveUniqueEntry(configDir, label, "tombstone");
+    const ledger = Ledger.open(entry.spec.repoPath);
+    const records = ledger.readAll();
+    if (!records.some((r) => r.kind === "generation_complete" && r.genId === genId)) {
+        blocked(`tombstone: no generation_complete ledger row for gen '${genId}' of '${label}' — nothing to bury`);
+    }
+    const promoted = records.find((r) => r.kind === "promote" && r.genId === genId);
+    if (promoted !== undefined) {
+        blocked(`tombstone: gen '${genId}' was already promoted at ${promoted.ts} — cull is for candidates the human never accepted`);
+    }
+    const buried = records.find((r) => r.kind === LEDGER_KIND_TOMBSTONE && r.genId === genId);
+    if (buried !== undefined) {
+        blocked(`tombstone: gen '${genId}' is already tombstoned at ${buried.ts}`);
+    }
+    ledger.append({ kind: LEDGER_KIND_TOMBSTONE, genId, data: { genId, reason, actor: "cli" } });
+    writeStdout(`tombstone recorded: '${genId}' (reason: ${echoed(reason)}) — commits and lineage preserved (cull ≠ delete)`);
+    return EXIT_OK;
+}
+export const tombstoneCommand = {
+    name: "tombstone",
+    summary: "human gate: bury a candidate lineage with a reason (append-only; never deletes)",
+    run: ({ args }) => runTombstone(args),
+};

package/dist/config.js

@@ -0,0 +1,161 @@
+// Config resolution (todo 1 contract):
+//   file:        $ABATHUR_CONFIG (fail-closed if set) > ~/.config/abathur/config.jsonc
+//                > <package>/config/abathur.jsonc > built-in defaults
+//   overlay:     sibling `<base>.local.jsonc` (gitignored *.local.jsonc) deep-merged
+//                over the base before strict validation — machine-local values live there.
+// Every failure throws ConfigError, which the CLI boundary maps to exit 2.
+import { readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { parseJsonc } from "./jsonc.js";
+// JSONC normalization seam — re-exported so consumers/tests import it from the
+// config module (parser implementation lives in src/jsonc.ts).
+export { stripJsonc } from "./jsonc.js";
+export const configSchema = z.strictObject({
+    /** Absolute path to the `opencode` CLI binary; null = resolve from PATH at call time. */
+    opencodeBin: z.string().min(1).nullable().default(null),
+    /** Data home (ledger, registry, sandboxes); null = $ABATHUR_HOME else ~/.local/share/abathur. */
+    stateDir: z.string().min(1).nullable().default(null),
+});
+export class ConfigError extends Error {
+    kind;
+    filePath;
+    keys;
+    constructor(kind, message, filePath, keys) {
+        super(message);
+        this.kind = kind;
+        this.filePath = filePath;
+        this.keys = keys;
+        this.name = "ConfigError";
+    }
+}
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isReadableFile(candidate) {
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Shipped read-only defaults, co-located with the package (package.json "files"). */
+const repoConfigPath = fileURLToPath(new URL("../config/abathur.jsonc", import.meta.url));
+function resolveHome(env) {
+    return env.HOME === undefined || env.HOME.length === 0 ? os.homedir() : env.HOME;
+}
+function userConfigPath(env) {
+    return path.join(resolveHome(env), ".config", "abathur", "config.jsonc");
+}
+function readJsoncDocument(filePath) {
+    let text;
+    try {
+        text = readFileSync(filePath, "utf8");
+    }
+    catch {
+        throw new ConfigError("unreadable", `config: cannot read ${filePath}`, filePath);
+    }
+    let parsed;
+    try {
+        parsed = parseJsonc(text);
+    }
+    catch (cause) {
+        throw new ConfigError("malformed", `config: malformed JSONC in ${filePath}: ${errorMessage(cause)}`, filePath);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new ConfigError("malformed", `config: expected a top-level object in ${filePath}`, filePath);
+    }
+    return parsed;
+}
+// -------------------------------------------------------------- merge + validate
+/** Plain objects merge recursively; arrays and scalars are replaced wholesale (overlay wins). */
+export function deepMerge(base, overlay) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        const existing = out[key];
+        out[key] =
+            isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value;
+    }
+    return out;
+}
+function validateConfig(doc, origin) {
+    const result = configSchema.safeParse(doc);
+    if (result.success)
+        return result.data;
+    for (const issue of result.error.issues) {
+        if (issue.code === "unrecognized_keys") {
+            const listed = issue.keys.map((key) => `"${key}"`).join(", ");
+            throw new ConfigError("unknown-key", `config: unknown ${issue.keys.length === 1 ? "key" : "keys"} ${listed} in ${origin} — ` +
+                `allowed: ${Object.keys(configSchema.shape).join(", ")}`, origin, issue.keys);
+        }
+    }
+    const [first] = result.error.issues;
+    const where = first === undefined || first.path.length === 0 ? "<root>" : first.path.join(".");
+    const why = first === undefined ? "schema rejected the document" : first.message;
+    throw new ConfigError("invalid-value", `config: invalid value for "${where}" in ${origin}: ${why}`, origin);
+}
+// ------------------------------------------------------------------ resolution
+/**
+ * First existing file in: $ABATHUR_CONFIG (fail-closed when set) >
+ * ~/.config/abathur/config.jsonc > <package>/config/abathur.jsonc; null = built-in defaults.
+ */
+export function resolveConfigPath(env = process.env) {
+    const raw = env.ABATHUR_CONFIG;
+    if (raw !== undefined) {
+        if (raw.length === 0) {
+            throw new ConfigError("unreadable", "config: $ABATHUR_CONFIG is set but empty", raw);
+        }
+        if (!isReadableFile(raw)) {
+            throw new ConfigError("unreadable", `config: $ABATHUR_CONFIG points to an unreadable file: ${raw}`, raw);
+        }
+        return raw;
+    }
+    const user = userConfigPath(env);
+    if (isReadableFile(user))
+        return user;
+    if (isReadableFile(repoConfigPath))
+        return repoConfigPath;
+    return null;
+}
+/**
+ * Directory owning the writable config state (genome registry, todo 4+):
+ * parent of $ABATHUR_CONFIG when set, else the canonical ~/.config/abathur —
+ * which may not exist yet; callers mkdir -p on write. The shipped repo default
+ * under <package>/config/ is read-only and never used as a data dir.
+ */
+export function resolveConfigDir(env = process.env) {
+    const raw = env.ABATHUR_CONFIG;
+    if (raw !== undefined && raw.length > 0)
+        return path.dirname(path.resolve(raw));
+    return path.join(resolveHome(env), ".config", "abathur");
+}
+function overlayPathFor(basePath) {
+    return basePath.endsWith(".jsonc")
+        ? `${basePath.slice(0, -".jsonc".length)}.local.jsonc`
+        : `${basePath}.local.jsonc`;
+}
+/** Read base + `*.local.jsonc` overlay, deep-merge, JSONC-parse, zod-strict-validate. Throws ConfigError (→ exit 2). */
+export function loadConfig(env = process.env) {
+    const filePath = resolveConfigPath(env);
+    if (filePath === null) {
+        return {
+            config: validateConfig({}, "<abathur built-in defaults>"),
+            path: null,
+            overlayPath: null,
+        };
+    }
+    const base = readJsoncDocument(filePath);
+    const overlay = overlayPathFor(filePath);
+    if (!isReadableFile(overlay)) {
+        return { config: validateConfig(base, filePath), path: filePath, overlayPath: null };
+    }
+    const merged = deepMerge(base, readJsoncDocument(overlay));
+    const origin = `${filePath} (plus overlay ${overlay})`;
+    return { config: validateConfig(merged, origin), path: filePath, overlayPath: overlay };
+}

package/dist/core/bundle-common.js

@@ -0,0 +1,119 @@
+// Shared lineage-bundle plumbing (todo 12): tree access, contained-spec parsing,
+// benchDigest reconstruction and mask-plan construction — one implementation so
+// export and inspect can never drift apart.
+import { createHash } from "node:crypto";
+import { cannotAnswer } from "../exit.js";
+import { parseJsonc } from "../jsonc.js";
+import { benchDigest } from "./ids.js";
+import { genomeSpecSchema } from "./spec.js";
+import { buildMaskPlan } from "./bundle-mask.js";
+export const EVIDENCE_CAP_BYTES = 2 * 1024 * 1024;
+export const TREES_PREFIX = "trees/";
+export const EVIDENCE_PREFIX = "evidence/";
+export const sha256Hex = (data) => createHash("sha256").update(data).digest("hex");
+/** trees/<genId>/... member paths → the generation ids shipped in this bundle. */
+export function bundleGenIds(members) {
+    const ids = new Set();
+    for (const m of members) {
+        if (!m.path.startsWith(TREES_PREFIX))
+            continue;
+        const rest = m.path.slice(TREES_PREFIX.length);
+        const slash = rest.indexOf("/");
+        if (slash > 0)
+            ids.add(rest.slice(0, slash));
+    }
+    return [...ids].sort();
+}
+/** The primary generation — lexicographically greatest genId (ids embed a UTC
+ *  timestamp, so this is the newest). Export and inspect share this rule. */
+export function primaryGenId(genIds) {
+    const primary = [...genIds].sort().at(-1);
+    if (primary === undefined)
+        cannotAnswer("bundle: no trees/<genId>/ generation content inside");
+    return primary;
+}
+/** Rel-path → bytes map for one generation's tree members. */
+export function treeOf(members, genId) {
+    const prefix = `${TREES_PREFIX}${genId}/`;
+    const tree = new Map();
+    for (const m of members)
+        if (m.path.startsWith(prefix))
+            tree.set(m.path.slice(prefix.length), m.content);
+    return tree;
+}
+export function parseSpecMember(bytes, origin) {
+    let document;
+    try {
+        document = parseJsonc(new TextDecoder().decode(bytes));
+    }
+    catch (cause) {
+        return cannotAnswer(`bundle: malformed JSONC in ${origin}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const parsed = genomeSpecSchema.safeParse(document);
+    if (!parsed.success) {
+        cannotAnswer(`bundle: ${origin} is not a valid GenomeSpec: ${String(parsed.error.issues[0]?.message ?? "schema")}`);
+    }
+    return parsed.data;
+}
+export function containedSpec(tree, genId) {
+    const specBytes = tree.get("genome.jsonc");
+    if (specBytes === undefined)
+        cannotAnswer(`bundle: trees/${genId}/genome.jsonc missing — cannot self-describe the genome`);
+    return parseSpecMember(specBytes, `trees/${genId}/genome.jsonc`);
+}
+const SCRIPT_TOKEN = /^[A-Za-z0-9._/-]+\.(?:mjs|cjs|js|py|sh)$/;
+/** File-operand tokens of a command template that exist in the generation tree.
+ *  {placeholder} tokens never match, so unit paths stay out. */
+export function commandScriptPaths(template) {
+    return template
+        .split(/\s+/)
+        .map((tok) => tok.replace(/^["']|["'],?$/g, ""))
+        .filter((tok) => SCRIPT_TOKEN.test(tok) && !tok.includes("{"));
+}
+export function benchScriptsFor(spec, tree) {
+    const templates = [spec.bench.graderCommand, spec.bench.seedCommand, spec.bench.resetCommand];
+    const byPath = new Map();
+    for (const template of templates) {
+        if (template === undefined)
+            continue;
+        for (const p of commandScriptPaths(template)) {
+            const content = tree.get(p);
+            if (content !== undefined && !byPath.has(p))
+                byPath.set(p, { path: p, content });
+        }
+    }
+    return [...byPath.values()];
+}
+/** benchDigest recomputed from a generation's contained tree + spec (shared by
+ *  export "recompute at build" and inspect "re-verify"). */
+export function benchDigestFor(spec, tree, genId) {
+    const units = spec.bench.units.map((unit) => {
+        const content = tree.get(unit.path);
+        if (content === undefined)
+            cannotAnswer(`bundle: bench unit '${unit.id}' file '${unit.path}' absent from trees/${genId}/`);
+        return { unitId: unit.id, content };
+    });
+    return benchDigest({
+        units,
+        scripts: benchScriptsFor(spec, tree),
+        graderCommand: spec.bench.graderCommand,
+        runCommand: spec.bench.runCommand,
+        ...(spec.bench.judgeCommand === undefined ? {} : { judgeCommand: spec.bench.judgeCommand }),
+        ...(spec.bench.agentModel === undefined ? {} : { agentModel: spec.bench.agentModel }),
+        ...(spec.bench.judgeModel === undefined ? {} : { judgeModel: spec.bench.judgeModel }),
+        timeoutS: spec.bench.timeoutS,
+    });
+}
+export function maskPlanFor(spec, home) {
+    return buildMaskPlan({ home, repoPath: spec.repoPath, extra: spec.bundle?.maskLiterals ?? [] });
+}
+/** A runId is r-<genId>-<unitId>-<rep>; recover the rep and validate path safety. */
+export function repOfRunId(runId, genId, unitId) {
+    const prefix = `r-${genId}-${unitId}-`;
+    const rep = runId.startsWith(prefix) ? runId.slice(prefix.length) : "";
+    if (!/^\d+$/.test(rep)) {
+        cannotAnswer(`bundle: ledger runId '${runId}' does not match unit '${unitId}' of gen ${genId}`);
+    }
+    return rep;
+}
+export const PATH_SAFE = /^[A-Za-z0-9._-]+$/;