@tachikomagundam/abathur 0.1.0

package/dist/core/evolve/friction.js

@@ -0,0 +1,150 @@
+// Structured friction digests (plan todo 11a): every run appends ONE fixed-shape
+// friction_digest record to the global queue <configDir>/friction.jsonl (todo-2
+// guarded helpers — lock + schema envelope + tail repair come free). Stalls,
+// repeated rejections (todo-8 stage/reason counts), inconclusive causes and CLI
+// errors are COUNTS and ENUMS, never free text: every string field passes
+// scrub() (printable-ASCII, single line, bounded).
+//
+// VAL LEAK GATE (plan 157-164, the core rule): material from val-split units
+// contributes counts, alias positions and sample numbers ONLY — unit ids,
+// paths, scenario text and failure strings sourced from val runs can never
+// enter a record, because the queue is mutator-adjacent context downstream.
+import { z } from "zod";
+import { appendFriction, LedgerError, readFriction, } from "../ledger.js";
+export const FRICTION_KIND = "friction_digest";
+/** Rejection stages as produced by todo-8 (candidate.ts schema|syntax|path + driver apply|parse). */
+export const REJECT_STAGES = ["schema", "syntax", "path", "apply", "parse"];
+const MAX_REASONS = 10;
+const MAX_TRAIN_UNITS = 32;
+const MAX_FAILURES_PER_UNIT = 4;
+const MAX_REASON_CHARS = 200;
+const MAX_UNIT_ID_CHARS = 120;
+/** Printable-ASCII, single line, bounded — the queue never carries ANSI or newlines. */
+export function scrub(value, max = MAX_REASON_CHARS) {
+    const one = value.replace(/[^ -~]/g, " ").replace(/\s+/g, " ").trim();
+    if (one.length <= max)
+        return one;
+    return `${one.slice(0, Math.max(0, max - 3))}...`;
+}
+export const frictionCauseSchema = z.enum(["run-summary", "cli-error", "self-eval"]);
+export const frictionStageCountsSchema = z.strictObject({
+    schema: z.number().int().nonnegative(),
+    syntax: z.number().int().nonnegative(),
+    path: z.number().int().nonnegative(),
+    apply: z.number().int().nonnegative(),
+    parse: z.number().int().nonnegative(),
+});
+export const frictionDigestSchema = z.strictObject({
+    genomeFp: z.string().regex(/^[0-9a-f]{16}$/),
+    cause: frictionCauseSchema,
+    exit: z.union([z.literal(0), z.literal(1), z.literal(2)]),
+    complete: z.boolean(),
+    counts: z.strictObject({
+        applied: z.number().int().nonnegative(),
+        rejected: z.number().int().nonnegative(),
+        benched: z.number().int().nonnegative(),
+        inconclusive: z.number().int().nonnegative(),
+        nominated: z.number().int().nonnegative(),
+        timeouts: z.number().int().nonnegative(),
+        reaped: z.number().int().nonnegative(),
+    }),
+    rejections: z.strictObject({ total: z.number().int().nonnegative(), byStage: frictionStageCountsSchema }),
+    stall: z.strictObject({ budgetTruncated: z.boolean(), orphanGroups: z.number().int().nonnegative() }),
+    train: z
+        .array(z.strictObject({
+        unitId: z.string().min(1).max(MAX_UNIT_ID_CHARS),
+        n: z.number().int().nonnegative(),
+        mean: z.number().finite(),
+        failures: z.array(z.string().min(1).max(MAX_REASON_CHARS)).max(MAX_FAILURES_PER_UNIT),
+    }))
+        .max(MAX_TRAIN_UNITS),
+    val: z.strictObject({
+        count: z.number().int().nonnegative(),
+        aliases: z.array(z.string().regex(/^val-[0-9]+$/)).max(64),
+        samples: z.number().int().nonnegative(),
+    }),
+    reasons: z.array(z.string().min(1).max(MAX_REASON_CHARS)).max(MAX_REASONS),
+});
+function meanOf(scores) {
+    if (scores.length === 0)
+        return 0;
+    return scores.reduce((a, b) => a + b, 0) / scores.length;
+}
+/** Pure builder: sanitizes + bounds every string, then schema-parses (fail-closed). */
+export function buildRunFriction(input) {
+    const byStage = { schema: 0, syntax: 0, path: 0, apply: 0, parse: 0 };
+    const unknownStages = [];
+    for (const rejection of input.rejected) {
+        const hit = REJECT_STAGES.find((stage) => stage === rejection.stage);
+        if (hit !== undefined)
+            byStage[hit] += 1;
+        else
+            unknownStages.push(`rejection stage '${scrub(rejection.stage, 40)}': ${scrub(rejection.reason)}`);
+    }
+    const train = [];
+    let valCount = 0;
+    let valSamples = 0;
+    const valAliases = [];
+    for (const unit of input.units) {
+        if (unit.split === "val") {
+            valAliases.push(`val-${String(valCount + 1)}`);
+            valCount += 1;
+            valSamples += unit.scores.length;
+            continue;
+        }
+        if (train.length >= MAX_TRAIN_UNITS)
+            continue;
+        train.push({
+            unitId: scrub(unit.unitId, MAX_UNIT_ID_CHARS),
+            n: unit.scores.length,
+            mean: Number(meanOf(unit.scores).toFixed(6)),
+            failures: unit.failures.map((f) => scrub(f)).filter((f) => f.length > 0).slice(0, MAX_FAILURES_PER_UNIT),
+        });
+    }
+    const data = frictionDigestSchema.parse({
+        genomeFp: input.genomeFp,
+        cause: input.cause,
+        exit: input.exit,
+        complete: input.complete,
+        counts: input.counts,
+        rejections: { total: input.rejected.length, byStage },
+        stall: { budgetTruncated: input.stall.budgetTruncated, orphanGroups: input.stall.orphanGroups },
+        train,
+        val: { count: valCount, aliases: valAliases, samples: valSamples },
+        reasons: [...input.reasons.map((r) => scrub(r)).filter((r) => r.length > 0).slice(0, MAX_REASONS), ...unknownStages].slice(0, MAX_REASONS),
+    });
+    return input.runId === undefined
+        ? { kind: FRICTION_KIND, data }
+        : { kind: FRICTION_KIND, runId: scrub(input.runId, 160), data };
+}
+export function appendRunFriction(configDir, input, opts = {}) {
+    return appendFriction(configDir, buildRunFriction(input), opts);
+}
+/**
+ * Fail-closed queue reader: a corrupt line yields a readable error naming the
+ * file and line (never a crash, never a silent skip); foreign record kinds are
+ * refused like corruption — the queue holds friction_digest records only.
+ */
+export function readFrictionDigests(configDir) {
+    let records;
+    try {
+        records = readFriction(configDir);
+    }
+    catch (error) {
+        if (error instanceof LedgerError)
+            return { digests: [], error: error.message };
+        throw error;
+    }
+    const digests = [];
+    for (const [index, record] of records.entries()) {
+        if (record.kind !== FRICTION_KIND) {
+            return { digests, error: `friction: line ${String(index + 1)} has kind '${record.kind}', expected '${FRICTION_KIND}'` };
+        }
+        const parsed = frictionDigestSchema.safeParse(record.data);
+        if (!parsed.success) {
+            return { digests, error: `friction: line ${String(index + 1)} failed ${FRICTION_KIND} schema: ${parsed.error.issues[0]?.message ?? "schema"}` };
+        }
+        digests.push(parsed.data);
+    }
+    return { digests, error: null };
+}

package/dist/core/evolve/reflect.js

@@ -0,0 +1,191 @@
+// Reflection-driven mutator session driver (todo 8, plan lines 133-140).
+//
+// runMutatorSession launches the candidate generator as a runCommand-template child
+// (opencode or a stub script) whose --dir points at a throwaway worktree snapshotted
+// from the incumbent head (todo-3 store). The child's stdout must be
+// { candidates: [{ id?, rationale, diffs: [unified diff strings] } ] } (zod-checked).
+// Each candidate is validated (candidate.ts) and applied ONLY inside its own throwaway
+// worktree — the real repo worktree is never touched — then sealed (a real commit) or
+// discarded. EVERY rejection (schema/syntax/path/apply/parse) is booked in the genome
+// ledger as kind "candidate_rejected". A missing mutator binary exits 2 BEFORE spawning.
+//
+// The brief policy lives in brief.ts. This module re-exports the whole todo-9 surface:
+// buildBrief / runMutatorSession / validateCandidate + ARTIFACT_GLOBS.
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import path from "node:path";
+import { blocked, cannotAnswer } from "../../exit.js";
+import { renderCommand, runChild } from "../../bench/adapter.js";
+import { fingerprint, genId } from "../ids.js";
+import { Ledger } from "../ledger.js";
+import { fingerprint16 } from "../genome.js";
+import { newGeneration, openGenome, sealGeneration } from "../worktree.js";
+import { formatZodIssues } from "../spec.js";
+import { ARTIFACT_GLOBS, artifactGlobsFromGitignore, candidateIdOf, mutatorOutputSchema, validateCandidate, } from "./candidate.js";
+import { applyChanges } from "./udiff.js";
+export { buildBrief } from "./brief.js";
+export { ARTIFACT_GLOBS, artifactGlobsFromGitignore, candidateSchema, mutatorOutputSchema, validateCandidate, } from "./candidate.js";
+export { parseUnifiedDiff, applyChanges } from "./udiff.js";
+function isExecutableFile(p) {
+    try {
+        const st = statSync(p);
+        return st.isFile() && (st.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Fail-closed bin resolution BEFORE any spawn (no raw ENOENT, plan: exit 2). */
+function resolveBin(name, opencodeBin) {
+    if (name === "opencode" && opencodeBin !== null) {
+        if (isExecutableFile(opencodeBin))
+            return opencodeBin;
+        cannotAnswer(`mutator: configured opencodeBin is not executable: ${opencodeBin}`, "set opencodeBin in the abathur config to a working opencode binary");
+    }
+    if (name.includes("/")) {
+        const resolved = path.resolve(name);
+        if (isExecutableFile(resolved))
+            return resolved;
+        cannotAnswer(`mutator: command binary not found or not executable: ${name}`);
+    }
+    for (const dir of (process.env["PATH"] ?? "").split(path.delimiter)) {
+        if (dir === "")
+            continue;
+        const candidate = path.join(dir, name);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    const detail = name === "opencode" ? " (opencodeBin unset and opencode not on PATH)" : "";
+    cannotAnswer(`mutator: binary '${name}' not found${detail}`, "install the mutator CLI or set opencodeBin in the config");
+}
+function oneLine(text, max) {
+    const flat = text.replace(/[\r\n\t]+/g, " ");
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+function sealMessage(candidateId, rationale) {
+    const safe = rationale.replace(/[^ -~]/g, " ");
+    return `abathur: mutator candidate ${candidateId} — ${oneLine(safe, 80)}`;
+}
+function readIfText(filePath) {
+    return existsSync(filePath) ? readFileSync(filePath, "utf8") : null;
+}
+/** Parse the child's stdout contract; a broken batch is a clean fatal error AFTER ledger booking. */
+function parseStdout(stdout, reject) {
+    let doc;
+    try {
+        doc = JSON.parse(stdout);
+    }
+    catch {
+        const preview = oneLine(stdout, 200);
+        reject("mutator-stdout", "parse", `stdout is not JSON: ${preview}`);
+        blocked(`mutator: stdout is not JSON — cannot use this candidate batch (preview: ${preview})`);
+    }
+    const parsed = mutatorOutputSchema.safeParse(doc);
+    if (!parsed.success) {
+        const reason = `expected an object with a non-empty 'candidates' array: ${formatZodIssues(parsed.error.issues).join("; ")}`;
+        reject("mutator-stdout", "schema", reason);
+        blocked(`mutator: output schema rejected — ${reason}`);
+    }
+    return parsed.data;
+}
+export async function runMutatorSession(opts) {
+    const { spec } = opts;
+    const env = opts.env ?? process.env;
+    const now = opts.now ?? (() => new Date());
+    const timeoutS = opts.timeoutS ?? spec.bench.timeoutS;
+    const maxCandidates = opts.maxCandidates ?? spec.budget.maxCandidates;
+    const probeArgv = renderCommand(opts.mutatorCommand, { worktree: "", brief: "" });
+    const bin = resolveBin(probeArgv[0] ?? "", opts.opencodeBin ?? null);
+    const opened = await openGenome(spec.repoPath, [], { env });
+    const genome = { repoPath: spec.repoPath, genomeFp: fingerprint16(spec) };
+    const ledger = opts.ledger ?? Ledger.open(spec.repoPath);
+    const gitignoreText = readIfText(path.join(spec.repoPath, ".gitignore"));
+    const artifactGlobs = gitignoreText === null ? ARTIFACT_GLOBS : [...ARTIFACT_GLOBS, ...artifactGlobsFromGitignore(gitignoreText)];
+    const policy = { immutableGlobs: spec.kernel.immutableGlobs, artifactGlobs };
+    const briefDir = mkdtempSync(path.join(os.tmpdir(), "abathur-brief-"));
+    const briefFile = path.join(briefDir, "brief.md");
+    writeFileSync(briefFile, opts.brief, "utf8");
+    const applied = [];
+    const rejected = [];
+    const reject = (candidateId, stage, reason, genIdValue) => {
+        rejected.push({ candidateId, stage, reason });
+        ledger.append({
+            kind: "candidate_rejected",
+            ...(genIdValue === undefined ? {} : { genId: genIdValue }),
+            data: { candidateId, stage, reason },
+        });
+    };
+    let launchGenId = "";
+    try {
+        launchGenId = genId(fingerprint({ abathur: "mutator-launch", head: opened.headCommit, at: now().getTime() }), now());
+        const launch = await newGeneration(genome, opened.headCommit, launchGenId, { env });
+        try {
+            const argv = renderCommand(opts.mutatorCommand, { worktree: launch.worktreePath, brief: briefFile });
+            const child = await runChild({
+                argv: [bin, ...argv.slice(1)],
+                cwd: launch.worktreePath,
+                timeoutS,
+                ...(opts.onChild === undefined ? {} : { onChild: opts.onChild }),
+            });
+            if (child.kind !== "exited") {
+                blocked(`mutator: child ${child.kind}: ${child.reason}`);
+            }
+            const doc = parseStdout(child.stdout, reject);
+            const raws = doc.candidates.slice(0, maxCandidates);
+            for (const [index, raw] of raws.entries()) {
+                const id = candidateIdOf(raw, index);
+                const v = validateCandidate(raw, policy, id);
+                if (!v.ok) {
+                    reject(id, v.stage, v.reason);
+                    continue;
+                }
+                const gen = genId(fingerprint({ parent: opened.headCommit, candidateId: v.candidateId, changes: v.changes, at: now().getTime(), index }), now());
+                const wt = await newGeneration(genome, opened.headCommit, gen, { env });
+                let sealedOk = false;
+                try {
+                    const changes = applyChanges(v.changes, (rel) => readIfText(path.join(wt.worktreePath, rel)));
+                    if (!changes.ok) {
+                        reject(v.candidateId, "apply", changes.reason, gen);
+                        continue;
+                    }
+                    let wrote = 0;
+                    for (const [rel, content] of changes.files) {
+                        if (content === readIfText(path.join(wt.worktreePath, rel)))
+                            continue;
+                        const target = path.join(wt.worktreePath, rel);
+                        mkdirSync(path.dirname(target), { recursive: true });
+                        writeFileSync(target, content, "utf8");
+                        wrote += 1;
+                    }
+                    if (wrote === 0) {
+                        reject(v.candidateId, "apply", "candidate changes nothing (incumbent content already matches)", gen);
+                        continue;
+                    }
+                    const sealed = await sealGeneration(genome, gen, sealMessage(v.candidateId, v.rationale), { env });
+                    sealedOk = true;
+                    applied.push({
+                        candidateId: v.candidateId,
+                        rationale: v.rationale,
+                        genId: gen,
+                        worktreePath: wt.worktreePath,
+                        parentCommit: opened.headCommit,
+                        commitSha: sealed.commitSha,
+                        treeSha: sealed.treeSha,
+                        touchedFiles: changes.touched,
+                    });
+                }
+                finally {
+                    if (!sealedOk)
+                        rmSync(wt.worktreePath, { recursive: true, force: true });
+                }
+            }
+        }
+        finally {
+            rmSync(launch.worktreePath, { recursive: true, force: true });
+        }
+    }
+    finally {
+        rmSync(briefDir, { recursive: true, force: true });
+    }
+    return { launchGenId, applied, rejected };
+}

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

@@ -0,0 +1,170 @@
+// Budgeted bench execution for the run-loop (todo 9): adapter factory +
+// reset→seed→run→score matrix driver. Row schemas / resume readers: run-rows.ts.
+import path from "node:path";
+import { cannotAnswer } from "../../exit.js";
+import { runId } from "../ids.js";
+import { buildManifest } from "../kernel.js";
+import { budgetExhausted } from "../stats.js";
+import { ToyBenchAdapter } from "../../bench/toy.js";
+import { FixtureScenariosAdapter } from "../../bench/fixture.js";
+import { round3, unitMatrixRowSchema } from "./run-rows.js";
+import { selfBench } from "./self-snapshot.js";
+export function cloneMatrixRow(u) {
+    return { unitId: u.unitId, split: u.split, scores: [...u.scores], runIds: [...u.runIds], failures: [...u.failures] };
+}
+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.
+export function asReplicates(rows) {
+    return rows.filter((u) => u.scores.length > 0).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. */
+export function openBenchAdapter(spec, opts) {
+    const childOpts = opts.onChild === undefined ? {} : { onChild: opts.onChild };
+    const envOpts = opts.env === undefined ? {} : { env: opts.env };
+    const binOpts = opts.opencodeBin === undefined ? {} : { opencodeBin: opts.opencodeBin };
+    switch (spec.bench.type) {
+        case "toy":
+            return { adapter: new ToyBenchAdapter(spec, { ...childOpts }), release: () => { } };
+        case "opencode-fixture-scenarios": {
+            const adapter = new FixtureScenariosAdapter(spec, {
+                configDir: opts.configDir,
+                // plan line 118: val paths surface in the manifest ONLY when the
+                // operator passed --include-val; authority to BENCH them is separate.
+                includeVal: opts.includeVal === true,
+                loopValAuthority: opts.loopValAuthority === true,
+                ...envOpts,
+                ...binOpts,
+                ...childOpts,
+            });
+            return { adapter, release: () => adapter.release() };
+        }
+        default: {
+            const exhaust = spec.bench.type;
+            return cannotAnswer(`bench: unsupported bench type '${String(exhaust)}'`);
+        }
+    }
+}
+// ------------------------------------------------------------- bench runner
+/**
+ * benchTarget is the evolution loop's bench driver, and the selection gate is
+ * its consumer: nomination REQUIRES val replicates (plan lines 125-132) and
+ * SC4 benches the shipped fixture genome train+val (plan line 214) — so the loop
+ * ALWAYS benches val units, with or without the operator flag. Commit 3c6bbf9
+ * conflated this with `--include-val` and every default `abathur run` on a
+ * val-bearing fixture genome crashed (exit 2) at the first val unit, mid-bench,
+ * before any generation row; src/test/fixture-loop.test.ts pins the fix.
+ * Exposure of val ids/paths (adapter manifest) remains the operator's
+ * includeVal alone. Do NOT gate loop benching on the operator flag again.
+ */
+const LOOP_VAL_AUTHORITY = true;
+/**
+ * Drive reset→seed→run→score over EVERY unit (train AND val: the nomination gate
+ * needs val replicates) `reps` times, checking the budget before each replicate.
+ * A budget stop ends the pass with complete:false; timeout/infra_failed runs and
+ * inconclusive graders are recorded as failure notes and carry NO score sample
+ * (excluded from distributions per the hr discipline, never zeroed).
+ */
+export async function benchTarget(o) {
+    if (o.selfBench !== undefined) {
+        const res = await selfBench({
+            spec: o.spec,
+            genomeRepo: o.selfBench.genomeRepo,
+            genomeFp: o.selfBench.genomeFp,
+            incumbentCommit: o.selfBench.incumbentCommit,
+            candidateCommit: o.selfBench.candidateCommit,
+            genId: o.genId,
+            reps: o.reps,
+            env: o.selfBench.env,
+            onChild: o.tracker.onChild,
+        });
+        return {
+            units: res.units,
+            spent: res.spent,
+            provenance: res.provenance,
+            complete: res.complete,
+            manifest: buildManifest(o.selfBench.genomeRepo, o.spec.kernel.immutableGlobs),
+            failures: res.failures,
+        };
+    }
+    const rows = new Map();
+    for (const unit of o.spec.bench.units) {
+        rows.set(unit.id, { unitId: unit.id, split: unit.split, scores: [], runIds: [], failures: [] });
+    }
+    let tokens = 0;
+    let wallS = 0;
+    let provenance = null;
+    let complete = true;
+    const bundle = openBenchAdapter(o.spec, {
+        configDir: o.configDir,
+        loopValAuthority: LOOP_VAL_AUTHORITY,
+        ...(o.includeVal === true ? { includeVal: true } : {}),
+        ...(o.env === undefined ? {} : { env: o.env }),
+        ...(o.opencodeBin === undefined ? {} : { opencodeBin: o.opencodeBin }),
+        onChild: o.tracker.onChild,
+    });
+    try {
+        o.tracker.phase(o.genId, `${o.source}-bench`);
+        outer: for (const unit of o.spec.bench.units) {
+            for (let rep = 0; rep < o.reps; rep += 1) {
+                const running = {
+                    candidates: o.countersBefore.candidates,
+                    modelCalls: o.countersBefore.modelCalls,
+                    tokens: o.countersBefore.tokens + tokens,
+                    wallS: round3(o.countersBefore.wallS + wallS),
+                };
+                if (budgetExhausted(running, o.caps)) {
+                    complete = false;
+                    break outer;
+                }
+                const sandbox = path.join(o.sandboxRoot, `${unit.id}-${String(rep)}`);
+                await bundle.adapter.reset(sandbox);
+                await bundle.adapter.seed(sandbox);
+                const started = Date.now();
+                const run = await bundle.adapter.run(unit, sandbox, o.spec.bench.timeoutS);
+                wallS += (Date.now() - started) / 1000;
+                provenance ??= run.benchProvenance;
+                tokens += run.metrics.tokensEst;
+                const row = rows.get(unit.id);
+                if (row === undefined)
+                    cannotAnswer(`bench: unknown unit '${unit.id}' returned from spec`);
+                if (run.status !== "ok") {
+                    row.failures.push(`${unit.id} rep ${String(rep)}: run ${run.status}: ${run.note ?? run.status}`);
+                    continue;
+                }
+                const score = await bundle.adapter.score(unit);
+                if (score.kind === "scored") {
+                    row.scores.push(score.result.score);
+                    row.runIds.push(runId(o.genId, unit.id, rep));
+                    if (!score.result.pass) {
+                        row.failures.push(`${unit.id} rep ${String(rep)}: scored ${String(score.result.score)} (not passing)`);
+                    }
+                }
+                else {
+                    row.failures.push(`${unit.id} rep ${String(rep)}: grader inconclusive: ${score.reason}`);
+                }
+            }
+        }
+    }
+    finally {
+        bundle.release();
+    }
+    const spent = {
+        candidates: o.source === "candidate" ? 1 : 0,
+        modelCalls: 0,
+        tokens,
+        wallS: round3(wallS),
+    };
+    const failures = [...rows.values()].flatMap((r) => r.failures);
+    return {
+        units: [...rows.values()].map((r) => unitMatrixRowSchema.parse(r)),
+        spent,
+        provenance: provenance ?? { benchType: o.spec.bench.type, versions: [] },
+        complete,
+        manifest: buildManifest(path.resolve(o.spec.repoPath), o.spec.kernel.immutableGlobs),
+        failures,
+    };
+}

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

@@ -0,0 +1,63 @@
+// Friction aggregation for the run-loop (plan todo 11a): accumulates bench,
+// session and verdict facts as they happen and emits ONE RunFrictionInput at
+// run end. Lives outside run-loop.ts so the orchestrator stays focused; the
+// loop only calls into this when the CLI injected a sink. Every string that
+// reaches the queue passes through friction.ts buildRunFriction (scrub +
+// bounds + val aliasing) — nothing here may add raw child output.
+export function startRunFriction(sink) {
+    const units = new Map();
+    let rejected = [];
+    let applied = 0;
+    let benched = 0;
+    let truncated = false;
+    const reasons = [];
+    const fold = (rows) => {
+        for (const r of rows) {
+            const agg = units.get(r.unitId) ?? { unitId: r.unitId, split: r.split, scores: [], failures: [] };
+            agg.scores.push(...r.scores);
+            agg.failures.push(...r.failures);
+            units.set(r.unitId, agg);
+        }
+    };
+    return {
+        noteUnits: fold,
+        noteBench(out) {
+            benched += 1;
+            truncated ||= !out.complete;
+            fold(out.units);
+        },
+        noteSession(rows, appliedCount) {
+            rejected = rows.map((r) => ({ stage: r.stage, reason: r.reason }));
+            applied = appliedCount;
+        },
+        noteCandidate(candidateId, failures, guardNote) {
+            if (guardNote !== null)
+                reasons.push(`candidate ${candidateId}: self-bench guard ${guardNote}`);
+            for (const f of failures)
+                reasons.push(`candidate ${candidateId}: ${f}`);
+        },
+        emit(ctx) {
+            const timeouts = [...units.values()].reduce((n, u) => n + u.failures.filter((f) => f.includes(": run timeout") || f.includes(": run infra_failed")).length, 0);
+            sink({
+                genomeFp: ctx.genomeFp,
+                cause: "run-summary",
+                runId: ctx.runId,
+                exit: ctx.exit,
+                complete: !truncated,
+                counts: {
+                    applied,
+                    rejected: rejected.length,
+                    benched,
+                    inconclusive: ctx.considered.filter((v) => v === "inconclusive").length,
+                    nominated: ctx.considered.filter((v) => v === "nominated").length,
+                    timeouts,
+                    reaped: ctx.orphanGroups,
+                },
+                rejected,
+                units: [...units.values()],
+                reasons,
+                stall: { budgetTruncated: truncated, orphanGroups: ctx.orphanGroups },
+            });
+        },
+    };
+}