@tachikomagundam/abathur 0.1.0

package/dist/core/stats.js

@@ -0,0 +1,184 @@
+// Selection statistics (plan todo 7): nomination gates, Bonferroni correction,
+// Pareto ranking, budget-inconclusive verdicts. PURE functions only — budget
+// counters arrive as plain inputs, the seed is injectable, every threshold
+// comes from GenomeSpec.bench.stats (spec.ts), no I/O, no Date.now().
+//
+// SEMANTICS (plan-literal):
+//  - per-unit mean over nReps; the runner clamps nReps via clampReps (fixed
+//    count, no sequential escalation in v1). HARD RULE: n<2 on ANY candidate
+//    unit ⇒ variance undefined ⇒ verdict indeterminate, NEVER nominated; a
+//    val unit missing from the candidate entirely is the n=0 case of the same
+//    rule.
+//  - nomination gate (all three must hold, per pair): (1) CI half-width of the
+//    candidate's per-unit sample mean (95% Student-t, two-sided) ≤
+//    stats.halfWidth on every val unit of the incumbent's suite; (2) gain
+//    (aggregate train mean over the unit means, val-aggregate fallback when
+//    the bench has no train units) ≥ stats.minEffect; (3) no val regression:
+//    per-unit val mean ≥ incumbent mean − that unit's CI half-width (ties
+//    allowed ⇒ passes ⇔ delta ≥ −ciHalfWidth, evaluated with the SAME
+//    corrected alpha).
+//  - Bonferroni: family alpha 0.05 constant across finalist pairs; each pair's
+//    CI uses the corrected alpha FAMILY_ALPHA / nPairs (never configurable).
+//  - budget exhaustion (any cap at/above, counters vs caps) ⇒ inconclusive
+//    (exit 2 via VERDICT_EXIT), excluded from the comparison series, never an
+//    implicit pass. The gate itself is RNG-free; the only tie-break in this
+//    module is Pareto rank order, which takes an injectable seed.
+//  - Pareto over (trainScore, tokens, wallS); budget-truncated generations
+//    (complete:false) never enter the set.
+//
+// The inverse Student-t lives in stats-math.ts and the Pareto ranking in
+// stats-pareto.ts; both are re-exported here so the public surface of this
+// module — the one todos 9/10/12 consume — is unchanged. Accuracy: |t − table|
+// < 1e-3 for the t-distribution rows checked in stats.test.ts (df=1..30, α=0.05).
+import { EXIT_BLOCKED, EXIT_CANNOT_ANSWER, EXIT_OK } from "../exit.js";
+/** Per-unit replicate scores (train and val units alike). */
+import { studentTQuantile } from "./stats-math.js";
+import { seededRandom, paretoFrontier } from "./stats-pareto.js";
+export { studentTQuantile, seededRandom, paretoFrontier };
+/** Family-wise alpha across finalist pairs (bonferroniAlpha divides it). */
+export const FAMILY_ALPHA = 0.05;
+/** Verdict → process exit code. inconclusive = 2 (cannot answer), never 0. */
+export const VERDICT_EXIT = {
+    nominated: EXIT_OK, // 0 — gate recommends acceptance
+    culled: EXIT_BLOCKED, // 1 — decision: rejected by the gates
+    indeterminate: EXIT_BLOCKED, // 1 — decision: insufficient evidence to nominate
+    inconclusive: EXIT_CANNOT_ANSWER, // 2 — budget truncated the run; cannot answer
+};
+export function needsExit(verdict) {
+    return VERDICT_EXIT[verdict];
+}
+export function bonferroniAlpha(nPairs) {
+    if (!Number.isInteger(nPairs) || nPairs < 1) {
+        throw new RangeError(`bonferroniAlpha: nPairs=${String(nPairs)} must be an integer >= 1`);
+    }
+    return FAMILY_ALPHA / nPairs;
+}
+// --- Student-t quantile (no deps: bisection on the regularized incomplete beta) ---
+/** Per-unit summary: mean, unbiased variance, 95% two-sided CI half-width. */
+export function summarizeUnit(scores, alpha = FAMILY_ALPHA) {
+    const n = scores.length;
+    if (n < 2) {
+        return { n, mean: n === 1 ? scores[0] : Number.NaN, sampleVariance: Number.NaN, sem: Number.NaN, ciHalfWidth: Number.NaN, indeterminate: true };
+    }
+    let sum = 0;
+    for (const s of scores)
+        sum += s;
+    const mean = sum / n;
+    let ss = 0;
+    for (const s of scores) {
+        const d = s - mean;
+        ss += d * d;
+    }
+    const sampleVariance = ss / (n - 1);
+    const sem = Math.sqrt(sampleVariance / n);
+    return { n, mean, sampleVariance, sem, ciHalfWidth: studentTQuantile(alpha, n - 1) * sem, indeterminate: false };
+}
+/** Aggregate bench score: mean over train unit means; val fallback when the bench has no train units. */
+export function aggregateScore(units) {
+    const train = units.filter((u) => u.split === "train");
+    const pool = train.length > 0 ? train : units;
+    let sum = 0;
+    for (const u of pool)
+        sum += summarizeUnit(u.scores).mean;
+    return sum / pool.length;
+}
+/** `--reps N` clamps into [nReps.initial, nReps.max]; absent ⇒ initial (no sequential escalation in v1). */
+export function clampReps(requested, nReps) {
+    const target = requested !== undefined && Number.isFinite(requested) ? requested : nReps.initial;
+    return Math.min(nReps.max, Math.max(nReps.initial, target));
+}
+/** Any cap at/above ⇒ exhausted. Counters arrive as plain inputs — no I/O. */
+export function budgetExhausted(counters, caps) {
+    return (counters.candidates >= caps.maxCandidates ||
+        counters.modelCalls >= caps.maxModelCalls ||
+        counters.tokens >= caps.maxTokens ||
+        counters.wallS >= caps.maxWallS);
+}
+function fmt(x) {
+    return Number.isFinite(x) ? x.toFixed(4) : String(x);
+}
+function budgetFailureLines(counters, caps) {
+    const rows = [
+        ["candidates", counters.candidates, caps.maxCandidates],
+        ["modelCalls", counters.modelCalls, caps.maxModelCalls],
+        ["tokens", counters.tokens, caps.maxTokens],
+        ["wallS", counters.wallS, caps.maxWallS],
+    ];
+    return rows
+        .filter(([, used, cap]) => used >= cap)
+        .map(([name, used, cap]) => `budget exhausted: ${name}=${used}/${cap}`);
+}
+/**
+ * Nomination gate for ONE finalist pair (candidate vs incumbent). The verdict
+ * never inspects the world: thresholds come from stats, budget counters and
+ * caps are plain values, and the gate is RNG-free (no tie-break needed).
+ */
+export function evaluate(input) {
+    const { candidate, incumbent, stats, budgetCaps, nPairs } = input;
+    const alpha = bonferroniAlpha(nPairs);
+    const base = {
+        runId: candidate.runId,
+        counters: candidate.counters,
+        caps: budgetCaps,
+        minEffect: stats.minEffect,
+        effectiveAlpha: alpha,
+        nPairs,
+    };
+    // 1) Budget exhaustion short-circuits: inconclusive, excluded from the
+    //    comparison series, never an implicit pass even when metrics look great.
+    if (budgetExhausted(candidate.counters, budgetCaps)) {
+        return { ...base, verdict: "inconclusive", exitCode: needsExit("inconclusive"), gain: null, unitComparisons: [], failures: budgetFailureLines(candidate.counters, budgetCaps) };
+    }
+    const candByUnit = new Map(candidate.units.map((u) => [u.unitId, u]));
+    const incByUnit = new Map(incumbent.units.map((u) => [u.unitId, u]));
+    const failures = [];
+    // 2) HARD RULE nReps ≥ 2: n<2 on ANY candidate unit (or a val unit missing
+    //    from the candidate ⇒ n=0) leaves the variance undefined.
+    for (const unit of candidate.units) {
+        if (unit.scores.length < 2) {
+            failures.push(`n=${unit.scores.length} on unit '${unit.unitId}': variance undefined — indeterminate, never nominated`);
+        }
+    }
+    for (const [unitId, incUnit] of incByUnit) {
+        if (incUnit.split === "val" && !candByUnit.has(unitId)) {
+            failures.push(`no replicates for val unit '${unitId}' on candidate '${candidate.runId}' — variance undefined, never nominated`);
+        }
+    }
+    if (failures.length > 0) {
+        return { ...base, verdict: "indeterminate", exitCode: needsExit("indeterminate"), gain: aggregateScore(candidate.units) - aggregateScore(incumbent.units), unitComparisons: [], failures };
+    }
+    // 3) Per-val-unit comparisons + the two precision gates.
+    const unitComparisons = [];
+    for (const [unitId, incUnit] of incByUnit) {
+        if (incUnit.split !== "val")
+            continue;
+        const candUnit = candByUnit.get(unitId);
+        if (candUnit === undefined)
+            continue; // already ruled indeterminate above
+        const cs = summarizeUnit(candUnit.scores, alpha);
+        const incumbentMean = summarizeUnit(incUnit.scores).mean;
+        const delta = cs.mean - incumbentMean;
+        unitComparisons.push({
+            unitId,
+            candidateMean: cs.mean,
+            incumbentMean,
+            ciHalfWidth: cs.ciHalfWidth,
+            delta,
+            ciPasses: cs.ciHalfWidth <= stats.halfWidth,
+            passes: delta >= -cs.ciHalfWidth, // ties allowed
+        });
+        if (cs.ciHalfWidth > stats.halfWidth) {
+            failures.push(`CI half-width ${fmt(cs.ciHalfWidth)} > halfWidth ${fmt(stats.halfWidth)} on unit '${unitId}'`);
+        }
+        if (delta < -cs.ciHalfWidth) {
+            failures.push(`regression on unit '${unitId}': delta ${fmt(delta)} < ${fmt(-cs.ciHalfWidth)} (mean ${fmt(cs.mean)} < ${fmt(incumbentMean)} - ${fmt(cs.ciHalfWidth)})`);
+        }
+    }
+    // 4) Effect-size floor on the aggregate gain.
+    const gain = aggregateScore(candidate.units) - aggregateScore(incumbent.units);
+    if (gain < stats.minEffect) {
+        failures.push(`gain ${fmt(gain)} < minEffect ${fmt(stats.minEffect)}`);
+    }
+    const verdict = failures.length === 0 ? "nominated" : "culled";
+    return { ...base, verdict, exitCode: needsExit(verdict), gain, unitComparisons, failures };
+}

package/dist/core/worktree.js

@@ -0,0 +1,190 @@
+// Git worktree generation store (todo 3).
+//
+// Cache-path scheme:
+//   $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
+//
+// Invariants upheld here:
+//   - generations live in detached worktrees under the cache root — abathur NEVER
+//     commits into the genome repo's checked-out branch and never mutates the
+//     user's main worktree (dirty target paths are a refusal, not a fix);
+//   - no push and no ref update without a compare-and-swap old-value here —
+//     abathur/incumbent moves fast-forward-only (todo 10 consumes that helper);
+//   - every git call goes through src/util/git.ts (execFile array argv, timeout).
+import { mkdir, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { blocked, cannotAnswer } from "../exit.js";
+import { git, tryGit } from "../util/git.js";
+import { generationPath, genomeDir, gitOpts, requireRev, SNAPSHOTS_DIR, } from "./genome-paths.js";
+import { removeFrozenTree } from "./snapshot.js";
+export { cacheRoot } from "./genome-paths.js";
+export { snapshotCommit } from "./snapshot.js";
+export { INCUMBENT_BRANCH, fastForwardIncumbent } from "./incumbent.js";
+const DAY_MS = 86_400_000;
+/** Fixed committer identity for sealed generations (repo config is never trusted or touched). */
+const SEAL_IDENTITY = ["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local"];
+// ------------------------------------------------------------------ openGenome
+/** Porcelain v1 with -z: "XY path" records; rename/copy records carry the source as an extra NUL field. */
+function parsePorcelain(raw) {
+    const tokens = raw.split("\0");
+    const out = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === undefined || token.length < 4)
+            continue;
+        const entry = { xy: token.slice(0, 2), file: token.slice(3) };
+        out.push(entry);
+        const kind = entry.xy.charAt(0);
+        if (kind === "R" || kind === "C")
+            i += 1; // consume rename/copy source
+    }
+    return out;
+}
+function normalizeTarget(repo, target) {
+    const rel = path.relative(repo, path.resolve(repo, target));
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        cannotAnswer(`worktree: target path "${target}" is outside the genome repo ${repo}`);
+    }
+    return rel; // "" === whole repo
+}
+function isUnder(file, target) {
+    return target === "" || file === target || file.startsWith(`${target}/`);
+}
+/**
+ * Verify the genome repo is a usable worktree base and return dirtiness data.
+ * Refusal (blocked, exit 1) happens ONLY when a path under `targetPaths` is
+ * dirty (tracked modifications, staged changes, or untracked files); dirtiness
+ * elsewhere is returned as `dirtyWorktree` notices for the ledger.
+ */
+export async function openGenome(repoPath, targetPaths = [], opts = {}) {
+    const repo = path.resolve(repoPath);
+    const dirStat = await stat(repo).catch(() => null);
+    if (dirStat === null || !dirStat.isDirectory()) {
+        blocked(`worktree: genome repo not found at ${repo}`, "clone the genome first");
+    }
+    const gopts = gitOpts(opts, repo);
+    const inside = await tryGit(["rev-parse", "--git-dir"], gopts);
+    if (!inside.ok) {
+        blocked(`worktree: ${repo} is not a git repository`, inside.error.stderr.trim());
+    }
+    const bare = await git(["rev-parse", "--is-bare-repository"], gopts);
+    if (bare.stdout.trim() === "true") {
+        blocked(`worktree: ${repo} is a bare repo — genomes must be full working copies (the ledger lives in-tree)`);
+    }
+    const head = await tryGit(["rev-parse", "HEAD"], gopts);
+    if (!head.ok) {
+        blocked(`worktree: ${repo} has no commits — seed the genome before opening it`);
+    }
+    const branchRun = await tryGit(["rev-parse", "--abbrev-ref", "HEAD"], gopts);
+    const status = await git(["status", "--porcelain=v1", "-z", "--untracked-files=all"], gopts);
+    const entries = parsePorcelain(status.stdout);
+    const targets = targetPaths.map((t) => normalizeTarget(repo, t));
+    const underTarget = (e) => targets.some((t) => isUnder(e.file, t));
+    const dirtyTargets = entries.filter(underTarget);
+    if (dirtyTargets.length > 0) {
+        blocked(`worktree: refusing to open ${repo}: dirty target path(s): ${dirtyTargets
+            .map((e) => `${e.xy} ${e.file}`)
+            .join(", ")}`, "commit or restore them first — abathur never mutates your worktree");
+    }
+    return {
+        repoPath: repo,
+        headCommit: head.stdout.trim(),
+        branch: branchRun.ok ? branchRun.stdout.trim() : "HEAD",
+        dirtyWorktree: entries.filter((e) => !underTarget(e)),
+    };
+}
+// -------------------------------------------------------------- generations
+/** `git worktree add --detach <cache>/<genomeFp>/<genId> <parentCommit>`; rev may be a sha or a safe ref name. */
+export async function newGeneration(genome, parentCommit, genId, opts = {}) {
+    const env = opts.env ?? process.env;
+    const wt = generationPath(env, genome, genId); // validates both segments (exit 2 on junk)
+    const rev = requireRev(parentCommit); // validates before any git spawn
+    const repo = path.resolve(genome.repoPath);
+    if ((await stat(wt).catch(() => null)) !== null) {
+        cannotAnswer(`worktree: generation directory already exists: ${wt}`);
+    }
+    await mkdir(path.dirname(wt), { recursive: true });
+    const added = await tryGit(["worktree", "add", "--detach", wt, rev], gitOpts(opts, repo));
+    if (!added.ok) {
+        const why = added.error.stderr.trim().split("\n")[0] ?? added.error.message;
+        blocked(`worktree: cannot create generation ${genId} from ${rev}: ${why}`, "is the parent commit reachable in the genome repo?");
+    }
+    const head = await git(["rev-parse", "HEAD"], gitOpts(opts, wt));
+    return { worktreePath: wt, parentCommit: head.stdout.trim() };
+}
+/** Stage everything inside the generation worktree and commit it; returns commit + tree shas. */
+export async function sealGeneration(genome, genId, message, opts = {}) {
+    const env = opts.env ?? process.env;
+    const wt = generationPath(env, genome, genId);
+    if ((await stat(wt).catch(() => null)) === null) {
+        blocked(`worktree: generation ${genId} not found under ${path.dirname(wt)}`, "open a generation with newGeneration first");
+    }
+    const gopts = gitOpts(opts, wt);
+    const attached = await tryGit(["symbolic-ref", "-q", "HEAD"], gopts);
+    if (attached.ok) {
+        blocked(`worktree: refusing to seal ${genId} — generations must be detached from branches`, "this worktree is on a live branch; abathur never commits there");
+    }
+    const porcelain = await git(["status", "--porcelain", "--untracked-files=all"], gopts);
+    if (porcelain.stdout.length === 0) {
+        blocked(`worktree: nothing to seal in generation ${genId} — stage a mutation first`);
+    }
+    await git(["add", "-A"], gopts);
+    // `-m${message}` as ONE argv element: a dash-leading message can never be parsed as an option.
+    await git([...SEAL_IDENTITY, "commit", "-q", `-m${message}`], gopts);
+    const commitSha = (await git(["rev-parse", "HEAD"], gopts)).stdout.trim();
+    const treeSha = (await git(["rev-parse", "HEAD^{tree}"], gopts)).stdout.trim();
+    return { commitSha, treeSha };
+}
+// ------------------------------------------------------------------ cleanup
+async function listOrEmpty(dir) {
+    try {
+        return await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Remove generation/snapshot dirs older than `olderThanDays` (0 = everything)
+ * and prune the repo's dead worktree registry entries. Idempotent: a second
+ * run reports nothing. Frozen snapshot dirs are thawed before removal.
+ */
+export async function cleanupStale(genome, olderThanDays, opts = {}) {
+    if (!Number.isFinite(olderThanDays) || olderThanDays < 0) {
+        cannotAnswer("worktree: olderThanDays must be a finite number >= 0");
+    }
+    const env = opts.env ?? process.env;
+    const dir = genomeDir(env, genome); // validates the fingerprint
+    const cutoff = Date.now() - olderThanDays * DAY_MS;
+    const roots = [];
+    for (const name of await listOrEmpty(dir)) {
+        if (name !== SNAPSHOTS_DIR)
+            roots.push(path.join(dir, name));
+    }
+    const snapRoot = path.join(dir, SNAPSHOTS_DIR);
+    for (const name of await listOrEmpty(snapRoot)) {
+        roots.push(path.join(snapRoot, name));
+    }
+    const removed = [];
+    const kept = [];
+    for (const p of roots) {
+        const st = await stat(p).catch(() => null);
+        if (st === null)
+            continue;
+        if (st.mtimeMs <= cutoff) {
+            await removeFrozenTree(p);
+            removed.push(p);
+        }
+        else {
+            kept.push(p);
+        }
+    }
+    // Prune AFTER removal: dirs we just deleted leave dead registry entries that
+    // would otherwise block re-adding a generation with the same id.
+    const pruned = await tryGit(["worktree", "prune"], gitOpts(opts, path.resolve(genome.repoPath)));
+    if (!pruned.ok) {
+        blocked(`worktree: cannot prune the worktree registry of ${genome.repoPath}: ${pruned.error.stderr.trim()}`);
+    }
+    return { removed, kept };
+}

package/dist/exit.js

@@ -0,0 +1,32 @@
+// Exit-code contract (family-wide, border/README.md:289-296):
+//   0 = ok/pass            1 = blocked/failed (decision)   2 = cannot-answer (tool error:
+//                             config error, malformed input, missing engine, lock holder)
+// Handlers never touch process directly: they return 0 or throw ExitSignal; the CLI
+// boundary (src/cli.ts main) renders one clean line per failure and sets process.exitCode.
+export const EXIT_OK = 0;
+export const EXIT_BLOCKED = 1;
+export const EXIT_CANNOT_ANSWER = 2;
+/** Control-flow exception carrying the process exit code for the current run. */
+export class ExitSignal extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = "ExitSignal";
+    }
+}
+/** Gate blocked the action (HIGH/CRITICAL verdict, refused promote, ...). */
+export function blocked(message, hint) {
+    throw new ExitSignal(EXIT_BLOCKED, message, hint);
+}
+/** The harness could not answer: config/engine/input error. Never exit 0 on this class. */
+export function cannotAnswer(message, hint) {
+    throw new ExitSignal(EXIT_CANNOT_ANSWER, message, hint);
+}
+/** Single-line rendering used by the CLI boundary for every ExitSignal. */
+export function renderExitSignal(signal) {
+    const base = `abathur: ${signal.message}`;
+    return signal.hint === undefined ? base : `${base}\n  hint: ${signal.hint}`;
+}

package/dist/genomes/toy-smoke/genome.jsonc

@@ -0,0 +1,30 @@
+{
+  "label": "toy-smoke",
+  "repoPath": ".",
+  "bench": {
+    "type": "toy",
+    "units": [
+      { "id": "add", "path": "units/add.mjs", "split": "train" },
+      { "id": "mul", "path": "units/mul.mjs", "split": "train" },
+      { "id": "explode", "path": "units/explode.mjs", "split": "train" },
+      { "id": "sub", "path": "units/sub.mjs", "split": "val" }
+    ],
+    "runCommand": "node {unit.path}",
+    "graderCommand": "node grader.mjs {unit.path}",
+    "timeoutS": 10,
+    "stats": {
+      "halfWidth": 0.25,
+      "minEffect": 0.5,
+      "nReps": { "initial": 2, "max": 4 }
+    }
+  },
+  "budget": {
+    "maxCandidates": 4,
+    "maxModelCalls": 16,
+    "maxTokens": 100000,
+    "maxWallS": 300
+  },
+  "kernel": {
+    "immutableGlobs": ["grader.mjs"]
+  }
+}

package/dist/genomes/toy-smoke/grader.mjs

@@ -0,0 +1,61 @@
+// Toy grader (plan todo 5): script-first, model-free. Consumes a unit path (argv[2],
+// resolved against cwd), imports the unit module, and scores it from its exported
+// `checks(): boolean[]` contract. Prints EXACTLY one JSON line on success:
+//   {unit, score 0..1, pass, metrics {tokensEst, turns}}
+// Any problem (missing file, import throw, contract violation) => one stderr line
+// and exit 1 with NO JSON — the adapter maps that to an inconclusive-for-unit.
+// NOTE: importing executes unit top-level code; units must guard side effects with
+// the standard `isMain` check (see units/*.mjs), exactly like Python __main__.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const BYTES_PER_TOKEN = 4;
+
+const unitArg = process.argv[2];
+if (typeof unitArg !== "string" || unitArg.length === 0) fail("usage: node grader.mjs <unitPath>");
+
+const unitAbs = path.resolve(process.cwd(), unitArg);
+let bytes;
+try {
+  bytes = readFileSync(unitAbs);
+} catch {
+  fail(`unit file not readable: ${unitArg}`);
+}
+
+let mod;
+try {
+  mod = await import(pathToFileURL(unitAbs).href);
+} catch (cause) {
+  fail(`unit import failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+}
+
+if (typeof mod.checks !== "function") fail("unit does not export checks(): boolean[]");
+
+let results;
+try {
+  results = mod.checks();
+} catch (cause) {
+  fail(`checks() threw: ${cause instanceof Error ? cause.message : String(cause)}`);
+}
+
+if (!Array.isArray(results) || results.length === 0) fail("checks() must return a non-empty array");
+if (!results.every((r) => typeof r === "boolean")) fail("checks() must return booleans only");
+
+const passes = results.filter((r) => r).length;
+const line = {
+  unit: unitArg,
+  score: passes / results.length,
+  pass: passes === results.length,
+  metrics: {
+    tokensEst: Math.ceil(bytes.length / BYTES_PER_TOKEN),
+    turns: results.length,
+  },
+};
+process.stdout.write(`${JSON.stringify(line)}\n`);
+
+function fail(reason) {
+  process.stderr.write(`grader: ${reason}\n`);
+  process.exit(1);
+}

package/dist/genomes/toy-smoke/init.mjs

@@ -0,0 +1,63 @@
+// Toy-smoke self-init (plan todo 5): `node init.mjs <destDir>` materializes an
+// independent toy genome repo in destDir:
+//   1. copy this template dir (skipping any .git/.state) into destDir,
+//   2. rewrite genome.jsonc repoPath to the absolute destDir (paths are GENERATED
+//      at runtime — nothing on disk hardcodes a machine path, D7),
+//   3. when no .git exists, `git init` + full commit so todo-3 worktree flows work.
+// Prints the destDir on stdout. Usage errors exit 2.
+
+import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const destArg = process.argv[2];
+if (typeof destArg !== "string" || destArg.length === 0) {
+  process.stderr.write("usage: node init.mjs <destDir>\n");
+  process.exit(2);
+}
+const dest = path.resolve(destArg);
+if (dest === here) {
+  process.stderr.write("init: destDir must differ from the template directory\n");
+  process.exit(2);
+}
+
+if (!existsSync(path.join(here, "genome.jsonc"))) {
+  process.stderr.write(`init: template dir ${here} has no genome.jsonc\n`);
+  process.exit(2);
+}
+
+cpSync(here, dest, {
+  recursive: true,
+  filter: (src) => {
+    const rel = path.relative(here, src);
+    return rel !== ".git" && !rel.startsWith(`.git${path.sep}`) && rel !== ".state" && !rel.startsWith(`.state${path.sep}`);
+  },
+});
+
+const specPath = path.join(dest, "genome.jsonc");
+const spec = JSON.parse(readFileSync(specPath, "utf8"));
+spec.repoPath = dest;
+writeFileSync(specPath, `${JSON.stringify(spec, null, 2)}\n`, "utf8");
+
+if (!existsSync(path.join(dest, ".git"))) {
+  git(["init", "-b", "main"]);
+  git(["add", "-A"]);
+  // identity pinned via -c BEFORE the subcommand (global gitconfig immune;
+  // `git init` itself rejects -c after the subcommand — learnings todo 3).
+  git(["-c", "user.name=abathur", "-c", "user.email=abathur@harness.local", "commit", "-m", "toy-smoke fixture seed"]);
+}
+
+process.stdout.write(`${dest}\n`);
+
+function git(args) {
+  const run = spawnSync("git", args, { cwd: dest, encoding: "utf8" });
+  if (run.error !== undefined && run.error !== null) {
+    throw new Error(`init: cannot spawn git: ${run.error.message}`);
+  }
+  if (run.status !== 0) {
+    throw new Error(`git ${args.join(" ")} failed (${String(run.status)}): ${(run.stderr ?? "").trim()}`);
+  }
+}

package/dist/genomes/toy-smoke/units/add.mjs

@@ -0,0 +1,17 @@
+// Toy unit: add — shipped WITH A SEEDED BUG (subtraction). The stub-mutators
+// 'fix-add' scripted patch flips it to the correct sum; grader checks() grade it.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const isMain =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+export function add(a, b) {
+  return a - b; // seeded bug: must be `return a + b;`
+}
+
+export function checks() {
+  return [add(2, 3) === 5, add(0, 7) === 7, add(-1, 1) === 0];
+}
+
+if (isMain) console.log(`add(2,3)=${add(2, 3)}`);

package/dist/genomes/toy-smoke/units/explode.mjs

@@ -0,0 +1,4 @@
+// Toy unit: explode — exits 1 at import time. run() sees status ok + exitCode 1;
+// score() sees the grader die mid-import with exit 1 and must record the unit as
+// inconclusive, never crash the bench (plan AC (d)).
+process.exit(1);

package/dist/genomes/toy-smoke/units/hang.mjs

@@ -0,0 +1,16 @@
+// Toy unit: hang — blocks far longer than any test timeout via `exec sleep`
+// (learnings: execFile-without-input closes stdin, so hang fixtures must exec
+// sleep, never cat). Fixture for AC (e): the adapter must SIGKILL the whole
+// process group (node + sh + sleep) and record status timeout.
+import { execSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const isMain =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+export function checks() {
+  return [true];
+}
+
+if (isMain) execSync("sleep 31.7", { stdio: "ignore" });

package/dist/genomes/toy-smoke/units/mul.mjs

@@ -0,0 +1,16 @@
+// Toy unit: mul — correct baseline; grader score 1.0, pass true.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const isMain =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+export function mul(a, b) {
+  return a * b;
+}
+
+export function checks() {
+  return [mul(2, 3) === 6, mul(0, 7) === 0, mul(-2, 3) === -6];
+}
+
+if (isMain) console.log(`mul(2,3)=${mul(2, 3)}`);

package/dist/genomes/toy-smoke/units/mutate.mjs

@@ -0,0 +1,18 @@
+// Toy unit: mutate — run() writes ./poison.txt into the sandbox cwd (state mutation;
+// import for grading stays pure via the isMain guard). Fixture for AC (c):
+// reset+seed must restore a byte-identical tree digest.
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const isMain =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+export function checks() {
+  return [true];
+}
+
+if (isMain) {
+  writeFileSync(path.join(process.cwd(), "poison.txt"), "mutated\n");
+  console.log("mutated sandbox state");
+}

package/dist/genomes/toy-smoke/units/sub.mjs

@@ -0,0 +1,16 @@
+// Toy unit: sub — the required val-split unit; correct baseline (score 1.0).
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const isMain =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+export function sub(a, b) {
+  return a - b;
+}
+
+export function checks() {
+  return [sub(9, 4) === 5, sub(0, 0) === 0, sub(-3, -3) === 0];
+}
+
+if (isMain) console.log(`sub(9,4)=${sub(9, 4)}`);