balladeer 1.0.16 → 1.0.17

package/dist/hook-trust.d.ts

@@ -16,16 +16,48 @@ export type TrustingHost = "codex";
 /** Hosts that run a hook only after the person has approved it. */
 export declare const HOSTS_REQUIRING_TRUST: readonly TrustingHost[];
 /**
- * This command wrote or changed the host's hooks, or found them in place with
- * no record that it ever had: either way, from now the host has to have run
- * them once before anybody assumes it does.
+ * Hooks this command writes as one set, each set with its own marks. The
+ * guidance hooks and the push check are written separately, and a host keeps
+ * running an unchanged hook it already trusted, so one set running says
+ * nothing about the other: once the push check was added, the trusted
+ * guidance hooks would run at the next session start and settle a single mark
+ * while the new push check still waited for review.
  */
-export declare function noteHooksWritten(environment: NodeJS.ProcessEnv, host: TrustingHost, changed: boolean, now?: number): void;
-/** One of the host's hooks ran, which it does only once they are trusted. */
-export declare function noteHookFired(environment: NodeJS.ProcessEnv, host: TrustingHost, now?: number): void;
-/** True while the hooks last written for this host have never run in it. */
+export type HookSet = "guidance" | "push-check";
+/**
+ * The push check's entry starts Node only for a command that could push
+ * (`pushCheckCommand` in user-scope.ts), so the run that settles its mark
+ * would wait for the first push, and meanwhile the person would be told to
+ * trust hooks they already trusted. This file exists exactly while that set
+ * waits for its first run in the host, and the entry sends every command
+ * through to Node while it does.
+ */
+export declare function pushCheckAwaitingFile(environment: NodeJS.ProcessEnv, host: TrustingHost): string;
+/**
+ * This command wrote or changed one set of the host's hooks, or found it in
+ * place with no record that it ever had: either way, from now the host has to
+ * have run that set once before anybody assumes it does. `hooks` is how many
+ * hooks the set is, which the notice counts.
+ */
+export declare function noteHooksWritten(environment: NodeJS.ProcessEnv, host: TrustingHost, changed: boolean, now?: number, options?: Readonly<{
+    set?: HookSet;
+    hooks?: number;
+}>): void;
+/** This command took one set of the host's hooks out: nothing of it is left to trust. */
+export declare function noteHooksRemoved(environment: NodeJS.ProcessEnv, host: TrustingHost, set: HookSet): void;
+/** One hook of that set ran, which it does only once it is trusted. */
+export declare function noteHookFired(environment: NodeJS.ProcessEnv, host: TrustingHost, now?: number, set?: HookSet): void;
+/** True while some set of the hooks last written for this host has never run in it. */
 export declare function hooksAwaitingTrust(environment: NodeJS.ProcessEnv, host: TrustingHost): boolean;
+/** A small count the way a sentence says it. */
+export declare function countWord(count: number): string;
+/** How many of Balladeer's hooks this host was last given, over every set written. */
+export declare function hooksWritten(environment: NodeJS.ProcessEnv, host: TrustingHost): number;
 /** The host a session belongs to, from the name it gave when it said hello. */
 export declare function trustingHost(clientName: unknown): TrustingHost | undefined;
-/** What the agent is asked to pass on, once, in the host where the approval happens. */
-export declare const HOOKS_AWAITING_TRUST_NOTICE = "Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. Ask them to type /hooks in Codex and trust Balladeer's three hooks; until then Codex has Balladeer's tools without its session-start guidance or its updates.";
+/**
+ * What the agent is asked to pass on, once, in the host where the approval
+ * happens. It counts the hooks this command last wrote there, so a laptop given
+ * the push check is told to trust six and one without it four.
+ */
+export declare function hooksAwaitingTrustNotice(environment: NodeJS.ProcessEnv, host?: TrustingHost): string;

package/dist/hook-trust.js

@@ -1,9 +1,14 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { configHome } from "./store.js";
 /** Hosts that run a hook only after the person has approved it. */
 export const HOSTS_REQUIRING_TRUST = ["codex"];
+const SETS = ["guidance", "push-check"];
+/** How many hooks a set is, for a mark an earlier release wrote without saying. */
+const DEFAULT_COUNT = { guidance: 4, "push-check": 2 };
 const FILE = "hook-trust.json";
+/** The guidance set keeps the key earlier releases wrote, so their marks still count. */
+const key = (host, set) => set === "guidance" ? host : `${host}:${set}`;
 function read(environment) {
     try {
         const parsed = JSON.parse(readFileSync(join(configHome(environment), FILE), "utf8"));
@@ -15,49 +20,126 @@ function read(environment) {
         return {};
     }
 }
+/**
+ * The push check's entry starts Node only for a command that could push
+ * (`pushCheckCommand` in user-scope.ts), so the run that settles its mark
+ * would wait for the first push, and meanwhile the person would be told to
+ * trust hooks they already trusted. This file exists exactly while that set
+ * waits for its first run in the host, and the entry sends every command
+ * through to Node while it does.
+ */
+export function pushCheckAwaitingFile(environment, host) {
+    return join(configHome(environment), `${host}-push-check-awaiting-first-run`);
+}
+function forget(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        /* Left behind, it costs Node's start on each command, never a session. */
+    }
+}
 function write(environment, marks) {
     try {
         mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
         writeFileSync(join(configHome(environment), FILE), JSON.stringify(marks) + "\n", {
             mode: 0o600,
         });
+        for (const host of HOSTS_REQUIRING_TRUST) {
+            const file = pushCheckAwaitingFile(environment, host);
+            if (awaiting(marks[key(host, "push-check")]))
+                writeFileSync(file, "", { mode: 0o600 });
+            else
+                forget(file);
+        }
     }
     catch {
         /* A mark that cannot be written costs a notice, never a session. */
     }
 }
 /**
- * This command wrote or changed the host's hooks, or found them in place with
- * no record that it ever had: either way, from now the host has to have run
- * them once before anybody assumes it does.
+ * This command wrote or changed one set of the host's hooks, or found it in
+ * place with no record that it ever had: either way, from now the host has to
+ * have run that set once before anybody assumes it does. `hooks` is how many
+ * hooks the set is, which the notice counts.
  */
-export function noteHooksWritten(environment, host, changed, now = Date.now()) {
+export function noteHooksWritten(environment, host, changed, now = Date.now(), options = {}) {
+    const set = options.set ?? "guidance";
+    const marks = read(environment);
+    const mark = marks[key(host, set)];
+    const counted = options.hooks === undefined || mark?.hooks === options.hooks;
+    if (!changed && mark?.writtenAt !== undefined && counted)
+        return;
+    write(environment, {
+        ...marks,
+        [key(host, set)]: {
+            ...mark,
+            ...(changed || mark?.writtenAt === undefined ? { writtenAt: now } : {}),
+            ...(options.hooks === undefined ? {} : { hooks: options.hooks }),
+        },
+    });
+}
+/** This command took one set of the host's hooks out: nothing of it is left to trust. */
+export function noteHooksRemoved(environment, host, set) {
     const marks = read(environment);
-    if (!changed && marks[host]?.writtenAt !== undefined)
+    if (marks[key(host, set)] === undefined)
         return;
-    write(environment, { ...marks, [host]: { ...marks[host], writtenAt: now } });
+    const rest = { ...marks };
+    delete rest[key(host, set)];
+    write(environment, rest);
 }
-/** One of the host's hooks ran, which it does only once they are trusted. */
-export function noteHookFired(environment, host, now = Date.now()) {
+/** One hook of that set ran, which it does only once it is trusted. */
+export function noteHookFired(environment, host, now = Date.now(), set = "guidance") {
+    // Settled or not, a file left behind would send every command to Node for good.
+    if (set === "push-check")
+        forget(pushCheckAwaitingFile(environment, host));
     const marks = read(environment);
-    const mark = marks[host];
+    const mark = marks[key(host, set)];
     // Nothing to settle, or already settled: no write on the session's path.
     if (mark?.firedAt !== undefined && mark.firedAt >= (mark.writtenAt ?? 0))
         return;
-    write(environment, { ...marks, [host]: { ...mark, firedAt: now } });
+    write(environment, { ...marks, [key(host, set)]: { ...mark, firedAt: now } });
 }
-/** True while the hooks last written for this host have never run in it. */
-export function hooksAwaitingTrust(environment, host) {
-    const mark = read(environment)[host];
+function awaiting(mark) {
     if (mark?.writtenAt === undefined)
         return false;
     return mark.firedAt === undefined || mark.firedAt < mark.writtenAt;
 }
+/** True while some set of the hooks last written for this host has never run in it. */
+export function hooksAwaitingTrust(environment, host) {
+    const marks = read(environment);
+    return SETS.some((set) => awaiting(marks[key(host, set)]));
+}
+const WORDS = ["no", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine"];
+/** A small count the way a sentence says it. */
+export function countWord(count) {
+    return WORDS[count] ?? String(count);
+}
+/** How many of Balladeer's hooks this host was last given, over every set written. */
+export function hooksWritten(environment, host) {
+    const marks = read(environment);
+    return SETS.reduce((total, set) => {
+        const mark = marks[key(host, set)];
+        return mark?.writtenAt === undefined ? total : total + (mark.hooks ?? DEFAULT_COUNT[set]);
+    }, 0);
+}
 /** The host a session belongs to, from the name it gave when it said hello. */
 export function trustingHost(clientName) {
     return typeof clientName === "string" && clientName.toLowerCase().startsWith("codex")
         ? "codex"
         : undefined;
 }
-/** What the agent is asked to pass on, once, in the host where the approval happens. */
-export const HOOKS_AWAITING_TRUST_NOTICE = "Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. Ask them to type /hooks in Codex and trust Balladeer's three hooks; until then Codex has Balladeer's tools without its session-start guidance or its updates.";
+/**
+ * What the agent is asked to pass on, once, in the host where the approval
+ * happens. It counts the hooks this command last wrote there, so a laptop given
+ * the push check is told to trust six and one without it four.
+ */
+export function hooksAwaitingTrustNotice(environment, host = "codex") {
+    const pushCheck = read(environment)[key(host, "push-check")]?.writtenAt !== undefined;
+    const count = hooksWritten(environment, host) || DEFAULT_COUNT.guidance;
+    return ("Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. " +
+        `Ask them to type /hooks in Codex and trust Balladeer's ${countWord(count)} hooks; until then Codex has Balladeer's tools without its session-start guidance, its updates, ` +
+        (pushCheck
+            ? "the note that reminds you to tell them what Balladeer did, or its check after a push."
+            : "or the note that reminds you to tell them what Balladeer did."));
+}

package/dist/judge-brief.d.ts

@@ -1,7 +1,7 @@
 import type { BehaviorMap } from "./behavior-map-schema.js";
 import type { PromiseDocument } from "./promise-meaning.js";
 /**
- * The fixed instructions a judge works from, `judge-brief/v1`.
+ * The fixed instructions a judge works from, `judge-brief/v3`.
  *
  * One promise, one change, one disposable checkout at the change's head. The
  * rules are the contract's: cases first, linked test first, broken only with a
@@ -14,8 +14,20 @@ import type { PromiseDocument } from "./promise-meaning.js";
  * The text is a constant so a verdict can name the exact brief it was given.
  * Changing a word here is a new revision.
  */
-export declare const JUDGE_BRIEF_REVISION = "judge-brief/v1";
-export declare const JUDGE_BRIEF = "You are judging one change to this repository against one promise about the software's behavior. A named person agreed the promise's meaning. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.\n\nDecide whether this change keeps the promise, breaks it, or whether you could not tell, and back what you say with evidence you produced yourself.\n\nRules:\n\n1. Read the promise's cases first. The passing cases (passing-1, passing-2, and so on, in the order listed) say what must keep happening. The failing cases (failing-1, and so on) say what must never happen. The non-goals say what the promise does not cover; a change there is not a break.\n2. If linked tests are listed, run them first, before anything else. If the runner already reports a linked test's outcome below, use it and rerun only when you need its output.\n3. Read the code, not descriptions of it. Commit messages, comments, documentation and pull request text say what someone intended, not what the code does.\n4. Report \"broken\" only with a command that fails (exits non-zero) with this change and passes (exits zero) without it, and only after you have run it both ways yourself. To run it without the change, check out the base commit in this copy with `git checkout --detach <base>`, run the command, then return with `git checkout --detach <head>`. If the command needs a test you wrote, put that test in a new file rather than editing an existing one, so it exists on both commits. The command must run from the repository root or from the directory you name as its cwd, and must not depend on anything outside this copy.\n5. Report \"kept\" only after you have exercised each passing case against the changed code, by running a test or a command that shows it, and list every case you exercised.\n6. Anything else is \"could_not_tell\". Say in notes what stopped you: a missing dependency, a service you could not reach, a case you could not exercise, time running out.\n7. Name the promise, never the person. Do not put anyone's name, email or account in your answer.\n8. Do not push, open or merge pull requests, publish anything, or change anything outside this copy. Do not read or print credentials.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"promiseId\": \"<the promise id below>\", \"verdict\": \"kept\" | \"broken\" | \"could_not_tell\", \"reproduction\": {\"command\": \"<shell command>\", \"cwd\": \".\"} or null, \"exercisedCases\": [\"passing-1\", ...], \"notes\": \"<at most a few sentences>\"}\n\nA reproduction is required for \"broken\" and optional otherwise.";
+export declare const JUDGE_BRIEF_REVISION = "judge-brief/v3";
+/**
+ * What `judge-brief/v3` added to v1, and all it added (Robert, 30 September
+ * 2026): a way forward when the tests need something the machine lacks.
+ *
+ * It comes last among the rules and only once the judge would otherwise
+ * answer could not tell, never before it has tried to prove or refute, so it
+ * cannot spend the time a proof needs. Measured against a same-day control of
+ * v1 on 30 September (docs/agentic-testing/evidence/20260930/setup-rule.md),
+ * it proved no fewer breaks. Could not tell stays could not tell; the only new
+ * thing in the answer is `nextStep`, the one step that would let the tests run.
+ */
+export declare const JUDGE_BRIEF_SETUP_RULE = "9. Only when you would otherwise answer \"could_not_tell\" because the tests need something this machine does not have, such as a test database, a running service, a browser or an environment variable, and only after you have tried to show a break or a keep as the rules above say: look for how the repository documents running its tests, in its README, its agent instruction files (AGENTS.md, CLAUDE.md and the like) and its package scripts, and try the steps it documents. Take no step it does not document, and even among those never install system software, and never ask for or read credentials. If the tests then run, carry on under the rules above. If they still cannot run, or trying would leave no time to answer, the answer stays \"could_not_tell\", never \"kept\", and you add \"nextStep\" to your JSON answer: the one step that would let the tests run, written so the person's agent can act on it, such as the exact documented command that starts the test database. Otherwise leave nextStep out.";
+export declare const JUDGE_BRIEF = "You are judging one change to this repository against one promise about the software's behavior. A named person agreed the promise's meaning. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.\n\nDecide whether this change keeps the promise, breaks it, or whether you could not tell, and back what you say with evidence you produced yourself.\n\nRules:\n\n1. Read the promise's cases first. The passing cases (passing-1, passing-2, and so on, in the order listed) say what must keep happening. The failing cases (failing-1, and so on) say what must never happen. The non-goals say what the promise does not cover; a change there is not a break.\n2. If linked tests are listed, run them first, before anything else. If the runner already reports a linked test's outcome below, use it and rerun only when you need its output.\n3. Read the code, not descriptions of it. Commit messages, comments, documentation and pull request text say what someone intended, not what the code does.\n4. Report \"broken\" only with a command that fails (exits non-zero) with this change and passes (exits zero) without it, and only after you have run it both ways yourself. To run it without the change, check out the base commit in this copy with `git checkout --detach <base>`, run the command, then return with `git checkout --detach <head>`. If the command needs a test you wrote, put that test in a new file rather than editing an existing one, so it exists on both commits. The command must run from the repository root or from the directory you name as its cwd, and must not depend on anything outside this copy.\n5. Report \"kept\" only after you have exercised each passing case against the changed code, by running a test or a command that shows it, and list every case you exercised.\n6. Anything else is \"could_not_tell\". Say in notes what stopped you: a missing dependency, a service you could not reach, a case you could not exercise, time running out.\n7. Name the promise, never the person. Do not put anyone's name, email or account in your answer.\n8. Do not push, open or merge pull requests, publish anything, or change anything outside this copy. Do not read or print credentials.\n9. Only when you would otherwise answer \"could_not_tell\" because the tests need something this machine does not have, such as a test database, a running service, a browser or an environment variable, and only after you have tried to show a break or a keep as the rules above say: look for how the repository documents running its tests, in its README, its agent instruction files (AGENTS.md, CLAUDE.md and the like) and its package scripts, and try the steps it documents. Take no step it does not document, and even among those never install system software, and never ask for or read credentials. If the tests then run, carry on under the rules above. If they still cannot run, or trying would leave no time to answer, the answer stays \"could_not_tell\", never \"kept\", and you add \"nextStep\" to your JSON answer: the one step that would let the tests run, written so the person's agent can act on it, such as the exact documented command that starts the test database. Otherwise leave nextStep out.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"promiseId\": \"<the promise id below>\", \"verdict\": \"kept\" | \"broken\" | \"could_not_tell\", \"reproduction\": {\"command\": \"<shell command>\", \"cwd\": \".\"} or null, \"exercisedCases\": [\"passing-1\", ...], \"notes\": \"<at most a few sentences>\"}\n\nA reproduction is required for \"broken\" and optional otherwise.";
 export type JudgeBriefInput = Readonly<{
     promise: PromiseDocument;
     map?: BehaviorMap;

package/dist/judge-brief.js

@@ -1,5 +1,5 @@
 /**
- * The fixed instructions a judge works from, `judge-brief/v1`.
+ * The fixed instructions a judge works from, `judge-brief/v3`.
  *
  * One promise, one change, one disposable checkout at the change's head. The
  * rules are the contract's: cases first, linked test first, broken only with a
@@ -12,7 +12,19 @@
  * The text is a constant so a verdict can name the exact brief it was given.
  * Changing a word here is a new revision.
  */
-export const JUDGE_BRIEF_REVISION = "judge-brief/v1";
+export const JUDGE_BRIEF_REVISION = "judge-brief/v3";
+/**
+ * What `judge-brief/v3` added to v1, and all it added (Robert, 30 September
+ * 2026): a way forward when the tests need something the machine lacks.
+ *
+ * It comes last among the rules and only once the judge would otherwise
+ * answer could not tell, never before it has tried to prove or refute, so it
+ * cannot spend the time a proof needs. Measured against a same-day control of
+ * v1 on 30 September (docs/agentic-testing/evidence/20260930/setup-rule.md),
+ * it proved no fewer breaks. Could not tell stays could not tell; the only new
+ * thing in the answer is `nextStep`, the one step that would let the tests run.
+ */
+export const JUDGE_BRIEF_SETUP_RULE = `9. Only when you would otherwise answer "could_not_tell" because the tests need something this machine does not have, such as a test database, a running service, a browser or an environment variable, and only after you have tried to show a break or a keep as the rules above say: look for how the repository documents running its tests, in its README, its agent instruction files (AGENTS.md, CLAUDE.md and the like) and its package scripts, and try the steps it documents. Take no step it does not document, and even among those never install system software, and never ask for or read credentials. If the tests then run, carry on under the rules above. If they still cannot run, or trying would leave no time to answer, the answer stays "could_not_tell", never "kept", and you add "nextStep" to your JSON answer: the one step that would let the tests run, written so the person's agent can act on it, such as the exact documented command that starts the test database. Otherwise leave nextStep out.`;
 export const JUDGE_BRIEF = `You are judging one change to this repository against one promise about the software's behavior. A named person agreed the promise's meaning. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.
 
 Decide whether this change keeps the promise, breaks it, or whether you could not tell, and back what you say with evidence you produced yourself.
@@ -27,6 +39,7 @@ Rules:
 6. Anything else is "could_not_tell". Say in notes what stopped you: a missing dependency, a service you could not reach, a case you could not exercise, time running out.
 7. Name the promise, never the person. Do not put anyone's name, email or account in your answer.
 8. Do not push, open or merge pull requests, publish anything, or change anything outside this copy. Do not read or print credentials.
+${JUDGE_BRIEF_SETUP_RULE}
 
 Your final message must be exactly one JSON object and nothing after it:
 

package/dist/judge-hook.d.ts

@@ -1,20 +1,30 @@
 /**
- * Where a judge run starts: a coding host's PreToolUse hook, or git's own
- * pre-push hook.
+ * Where a judge run starts: a coding host's hook around a shell command, or
+ * git's own pre-push hook.
  *
- * The host hook fires on every shell command the agent runs, so the first job
- * is to say "not a push" and get out of the way in milliseconds. Only `git
- * push`, `gh pr create` and `gh pr merge` go further. The command is read the
- * way a shell reads it, so a push inside a quoted commit message is not a push
- * and `git stash push` is not one either.
+ * The host hook fires on every shell command the agent runs, twice: before it
+ * runs (PreToolUse) and after (PostToolUse). The first job each time is to say
+ * "not a push" and get out of the way in milliseconds. Only `git push`, `gh pr
+ * create` and `gh pr merge` go further. The command is read the way a shell
+ * reads it, so a push inside a quoted commit message is not a push and `git
+ * stash push` is not one either.
+ *
+ * Report mode judges after the push, so the push is never held and the check
+ * sees exactly what was pushed. Block mode judges before it, because a push
+ * can only be held before it runs.
  */
 export type HookHost = "claude" | "codex" | "git";
+/** The two host events the judge is installed on, in the order a command meets them. */
+export type HookEvent = "PreToolUse" | "PostToolUse";
+export declare const JUDGE_HOOK_EVENTS: readonly HookEvent[];
 export type HookInput = Readonly<{
     eventName?: string;
     toolName?: string;
     command?: string;
     cwd?: string;
     model?: string;
+    /** The host's session, from `session_id`, which both Claude Code and Codex send. */
+    sessionId?: string;
 }>;
 /** A coding host's hook payload, or nothing when the text is not one. */
 export declare function parseHookInput(text: string): HookInput | undefined;
@@ -26,17 +36,118 @@ export type PushedRef = Readonly<{
     remoteSha: string;
 }>;
 export declare function parsePrePushInput(text: string): PushedRef[];
+/** What separates or groups commands in a shell line. */
+export type ShellOperator = ";" | "&&" | "||" | "|" | "&" | "\n" | "(" | ")" | "`";
+/** One piece of a shell line: a simple command's words, or what comes between commands. */
+export type ShellPiece = Readonly<{
+    kind: "command";
+    words: readonly string[];
+}> | Readonly<{
+    kind: "operator";
+    operator: ShellOperator;
+}>;
 /**
- * The simple commands a shell line runs, as word lists.
+ * A shell line in the order a shell reads it: simple commands and the
+ * operators between them.
+ *
+ * Quotes and backslashes are honored, so quoted text stays one word. `;`,
+ * `&&`, `||`, `|`, `&`, newlines, parentheses and backquotes come between
+ * commands. A comment runs to the end of its line. A redirection (`>`, `2>&1`,
+ * `<file`, `&>log`) and its target are left out of the command's words.
  *
- * Quotes and backslashes are honored, so quoted text stays one word; `;`,
- * `&&`, `||`, `|`, `&`, newlines and parentheses end a command, so `npm test
- * && git push` is two commands and `$(git push)` is found. A comment runs to
- * the end of its line.
+ * A here-document (`<<WORD`, `<<'WORD'`, `<<"WORD"`, `<<-WORD`) is data: the
+ * lines after its command, up to a line that is exactly WORD (leading tabs
+ * removed for `<<-`), are not commands. A here-string's word (`<<<`) is data
+ * too. Two exceptions keep a push inside one from going unseen: text fed to a
+ * shell that reads its script from input (`bash <<EOF`, `cat <<EOF | sh`) is
+ * read as that script, and the `$(...)` and backquotes in a here-document
+ * whose delimiter is not quoted are read as the commands the shell runs while
+ * expanding it. Either is read as a subshell, after the pipeline it feeds. A
+ * here-document that never reaches its delimiter line is not taken as one, so
+ * the lines after it are still read as commands.
+ */
+export declare function scanShell(line: string, depth?: number): ShellPiece[];
+/**
+ * The simple commands a shell line runs, as word lists, in the order
+ * `scanShell` reads them: `npm test && git push` is two commands, `$(git
+ * push)` is found, and a here-document's text is not a command.
  */
 export declare function shellCommands(line: string): string[][];
+/** Where one push, pull request creation or merge in a shell line runs. */
+export type PushSite = Readonly<{
+    kind: "push" | "create" | "merge";
+    /** The absolute directory it runs in; absent when that cannot be told for certain. */
+    directory?: string;
+    /** The repository a pull request command names with `--repo`, `-R` or `GH_REPO`. */
+    repo?: string;
+}>;
+/**
+ * Every push, pull request creation and merge in a shell line, with the
+ * directory it runs in when that can be told for certain.
+ *
+ * Starting from `cwd`, each `cd` moves the line along in order, and a git
+ * command's own `-C` options apply to that command alone. A `cd` inside
+ * parentheses, backquotes or `$(...)` ends with them. Anything that makes the
+ * directory uncertain makes it unknown from there on rather than guessed: `cd`
+ * with no directory, `cd -`, a variable or pattern, `pushd` or `popd`, a `cd`
+ * in a pipeline or in the background, a `cd` inside `if`, a loop, `case` or a
+ * function, and a `cd` that ran only when an earlier command succeeded or
+ * failed, once the line goes past its `&&` chain. A shell's `-c` script starts
+ * where the shell does and moves nothing outside it.
+ */
+export declare function pushSites(line: string, cwd: string | undefined, depth?: number): PushSite[];
+/** Where a shell line's pushes run, when that is one directory that can be told for certain. */
+export type PushPlace = Readonly<{
+    known: true;
+    directory: string;
+    sites: readonly PushSite[];
+}> | Readonly<{
+    known: false;
+}>;
+/**
+ * The one directory a shell line's pushes run in, starting from `cwd`, or
+ * unknown when any of them cannot be told or they run in more than one.
+ */
+export declare function pushPlace(line: string, cwd: string): PushPlace;
+/**
+ * A repository as `owner/name` in lower case, from a remote URL or a `--repo`
+ * value: `https://github.com/o/r.git`, `git@github.com:o/r.git`,
+ * `ssh://git@host/o/r`, `HOST/o/r` or `o/r`. Nothing when there is no owner.
+ */
+export declare function repositoryName(reference: string): string | undefined;
+/** The repositories a checkout's remotes point at, from what `git remote -v` prints. */
+export declare function remoteRepositoryNames(listing: string): Set<string>;
 /** Whether a shell line pushes: `git push`, `gh pr create`, or `gh pr merge`, anywhere in it. */
-export declare function isPushCommand(line: string, depth?: number): boolean;
+export declare function isPushCommand(line: string): boolean;
+/**
+ * Whether a shell line sends this checkout's commits: a `git push`, or a `gh pr
+ * create`, which pushes the branch it opens a pull request for. A line whose
+ * only push is `gh pr merge` sends none; that pull request's commits were on
+ * the remote before the line ran.
+ */
+export declare function sendsCommits(line: string): boolean;
+/**
+ * The first command in the line that makes a commit before it pushes, as
+ * `git <subcommand>`, or nothing.
+ *
+ * A host's PreToolUse hook sees the checkout before the line runs, so in
+ * `git commit -am x && git push` the check judges the code as it was before
+ * the commit, and the commit the push carries is one it never saw. Only a
+ * commit made before the push matters: one made after it is not in what was
+ * pushed, and `gh pr merge` merges a pull request's head, not this checkout's.
+ */
+export declare function commitBeforePush(line: string): string | undefined;
+/**
+ * What a `gh pr merge` names. Neither field means the current branch's pull
+ * request, which is the change in this checkout; either one can name a pull
+ * request whose change is somewhere else entirely.
+ */
+export type MergeTarget = Readonly<{
+    selector?: string;
+    repo?: string;
+}>;
+/** Every `gh pr merge` in a shell line, with the pull request and repository it names. */
+export declare function mergeTargets(line: string): MergeTarget[];
 export type HookResponse = Readonly<{
     stdout: string;
     stderr: string;
@@ -47,11 +158,14 @@ export type HookResponse = Readonly<{
  * and the push goes ahead; a block is exit 2 with the reason, which both hosts
  * treat as a refusal of that one command. Claude Code also gets the reason as
  * `permissionDecision: "deny"`, which it prefers to stderr; Codex is given the
- * stderr form its documentation names.
+ * stderr form its documentation names. After the command ran (PostToolUse)
+ * there is nothing left to hold, so the lines are only ever context, named for
+ * the event that asked.
  */
 export declare function hookResponse(host: HookHost, outcome: Readonly<{
     block: boolean;
     lines: readonly string[];
+    event?: HookEvent;
 }>): HookResponse;
 /** The status line both hosts show while the hook runs, and the mark of the entry this command owns. */
 export declare const JUDGE_HOOK_MARKER = "Balladeer judge";
@@ -78,7 +192,67 @@ export type HookInstallResult = Readonly<{
     status: "written" | "unchanged" | "refused";
     reason?: string;
 }>;
+/** The hook file the installer writes for a host, relative to the repository root. */
+export declare function judgeHookFile(host: "claude" | "codex"): string;
+/**
+ * Whether the hook file the installer writes has this command's entry for one
+ * event. It reads the file rather than guessing, so a checkout installed by an
+ * earlier release, which wrote only the PreToolUse entry, is told apart from a
+ * current one. Anything unreadable counts as no entry.
+ */
+export declare function hasJudgeEntry(root: string, host: "claude" | "codex", event: HookEvent): boolean;
+/**
+ * Whether this checkout has the push check's own project entry for a host,
+ * under either event. Where it does, that entry owns the check in this
+ * checkout and the one setup writes at the host's user scope stands aside, so
+ * a push is judged once. Either event counts: a checkout an earlier release
+ * installed has only the entry before the push, and it keeps judging there.
+ */
+export declare function hasProjectJudgeHook(root: string, host: "claude" | "codex"): boolean;
+/**
+ * The checkout that holds a folder, found by walking up to its `.git` entry (a
+ * directory, or a file in a worktree). No process is started, so a folder that
+ * is not in a checkout at all is known in well under a millisecond.
+ */
+export declare function checkoutRoot(start: string): string | undefined;
+/**
+ * The push check's switch for this laptop, in Balladeer's own config home.
+ * Absent means on. Written only by `balladeer judge --push-check off`, and
+ * read by the user-scope entry on each push, so turning it off takes effect in
+ * sessions that are already open.
+ */
+export declare const PUSH_CHECK_SETTING_FILE = "push-check.json";
+export declare function pushCheckSettingPath(environment: NodeJS.ProcessEnv): string;
+/** True only when this laptop's switch says off; anything unreadable leaves it on. */
+export declare function pushCheckOff(environment: NodeJS.ProcessEnv): boolean;
+/** Turn the user-scope push check off or back on for this laptop. */
+export declare function setPushCheck(environment: NodeJS.ProcessEnv, on: boolean): void;
 /** Where git looks for hooks in this checkout, which is not `.git/hooks` in a worktree. */
 export declare function gitHooksDirectory(root: string): string;
 /** Install the judge hook for one host. Running it twice changes nothing the second time. */
 export declare function installJudgeHook(root: string, target: HookHost): HookInstallResult;
+/**
+ * Whether a commit is on a remote now: reachable from a remote-tracking ref,
+ * or else the tip of a branch some remote reports.
+ *
+ * `git push`, `git push origin HEAD:branch` and the push `gh pr create` makes
+ * all move the remote-tracking ref of what they pushed, so the first check is
+ * local and immediate. The second is there because a push can land without
+ * that ref moving: Codex's workspace sandbox keeps `.git` read-only, so its
+ * pushes reach the remote and then fail to update `refs/remotes/...` (hook
+ * canary, 29 September 2026). Asking each remote for its branch tips settles
+ * it without fetching anything, and a push that failed leaves its commit on
+ * neither.
+ */
+export declare function pushLanded(root: string, sha: string): Promise<boolean>;
+/**
+ * Where the remote default branch stood before this push, when this push is
+ * what moved it to `head`; otherwise nothing, and the ordinary fork-point rule
+ * applies.
+ *
+ * Judged after a push straight to the default branch, the fork point with that
+ * branch's remote-tracking ref is `head` itself, so the change would shrink to
+ * its last commit. git records the push in the ref's reflog ("update by
+ * push"), and the entry before it is where the branch stood.
+ */
+export declare function baseBeforePush(root: string, head: string): Promise<string | undefined>;