balladeer 1.0.16 → 1.0.17

package/dist/cli.d.ts

@@ -33,7 +33,7 @@ type Parsed = Readonly<{
      */
     repositories: readonly string[];
     hook: "codex" | "claude" | undefined;
-    event: "SessionStart" | "UserPromptSubmit" | "SubagentStart" | undefined;
+    event: "SessionStart" | "UserPromptSubmit" | "SubagentStart" | "PostToolUse" | undefined;
     owner: string | undefined;
     /** `check-seals --install-hook`: write the optional pre-push hook. */
     installHook: boolean;

package/dist/cli.js

@@ -25,7 +25,7 @@ import { runWhoami } from "./commands/whoami.js";
 import { runInstall } from "./install.js";
 import { openInBrowser } from "./open-browser.js";
 import { PUBLISHED_SPECIFIER } from "./release.js";
-import { CODEX_HOOK_APPROVAL, installUserScope, runningFromCheckout, userHome, } from "./user-scope.js";
+import { codexHookApproval, installUserScope, pushCheckSetupLine, pushCheckState, runningFromCheckout, userHome, } from "./user-scope.js";
 import { updateNotice } from "./currency.js";
 import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "./remove-earlier.js";
 import { recordSelfUpdateState, SELF_UPDATE_ENVIRONMENT } from "./self-update.js";
@@ -275,8 +275,9 @@ export function parseArguments(argv) {
             const requested = value("--event", inline);
             if (requested !== "SessionStart" &&
                 requested !== "UserPromptSubmit" &&
-                requested !== "SubagentStart")
-                throw new StoreError("usage", "--event needs SessionStart, UserPromptSubmit or SubagentStart.");
+                requested !== "SubagentStart" &&
+                requested !== "PostToolUse")
+                throw new StoreError("usage", "--event needs SessionStart, UserPromptSubmit, SubagentStart or PostToolUse.");
             event = requested;
         }
         else if (name === "--json")
@@ -497,12 +498,14 @@ function commandVersion(name) {
 function installEverything(options) {
     const published = !runningFromCheckout();
     let writes;
+    let pushCheck = "unavailable";
     const register = (installed) => {
         writes = installUserScope({
             environment: process.env,
             published,
             ...(installed === undefined ? {} : { installed }),
         });
+        pushCheck = pushCheckState(process.env, published, installed);
         return writes;
     };
     const code = runInstall({
@@ -510,12 +513,15 @@ function installEverything(options) {
         json: options.json,
         write: options.write,
         allowPartial: options.allowPartial,
-        onInstalled: (result) => ({ userScope: register(result.command) }),
+        onInstalled: (result) => {
+            const userScope = register(result.command);
+            return { userScope, pushCheck };
+        },
     });
     if (writes === undefined) {
         const fallback = register();
         if (options.json)
-            options.write(`${JSON.stringify({ step: "user_scope", userScope: fallback })}\n`);
+            options.write(`${JSON.stringify({ step: "user_scope", userScope: fallback, pushCheck })}\n`);
     }
     for (const w of writes ?? [])
         if (!options.json)
@@ -531,7 +537,7 @@ function installEverything(options) {
         if (options.json)
             options.write(`${JSON.stringify({ step: "codex_hooks", approval: codex.status === "written" ? "required" : "check", command: "/hooks" })}\n`);
         else
-            options.write(`${CODEX_HOOK_APPROVAL}\n`);
+            options.write(`${codexHookApproval(pushCheck !== "unavailable")}\n`);
     }
     // With the user-scope form in place, the older per-repository form in this
     // checkout only makes the session hear the guidance twice. Out it goes, with
@@ -554,6 +560,13 @@ function installEverything(options) {
         options.write("Balladeer now runs in every Claude Code" +
             ((writes ?? []).some((w) => w.host === "codex") ? " and Codex" : "") +
             " session on this machine. In a folder of a connected repository it works as before; anywhere else it stays quiet, and `balladeer status` there says why.\n");
+    // The push check rides on the same hooks file, so it is on wherever that
+    // file was written: said once per run, with how to turn it off. Under
+    // --json it is the `pushCheck` field of the install step, so that step stays
+    // one object.
+    const hooksFile = (writes ?? []).find((w) => w.path.endsWith("settings.json"));
+    if (!options.json && hooksFile !== undefined && hooksFile.status !== "refused")
+        options.write(`${pushCheckSetupLine(pushCheck)}\n`);
     const outcome = (writes ?? []).some((w) => w.status === "refused") ? 4 : code;
     // Started by the session hook's background update: leave how it ended where
     // the next hook fire will find it and tell the server.

package/dist/commands/guidance.d.ts

@@ -5,7 +5,8 @@ export type GuidanceOptions = Readonly<{
     controlPlane: string;
     repositoryId?: string;
     hook: "codex" | "claude";
-    event?: GuidanceEvent;
+    /** PostToolUse is the relay note, not guidance: see `runRelayNote`. */
+    event?: GuidanceEvent | "PostToolUse";
     runtimeGeneration?: string;
     environment: NodeJS.ProcessEnv;
     cwd: string;

package/dist/commands/guidance.js

@@ -1,3 +1,4 @@
+import { relayHook } from "../relay.js";
 import { validateProjectGuidanceScope } from "../guidance-install.js";
 import { GUIDANCE_UNAVAILABLE, loadGuidance, recordGuidanceContext, } from "../guidance.js";
 import { readCredentials } from "../store.js";
@@ -60,8 +61,62 @@ function eventFrom(input) {
 function identifier(input) {
     return typeof input === "string" && input.length > 0 && input.length <= 256 ? input : undefined;
 }
+/**
+ * After a Balladeer tool acts, a note the agent reads before it replies: tell
+ * the person what Balladeer did, in your own words (promise
+ * prom_45ef4e3d9e5545a9a411; plans/promise-relations/plan.md, step 1). Codex
+ * relayed every detail in 10 of 10 lab sessions with it and 6 of 10 without.
+ * Local only: no connection, no network, nothing stored. A tool result can be
+ * large, so the input bound is wider than guidance's; anything unreadable,
+ * oversized or late prints nothing, never the guidance-unavailable notice.
+ */
+async function runRelayNote(options) {
+    const input = await new Promise((resolve) => {
+        const chunks = [];
+        let bytes = 0;
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.stdin.removeListener("data", data);
+            resolve(value);
+        };
+        const data = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            bytes += buffer.length;
+            if (bytes > 1_048_576)
+                done(undefined);
+            else
+                chunks.push(buffer);
+        };
+        const timer = setTimeout(() => done(undefined), 1_000);
+        options.stdin.on("data", data);
+        options.stdin.once("end", () => {
+            try {
+                done(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                done(undefined);
+            }
+        });
+        options.stdin.once("error", () => done(undefined));
+    });
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return 0;
+    const record = input;
+    if (record.hook_event_name !== "PostToolUse")
+        return 0;
+    const out = relayHook(record);
+    if (out)
+        options.write(`${out}\n`);
+    return 0;
+}
 /** Hook stdout is bounded context only. Host prompts and transcript paths never leave this process. */
 export async function runGuidance(options) {
+    if (options.event === "PostToolUse")
+        return runRelayNote(options);
     // A project hook names its repository and must match the checkout it sits
     // in. A user-scope hook names none: the folder's remotes decide.
     const projectScoped = options.repositoryId !== undefined;

package/dist/commands/judge.d.ts

@@ -1,7 +1,9 @@
 import { type BehaviorMap } from "../behavior-map-schema.js";
 import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
-import { type HookHost } from "../judge-hook.js";
+import { type HookHost, type MergeTarget } from "../judge-hook.js";
 import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
+import { type CarriedFile } from "../scratch-worktree.js";
+import type { Features } from "../risk/contract.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.
@@ -18,7 +20,15 @@ export declare const JUDGE_VERDICT_SCHEMA_VERSION = "balladeer-judge-verdict/v1"
 export declare const JUDGE_CONFIG_SCHEMA_VERSION = "balladeer-judge-config/v1";
 export declare const JUDGE_CONFIG_PATH = ".continuity/judge.json";
 export declare 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 declare const KEPT_REPRODUCTIONS_DIRECTORY = ".continuity/judge-log/reproductions";
+export declare const KEPT_REPRODUCTION_SCHEMA_VERSION = "balladeer-kept-reproduction/v1";
 export declare 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 declare 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.";
 export type JudgeConfig = Readonly<{
     schemaVersion: typeof JUDGE_CONFIG_SCHEMA_VERSION;
     mode: "report" | "block";
@@ -28,6 +38,13 @@ export type JudgeConfig = Readonly<{
     sampleBelowLine: number;
     alwaysJudge: readonly string[];
     client: HeadlessClient | "auto";
+    /**
+     * Which promises the risk report hands to a judge: "direct" (the default)
+     * takes every promise whose own code or tests the change edits, and nothing
+     * else; "ranked" takes the top `topK` in the report's order plus a random
+     * sample below that line.
+     */
+    select: "direct" | "ranked";
     /**
      * From the push hook, also read the change for rules no promise records and
      * hand at most three to the pushing session as offers. Off unless set.
@@ -64,10 +81,25 @@ export type JudgeVerdict = {
         failsOnHead: boolean;
         passesOnBase: boolean;
         digest: string;
+        /**
+         * Where the reproduction was kept on this machine, repository-relative:
+         * a folder holding `manifest.json` and, under `files/`, the files the
+         * judge added, at the paths it wrote them. Only for a break verified both
+         * ways, and absent when keeping it failed.
+         */
+        keptIn?: string;
+        /** The kept files' repository-relative paths, each under `<keptIn>/files/`. */
+        keptFiles?: string[];
     } | null;
     reproductionRejected: string | null;
     exercisedCases: string[];
     notes: string;
+    /**
+     * On a could-not-tell the judge itself reached because the tests need
+     * something this machine lacks: the one step that would let them run, as
+     * the judge wrote it. Absent otherwise. It never changes the verdict.
+     */
+    nextStep?: string;
     judge: {
         client: HeadlessClient;
         model: string;
@@ -101,6 +133,8 @@ export type ReproductionCheck = Readonly<{
     rejected: string | null;
     /** The budget ran out while it was being run, so there is no answer yet. */
     stopped: boolean;
+    /** The files the judge added, carried to base and fingerprinted into `digest`. */
+    files: readonly CarriedFile[];
 }>;
 /**
  * Run a judge's reproduction both ways.
@@ -123,6 +157,42 @@ export declare function verifyReproduction(input: Readonly<{
     signal?: AbortSignal;
     scratch?: string;
 }>): Promise<ReproductionCheck>;
+export type KeptReproduction = Readonly<{
+    /** Repository-relative, forward slashes: the folder under the judge log. */
+    keptIn: string;
+    /** The files kept, repository-relative, each at `<keptIn>/files/<path>`. */
+    files: string[];
+}>;
+/**
+ * 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 declare function keepReproduction(input: Readonly<{
+    root: string;
+    headTree: string;
+    promiseId: string;
+    semanticDigest: string;
+    base: string;
+    head: string;
+    command: string;
+    cwd: string;
+    digest: string;
+    files: readonly CarriedFile[];
+}>): KeptReproduction | 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
@@ -137,7 +207,10 @@ type JudgeAnswer = Readonly<{
     }>;
     exercisedCases: string[];
     notes: string;
+    nextStep?: string;
 }>;
+/** The longest `nextStep` kept from a judge's answer, in characters. */
+export declare const NEXT_STEP_LIMIT = 500;
 /** The judge's final JSON, read strictly enough that a malformed answer is not a verdict. */
 export declare function readJudgeAnswer(json: Record<string, unknown> | undefined): JudgeAnswer | undefined;
 export type JudgePromiseInput = Readonly<{
@@ -180,6 +253,10 @@ export type JudgeArguments = Readonly<{
     mode?: "report" | "block";
     wait: boolean;
     hook?: HookHost;
+    /** Run by the entry setup writes at the host's user scope, which stands aside where it has nothing to do. */
+    userScope?: true;
+    /** Turn this laptop's user-scope push check on or off. */
+    pushCheck?: "on" | "off";
     installHook?: HookHost | "agents";
     fromFile?: string;
     map?: string;
@@ -188,13 +265,20 @@ export type JudgeArguments = Readonly<{
     repository?: string;
     controlPlane: string;
 }>;
-export declare const JUDGE_USAGE = "  npx -y balladeer@latest judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]\n                  [--report-only | --block] [--wait] [--json] [--client auto|claude|codex]\n                  [--from-file <promise.json> [--map <map.json>]]\n                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]\n      Judge whether this change keeps the promises it could break, one promise\n      at a time, on your own Claude Code or Codex login. A break counts only\n      with a command that fails with the change and passes without it, and\n      this command runs it both ways itself; anything unproven is \"could not\n      tell\". Report mode prints one line per promise and never stops anything;\n      --block exits 2 on a reproduced break, and when judges are still running\n      at the time limit it holds the push rather than letting it through.\n      --wait runs without the time limit. Promises come from --promises, else\n      the top of `balladeer risk`, else every mapped promise, plus\n      .continuity/judge.json's alwaysJudge and a small random sample. Verdicts\n      are kept in .continuity/judge-log/, which git ignores. --install-hook\n      adds the push hook to .claude/settings.json and .codex/hooks.json, or\n      .git/hooks/pre-push with git. With \"offers\": true in that file, the push\n      hook also reads the change for rules no promise records and offers at\n      most three to whoever is pushing; it records nothing and never holds a\n      push (see `balladeer offers`).\n";
+export declare const JUDGE_USAGE = "  npx -y balladeer@latest judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]\n                  [--report-only | --block] [--wait] [--json] [--client auto|claude|codex]\n                  [--from-file <promise.json> [--map <map.json>]]\n                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]\n                  [--push-check on|off]\n      Judge whether this change keeps the promises it could break, one promise\n      at a time, on your own Claude Code or Codex login. A break counts only\n      with a command that fails with the change and passes without it, and\n      this command runs it both ways itself; anything unproven is \"could not\n      tell\". Report mode prints one line per promise and never stops anything;\n      --block exits 2 on a reproduced break, and when judges are still running\n      at the time limit it holds the push rather than letting it through.\n      --wait runs without the time limit. Promises come from --promises, else\n      from `balladeer risk`: every promise whose own code or tests the\n      change edits, or with \"select\": \"ranked\" in .continuity/judge.json the\n      top of its ranking and a small random sample; else every mapped\n      promise; plus that file's alwaysJudge. Verdicts are kept in\n      .continuity/judge-log/, which git ignores. --install-hook adds the push\n      hook to .claude/settings.json and .codex/hooks.json, before and after\n      each shell command: report mode judges after a push has landed, so the\n      push never waits, and block mode judges before it. With git it writes\n      .git/hooks/pre-push, which judges before the push in both modes. With\n      \"offers\": true in .continuity/judge.json, the push hook also reads the\n      change for rules no promise records and offers at most three to\n      whoever is pushing; it records nothing and never holds a push (see\n      `balladeer offers`). Setup also writes the same pair of entries at\n      each host's user scope, running `judge --hook <host> --user-scope`,\n      so the check runs in every connected repository with mapped promises\n      and says nothing anywhere else; a checkout with its own entry keeps\n      the check to that entry. --push-check off turns the user-scope check\n      off on this laptop, and --push-check on turns it back on.\n";
 export declare function parseJudgeArguments(argv: readonly string[]): JudgeArguments;
-/** The subset of `balladeer-risk/v1` this command reads. */
+/**
+ * The subset of `balladeer-risk/v1` this command reads: enough to order the
+ * entries the way `balladeer risk` does. An entry without `features` reads as
+ * reaching its promise not at all, and one without `evidence` as none.
+ */
 export type RiskEntry = Readonly<{
     promiseId: string;
     score: number;
     band: string;
+    features?: Features;
+    /** The total weight of the entry's reasons. */
+    evidence?: number;
 }>;
 /** Read a risk report out of whatever `balladeer risk --json` printed. */
 export declare function readRiskOutput(stdout: string): RiskEntry[] | undefined;
@@ -209,10 +293,20 @@ export type Selection = Readonly<{
     why: "file" | "named" | "risk" | "sample" | "mapped" | "always";
 }>;
 /**
- * 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 declare function selectPromises(input: Readonly<{
     named?: readonly string[];
@@ -234,8 +328,39 @@ export declare function findLoggedVerdict(root: string, key: Readonly<{
     base: string;
     head: string;
 }>, now: Date): JudgeVerdict | undefined;
-/** One line per verdict, the promise named by its title and id. */
-export declare function verdictLine(verdict: JudgeVerdict, title: string, reused?: boolean): string;
+/** Said after "fix the behavior": a deliberate change is the person's, and the promise its owner's. */
+export declare 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.";
+export type VerdictLineContext = Readonly<{
+    /** The verdict was reached earlier for this same commit and read back from the log. */
+    reused?: boolean;
+    /**
+     * Whether the promise has a Balladeer check bound, as its connection said.
+     * Absent when that is unknown (a promise from a file or a map's excerpt),
+     * and then the line says nothing about a check rather than guessing.
+     */
+    checkBound?: boolean;
+}>;
+/**
+ * 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 declare function afterBreakLine(verdict: JudgeVerdict, checkBound?: boolean): string;
+/**
+ * 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 declare function stillKept(root: string, verdict: JudgeVerdict): JudgeVerdict;
+/**
+ * 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 declare function verdictLine(verdict: JudgeVerdict, title: string, context?: VerdictLineContext): string;
 export type JudgeDependencies = Readonly<{
     runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
     resolveLogin?: (requested: HeadlessClient | "auto", prefer?: HeadlessClient) => Promise<LoginCheck | undefined>;
@@ -250,7 +375,15 @@ export type JudgeDependencies = Readonly<{
     judge?: (input: JudgePromiseInput) => Promise<JudgeOutcome>;
     /** The agent run that reads the change for offers, when they are on. */
     offerAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** The head commit of the pull request a `gh pr merge` names. */
+    pullRequestHead?: (root: string, target: MergeTarget) => Promise<string | undefined>;
+    /** Whether this laptop has a connection for the checkout, read locally. */
+    connected?: (root: string) => boolean;
 }>;
+/** Said instead of verdicts when the check cannot tell which repository a push leaves from. */
+export declare 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 declare function pullRequestElsewhereLine(repo: string): string;
 export type JudgeRunOptions = Readonly<{
     args: JudgeArguments;
     cwd: string;
@@ -259,7 +392,33 @@ export type JudgeRunOptions = Readonly<{
     error: (text: string) => void;
     deps?: JudgeDependencies;
 }>;
+/** What `--push-check off` and `--push-check on` say. */
+export declare 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 declare 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 declare function userScopeTakesThePush(input: {
+    cwd: string;
+    host: "claude" | "codex";
+    environment: NodeJS.ProcessEnv;
+    connected: (root: string) => boolean;
+}): boolean;
 /** `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 declare function commitFirstLine(made: string): string;
 export declare function runJudge(options: JudgeRunOptions): Promise<number>;
 /** `balladeer judge ...` from raw arguments, as `cli.ts` hands them over. */
 export declare function judgeCommand(argv: readonly string[], io: Readonly<{