balladeer 1.0.16 → 1.0.17

package/dist/commands/judge.js

@@ -1,15 +1,18 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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 { effectiveBudgetSeconds, hookResponse, installJudgeHook, isPushCommand, parseHookInput, parsePrePushInput, } from "../judge-hook.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";
@@ -29,7 +32,15 @@ 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;
@@ -43,6 +54,7 @@ export const DEFAULT_JUDGE_CONFIG = {
     sampleBelowLine: 0.1,
     alwaysJudge: [],
     client: "auto",
+    select: "direct",
     offers: false,
     offersOn: "fixes",
     maxOffers: 1,
@@ -104,6 +116,7 @@ export function readJudgeConfig(root) {
             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),
@@ -167,6 +180,7 @@ export async function verifyReproduction(input) {
         digest,
         rejected,
         stopped: false,
+        files: carried,
     });
     const headCwd = insideDirectory(input.headTree, input.cwd);
     if (headCwd === undefined || !existsSync(headCwd))
@@ -177,7 +191,14 @@ export async function verifyReproduction(input) {
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
     if (atHead.aborted)
-        return { failsOnHead: false, passesOnBase: false, digest, rejected: null, stopped: true };
+        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)
@@ -199,17 +220,81 @@ export async function verifyReproduction(input) {
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
         if (atBase.aborted)
-            return { failsOnHead: true, passesOnBase: false, digest, rejected: null, stopped: true };
+            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 };
+        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
@@ -240,6 +325,8 @@ export function linkedTestCommand(tree, file) {
     }
     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)
@@ -262,11 +349,13 @@ export function readJudgeAnswer(json) {
             ...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 }),
     };
 }
 /**
@@ -398,6 +487,10 @@ export async function judgePromise(input) {
                     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({
@@ -413,12 +506,29 @@ export async function judgePromise(input) {
         });
         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",
@@ -439,6 +549,7 @@ export const JUDGE_USAGE = `  ${CLI_INVOCATION} judge [--promises <id,id>] [--to
                   [--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
@@ -447,14 +558,24 @@ export const JUDGE_USAGE = `  ${CLI_INVOCATION} judge [--promises <id,id>] [--to
       --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\`).
+      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];
@@ -466,6 +587,8 @@ export function parseJudgeArguments(argv) {
     let mode;
     let wait = false;
     let hook;
+    let userScope = false;
+    let pushCheck;
     let installHook;
     let fromFile;
     let map;
@@ -519,6 +642,14 @@ export function parseJudgeArguments(argv) {
             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);
@@ -546,6 +677,8 @@ export function parseJudgeArguments(argv) {
         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 }),
@@ -556,6 +689,8 @@ export function parseJudgeArguments(argv) {
         ...(mode === undefined ? {} : { mode }),
         wait,
         ...(hook === undefined ? {} : { hook }),
+        ...(userScope ? { userScope: true } : {}),
+        ...(pushCheck === undefined ? {} : { pushCheck }),
         ...(installHook === undefined ? {} : { installHook }),
         ...(fromFile === undefined ? {} : { fromFile }),
         ...(map === undefined ? {} : { map }),
@@ -565,6 +700,51 @@ export function parseJudgeArguments(argv) {
         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 = [];
@@ -592,9 +772,23 @@ export function readRiskOutput(stdout) {
             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 ?? "") }]
-                : [];
+            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;
@@ -648,10 +842,20 @@ export async function changedFiles(root, base, head) {
     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.
+ * 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 = [];
@@ -666,17 +870,23 @@ export function selectPromises(input) {
         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");
+        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)
@@ -691,17 +901,26 @@ function logPath(root, now) {
     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.
+ * 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.
  */
-export function appendVerdicts(root, verdicts, now) {
-    if (verdicts.length === 0)
-        return;
+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. */
@@ -736,23 +955,129 @@ 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) {
+/** 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 = reused ? " [judged earlier for this commit]" : "";
+    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}`;
+        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)}` : "";
-    return `could not tell: ${name}${earlier}.${notes}${rejected}`;
+    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)
@@ -786,7 +1111,40 @@ function describeInstall(result) {
         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 ?? {};
@@ -825,12 +1183,27 @@ export async function runJudge(options) {
                 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 });
+        const response = hookResponse(hook ?? "git", { block, lines, event });
         if (!json) {
             if (response.stdout)
                 options.write(response.stdout);
@@ -839,12 +1212,26 @@ export async function runJudge(options) {
         }
         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") {
@@ -854,17 +1241,62 @@ export async function runJudge(options) {
             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 0;
+            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)
@@ -882,7 +1314,7 @@ export async function runJudge(options) {
                 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');
+            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");
         }
@@ -892,7 +1324,68 @@ export async function runJudge(options) {
     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.`;
@@ -903,7 +1396,30 @@ export async function runJudge(options) {
             options.error(`${message}\n`);
         return 4;
     }
-    const base = args.base !== undefined ? await resolveCommit(root, args.base) : await defaultBase(root, head);
+    // 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.`
@@ -993,8 +1509,18 @@ export async function runJudge(options) {
         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 });
+        // 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);
     }
@@ -1072,7 +1598,12 @@ export async function runJudge(options) {
                     head,
                 }, now());
                 if (logged !== undefined) {
-                    verdicts.push({ verdict: logged, title: job.promise.title, reused: true });
+                    verdicts.push({
+                        verdict: logged,
+                        title: job.promise.title,
+                        reused: true,
+                        checkBound: job.promise.verifierBound,
+                    });
                     continue;
                 }
                 if (budget.signal.aborted) {
@@ -1099,7 +1630,12 @@ export async function runJudge(options) {
                 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 });
+                    verdicts.push({
+                        verdict: outcome.verdict,
+                        title: job.promise.title,
+                        reused: false,
+                        checkBound: job.promise.verifierBound,
+                    });
                     appendVerdicts(root, [outcome.verdict], now());
                 }
             }
@@ -1119,8 +1655,15 @@ export async function runJudge(options) {
         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)}`);
+    // 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)