@tachikomagundam/abathur 0.1.0

package/config/genomes/historian.example.jsonc

@@ -0,0 +1,124 @@
+// Historian genome instance (plan todo 14) — the first REAL genome.
+//
+// This file is a TEMPLATE: every machine-specific value is a ${ENV}-style
+// placeholder. Repo-tracked config must contain ZERO machine literals
+// (todo-15 grep gate). Materialize it for a live run by substituting the
+// placeholders from your environment into a PRIVATE copy (never committed),
+// then `abathur genome add <private-copy>`:
+//
+//   ${ABATHUR_HISTORIAN_REPO}  absolute path of the historian bench repo
+//                              (contains scenarios/, rubric.md, seed_sandbox.sh)
+//   ${ABATHUR_REPO}            absolute path of THIS Abathur checkout
+//                              (hosts graders/historian/*)
+//   ${ABATHUR_WIKI_BASE}       canonical wiki root, e.g. http://localhost:3000
+//                              (the /graphql endpoint is derived from it)
+//   ${ABATHUR_WIKI_OPS}        absolute path of the wiki-ops CLI script
+//
+// Live-run env the wrapper scripts require (exported by the operator shell,
+// never stored in config): ABATHUR_WIKI_KEY_FILE (wikijs admin token file;
+// defaults to $HOME/.wikijs-api-key inside the sandbox home).
+//
+// Bench protocol (src/bench/fixture.ts): per unit the adapter runs
+// reset -> seed -> run -> score in <configDir>/bench-sandboxes/<invId>/…
+// with HOME = the mirrored sandbox home; the scenario agent is spawned by
+// runCommand (opencode headless), the transcript is recorded at
+// $ABATHUR_TRANSCRIPT, and graderCommand emits the ONE-JSON-line score.
+//
+// Scoring (plan line 185, implemented in graders/historian/grader-core.mjs):
+// full scenarios Σ(w·d)/12 with pass = Σ ≥ 10 ∧ G = 1 (G hard gate);
+// scenario-05 renormalizes over the applicable set: (G+H+judgment)/3.
+// judgeCommand is deliberately UNWIRED: the fixture adapter never executes
+// it, so subjective dims A-D fall back to script-first mechanical proxies
+// (see the header comments in graders/historian/grader-core.mjs + learnings
+// §Todo 14).
+{
+  "label": "historian",
+  "repoPath": "${ABATHUR_HISTORIAN_REPO}",
+  "bench": {
+    "type": "opencode-fixture-scenarios",
+    "units": [
+      { "id": "scenario-01", "path": "scenarios/01-new-finding.md", "split": "train" },
+      { "id": "scenario-02", "path": "scenarios/02-incident.md", "split": "train" },
+      { "id": "scenario-03", "path": "scenarios/03-overlap-integration.md", "split": "train" },
+      { "id": "scenario-04", "path": "scenarios/04-organize-mess.md", "split": "val" },
+      { "id": "scenario-05", "path": "scenarios/05-worthiness-gate.md", "split": "train" },
+      { "id": "scenario-06", "path": "scenarios/06-incident-g1-format.md", "split": "train" },
+      { "id": "scenario-07", "path": "scenarios/07-zh-url-reporting.md", "split": "train" },
+      { "id": "scenario-08", "path": "scenarios/08-current-state-g5.md", "split": "train" },
+      { "id": "scenario-09", "path": "scenarios/09-timeline-week-groups.md", "split": "val" }
+    ],
+    "seedCommand": "bash ${ABATHUR_REPO}/graders/historian/seed-wrapped.sh ${ABATHUR_HISTORIAN_REPO}/seed_sandbox.sh",
+    "resetCommand": "bash ${ABATHUR_REPO}/graders/historian/reset-sandbox.sh",
+    "runCommand": "bash ${ABATHUR_REPO}/graders/historian/run-scenario.sh {unit.id} ${ABATHUR_HISTORIAN_REPO}/{unit.path}",
+    "graderCommand": "node ${ABATHUR_REPO}/graders/historian/grader.mjs {unit.id} ${ABATHUR_HISTORIAN_REPO}/{unit.path} ${ABATHUR_WIKI_BASE}",
+    "agentModel": "bailian-token-plan/qwen3.8-flash",
+    // Real agent runs, not unit tests: 1200s caps one stuck scenario without
+    // poisoning the generation (timeout => unscored/inconclusive, excluded by
+    // the stats layer). seed+reset hooks share a FIXED 60s adapter budget
+    // (fixture.ts HOOK_TIMEOUT_S) — measured full seed is 15.4s and reset
+    // (wiki-ops deletes + cache-refresh) ~15s, so both fit with margin.
+    "timeoutS": 1200,
+    "stats": {
+      "halfWidth": 0.15,
+      "minEffect": 0.1,
+      "nReps": { "initial": 1, "max": 3 }
+    }
+  },
+  // maxCandidates=3: the live campaign spends two generations on the
+  // back-to-back reset-equivalence proof (plan 182) and one on the bundle
+  // export AC (the first candidate trees sealed a too-short maskLiterals set,
+  // so their export correctly refuses — masking gate proven by refusal); a
+  // curator can lower this back to 1/2 once the campaign is archived. Wall/
+  // token caps are the hard stop for the live episode: 10 units x 2 benches x
+  // <=1200s worst case = 6.7h, so 8h bounds the run with slack (budget trip
+  // => inconclusive).
+  "budget": {
+    "maxCandidates": 3,
+    "maxModelCalls": 96,
+    "maxTokens": 80000000,
+    "maxWallS": 28800
+  },
+  // The bench surface is sealed: the mutator can never move scenario content,
+  // the rubric, the seeder, or the grading baseline (P5 / kernel audit).
+  "kernel": {
+    "immutableGlobs": [
+      "scenarios/**",
+      "rubric.md",
+      "seed_sandbox.sh",
+      "baseline/**",
+      "README.md"
+    ]
+  },
+  "requires": [
+    { "cmd": "python3", "args": ["${ABATHUR_WIKI_OPS}", "list"], "probeExit": 0 },
+    { "cmd": "curl", "args": ["-sf", "${ABATHUR_WIKI_BASE}"], "probeExit": 0 }
+  ],
+  "opencodeBinVersion": { "minVersion": "1.18.0" },
+  // Evidence masking for `bundle export` (todo 12): HOME + repoPath are always
+  // masked; the wiki origin plus the generic Unix roots below cover what live
+  // agents actually echo into transcripts (sandbox /tmp/... paths, /opt/wiki-ops
+  // CLI output, /mnt//var//etc host facts gathered during a scenario). The
+  // export gate fail-closes on ANY surviving /<machine-root>/, so without these
+  // declarations a real-run bundle refuses to write (observed live, task-14).
+  // The operator home root is intentionally absent here: HOME is masked
+  // automatically, and repo-tracked config must stay free of home-path literals
+  // (todo-15 grep gate).
+  "bundle": {
+    "maskLiterals": [
+      "${ABATHUR_WIKI_BASE}",
+      "/opt/",
+      "/tmp/",
+      "/var/",
+      "/etc/",
+      "/usr/",
+      "/mnt/",
+      "/srv/",
+      "/proc/",
+      "/sys/",
+      "/media/",
+      "/private/",
+      "/Users/",
+      "/root/"
+    ]
+  }
+}

package/dist/bench/adapter.js

@@ -0,0 +1,201 @@
+// Bench adapter contract (plan todo 5). The iface (incl. reset) is DEFINED HERE and
+// reused verbatim by the opencode-fixture adapter (todo 6) and the evolution loop
+// (todo 9). Shared plumbing also lives here so both adapters get identical argv
+// discipline — mirrors src/util/git.ts: argv arrays only, no shell, process-group
+// SIGKILL on timeout — and identical status semantics:
+//   ok            run completed under bench control (exitCode may still be != 0:
+//                 a failing UNIT is a measurement result, not an infra failure)
+//   timeout       killed after timeoutS via kill(-pid) — recorded, never rethrown
+//   infra_failed  the bench itself could not run (binary missing, spawn refused);
+//                 excluded from score distributions (hr discipline), not zeroed.
+import { spawn } from "node:child_process";
+import { cannotAnswer } from "../exit.js";
+export function unitVars(unit, sandboxDir) {
+    return { "unit.path": unit.path, "unit.id": unit.id, sandbox: sandboxDir, workdir: sandboxDir };
+}
+export function sandboxVars(sandboxDir) {
+    return { sandbox: sandboxDir, workdir: sandboxDir };
+}
+const PLACEHOLDER = /\{([A-Za-z0-9_.]+)\}/g;
+/**
+ * Render a bench command template into argv: quote-aware tokenization (single and
+ * double quotes group, are stripped), then {placeholder} substitution against vars.
+ * Unknown placeholders and unbalanced quotes are config errors -> exit 2 (fail-closed,
+ * never a silently half-substituted command).
+ */
+export function renderCommand(template, vars) {
+    const argv = tokenize(template);
+    if (argv.length === 0)
+        cannotAnswer(`bench command template is empty: '${template}'`);
+    return argv.map((token) => token.replace(PLACEHOLDER, (whole, key) => {
+        const value = vars[key];
+        if (value === undefined) {
+            cannotAnswer(`bench command '${template}': unknown placeholder '${whole}'`);
+        }
+        return value;
+    }));
+}
+function tokenize(source) {
+    const out = [];
+    let current = "";
+    let started = false;
+    let quote = null;
+    for (const ch of source) {
+        if (quote !== null) {
+            if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            started = true;
+            continue;
+        }
+        if (ch === " " || ch === "\t") {
+            if (started) {
+                out.push(current);
+                current = "";
+                started = false;
+            }
+            continue;
+        }
+        current += ch;
+        started = true;
+    }
+    if (quote !== null)
+        cannotAnswer(`unbalanced quote in bench command: '${source}'`);
+    if (started)
+        out.push(current);
+    return out;
+}
+const STREAM_CAP_BYTES = 1024 * 1024;
+/** SIGKILL the whole process group; ESRCH means everyone already exited. */
+export function killGroup(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // group already gone — the close handler still resolves the outcome.
+    }
+}
+/**
+ * Run argv (no shell) in a detached process group and hard-kill the GROUP after
+ * timeoutS, so children of the unit (sh -c sleep, opencode spawns) cannot outlive
+ * the bench. Resolves exactly once; never rejects — timeouts and spawn failures
+ * are recorded outcomes, matching the RunStatus trichotomy above.
+ */
+export function runChild(opts) {
+    if (!Number.isFinite(opts.timeoutS) || opts.timeoutS <= 0) {
+        throw new TypeError(`runChild: timeoutS must be a positive number, got ${String(opts.timeoutS)}`);
+    }
+    const [bin, ...rest] = opts.argv;
+    if (bin === undefined || bin.length === 0) {
+        throw new TypeError("runChild: argv must start with a binary path/name");
+    }
+    return new Promise((resolve) => {
+        const child = spawn(bin, rest, {
+            cwd: opts.cwd,
+            detached: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: opts.env === undefined
+                ? { ...process.env, LC_ALL: "C" }
+                : { ...process.env, ...opts.env, LC_ALL: "C" },
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let spawnError = null;
+        let notifyExit = () => { };
+        const exited = new Promise((resolve) => {
+            notifyExit = resolve;
+        });
+        if (opts.onChild !== undefined && child.pid !== undefined) {
+            opts.onChild({ pid: child.pid, exited }); // record BEFORE anything can wait on it
+        }
+        const cap = (buffer, chunk) => buffer.length >= STREAM_CAP_BYTES ? buffer : buffer + String(chunk);
+        child.stdout?.on("data", (chunk) => {
+            stdout = cap(stdout, chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = cap(stderr, chunk);
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup(child.pid);
+        }, Math.round(opts.timeoutS * 1000));
+        // Node emits 'close' after a failed spawn too (code null), so one resolve site.
+        child.on("error", (cause) => {
+            spawnError = cause.message;
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            notifyExit();
+            const kind = spawnError !== null ? "spawn_failed" : timedOut ? "timeout" : "exited";
+            const reason = spawnError !== null
+                ? `spawn failed: ${spawnError}`
+                : timedOut
+                    ? `killed after ${String(opts.timeoutS)}s: process group SIGKILL`
+                    : `exit code ${String(code)}`;
+            resolve({ kind, exitCode: kind === "exited" ? code : null, stdout, stderr, reason });
+        });
+    });
+}
+// ------------------------------------------------- shared adapter plumbing
+/** Metrics for a run that produced no measurement (timeout / infra_failed). */
+export const ZERO_METRICS = { tokensEst: 0, turns: 0 };
+export function childStatus(kind) {
+    switch (kind) {
+        case "exited":
+            return "ok";
+        case "timeout":
+            return "timeout";
+        case "spawn_failed":
+            return "infra_failed";
+    }
+}
+export function inconclusive(unitId, reason) {
+    return { kind: "inconclusive", unitId, reason };
+}
+export function firstLine(text) {
+    return (text.split("\n", 1)[0] ?? "").trim();
+}
+/** Grader contract (toy + fixture): the LAST stdout line parses to {unit, score 0..1, pass, metrics}. */
+export function parseGraderLine(stdoutText) {
+    const last = stdoutText
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .at(-1);
+    if (last === undefined)
+        return null;
+    let doc;
+    try {
+        doc = JSON.parse(last);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(doc) || typeof doc.unit !== "string")
+        return null;
+    if (!isFiniteNumber(doc.score) || doc.score < 0 || doc.score > 1)
+        return null;
+    if (typeof doc.pass !== "boolean")
+        return null;
+    const metrics = doc.metrics;
+    if (!isRecord(metrics) || !isCount(metrics.tokensEst) || !isCount(metrics.turns))
+        return null;
+    return { score: doc.score, pass: doc.pass, metrics: { tokensEst: metrics.tokensEst, turns: metrics.turns } };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isCount(value) {
+    return isFiniteNumber(value) && value >= 0;
+}

package/dist/bench/fixture-probe.js

@@ -0,0 +1,92 @@
+// Startup engine probes for the fixture-scenarios adapter (todo 6, plan 117-124):
+// `<opencodeBin> --version` parsed as semver and enforced against
+// spec.opencodeBinVersion.minVersion, plus every spec.requires[] binary probed by
+// argv spawn (PATH lookup, never a shell). Any failure is exit 2 BEFORE a unit
+// runs; every observed version string lands in the returned provenance list.
+import { cannotAnswer } from "../exit.js";
+import { loadConfig } from "../config.js";
+import { firstLine, runChild } from "./adapter.js";
+import { compareSemver, parseSemver, semverFromText } from "./fixture-support.js";
+const PROBE_TIMEOUT_S = 30;
+export function resolveOpencodeBin(opts) {
+    if (opts.opencodeBin !== undefined)
+        return opts.opencodeBin;
+    return loadConfig(opts.env ?? process.env).config.opencodeBin ?? "opencode";
+}
+export async function probeEngines(spec, bin, repoRoot, opts = {}) {
+    const observed = await probeOpencodeVersion(bin, repoRoot, opts);
+    const min = spec.opencodeBinVersion?.minVersion;
+    if (min !== undefined) {
+        const minVersion = parseSemver(min);
+        if (minVersion === null) {
+            cannotAnswer(`fixture: opencodeBinVersion.minVersion '${min}' is not a semver`);
+        }
+        if (compareSemver(observed.version, minVersion) < 0) {
+            cannotAnswer(`fixture: opencode ${observed.raw} is older than required minVersion ${min}`, "upgrade the opencode binary (config opencodeBin)");
+        }
+    }
+    const versions = [
+        { bin: "node", version: process.version },
+        { bin, version: observed.raw },
+    ];
+    for (const req of spec.requires ?? []) {
+        versions.push(await probeRequires(req, repoRoot, opts));
+    }
+    return versions;
+}
+async function probeOpencodeVersion(bin, cwd, opts) {
+    const probe = await runChild({
+        argv: [bin, "--version"],
+        cwd,
+        timeoutS: PROBE_TIMEOUT_S,
+        ...(opts.onChild === undefined ? {} : { onChild: opts.onChild }),
+    });
+    if (probe.kind !== "exited" || probe.exitCode !== 0) {
+        cannotAnswer(`fixture: '${bin} --version' failed (${probe.reason}) — no unit will run`, "set opencodeBin in config or install a supported opencode");
+    }
+    const observed = semverFromText(probe.stdout);
+    if (observed === null) {
+        cannotAnswer(`fixture: cannot parse a semver from '${bin} --version' output: ${firstLine(probe.stdout) || "no output"}`);
+    }
+    return observed;
+}
+/**
+ * Dry-run-only requires probe (task 14): verifies every spec.requires[] argv
+ * WITHOUT the opencode `--version` engine probe, so `run --dry-run` can prove
+ * machine prerequisites without spawning the engine or the mutator. Failure
+ * messages name the FULL argv (not just the binary) so a bad arg path is obvious.
+ * Returns the number of probes that passed.
+ */
+export async function probeRequiresOnly(spec, repoRoot) {
+    const reqs = spec.requires ?? [];
+    for (const req of reqs) {
+        const argv = [req.cmd, ...(req.args ?? ["--version"])];
+        const shown = argv.join(" ");
+        const outcome = await runChild({ argv, cwd: repoRoot, timeoutS: PROBE_TIMEOUT_S });
+        if (outcome.kind === "spawn_failed") {
+            cannotAnswer(`dry-run: prerequisite '${shown}' cannot spawn: ${outcome.reason}`, "install it or fix spec.requires before the real run");
+        }
+        if (outcome.kind !== "exited" || outcome.exitCode !== req.probeExit) {
+            cannotAnswer(`dry-run: prerequisite '${shown}' probe expected exit ${String(req.probeExit)}, got ${outcome.reason}`, "fix the prerequisite or spec.requires before the real run");
+        }
+    }
+    return reqs.length;
+}
+async function probeRequires(req, cwd, opts) {
+    const outcome = await runChild({
+        argv: [req.cmd, ...(req.args ?? ["--version"])],
+        cwd,
+        timeoutS: PROBE_TIMEOUT_S,
+        ...(opts.onChild === undefined ? {} : { onChild: opts.onChild }),
+    });
+    if (outcome.kind === "spawn_failed") {
+        cannotAnswer(`fixture: required prerequisite '${req.cmd}' is missing: ${outcome.reason}`, "install it or fix spec.requires before benching");
+    }
+    if (outcome.kind !== "exited" || outcome.exitCode !== req.probeExit) {
+        cannotAnswer(`fixture: prerequisite '${req.cmd}' probe expected exit ${String(req.probeExit)}, got ${outcome.reason}`);
+    }
+    return {
+        bin: req.cmd,
+        version: firstLine(outcome.stdout) || firstLine(outcome.stderr) || "no version output",
+    };
+}

package/dist/bench/fixture-support.js

@@ -0,0 +1,173 @@
+// Pure helpers behind the fixture-scenarios adapter (todo 6): semver probing,
+// the sandbox HOME mirror (copy-only, never symlink), the val-hiding scenario
+// manifest, and run-metadata parsing. No process state, no zod — everything is
+// deterministic given its inputs so reset→seed digests replay exactly.
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { cannotAnswer } from "../exit.js";
+import { canonicalJson } from "../core/ids.js";
+import { parseJsonc } from "../jsonc.js";
+const SEMVER = /v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/;
+export function parseSemver(text) {
+    const m = SEMVER.exec(text);
+    if (m === null)
+        return null;
+    const pre = m[4];
+    return {
+        major: Number(m[1]),
+        minor: Number(m[2]),
+        patch: Number(m[3]),
+        pre: pre === undefined || pre.length === 0 ? null : pre,
+    };
+}
+/** First line carrying a semver, as {raw, version}; raw is the whole trimmed line. */
+export function semverFromText(text) {
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const version = parseSemver(trimmed);
+        if (version !== null)
+            return { raw: trimmed, version };
+    }
+    return null;
+}
+export function compareSemver(a, b) {
+    for (const key of ["major", "minor", "patch"]) {
+        if (a[key] !== b[key])
+            return a[key] < b[key] ? -1 : 1;
+    }
+    if (a.pre === b.pre)
+        return 0;
+    if (a.pre === null)
+        return 1;
+    if (b.pre === null)
+        return -1;
+    return a.pre < b.pre ? -1 : 1;
+}
+// ------------------------------------------------------------- sandbox HOME
+export const SANDBOX_HOME_DIRNAME = ".sandbox-home";
+export const BENCH_DIRNAME = ".bench";
+/** Only this .opencode subset is mirrored from the real HOME (plan line 120). */
+const OPENCODE_SUBDIRS = ["plugin", "skills", "node_modules"];
+export function sandboxHomeDir(sandboxDir) {
+    return path.join(sandboxDir, SANDBOX_HOME_DIRNAME);
+}
+export function benchDir(sandboxDir) {
+    return path.join(sandboxDir, BENCH_DIRNAME);
+}
+export function transcriptPathFor(sandboxDir, unitId) {
+    return path.join(benchDir(sandboxDir), "transcripts", `${unitId}.jsonl`);
+}
+function copyDirIfExists(src, dst) {
+    if (!statSync(src, { throwIfNoEntry: false })?.isDirectory())
+        return;
+    try {
+        mkdirSync(path.dirname(dst), { recursive: true });
+        cpSync(src, dst, { recursive: true, dereference: true });
+    }
+    catch (cause) {
+        cannotAnswer(`fixture: cannot mirror sandbox home entry '${src}': ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+}
+function readConfigBase(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return {};
+    }
+    try {
+        const doc = file.endsWith(".jsonc") ? parseJsonc(text) : JSON.parse(text);
+        if (typeof doc === "object" && doc !== null && !Array.isArray(doc)) {
+            return doc;
+        }
+    }
+    catch {
+        // the copied config is the user's own malformed file: reset it to the mutation
+    }
+    return {};
+}
+/**
+ * Rebuild <sandbox>/.sandbox-home: .opencode/{plugin,skills,node_modules} copied from
+ * the real HOME, plus a COPY of the user's opencode config mutated with the scenario's
+ * agent model (never a symlink; real HOME is read-only for this adapter).
+ */
+export function mirrorSandboxHome(home, sandboxDir, agentModel) {
+    const sbHome = sandboxHomeDir(sandboxDir);
+    rmSync(sbHome, { recursive: true, force: true });
+    mkdirSync(sbHome, { recursive: true });
+    const srcOpen = path.join(home, ".opencode");
+    for (const sub of OPENCODE_SUBDIRS) {
+        copyDirIfExists(path.join(srcOpen, sub), path.join(sbHome, ".opencode", sub));
+    }
+    const srcCfg = path.join(home, ".config", "opencode");
+    const dstCfg = path.join(sbHome, ".config", "opencode");
+    copyDirIfExists(srcCfg, dstCfg);
+    mkdirSync(dstCfg, { recursive: true });
+    const jsonFile = path.join(dstCfg, "opencode.json");
+    const jsoncFile = path.join(dstCfg, "opencode.jsonc");
+    const base = existsSync(jsonFile)
+        ? readConfigBase(jsonFile)
+        : existsSync(jsoncFile)
+            ? readConfigBase(jsoncFile)
+            : {};
+    base["model"] = agentModel;
+    writeFileSync(jsonFile, `${canonicalJson(base)}\n`, "utf8");
+}
+/**
+ * Mutator-facing view: val scenarios appear as opaque aliases only — their id and
+ * path never enter the output unless the operator asked with includeVal.
+ */
+export function buildManifest(units, includeVal) {
+    return units.map((unit, index) => {
+        const alias = `scenario-${String(index + 1).padStart(2, "0")}`;
+        if (unit.split === "val" && !includeVal)
+            return { alias, split: "val" };
+        return { alias, split: unit.split, id: unit.id, path: unit.path };
+    });
+}
+export function manifestPathFor(sandboxDir) {
+    return path.join(benchDir(sandboxDir), "manifest.json");
+}
+export function writeManifest(sandboxDir, entries) {
+    mkdirSync(benchDir(sandboxDir), { recursive: true });
+    writeFileSync(manifestPathFor(sandboxDir), `${canonicalJson({ benchType: "opencode-fixture-scenarios", scenarios: entries })}\n`, "utf8");
+}
+/**
+ * Train/val discrimination is by SPLIT FIELD ONLY. allowVal = the caller's
+ * benching permission: operator includeVal OR the loop's internal
+ * loopValAuthority (see FixtureAdapterOptions; F1-fix2).
+ */
+export function gateVal(unit, allowVal) {
+    if (unit.split === "val" && !allowVal) {
+        cannotAnswer(`fixture: unit '${unit.id}' is a val-split scenario and requires the operator flag --include-val`, "the evolution loop benches val replicates under its internal loopValAuthority; this refusal is for a direct adapter consumer that never opted in — pass includeVal (CLI: 'abathur run --include-val', which additionally EXPOSES val ids/paths in the manifest)");
+    }
+}
+// ---------------------------------------------------------------- run meta
+/**
+ * Run-metadata contract: the fake/real runner may append a final JSON line
+ * {tokensEst?, turns?}; garbage or absence degrades to zeroed metrics, never a crash.
+ */
+export function parseRunMeta(stdoutText) {
+    const last = stdoutText
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .at(-1);
+    if (last === undefined)
+        return { tokensEst: 0, turns: 0 };
+    let doc;
+    try {
+        doc = JSON.parse(last);
+    }
+    catch {
+        return { tokensEst: 0, turns: 0 };
+    }
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        return { tokensEst: 0, turns: 0 };
+    const record = doc;
+    const count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+    return { tokensEst: count(record["tokensEst"]), turns: count(record["turns"]) };
+}