balladeer 1.0.16 → 1.0.17

package/dist/judge-hook.js

@@ -1,7 +1,13 @@
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
-import { basename, dirname, isAbsolute, join } from "node:path";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { runCommand } from "./gh.js";
+import { resolveCommit } from "./scratch-worktree.js";
+import { configHome } from "./store.js";
+export const JUDGE_HOOK_EVENTS = ["PreToolUse", "PostToolUse"];
+/** A session id as the hook keeps it: a bounded name, never a path or a sentence. */
+const SESSION_ID = /^[A-Za-z0-9._:-]{1,128}$/;
 /** A coding host's hook payload, or nothing when the text is not one. */
 export function parseHookInput(text) {
     let value;
@@ -22,6 +28,9 @@ export function parseHookInput(text) {
         ...(command === undefined ? {} : { command }),
         ...(typeof input.cwd === "string" ? { cwd: input.cwd } : {}),
         ...(typeof input.model === "string" ? { model: input.model } : {}),
+        ...(typeof input.session_id === "string" && SESSION_ID.test(input.session_id)
+            ? { sessionId: input.session_id }
+            : {}),
     };
 }
 const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
@@ -49,16 +58,130 @@ export function parsePrePushInput(text) {
     }
     return refs;
 }
+/** What ends a shell word outside quotes. */
+const WORD_END = /[\s;&|()<>`]/;
 /**
- * The simple commands a shell line runs, as word lists.
+ * One word read the way a shell reads it, starting at `from`: quotes and
+ * backslashes honored and removed. `quoted` says whether any part was quoted
+ * or escaped, which is what makes a here-document's text literal.
+ */
+function readWord(line, from) {
+    let text = "";
+    let quoted = false;
+    let at = from;
+    while (at < line.length && !WORD_END.test(line[at])) {
+        const char = line[at];
+        if (char === "'") {
+            quoted = true;
+            const close = line.indexOf("'", at + 1);
+            const end = close < 0 ? line.length : close;
+            text += line.slice(at + 1, end);
+            at = end + 1;
+        }
+        else if (char === '"') {
+            quoted = true;
+            at += 1;
+            while (at < line.length && line[at] !== '"') {
+                if (line[at] === "\\" && at + 1 < line.length)
+                    at += 1;
+                text += line[at];
+                at += 1;
+            }
+            at += 1;
+        }
+        else if (char === "\\") {
+            quoted = true;
+            if (at + 1 < line.length && line[at + 1] !== "\n")
+                text += line[at + 1];
+            at += 2;
+        }
+        else {
+            text += char;
+            at += 1;
+        }
+    }
+    return { text, end: Math.min(at, line.length), quoted };
+}
+function skipBlanks(line, from) {
+    let at = from;
+    while (at < line.length && (line[at] === " " || line[at] === "\t"))
+        at += 1;
+    return at;
+}
+/**
+ * Whether a command reads a script from its input: a shell given no `-c`
+ * script and no script file, as in `bash <<EOF` or `... | sh`.
+ */
+function readsScriptFromInput(words) {
+    const run = program(words);
+    if (run.length === 0 || !SHELLS.has(basename(run[0])))
+        return false;
+    const args = run.slice(1);
+    if (args.some((word) => /^-[a-z]*c[a-z]*$/.test(word)))
+        return false;
+    const operand = args.findIndex((word) => !word.startsWith("-"));
+    return operand < 0 || args.slice(0, operand).includes("-s");
+}
+/**
+ * The command substitutions in a here-document whose delimiter is not quoted,
+ * `$(...)` and backquotes, which the shell runs while it reads the text. The
+ * rest of the text is data.
+ */
+function substitutions(body) {
+    const found = [];
+    for (let at = 0; at < body.length; at += 1) {
+        const char = body[at];
+        if (char === "\\") {
+            at += 1;
+        }
+        else if (char === "$" && body[at + 1] === "(" && body[at + 2] !== "(") {
+            let depth = 1;
+            let end = at + 2;
+            while (end < body.length && depth > 0) {
+                if (body[end] === "(")
+                    depth += 1;
+                else if (body[end] === ")")
+                    depth -= 1;
+                if (depth > 0)
+                    end += 1;
+            }
+            found.push(body.slice(at + 2, end));
+            at = end;
+        }
+        else if (char === "`") {
+            let end = at + 1;
+            while (end < body.length && body[end] !== "`")
+                end += body[end] === "\\" ? 2 : 1;
+            found.push(body.slice(at + 1, end));
+            at = end;
+        }
+    }
+    return found;
+}
+/**
+ * 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 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.
+ * 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.
+ *
+ * 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 function shellCommands(line) {
-    const commands = [];
+export function scanShell(line, depth = 0) {
+    const pieces = [];
+    const fed = [];
+    const pending = [];
     let words = [];
     let word = "";
     let inWord = false;
@@ -71,17 +194,62 @@ export function shellCommands(line) {
     const endCommand = () => {
         endWord();
         if (words.length > 0)
-            commands.push(words);
+            pieces.push({ kind: "command", words });
         words = [];
     };
-    for (let at = 0; at < line.length; at += 1) {
+    const operator = (value) => {
+        endCommand();
+        pieces.push({ kind: "operator", operator: value });
+    };
+    /** The bodies of the here-documents waiting on the line that just ended, from `from`. */
+    const hereDocuments = (from) => {
+        let at = from;
+        while (pending.length > 0) {
+            const document = pending[0];
+            const lines = [];
+            let cursor = at;
+            let after = -1;
+            for (;;) {
+                const newline = line.indexOf("\n", cursor);
+                const stop = newline < 0 ? line.length : newline;
+                const text = document.stripTabs
+                    ? line.slice(cursor, stop).replace(/^\t+/, "")
+                    : line.slice(cursor, stop);
+                if (text === document.delimiter) {
+                    after = newline < 0 ? line.length : newline + 1;
+                    break;
+                }
+                lines.push(text);
+                if (newline < 0)
+                    break;
+                cursor = newline + 1;
+            }
+            if (after < 0) {
+                // Never closed: read what follows as commands rather than hide it.
+                pending.length = 0;
+                break;
+            }
+            pending.shift();
+            fed.push({
+                index: document.index,
+                body: lines.join("\n"),
+                expands: document.expands,
+                order: fed.length,
+            });
+            at = after;
+        }
+        return at;
+    };
+    let at = 0;
+    while (at < line.length) {
         const char = line[at];
+        const next = line[at + 1];
         if (char === "'") {
             const close = line.indexOf("'", at + 1);
             const end = close < 0 ? line.length : close;
             word += line.slice(at + 1, end);
             inWord = true;
-            at = end;
+            at = end + 1;
         }
         else if (char === '"') {
             inWord = true;
@@ -92,33 +260,412 @@ export function shellCommands(line) {
                 word += line[at];
                 at += 1;
             }
+            at += 1;
         }
         else if (char === "\\") {
-            if (at + 1 < line.length && line[at + 1] !== "\n")
-                word += line[at + 1];
-            inWord = true;
-            at += 1;
+            // A backslash before a newline joins two lines and adds nothing.
+            if (next !== undefined && next !== "\n") {
+                word += next;
+                inWord = true;
+            }
+            at += 2;
         }
         else if (char === "#" && !inWord) {
             const end = line.indexOf("\n", at);
-            at = end < 0 ? line.length : end - 1;
+            at = end < 0 ? line.length : end;
+        }
+        else if (char === "\n") {
+            operator("\n");
+            at = hereDocuments(at + 1);
         }
         else if (/\s/.test(char)) {
-            if (char === "\n")
-                endCommand();
+            endWord();
+            at += 1;
+        }
+        else if (char === "<" && next === "<" && line[at + 2] === "<") {
+            endWord();
+            const data = readWord(line, skipBlanks(line, at + 3));
+            fed.push({ index: pieces.length, body: data.text, expands: false, order: fed.length });
+            at = data.end;
+        }
+        else if (char === "<" && next === "<") {
+            endWord();
+            let from = at + 2;
+            const stripTabs = line[from] === "-";
+            if (stripTabs)
+                from += 1;
+            from = skipBlanks(line, from);
+            const delimiter = readWord(line, from);
+            if (delimiter.end > from)
+                pending.push({
+                    delimiter: delimiter.text,
+                    stripTabs,
+                    expands: !delimiter.quoted,
+                    index: pieces.length,
+                });
+            at = delimiter.end;
+        }
+        else if ((char === "<" || char === ">") && next === "(") {
+            // Process substitution: the parenthesis opens a command of its own.
+            endWord();
+            at += 1;
+        }
+        else if (char === "<" || char === ">" || (char === "&" && next === ">")) {
+            // A number written straight before the operator is the descriptor it redirects.
+            if (inWord && /^\d+$/.test(word)) {
+                word = "";
+                inWord = false;
+            }
             else
                 endWord();
+            let from = at + (char === "&" ? 2 : 1);
+            if (line[from] === ">" || line[from] === "&" || line[from] === "|")
+                from += 1;
+            else if (char === "<" && line[from] === ">")
+                from += 1;
+            at = readWord(line, skipBlanks(line, from)).end;
+        }
+        else if (char === "&" && next === "&") {
+            operator("&&");
+            at += 2;
         }
-        else if (";&|()`".includes(char)) {
-            endCommand();
+        else if (char === "|" && next === "|") {
+            operator("||");
+            at += 2;
+        }
+        else if (char === "|") {
+            operator("|");
+            at += next === "&" ? 2 : 1;
+        }
+        else if (char === "&" || char === ";" || char === "(" || char === ")" || char === "`") {
+            operator(char);
+            at += 1;
         }
         else {
             word += char;
             inWord = true;
+            at += 1;
         }
     }
     endCommand();
-    return commands;
+    if (depth >= 3)
+        return pieces;
+    // Text read as commands goes in as a subshell after the pipeline it feeds,
+    // latest first so the earlier positions stay where they are.
+    const isPipe = (piece) => piece?.kind === "operator" && piece.operator === "|";
+    const placed = fed
+        .filter((entry) => pieces[entry.index]?.kind === "command")
+        .map((entry) => {
+        let start = entry.index;
+        let end = entry.index;
+        while (start >= 2 && isPipe(pieces[start - 1]) && pieces[start - 2]?.kind === "command")
+            start -= 2;
+        while (isPipe(pieces[end + 1]) && pieces[end + 2]?.kind === "command")
+            end += 2;
+        const pipeline = pieces
+            .slice(start, end + 1)
+            .flatMap((piece) => (piece.kind === "command" ? [piece.words] : []));
+        const scripts = pipeline.some(readsScriptFromInput)
+            ? [entry.body]
+            : entry.expands
+                ? substitutions(entry.body)
+                : [];
+        return { end, order: entry.order, scripts };
+    })
+        .sort((a, b) => b.end - a.end || b.order - a.order);
+    for (const { end, scripts } of placed) {
+        const inserted = scripts.flatMap((script) => [
+            { kind: "operator", operator: "(" },
+            ...scanShell(script, depth + 1),
+            { kind: "operator", operator: ")" },
+        ]);
+        pieces.splice(end + 1, 0, ...inserted);
+    }
+    return pieces;
+}
+/**
+ * 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 function shellCommands(line) {
+    return scanShell(line).flatMap((piece) => (piece.kind === "command" ? [[...piece.words]] : []));
+}
+/** Words that group commands or negate one; the command is what follows them. */
+const GROUPING = new Set(["{", "}", "!"]);
+/** Words after which a command runs only sometimes, repeatedly, or later. */
+const BRANCHING = new Set([
+    "if",
+    "then",
+    "elif",
+    "else",
+    "fi",
+    "for",
+    "while",
+    "until",
+    "do",
+    "done",
+    "case",
+    "esac",
+    "select",
+    "function",
+]);
+/**
+ * A directory a command names, taken from `from`, or nothing when it cannot
+ * be told for certain: a variable, a pattern, another user's home, or a
+ * starting point that is itself unknown.
+ */
+function directoryFrom(from, named) {
+    if (from === undefined || named === "" || /[$`*?[]/.test(named))
+        return undefined;
+    let path = named;
+    if (path === "~" || path.startsWith("~/")) {
+        const home = process.env.HOME;
+        if (!home || !isAbsolute(home))
+            return undefined;
+        path = join(home, path.slice(1));
+    }
+    else if (path.startsWith("~"))
+        return undefined;
+    const joined = isAbsolute(path) ? join(path) : join(from, path);
+    return joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
+}
+/** Where `cd` with these arguments goes. `cd`, `cd -` and `cd a b` cannot be told. */
+function cdTarget(from, args) {
+    let at = 0;
+    while (at < args.length && /^-[LPe@]+$/.test(args[at]))
+        at += 1;
+    if (args[at] === "--")
+        at += 1;
+    const rest = args.slice(at);
+    if (rest.length !== 1 || rest[0] === "-")
+        return undefined;
+    return directoryFrom(from, rest[0]);
+}
+/** Where a git command runs after its `-C` options; `--git-dir` and `--work-tree` cannot be told. */
+function gitDirectory(from, args) {
+    let here = from;
+    for (let at = 0; at < args.length; at += 1) {
+        const word = args[at];
+        if (/^--(git-dir|work-tree)(=|$)/.test(word))
+            return undefined;
+        if (word === "-C") {
+            const named = args[at + 1];
+            if (named === undefined)
+                return undefined;
+            if (named !== "")
+                here = directoryFrom(here, named);
+            at += 1;
+        }
+        else if (GIT_VALUE_OPTIONS.has(word))
+            at += 1;
+        else if (!word.startsWith("-"))
+            break;
+    }
+    return here;
+}
+/** `gh pr create` options that take the next word as their value. */
+const GH_CREATE_VALUE_OPTIONS = new Set([
+    "-a",
+    "--assignee",
+    "-B",
+    "--base",
+    "-b",
+    "--body",
+    "-F",
+    "--body-file",
+    "-H",
+    "--head",
+    "-l",
+    "--label",
+    "-m",
+    "--milestone",
+    "-p",
+    "--project",
+    "-R",
+    "--repo",
+    "-r",
+    "--reviewer",
+    "-T",
+    "--template",
+    "-t",
+    "--title",
+    "--recover",
+]);
+function createRepo(args) {
+    let repo;
+    for (let at = 0; at < args.length; at += 1) {
+        const word = args[at];
+        if (word === "--")
+            break;
+        if (word.startsWith("--repo="))
+            repo = word.slice("--repo=".length);
+        else if (GH_CREATE_VALUE_OPTIONS.has(word)) {
+            if (word === "-R" || word === "--repo")
+                repo = args[at + 1];
+            at += 1;
+        }
+    }
+    return repo;
+}
+/**
+ * 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 function pushSites(line, cwd, depth = 0) {
+    const pieces = scanShell(line);
+    const sites = [];
+    const saved = [];
+    let here = cwd;
+    // Set after a `cd` that ran only when an earlier command succeeded or
+    // failed: it holds along its own `&&` chain and not past it.
+    let conditional = false;
+    let backquoted = false;
+    let branching = false;
+    const restore = () => {
+        const frame = saved.pop();
+        here = frame === undefined ? undefined : frame.here;
+        conditional = frame === undefined ? false : frame.conditional;
+    };
+    const operatorAt = (index) => {
+        const piece = pieces[index];
+        return piece?.kind === "operator" ? piece.operator : undefined;
+    };
+    for (let index = 0; index < pieces.length; index += 1) {
+        const piece = pieces[index];
+        if (piece.kind === "operator") {
+            const value = piece.operator;
+            if (value === "(") {
+                // `name()` defines a function, whose body runs later if at all.
+                if (operatorAt(index + 1) === ")")
+                    branching = true;
+                saved.push({ here, conditional });
+                conditional = false;
+            }
+            else if (value === ")")
+                restore();
+            else if (value === "`") {
+                if (backquoted)
+                    restore();
+                else {
+                    saved.push({ here, conditional });
+                    conditional = false;
+                }
+                backquoted = !backquoted;
+            }
+            else if (value !== "&&" && conditional) {
+                here = undefined;
+                conditional = false;
+            }
+            continue;
+        }
+        let start = 0;
+        while (start < piece.words.length) {
+            const word = piece.words[start];
+            if (BRANCHING.has(word))
+                branching = true;
+            else if (!GROUPING.has(word))
+                break;
+            start += 1;
+        }
+        const words = piece.words.slice(start);
+        const run = program(words);
+        if (run.length === 0)
+            continue;
+        const prefix = words.slice(0, words.length - run.length);
+        const name = basename(run[0]);
+        const before = operatorAt(index - 1);
+        const after = operatorAt(index + 1);
+        if (name === "cd") {
+            if (branching || before === "|" || after === "|" || after === "&")
+                here = undefined;
+            else {
+                here = cdTarget(here, run.slice(1));
+                if (before === "&&" || before === "||")
+                    conditional = true;
+            }
+        }
+        else if (name === "pushd" || name === "popd")
+            here = undefined;
+        else if (name === "git" && gitSubcommand(run.slice(1)) === "push") {
+            const directory = prefix.some((word) => /^GIT_(DIR|WORK_TREE)=/.test(word))
+                ? undefined
+                : gitDirectory(here, run.slice(1));
+            sites.push({ kind: "push", ...(directory === undefined ? {} : { directory }) });
+        }
+        else if (name === "gh" && run[1] === "pr" && (run[2] === "create" || run[2] === "merge")) {
+            const named = (run[2] === "merge" ? mergeTarget(run.slice(3)).repo : createRepo(run.slice(3))) ??
+                prefix.find((word) => word.startsWith("GH_REPO="))?.slice("GH_REPO=".length);
+            const directory = named !== undefined && /[$`]/.test(named) ? undefined : here;
+            sites.push({
+                kind: run[2],
+                ...(directory === undefined ? {} : { directory }),
+                ...(named ? { repo: named } : {}),
+            });
+        }
+        else if (SHELLS.has(name) && depth < 3) {
+            const flag = run.findIndex((word, at) => at > 0 && /^-[a-z]*c[a-z]*$/.test(word));
+            const script = flag > 0 ? run[flag + 1] : undefined;
+            if (script !== undefined)
+                sites.push(...pushSites(script, here, depth + 1));
+        }
+    }
+    return sites;
+}
+/**
+ * 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 function pushPlace(line, cwd) {
+    const sites = pushSites(line, cwd);
+    if (sites.length === 0)
+        return { known: true, directory: cwd, sites };
+    const directories = new Set(sites.map((site) => site.directory));
+    const [directory] = directories;
+    if (directories.size !== 1 || directory === undefined)
+        return { known: false };
+    return { known: true, directory, sites };
+}
+/**
+ * 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 function repositoryName(reference) {
+    let path = reference.trim();
+    const url = /^[a-z][a-z0-9+.-]*:\/\/[^/]*(\/.*)?$/i.exec(path);
+    const scp = url === null ? /^(?:[^/@:\s]+@)?[^/:\s]+:(.*)$/.exec(path) : null;
+    if (url !== null)
+        path = url[1] ?? "";
+    else if (scp !== null)
+        path = scp[1] ?? "";
+    const segments = path
+        .replace(/\/+$/, "")
+        .replace(/\.git$/i, "")
+        .split("/")
+        .filter(Boolean);
+    return segments.length < 2 ? undefined : segments.slice(-2).join("/").toLowerCase();
+}
+/** The repositories a checkout's remotes point at, from what `git remote -v` prints. */
+export function remoteRepositoryNames(listing) {
+    const names = new Set();
+    for (const line of listing.split("\n")) {
+        const url = line.trim().split(/\s+/)[1];
+        const name = url === undefined ? undefined : repositoryName(url);
+        if (name !== undefined)
+            names.add(name);
+    }
+    return names;
 }
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
 const WRAPPERS = new Set(["env", "command", "exec", "time", "nohup", "nice", "sudo", "builtin"]);
@@ -162,36 +709,161 @@ function gitSubcommand(args) {
     }
     return undefined;
 }
-/** Whether a shell line pushes: `git push`, `gh pr create`, or `gh pr merge`, anywhere in it. */
-export function isPushCommand(line, depth = 0) {
+/**
+ * The commands in a shell line that matter to the judge, in the order they
+ * run: pushes, pull requests created or merged, and commits. A shell's `-c`
+ * script is read in place, a few levels deep.
+ */
+function steps(line, depth = 0) {
+    const found = [];
     for (const words of shellCommands(line)) {
         const run = program(words);
         if (run.length === 0)
             continue;
         const name = basename(run[0]);
-        if (name === "git" && gitSubcommand(run.slice(1)) === "push")
-            return true;
-        if (name === "gh" && run[1] === "pr" && (run[2] === "create" || run[2] === "merge"))
-            return true;
-        if (SHELLS.has(name) && depth < 3) {
+        if (name === "git") {
+            const subcommand = gitSubcommand(run.slice(1));
+            if (subcommand === "push" || subcommand === "commit")
+                found.push({ kind: subcommand, args: [] });
+        }
+        else if (name === "gh" && run[1] === "pr" && (run[2] === "create" || run[2] === "merge"))
+            found.push({ kind: run[2], args: run.slice(3) });
+        else if (SHELLS.has(name) && depth < 3) {
             const flag = run.findIndex((word, index) => index > 0 && /^-[a-z]*c[a-z]*$/.test(word));
             const script = flag > 0 ? run[flag + 1] : undefined;
-            if (script !== undefined && isPushCommand(script, depth + 1))
-                return true;
+            if (script !== undefined)
+                found.push(...steps(script, depth + 1));
         }
     }
-    return false;
+    return found;
+}
+/** Whether a shell line pushes: `git push`, `gh pr create`, or `gh pr merge`, anywhere in it. */
+export function isPushCommand(line) {
+    return steps(line).some((step) => step.kind !== "commit");
+}
+/**
+ * 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 function sendsCommits(line) {
+    return steps(line).some((step) => step.kind === "push" || step.kind === "create");
+}
+/**
+ * git commands that make a commit or move the branch to one: what a check run
+ * before the shell line cannot see, because it does not exist yet.
+ */
+const COMMIT_MAKING = new Set(["commit", "merge", "cherry-pick", "revert", "am", "rebase", "pull"]);
+/** Flags with which those commands make no commit: they stop, or only pretend. */
+const MAKES_NO_COMMIT = new Set(["--abort", "--quit", "--dry-run"]);
+/** The simple commands a shell line runs, in order, with those inside `bash -c` and the like in place. */
+function commandsInOrder(line, depth = 0) {
+    const out = [];
+    for (const words of shellCommands(line)) {
+        const run = program(words);
+        if (run.length === 0)
+            continue;
+        if (SHELLS.has(basename(run[0])) && depth < 3) {
+            const flag = run.findIndex((word, index) => index > 0 && /^-[a-z]*c[a-z]*$/.test(word));
+            const script = flag > 0 ? run[flag + 1] : undefined;
+            if (script !== undefined) {
+                out.push(...commandsInOrder(script, depth + 1));
+                continue;
+            }
+        }
+        out.push(run);
+    }
+    return out;
+}
+/**
+ * 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 function commitBeforePush(line) {
+    let found;
+    for (const run of commandsInOrder(line)) {
+        const name = basename(run[0]);
+        if (name === "gh" && run[1] === "pr" && run[2] === "create")
+            return found;
+        if (name !== "git")
+            continue;
+        const subcommand = gitSubcommand(run.slice(1));
+        if (subcommand === "push")
+            return found;
+        if (found === undefined &&
+            subcommand !== undefined &&
+            COMMIT_MAKING.has(subcommand) &&
+            !run.some((word) => MAKES_NO_COMMIT.has(word)))
+            found = `git ${subcommand}`;
+    }
+    return undefined;
+}
+/** `gh pr merge` options that take the next word as their value. */
+const GH_MERGE_VALUE_OPTIONS = new Set([
+    "-A",
+    "--author-email",
+    "-b",
+    "--body",
+    "-F",
+    "--body-file",
+    "--match-head-commit",
+    "-t",
+    "--subject",
+    "-R",
+    "--repo",
+]);
+function mergeTarget(args) {
+    let selector;
+    let repo;
+    for (let at = 0; at < args.length; at += 1) {
+        const word = args[at];
+        if (word === "--") {
+            selector ??= args[at + 1];
+            break;
+        }
+        if (word.startsWith("--") && word.includes("=")) {
+            if (word.startsWith("--repo="))
+                repo = word.slice("--repo=".length);
+            continue;
+        }
+        if (GH_MERGE_VALUE_OPTIONS.has(word)) {
+            if (word === "-R" || word === "--repo")
+                repo = args[at + 1];
+            at += 1;
+            continue;
+        }
+        if (word.startsWith("-"))
+            continue;
+        selector ??= word;
+    }
+    return { ...(selector ? { selector } : {}), ...(repo ? { repo } : {}) };
+}
+/** Every `gh pr merge` in a shell line, with the pull request and repository it names. */
+export function mergeTargets(line) {
+    return steps(line)
+        .filter((step) => step.kind === "merge")
+        .map((step) => mergeTarget(step.args));
 }
 /**
  * What the host is told. In report mode the lines reach the agent as context
  * 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 function hookResponse(host, outcome) {
     const text = outcome.lines.join("\n");
-    if (outcome.block) {
+    const event = outcome.event ?? "PreToolUse";
+    if (outcome.block && event === "PreToolUse") {
         if (host === "claude")
             return {
                 stdout: `${JSON.stringify({
@@ -212,7 +884,7 @@ export function hookResponse(host, outcome) {
         return { stdout: `${text}\n`, stderr: "", exitCode: 0 };
     return {
         stdout: `${JSON.stringify({
-            hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: text },
+            hookSpecificOutput: { hookEventName: event, additionalContext: text },
         })}\n`,
         stderr: "",
         exitCode: 0,
@@ -296,17 +968,106 @@ function writeAtomically(path, content, mode) {
         throw error;
     }
 }
+/** The hook file the installer writes for a host, relative to the repository root. */
+export function judgeHookFile(host) {
+    return host === "claude" ? ".claude/settings.json" : ".codex/hooks.json";
+}
+/** Whether one row of a hook event's list is an entry this command owns: a handler carries the marker. */
+function ownsRow(row) {
+    const handlers = row?.hooks;
+    return Array.isArray(handlers)
+        ? handlers.some((handler) => handler?.statusMessage === JUDGE_HOOK_MARKER)
+        : false;
+}
+/**
+ * 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 function hasJudgeEntry(root, host, event) {
+    try {
+        const text = readOwnFile(join(root, judgeHookFile(host)));
+        if (text === undefined)
+            return false;
+        const rows = JSON.parse(text)?.hooks?.[event];
+        return Array.isArray(rows) && rows.some(ownsRow);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function hasProjectJudgeHook(root, host) {
+    return JUDGE_HOOK_EVENTS.some((event) => hasJudgeEntry(root, host, event));
+}
 /**
- * The PreToolUse entry in a host's JSON hook file, added once.
+ * 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 function checkoutRoot(start) {
+    let directory = resolve(start);
+    for (;;) {
+        if (existsSync(join(directory, ".git")))
+            return directory;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}
+/**
+ * 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 const PUSH_CHECK_SETTING_FILE = "push-check.json";
+export function pushCheckSettingPath(environment) {
+    return join(configHome(environment), PUSH_CHECK_SETTING_FILE);
+}
+/** True only when this laptop's switch says off; anything unreadable leaves it on. */
+export function pushCheckOff(environment) {
+    try {
+        const parsed = JSON.parse(readFileSync(pushCheckSettingPath(environment), "utf8"));
+        return parsed?.on === false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Turn the user-scope push check off or back on for this laptop. */
+export function setPushCheck(environment, on) {
+    const path = pushCheckSettingPath(environment);
+    if (on) {
+        rmSync(path, { force: true });
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify({ on: false })}\n`, { mode: 0o600 });
+}
+/**
+ * The PreToolUse and PostToolUse entries in a host's JSON hook file, each
+ * added once. Both run the same command; the judge reads which event called it
+ * from the host's input (`hook_event_name`).
  *
  * The entry this command owns is the one whose handler carries the marker. A
- * second run finds it and changes nothing, byte for byte. An owned entry that
- * somebody edited is left alone and reported, the same rule the guidance
- * installer follows: it is theirs now, and silently putting it back would undo
- * a decision somebody made on purpose.
+ * second run finds both and changes nothing, byte for byte; a file written by
+ * an earlier release, with only the PreToolUse entry, gains the PostToolUse
+ * one. An owned entry that somebody edited is left alone and reported, and
+ * nothing in the file is written, the same rule the guidance installer
+ * follows: it is theirs now, and silently putting it back would undo a
+ * decision somebody made on purpose.
  */
 function installJsonHook(root, host) {
-    const relativePath = host === "claude" ? ".claude/settings.json" : ".codex/hooks.json";
+    const relativePath = judgeHookFile(host);
     const path = join(root, relativePath);
     try {
         const before = readOwnFile(path);
@@ -328,28 +1089,33 @@ function installJsonHook(root, host) {
                 reason: `hooks in ${relativePath} is not an object`,
             };
         const events = hooks;
-        const rows = events.PreToolUse === undefined ? [] : events.PreToolUse;
-        if (!Array.isArray(rows))
-            return {
-                target: host,
-                path: relativePath,
-                status: "refused",
-                reason: `hooks.PreToolUse in ${relativePath} is not a list`,
-            };
-        const own = rows.filter((row) => Array.isArray(row?.hooks)
-            ? row.hooks.some((handler) => handler?.statusMessage === JUDGE_HOOK_MARKER)
-            : false);
         const expected = expectedEntry(host);
-        if (own.length === 1 && JSON.stringify(own[0]) === JSON.stringify(expected))
+        const missing = [];
+        for (const event of JUDGE_HOOK_EVENTS) {
+            const rows = events[event] === undefined ? [] : events[event];
+            if (!Array.isArray(rows))
+                return {
+                    target: host,
+                    path: relativePath,
+                    status: "refused",
+                    reason: `hooks.${event} in ${relativePath} is not a list`,
+                };
+            const own = rows.filter(ownsRow);
+            if (own.length === 1 && JSON.stringify(own[0]) === JSON.stringify(expected))
+                continue;
+            if (own.length > 0)
+                return {
+                    target: host,
+                    path: relativePath,
+                    status: "refused",
+                    reason: `${relativePath} already has a Balladeer judge entry under ${event} that was edited by hand, so the file was left as it is. Remove it to have this command write the current ones.`,
+                };
+            missing.push(event);
+        }
+        if (missing.length === 0)
             return { target: host, path: relativePath, status: "unchanged" };
-        if (own.length > 0)
-            return {
-                target: host,
-                path: relativePath,
-                status: "refused",
-                reason: `${relativePath} already has a Balladeer judge entry that was edited by hand, so it was left as it is. Remove it to have this command write the current one.`,
-            };
-        events.PreToolUse = [...rows, expected];
+        for (const event of missing)
+            events[event] = [...(events[event] ?? []), expected];
         settings.hooks = events;
         const mode = before === undefined ? 0o644 : lstatSync(path).mode & 0o777;
         writeAtomically(path, `${JSON.stringify(settings, null, 2)}\n`, mode);
@@ -418,3 +1184,95 @@ function installGitHook(root) {
 export function installJudgeHook(root, target) {
     return target === "git" ? installGitHook(root) : installJsonHook(root, target);
 }
+const SHA = /^[0-9a-f]{40}$/;
+/**
+ * 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 async function pushLanded(root, sha) {
+    const local = await runCommand("git", [
+        "-C",
+        root,
+        "for-each-ref",
+        "--contains",
+        sha,
+        "--count=1",
+        "--format=%(refname)",
+        "refs/remotes",
+    ], { timeoutMs: 30_000 });
+    if (local.ok && local.stdout.trim() !== "")
+        return true;
+    const remotes = await runCommand("git", ["-C", root, "remote"]);
+    if (!remotes.ok)
+        return false;
+    const names = remotes.stdout
+        .split("\n")
+        .map((name) => name.trim())
+        .filter(Boolean);
+    for (const remote of names.slice(0, 5)) {
+        const listed = await runCommand("git", ["-C", root, "ls-remote", "--heads", remote], {
+            timeoutMs: 20_000,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        });
+        if (listed.ok && listed.stdout.split("\n").some((line) => line.startsWith(`${sha}\t`)))
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 async function baseBeforePush(root, head) {
+    const names = [];
+    const remoteHead = await runCommand("git", [
+        "-C",
+        root,
+        "rev-parse",
+        "--abbrev-ref",
+        "origin/HEAD",
+    ]);
+    const named = remoteHead.stdout.trim();
+    if (remoteHead.ok && named && named !== "origin/HEAD")
+        names.push(named);
+    names.push("origin/main", "origin/master");
+    for (const name of new Set(names)) {
+        if ((await resolveCommit(root, name)) !== head)
+            continue;
+        const log = await runCommand("git", [
+            "-C",
+            root,
+            "reflog",
+            "show",
+            "--format=%H %gs",
+            "-n",
+            "2",
+            name,
+        ]);
+        const [latest, earlier] = log.ok ? log.stdout.trim().split("\n") : [];
+        if (!latest?.startsWith(`${head} update by push`) || earlier === undefined)
+            return undefined;
+        const previous = earlier.split(" ")[0] ?? "";
+        if (!SHA.test(previous) || previous === head)
+            return undefined;
+        const fork = await runCommand("git", ["-C", root, "merge-base", head, previous]);
+        const sha = fork.stdout.trim();
+        return fork.ok && SHA.test(sha) && sha !== head ? sha : undefined;
+    }
+    return undefined;
+}