@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/runs.js

@@ -0,0 +1,708 @@
+/**
+ * The agent run record (#3033, ws-076): what each agent run cost and which
+ * changes it made.
+ *
+ * chant records runs and never starts one (ws-052). Whatever ran the agent,
+ * a steward step, a factory, hud's chat or a lobby that proxies model calls,
+ * reports the run through `chant workspace runs start|end|record`, and
+ * chant appends it to the run ledger on `chant/lifecycle`, beside the work
+ * lease histories (ws-068: a ledger entry is a fact about a run, never
+ * revised). Nothing is written to the working tree, and no transcript is
+ * copied: the record pins one by sha256.
+ *
+ * ## Storage
+ *
+ * `_agent-runs/<run id>.jsonl` in the ledger of the workspace root (flat at
+ * the root, under `_members/<member>/` for a nested workspace). One file per
+ * run, so concurrent runs never contend for one file, with two kinds of line:
+ *
+ * - `start`: who the run worked for (`by`), the agent session, the harness,
+ *   model and provider, the work item and lease it worked under, the records
+ *   it worked on, and the instruction pinned by hash.
+ * - `end`: the outcome, the turns and tokens, the cost with its currency and
+ *   the source of its prices, the transcript pinned by hash, and the commits
+ *   the run made, each with its `git patch-id --stable` (#3036) and, when
+ *   the writer knows them, the hunks of it the run wrote (#3034).
+ * - `statement`: after the end, a DSSE envelope a runner or steward key
+ *   signed over the run (#3192, ./trust/run-statement.ts). A run may have
+ *   several, such as one per signer; none changes the record they sign.
+ *
+ * The file name is `_agent-runs`, not `runs`, because an Op run already has
+ * `<env>/runs__<op>.jsonl` (`../lifecycle/run-ledger.ts`).
+ *
+ * ## The join
+ *
+ * A commit names its run with the `Chant-Run` trailer (#3149, ws-075). The
+ * run's end can also list commits, which joins a commit that carries no
+ * trailer. `workspace runs` reports both, and `graph --intent` links each
+ * commit to its run.
+ *
+ * When neither holds, as after a rebase or a cherry-pick that dropped the
+ * trailer, a commit whose `git patch-id --stable` equals one the run's end
+ * recorded joins the run by content (#3036), marked `patch-id`. A content join
+ * never overrides a trailer or a record join: it is tried only for a commit
+ * that has neither. A squash of several commits has a patch-id of its own, so
+ * it never joins this way.
+ *
+ * A squash merge's commit carries none of its pull request's trailers or
+ * SHAs. When a read is asked to follow squashes (#3035, `squash.ts`), the
+ * squash commit joins every run its pull request's original commits join,
+ * marked `squash` with the originals in `via`.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { describeLifecyclePush, fetchLifecycleStatus, pushLifecycleStatus, readBlobBySha, RefCASConflictError, writeLedgerFiles } from "../lifecycle/git.js";
+import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
+import { sortedJsonReplacer } from "../utils.js";
+import { followSquashes } from "./squash.js";
+import { RUN_TRAILER, parseRecordRef } from "./trailers.js";
+import { runRecordDigest } from "./trust/run-statement.js";
+/** The directory on `chant/lifecycle` that holds the agent runs, under the workspace root's ledger prefix. */
+export const AGENT_RUNS_DIR = "_agent-runs";
+/** The branch the ledger is on. */
+export const LEDGER_BRANCH = "chant/lifecycle";
+/** A run id: one file name and one trailer value. */
+export const RUN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const COMMIT = /^[0-9a-f]{4,64}$/;
+const CURRENCY = /^[A-Z]{3}$/;
+// ── The caller's fields ──────────────────────────────────────────────────────
+const count = z.number().int().nonnegative();
+const nonEmpty = z.string().trim().min(1).refine((s) => !/[\r\n]/.test(s), "one line of text");
+const iso = z.string().refine((s) => !Number.isNaN(Date.parse(s)) && /^\d{4}-\d{2}-\d{2}T/.test(s), "an ISO 8601 date and time");
+const costSchema = z.object({ amount: z.number().nonnegative().finite(), currency: z.string().regex(CURRENCY, "an ISO 4217 code such as USD"), source: nonEmpty }).strict();
+const usageSchema = z.object({ turns: count.optional(), inputTokens: count.optional(), outputTokens: count.optional(), cacheReadTokens: count.optional(), cacheWriteTokens: count.optional() }).strict();
+const pinSchema = z
+    .object({ sha256: z.string().regex(SHA256, "64 lower-case hex digits").optional(), path: nonEmpty.optional(), ref: nonEmpty.optional() })
+    .strict()
+    .refine((p) => (p.sha256 === undefined) !== (p.path === undefined), "give sha256, or a path for chant to hash, not both");
+/** The longest instruction excerpt kept, in characters. */
+export const INSTRUCTION_EXCERPT_MAX = 500;
+const instructionSchema = z
+    .object({
+    sha256: z.string().regex(SHA256, "64 lower-case hex digits").optional(),
+    path: nonEmpty.optional(),
+    ref: nonEmpty.optional(),
+    excerpt: z.string().trim().min(1).max(INSTRUCTION_EXCERPT_MAX).optional(),
+})
+    .strict()
+    .refine((p) => (p.sha256 === undefined) !== (p.path === undefined), "give sha256, or a path for chant to hash, not both");
+const lineNumber = z.number().int().positive();
+const hunkSchema = z
+    .object({ path: nonEmpty, start: lineNumber, end: lineNumber })
+    .strict()
+    .refine((h) => h.end >= h.start, "end is not before start")
+    .refine((h) => !h.path.startsWith("/") && !h.path.split("/").includes(".."), "a path from the repository root");
+const commitSchema = z.union([z.string().regex(COMMIT, "a commit id"), z.object({ sha: z.string().regex(COMMIT, "a commit id"), hunks: z.array(hunkSchema).min(1) }).strict()]);
+const startFields = {
+    id: z.string().regex(RUN_ID_PATTERN, "letters, digits, '.', '_' and '-', starting with a letter or digit").optional(),
+    startedAt: iso.optional(),
+    by: nonEmpty.optional(),
+    agent: nonEmpty.optional(),
+    harness: z.union([nonEmpty, z.object({ name: nonEmpty, version: nonEmpty.optional() }).strict()]),
+    model: nonEmpty.optional(),
+    provider: nonEmpty.optional(),
+    unit: z.union([nonEmpty, z.object({ id: nonEmpty, kind: nonEmpty.optional() }).strict()]).optional(),
+    lease: nonEmpty.optional(),
+    records: z.array(z.string().refine((s) => parseRecordRef(s) !== undefined, "<kind>:<id>")).optional(),
+    instruction: instructionSchema.optional(),
+};
+const endFields = {
+    endedAt: iso.optional(),
+    outcome: nonEmpty.optional(),
+    usage: usageSchema.optional(),
+    models: z.array(z.object({ model: nonEmpty, provider: nonEmpty.optional(), inputTokens: count.optional(), outputTokens: count.optional(), cacheReadTokens: count.optional(), cacheWriteTokens: count.optional(), cost: costSchema.optional() }).strict()).optional(),
+    cost: costSchema.optional(),
+    transcript: pinSchema.optional(),
+    commits: z.array(commitSchema).optional(),
+};
+/** The fields `runs start --from` takes. */
+export const runStartInputSchema = z.object(startFields).strict();
+/** The fields `runs end <id> --from` takes. */
+export const runEndInputSchema = z.object(endFields).strict();
+/** The fields `runs record --from` takes: a start and an end in one. */
+export const runRecordInputSchema = z.object({ ...startFields, ...endFields }).strict();
+export class RunWriteError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RunWriteError";
+    }
+}
+// ── Git ──────────────────────────────────────────────────────────────────────
+function git(top, args, input) {
+    try {
+        return execFileSync("git", args, { cwd: top, encoding: "utf-8", input, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The full id of `rev` as a commit, or undefined. */
+function commitId(top, rev) {
+    return git(top, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`])?.trim() || undefined;
+}
+/** `git patch-id --stable` of one commit, or null when it has no patch, such as a merge. */
+export function patchIdOf(top, sha) {
+    const patch = git(top, ["show", "--format=", "--patch", "--no-color", "--no-ext-diff", sha]);
+    if (!patch || patch.trim() === "")
+        return null;
+    const out = git(top, ["patch-id", "--stable"], patch);
+    return out?.trim().split(/\s+/)[0] || null;
+}
+/** Parse `git patch-id` output, `<patch-id> <commit>` per line, into commit to patch-id. */
+function parsePatchIds(out) {
+    const ids = new Map();
+    for (const line of (out ?? "").split("\n")) {
+        const [patchId, sha] = line.trim().split(/\s+/);
+        if (patchId && sha && !ids.has(sha))
+            ids.set(sha, patchId);
+    }
+    return ids;
+}
+/**
+ * `git patch-id --stable` of each commit, in two git calls however many there
+ * are (#3036). A commit with no patch, such as a merge, is left out.
+ */
+export function patchIdsOf(top, shas) {
+    if (shas.length === 0)
+        return new Map();
+    const patches = git(top, ["log", "--no-walk=unsorted", "--stdin", "--no-merges", "--format=commit %H", "--patch", "--no-color", "--no-ext-diff"], `${shas.join("\n")}\n`);
+    if (!patches?.trim())
+        return new Map();
+    return parsePatchIds(git(top, ["patch-id", "--stable"], patches));
+}
+/**
+ * `git patch-id --stable` of each commit reachable from `rev` and committed
+ * after `since` (ISO 8601), merges left out (#3036). A rebase or a
+ * cherry-pick commits anew, so a rewritten commit is never older than the
+ * one it was rewritten from.
+ */
+export function patchIdsSince(top, rev, since) {
+    if (!commitId(top, rev))
+        return new Map();
+    const patches = git(top, ["log", rev, `--since=${since}`, "--no-merges", "--format=commit %H", "--patch", "--no-color", "--no-ext-diff"]);
+    if (!patches?.trim())
+        return new Map();
+    return parsePatchIds(git(top, ["patch-id", "--stable"], patches));
+}
+function hashFile(path) {
+    const bytes = readFileSync(path);
+    return { sha256: createHash("sha256").update(bytes).digest("hex"), bytes: statSync(path).size, ref: null };
+}
+function pinOf(p, cwd, what) {
+    if (!p)
+        return null;
+    const excerpt = p.excerpt === undefined ? {} : { excerpt: p.excerpt };
+    if (p.sha256)
+        return { sha256: p.sha256, bytes: null, ref: p.ref ?? null, ...excerpt };
+    const path = resolve(cwd, p.path);
+    let pin;
+    try {
+        pin = hashFile(path);
+    }
+    catch (err) {
+        throw new RunWriteError("write-input-invalid", `${what}.path ${p.path} can't be read to hash it: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { ...pin, ref: p.ref ?? p.path, ...excerpt };
+}
+// ── Building the lines ───────────────────────────────────────────────────────
+/** A new run id: the start time to the second, and eight random hex digits. */
+export function newRunId(now) {
+    return `${now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z")}-${randomBytes(4).toString("hex")}`;
+}
+function parseInput(schema, value, verb) {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+        throw new RunWriteError("write-input-invalid", `runs ${verb}: ${parsed.error.issues.map((i) => `${i.path.length ? i.path.join(".") : "the fields"}: ${i.message}`).join("; ")}`);
+    }
+    return parsed.data;
+}
+function startLine(input, id, at, cwd) {
+    const harness = typeof input.harness === "string" ? { name: input.harness, version: null } : { name: input.harness.name, version: input.harness.version ?? null };
+    const unit = input.unit === undefined ? null : typeof input.unit === "string" ? { id: input.unit, kind: null } : { id: input.unit.id, kind: input.unit.kind ?? null };
+    return {
+        version: 1,
+        event: "start",
+        run: id,
+        at,
+        by: input.by ?? null,
+        agent: input.agent ?? null,
+        harness,
+        model: input.model ?? null,
+        provider: input.provider ?? null,
+        unit,
+        lease: input.lease ?? null,
+        records: (input.records ?? []).map((r) => parseRecordRef(r)),
+        instruction: pinOf(input.instruction, cwd, "instruction"),
+    };
+}
+function endLine(input, id, at, top, cwd) {
+    const commits = [];
+    for (const entry of input.commits ?? []) {
+        const c = typeof entry === "string" ? entry : entry.sha;
+        const sha = commitId(top, c);
+        if (!sha)
+            throw new RunWriteError("write-input-invalid", `commits: ${c} names no commit in this repository`);
+        const hunks = typeof entry === "string" ? undefined : entry.hunks.map((h) => ({ path: h.path, start: h.start, end: h.end }));
+        const listed = commits.find((x) => x.sha === sha);
+        if (listed) {
+            if (hunks)
+                listed.hunks = [...(listed.hunks ?? []), ...hunks];
+        }
+        else
+            commits.push({ sha, patchId: patchIdOf(top, sha), ...(hunks ? { hunks } : {}) });
+    }
+    const usage = input.usage
+        ? { turns: input.usage.turns ?? null, inputTokens: input.usage.inputTokens ?? null, outputTokens: input.usage.outputTokens ?? null, cacheReadTokens: input.usage.cacheReadTokens ?? null, cacheWriteTokens: input.usage.cacheWriteTokens ?? null }
+        : null;
+    return {
+        version: 1,
+        event: "end",
+        run: id,
+        at,
+        outcome: input.outcome ?? null,
+        usage,
+        models: (input.models ?? []).map((m) => ({
+            model: m.model,
+            provider: m.provider ?? null,
+            inputTokens: m.inputTokens ?? null,
+            outputTokens: m.outputTokens ?? null,
+            cacheReadTokens: m.cacheReadTokens ?? null,
+            cacheWriteTokens: m.cacheWriteTokens ?? null,
+            cost: m.cost ?? null,
+        })),
+        cost: input.cost ?? null,
+        transcript: pinOf(input.transcript, cwd, "transcript"),
+        commits,
+    };
+}
+// ── Reading the ledger ───────────────────────────────────────────────────────
+/** Parse one run file, oldest line first. Lines that aren't run events are counted and skipped. */
+export function parseRunFile(content, id) {
+    const lines = [];
+    let malformed = 0;
+    for (const raw of content.split("\n").map((l) => l.trim()).filter(Boolean)) {
+        try {
+            const v = JSON.parse(raw);
+            const statement = v.event === "statement" && typeof v.envelope === "object" && v.envelope !== null;
+            const ok = v.version === 1 && (v.event === "start" || v.event === "end" || statement) && v.run === id && typeof v.at === "string";
+            if (ok)
+                lines.push(v);
+            else
+                malformed++;
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { lines, malformed };
+}
+/** The ledger directory of the workspace whose root is `rootOnDisk`, on the branch. */
+export async function runsDir(rootOnDisk) {
+    const { prefix } = await resolveMemberLedger(rootOnDisk);
+    return `${prefix}${AGENT_RUNS_DIR}`;
+}
+/** Every run file in `dir` on the local branch, or on `ref` when given, by run id, and the branch tip read. Never fetches. */
+export function readRunFiles(top, dir, ref = `refs/heads/${LEDGER_BRANCH}`) {
+    const files = new Map();
+    const tip = commitId(top, ref) ?? null;
+    if (!tip)
+        return { tip, files };
+    const listing = git(top, ["ls-tree", "-z", `${tip}:${dir}`]);
+    if (!listing)
+        return { tip, files };
+    const entries = [];
+    for (const entry of listing.split("\0").filter(Boolean)) {
+        const tab = entry.indexOf("\t");
+        const [, type, sha] = entry.slice(0, tab).split(" ");
+        const name = entry.slice(tab + 1);
+        const m = name.match(/^(.+)\.jsonl$/);
+        if (type === "blob" && m && RUN_ID_PATTERN.test(m[1]))
+            entries.push({ id: m[1], sha });
+    }
+    if (entries.length === 0)
+        return { tip, files };
+    const batch = git(top, ["cat-file", "--batch"], `${entries.map((e) => e.sha).join("\n")}\n`) ?? "";
+    // Each object: "<sha> blob <size>\n<content>\n".
+    let pos = 0;
+    for (const e of entries) {
+        const nl = batch.indexOf("\n", pos);
+        if (nl < 0)
+            break;
+        const size = Number(batch.slice(pos, nl).split(" ")[2]);
+        const start = nl + 1;
+        const content = Buffer.from(batch.slice(start)).subarray(0, size).toString("utf-8");
+        files.set(e.id, { path: `${dir}/${e.id}.jsonl`, content });
+        pos = start + content.length + 1;
+    }
+    return { tip, files };
+}
+const APPEND_RETRY_ATTEMPTS = 5;
+/**
+ * Append `make(existing)`'s lines to run `id`'s file, with the read-then-CAS
+ * retry the lease history uses, then push `chant/lifecycle` best-effort.
+ */
+async function appendRun(top, rootOnDisk, id, make, message) {
+    await fetchLifecycleStatus({ cwd: top }).catch(() => undefined);
+    const dir = await runsDir(rootOnDisk);
+    const path = `${dir}/${id}.jsonl`;
+    let commit;
+    let written = [];
+    let lastErr;
+    for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS && commit === undefined; attempt++) {
+        const prior = git(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${LEDGER_BRANCH}:${path}`])?.trim() || null;
+        const text = prior ? ((await readBlobBySha(prior, { cwd: top })) ?? "") : "";
+        const existing = parseRunFile(text, id).lines;
+        const lines = make(existing);
+        const content = [text.replace(/\n$/, ""), ...lines.map((l) => JSON.stringify(l, sortedJsonReplacer))].filter(Boolean).join("\n");
+        try {
+            commit = await writeLedgerFiles([{ path, content, expectPriorSha: prior }], message, { cwd: top });
+            written = [...existing, ...lines];
+        }
+        catch (err) {
+            if (!(err instanceof RefCASConflictError))
+                throw err;
+            lastErr = err;
+        }
+    }
+    if (commit === undefined)
+        throw lastErr;
+    const push = await pushLifecycleStatus({ cwd: top }).catch((err) => ({ status: "failed", remote: "(unknown)", stderr: err instanceof Error ? err.message : String(err) }));
+    const notPushed = describeLifecyclePush(push);
+    return { id, lines: written, ledger: { branch: LEDGER_BRANCH, path, commit, pushed: push.status === "pushed", ...(notPushed ? { notPushed } : {}) } };
+}
+/** `runs start`: a run's start, with a new id unless the fields give one. Refused with `run-exists` for an id in use. */
+export async function startRun(fields, ctx) {
+    const input = parseInput(runStartInputSchema, fields, "start");
+    const startedAt = input.startedAt ?? (ctx.now?.() ?? new Date()).toISOString();
+    const id = input.id ?? newRunId(new Date(startedAt));
+    const line = startLine(input, id, startedAt, ctx.cwd);
+    return appendRun(ctx.top, ctx.rootOnDisk, id, (existing) => {
+        if (existing.length > 0)
+            throw new RunWriteError("run-exists", `the ledger already has an agent run ${id}`);
+        return [line];
+    }, `Agent run start: ${id}`);
+}
+/** `runs end <id>`: a started run's end. Refused with `run-unknown` when it never started and `run-ended` when it already ended. */
+export async function endRun(id, fields, ctx) {
+    if (!RUN_ID_PATTERN.test(id))
+        throw new RunWriteError("run-unknown", `${JSON.stringify(id)} is not a run id`);
+    const input = parseInput(runEndInputSchema, fields, "end");
+    const now = ctx.now?.() ?? new Date();
+    const line = endLine(input, id, input.endedAt ?? now.toISOString(), ctx.top, ctx.cwd);
+    return appendRun(ctx.top, ctx.rootOnDisk, id, (existing) => {
+        const start = existing.find((l) => l.event === "start");
+        if (!start)
+            throw new RunWriteError("run-unknown", `the ledger has no agent run ${id}; start it with runs start, or report a finished run with runs record`);
+        if (existing.some((l) => l.event === "end"))
+            throw new RunWriteError("run-ended", `agent run ${id} has already ended`);
+        if (Date.parse(line.at) < Date.parse(start.at))
+            throw new RunWriteError("write-input-invalid", `endedAt ${line.at} is before the run started at ${start.at}`);
+        return [line];
+    }, `Agent run end: ${id}`);
+}
+/** `runs record`: a run that has finished, its start and end in one write. */
+export async function recordRun(fields, ctx) {
+    const input = parseInput(runRecordInputSchema, fields, "record");
+    const now = ctx.now?.() ?? new Date();
+    const endedAt = input.endedAt ?? now.toISOString();
+    const startedAt = input.startedAt ?? endedAt;
+    if (Date.parse(endedAt) < Date.parse(startedAt))
+        throw new RunWriteError("write-input-invalid", `endedAt ${endedAt} is before startedAt ${startedAt}`);
+    const id = input.id ?? newRunId(new Date(startedAt));
+    const start = startLine(input, id, startedAt, ctx.cwd);
+    const end = endLine(input, id, endedAt, ctx.top, ctx.cwd);
+    return appendRun(ctx.top, ctx.rootOnDisk, id, (existing) => {
+        if (existing.length > 0)
+            throw new RunWriteError("run-exists", `the ledger already has an agent run ${id}`);
+        return [start, end];
+    }, `Agent run: ${id}`);
+}
+/**
+ * `runs sign <id>`: append a statement over an ended run (#3192). The caller
+ * has built or checked the envelope against the record whose hash is
+ * `recordSha256`; the append refuses if the ledger's record is not that one.
+ */
+export async function appendRunStatement(id, envelope, recordSha256, ctx) {
+    if (!RUN_ID_PATTERN.test(id))
+        throw new RunWriteError("run-unknown", `${JSON.stringify(id)} is not a run id`);
+    const at = (ctx.now?.() ?? new Date()).toISOString();
+    return appendRun(ctx.top, ctx.rootOnDisk, id, (existing) => {
+        const start = existing.find((l) => l.event === "start");
+        const end = existing.find((l) => l.event === "end");
+        if (!start)
+            throw new RunWriteError("run-unknown", `the ledger has no agent run ${id}`);
+        if (!end)
+            throw new RunWriteError("run-not-ended", `agent run ${id} has not ended; a statement is signed over a run's whole record, so record its end first`);
+        if (runRecordDigest(start, end) !== recordSha256)
+            throw new RunWriteError("run-statement-mismatch", `agent run ${id}'s record changed while it was being signed; sign it again`);
+        return [{ version: 1, event: "statement", run: id, at, envelope }];
+    }, `Agent run statement: ${id}`);
+}
+/** The order a reader lists joins in: the commit's own trailer first, a squash's originals last. */
+export const RUN_JOIN_ORDER = ["trailer", "record", "patch-id", "squash"];
+/** Fold a run's lines into one view, or undefined when it has no start. */
+export function foldRun(id, path, lines) {
+    const start = lines.find((l) => l.event === "start");
+    if (!start)
+        return undefined;
+    const end = lines.find((l) => l.event === "end");
+    return {
+        id,
+        state: end ? "ended" : "running",
+        startedAt: start.at,
+        endedAt: end?.at ?? null,
+        outcome: end?.outcome ?? null,
+        by: start.by,
+        agent: start.agent,
+        harness: start.harness,
+        model: start.model,
+        provider: start.provider,
+        unit: start.unit,
+        lease: start.lease,
+        records: start.records ?? [],
+        instruction: start.instruction ?? null,
+        usage: end?.usage ?? null,
+        models: end?.models ?? [],
+        cost: end?.cost ?? null,
+        transcript: end?.transcript ?? null,
+        commits: (end?.commits ?? []).map((c) => ({ sha: c.sha, patchId: c.patchId, joinedBy: ["record"], hunks: Array.isArray(c.hunks) && c.hunks.length > 0 ? c.hunks : null })),
+        decisions: [],
+        ledger: path,
+        record: end ? { sha256: runRecordDigest(start, end) } : null,
+        statements: lines.filter((l) => l.event === "statement").map((l) => ({ at: l.at, envelope: l.envelope })),
+    };
+}
+/** Every run in the ledger of the workspace at `rootOnDisk`, by id, with the malformed line count. Never fetches. */
+export async function readRuns(top, rootOnDisk) {
+    const dir = await runsDir(rootOnDisk);
+    const { tip, files } = readRunFiles(top, dir);
+    const runs = new Map();
+    let malformed = 0;
+    for (const [id, f] of files) {
+        const parsed = parseRunFile(f.content, id);
+        malformed += parsed.malformed;
+        const view = foldRun(id, f.path, parsed.lines);
+        if (view)
+            runs.set(id, view);
+        else
+            malformed += parsed.lines.length;
+    }
+    return { tip, dir, runs, malformed };
+}
+/**
+ * The commits reachable from `rev` that carry a `Chant-Run` trailer, by run
+ * id, newest first. One `git log` over the history; nothing is fetched.
+ */
+export function commitsByRunTrailer(top, rev = "HEAD") {
+    const out = new Map();
+    if (!commitId(top, rev))
+        return out;
+    const text = git(top, ["log", rev, `--format=%x00%H%x1f%(trailers:key=${RUN_TRAILER},valueonly,separator=%x1e)`]) ?? "";
+    for (const record of text.split("\0")) {
+        if (!record.trim())
+            continue;
+        const [sha, values] = record.split("\x1f");
+        for (const v of (values ?? "").split("\x1e").map((x) => x.trim()).filter(Boolean))
+            (out.get(v) ?? out.set(v, []).get(v)).push(sha.trim());
+    }
+    return out;
+}
+/** Add the commits that name each run by trailer to its `commits`, after the ones its end lists. */
+export function joinTrailerCommits(runs, byTrailer, top) {
+    for (const [id, shas] of byTrailer) {
+        const run = runs.get(id);
+        if (!run)
+            continue;
+        for (const sha of shas) {
+            const listed = run.commits.find((c) => c.sha === sha);
+            if (listed) {
+                if (!listed.joinedBy.includes("trailer"))
+                    listed.joinedBy.push("trailer");
+            }
+            else
+                run.commits.push({ sha, patchId: patchIdOf(top, sha), joinedBy: ["trailer"], hunks: null });
+        }
+    }
+}
+/** A day, the slack {@link joinPatchIdCommits} gives a run's start against clocks that disagree. */
+const CLOCK_SLACK_MS = 24 * 60 * 60 * 1000;
+/** Each recorded patch-id, to the runs whose end listed a commit with it and that commit. */
+export function recordedPatchIds(runs) {
+    const out = new Map();
+    for (const r of runs) {
+        for (const c of r.commits) {
+            if (!c.patchId || !c.joinedBy.includes("record"))
+                continue;
+            const list = out.get(c.patchId) ?? out.set(c.patchId, []).get(c.patchId);
+            if (!list.some((x) => x.run === r.id && x.sha === c.sha))
+                list.push({ run: r.id, sha: c.sha });
+        }
+    }
+    return out;
+}
+/**
+ * Add to each run the commits on `rev`'s history that join it by content
+ * (#3036): a commit that no run lists, that carries no `Chant-Run`, and whose
+ * patch-id equals one the run's end recorded. Only commits made since the
+ * earliest such run started are read, less a day for clocks.
+ */
+export function joinPatchIdCommits(runs, byTrailer, top, rev = "HEAD") {
+    const recorded = recordedPatchIds(runs.values());
+    if (recorded.size === 0)
+        return;
+    const starts = [...new Set([...recorded.values()].flat().map((x) => x.run))].map((id) => Date.parse(runs.get(id).startedAt)).filter((t) => !Number.isNaN(t));
+    if (starts.length === 0)
+        return;
+    const since = new Date(Math.min(...starts) - CLOCK_SLACK_MS).toISOString();
+    const joined = new Set([...byTrailer.values()].flat());
+    for (const r of runs.values())
+        for (const c of r.commits)
+            joined.add(c.sha);
+    for (const [sha, patchId] of patchIdsSince(top, rev, since)) {
+        if (joined.has(sha))
+            continue;
+        for (const hit of recorded.get(patchId) ?? []) {
+            const run = runs.get(hit.run);
+            if (!run.commits.some((c) => c.sha === sha))
+                run.commits.push({ sha, patchId, joinedBy: ["patch-id"], hunks: null, recordedAs: hit.sha });
+        }
+    }
+}
+/**
+ * For each commit, the runs that made it: the run its `Chant-Run` trailer
+ * names, and every run whose end lists it. A commit with neither joins every
+ * run whose end recorded its patch-id (#3036). Reads the run ledger once from
+ * the local branch; never fetches.
+ */
+export async function runsForCommits(top, rootOnDisk, commits) {
+    let runs = new Map();
+    try {
+        runs = (await readRuns(top, rootOnDisk)).runs;
+    }
+    catch {
+        // A ledger that can't be located leaves every run unrecorded; the trailers still say which.
+    }
+    const listing = new Map();
+    for (const r of runs.values())
+        for (const c of r.commits)
+            (listing.get(c.sha) ?? listing.set(c.sha, []).get(c.sha)).push(r.id);
+    // The content join (#3036): only when some run recorded a patch-id, and only for the commits read.
+    const recorded = recordedPatchIds(runs.values());
+    const patchIds = recorded.size > 0 ? patchIdsOf(top, commits.map((c) => c.sha)) : new Map();
+    const refs = new Map();
+    const conflicts = [];
+    const refOf = (id, joinedBy, recordedAs) => {
+        const r = runs.get(id);
+        return {
+            id,
+            recorded: r !== undefined,
+            state: r?.state ?? null,
+            harness: r?.harness.name ?? null,
+            model: r?.model ?? null,
+            provider: r?.provider ?? null,
+            by: r?.by ?? null,
+            agent: r?.agent ?? null,
+            unit: r?.unit?.id ?? null,
+            joinedBy,
+            ...(recordedAs ? { recordedAs } : {}),
+        };
+    };
+    for (const c of commits) {
+        const listed = listing.get(c.sha) ?? [];
+        const ids = [...new Set([...(c.run ? [c.run] : []), ...listed])];
+        const matches = (recorded.get(patchIds.get(c.sha) ?? "") ?? []).filter((m) => m.sha !== c.sha);
+        if (ids.length > 0) {
+            const others = matches.filter((m) => !ids.includes(m.run));
+            if (others.length > 0)
+                conflicts.push({ sha: c.sha, joined: ids, content: others });
+            refs.set(c.sha, ids.map((id) => refOf(id, [...(c.run === id ? ["trailer"] : []), ...(listed.includes(id) ? ["record"] : [])])));
+            continue;
+        }
+        const byRun = new Map();
+        for (const m of matches)
+            if (!byRun.has(m.run))
+                byRun.set(m.run, m.sha);
+        refs.set(c.sha, [...byRun].map(([id, recordedAs]) => refOf(id, ["patch-id"], recordedAs)));
+    }
+    return { refs, runs, conflicts };
+}
+/**
+ * Give each followed squash commit the runs its original commits join
+ * (#3035): `refs` must hold the originals' runs. A run the squash already
+ * joins gets `squash` added; another is added with `joinedBy: ["squash"]`.
+ * `via` lists the originals that join it.
+ */
+export function addSquashRuns(refs, follows) {
+    for (const f of follows.values()) {
+        if (!f.followed)
+            continue;
+        const list = refs.get(f.sha) ?? refs.set(f.sha, []).get(f.sha);
+        for (const o of f.commits) {
+            for (const r of refs.get(o) ?? []) {
+                const have = list.find((x) => x.id === r.id);
+                if (have) {
+                    if (!have.joinedBy.includes("squash"))
+                        have.joinedBy.push("squash");
+                    have.via = [...new Set([...(have.via ?? []), o])];
+                    continue;
+                }
+                const { recordedAs: _r, via: _v, ...rest } = r;
+                list.push({ ...rest, joinedBy: ["squash"], via: [o] });
+            }
+        }
+    }
+}
+/**
+ * Follow the squash merges on `rev`'s history made since the earliest run
+ * started (#3035), and add each to the runs its pull request's original
+ * commits join: a commit a run's end lists, or one whose `Chant-Run` names
+ * the run. Missing pull request refs are fetched from `origin`. Returns what
+ * each squash's follow found, for the read's reasons.
+ */
+export function joinSquashCommits(runs, top, rev = "HEAD") {
+    const starts = [...runs.values()].map((r) => Date.parse(r.startedAt)).filter((t) => !Number.isNaN(t));
+    if (starts.length === 0 || !commitId(top, rev))
+        return [];
+    const since = new Date(Math.min(...starts) - CLOCK_SLACK_MS).toISOString();
+    const candidates = [];
+    for (const line of (git(top, ["log", rev, `--since=${since}`, "--no-merges", "--format=%H%x1f%s"]) ?? "").split("\n")) {
+        const [sha, subject] = line.split("\x1f");
+        if (sha && subject !== undefined)
+            candidates.push({ sha: sha.trim(), subject });
+    }
+    const follows = followSquashes(top, candidates, { fetchMissing: true });
+    const originals = [...new Set([...follows.values()].flatMap((f) => f.commits))];
+    const trailerRun = new Map();
+    if (originals.length > 0) {
+        const text = git(top, ["log", "--no-walk=unsorted", "--stdin", `--format=%x00%H%x1f%(trailers:key=${RUN_TRAILER},valueonly,separator=%x1e)`], `${originals.join("\n")}\n`) ?? "";
+        for (const record of text.split("\0")) {
+            if (!record.trim())
+                continue;
+            const [sha, values] = record.split("\x1f");
+            trailerRun.set(sha.trim(), (values ?? "").split("\x1e").map((x) => x.trim()).filter(Boolean));
+        }
+    }
+    for (const f of follows.values()) {
+        if (!f.followed)
+            continue;
+        for (const r of runs.values()) {
+            const via = f.commits.filter((o) => r.commits.some((c) => c.sha === o && c.joinedBy.some((j) => j !== "squash")) || (trailerRun.get(o) ?? []).includes(r.id));
+            if (via.length === 0)
+                continue;
+            const listed = r.commits.find((c) => c.sha === f.sha);
+            if (listed) {
+                if (!listed.joinedBy.includes("squash"))
+                    listed.joinedBy.push("squash");
+                listed.via = [...new Set([...(listed.via ?? []), ...via])];
+            }
+            else
+                r.commits.push({ sha: f.sha, patchId: patchIdOf(top, f.sha), joinedBy: ["squash"], hunks: null, via });
+        }
+    }
+    return [...follows.values()];
+}