balladeer 1.0.15 → 1.0.17

package/dist/commands/judge.js

@@ -0,0 +1,1713 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, 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 { baseBeforePush, checkoutRoot, commitBeforePush, effectiveBudgetSeconds, hasJudgeEntry, hasProjectJudgeHook, hookResponse, installJudgeHook, isPushCommand, mergeTargets, parseHookInput, parsePrePushInput, pushCheckOff, pushLanded, pushPlace, remoteRepositoryNames, repositoryName, sendsCommits, setPushCheck, } from "../judge-hook.js";
+import { noteHookFired } from "../hook-trust.js";
+import { sessionMemory } from "../judge-said.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 { directness, riskOrder } from "../risk/score.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";
+/**
+ * Where a verified reproduction's files are kept, one folder per promise and
+ * pushed commit, inside the judge log so git ignores them like the log itself.
+ */
+export const KEPT_REPRODUCTIONS_DIRECTORY = `${JUDGE_LOG_DIRECTORY}/reproductions`;
+export const KEPT_REPRODUCTION_SCHEMA_VERSION = "balladeer-kept-reproduction/v1";
+export const STILL_JUDGING = "still judging; rerun `balladeer judge --wait`";
+/** Block mode's answer to a line that commits and then pushes: the check runs before the line. */
+export const COMMIT_THEN_PUSH = "Held: this command makes a commit and then pushes it, and the check runs before the command, so it cannot see a commit that has not been made yet. Commit first, then push in a separate command.";
+/** 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",
+    select: "direct",
+    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),
+            select: pick("select", (v) => v === "direct" || v === "ranked", d.select),
+            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,
+        files: carried,
+    });
+    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,
+            files: carried,
+        };
+    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,
+                files: carried,
+            };
+        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,
+            files: carried,
+        };
+    }
+    finally {
+        await tree.worktree.remove();
+    }
+}
+/**
+ * Keep a verified reproduction on this machine, so the break can become a
+ * lasting test instead of vanishing with the judge's checkout.
+ *
+ * The files the judge added are copied from its checkout into
+ * `.continuity/judge-log/reproductions/<promise id>-<first 12 of head>/files/`
+ * at the paths the judge wrote them, beside a `manifest.json` that says which
+ * promise, meaning and change they reproduce a break of, with the command,
+ * its cwd, the digest and each file's own fingerprint. The digest can be
+ * recomputed from the manifest alone. A reproduction that added no files
+ * keeps just the manifest. The judge log carries its own `.gitignore`, so
+ * nothing here is ever committed, and nothing here is sent anywhere.
+ *
+ * The folder is written beside its final name and then renamed into place,
+ * replacing an earlier one for the same promise and commit, so a reader never
+ * sees half of one. Keeping is a courtesy to the person, never a condition of
+ * the verdict: when it fails, the verdict stands and says nothing was kept.
+ */
+export function keepReproduction(input) {
+    const keptIn = `${KEPT_REPRODUCTIONS_DIRECTORY}/${input.promiseId}-${input.head.slice(0, 12)}`;
+    const folder = insideDirectory(input.root, keptIn);
+    if (folder === undefined || !PROMISE_ID.test(input.promiseId))
+        return undefined;
+    const staging = `${folder}.partial-${process.pid}`;
+    try {
+        judgeLogDirectory(input.root);
+        rmSync(staging, { recursive: true, force: true });
+        mkdirSync(staging, { recursive: true });
+        const kept = carryFiles(input.headTree, join(staging, "files"), input.files);
+        const manifest = {
+            schemaVersion: KEPT_REPRODUCTION_SCHEMA_VERSION,
+            promiseId: input.promiseId,
+            semanticDigest: input.semanticDigest,
+            base: input.base,
+            head: input.head,
+            command: input.command,
+            cwd: input.cwd,
+            digest: input.digest,
+            files: kept.map((file) => ({ path: file.path, sha256: file.sha256 })),
+        };
+        writeFileSync(join(staging, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        rmSync(folder, { recursive: true, force: true });
+        renameSync(staging, folder);
+        return { keptIn, files: kept.map((file) => file.path) };
+    }
+    catch {
+        rmSync(staging, { recursive: true, force: true });
+        return undefined;
+    }
+}
+/**
+ * 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 longest `nextStep` kept from a judge's answer, in characters. */
+export const NEXT_STEP_LIMIT = 500;
+/** 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))),
+        ]
+        : [];
+    const nextStep = typeof json.nextStep === "string" ? json.nextStep.trim().slice(0, NEXT_STEP_LIMIT) : "";
+    return {
+        verdict,
+        ...(reproduction === undefined ? {} : { reproduction }),
+        exercisedCases,
+        notes: typeof json.notes === "string" ? json.notes.slice(0, 2000) : "",
+        ...(nextStep === "" ? {} : { nextStep }),
+    };
+}
+/**
+ * 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,
+                    // Only the judge's own could-not-tell carries a way forward.
+                    ...(answer.verdict === "could_not_tell" && answer.nextStep !== undefined
+                        ? { nextStep: answer.nextStep }
+                        : {}),
+                }),
+            };
+        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" };
+        // Only a break that held up both ways is worth keeping: it is the start
+        // of a lasting test, and a rejected one would be the start of a wrong one.
+        const kept = check.rejected === null && check.failsOnHead && check.passesOnBase
+            ? keepReproduction({
+                root: input.root,
+                headTree: headTree.path,
+                promiseId: input.promise.promiseId,
+                semanticDigest: input.promise.semanticDigest,
+                base: input.base,
+                head: input.head,
+                command: answer.reproduction.command,
+                cwd: answer.reproduction.cwd,
+                digest: check.digest,
+                files: check.files,
+            })
+            : undefined;
+        const reproduction = {
+            command: answer.reproduction.command,
+            cwd: answer.reproduction.cwd,
+            failsOnHead: check.failsOnHead,
+            passesOnBase: check.passesOnBase,
+            digest: check.digest,
+            ...(kept === undefined ? {} : { keptIn: kept.keptIn, keptFiles: kept.files }),
+        };
+        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]]
+                  [--push-check on|off]
+      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
+      from \`balladeer risk\`: every promise whose own code or tests the
+      change edits, or with "select": "ranked" in .continuity/judge.json the
+      top of its ranking and a small random sample; else every mapped
+      promise; plus that file's alwaysJudge. Verdicts are kept in
+      .continuity/judge-log/, which git ignores. --install-hook adds the push
+      hook to .claude/settings.json and .codex/hooks.json, before and after
+      each shell command: report mode judges after a push has landed, so the
+      push never waits, and block mode judges before it. With git it writes
+      .git/hooks/pre-push, which judges before the push in both modes. With
+      "offers": true in .continuity/judge.json, 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\`). Setup also writes the same pair of entries at
+      each host's user scope, running \`judge --hook <host> --user-scope\`,
+      so the check runs in every connected repository with mapped promises
+      and says nothing anywhere else; a checkout with its own entry keeps
+      the check to that entry. --push-check off turns the user-scope check
+      off on this laptop, and --push-check on turns it back on.
+`;
+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 userScope = false;
+    let pushCheck;
+    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 === "--user-scope")
+            userScope = true;
+        else if (name === "--push-check") {
+            const requested = value(name, inline);
+            if (requested !== "on" && requested !== "off")
+                throw new StoreError("usage", "--push-check needs on or off.");
+            pushCheck = requested;
+        }
+        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.");
+    if (userScope && hook !== "claude" && hook !== "codex")
+        throw new StoreError("usage", "--user-scope goes with --hook claude or --hook codex.");
+    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 }),
+        ...(userScope ? { userScope: true } : {}),
+        ...(pushCheck === undefined ? {} : { pushCheck }),
+        ...(installHook === undefined ? {} : { installHook }),
+        ...(fromFile === undefined ? {} : { fromFile }),
+        ...(map === undefined ? {} : { map }),
+        ...(repo === undefined ? {} : { repo }),
+        ...(client === undefined ? {} : { client }),
+        ...(repository === undefined ? {} : { repository }),
+        controlPlane: normalizeControlPlane(chosen),
+    };
+}
+const NO_FEATURES = {
+    symbol_hit: 0,
+    graph_forward_distance: null,
+    graph_reverse_distance: null,
+    resource_overlap: 0,
+    linked_test_changed: 0,
+    sink_reach: 0,
+    delta_similarity: 0,
+    intent_clash: 0,
+    prior_break: 0,
+    churn: 0,
+};
+function readFeatures(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const row = value;
+    const count = (key) => (typeof row[key] === "number" ? row[key] : 0);
+    const distance = (key) => (typeof row[key] === "number" ? row[key] : null);
+    return {
+        symbol_hit: count("symbol_hit"),
+        graph_forward_distance: distance("graph_forward_distance"),
+        graph_reverse_distance: distance("graph_reverse_distance"),
+        resource_overlap: count("resource_overlap"),
+        linked_test_changed: count("linked_test_changed"),
+        sink_reach: count("sink_reach"),
+        delta_similarity: count("delta_similarity"),
+        intent_clash: count("intent_clash"),
+        prior_break: count("prior_break"),
+        churn: count("churn"),
+    };
+}
+/** How directly the change reaches an entry's promise, by `balladeer risk`'s own rule. */
+function tierOf(entry) {
+    return directness(entry.features ?? NO_FEATURES);
+}
+/** The order `balladeer risk` lists promises in: directness, then score, then evidence, then id. */
+function byEntryRisk(a, b) {
+    const key = (entry) => ({
+        promiseId: entry.promiseId,
+        score: entry.score,
+        features: entry.features ?? NO_FEATURES,
+        evidence: entry.evidence ?? 0,
+    });
+    return riskOrder(key(a), key(b));
+}
+/** 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;
+            if (typeof entry.promiseId !== "string" || typeof entry.score !== "number")
+                return [];
+            const features = readFeatures(entry.features);
+            const reasons = Array.isArray(entry.reasons) ? entry.reasons : [];
+            const evidence = reasons.reduce((sum, reason) => {
+                const weight = reason?.weight;
+                return sum + (typeof weight === "number" && Number.isFinite(weight) ? weight : 0);
+            }, 0);
+            return [
+                {
+                    promiseId: entry.promiseId,
+                    score: entry.score,
+                    band: String(entry.band ?? ""),
+                    ...(features === undefined ? {} : { features }),
+                    evidence,
+                },
+            ];
+        });
+    }
+    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 from the risk report, else every
+ * mapped promise; then `alwaysJudge`.
+ *
+ * From the risk report, in the order `balladeer risk` lists it (how directly
+ * the change reaches each promise, then score, then evidence, then id; a score
+ * alone ties at 1 and falls to the alphabet):
+ *
+ * - "direct" takes every promise whose own code or tests the change edits
+ *   (directness tier 3), and nothing else. The first live evaluation found
+ *   that this selects about 1.8 promises a change and included the broken one
+ *   in 17 of 17 cases. Only a `--top` given by hand caps it.
+ * - "ranked" takes the top k with a score above zero, plus a random sample
+ *   below that line. The sample is what keeps a 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 ordered = input.risk.filter((entry) => entry.band !== "unmapped").sort(byEntryRisk);
+        if (input.config.select === "direct") {
+            const direct = ordered.filter((entry) => tierOf(entry) === 3);
+            const capped = input.topK === undefined ? direct : direct.slice(0, input.topK);
+            for (const entry of capped)
+                add(entry.promiseId, "risk");
+        }
+        else {
+            const k = input.topK ?? input.config.topK;
+            const top = ordered.filter((entry) => entry.score > 0).slice(0, k);
+            for (const entry of top)
+                add(entry.promiseId, "risk");
+            const below = ordered.filter((entry) => !top.includes(entry));
+            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`);
+}
+/**
+ * The judge log directory, made with its own `.gitignore` of `*` when it is
+ * new, so neither a verdict nor a kept reproduction ever lands in a commit,
+ * whatever the repository's own `.gitignore` says.
+ */
+function judgeLogDirectory(root) {
+    const directory = join(root, JUDGE_LOG_DIRECTORY);
+    mkdirSync(directory, { recursive: true });
+    const ignore = join(directory, ".gitignore");
+    if (!existsSync(ignore))
+        writeFileSync(ignore, "*\n", "utf8");
+    return directory;
+}
+/**
+ * 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;
+    judgeLogDirectory(root);
+    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)}...`;
+}
+/** Said after "fix the behavior": a deliberate change is the person's, and the promise its owner's. */
+export const DELIBERATE_CHANGE = "If the person changed this behavior on purpose, do not undo their change: tell them it breaks this promise, whose meaning only its owner can change.";
+/**
+ * What to do after a reproduced break, as one line an agent reads in order:
+ * where the test that shows it is kept, fix the behavior rather than the
+ * test, then make the break a lasting check in this repository's own tests,
+ * committed with the fix and linked to the promise's map, and tell the person
+ * in one line what was added. When the promise's own Balladeer check missed
+ * the break, a repair of that check is proposed to its owner as well.
+ */
+export function afterBreakLine(verdict, checkBound) {
+    const id = verdict.promiseId;
+    // A break the person made on purpose is not the agent's to undo. Seen in a
+    // native run on 30 September 2026: the agent rightly asked instead of
+    // reverting a person's own edit, but the line should not rely on that.
+    const onPurpose = ` ${DELIBERATE_CHANGE}`;
+    const keptIn = verdict.reproduction?.keptIn;
+    const files = verdict.reproduction?.keptFiles ?? [];
+    const comment = `with ${id} in a comment at its top`;
+    let start;
+    if (keptIn !== undefined && files.length > 0) {
+        // The command names the files where the judge wrote them, which is not
+        // where they are kept, so the line says both.
+        const where = files.length === 1
+            ? `the test that shows it is kept at ${keptIn}/files/${files[0]} (the command runs it from ${files[0]})`
+            : `the files that show it are kept in ${keptIn}/files/ (${files.slice(0, 3).join(", ")}${files.length > 3 ? ` and ${files.length - 3} more` : ""}; the command runs them from those paths)`;
+        start =
+            `${where}. Fix the behavior, not the test.${onPurpose} Then make this break a lasting check: ` +
+                `move that test into this repository's own tests beside the code it covers, following their conventions, ${comment};`;
+    }
+    else {
+        start =
+            `${keptIn !== undefined ? "the command alone shows it, so no test file was kept. " : ""}` +
+                `Fix the behavior, not the test.${onPurpose} Then make this break a lasting check: ` +
+                `turn the command into a test in this repository's own test framework (unless it already runs one), beside the code it covers, ${comment};`;
+    }
+    const rest = ` run it and see it pass on the fix; commit it with the fix; and link it to the promise with \`balladeer map --link-test ${id} <its path>\`.`;
+    const repair = checkBound === true
+        ? " Its Balladeer check missed this break, so also propose adding this case to that check with the propose_verifier_repair tool, which goes to the promise's owner for review."
+        : "";
+    const relay = " Then tell the person in one line, in your own words rather than pasting this, what you added.";
+    return `Next: ${start}${rest}${repair}${relay}`;
+}
+/**
+ * The verdict as it may be told now: a reproduction said to be kept whose
+ * folder is no longer on this machine (a verdict read back from the log after
+ * somebody cleared it) loses its kept fields, so the line never points at a
+ * file that is not there.
+ */
+export function stillKept(root, verdict) {
+    const reproduction = verdict.reproduction;
+    if (reproduction?.keptIn === undefined)
+        return verdict;
+    const folder = insideDirectory(root, reproduction.keptIn);
+    if (folder !== undefined && existsSync(join(folder, "manifest.json")))
+        return verdict;
+    const rest = { ...reproduction };
+    delete rest.keptIn;
+    delete rest.keptFiles;
+    return { ...verdict, reproduction: rest };
+}
+/**
+ * One line per verdict, the promise named by its title and id. A broken one
+ * carries a second, indented line saying what to do next.
+ */
+export function verdictLine(verdict, title, context = {}) {
+    const name = `${title} (${verdict.promiseId})`;
+    const earlier = context.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}\n` +
+            `    ${afterBreakLine(verdict, context.checkBound)}`);
+    }
+    const rejected = verdict.reproductionRejected
+        ? ` A reported break did not hold up when run both ways: ${verdict.reproductionRejected}.`
+        : "";
+    const notes = verdict.notes ? ` ${sentence(verdict.notes)}` : "";
+    const nextStep = verdict.nextStep?.trim()
+        ? ` To let it run: ${sentence(verdict.nextStep, NEXT_STEP_LIMIT)}`
+        : "";
+    return `could not tell: ${name}${earlier}.${notes}${rejected}${nextStep}`;
+}
+/** The head commit of a named pull request, through the person's own `gh`. */
+async function pullRequestHead(root, target) {
+    const result = await runCommand("gh", [
+        "pr",
+        "view",
+        ...(target.selector === undefined ? [] : [target.selector]),
+        ...(target.repo === undefined ? [] : ["--repo", target.repo]),
+        "--json",
+        "headRefOid",
+        "--jq",
+        ".headRefOid",
+    ], { cwd: root, timeoutMs: 10_000 });
+    const sha = result.stdout.trim();
+    return result.ok && /^[0-9a-f]{40}$/.test(sha) ? sha : undefined;
+}
+/** Said instead of verdicts when the check cannot tell which repository a push leaves from. */
+export const PUSH_REPOSITORY_UNKNOWN = "Balladeer judge: this push was not judged, because the check could not tell which repository it pushes.";
+/** Said instead of verdicts when every pull request the command opens or merges is in another repository. */
+export function pullRequestElsewhereLine(repo) {
+    return `Balladeer judge: the pull request is in another repository (${repo}), not this checkout's, so nothing was judged.`;
+}
+/**
+ * The repository the command's pull requests are in, when every push in it
+ * is a `gh pr create` or `gh pr merge` naming, with `--repo`, `-R` or
+ * `GH_REPO`, a repository that none of this checkout's remotes points at.
+ * Otherwise nothing, and the change here is judged as usual.
+ */
+async function pullRequestElsewhere(directory, sites) {
+    if (sites.length === 0 || sites.some((site) => site.repo === undefined))
+        return undefined;
+    const listed = await runCommand("git", ["-C", directory, "remote", "-v"]);
+    const own = listed.ok ? remoteRepositoryNames(listed.stdout) : new Set();
+    const inOwn = (repo) => {
+        const name = repositoryName(repo);
+        return name !== undefined && own.has(name);
+    };
+    return sites.some((site) => inOwn(site.repo)) ? undefined : sites[0].repo;
+}
+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();
+}
+/** What `--push-check off` and `--push-check on` say. */
+export const PUSH_CHECK_OFF_LINE = "The push check is off on this laptop: after a push it now says nothing, in every repository. A repository's own entry from `balladeer judge --install-hook` still runs. Turn it back on with `balladeer judge --push-check on`.";
+export const PUSH_CHECK_ON_LINE = "The push check is back on for this laptop: after a push in a connected repository whose promises have behavior maps, it reports what the push may have broken, and it never holds the push.";
+/**
+ * Whether the push check's user-scope entry has this push to itself, decided
+ * before anything is started or fetched: the entry runs on every shell command
+ * in every folder on the laptop, and most folders have nothing to judge. It
+ * stands aside, saying nothing, when the laptop turned the check off, the
+ * folder is in no checkout, the checkout has the push check's own project
+ * entry for this host (that entry owns the check there, so a push is judged
+ * once), or no promise here has a behavior map. Only then is the connection
+ * looked for, which reads the checkout's remotes, and a checkout this laptop
+ * has not connected is left alone too.
+ */
+export function userScopeTakesThePush(input) {
+    if (pushCheckOff(input.environment))
+        return false;
+    const root = checkoutRoot(input.cwd);
+    if (root === undefined)
+        return false;
+    if (hasProjectJudgeHook(root, input.host))
+        return false;
+    const mapped = readBehaviorMaps(join(root, ".continuity/behavior-maps")).some((entry) => entry.map !== undefined);
+    return mapped && input.connected(root);
+}
+/** `balladeer judge`, from arguments already parsed. */
+/**
+ * The line an answer opens with when the command makes a commit before it
+ * pushes. Robert approved it on 30 September 2026: the check keeps running
+ * before the push, and says plainly that it did not see the commit.
+ */
+export function commitFirstLine(made) {
+    return `This command runs \`${made}\` before it pushes, and Balladeer checks the code before a command runs, so this check covers the code as it was before this command, not the commit it makes. Run \`balladeer judge\` once it is pushed to check that commit.`;
+}
+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);
+        }
+    };
+    // Which host event called: PreToolUse before the command runs, PostToolUse
+    // after it. Report mode acts on the second and block mode on the first.
+    let event = "PreToolUse";
+    let command;
+    // Said after everything else the run has to say, before any offers.
+    const trailing = [];
+    // Set only when the check runs before a line that makes a commit before it
+    // pushes (a checkout whose hook predates judging after the push): whatever
+    // it says is about the code before that commit, and the answer says so
+    // first. After the push the commit exists, and nothing needs saying.
+    let commitFirst;
+    const respond = async (block) => {
+        if (commitFirst !== undefined)
+            lines.unshift(commitFirstLine(commitFirst));
+        commitFirst = undefined;
+        const offered = await settleOffers();
+        lines.push(...trailing);
+        // 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, event });
+        if (!json) {
+            if (response.stdout)
+                options.write(response.stdout);
+            if (response.stderr && (hook !== undefined || block))
+                options.error(response.stderr);
+        }
+        return response.exitCode;
+    };
+    if (args.pushCheck !== undefined) {
+        setPushCheck(options.environment, args.pushCheck === "on");
+        options.write(`${args.pushCheck === "on" ? PUSH_CHECK_ON_LINE : PUSH_CHECK_OFF_LINE}\n`);
+        return 0;
+    }
+    // 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;
+    // A merge that names a pull request is about that pull request's change,
+    // which need not be the one in this checkout.
+    let namedMerge;
+    // Where the command pushes from, which is not the session's folder when it
+    // moves first (`cd ../other && git push`, `git -C ../other push`). When that
+    // cannot be told for certain, nothing is judged and the answer says so.
+    let place;
+    // The host's session, so a could-not-tell it already heard comes back quietly.
+    let sessionId;
+    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 {
+            // Codex runs a user hook only once the person trusted it, so this one
+            // running at all, push or not, says the push check is trusted there.
+            if (args.userScope && hook === "codex")
+                noteHookFired(options.environment, "codex", now().getTime(), "push-check");
+            const parsed = parseHookInput(input);
+            if (parsed?.command === undefined || !isPushCommand(parsed.command))
+                return 0;
+            // The installer adds this command to both events; on any other event,
+            // wired by hand, there is nothing for it to do.
+            const called = parsed.eventName ?? "PreToolUse";
+            if (called !== "PreToolUse" && called !== "PostToolUse")
+                return 0;
+            event = called;
+            command = parsed.command;
+            if (parsed.cwd !== undefined && existsSync(parsed.cwd))
+                cwd = parsed.cwd;
+            // Where the push leaves from first: the user-scope entry decides on
+            // that repository, or on the session's own when the line does not say.
+            place = pushPlace(parsed.command, cwd);
+            if (place.known && existsSync(place.directory))
+                cwd = place.directory;
+            else
+                place = { known: false };
+            sessionId = parsed.sessionId;
+            if (args.userScope &&
+                !userScopeTakesThePush({
+                    cwd,
+                    host: hook,
+                    environment: options.environment,
+                    connected: deps.connected ??
+                        ((root) => connectionReader({
+                            environment: options.environment,
+                            controlPlane: args.controlPlane,
+                            cwd: root,
+                            ...(args.repository === undefined ? {} : { repository: args.repository }),
+                        }).ok),
+                }))
+                return 0;
+            namedMerge = mergeTargets(parsed.command).find((target) => target.selector !== undefined || target.repo !== undefined);
+        }
+    }
+    const pushedFromUnknown = () => {
+        emit({
+            step: "judge",
+            status: "nothing_to_judge",
+            reason: "repository_unknown",
+            message: PUSH_REPOSITORY_UNKNOWN,
+            exitCode: 0,
+        });
+        lines.push(PUSH_REPOSITORY_UNKNOWN);
+        return respond(false);
+    };
+    const root = args.repo !== undefined ? resolve(options.cwd, args.repo) : await repositoryRoot(cwd);
+    if (root === undefined || !existsSync(root)) {
+        if (hook !== undefined)
+            return place?.known === false ? pushedFromUnknown() : 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` when a command pushes or opens or merges a pull request, and says nothing for any other command. In report mode, the default, it judges once the push has landed, so the push never waits for it. Set "mode": "block" in .continuity/judge.json to judge before the push instead and stop it on a reproduced break. A session that is already open picks up the hook once it is restarted.\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}.`);
+    // Report mode judges after the command and block mode before it, so each
+    // mode acts on one of the two events and lets the other go at once.
+    if (hook === "claude" || hook === "codex") {
+        if (event === "PostToolUse" && mode === "block")
+            return 0;
+        if (event === "PreToolUse" && mode === "block" && command !== undefined) {
+            if (commitBeforePush(command) !== undefined) {
+                lines.push(COMMIT_THEN_PUSH);
+                return respond(true);
+            }
+        }
+        if (event === "PreToolUse" && mode === "report") {
+            // Setup writes the user-scope pair together, so its entry after the
+            // push is there to judge; an earlier project install may have only this one.
+            if (args.userScope || hasJudgeEntry(root, hook, "PostToolUse"))
+                return 0;
+            if (command !== undefined)
+                commitFirst = commitBeforePush(command);
+            // Installed by an earlier release, with no entry after the push: judge
+            // here as that release did, rather than not at all, and say how to move.
+            trailing.push(`Balladeer judge: this push waited for the check because this checkout's hook was installed by an earlier release. Run \`balladeer judge --install-hook ${hook}\` again so the check runs after the push instead.`);
+        }
+    }
+    // Where the push leaves from: judged there, or not at all when that cannot be known,
+    // and a pull request in another repository is not this checkout's to judge. After
+    // the event gate, so each line is said once, on the event that acts.
+    if (place?.known === false)
+        return pushedFromUnknown();
+    const elsewhere = place?.known ? await pullRequestElsewhere(cwd, place.sites) : undefined;
+    if (elsewhere !== undefined) {
+        const message = pullRequestElsewhereLine(elsewhere);
+        emit({
+            step: "judge",
+            status: "nothing_to_judge",
+            reason: "pull_request_elsewhere",
+            message,
+            exitCode: 0,
+        });
+        lines.push(message);
+        return respond(false);
+    }
+    await runCommand("git", ["-C", root, "worktree", "prune"]);
+    if (namedMerge !== undefined && args.head === undefined) {
+        const named = [namedMerge.repo, namedMerge.selector].filter(Boolean).join(" ");
+        const target = await (deps.pullRequestHead ?? pullRequestHead)(root, namedMerge);
+        const local = target === undefined ? undefined : await resolveCommit(root, target);
+        if (local === undefined) {
+            const message = target === undefined
+                ? `Balladeer judge: could not read which commit pull request ${named} would merge, so it was not judged.`
+                : `Balladeer judge: pull request ${named} merges ${target.slice(0, 12)}, which is not in this checkout, so it was not judged.`;
+            emit({
+                step: "judge",
+                status: "nothing_to_judge",
+                reason: "merge_elsewhere",
+                message,
+                exitCode: 0,
+            });
+            lines.push(message);
+            return respond(false);
+        }
+        pushedHead = local;
+    }
+    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;
+    }
+    // After the command, what was pushed is what is judged, so it has to have
+    // reached the remote: Codex calls this hook after a push that failed, too.
+    // A merge sends no commits of this checkout, so it has nothing to check.
+    if (event === "PostToolUse" &&
+        command !== undefined &&
+        sendsCommits(command) &&
+        namedMerge === undefined &&
+        args.head === undefined &&
+        !(await pushLanded(root, head))) {
+        const message = `Balladeer judge: nothing was judged, because the push did not land: ${head.slice(0, 12)} is on no remote branch.`;
+        emit({
+            step: "judge",
+            status: "nothing_to_judge",
+            reason: "push_not_landed",
+            message,
+            exitCode: 0,
+        });
+        lines.push(message);
+        return respond(false);
+    }
+    const base = args.base !== undefined
+        ? await resolveCommit(root, args.base)
+        : ((event === "PostToolUse" ? await baseBeforePush(root, head) : undefined) ??
+            (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) {
+        // Said in one line either way, so that silence is never read as safe.
+        const noMaps = mappedIds.length === 0;
+        const message = noMaps
+            ? "No promise here has a behavior map yet, so nothing was judged. Build them with `balladeer map --all`."
+            : `This ${hook === undefined ? "change" : "push"} touches no promise's mapped code, so nothing was judged.`;
+        emit({
+            step: "judge",
+            status: "nothing_to_judge",
+            reason: noMaps ? "no_maps" : "no_promise_touched",
+            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,
+                        checkBound: job.promise.verifierBound,
+                    });
+                    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,
+                        checkBound: job.promise.verifierBound,
+                    });
+                    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:`);
+    // A could-not-tell this session already heard in full comes back as one quiet line.
+    const told = sessionMemory(join(root, JUDGE_LOG_DIRECTORY), sessionId, now());
+    for (const { verdict, title, reused, checkBound } of verdicts)
+        lines.push(`  ${told?.repeat(verdict, title) ??
+            verdictLine(stillKept(root, verdict), title, {
+                reused,
+                ...(checkBound === undefined ? {} : { checkBound }),
+            })}`);
+    told?.save();
+    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,
+    });
+}