@tachikomagundam/abathur 0.1.0

package/dist/core/bundle-tar.js

@@ -0,0 +1,240 @@
+// Pure-node tar (USTAR + PAX 'path' override) for lineage bundles (todo 12).
+// Deterministic output (mtime 0, uid/gid 0, fixed mode, sorted-in-callers paths)
+// so a re-export of the same ledger state is byte-identical; the reader is the
+// adversarial boundary — it never materialises anything, validates every header
+// checksum, and refuses absolute / traversal / odd-type member names.
+const BLOCK = 512;
+const NAME_MAX = 99;
+const PREFIX_MAX = 154;
+export const TAR_TOTAL_CAP_BYTES = 64 * 1024 * 1024;
+export class TarError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TarError";
+    }
+}
+function ascii(s, len) {
+    if (s.length > len)
+        throw new TarError(`tar field overflow: "${s}" > ${String(len)} bytes`);
+    const b = new Uint8Array(len);
+    for (let i = 0; i < s.length; i += 1)
+        b[i] = s.charCodeAt(i);
+    return b;
+}
+function octal(value, len) {
+    if (!Number.isInteger(value) || value < 0)
+        throw new TarError(`tar octal: bad value ${String(value)}`);
+    const digits = (value >>> 0).toString(8).padStart(len - 1, "0");
+    if (digits.length > len - 1)
+        throw new TarError(`tar octal overflow: ${String(value)}`);
+    return ascii(`${digits}\0`, len);
+}
+function assertSafePath(p) {
+    if (p.length === 0)
+        throw new TarError("tar: empty member path");
+    if (p.startsWith("/") || p.includes("\\"))
+        throw new TarError(`tar: unsafe member path ${p}`);
+    for (const seg of p.split("/")) {
+        if (seg === ".." || seg === "")
+            throw new TarError(`tar: traversal/unsafe member path ${p}`);
+    }
+}
+function zeroBlock() {
+    return new Uint8Array(BLOCK);
+}
+function headerBlock(fields) {
+    const h = new Uint8Array(BLOCK);
+    const parts = [
+        [ascii(fields.name, 100), 0],
+        [octal(0o644, 8), 100],
+        [octal(0, 8), 108],
+        [octal(0, 8), 116],
+        [octal(fields.size, 12), 124],
+        [octal(0, 12), 136],
+        [new Uint8Array(8).fill(0x20), 148],
+        [ascii(fields.typeflag, 1), 156],
+        [new Uint8Array(100), 157],
+        [ascii("ustar\0", 6), 257],
+        [ascii("00", 2), 263],
+        [new Uint8Array(32), 265],
+        [new Uint8Array(32), 297],
+        [octal(0, 8), 329],
+        [octal(0, 8), 337],
+        [ascii(fields.prefix, PREFIX_MAX + 1), 345],
+    ];
+    for (const [bytes, offset] of parts)
+        h.set(bytes, offset);
+    let sum = 0;
+    for (const byte of h)
+        sum += byte;
+    h.set(ascii(`${(sum & 0o777777).toString(8).padStart(6, "0")}\0 `, 8), 148);
+    return h;
+}
+function splitLongPath(p) {
+    if (p.length <= NAME_MAX)
+        return { name: p, prefix: "" };
+    let cut = -1;
+    for (let i = p.length - 1; i >= 0; i -= 1) {
+        if (p[i] === "/" && p.slice(0, i).length <= PREFIX_MAX && p.slice(i + 1).length <= NAME_MAX) {
+            cut = i;
+            break;
+        }
+    }
+    if (cut < 0)
+        return null;
+    return { name: p.slice(cut + 1), prefix: p.slice(0, cut) };
+}
+function paxPathHeader(p) {
+    // PAX len counts BYTES of "<len> path=<p>\n" — for non-ASCII names the UTF-8
+    // byte length exceeds the string length, so the fixed point is byte-based.
+    const enc = new TextEncoder();
+    const body = `path=${p}\n`;
+    let len = enc.encode(body).length + 5;
+    for (;;) {
+        const record = `${String(len)} ${body}`;
+        const bytes = enc.encode(record);
+        if (bytes.length === len) {
+            const name = `././PaxHeaders.${p.split("/").pop() ?? "x"}`.slice(0, 99);
+            const header = headerBlock({ name, prefix: "", size: bytes.length, typeflag: "x" });
+            const data = new Uint8Array(Math.ceil(bytes.length / BLOCK) * BLOCK);
+            data.set(bytes);
+            return new Uint8Array([...header, ...data]);
+        }
+        len = bytes.length;
+    }
+}
+function pad(data) {
+    const rem = data.length % BLOCK;
+    if (rem === 0)
+        return data;
+    const out = new Uint8Array(data.length + (BLOCK - rem));
+    out.set(data);
+    return out;
+}
+/** Serialise members (callers keep them sorted) into deterministic tar bytes. */
+export function writeTar(members) {
+    const chunks = [];
+    for (const m of members) {
+        assertSafePath(m.path);
+        if (m.path.length > PREFIX_MAX + 1 + NAME_MAX)
+            throw new TarError(`tar: path too long: ${m.path}`);
+        const split = m.path.length <= NAME_MAX ? { name: m.path, prefix: "" } : splitLongPath(m.path);
+        // USTAR name/prefix fields are 7-bit (ascii() truncates each char to its low
+        // byte), so anything outside printable ASCII travels in a PAX 'path' override.
+        if (split === null || !/^[\x20-\x7E]+$/.test(m.path)) {
+            chunks.push(paxPathHeader(m.path));
+            chunks.push(headerBlock({ name: m.path.slice(0, NAME_MAX), prefix: "", size: m.content.length, typeflag: "0" }));
+        }
+        else {
+            chunks.push(headerBlock({ name: split.name, prefix: split.prefix, size: m.content.length, typeflag: "0" }));
+        }
+        const data = pad(m.content);
+        chunks.push(data);
+    }
+    chunks.push(zeroBlock(), zeroBlock());
+    return concat(chunks);
+}
+function concat(chunks) {
+    const size = chunks.reduce((acc, c) => acc + c.length, 0);
+    const out = new Uint8Array(size);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}
+function parseOctal(field) {
+    const s = new TextDecoder().decode(field).replace(/\0| /g, "");
+    if (s.length === 0)
+        return 0;
+    if (!/^[0-7]+$/.test(s))
+        throw new TarError(`tar: bad octal field "${s}"`);
+    const v = Number.parseInt(s, 8);
+    if (!Number.isSafeInteger(v) || v < 0)
+        throw new TarError("tar: octal field out of range");
+    return v;
+}
+function verifyChecksum(block) {
+    const stored = parseOctal(block.subarray(148, 156));
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i += 1) {
+        sum += i >= 148 && i < 156 ? 0x20 : (block[i] ?? 0);
+    }
+    if (sum !== stored)
+        throw new TarError("tar: header checksum mismatch (corrupt or truncated archive)");
+}
+/** Parse tar bytes; throws TarError on any corruption, traversal or odd member type. */
+export function readTar(bytes) {
+    const members = [];
+    const seen = new Set();
+    let off = 0;
+    let pendingPath = null;
+    let totalBytes = 0;
+    const dec = new TextDecoder();
+    const cstring = (b) => dec.decode(b).split("\0")[0] ?? "";
+    while (off < bytes.length) {
+        if (bytes.length - off < BLOCK) {
+            throw new TarError("tar: truncated archive (partial block at end of stream)");
+        }
+        const block = bytes.subarray(off, off + BLOCK);
+        off += BLOCK;
+        if (block.every((x) => x === 0)) {
+            const rest = bytes.subarray(off);
+            if (bytes.length - (off - BLOCK) < 2 * BLOCK || rest.length % BLOCK !== 0 || !rest.every((x) => x === 0)) {
+                throw new TarError("tar: truncated archive (incomplete end-of-archive marker)");
+            }
+            break;
+        }
+        verifyChecksum(block);
+        const magic = cstring(block.subarray(257, 265));
+        if (!magic.startsWith("ustar"))
+            throw new TarError("tar: missing ustar magic — not a tar archive");
+        const rawName = cstring(block.subarray(0, 100));
+        const prefix = cstring(block.subarray(345, 500));
+        const size = parseOctal(block.subarray(124, 136));
+        const typeflag = String.fromCharCode(block[156] ?? 0x30);
+        const name = prefix.length > 0 && pendingPath === null ? `${prefix}/${rawName}` : rawName;
+        if (size > TAR_TOTAL_CAP_BYTES || totalBytes + size > TAR_TOTAL_CAP_BYTES) {
+            throw new TarError(`tar: member ${name} exceeds size cap`);
+        }
+        if (bytes.length - off < size)
+            throw new TarError(`tar: truncated archive (member ${name} data missing)`);
+        const data = bytes.subarray(off, off + Math.ceil(size / BLOCK) * BLOCK).subarray(0, size);
+        off += Math.ceil(size / BLOCK) * BLOCK;
+        if (typeflag === "x" || typeflag === "g") {
+            pendingPath = extractPaxPath(dec.decode(data)) ?? pendingPath;
+            continue;
+        }
+        if (typeflag === "5")
+            continue;
+        if (typeflag !== "0" && typeflag !== "\0") {
+            throw new TarError(`tar: refusing member ${name} of type '${typeflag}' (only regular files allowed)`);
+        }
+        const finalPath = pendingPath ?? name;
+        pendingPath = null;
+        assertSafePath(finalPath);
+        if (seen.has(finalPath))
+            throw new TarError(`tar: duplicate member path ${finalPath}`);
+        seen.add(finalPath);
+        totalBytes += size;
+        members.push({ path: finalPath, content: new Uint8Array(data) });
+    }
+    return members;
+}
+function extractPaxPath(records) {
+    const enc = new TextEncoder();
+    let path = null;
+    for (const record of records.split("\n")) {
+        if (record.length === 0)
+            continue;
+        const space = record.indexOf(" ");
+        const eq = record.indexOf("=", space + 1);
+        // the declared len is the record's BYTE length + the split-off "\n"
+        if (space > 0 && eq > space && record.slice(0, space) === String(enc.encode(record).length + 1)) {
+            if (record.slice(space + 1, eq) === "path")
+                path = record.slice(eq + 1);
+        }
+    }
+    return path;
+}

package/dist/core/bundle.js

@@ -0,0 +1,9 @@
+// Lineage bundles (todo 12) — public surface: export + inspect with provenance
+// and redacted train-only evidence. Members are verified byte-for-byte on
+// inspect; nothing inside a bundle implies trust, only self-consistency.
+export { exportBundle } from "./bundle-export.js";
+export { inspectBundle } from "./bundle-inspect.js";
+export { bundleManifestSchema, DIGEST_ALGO, BUNDLE_SCHEMA_VERSION } from "./bundle-manifest.js";
+export { buildMaskPlan, scanMemberLeaks } from "./bundle-mask.js";
+export { readTar, writeTar, TarError } from "./bundle-tar.js";
+export { benchDigestFor, containedSpec, maskPlanFor, primaryGenId, sha256Hex, treeOf } from "./bundle-common.js";

package/dist/core/evolve/brief.js

@@ -0,0 +1,45 @@
+// Reflection brief builder (todo 8, plan lines 133-140): pure spec + bench
+// results in → mutator-facing text out. Only failed/inconclusive TRAIN units get
+// detail; VAL units are referenced by opaque aliases (val-1, val-2…) — never topic
+// text, file names, or scores.
+function oneLine(text, max) {
+    const flat = text.replace(/[\r\n\t]+/g, " ");
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+function isFailing(u) {
+    return u.failures.length > 0 || u.scores.length === 0 || u.scores.some((s) => s < 1);
+}
+/**
+ * Reflection brief from FAILED TRAIN units only. Val units never appear with
+ * identity: count + opaque aliases, no ids, no paths, no scores, no content.
+ */
+export function buildBrief(spec, units, counters) {
+    const failing = units.filter((u) => u.unit.split === "train" && isFailing(u));
+    const valCount = units.filter((u) => u.unit.split === "val").length;
+    const lines = [];
+    lines.push(`# Abathur mutation brief — genome "${spec.label}"`);
+    lines.push("");
+    lines.push(`Budget spent so far: candidates=${String(counters.candidates)} modelCalls=${String(counters.modelCalls)} ` +
+        `tokens=${String(counters.tokens)} wallS=${String(counters.wallS)}.`);
+    lines.push(`Caps: maxCandidates=${String(spec.budget.maxCandidates)} maxModelCalls=${String(spec.budget.maxModelCalls)} ` +
+        `maxTokens=${String(spec.budget.maxTokens)} maxWallS=${String(spec.budget.maxWallS)}.`);
+    if (failing.length === 0) {
+        lines.push("", "No failing train units to reflect on this session.");
+    }
+    else {
+        lines.push("", `Failing train units (${String(failing.length)}):`);
+        for (const f of failing) {
+            lines.push("", `## ${f.unit.path} (unit id: ${f.unit.id})`);
+            lines.push(`- scores over ${String(f.scores.length)} reps: ${f.scores.map(String).join(", ")}`);
+            for (const failure of f.failures)
+                lines.push(`- failure: ${oneLine(failure, 500)}`);
+        }
+    }
+    lines.push("", "Candidate contract: stdout JSON {candidates:[{id?,rationale,diffs:[unified-diff strings]}]}.");
+    lines.push("Deletions, renames and binary hunks are refused; any kernel-immutable or artifact path in a candidate rejects the WHOLE candidate.");
+    if (valCount > 0) {
+        const aliases = Array.from({ length: valCount }, (_, k) => `val-${String(k + 1)}`).join(", ");
+        lines.push("", `Validation split: ${String(valCount)} held-out units (${aliases}). Their topics, file names, scores and content are withheld from you by policy.`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/core/evolve/candidate.js

@@ -0,0 +1,140 @@
+// Candidate validation for the mutator session (todo 8, plan lines 133-140).
+// Everything is pure: zod schema for the child's output contract, the central
+// ARTIFACT_GLOBS policy, gitignore → glob translation, and validateCandidate
+// which turns one raw candidate into parsed FileChanges or a staged rejection.
+// WHOLE-CANDIDATE REJECTION is the rule: any single violating path rejects the
+// entire candidate — there is no partial-apply path through this module.
+import { z } from "zod";
+import path from "node:path";
+import { compileGlob } from "../glob.js";
+import { formatZodIssues } from "../spec.js";
+import { parseUnifiedDiff } from "./udiff.js";
+/**
+ * Build/hidden state that evolution must never write. Plan wording:
+ * ".gitignore'd outputs, dist/**, node_modules/**, .state/**, *.local.jsonc".
+ * `.state/**` doubles as the ledger-seal surface — mutating it from a candidate
+ * is self-tampering. Deep variants cover nested installs; the repo's own
+ * .gitignore is folded in via artifactGlobsFromGitignore at session time.
+ */
+export const ARTIFACT_GLOBS = Object.freeze([
+    "dist/**",
+    "**/dist/**",
+    "node_modules/**",
+    "**/node_modules/**",
+    ".state/**",
+    "**/.state/**",
+    "*.local.jsonc",
+    "**/*.local.jsonc",
+]);
+/** Translate .gitignore lines into our glob language (fail-closed broadening). */
+export function artifactGlobsFromGitignore(text) {
+    const globs = [];
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#") || line.startsWith("!"))
+            continue;
+        const dirStyle = line.endsWith("/");
+        const body = dirStyle ? line.slice(0, -1) : line;
+        const core = body.startsWith("/") ? body.slice(1) : body;
+        if (core === "")
+            continue;
+        if (dirStyle) {
+            globs.push(`${core}/**`);
+            if (!core.includes("/"))
+                globs.push(`**/${core}/**`);
+        }
+        else if (!core.includes("/")) {
+            globs.push(core, `**/${core}`);
+        }
+        else {
+            globs.push(core);
+        }
+    }
+    return globs;
+}
+/** One mutator candidate: unified diff chunks + a rationale string (plan contract). */
+export const candidateSchema = z.strictObject({
+    id: z
+        .string()
+        .regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/)
+        .optional(),
+    rationale: z.string().min(1).max(4000),
+    diffs: z.array(z.string().min(1)).min(1),
+});
+/** Top level of the child's stdout; elements are schema-checked per candidate. */
+export const mutatorOutputSchema = z.strictObject({
+    candidates: z.array(z.unknown()).min(1),
+});
+/** Candidate ids are attacker-influenced; the fallback keeps ledger rows stable. */
+export function candidateIdOf(raw, index) {
+    if (typeof raw === "object" && raw !== null && "id" in raw) {
+        const id = raw.id;
+        if (typeof id === "string" && id.length > 0)
+            return id;
+    }
+    return `candidate-${String(index + 1)}`;
+}
+/** Reject absolute / traversal / VCS / control-char paths before any glob runs. */
+function unsafePathReason(p) {
+    if (p.length === 0)
+        return "empty path";
+    if (p.startsWith("/") || p.includes("\\"))
+        return "absolute or drive-style path";
+    if (p.includes("\0") || p.includes("\n") || p.includes("\r"))
+        return "control characters";
+    if (p.endsWith("/"))
+        return "directory path";
+    const segments = p.split("/");
+    if (segments.some((s) => s === ".."))
+        return "directory traversal";
+    if (segments.some((s) => s === ".git"))
+        return "VCS metadata path";
+    if (path.posix.normalize(p) !== p)
+        return "non-canonical path";
+    return null;
+}
+function policyHit(p, globs) {
+    for (const g of globs) {
+        if (compileGlob(g).test(p))
+            return g;
+    }
+    return null;
+}
+/**
+ * Validate one raw candidate against the schema, diff syntax, and the sealed
+ * paths (kernel.immutableGlobs + artifact globs). Returns the parsed changes
+ * ONLY when every file of the candidate passes — a single violation rejects
+ * the whole candidate with the stage and reason the session logs to the ledger.
+ */
+export function validateCandidate(raw, policy, fallbackId = "candidate") {
+    const parsed = candidateSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, stage: "schema", reason: formatZodIssues(parsed.error.issues).join("; ") };
+    }
+    const changes = [];
+    for (const diff of parsed.data.diffs) {
+        const p = parseUnifiedDiff(diff);
+        if (!p.ok)
+            return { ok: false, stage: "syntax", reason: p.error };
+        for (const c of p.changes) {
+            if (changes.some((e) => e.path === c.path)) {
+                return { ok: false, stage: "syntax", reason: `duplicate file section across diff chunks: ${c.path}` };
+            }
+            changes.push(c);
+        }
+    }
+    for (const c of changes) {
+        const unsafe = unsafePathReason(c.path);
+        if (unsafe !== null)
+            return { ok: false, stage: "path", reason: `refused path (${unsafe}): ${c.path}` };
+        const sealed = policyHit(c.path, policy.immutableGlobs);
+        if (sealed !== null) {
+            return { ok: false, stage: "path", reason: `path '${c.path}' touches kernel-immutable glob '${sealed}' — whole candidate rejected` };
+        }
+        const artifact = policyHit(c.path, policy.artifactGlobs);
+        if (artifact !== null) {
+            return { ok: false, stage: "path", reason: `path '${c.path}' touches artifact glob '${artifact}' — whole candidate rejected` };
+        }
+    }
+    return { ok: true, candidateId: parsed.data.id ?? fallbackId, rationale: parsed.data.rationale, changes };
+}

package/dist/core/evolve/child-track.js

@@ -0,0 +1,197 @@
+// Active-child tracking + orphan reaping for the run-loop (plan todo 9).
+//
+// Every child the loop spawns (mutator, bench unit, grader, engine probe) is
+// recorded in <genomeRepo>/.state/abathur/active-children.jsonl the instant it
+// spawns — BEFORE any await — with its pid. Children run detached (pid ===
+// pgid, see bench/adapter.ts runChild), so the recorded pid doubles as the
+// process-group id and the reap can SIGKILL whole groups.
+//
+// Reaper contract (startup of every `abathur run`):
+//   - ONLY pids present in this log are ever signalled — an unrecorded process
+//     is off-limits, always;
+//   - the log is read at startup only while the genome lock is held, so every
+//     entry belongs to a DEAD prior run; liveness is recorded per entry
+//     (kill-0: ESRCH dead, EPERM foreign-but-alive) and the group gets
+//     kill(-pgid, SIGKILL), ESRCH being a benign no-op;
+//   - self pid and structurally invalid records are skipped (never killed);
+//   - malformed lines are counted and skipped: corrupt tracking state must
+//     degrade the reap, never crash the run;
+//   - after killing, the log is truncated — reap is once-per-entry.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { canonicalJson } from "../ids.js";
+export function activeChildrenPath(genomeRepo) {
+    return path.join(genomeRepo, ".state", "abathur", "active-children.jsonl");
+}
+function parseRecord(line) {
+    let doc;
+    try {
+        doc = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        return null;
+    const raw = doc;
+    const { pid, pgid, genId } = raw;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 1)
+        return null;
+    const resolvedGid = typeof pgid === "number" && Number.isInteger(pgid) && pgid > 1 ? pgid : pid;
+    if (typeof genId !== "string" || genId.length === 0)
+        return null;
+    const kindVal = raw["kind"];
+    const atVal = raw["at"];
+    return {
+        v: 1,
+        pid,
+        pgid: resolvedGid,
+        genId,
+        kind: typeof kindVal === "string" && kindVal.length > 0 ? kindVal : "child",
+        at: typeof atVal === "string" ? atVal : "",
+    };
+}
+/** Tolerant reader: malformed lines yield nothing, the file may be absent. */
+export function readChildRecords(genomeRepo) {
+    let text;
+    try {
+        text = readFileSync(activeChildrenPath(genomeRepo), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line.length === 0)
+            continue;
+        const rec = parseRecord(line);
+        if (rec !== null)
+            out.push(rec);
+    }
+    return out;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM"; // foreign-owned ⇒ alive
+    }
+}
+function killGroup(pgid) {
+    try {
+        process.kill(-pgid, "SIGKILL");
+        return "sent";
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return "already-gone";
+        return "foreign";
+    }
+}
+/**
+ * SIGKILL every recorded group of the dead prior run(s), then truncate the log.
+ * Call only under the genome lock: live entries from a concurrent run must
+ * never pass through here.
+ */
+export function reapOrphans(genomeRepo) {
+    const filePath = activeChildrenPath(genomeRepo);
+    let text;
+    try {
+        text = readFileSync(filePath, "utf8");
+    }
+    catch {
+        return { reaped: [], skipped: [], malformed: 0 }; // no tracking state ⇒ nothing to reap
+    }
+    const reaped = [];
+    const skipped = [];
+    let malformed = 0;
+    for (const line of text.split("\n")) {
+        if (line.length === 0)
+            continue;
+        const rec = parseRecord(line);
+        if (rec === null) {
+            malformed += 1;
+            continue;
+        }
+        if (rec.pid === process.pid) {
+            skipped.push(`self pid ${String(rec.pid)} (never kill own process group)`);
+            continue;
+        }
+        const alive = pidAlive(rec.pid);
+        const outcome = killGroup(rec.pgid);
+        if (outcome === "foreign") {
+            skipped.push(`pid ${String(rec.pid)} group is foreign-owned (EPERM)`);
+            continue;
+        }
+        reaped.push({ pid: rec.pid, alive });
+    }
+    writeFileSync(filePath, "", "utf8"); // truncate AFTER kills: a crash mid-reap re-kills idempotently
+    return { reaped, skipped, malformed };
+}
+/**
+ * Live-run recorder: an entry appears the moment a child spawns and vanishes
+ * when it exits, so a clean run leaves an empty log and a crashed run leaves
+ * exactly its orphans for the next reap. All file mutations are synchronous —
+ * there is no await window between spawn and record.
+ */
+export class ChildTracker {
+    filePath;
+    genId = "unassigned";
+    kind = "child";
+    pending = new Set();
+    constructor(genomeRepo) {
+        this.filePath = activeChildrenPath(genomeRepo);
+    }
+    /** Tag every child spawned from here on (phase transitions are sequential). */
+    phase(genId, kind) {
+        this.genId = genId;
+        this.kind = kind;
+    }
+    /** Adapter-facing ChildOptions.onChild sink: append-before-exec, remove-on-exit. */
+    onChild = (handle) => {
+        mkdirSync(path.dirname(this.filePath), { recursive: true });
+        const record = {
+            v: 1,
+            pid: handle.pid,
+            pgid: handle.pid, // runChild spawns detached ⇒ child.pid is its own process-group id
+            genId: this.genId,
+            kind: this.kind,
+            at: new Date().toISOString(),
+        };
+        writeFileSync(this.filePath, `${canonicalJson(record)}\n`, { flag: "a" });
+        const settled = handle.exited.then(() => {
+            this.pending.delete(settled);
+            this.remove(handle.pid);
+        });
+        this.pending.add(settled);
+    };
+    /** Resolve once every recorded child that exited has been removed from the log. */
+    async drain() {
+        while (this.pending.size > 0) {
+            await Promise.all([...this.pending]);
+        }
+    }
+    remove(pid) {
+        let text;
+        try {
+            text = readFileSync(this.filePath, "utf8");
+        }
+        catch {
+            return; // truncation (e.g. a reap) already owns the log
+        }
+        const lines = text.split("\n").filter((line) => line.length > 0);
+        const kept = lines.filter((line) => {
+            const rec = parseRecord(line);
+            return rec === null || rec.pid !== pid; // malformed lines survive until the next reap
+        });
+        if (kept.length === lines.length)
+            return;
+        const body = kept.length === 0 ? "" : `${kept.join("\n")}\n`;
+        const tmp = `${this.filePath}.tmp-${String(pid)}`;
+        writeFileSync(tmp, body, "utf8");
+        renameSync(tmp, this.filePath); // atomic swap: a crash mid-rewrite never truncates live entries
+    }
+}