@tachikomagundam/abathur 0.2.3 → 0.2.5

package/config/genomes/historian.example.jsonc

@@ -8,6 +8,11 @@
 //
 //   ${ABATHUR_HISTORIAN_REPO}  absolute path of the historian bench repo
 //                              (contains scenarios/, rubric.md, seed_sandbox.sh)
+//                              — repoPath ONLY: the S4 engine seam delivers the
+//                              bench's ACTIVE TREE (incumbent repoPath /
+//                              candidate worktree) to the commands below as the
+//                              {repoRoot} template var, so unit/seed paths must
+//                              NOT bake a materialized repo literal here.
 //   ${ABATHUR_REPO}            absolute path of THIS Abathur checkout
 //                              (hosts graders/historian/*)
 //   ${ABATHUR_WIKI_BASE}       canonical wiki root, e.g. http://localhost:3000
@@ -47,11 +52,11 @@
       { "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",
+    "seedCommand": "bash ${ABATHUR_REPO}/graders/historian/seed-wrapped.sh {repoRoot}/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",
+    "runCommand": "bash ${ABATHUR_REPO}/graders/historian/run-scenario.sh {unit.id} {repoRoot}/{unit.path}",
+    "graderCommand": "node ${ABATHUR_REPO}/graders/historian/grader.mjs {unit.id} {repoRoot}/{unit.path} ${ABATHUR_WIKI_BASE}",
+    "agentModel": "replace-me/provider/model", // operator: substitute the real <provider>/<model> when copying
     // 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

package/dist/bench/adapter.js

@@ -10,11 +10,29 @@
 //                 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 };
+/**
+ * `{repoRoot}` = the bench's ACTIVE TREE: the genome repoPath for the incumbent,
+ * the sealed candidate worktree for a candidate (run-loop.ts swaps spec.repoPath
+ * per target; adapters resolve it through effectiveRepoPath at construction).
+ * Omitting repoRoot keeps `{repoRoot}` an UNKNOWN placeholder — fail-closed
+ * exit 2, never a silently half-substituted command.
+ */
+export function unitVars(unit, sandboxDir, repoRoot) {
+    const vars = {
+        "unit.path": unit.path,
+        "unit.id": unit.id,
+        sandbox: sandboxDir,
+        workdir: sandboxDir,
+    };
+    if (repoRoot !== undefined)
+        vars["repoRoot"] = repoRoot;
+    return vars;
 }
-export function sandboxVars(sandboxDir) {
-    return { sandbox: sandboxDir, workdir: sandboxDir };
+export function sandboxVars(sandboxDir, repoRoot) {
+    const vars = { sandbox: sandboxDir, workdir: sandboxDir };
+    if (repoRoot !== undefined)
+        vars["repoRoot"] = repoRoot;
+    return vars;
 }
 const PLACEHOLDER = /\{([A-Za-z0-9_.]+)\}/g;
 /**

package/dist/bench/fixture.js

@@ -32,6 +32,7 @@ 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 { effectiveRepoPath } from "../core/spec.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";
@@ -52,7 +53,10 @@ export class FixtureScenariosAdapter {
         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);
+        // Active-tree resolution follows the run-loop notion (run-loop.ts:142): a
+        // concrete repoPath resolves exactly as before; a `${VAR}` env literal
+        // resolves at THIS fs boundary or exits 2 naming the variable.
+        const root = effectiveRepoPath(spec.repoPath);
         if (!statSync(root, { throwIfNoEntry: false })?.isDirectory()) {
             cannotAnswer(`fixture: repoPath '${spec.repoPath}' is not a readable directory`);
         }
@@ -84,7 +88,7 @@ export class FixtureScenariosAdapter {
         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)),
+            argv: renderCommand(this.spec.bench.runCommand, unitVars(unit, sandboxDir, this.repoRoot)),
             cwd: sandboxDir,
             timeoutS,
             env: this.sandboxEnv(sandboxDir, unit),
@@ -109,7 +113,7 @@ export class FixtureScenariosAdapter {
             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)),
+            argv: renderCommand(this.spec.bench.graderCommand, unitVars(unit, sandbox, this.repoRoot)),
             cwd: sandbox,
             timeoutS: this.spec.bench.timeoutS,
             env: this.sandboxEnv(sandbox),
@@ -211,7 +215,7 @@ export class FixtureScenariosAdapter {
         if (template === undefined)
             return;
         const outcome = await runChild({
-            argv: renderCommand(template, sandboxVars(sandboxDir)),
+            argv: renderCommand(template, sandboxVars(sandboxDir, this.repoRoot)),
             cwd: sandboxDir,
             timeoutS: HOOK_TIMEOUT_S,
             env: this.sandboxEnv(sandboxDir),

package/dist/bench/toy.js

@@ -53,7 +53,7 @@ export class ToyBenchAdapter {
     async run(unit, sandboxDir, timeoutS) {
         this.activeSandbox = sandboxDir;
         const outcome = await runChild({
-            argv: renderCommand(this.spec.bench.runCommand, unitVars(unit, sandboxDir)),
+            argv: renderCommand(this.spec.bench.runCommand, unitVars(unit, sandboxDir, this.repoRoot)),
             cwd: sandboxDir,
             timeoutS,
             ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
@@ -75,7 +75,7 @@ export class ToyBenchAdapter {
             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)),
+            argv: renderCommand(this.spec.bench.graderCommand, unitVars(unit, sandbox, this.repoRoot)),
             cwd: sandbox,
             timeoutS: this.spec.bench.timeoutS,
             ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),
@@ -109,7 +109,7 @@ export class ToyBenchAdapter {
         if (template === undefined)
             return;
         const outcome = await runChild({
-            argv: renderCommand(template, sandboxVars(sandboxDir)),
+            argv: renderCommand(template, sandboxVars(sandboxDir, this.repoRoot)),
             cwd: sandboxDir,
             timeoutS: HOOK_TIMEOUT_S,
             ...(this.opts.onChild === undefined ? {} : { onChild: this.opts.onChild }),

package/dist/commands/status.js

@@ -15,6 +15,7 @@ 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";
+import { effectiveRepoPath } from "../core/spec.js";
 const KIND_GENERATION = "generation_complete";
 const KIND_PROMOTE = "promote";
 const KIND_TOMBSTONE = "tombstone";
@@ -113,7 +114,11 @@ async function runStatus(args) {
         renderQueue(queue);
         return EXIT_OK;
     }
-    const repo = entry.spec.repoPath;
+    // Resolve at the fs seam exactly like run/genome/kernel (run-loop.ts:142):
+    // feeding the stored UNRESOLVED `${VAR}` literal to git/ledger paths makes
+    // Node report the missing cwd as the misleading `spawn git ENOENT`; an unset
+    // variable is now a clean exit 2 that names it.
+    const repo = effectiveRepoPath(entry.spec.repoPath);
     const records = readLedgerRecords(ledgerPath(repo));
     const gens = generations(records);
     writeStdout(`genome: ${flat(entry.label)} (${entry.fingerprint})  repo: ${flat(repo, 200)}`);

package/dist/core/evolve/run-bench.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { cannotAnswer } from "../../exit.js";
 import { runId } from "../ids.js";
 import { buildManifest } from "../kernel.js";
+import { effectiveRepoPath } from "../spec.js";
 import { budgetExhausted } from "../stats.js";
 import { ToyBenchAdapter } from "../../bench/toy.js";
 import { FixtureScenariosAdapter } from "../../bench/fixture.js";
@@ -15,10 +16,11 @@ export function cloneMatrixRow(u) {
 export function copyProvenance(p) {
     return { benchType: p.benchType, versions: p.versions.map((v) => ({ bin: v.bin, version: v.version })) };
 }
-// Unscored units (run timeout/infra_failed, inconclusive grader, budget cut) must be
-// excluded before stats.evaluate — empty replicate lists poison aggregateScore with NaN.
+// Invariant: unscored units (timeout/infra_failed/budget cut) stay in the matrix —
+// dropping them asymmetrically shifts one arm's aggregate pool (campaign-6 artifact);
+// evaluate() fail-closes any arm's n<2 as indeterminate before any aggregation.
 export function asReplicates(rows) {
-    return rows.filter((u) => u.scores.length > 0).map((u) => ({ unitId: u.unitId, split: u.split, scores: u.scores }));
+    return rows.map((u) => ({ unitId: u.unitId, split: u.split, scores: u.scores }));
 }
 export * from "./run-rows.js";
 /** toy ⇒ stateless adapter; fixture ⇒ ctor acquires the fingerprint lock immediately. */
@@ -164,7 +166,7 @@ export async function benchTarget(o) {
         spent,
         provenance: provenance ?? { benchType: o.spec.bench.type, versions: [] },
         complete,
-        manifest: buildManifest(path.resolve(o.spec.repoPath), o.spec.kernel.immutableGlobs),
+        manifest: buildManifest(effectiveRepoPath(o.spec.repoPath), o.spec.kernel.immutableGlobs),
         failures,
     };
 }

package/dist/core/evolve/run-loop.js

@@ -32,7 +32,7 @@ import { compactUtc, fingerprint, genId } from "../ids.js";
 import { LEDGER_KIND_GENERATION_COMPLETE, acquireGenomeLock, Ledger } from "../ledger.js";
 import { openGenome } from "../worktree.js";
 import { clampReps, evaluate, needsExit } from "../stats.js";
-import { effectiveRepoPath, isEnvRepoLiteral } from "../spec.js";
+import { effectiveRepoPath, envRepoName, isEnvRepoLiteral } from "../spec.js";
 import { ChildTracker, reapOrphans } from "./child-track.js";
 import { buildBrief } from "./brief.js";
 import { startRunFriction } from "./run-friction.js";
@@ -101,7 +101,13 @@ async function evolve(opts, mutatorCommand, ledger, caps, reps, env, now) {
     const spec = opts.entry.spec;
     const lines = [];
     const genomeRepo = effectiveRepoPath(spec.repoPath);
-    const selfMode = isEnvRepoLiteral(spec.repoPath);
+    // Engine-self ONLY: a `${VAR}` literal is a path-injection convenience any
+    // harness repo may use (campaign-1 misroute pin: selfmode-literal.test.ts).
+    const selfMode = envRepoName(spec.repoPath) === "ABATHUR_SELF_REPO";
+    // Env-literals resolve to concrete paths exactly once, here at the FS
+    // boundary; bench/reflect drivers below never see the raw literal.
+    // Concrete repoPaths flow through byte-identical to before.
+    const loopSpec = isEnvRepoLiteral(spec.repoPath) ? { ...spec, repoPath: genomeRepo } : spec;
     const fric = opts.friction === undefined ? null : startRunFriction(opts.friction);
     // Reap only under the genome lock: every remaining log entry belongs to a dead run.
     const reap = reapOrphans(genomeRepo);
@@ -131,7 +137,7 @@ async function evolve(opts, mutatorCommand, ledger, caps, reps, env, now) {
     else {
         const gen = genId(fingerprint({ incumbent: opened.headCommit, at: now().getTime() }), now());
         const out = await benchTarget({
-            spec,
+            spec: loopSpec,
             genId: gen,
             reps,
             caps,
@@ -181,7 +187,7 @@ async function evolve(opts, mutatorCommand, ledger, caps, reps, env, now) {
         const brief = buildBrief(spec, evidence, counters);
         tracker.phase(`mutator-${invId}`, "mutator-session");
         const session = await runMutatorSession({
-            spec: selfMode ? { ...spec, repoPath: genomeRepo } : spec,
+            spec: loopSpec,
             brief,
             mutatorCommand,
             ...(opts.opencodeBin === undefined ? {} : { opencodeBin: opts.opencodeBin }),

package/dist/core/evolve/run-plan.js

@@ -1,7 +1,7 @@
 // --dry-run plan rendering + budget-cap resolution (todo 9). Presentation of
 // the resolved startup state only — the dry-run gate in run-loop.ts calls this
 // AFTER the kernel audit and BEFORE any ledger/lock/spawn touch.
-import path from "node:path";
+import { effectiveRepoPath } from "../spec.js";
 import { peekPlanState } from "./run-rows.js";
 /** `--max-candidates` clamps DOWN to the genome's own cap, never above. */
 export function effectiveCaps(spec, clamp) {
@@ -15,12 +15,16 @@ export function effectiveCaps(spec, clamp) {
 }
 export function planLines(req) {
     const spec = req.entry.spec;
-    const peek = peekPlanState(spec.repoPath);
+    // `${VAR}` literals resolve through the same FS-boundary contract as every
+    // other consumer; the plan line + resume peek must never join the raw
+    // literal against cwd.
+    const genomeRepo = effectiveRepoPath(spec.repoPath);
+    const peek = peekPlanState(genomeRepo);
     const specMax = spec.budget.maxCandidates;
     const unitList = spec.bench.units.map((u) => `${u.id}(${u.split})`).join(" ");
     return [
         `run plan — genome '${spec.label}' (${req.entry.fingerprint})`,
-        `  repo: ${path.resolve(spec.repoPath)}`,
+        `  repo: ${genomeRepo}`,
         `  bench: ${spec.bench.type} — timeoutS=${String(spec.bench.timeoutS)} stats minEffect=${String(spec.bench.stats.minEffect)} halfWidth=${String(spec.bench.stats.halfWidth)}`,
         `  units: ${unitList}`,
         ...(req.requiresProbed === undefined

package/dist/core/spec.js

@@ -126,7 +126,11 @@ export function errorText(cause) {
  * resolved ONLY at FS boundaries, never inside the spec.
  */
 const ENV_REPO_LITERAL = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
-/** True when the spec stores an unresolved `${VAR}` env literal (self-genome marker). */
+/**
+ * True when the spec stores an unresolved `${VAR}` env literal — a path-
+ * injection convenience ANY genome may use, NOT an engine-self discriminator
+ * (for that compare envRepoName against ABATHUR_SELF_REPO).
+ */
 export function isEnvRepoLiteral(repoPath) {
     return ENV_REPO_LITERAL.test(repoPath);
 }

package/dist/core/stats.js

@@ -132,29 +132,47 @@ export function evaluate(input) {
     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`);
+    // 2) Cross-arm replicate rule. A unit measured cleanly (n>=2) on ONE arm but
+    //    not on the other leaves that comparison's variance undefined ⇒
+    //    indeterminate, never a silent cull and never a nomination (campaign-6:
+    //    the candidate's train unit scored while the incumbent's had timed out;
+    //    the old one-sided drop shifted the incumbent aggregate to the val
+    //    fallback and minted a bogus negative gain). A unit unmeasured on BOTH
+    //    arms is excluded symmetrically — every aggregate and comparison then
+    //    runs on a pool both arms share replicate-for-replicate.
+    const excluded = new Set();
+    for (const unitId of new Set([...incByUnit.keys(), ...candByUnit.keys()])) {
+        const cn = candByUnit.get(unitId)?.scores.length ?? 0;
+        const inn = incByUnit.get(unitId)?.scores.length ?? 0;
+        if (cn >= 2 && inn < 2) {
+            failures.push(`n=${inn} on incumbent unit '${unitId}': baseline 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`);
+        else if (inn >= 2 && cn < 2) {
+            if (incByUnit.get(unitId)?.split === "val") {
+                failures.push(`no replicates for val unit '${unitId}' on candidate '${candidate.runId}' — variance undefined, never nominated`);
+            }
+            else {
+                failures.push(`n=${cn} on unit '${unitId}': variance undefined — indeterminate, never nominated`);
+            }
+        }
+        else if (cn < 2 && inn < 2) {
+            excluded.add(unitId);
         }
     }
     if (failures.length > 0) {
-        return { ...base, verdict: "indeterminate", exitCode: needsExit("indeterminate"), gain: aggregateScore(candidate.units) - aggregateScore(incumbent.units), unitComparisons: [], failures };
+        return { ...base, verdict: "indeterminate", exitCode: needsExit("indeterminate"), gain: null, unitComparisons: [], failures };
     }
+    const candKept = candidate.units.filter((u) => !excluded.has(u.unitId));
+    const incKept = incumbent.units.filter((u) => !excluded.has(u.unitId));
+    const candByUnitKept = new Map(candKept.map((u) => [u.unitId, u]));
     // 3) Per-val-unit comparisons + the two precision gates.
     const unitComparisons = [];
     for (const [unitId, incUnit] of incByUnit) {
-        if (incUnit.split !== "val")
+        if (incUnit.split !== "val" || excluded.has(unitId))
             continue;
-        const candUnit = candByUnit.get(unitId);
+        const candUnit = candByUnitKept.get(unitId);
         if (candUnit === undefined)
-            continue; // already ruled indeterminate above
+            continue; // excluded/unreachable
         const cs = summarizeUnit(candUnit.scores, alpha);
         const incumbentMean = summarizeUnit(incUnit.scores).mean;
         const delta = cs.mean - incumbentMean;
@@ -174,8 +192,8 @@ export function evaluate(input) {
             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);
+    // 4) Effect-size floor on the aggregate gain (shared, symmetric pool).
+    const gain = aggregateScore(candKept) - aggregateScore(incKept);
     if (gain < stats.minEffect) {
         failures.push(`gain ${fmt(gain)} < minEffect ${fmt(stats.minEffect)}`);
     }

package/dist/test/bench-adapter.test.js

@@ -31,3 +31,27 @@ test("renderCommand: quote-aware argv, placeholders, fail-closed junk (exit 2)",
     expectExit2(() => renderCommand("   ", unitVars(unit, "/s")), "empty");
     expectExit2(() => renderCommand('node "oops', unitVars(unit, "/s")), "unbalanced quote");
 });
+// S4 engine seam: {repoRoot} = the bench's ACTIVE TREE, threaded through the
+// shared CommandVars constructors so both adapters resolve it identically.
+// Without a threaded repoRoot the placeholder must stay FAIL-CLOSED (exit 2),
+// exactly like any unknown placeholder — never a half-substituted command.
+test("{repoRoot}: unitVars/sandboxVars carry the active tree into run/grader/hook templates", () => {
+    const unit = { id: "u1", path: "scenarios/a.md", split: "train" };
+    assert.deepEqual(renderCommand("bash run-scenario.sh {unit.id} {repoRoot}/{unit.path}", unitVars(unit, "/sbx", "/active/tree")), ["bash", "run-scenario.sh", "u1", "/active/tree/scenarios/a.md"]);
+    assert.deepEqual(renderCommand("bash seed-wrapped.sh {repoRoot}/seed_sandbox.sh", sandboxVars("/sbx", "/active/tree")), ["bash", "seed-wrapped.sh", "/active/tree/seed_sandbox.sh"]);
+    // pre-existing keys untouched by the seam
+    assert.deepEqual(unitVars(unit, "/sbx", "/r"), {
+        "unit.path": "scenarios/a.md",
+        "unit.id": "u1",
+        sandbox: "/sbx",
+        workdir: "/sbx",
+        repoRoot: "/r",
+    });
+    assert.deepEqual(sandboxVars("/sbx", "/r"), { sandbox: "/sbx", workdir: "/sbx", repoRoot: "/r" });
+});
+test("{repoRoot} unthreaded ⇒ fail-closed exit 2 (unknown placeholder behavior UNCHANGED)", () => {
+    const unit = { id: "u1", path: "p", split: "train" };
+    expectExit2(() => renderCommand("node x {repoRoot}", unitVars(unit, "/s")), "unknown placeholder");
+    expectExit2(() => renderCommand("node x {repoRoot}", sandboxVars("/s")), "unknown placeholder");
+    expectExit2(() => renderCommand("node x {repoRoot}", { worktree: "/w", brief: "/b" }), "unknown placeholder");
+});

package/dist/test/bench-reporoot.test.js

@@ -0,0 +1,197 @@
+// S4 engine seam — the {repoRoot} command variable. The mutation channel's
+// delivery hinge: run/grader/seed/reset templates must resolve {repoRoot} to
+// the bench's ACTIVE TREE — the genome repoPath for the incumbent, the sealed
+// candidate worktree for a candidate (run-loop.ts swaps `spec.repoPath` before
+// benching each candidate; the adapter must follow that same notion, including
+// effectiveRepoPath's env-literal resolution at the FS boundary).
+// Unknown placeholders stay fail-closed (exit 2). Offline: capture scripts
+// record the rendered argv; the fake opencode only answers --version.
+import assert from "node:assert/strict";
+import { chmodSync, cpSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import * as os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+import { ExitSignal } from "../exit.js";
+import { parseGenomeSpecDocument } from "../core/spec.js";
+import { FixtureScenariosAdapter } from "../bench/fixture.js";
+// ------------------------------------------------------------------- helpers
+async function freshDir(t, prefix) {
+    const dir = await mkdtemp(path.join(os.tmpdir(), `abathur-${prefix}-`));
+    t.after(() => rm(dir, { recursive: true, force: true }));
+    return dir;
+}
+async function writeScript(dir, name, body) {
+    const filePath = path.join(dir, name);
+    await writeFile(filePath, body, "utf8");
+    chmodSync(filePath, 0o755);
+    return filePath;
+}
+/** Records `argv[mode, out, ...rest]`: rest joined per line into `out`; prints the metric/score line. */
+const CAPTURE = `#!/usr/bin/env node
+import { writeFileSync } from "node:fs";
+const [mode, out, ...rest] = process.argv.slice(2);
+writeFileSync(out, rest.join("\\n") + "\\n", "utf8");
+if (mode === "score") {
+  process.stdout.write(JSON.stringify({ unit: "one", score: 1, pass: true, metrics: { tokensEst: 3, turns: 1 } }) + "\\n");
+} else {
+  process.stdout.write(JSON.stringify({ tokensEst: 3, turns: 1 }) + "\\n");
+}
+`;
+const FAKE_OC = `#!/usr/bin/env bash
+if [ "\${1:-}" = "--version" ]; then echo "1.2.3"; exit 0; fi
+exit 0
+`;
+const UNIT = { id: "one", path: "scenarios/one.md", split: "train" };
+const VAL_UNIT = { id: "v1", path: "scenarios/v1.md", split: "val" };
+async function seamFixture(t, genDir) {
+    const root = await freshDir(t, "seam-ad");
+    const capPath = await writeScript(root, "cap.mjs", CAPTURE);
+    const binDir = await freshDir(t, "seam-bin");
+    const binPath = await writeScript(binDir, "oc-fake", FAKE_OC);
+    const home = await freshDir(t, "seam-home");
+    const configDir = await freshDir(t, "seam-cfg");
+    const outDir = path.join(root, "caps");
+    mkdirSync(outDir, { recursive: true });
+    const out = (name) => path.join(outDir, `${name}.txt`);
+    const spec = parseGenomeSpecDocument({
+        label: "seam-germ",
+        repoPath: genDir,
+        bench: {
+            type: "opencode-fixture-scenarios",
+            units: [UNIT, VAL_UNIT],
+            runCommand: `node ${capPath} run ${out("run")} {repoRoot} {unit.path}`,
+            seedCommand: `node ${capPath} seed ${out("seed")} {repoRoot}`,
+            resetCommand: `node ${capPath} reset ${out("reset")} {repoRoot}`,
+            graderCommand: `node ${capPath} score ${out("grader")} {repoRoot}`,
+            agentModel: "test/agent",
+            timeoutS: 30,
+            stats: { halfWidth: 0.15, minEffect: 0.1, nReps: { initial: 1, max: 2 } },
+        },
+        budget: { maxCandidates: 2, maxModelCalls: 4, maxTokens: 10000, maxWallS: 600 },
+        kernel: { immutableGlobs: [] },
+        requires: [{ cmd: "node", args: ["--version"], probeExit: 0 }],
+        opencodeBinVersion: { minVersion: "1.0.0" },
+    }, "<test>");
+    const sandbox = path.join(root, "sandbox");
+    return {
+        spec,
+        genDir,
+        sandbox,
+        home,
+        cap: capPath,
+        binPath,
+        out,
+        adapter: (s) => new FixtureScenariosAdapter(s, { env: { HOME: home }, home, configDir, opencodeBin: binPath }),
+    };
+}
+/** Minimal genome dir (the fixture adapter only requires repoPath to be a directory). */
+async function genomeTree(t, name = "germ") {
+    const genRoot = await freshDir(t, `seam-${name}`);
+    const genDir = path.join(genRoot, "germ");
+    mkdirSync(path.join(genDir, "scenarios"), { recursive: true });
+    writeFileSync(path.join(genDir, "scenarios", "one.md"), "# one\n\n## Brief\ndo it\n", "utf8");
+    writeFileSync(path.join(genDir, "scenarios", "v1.md"), "# v1\n\n## Brief\ndo it val\n", "utf8");
+    return genDir;
+}
+function readCap(file) {
+    return readFileSync(file, "utf8").trim();
+}
+function isExit2Matching(needle) {
+    return (cause) => cause instanceof ExitSignal && cause.code === 2 && needle.test(cause.message);
+}
+// --------------------------------------------------------------------- pins
+test("{repoRoot} renders to the incumbent genome repoPath in run + grader + hooks", async (t) => {
+    const genDir = await genomeTree(t);
+    const f = await seamFixture(t, genDir);
+    const adapter = f.adapter(f.spec);
+    try {
+        await adapter.reset(f.sandbox);
+        await adapter.seed(f.sandbox);
+        const run = await adapter.run(UNIT, f.sandbox, 30);
+        assert.equal(run.status, "ok");
+        const score = await adapter.score(UNIT);
+        assert.equal(score.kind, "scored");
+        assert.equal(readCap(f.out("run")), `${genDir}\nscenarios/one.md`);
+        assert.equal(readCap(f.out("grader")), genDir);
+        assert.equal(readCap(f.out("seed")), genDir);
+        assert.equal(readCap(f.out("reset")), genDir);
+    }
+    finally {
+        adapter.release();
+    }
+});
+test("{repoRoot} follows the candidate worktree when spec.repoPath is swapped (run-loop.ts pattern)", async (t) => {
+    const genDir = await genomeTree(t);
+    const f = await seamFixture(t, genDir);
+    // simulate run-loop.ts:279 — benchTarget receives { ...spec, repoPath: worktreePath }
+    const worktree = path.join(path.dirname(genDir), "wt");
+    cpSync(genDir, worktree, { recursive: true });
+    mkdirSync(path.join(worktree, "abathur-notes"), { recursive: true });
+    writeFileSync(path.join(worktree, "abathur-notes", "card.md"), "planted run card\n", "utf8");
+    const candidate = f.adapter({ ...f.spec, repoPath: worktree });
+    try {
+        const sandbox = path.join(f.sandbox, "cand");
+        await candidate.reset(sandbox);
+        await candidate.seed(sandbox);
+        const run = await candidate.run(UNIT, sandbox, 30);
+        assert.equal(run.status, "ok");
+        const score = await candidate.score(UNIT);
+        assert.equal(score.kind, "scored");
+        assert.equal(readCap(f.out("run")), `${worktree}\nscenarios/one.md`);
+        assert.equal(readCap(f.out("grader")), worktree);
+    }
+    finally {
+        candidate.release();
+    }
+});
+test("fixture ctor resolves an env-literal repoPath via effectiveRepoPath (run-loop.ts:142 pattern)", async (t) => {
+    const genDir = await genomeTree(t, "lit");
+    const f = await seamFixture(t, genDir);
+    const litSpec = { ...f.spec, repoPath: "${ABATHUR_SEAM_LIT_REPO}" };
+    const base = {
+        env: { HOME: f.home },
+        home: f.home,
+        configDir: path.join(f.home, ".config", "abathur"),
+        opencodeBin: f.binPath,
+    };
+    delete process.env["ABATHUR_SEAM_LIT_REPO"];
+    try {
+        // unset env ⇒ clean exit 2 NAMING the variable (never a garbage-path spawn error)
+        assert.throws(() => new FixtureScenariosAdapter(litSpec, base), isExit2Matching(/requires env var ABATHUR_SEAM_LIT_REPO/));
+        // set env ⇒ resolves at the FS boundary; {repoRoot} renders to the resolved tree
+        process.env["ABATHUR_SEAM_LIT_REPO"] = genDir;
+        const adapter = new FixtureScenariosAdapter(litSpec, base);
+        try {
+            const sandbox = path.join(f.sandbox, "lit");
+            await adapter.reset(sandbox);
+            await adapter.seed(sandbox);
+            const run = await adapter.run(UNIT, sandbox, 30);
+            assert.equal(run.status, "ok");
+            assert.equal(readCap(f.out("run")), `${genDir}\nscenarios/one.md`);
+        }
+        finally {
+            adapter.release();
+        }
+    }
+    finally {
+        delete process.env["ABATHUR_SEAM_LIT_REPO"];
+    }
+});
+test("fail-closed UNCHANGED: unknown placeholder through the adapter is still exit 2", async (t) => {
+    const genDir = await genomeTree(t, "unk");
+    const f = await seamFixture(t, genDir);
+    const bad = {
+        ...f.spec,
+        bench: { ...f.spec.bench, runCommand: `node ${f.cap} run ${f.out("bad")} {nope}` },
+    };
+    const adapter = f.adapter(bad);
+    try {
+        await adapter.reset(f.sandbox);
+        await adapter.seed(f.sandbox);
+        await assert.rejects(() => adapter.run(UNIT, f.sandbox, 30), isExit2Matching(/unknown placeholder/));
+    }
+    finally {
+        adapter.release();
+    }
+});