balladeer 1.0.14 → 1.0.16

package/dist/commands/judge.js

@@ -0,0 +1,1170 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { CASE_ID, PROMISE_ID, parseBehaviorMap } from "../behavior-map-schema.js";
+import { runCommand } from "../gh.js";
+import { repositoryRoot } from "../git.js";
+import { agentEnvironment, resolveClient, runHeadlessAgent, JUDGE_ACTIVE_VARIABLE, } from "../headless-agent.js";
+import { JUDGE_BRIEF_REVISION, judgePrompt } from "../judge-brief.js";
+import { effectiveBudgetSeconds, hookResponse, installJudgeHook, isPushCommand, parseHookInput, parsePrePushInput, } from "../judge-hook.js";
+import { runOwnedProcess, tail } from "../owned-process.js";
+import { caseIds, connectionReader, promiseFromExcerpt, readPromiseFile, sha256Digest, } from "../promise-meaning.js";
+import { addScratchWorktree, carryFiles, newFiles, removeLiveWorktreesNow, resolveCommit, shareDependencies, } from "../scratch-worktree.js";
+import { normalizeControlPlane, StoreError } from "../store.js";
+import { CLI_INVOCATION, DEFAULT_CONTROL_PLANE } from "../wire.js";
+import { AGENT_TOOLS, REFUSED_TOOL_RULES, agentFailure, readBehaviorMap, readBehaviorMaps, } from "./map.js";
+import { offersForPush } from "./offers.js";
+/**
+ * `balladeer judge`: for a change about to leave this machine, ask the person's
+ * own coding agent, one promise at a time, whether the change keeps it.
+ *
+ * A verdict is only as good as its evidence, so the runner does not take a
+ * judge's word for a break. A judge that says "broken" must hand back a command,
+ * and the runner runs that command itself, once at head and once in a clean
+ * checkout of base: it must fail with the change and pass without it. Anything
+ * short of that is "could not tell", with the reason kept. Nothing here ever
+ * says a promise is protected; a judge's "kept" is a local reading of one
+ * change, not a check that holds.
+ */
+export const JUDGE_VERDICT_SCHEMA_VERSION = "balladeer-judge-verdict/v1";
+export const JUDGE_CONFIG_SCHEMA_VERSION = "balladeer-judge-config/v1";
+export const JUDGE_CONFIG_PATH = ".continuity/judge.json";
+export const JUDGE_LOG_DIRECTORY = ".continuity/judge-log";
+export const STILL_JUDGING = "still judging; rerun `balladeer judge --wait`";
+/** However long `--wait` allows, one judge is stopped after this. */
+const JUDGE_CAP_MS = 15 * 60_000;
+const LINKED_TEST_TIMEOUT_MS = 3 * 60_000;
+const REPRODUCTION_TIMEOUT_MS = 5 * 60_000;
+export const DEFAULT_JUDGE_CONFIG = {
+    schemaVersion: JUDGE_CONFIG_SCHEMA_VERSION,
+    mode: "report",
+    topK: 8,
+    concurrency: 3,
+    budgetSeconds: 240,
+    sampleBelowLine: 0.1,
+    alwaysJudge: [],
+    client: "auto",
+    offers: false,
+    offersOn: "fixes",
+    maxOffers: 1,
+};
+/**
+ * Whether the configuration turns offers on with the key the first exploration
+ * used. That key is refused rather than read: its word is one nobody should be
+ * asked to learn, and a switch that starts a reading on every push is not one
+ * to keep honoring under an old name.
+ */
+function usesRetiredOffersKey(input) {
+    return input["candidates"] !== undefined;
+}
+/**
+ * `.continuity/judge.json`, with the contract's defaults for anything absent.
+ * A field that is present and wrong keeps its default and is named, so a typo
+ * in a team's config is visible rather than quietly ignored.
+ */
+export function readJudgeConfig(root) {
+    const path = join(root, JUDGE_CONFIG_PATH);
+    if (!existsSync(path))
+        return { config: DEFAULT_JUDGE_CONFIG, problems: [] };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {
+            config: DEFAULT_JUDGE_CONFIG,
+            problems: [`${JUDGE_CONFIG_PATH} is not JSON, so the defaults were used`],
+        };
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return {
+            config: DEFAULT_JUDGE_CONFIG,
+            problems: [`${JUDGE_CONFIG_PATH} is not an object, so the defaults were used`],
+        };
+    const input = raw;
+    const problems = [];
+    const pick = (key, valid, fallback) => {
+        if (!(key in input))
+            return fallback;
+        if (valid(input[key]))
+            return input[key];
+        problems.push(`${key} in ${JUDGE_CONFIG_PATH} is not valid, so ${JSON.stringify(fallback)} was used`);
+        return fallback;
+    };
+    const whole = (min, max) => (value) => typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
+    const d = DEFAULT_JUDGE_CONFIG;
+    if (usesRetiredOffersKey(input))
+        problems.push(`${JUDGE_CONFIG_PATH} turns offers on with a key that is no longer read; write "offers": true instead`);
+    return {
+        config: {
+            schemaVersion: JUDGE_CONFIG_SCHEMA_VERSION,
+            mode: pick("mode", (v) => v === "report" || v === "block", d.mode),
+            topK: pick("topK", whole(0, 100), d.topK),
+            concurrency: pick("concurrency", whole(1, 16), d.concurrency),
+            budgetSeconds: pick("budgetSeconds", (v) => typeof v === "number" && Number.isFinite(v) && v > 0 && v <= 3600, d.budgetSeconds),
+            sampleBelowLine: pick("sampleBelowLine", (v) => typeof v === "number" && v >= 0 && v <= 1, d.sampleBelowLine),
+            alwaysJudge: pick("alwaysJudge", (v) => Array.isArray(v) && v.every((id) => typeof id === "string" && PROMISE_ID.test(id)), [...d.alwaysJudge]),
+            client: pick("client", (v) => v === "auto" || v === "claude" || v === "codex", d.client),
+            offers: pick("offers", (v) => typeof v === "boolean", d.offers),
+            offersOn: pick("offersOn", (v) => v === "fixes" || v === "all", d.offersOn),
+            maxOffers: pick("maxOffers", whole(1, 3), d.maxOffers),
+        },
+        problems,
+    };
+}
+function runEnvironment(parent) {
+    // CI keeps a test runner out of watch mode, which would otherwise hold the
+    // command open until its time ran out.
+    return { ...agentEnvironment(parent), CI: "1" };
+}
+export async function runShell(command, cwd, options) {
+    const run = await runOwnedProcess({
+        command: "/bin/sh",
+        args: ["-c", command],
+        cwd,
+        env: runEnvironment(options.env),
+        timeoutMs: options.timeoutMs,
+        maxOutputBytes: 1024 * 1024,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    return {
+        exitCode: run.spawnError !== undefined ? null : run.exitCode,
+        timedOut: run.timedOut || run.bounded,
+        aborted: run.aborted,
+        output: tail(`${run.stdout}\n${run.stderr}`, 1500),
+    };
+}
+function insideDirectory(root, cwd) {
+    const target = resolve(root, cwd || ".");
+    const inside = relative(root, target);
+    return inside.startsWith("..") || isAbsolute(inside) ? undefined : target;
+}
+/**
+ * Run a judge's reproduction both ways.
+ *
+ * At head, in the judge's own checkout, reset to head so a judge that left it
+ * on base cannot fool the check. At base, in a fresh checkout of base, with the
+ * files the judge added carried across so a new test exists on both sides. It
+ * must exit non-zero at head and zero at base; either disagreeing rejects it,
+ * and the reason says which.
+ */
+export async function verifyReproduction(input) {
+    const timeoutMs = input.timeoutMs ?? REPRODUCTION_TIMEOUT_MS;
+    const seconds = Math.round(timeoutMs / 1000);
+    await runCommand("git", [
+        "-C",
+        input.headTree,
+        "checkout",
+        "--quiet",
+        "--detach",
+        "--force",
+        input.head,
+    ]);
+    const carried = await newFiles(input.headTree);
+    const digest = sha256Digest({ command: input.command, cwd: input.cwd, files: carried });
+    const reject = (failsOnHead, passesOnBase, rejected) => ({
+        failsOnHead,
+        passesOnBase,
+        digest,
+        rejected,
+        stopped: false,
+    });
+    const headCwd = insideDirectory(input.headTree, input.cwd);
+    if (headCwd === undefined || !existsSync(headCwd))
+        return reject(false, false, `its cwd ${input.cwd} is not a directory inside the repository`);
+    const atHead = await runShell(input.command, headCwd, {
+        env: input.env,
+        timeoutMs,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    if (atHead.aborted)
+        return { failsOnHead: false, passesOnBase: false, digest, rejected: null, stopped: true };
+    if (atHead.timedOut)
+        return reject(false, false, `it was still running at head after ${seconds} seconds`);
+    if (atHead.exitCode === null)
+        return reject(false, false, "it could not be started at head");
+    if (atHead.exitCode === 0)
+        return reject(false, false, "it passes with the change (exit 0), so it does not show a break");
+    const tree = await addScratchWorktree(input.root, input.base, "judge-base", input.scratch);
+    if (!tree.ok)
+        return reject(true, false, `the base commit could not be checked out: ${tree.reason}`);
+    try {
+        await shareDependencies(input.root, tree.worktree.path);
+        carryFiles(input.headTree, tree.worktree.path, carried);
+        const baseCwd = insideDirectory(tree.worktree.path, input.cwd);
+        if (baseCwd === undefined || !existsSync(baseCwd))
+            return reject(true, false, `its cwd ${input.cwd} does not exist without the change`);
+        const atBase = await runShell(input.command, baseCwd, {
+            env: input.env,
+            timeoutMs,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        if (atBase.aborted)
+            return { failsOnHead: true, passesOnBase: false, digest, rejected: null, stopped: true };
+        if (atBase.timedOut)
+            return reject(true, false, `it was still running at base after ${seconds} seconds`);
+        if (atBase.exitCode !== 0)
+            return reject(true, false, `it also fails without the change (exit ${atBase.exitCode ?? "none"}), so the failure is not this change's`);
+        return { failsOnHead: true, passesOnBase: true, digest, rejected: null, stopped: false };
+    }
+    finally {
+        await tree.worktree.remove();
+    }
+}
+/**
+ * How this repository runs one test file, when it can be told from the files
+ * alone. A runner that cannot be told is `none`, and the judge is left to find
+ * its own way.
+ */
+export function linkedTestCommand(tree, file) {
+    const quoted = `'${file.replace(/'/g, `'\\''`)}'`;
+    if (file.endsWith(".py"))
+        return `python3 -m pytest -q ${quoted}`;
+    if (file.endsWith(".go"))
+        return `go test ./${dirname(file)}`;
+    if (!/\.(m?[jt]sx?|cjs|cts)$/.test(file))
+        return undefined;
+    for (const [tool, run] of [
+        ["vitest", "run"],
+        ["jest", ""],
+        ["mocha", ""],
+    ]) {
+        if (existsSync(join(tree, "node_modules", ".bin", tool)))
+            return `node_modules/.bin/${tool}${run ? ` ${run}` : ""} ${quoted}`;
+    }
+    try {
+        if (/from\s+["']node:test["']|require\(["']node:test["']\)/.test(readFileSync(join(tree, file), "utf8")))
+            return `node --test ${quoted}`;
+    }
+    catch {
+        /* Unreadable: no command. */
+    }
+    return undefined;
+}
+/** The judge's final JSON, read strictly enough that a malformed answer is not a verdict. */
+export function readJudgeAnswer(json) {
+    if (json === undefined)
+        return undefined;
+    const verdict = json.verdict;
+    if (verdict !== "kept" && verdict !== "broken" && verdict !== "could_not_tell")
+        return undefined;
+    const raw = json.reproduction;
+    const reproduction = raw !== null &&
+        typeof raw === "object" &&
+        typeof raw.command === "string" &&
+        raw.command.trim() !== ""
+        ? {
+            command: raw.command.trim().slice(0, 2000),
+            cwd: typeof raw.cwd === "string" && raw.cwd.trim() ? raw.cwd.trim() : ".",
+        }
+        : undefined;
+    const exercisedCases = Array.isArray(json.exercisedCases)
+        ? [
+            ...new Set(json.exercisedCases.filter((id) => typeof id === "string" && CASE_ID.test(id))),
+        ]
+        : [];
+    return {
+        verdict,
+        ...(reproduction === undefined ? {} : { reproduction }),
+        exercisedCases,
+        notes: typeof json.notes === "string" ? json.notes.slice(0, 2000) : "",
+    };
+}
+/**
+ * One promise judged against one change, with its reproduction verified.
+ *
+ * Returns `stopped` when the caller's budget ran out first, which is not a
+ * verdict and is never logged as one: the push is either held or told the
+ * judge is still running, never let through as if it had been judged.
+ */
+export async function judgePromise(input) {
+    const timeoutMs = input.timeoutMs ?? JUDGE_CAP_MS;
+    const tree = await addScratchWorktree(input.root, input.head, `judge-${input.promise.promiseId}`, input.scratch);
+    if (!tree.ok)
+        return { status: "not_judged", reason: tree.reason };
+    const headTree = tree.worktree;
+    try {
+        await shareDependencies(input.root, headTree.path);
+        let linkedTestRun = { file: "", outcome: "none" };
+        const linkedTestRuns = [];
+        const firstTest = input.map?.linkedTests[0];
+        if (firstTest !== undefined) {
+            const command = linkedTestCommand(headTree.path, firstTest.file);
+            if (command === undefined)
+                linkedTestRun = { file: firstTest.file, outcome: "none" };
+            else {
+                const run = await runShell(command, headTree.path, {
+                    env: input.env,
+                    timeoutMs: Math.min(LINKED_TEST_TIMEOUT_MS, timeoutMs),
+                    ...(input.signal === undefined ? {} : { signal: input.signal }),
+                });
+                if (run.aborted)
+                    return { status: "stopped" };
+                const outcome = run.timedOut || run.exitCode === null || run.exitCode === 127
+                    ? "error"
+                    : run.exitCode === 0
+                        ? "pass"
+                        : "fail";
+                linkedTestRun = { file: firstTest.file, outcome };
+                linkedTestRuns.push({
+                    file: firstTest.file,
+                    command,
+                    outcome,
+                    output: tail(run.output, 800),
+                });
+            }
+        }
+        const agent = await (input.runAgent ?? runHeadlessAgent)({
+            client: input.login.client,
+            login: input.login,
+            cwd: headTree.path,
+            prompt: judgePrompt({
+                promise: input.promise,
+                ...(input.map === undefined ? {} : { map: input.map }),
+                changedFiles: input.changedFiles,
+                base: input.base,
+                head: input.head,
+                linkedTestRuns,
+                minutes: Math.max(1, Math.floor(timeoutMs / 60_000)),
+            }),
+            allowedTools: AGENT_TOOLS,
+            disallowedTools: REFUSED_TOOL_RULES,
+            sandbox: "workspace-write",
+            timeoutMs,
+            env: input.env,
+            jsonOutput: true,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(input.scratch === undefined ? {} : { scratch: input.scratch }),
+        });
+        if (agent.aborted)
+            return { status: "stopped" };
+        if (agent.reason === "no_verified_login")
+            return { status: "not_judged", reason: agentFailure(agent) };
+        const judge = {
+            client: input.login.client,
+            model: agent.model ?? "",
+            durationMs: agent.durationMs,
+            inputTokens: agent.inputTokens ?? 0,
+            outputTokens: agent.outputTokens ?? 0,
+        };
+        const verdict = (fields) => ({
+            schemaVersion: JUDGE_VERDICT_SCHEMA_VERSION,
+            promiseId: input.promise.promiseId,
+            semanticDigest: input.promise.semanticDigest,
+            base: input.base,
+            head: input.head,
+            verdict: "could_not_tell",
+            reproduction: null,
+            reproductionRejected: null,
+            exercisedCases: [],
+            notes: "",
+            judge,
+            briefRevision: JUDGE_BRIEF_REVISION,
+            mapUsed: input.map !== undefined,
+            linkedTestRun,
+            ...fields,
+        });
+        const answer = agent.ok ? readJudgeAnswer(agent.json) : undefined;
+        if (answer === undefined)
+            return {
+                status: "judged",
+                verdict: verdict({
+                    notes: agent.ok ? "the judge's answer was not a verdict" : agentFailure(agent),
+                }),
+            };
+        if (answer.verdict === "kept") {
+            const missing = caseIds(input.promise).passing.filter((id) => !answer.exercisedCases.includes(id));
+            if (missing.length > 0)
+                return {
+                    status: "judged",
+                    verdict: verdict({
+                        exercisedCases: answer.exercisedCases,
+                        notes: `The judge answered kept without exercising ${missing.join(", ")}. ${answer.notes}`.trim(),
+                    }),
+                };
+            return {
+                status: "judged",
+                verdict: verdict({
+                    verdict: "kept",
+                    exercisedCases: answer.exercisedCases,
+                    notes: answer.notes,
+                }),
+            };
+        }
+        if (answer.verdict === "could_not_tell" || answer.reproduction === undefined)
+            return {
+                status: "judged",
+                verdict: verdict({
+                    exercisedCases: answer.exercisedCases,
+                    notes: answer.verdict === "broken"
+                        ? `The judge answered broken without a command that shows it. ${answer.notes}`.trim()
+                        : answer.notes,
+                }),
+            };
+        const check = await verifyReproduction({
+            root: input.root,
+            headTree: headTree.path,
+            head: input.head,
+            base: input.base,
+            command: answer.reproduction.command,
+            cwd: answer.reproduction.cwd,
+            env: input.env,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(input.scratch === undefined ? {} : { scratch: input.scratch }),
+        });
+        if (check.stopped)
+            return { status: "stopped" };
+        const reproduction = {
+            command: answer.reproduction.command,
+            cwd: answer.reproduction.cwd,
+            failsOnHead: check.failsOnHead,
+            passesOnBase: check.passesOnBase,
+            digest: check.digest,
+        };
+        return {
+            status: "judged",
+            verdict: verdict({
+                verdict: check.rejected === null ? "broken" : "could_not_tell",
+                reproduction,
+                reproductionRejected: check.rejected,
+                exercisedCases: answer.exercisedCases,
+                notes: answer.notes,
+            }),
+        };
+    }
+    finally {
+        await headTree.remove();
+    }
+}
+export const JUDGE_USAGE = `  ${CLI_INVOCATION} judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]
+                  [--report-only | --block] [--wait] [--json] [--client auto|claude|codex]
+                  [--from-file <promise.json> [--map <map.json>]]
+                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]
+      Judge whether this change keeps the promises it could break, one promise
+      at a time, on your own Claude Code or Codex login. A break counts only
+      with a command that fails with the change and passes without it, and
+      this command runs it both ways itself; anything unproven is "could not
+      tell". Report mode prints one line per promise and never stops anything;
+      --block exits 2 on a reproduced break, and when judges are still running
+      at the time limit it holds the push rather than letting it through.
+      --wait runs without the time limit. Promises come from --promises, else
+      the top of \`balladeer risk\`, else every mapped promise, plus
+      .continuity/judge.json's alwaysJudge and a small random sample. Verdicts
+      are kept in .continuity/judge-log/, which git ignores. --install-hook
+      adds the push hook to .claude/settings.json and .codex/hooks.json, or
+      .git/hooks/pre-push with git. With "offers": true in that file, the push
+      hook also reads the change for rules no promise records and offers at
+      most three to whoever is pushing; it records nothing and never holds a
+      push (see \`balladeer offers\`).
+`;
+export function parseJudgeArguments(argv) {
+    const args = [...argv];
+    let promises;
+    let topK;
+    let base;
+    let head;
+    let json = false;
+    let mode;
+    let wait = false;
+    let hook;
+    let installHook;
+    let fromFile;
+    let map;
+    let repo;
+    let client;
+    let repository;
+    let controlPlane;
+    const value = (flag, inline) => {
+        const next = inline ?? args.shift();
+        if (next === undefined || next === "")
+            throw new StoreError("usage", `${flag} needs a value.`);
+        return next;
+    };
+    const host = (flag, requested) => {
+        if (requested !== "claude" && requested !== "codex" && requested !== "git")
+            throw new StoreError("usage", `${flag} needs claude, codex or git.`);
+        return requested;
+    };
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (!arg.startsWith("--"))
+            throw new StoreError("usage", `judge takes no bare arguments: ${arg}.`);
+        const [name, ...rest] = arg.split("=");
+        const inline = rest.length > 0 ? rest.join("=") : undefined;
+        if (name === "--promises") {
+            promises = value(name, inline)
+                .split(",")
+                .map((id) => id.trim())
+                .filter(Boolean);
+            const bad = promises.find((id) => !PROMISE_ID.test(id));
+            if (bad !== undefined)
+                throw new StoreError("usage", `"${bad}" is not a promise id.`);
+        }
+        else if (name === "--top") {
+            const k = Number(value(name, inline));
+            if (!Number.isInteger(k) || k < 0 || k > 100)
+                throw new StoreError("usage", "--top needs a whole number from 0 to 100.");
+            topK = k;
+        }
+        else if (name === "--base")
+            base = value(name, inline);
+        else if (name === "--head")
+            head = value(name, inline);
+        else if (name === "--json")
+            json = true;
+        else if (name === "--report-only")
+            mode = "report";
+        else if (name === "--block")
+            mode = "block";
+        else if (name === "--wait")
+            wait = true;
+        else if (name === "--hook")
+            hook = host(name, value(name, inline));
+        else if (name === "--install-hook") {
+            const next = inline ?? (["claude", "codex", "git"].includes(args[0] ?? "") ? args.shift() : undefined);
+            installHook = next === undefined ? "agents" : host(name, next);
+        }
+        else if (name === "--from-file")
+            fromFile = value(name, inline);
+        else if (name === "--map")
+            map = value(name, inline);
+        else if (name === "--repo")
+            repo = value(name, inline);
+        else if (name === "--repository")
+            repository = value(name, inline);
+        else if (name === "--control-plane")
+            controlPlane = value(name, inline);
+        else if (name === "--client") {
+            const requested = value(name, inline);
+            if (requested !== "auto" && requested !== "claude" && requested !== "codex")
+                throw new StoreError("usage", "--client needs auto, claude or codex.");
+            client = requested;
+        }
+        else
+            throw new StoreError("usage", `Unknown option ${arg} for judge.`);
+    }
+    if (map !== undefined && fromFile === undefined)
+        throw new StoreError("usage", "--map goes with --from-file; a mapped promise's own map is read by itself.");
+    if (fromFile !== undefined && promises !== undefined)
+        throw new StoreError("usage", "--from-file judges the promise in that file; leave out --promises.");
+    const chosen = controlPlane ?? process.env.BALLADEER_CONTROL_PLANE?.trim() ?? DEFAULT_CONTROL_PLANE;
+    return {
+        ...(promises === undefined ? {} : { promises }),
+        ...(topK === undefined ? {} : { topK }),
+        ...(base === undefined ? {} : { base }),
+        ...(head === undefined ? {} : { head }),
+        json,
+        ...(mode === undefined ? {} : { mode }),
+        wait,
+        ...(hook === undefined ? {} : { hook }),
+        ...(installHook === undefined ? {} : { installHook }),
+        ...(fromFile === undefined ? {} : { fromFile }),
+        ...(map === undefined ? {} : { map }),
+        ...(repo === undefined ? {} : { repo }),
+        ...(client === undefined ? {} : { client }),
+        ...(repository === undefined ? {} : { repository }),
+        controlPlane: normalizeControlPlane(chosen),
+    };
+}
+/** Read a risk report out of whatever `balladeer risk --json` printed. */
+export function readRiskOutput(stdout) {
+    const documents = [];
+    try {
+        documents.push(JSON.parse(stdout));
+    }
+    catch {
+        for (const line of stdout.split("\n")) {
+            try {
+                documents.push(JSON.parse(line));
+            }
+            catch {
+                /* Not a JSON line. */
+            }
+        }
+    }
+    for (const document of documents) {
+        const report = document?.schemaVersion === "balladeer-risk/v1"
+            ? document
+            : document?.report;
+        if (report?.schemaVersion !== "balladeer-risk/v1")
+            continue;
+        const rows = report.promises;
+        if (!Array.isArray(rows))
+            continue;
+        return rows.flatMap((row) => {
+            const entry = row;
+            return typeof entry.promiseId === "string" && typeof entry.score === "number"
+                ? [{ promiseId: entry.promiseId, score: entry.score, band: String(entry.band ?? "") }]
+                : [];
+        });
+    }
+    return undefined;
+}
+/** `balladeer risk --json`, run as a child of this same command, when this build has it. */
+async function riskFromCommand(root, base, env) {
+    const entry = process.argv[1];
+    if (entry === undefined || !/(^|[/\\])(cli\.(m?js|ts)|balladeer)$/.test(entry))
+        return undefined;
+    const run = await runOwnedProcess({
+        command: process.execPath,
+        args: [...process.execArgv, entry, "risk", "--json", "--base", base],
+        cwd: root,
+        env: { ...env, [JUDGE_ACTIVE_VARIABLE]: "1" },
+        timeoutMs: 60_000,
+        maxOutputBytes: 4 * 1024 * 1024,
+    });
+    return run.exitCode === 0 ? readRiskOutput(run.stdout) : undefined;
+}
+/**
+ * The commit a change is measured from: the fork point with the remote default
+ * branch, else with this branch's upstream, else the parent of head.
+ */
+export async function defaultBase(root, head) {
+    const branches = [];
+    const remoteHead = await runCommand("git", [
+        "-C",
+        root,
+        "rev-parse",
+        "--abbrev-ref",
+        "origin/HEAD",
+    ]);
+    if (remoteHead.ok && remoteHead.stdout.trim() && remoteHead.stdout.trim() !== "origin/HEAD")
+        branches.push(remoteHead.stdout.trim());
+    branches.push("origin/main", "origin/master", "@{upstream}");
+    for (const branch of branches) {
+        const ref = await resolveCommit(root, branch);
+        if (ref === undefined)
+            continue;
+        const forkPoint = await runCommand("git", ["-C", root, "merge-base", head, ref]);
+        const sha = forkPoint.stdout.trim();
+        if (forkPoint.ok && /^[0-9a-f]{40}$/.test(sha) && sha !== head)
+            return sha;
+    }
+    return resolveCommit(root, `${head}^`);
+}
+export async function changedFiles(root, base, head) {
+    const diff = await runCommand("git", ["-C", root, "diff", "--name-only", base, head], {
+        timeoutMs: 60_000,
+    });
+    return diff.ok ? diff.stdout.split("\n").filter((line) => line.trim() !== "") : [];
+}
+/**
+ * Which promises to judge: named ones, else the top of the risk report plus a
+ * random sample below its line, else every mapped promise; then `alwaysJudge`.
+ * The sample is what keeps the ranking honest: a break found below the line is
+ * a miss the ranking made, counted rather than never seen.
+ */
+export function selectPromises(input) {
+    const out = [];
+    const seen = new Set();
+    const add = (promiseId, why) => {
+        if (seen.has(promiseId))
+            return;
+        seen.add(promiseId);
+        out.push({ promiseId, why });
+    };
+    if (input.named !== undefined)
+        for (const id of input.named)
+            add(id, "named");
+    else if (input.risk !== undefined) {
+        const k = input.topK ?? input.config.topK;
+        const ranked = input.risk
+            .filter((entry) => entry.band !== "unmapped" && entry.score > 0)
+            .sort((a, b) => b.score - a.score || a.promiseId.localeCompare(b.promiseId));
+        const top = ranked.slice(0, k);
+        for (const entry of top)
+            add(entry.promiseId, "risk");
+        const below = input.risk.filter((entry) => entry.band !== "unmapped" && !top.some((row) => row.promiseId === entry.promiseId));
+        for (const entry of below)
+            if (input.random() < input.config.sampleBelowLine)
+                add(entry.promiseId, "sample");
+    }
+    else
+        for (const id of input.mapped)
+            add(id, "mapped");
+    for (const id of input.config.alwaysJudge)
+        add(id, "always");
+    return out;
+}
+function logPath(root, now) {
+    // One file per UTC day. A file name, not a sentence: nobody reads it as a time.
+    const day = now.toISOString().slice(0, 10);
+    return join(root, JUDGE_LOG_DIRECTORY, `${day}.jsonl`);
+}
+/**
+ * Append verdicts to today's log. The directory carries its own `.gitignore`,
+ * so a verdict log never lands in a commit whatever the repository ignores.
+ */
+export function appendVerdicts(root, verdicts, now) {
+    if (verdicts.length === 0)
+        return;
+    const directory = join(root, JUDGE_LOG_DIRECTORY);
+    mkdirSync(directory, { recursive: true });
+    const ignore = join(directory, ".gitignore");
+    if (!existsSync(ignore))
+        writeFileSync(ignore, "*\n", "utf8");
+    appendFileSync(logPath(root, now), verdicts.map((verdict) => `${JSON.stringify(verdict)}\n`).join(""), "utf8");
+}
+/** A verdict already reached for exactly this promise, meaning, change and brief. */
+export function findLoggedVerdict(root, key, now) {
+    const days = [now, new Date(now.getTime() - 86_400_000)];
+    for (const day of days) {
+        const path = logPath(root, day);
+        if (!existsSync(path))
+            continue;
+        const lines = readFileSync(path, "utf8").split("\n").reverse();
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const verdict = JSON.parse(line);
+                if (verdict.schemaVersion === JUDGE_VERDICT_SCHEMA_VERSION &&
+                    verdict.promiseId === key.promiseId &&
+                    verdict.semanticDigest === key.semanticDigest &&
+                    verdict.base === key.base &&
+                    verdict.head === key.head &&
+                    verdict.briefRevision === JUDGE_BRIEF_REVISION)
+                    return verdict;
+            }
+            catch {
+                /* A torn line is skipped. */
+            }
+        }
+    }
+    return undefined;
+}
+function sentence(text, limit = 240) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= limit ? flat : `${flat.slice(0, limit - 3)}...`;
+}
+/** One line per verdict, the promise named by its title and id. */
+export function verdictLine(verdict, title, reused = false) {
+    const name = `${title} (${verdict.promiseId})`;
+    const earlier = reused ? " [judged earlier for this commit]" : "";
+    if (verdict.verdict === "kept")
+        return `kept: ${name}${earlier}`;
+    if (verdict.verdict === "broken") {
+        const where = verdict.reproduction && verdict.reproduction.cwd !== "."
+            ? ` (in ${verdict.reproduction.cwd})`
+            : "";
+        return `broken: ${name}${earlier}. Reproduce with: ${verdict.reproduction?.command ?? ""}${where}`;
+    }
+    const rejected = verdict.reproductionRejected
+        ? ` A reported break did not hold up when run both ways: ${verdict.reproductionRejected}.`
+        : "";
+    const notes = verdict.notes ? ` ${sentence(verdict.notes)}` : "";
+    return `could not tell: ${name}${earlier}.${notes}${rejected}`;
+}
+async function readStdin(limit = 1024 * 1024, idleMs = 5000) {
+    if (process.stdin.isTTY)
+        return "";
+    return new Promise((resolveText) => {
+        const chunks = [];
+        let size = 0;
+        let timer = setTimeout(done, idleMs);
+        function done() {
+            clearTimeout(timer);
+            process.stdin.removeAllListeners("data");
+            process.stdin.removeAllListeners("end");
+            process.stdin.pause();
+            resolveText(Buffer.concat(chunks).toString("utf8"));
+        }
+        process.stdin.on("data", (chunk) => {
+            size += chunk.length;
+            if (size <= limit)
+                chunks.push(chunk);
+            clearTimeout(timer);
+            timer = setTimeout(done, idleMs);
+        });
+        process.stdin.on("end", done);
+        process.stdin.resume();
+    });
+}
+function describeInstall(result) {
+    if (result.status === "written")
+        return `Written: ${result.path}.`;
+    if (result.status === "unchanged")
+        return `Already current: ${result.path}. Nothing was changed.`;
+    return `Not changed: ${result.path}. ${result.reason ?? ""}`.trim();
+}
+/** `balladeer judge`, from arguments already parsed. */
+export async function runJudge(options) {
+    const { args } = options;
+    const deps = options.deps ?? {};
+    const now = deps.now ?? (() => new Date());
+    const hook = args.hook;
+    const json = args.json && hook === undefined;
+    const lines = [];
+    const emit = (step) => {
+        if (json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    // Started once the change is known, when the team turned offers on: the
+    // rules this change establishes that no promise records. It spends from the
+    // hook's own budget and is awaited only at the moment of answering, so it
+    // never delays a judge; whatever it does, it never changes the answer's
+    // exit, and a reading still running at the deadline is stopped and says
+    // nothing.
+    let offerReading;
+    let offerDeadline = 0;
+    const offerStop = new AbortController();
+    const settleOffers = async () => {
+        if (offerReading === undefined)
+            return [];
+        let timer;
+        const late = new Promise((done) => {
+            timer = setTimeout(() => {
+                offerStop.abort();
+                done([]);
+            }, Math.max(0, offerDeadline - Date.now()));
+        });
+        try {
+            return await Promise.race([offerReading.catch(() => []), late]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    };
+    const respond = async (block) => {
+        const offered = await settleOffers();
+        // Apart from the verdicts, after them, with a line between.
+        if (offered.length > 0)
+            lines.push(...(lines.length > 0 ? [""] : []), ...offered);
+        const response = hookResponse(hook ?? "git", { block, lines });
+        if (!json) {
+            if (response.stdout)
+                options.write(response.stdout);
+            if (response.stderr && (hook !== undefined || block))
+                options.error(response.stderr);
+        }
+        return response.exitCode;
+    };
+    // A judge's own shell commands run with this set, and a push hook inside a
+    // judge would otherwise start judging all over again.
+    if (hook !== undefined && options.environment[JUDGE_ACTIVE_VARIABLE] === "1")
+        return 0;
+    let cwd = options.cwd;
+    let pushedHead;
+    if (hook !== undefined) {
+        const input = await (deps.stdin ?? (() => readStdin()))();
+        if (hook === "git") {
+            const refs = parsePrePushInput(input);
+            if (refs.length === 0)
+                return 0;
+            pushedHead = refs[0].localSha;
+        }
+        else {
+            const parsed = parseHookInput(input);
+            if (parsed?.command === undefined || !isPushCommand(parsed.command))
+                return 0;
+            if (parsed.cwd !== undefined && existsSync(parsed.cwd))
+                cwd = parsed.cwd;
+        }
+    }
+    const root = args.repo !== undefined ? resolve(options.cwd, args.repo) : await repositoryRoot(cwd);
+    if (root === undefined || !existsSync(root)) {
+        if (hook !== undefined)
+            return 0;
+        const message = "This is not a git repository, so there is no change to judge.";
+        emit({ step: "error", reason: "not_a_repository", message, changed: false, exitCode: 4 });
+        if (!json)
+            options.error(`${message}\n`);
+        return 4;
+    }
+    if (args.installHook !== undefined) {
+        const targets = args.installHook === "agents" ? ["claude", "codex"] : [args.installHook];
+        let refused = false;
+        for (const target of targets) {
+            const result = installJudgeHook(root, target);
+            refused ||= result.status === "refused";
+            emit({ step: "hook", path: result.path, changed: result.status === "written" });
+            if (!json)
+                options.write(`${describeInstall(result)}\n`);
+        }
+        if (!json) {
+            options.write('It runs `balladeer judge` before a push or a pull request and says nothing for any other command. Report mode is the default; set "mode": "block" in .continuity/judge.json to stop a push on a reproduced break.\n');
+            if (targets.includes("codex"))
+                options.write("Codex runs a project hook once you trust it: open /hooks in Codex and review it.\n");
+        }
+        return refused ? 4 : 0;
+    }
+    const { config, problems } = readJudgeConfig(root);
+    const mode = args.mode ?? config.mode;
+    for (const problem of problems)
+        lines.push(`Balladeer judge: ${problem}.`);
+    await runCommand("git", ["-C", root, "worktree", "prune"]);
+    const head = await resolveCommit(root, args.head ?? pushedHead ?? "HEAD");
+    if (head === undefined) {
+        const message = `${args.head ?? "HEAD"} is not a commit here, so there is nothing to judge.`;
+        if (hook !== undefined)
+            return 0;
+        emit({ step: "error", reason: "no_head", message, changed: false, exitCode: 4 });
+        if (!json)
+            options.error(`${message}\n`);
+        return 4;
+    }
+    const base = args.base !== undefined ? await resolveCommit(root, args.base) : await defaultBase(root, head);
+    if (base === undefined || base === head) {
+        const message = base === undefined
+            ? `${args.base ?? "the base"} is not a commit here, so nothing was judged.`
+            : "Nothing to judge: the change is empty.";
+        emit({
+            step: "judge",
+            status: "nothing_to_judge",
+            reason: base === undefined ? "no_base" : "empty_change",
+            message,
+            exitCode: 0,
+        });
+        if (hook === undefined)
+            lines.push(message);
+        return respond(false);
+    }
+    const files = await changedFiles(root, base, head);
+    // Which promises, before spending anything on a login check.
+    let filePromise;
+    let fileMap;
+    if (args.fromFile !== undefined) {
+        const read = readPromiseFile(resolve(options.cwd, args.fromFile));
+        if (!read.ok) {
+            emit({
+                step: "error",
+                reason: "promise_unreadable",
+                message: read.reason,
+                changed: false,
+                exitCode: 4,
+            });
+            if (!json)
+                options.error(`${read.reason}\n`);
+            return 4;
+        }
+        filePromise = read.promise;
+        if (args.map !== undefined) {
+            try {
+                const parsed = parseBehaviorMap(JSON.parse(readFileSync(resolve(options.cwd, args.map), "utf8")));
+                if (!parsed.ok)
+                    throw new Error(parsed.errors.slice(0, 3).join("; "));
+                fileMap = parsed.value;
+            }
+            catch (error) {
+                const message = `${args.map} is not a usable behavior map: ${error instanceof Error ? error.message : String(error)}`;
+                emit({ step: "error", reason: "map_unreadable", message, changed: false, exitCode: 4 });
+                if (!json)
+                    options.error(`${message}\n`);
+                return 4;
+            }
+        }
+    }
+    if (config.offers && hook !== undefined) {
+        // Even when no promise is at risk and no map exists: a change nobody
+        // mapped is exactly where a rule nobody wrote down is likeliest.
+        offerDeadline = Date.now() + effectiveBudgetSeconds(config.budgetSeconds, true) * 1000;
+        offerReading = offersForPush({
+            root,
+            base,
+            head,
+            files,
+            host: hook,
+            environment: options.environment,
+            controlPlane: args.controlPlane,
+            client: args.client ?? config.client,
+            deadline: offerDeadline,
+            signal: offerStop.signal,
+            policy: config.offersOn,
+            max: config.maxOffers,
+            ...(deps.reader === undefined ? {} : { reader: deps.reader }),
+            ...(deps.offerAgent === undefined ? {} : { runAgent: deps.offerAgent }),
+        });
+    }
+    const mappedIds = readBehaviorMaps(join(root, ".continuity/behavior-maps"))
+        .filter((entry) => entry.map !== undefined)
+        .map((entry) => entry.promiseId);
+    const named = filePromise !== undefined ? [filePromise.promiseId] : args.promises;
+    const risk = named === undefined
+        ? await (deps.riskReport ?? ((r, b) => riskFromCommand(r, b, options.environment)))(root, base, head)
+        : undefined;
+    const selected = selectPromises({
+        ...(named === undefined ? {} : { named }),
+        ...(risk === undefined ? {} : { risk }),
+        mapped: mappedIds,
+        // A promise handed over in a file is judged alone: the repository's own
+        // standing list belongs to its own promises, not to the one in the file.
+        config: filePromise === undefined ? config : { ...config, alwaysJudge: [] },
+        ...(args.topK === undefined ? {} : { topK: args.topK }),
+        random: deps.random ?? Math.random,
+    });
+    if (selected.length === 0) {
+        const message = "No promise here has a behavior map yet, so nothing was judged. Build them with `balladeer map --all`.";
+        emit({ step: "judge", status: "nothing_to_judge", reason: "no_maps", message, exitCode: 0 });
+        lines.push(message);
+        return respond(false);
+    }
+    const prefer = hook === "claude" || hook === "codex" ? hook : undefined;
+    const requested = args.client ?? config.client;
+    const login = await (deps.resolveLogin ??
+        ((client, preferred) => resolveClient(client, {
+            env: options.environment,
+            cwd: root,
+            ...(preferred === undefined ? {} : { prefer: preferred }),
+        })))(requested, prefer);
+    if (login === undefined) {
+        const message = "not judged: no Claude Code signed in through claude.ai, and no Codex signed in with ChatGPT, is on this machine, so Balladeer did not judge this change.";
+        emit({ step: "judge", status: "not_judged", reason: "no_login", message, exitCode: 0 });
+        lines.push(message);
+        return respond(false);
+    }
+    // Meanings: the file, else this repository's connection, else the map's own excerpt.
+    let reader = deps.reader ?? undefined;
+    if (deps.reader === undefined && filePromise === undefined) {
+        const connection = connectionReader({
+            environment: options.environment,
+            controlPlane: args.controlPlane,
+            cwd: root,
+            ...(args.repository === undefined ? {} : { repository: args.repository }),
+        });
+        if (connection.ok)
+            reader = connection.reader;
+    }
+    const jobs = [];
+    const unreadable = [];
+    for (const { promiseId } of selected) {
+        const map = filePromise !== undefined ? fileMap : readBehaviorMap(root, promiseId);
+        let promise = filePromise;
+        if (promise === undefined && reader !== undefined) {
+            const read = await reader.get(promiseId);
+            if (read.ok)
+                promise = read.promise;
+        }
+        if (promise === undefined && map?.meaning !== undefined)
+            promise = promiseFromExcerpt(promiseId, map.semanticDigest, map.meaning);
+        if (promise === undefined)
+            unreadable.push(promiseId);
+        else
+            jobs.push({ promise, ...(map === undefined ? {} : { map }) });
+    }
+    const stopHandler = () => {
+        removeLiveWorktreesNow();
+        process.exit(130);
+    };
+    process.once("SIGINT", stopHandler);
+    process.once("SIGTERM", stopHandler);
+    const budget = new AbortController();
+    // From a hook, the host's own timeout rules and a timed-out hook lets the
+    // push run, so the budget is capped below it; by hand, the person's number.
+    const budgetMs = args.wait
+        ? undefined
+        : effectiveBudgetSeconds(config.budgetSeconds, args.hook !== undefined) * 1000;
+    const timer = budgetMs === undefined ? undefined : setTimeout(() => budget.abort(), budgetMs);
+    const started = Date.now();
+    const verdicts = [];
+    const stillJudging = [];
+    const notJudged = [];
+    try {
+        const queue = [...jobs];
+        const worker = async () => {
+            for (;;) {
+                const job = queue.shift();
+                if (job === undefined)
+                    return;
+                const logged = findLoggedVerdict(root, {
+                    promiseId: job.promise.promiseId,
+                    semanticDigest: job.promise.semanticDigest,
+                    base,
+                    head,
+                }, now());
+                if (logged !== undefined) {
+                    verdicts.push({ verdict: logged, title: job.promise.title, reused: true });
+                    continue;
+                }
+                if (budget.signal.aborted) {
+                    stillJudging.push(job);
+                    continue;
+                }
+                const remaining = budgetMs === undefined ? JUDGE_CAP_MS : Math.max(1000, budgetMs - (Date.now() - started));
+                const outcome = await (deps.judge ?? judgePromise)({
+                    root,
+                    promise: job.promise,
+                    ...(job.map === undefined ? {} : { map: job.map }),
+                    base,
+                    head,
+                    changedFiles: files,
+                    login,
+                    env: options.environment,
+                    timeoutMs: Math.min(JUDGE_CAP_MS, remaining),
+                    signal: budget.signal,
+                    ...(deps.scratch === undefined ? {} : { scratch: deps.scratch }),
+                    ...(deps.runAgent === undefined ? {} : { runAgent: deps.runAgent }),
+                });
+                if (outcome.status === "stopped")
+                    stillJudging.push(job);
+                else if (outcome.status === "not_judged")
+                    notJudged.push({ id: job.promise.promiseId, reason: outcome.reason });
+                else {
+                    verdicts.push({ verdict: outcome.verdict, title: job.promise.title, reused: false });
+                    appendVerdicts(root, [outcome.verdict], now());
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(config.concurrency, Math.max(1, jobs.length)) }, worker));
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        process.removeListener("SIGINT", stopHandler);
+        process.removeListener("SIGTERM", stopHandler);
+    }
+    const order = new Map(selected.map((entry, index) => [entry.promiseId, index]));
+    verdicts.sort((a, b) => (order.get(a.verdict.promiseId) ?? 0) - (order.get(b.verdict.promiseId) ?? 0));
+    const broken = verdicts.filter((entry) => entry.verdict.verdict === "broken");
+    if (json)
+        for (const { verdict } of verdicts)
+            options.write(`${JSON.stringify(verdict)}\n`);
+    lines.push(`Balladeer judged this change (${base.slice(0, 12)}..${head.slice(0, 12)}, ${files.length} files) against ${verdicts.length} of ${selected.length} promises it could affect, in ${mode} mode:`);
+    for (const { verdict, title, reused } of verdicts)
+        lines.push(`  ${verdictLine(verdict, title, reused)}`);
+    for (const { id, reason } of notJudged)
+        lines.push(`  not judged: ${id}: ${reason}`);
+    for (const id of unreadable)
+        lines.push(`  not judged: ${id}: its meaning could not be read here and it has no behavior map.`);
+    if (stillJudging.length > 0) {
+        const ids = stillJudging.map((job) => job.promise.promiseId);
+        const names = stillJudging
+            .map((job) => `${job.promise.title} (${job.promise.promiseId})`)
+            .join("; ");
+        const message = mode === "block"
+            ? `Held: ${STILL_JUDGING}, then push again. Still judging when the time ran out: ${names}.`
+            : `Still judging when the time ran out, so not judged yet: ${names}. Run \`balladeer judge --wait\` to finish them.`;
+        lines.push(message);
+        emit({
+            step: "judge",
+            status: "still_judging",
+            reason: "budget_spent",
+            message,
+            promiseIds: ids,
+            exitCode: mode === "block" ? 2 : 0,
+        });
+    }
+    if (broken.length > 0 && mode === "block")
+        lines.push("This push is stopped because a promise's break was reproduced both ways. Fix the behavior, or run the reproduction to see it, then push again.");
+    const block = mode === "block" && (broken.length > 0 || stillJudging.length > 0);
+    if (json)
+        return block ? 2 : 0;
+    return respond(block);
+}
+/** `balladeer judge ...` from raw arguments, as `cli.ts` hands them over. */
+export async function judgeCommand(argv, io) {
+    let args;
+    try {
+        args = parseJudgeArguments(argv);
+    }
+    catch (error) {
+        io.error(`${error instanceof Error ? error.message : String(error)}\n\n${JUDGE_USAGE}`);
+        return 4;
+    }
+    return runJudge({
+        args,
+        cwd: io.cwd,
+        environment: io.environment,
+        write: io.write,
+        error: io.error,
+    });
+}