@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/recheck.js

@@ -0,0 +1,1398 @@
+// Post-approval delta recheck.
+//
+// Once a PR is approved, a later change can still regress it. A staleness
+// check that re-reviews on every commit after the approval spends most of its
+// output concluding nothing changed, so the delta is classified first, and
+// the standing verdict is UPHELD BY DEFAULT.
+//
+// Shape of the mechanism:
+//
+//   trigger ──► planRecheck() ──► no-op (uphold, nothing posted, nothing spent)
+//                             └─► one nudge to the PR's OWN sticky session
+//
+// Four triggers: a push after an approve, CI completing at the head, the base
+// branch advancing, and an author reply. The author reply is deliberately a
+// no-op HERE: `src/pingpong.ts` already owns that path (≤3 exchanges, reply +
+// optional thread resolve) and a second reply handler would duplicate it.
+// With no code delta there is nothing to recheck; the value is the reply,
+// which is already owned.
+//
+// Invariants this module keeps structurally, not by prompting:
+//
+//  1. **Only APPROVE → REQUEST_CHANGES.** A recheck is planned only when the
+//     standing verdict is APPROVE, and the decision file accepts exactly two
+//     outcomes: `uphold` and `request_changes`. Anything else — including a
+//     literal "APPROVE" or "NEEDS_HUMAN" — is coerced to `uphold` and logged.
+//     The path can therefore never re-approve and never park.
+//  2. **A trivial or empty delta costs one classification and a no-op.** That
+//     is what makes the broad trigger set affordable. A base advance touching
+//     no PR-owned file is the loudest instance: every file it brings is a
+//     `base-merge` file, so it resolves to `trivial-delta`.
+//  3. **An unchanged head with no new evidence is a no-op** — the same rule
+//     the gate's guard applies (`guards.hasNewEvidence`), read here off the
+//     same single `reviewed_heads` mark. There is no second copy.
+//  4. **Single shepherd.** The recheck is a nudge to the PR's existing `pr-<n>`
+//     session — no new session, no lens fan-out, no round. It goes through
+//     `wakeOrHold`, so a nudge arriving mid-round is held and flushed at round
+//     end like any other wake.
+//  5. **No GitHub write lives here.** The module reads (compare, files) and
+//     writes nothing; the session posts its review through the gated scripts.
+//     The MutationGate keeps its monopoly by this module having no mutation.
+import { existsSync, mkdirSync, readdirSync, renameSync, watch } from "node:fs";
+import { join } from "node:path";
+import { readFindingsRecord } from "@quickchatai/pi-quickreview/src/findingsrecord.js";
+import { isMigrationPath } from "@quickchatai/pi-quickreview/src/heuristics.js";
+import { parseHunkHeader } from "@quickchatai/pi-quickreview/src/hunkheader.js";
+import { applyEvent } from "./statemachine.js";
+import { recheckHead12, recheckKeyPrefix } from "@quickchatai/pi-quickreview/src/findingkey.js";
+import { recheckWakeReason } from "./state.js";
+import { normalizeVerdict, recheckPromptMarker, stampPrompt, } from "@quickchatai/pi-quickreview/src/types.js";
+import { standingVerdict } from "@quickchatai/pi-quickreview/src/standing-review.js";
+import { wakeOrHold, withRepoFacts } from "./wakes.js";
+import { prWorktreeRel } from "./worktrees.js";
+import { readSettledJson, resolvePartialWritePolicy, } from "@quickchatai/pi-quickreview/src/settledread.js";
+/** The delta of a range GitHub could not list: no files, and significant by
+ * construction — nothing is known about what it holds. */
+export function unreadDelta() {
+    return Object.assign([], { unread: true });
+}
+/** Dependency-manifest lockfiles: generated, never reviewed on their content. */
+const LOCKFILES = new Set([
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "poetry.lock",
+    "uv.lock",
+    "Pipfile.lock",
+    "Cargo.lock",
+    "Gemfile.lock",
+    "composer.lock",
+    "go.sum",
+]);
+/** Manifests whose version field moves on a release bump. */
+const VERSION_MANIFESTS = new Set([
+    "package.json",
+    "pyproject.toml",
+    "Cargo.toml",
+    "setup.cfg",
+    "VERSION",
+    "version.txt",
+]);
+function baseName(path) {
+    return path.split("/").pop() ?? path;
+}
+/**
+ * Split a migration filename into its number and the rest: `0042_add_foo.py`
+ * → `{ num: "0042", rest: "add_foo.py" }`. Null when the file is not a
+ * numbered migration.
+ */
+export function migrationName(path) {
+    const m = /^(\d+)[_-](.+)$/.exec(baseName(path));
+    if (!m || !isMigrationPath(path))
+        return null;
+    return { num: m[1], rest: m[2] };
+}
+/** A rename that only moves a migration's number: `0042_x.py` → `0043_x.py`. */
+export function isMigrationRenumber(from, to) {
+    const a = migrationName(from);
+    const b = migrationName(to);
+    return a !== null && b !== null && a.rest === b.rest && a.num !== b.num;
+}
+/**
+ * The hunks of a unified diff. File headers (`---`/`+++`) are recognised only
+ * before the first hunk — inside one, `--- x` is a removed line that reads
+ * `-- x`. A patch with no `@@` line is one hunk.
+ */
+function parseHunks(patch) {
+    const hunks = [];
+    let cur = null;
+    for (const line of patch.split("\n")) {
+        if (line.startsWith("@@")) {
+            cur = {
+                section: /^@@[^@]*@@ ?(.*)$/.exec(line)?.[1] ?? "",
+                oldStart: parseHunkHeader(line)?.old_start ?? null,
+                lines: [],
+            };
+            hunks.push(cur);
+            continue;
+        }
+        if (cur === null && (line.startsWith("+++") || line.startsWith("---")))
+            continue;
+        const kind = line.charAt(0);
+        if (kind !== " " && kind !== "+" && kind !== "-")
+            continue;
+        if (cur === null) {
+            cur = { section: "", oldStart: null, lines: [] };
+            hunks.push(cur);
+        }
+        cur.lines.push({ kind, text: line.slice(1) });
+    }
+    return hunks;
+}
+function changeBlocks(hunk) {
+    const blocks = [];
+    let cur = null;
+    for (const line of hunk.lines) {
+        if (line.kind === " ") {
+            cur = null;
+            continue;
+        }
+        if (cur === null) {
+            cur = { added: [], removed: [] };
+            blocks.push(cur);
+        }
+        (line.kind === "+" ? cur.added : cur.removed).push(line.text);
+    }
+    return blocks;
+}
+/** Every line of one kind in a patch, prefix kept — a whole added or removed
+ * file's text. */
+function changedLines(patch, kind) {
+    return parseHunks(patch).flatMap((h) => h.lines.filter((l) => l.kind === kind).map((l) => `${kind}${l.text}`));
+}
+/** A quoted literal on one line. Whitespace inside one is content, never
+ * formatting: `"a b"` → `"ab"` changes the program. */
+const QUOTED = /("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`)/;
+/** Drop whitespace OUTSIDE quoted literals; the literals stay verbatim. */
+function stripOutsideQuotes(line) {
+    return line
+        .split(QUOTED)
+        .map((part, i) => (i % 2 === 1 ? part : part.replace(/\s+/g, "")))
+        .join("");
+}
+/** Languages whose leading whitespace is syntax — a dedent in Python moves a
+ * line out of its block; in YAML it moves a key to another mapping; in the
+ * indented style-sheet syntaxes (Sass, Stylus) it moves a rule out of the
+ * selector it was nested under. */
+function indentSignificant(path) {
+    if (!path)
+        return false;
+    const base = baseName(path);
+    return /\.(py|pyi|ya?ml|sass|styl)$/i.test(base) || base === "Makefile" || /\.mk$/i.test(base);
+}
+/** A shell script's basename (a Dockerfile counts). */
+function isShellFile(base) {
+    return /\.(sh|bash|zsh|ksh)$/i.test(base) || base === "Dockerfile";
+}
+/** A Ruby file's basename (a Gemfile counts). */
+function isRubyFile(base) {
+    return /\.rb$/i.test(base) || base === "Gemfile";
+}
+/** Languages where a line break ends a command or statement — in a shell
+ * script `a\n-b` runs two commands where `a -b` runs one; Ruby and Go end a
+ * statement at most line breaks. */
+function lineTerminated(path) {
+    if (!path)
+        return false;
+    const base = baseName(path);
+    return isShellFile(base) || isRubyFile(base) || /\.go$/i.test(base);
+}
+/**
+ * The whitespace-insensitive form of a side of a patch. Whitespace between
+ * tokens is dropped (quoted literals kept verbatim) and the lines are
+ * concatenated, so a re-indent or a re-flow compares equal. For an
+ * indentation-significant file each non-blank line keeps its leading
+ * whitespace and stays its own line — a re-flow or re-indent there is not
+ * provably meaningless, so it is not formatting. For a file whose line
+ * breaks end statements each non-blank line stays its own line, so a re-flow
+ * there is not formatting while a re-indent still is.
+ */
+function squash(lines, path) {
+    if (lineTerminated(path))
+        return lines
+            .filter((l) => l.trim() !== "")
+            .map(stripOutsideQuotes)
+            .join("\n");
+    if (!indentSignificant(path))
+        return lines.map(stripOutsideQuotes).join("");
+    return lines
+        .filter((l) => l.trim() !== "")
+        .map((l) => (/^\s*/.exec(l)?.[0] ?? "") + stripOutsideQuotes(l))
+        .join("\n");
+}
+/**
+ * The slash-span form of a side of a patch: on each line, the raw text from
+ * its first `/` to its last is kept verbatim (delimited), and whitespace
+ * elsewhere is dropped. A regex literal never crosses a line, so it always
+ * lies inside its line's span; whitespace inside one is content (`/a b/` →
+ * `/ab/` changes the program). Telling a regex from a division, a comment or
+ * a markup closing tag is not attempted: any whitespace change between the
+ * first and last `/` of a line is held significant, so this form can only
+ * make a delta less trivial, never more.
+ */
+function slashSpans(lines) {
+    return lines
+        .map((l) => {
+        const i = l.indexOf("/");
+        const j = l.lastIndexOf("/");
+        if (i === j)
+            return l.replace(/\s+/g, "");
+        return `${l.slice(0, i).replace(/\s+/g, "")}\0${l.slice(i, j + 1)}\0${l.slice(j + 1).replace(/\s+/g, "")}`;
+    })
+        .join("");
+}
+/** The class of a character for token joining: two characters of one class
+ * that whitespace separates would read as ONE token once it is dropped —
+ * `const n` → `constn`, `a + ++b` → `a+++b` (the same as `a++ + b`). Null for
+ * a character no neighbour joins with (brackets, separators, quotes). */
+function joinClass(ch) {
+    if (/[\w$]/.test(ch) || ch.charCodeAt(0) > 127)
+        return "word";
+    if (/[+\-*/%&|^!~<>=?:.@#]/.test(ch))
+        return "op";
+    return null;
+}
+/** A word after which a line break ends the statement (JavaScript's
+ * restricted productions: `return\n(x)` returns undefined). Matched against
+ * the last nine characters, one more than the longest word. */
+const RESTRICTED_WORD_END = /(?:^|[^\w$])(?:return|throw|break|continue|yield|async)$/;
+/**
+ * The token-seam form of a side of a patch: whitespace outside quoted
+ * literals is dropped EXCEPT where it separates two characters of one join
+ * class, where it becomes a single space — or a line break, when the gap
+ * holds one. Dropping that whitespace would merge two tokens into one
+ * (`a + ++b` and `a++ + b` both squash to `a+++b`), so whether it is there is
+ * content. A line break is also kept wherever it can end a statement however
+ * the tokens join: after a restricted word (`return\n(x)`) and beside `++` or
+ * `--` (`a++\nb` against `a\n++b`). Every line break kept is a `\n` the form
+ * holds nowhere else, so compared beside `squash` this form can only make a
+ * delta less trivial, never more.
+ */
+function tokenSeams(lines) {
+    let out = "";
+    let gap = false;
+    let lineBreak = false;
+    // A line comment runs to the end of its line, so the break after a line
+    // that holds a comment marker outside a literal is content.
+    const LINE_COMMENT = /\/\/|#|--/;
+    const push = (text) => {
+        if (text === "")
+            return;
+        const prev = out.slice(-1);
+        if (gap && prev !== "") {
+            const cls = joinClass(prev);
+            const seam = cls !== null && cls === joinClass(text.charAt(0));
+            const ends = lineBreak &&
+                (seam ||
+                    RESTRICTED_WORD_END.test(out.slice(-9)) ||
+                    /(?:\+\+|--)$/.test(out.slice(-2)) ||
+                    /^(?:\+\+|--)/.test(text));
+            // A seam keeps its space and gains the break, so deleting every "\n"
+            // gives back the form without breaks exactly — before and after
+            // `digitsOnly` masks it — and the break form only ever refines it.
+            if (seam)
+                out += " ";
+            if (ends)
+                out += "\n";
+        }
+        out += text;
+        gap = false;
+        lineBreak = false;
+    };
+    for (const line of lines) {
+        gap = true;
+        lineBreak = true;
+        let commented = false;
+        line.split(QUOTED).forEach((part, i) => {
+            if (i % 2 === 1)
+                return push(part);
+            if (LINE_COMMENT.test(part))
+                commented = true;
+            part.split(/(\s+)/).forEach((chunk, k) => {
+                if (k % 2 === 1)
+                    gap = true;
+                else
+                    push(chunk);
+            });
+        });
+        if (commented && out !== "")
+            out += "\n";
+    }
+    return out;
+}
+/** Style sheets: whitespace between two selector tokens is a combinator
+ * (`a .child` is a descendant, `a.child` a compound), so no whitespace that
+ * separates two tokens there may vanish or appear, whatever their classes. */
+function selectorWhitespace(path) {
+    return path !== undefined && /\.(css|scss|sass|less|styl)$/i.test(baseName(path));
+}
+/** Every whitespace run inside a line collapsed to one space and the lines
+ * joined by one: a re-indent and a re-flow compare equal, a gap that opens or
+ * closes between two tokens does not. */
+function collapsed(lines) {
+    return lines
+        .map((l) => l.trim().replace(/\s+/g, " "))
+        .filter((l) => l !== "")
+        .join(" ");
+}
+/** A heredoc opener: `<<EOF`, `<<-'EOF'`, `<< "EOF"` (shell) and `<<~SQL`
+ * (Ruby, no space — `a << b` appends). */
+const SHELL_HEREDOC = /<<-?\s*(['"]?)[A-Za-z_]\w*\1/;
+const RUBY_HEREDOC = /<<[-~]?(['"]?)[A-Za-z_]\w*\1/;
+/** A YAML block scalar indicator closing its line (`key: |`, `- >-`). */
+const YAML_BLOCK_SCALAR = /(?:^|:|-)\s*[|>][-+1-9]{0,2}\s*(?:#.*)?$/;
+/**
+ * May this hunk's changed lines sit inside a literal that spans lines — a
+ * template literal, a triple-quoted string, a heredoc, a YAML block scalar?
+ * Whitespace inside one is content, and the per-line `QUOTED` rule cannot see
+ * a literal that opens or closes on another line. Judged from what the hunk
+ * shows (its section text, its context and its changed lines): an unbalanced
+ * backtick, any triple quote, or the language's own opener. A literal whose
+ * delimiters both lie outside the hunk is beyond what the patch shows.
+ */
+function mayTouchMultilineLiteral(hunk, path) {
+    const base = path === undefined ? "" : baseName(path);
+    const shell = isShellFile(base);
+    const ruby = isRubyFile(base);
+    const yaml = /\.ya?ml$/i.test(base);
+    return [hunk.section, ...hunk.lines.map((l) => l.text)].some((text) => text.includes('"""') ||
+        text.includes("'''") ||
+        (text.replace(/\\./g, "").split("`").length - 1) % 2 === 1 ||
+        (shell && SHELL_HEREDOC.test(text)) ||
+        (ruby && RUBY_HEREDOC.test(text)) ||
+        (yaml && YAML_BLOCK_SCALAR.test(text)));
+}
+/**
+ * The forms a side of a change block is compared in, every one of which must
+ * match for the change to be whitespace-only: `squash` (insignificant
+ * whitespace dropped — never inside a quoted literal, never leading
+ * indentation of a whitespace-significant language), `slashSpans` (no line's
+ * whitespace changed between its first and last `/` — a regex literal's
+ * whitespace is content), `tokenSeams` (no whitespace that separates two
+ * tokens appeared or vanished) and, in a style sheet, `collapsed`. The one
+ * list both `formattingOnly` and `digitsOnly` compare.
+ */
+function whitespaceForms(lines, path) {
+    const forms = [squash(lines, path), slashSpans(lines), tokenSeams(lines)];
+    if (selectorWhitespace(path))
+        forms.push(collapsed(lines));
+    return forms;
+}
+/** The two sides of a block agree in every `whitespaceForms` form, each
+ * compared after `mask` (identity unless a caller masks something out). */
+function sameForms(block, path, mask = (form) => form) {
+    const removed = whitespaceForms(block.removed, path);
+    return whitespaceForms(block.added, path).every((form, i) => mask(form) === mask(removed[i]));
+}
+/**
+ * Whitespace-only change, judged change block by change block (see
+ * `changeBlocks`): within a block, concatenation (not a per-line set) is the
+ * comparison, so a re-indent or a re-flow passes while a reordering of real
+ * lines does not — and a line moved across unchanged code is two blocks that
+ * each differ. A hunk that may touch a multi-line literal is never
+ * formatting.
+ */
+export function formattingOnly(patch, path) {
+    const hunks = parseHunks(patch);
+    const blocks = hunks.flatMap(changeBlocks);
+    if (blocks.length === 0)
+        return false;
+    if (hunks.some((h) => mayTouchMultilineLiteral(h, path)))
+        return false;
+    return blocks.every((b) => sameForms(b, path));
+}
+/** A migration number: a digit run that starts a token and is followed by `_`
+ * and a letter — the `NNNN_name` shape a migration filename or `dependencies`
+ * entry carries. `1_000` (a numeric literal) is not one. */
+const MIGRATION_NUMBER = /(?<![A-Za-z0-9_])\d+(?=_[A-Za-z])/g;
+/** Same text once every MIGRATION-NUMBER run is masked — the renumber's
+ * content edit (`dependencies = [("app", "0042_x")]` → `"0043_x"`) and nothing
+ * else. Only the migration-number shape is masked (`MIGRATION_NUMBER`): a
+ * semantic numeric change inside a renamed migration — a batch size, a
+ * timeout, a default, `1_000` → `2_000` — does NOT mask away, so it
+ * classifies significant. Judged block by block like `formattingOnly`; in a
+ * hunk that may touch a multi-line literal the raw lines are compared, so only
+ * the numbers may differ there. */
+export function digitsOnly(patch, path) {
+    const masked = (text) => text.replace(MIGRATION_NUMBER, "#");
+    return parseHunks(patch).every((hunk) => {
+        const literal = mayTouchMultilineLiteral(hunk, path);
+        return changeBlocks(hunk).every((block) => literal
+            ? masked(block.added.join("\n")) === masked(block.removed.join("\n"))
+            : sameForms(block, path, masked));
+    });
+}
+/** One release-version line and nothing else on it: `"version": "1.2.3",`
+ * (package.json) or `version = "1.2.3"` (pyproject/Cargo). The value must
+ * look like a version — a digit first, no spaces — so the npm lifecycle
+ * script `"version": "npm run build"` does not pass, and a line that merely
+ * MENTIONS version (`serde = { version = "1", features = [...] }`, an inline
+ * dependency with a `git` source) is not the key itself. */
+const RELEASE_VERSION_LINE = /^\s*(?:"version"\s*:\s*"v?\d[^"\s]*"\s*,?|version\s*=\s*(?:"v?\d[^"\s]*"|'v?\d[^'\s]*'))\s*$/i;
+/** A TOML table header line, its name with surrounding space dropped:
+ * `[package]` → `package`; an array table (`[[bin]]`) keeps its brackets. */
+const TOML_TABLE = /^\s*(\[?\[[^\]]+\]\]?)\s*(?:#.*)?$/;
+/** The TOML tables whose `version` key is the package's own release. */
+const RELEASE_TABLES = new Set(["package", "workspace.package", "project", "tool.poetry"]);
+function tomlTable(text) {
+    const m = TOML_TABLE.exec(text);
+    if (!m)
+        return null;
+    const header = m[1];
+    return header.startsWith("[[") ? header : header.slice(1, -1).replace(/\s+/g, "");
+}
+/** How far a line of JSON opens (+) or closes (−) objects and arrays, its
+ * quoted strings left out. */
+function jsonDepthDelta(text) {
+    let delta = 0;
+    text.split(QUOTED).forEach((part, i) => {
+        if (i % 2 === 1)
+            return;
+        for (const ch of part) {
+            if (ch === "{" || ch === "[")
+                delta++;
+            else if (ch === "}" || ch === "]")
+                delta--;
+        }
+    });
+    return delta;
+}
+/** Every changed line is the release-version key itself — the release-bump
+ * shape. The key must also be the package's own, proven from what the hunk
+ * shows: in a TOML manifest it sits in a release table (`RELEASE_TABLES`) —
+ * `version = "2"` under `[dependencies.serde]` is a dependency requirement —
+ * and in a JSON manifest it is a key of the top-level object, which the hunk
+ * proves only when it starts at the file's first line (`"version"` under
+ * `"config"` is configuration, not the release). A line whose place the patch
+ * does not show is not proven to be the release. */
+export function versionOnly(patch, path) {
+    if (path !== undefined && ["VERSION", "version.txt"].includes(baseName(path))) {
+        const lines = parseHunks(patch).flatMap((h) => h.lines);
+        const version = /^v?\d+(?:\.\d+)*(?:[-+][0-9A-Za-z.-]+)?$/;
+        return (lines.some((line) => line.kind !== " ") &&
+            lines.every((line) => line.text.trim() === "" ? line.kind === " " : version.test(line.text.trim())));
+    }
+    const toml = path !== undefined && /\.toml$/i.test(path);
+    const json = path !== undefined && /\.json$/i.test(path);
+    let changed = 0;
+    for (const hunk of parseHunks(patch)) {
+        let table = tomlTable(hunk.section);
+        // The old side's nesting depth before the line; unknown (null) unless
+        // the hunk starts at the top of the file.
+        let depth = hunk.oldStart === 1 ? 0 : null;
+        for (const line of hunk.lines) {
+            table = tomlTable(line.text) ?? table;
+            if (line.kind !== " ") {
+                changed++;
+                if (!RELEASE_VERSION_LINE.test(line.text))
+                    return false;
+                if (toml && (table === null || !RELEASE_TABLES.has(table)))
+                    return false;
+                if (json && depth !== 1)
+                    return false;
+            }
+            if (depth !== null && line.kind !== "+")
+                depth += jsonDepthDelta(line.text);
+        }
+    }
+    return changed > 0;
+}
+/** Does an ownership set hold this file — under its name, or, for a rename,
+ * under the name it had? The one ownership rule the classifier and the
+ * reviewed-head ownership read share. */
+export function ownedBy(file, owned) {
+    return (owned.has(file.filename) ||
+        (file.previous_filename !== undefined && owned.has(file.previous_filename)));
+}
+/** The PR's own files as an ownership set — or undefined, "ownership not
+ * consulted", when the list was truncated: a PR-owned file past GitHub's cap
+ * would otherwise read as a base-merge file, which is trivial. */
+export function ownershipSet(own) {
+    if (own.truncated)
+        return undefined;
+    return new Set(own.flatMap((f) => (f.previous_filename ? [f.filename, f.previous_filename] : [f.filename])));
+}
+/** Classify one file. The rules are deliberately narrow: anything a rule does
+ * not positively recognise is significant. */
+export function classifyFile(file, opts = {}) {
+    const name = file.filename;
+    const trivial = (reason) => ({
+        filename: name,
+        class: "trivial",
+        reason,
+    });
+    // A hand-resolved merge conflict is never trivial, wherever the file lives.
+    if (opts.resolvedFiles?.has(name))
+        return { filename: name, class: "significant", reason: "content" };
+    if (opts.prFiles && !ownedBy(file, opts.prFiles))
+        return trivial("base-merge");
+    const patch = file.patch ?? "";
+    const churn = (file.additions ?? 0) + (file.deletions ?? 0);
+    if (file.previous_filename && isMigrationRenumber(file.previous_filename, name)) {
+        // A missing patch with churn (GitHub omits it on large files) proves
+        // nothing — the same reading classifyDelta's delete+add pairing takes.
+        if (churn === 0 || (patch && (digitsOnly(patch, name) || formattingOnly(patch, name))))
+            return trivial("migration-renumber");
+        return { filename: name, class: "significant", reason: "content" };
+    }
+    if (file.previous_filename && churn === 0)
+        return trivial("pure-rename");
+    if (LOCKFILES.has(baseName(name)))
+        return trivial("version-bump");
+    if (VERSION_MANIFESTS.has(baseName(name)) && patch && versionOnly(patch, name))
+        return trivial("version-bump");
+    if (patch && formattingOnly(patch, name))
+        return trivial("formatting");
+    if (!patch && churn === 0)
+        return trivial("no-content-change");
+    return { filename: name, class: "significant", reason: "content" };
+}
+/**
+ * Classify the whole delta. Run before the per-file pass: GitHub reports a
+ * migration renumber as a rename only when it detects one — a large enough
+ * content edit comes back as a delete + an add. That pair is a renumber only
+ * when its content, too, differs by migration numbers alone (`digitsOnly`).
+ */
+export function classifyDelta(files, opts = {}) {
+    const removedMigrations = new Map();
+    for (const f of files) {
+        if (f.status !== "removed")
+            continue;
+        const m = migrationName(f.filename);
+        if (m)
+            removedMigrations.set(m.rest, f);
+    }
+    const renumbered = new Set();
+    for (const f of files) {
+        if (f.status !== "added")
+            continue;
+        const m = migrationName(f.filename);
+        const partner = m ? removedMigrations.get(m.rest) : undefined;
+        if (!m || !partner)
+            continue;
+        if (migrationName(partner.filename)?.num === m.num)
+            continue;
+        // The names only say it MIGHT be a renumber; the content must say it is.
+        // GitHub reports a rename as delete + add exactly when similarity is low,
+        // so the pair is trivial only when the removed file's text and the added
+        // file's text differ by migration numbers alone. A missing patch (GitHub
+        // omits it on large files) proves nothing, so it is not a renumber.
+        if (!f.patch || !partner.patch)
+            continue;
+        const gone = changedLines(partner.patch, "-");
+        const came = changedLines(f.patch, "+");
+        if (gone.length === 0 && came.length === 0)
+            continue;
+        if (!digitsOnly(["@@", ...gone, ...came].join("\n"), f.filename))
+            continue;
+        renumbered.add(f.filename);
+        renumbered.add(partner.filename);
+    }
+    const classified = files.map((f) => {
+        // A hand-resolved conflict beats every trivial rule, renumber included:
+        // classifyFile alone decides it.
+        if (renumbered.has(f.filename) && !opts.resolvedFiles?.has(f.filename)) {
+            // Ownership still wins: a migration that arrived with the base is a
+            // base-merge file whatever its number does.
+            const owned = !opts.prFiles || opts.prFiles.has(f.filename);
+            return {
+                filename: f.filename,
+                class: "trivial",
+                reason: owned ? "migration-renumber" : "base-merge",
+            };
+        }
+        return classifyFile(f, opts);
+    });
+    const significant = classified.filter((f) => f.class === "significant");
+    // A truncated delta is significant by construction: the files GitHub did not
+    // return may be exactly the PR-owned edit, and "all visible files trivial"
+    // says nothing about them. An unread one, for the same reason.
+    if (files.unread)
+        return { class: "significant", files: classified, significant, unread: true };
+    if (files.truncated)
+        return { class: "significant", files: classified, significant, truncated: true };
+    const cls = classified.length === 0 ? "empty" : significant.length > 0 ? "significant" : "trivial";
+    return { class: cls, files: classified, significant };
+}
+/** CI conclusions that carry no bad news. Anything else at an approved head is
+ * new evidence (guard 2's sense): something the standing review did not see. */
+const CI_BENIGN = new Set(["success", "neutral", "skipped", "cancelled", "stale"]);
+export function ciIsAdverse(conclusion) {
+    if (!conclusion)
+        return false;
+    return !CI_BENIGN.has(conclusion.toLowerCase());
+}
+/**
+ * Guard 2's rule as the recheck reads it, off the same mark: an unchanged head
+ * with nothing new is a no-op. A base advance is exempt because its delta is on
+ * the base side, and an adverse CI conclusion IS the new evidence. The runner's
+ * free early refusal and the plan both ask this one predicate.
+ */
+export function unchangedHeadNoop(trigger, headSha, lastReviewedSha, ci) {
+    const adverseCi = trigger === "ci" && ciIsAdverse(ci?.conclusion);
+    return trigger !== "base_advance" && headSha === lastReviewedSha && !adverseCi;
+}
+/** Move a withheld-approval mark to a newer head after an uphold. This is NOT
+ * a re-approve — the approval was never posted; the CI-gate retry still
+ * demands green CI at the new head before anything posts. No mark, or a mark
+ * already at this head, is a silent no-op. */
+export function carryWithheldMark(store, pr, newHead, via, log = () => { }) {
+    const withheld = store.approvalWithheld(pr);
+    if (!withheld || withheld.head_sha === newHead)
+        return;
+    // Only ever carry TO the PR's current head. Overlapping rechecks finish in
+    // any order: an older push's handler finishing after the newer one's would
+    // otherwise carry the mark BACK, and the ci_completed retry at the real head
+    // then no-ops on "head-moved" with the push backstop already claimed —
+    // stranded. Read and write are one synchronous stretch, so nothing can
+    // interleave between them.
+    const current = store.getPr(pr)?.head_sha;
+    if (current && current !== newHead) {
+        store.logEvent("approval_withheld_carry_stale", pr, {
+            from: withheld.head_sha,
+            to: newHead,
+            current,
+            via,
+        });
+        log(`recheck: #${pr} withheld approval NOT carried to ${newHead.slice(0, 7)} — the PR is at ${current.slice(0, 7)} (${via})`);
+        return;
+    }
+    // The classifier verdict that caused the withhold rides along with the
+    // mark — the carried head has no fresher CI read to offer, and the CI-gate
+    // retry re-classifies at release time anyway.
+    store.recordApprovalWithheld(pr, {
+        head_sha: newHead,
+        ci_state: withheld.ci_state ?? null,
+        reason: withheld.reason ?? "red-ci",
+    });
+    store.logEvent("approval_withheld_carried", pr, { from: withheld.head_sha, to: newHead, via });
+    log(`recheck: #${pr} withheld approval carried ${withheld.head_sha.slice(0, 7)} → ${newHead.slice(0, 7)} (${via})`);
+}
+/**
+ * The whole decision, pure. Order matters: the cheap structural refusals come
+ * before anything that would cost a classification, and the classification
+ * comes before anything that would cost a session turn.
+ */
+export function planRecheck(input) {
+    const noop = (reason, classification) => ({
+        action: "noop",
+        reason,
+        class: classification?.class ?? "empty",
+        ...(classification ? { classification } : {}),
+    });
+    // The author-reply trigger is owned end to end by src/pingpong.ts. Nothing
+    // to recheck without a code delta, and a second reply handler would
+    // duplicate it.
+    if (input.trigger === "author_reply")
+        return noop("pingpong-owns-reply");
+    // Only a standing APPROVE can be moved by this path, and only downwards.
+    // Everything else (REQUEST_CHANGES, NEEDS_HUMAN, never reviewed) already has
+    // a route: the ordinary trigger → round path.
+    if (normalizeVerdict(input.standing) !== "APPROVE")
+        return noop("no-standing-approval");
+    if (unchangedHeadNoop(input.trigger, input.head_sha, input.last_reviewed_sha, input.ci))
+        return noop("unchanged-head");
+    const adverseCi = input.trigger === "ci" && ciIsAdverse(input.ci?.conclusion);
+    const classification = classifyDelta(input.delta, {
+        ...(input.prFiles ? { prFiles: new Set(input.prFiles) } : {}),
+        ...(input.resolvedFiles ? { resolvedFiles: new Set(input.resolvedFiles) } : {}),
+    });
+    if (adverseCi)
+        return {
+            action: "recheck",
+            class: classification.class,
+            evidence: classification.unread
+                ? `CI concluded ${input.ci?.conclusion}; the delta's files could not be read from GitHub — read the delta in the worktree yourself`
+                : `CI concluded ${input.ci?.conclusion}`,
+            classification,
+        };
+    if (classification.class === "empty")
+        return noop("empty-delta", classification);
+    if (classification.class === "trivial")
+        return noop("trivial-delta", classification);
+    return {
+        action: "recheck",
+        class: classification.class,
+        evidence: classification.truncated
+            ? `GitHub truncated the delta at ${classification.files.length} file(s) — the unseen remainder may hold changes this review has not seen`
+            : `${classification.significant.length} changed file(s) this review has not seen`,
+        classification,
+    };
+}
+// ---- the order handed to the session --------------------------------------
+/** `pr-<n>-recheck-<head12>.json` — the decision file's name under `verdict/`,
+ * and the findings record's under `state/findings/`. */
+export function recheckDecisionFile(pr, headSha) {
+    return `pr-${pr}-recheck-${recheckHead12(headSha)}.json`;
+}
+export const RECHECK_FILE_RE = /^pr-(\d+)-recheck-([0-9a-f]{7,40})\.json$/i;
+/** The runaway-guard identity of one recheck question: (trigger, head, ci
+ * conclusion, base target). Shared by runRecheck's claim and the reconcile
+ * backstop's has-this-been-asked check. */
+export function recheckFingerprint(req, headOverride) {
+    const head = headOverride ?? req.head_sha ?? "";
+    return [req.trigger, head, req.ci?.conclusion ?? "", req.base?.after ?? ""].join(":");
+}
+/** Fallback renderer (stub-wired daemon, unit tests): the order as JSON. */
+export function defaultRecheckPrompt(order) {
+    return JSON.stringify(order, null, 2);
+}
+/**
+ * The files the PR owns for delta classification: what it owns at the current
+ * head PLUS what it owned at the REVIEWED head. A push that
+ * restores a reviewed file to its base content drops it from the current diff,
+ * yet that is the PR undoing its own reviewed change, not a base merge. The
+ * second read happens only when a delta file falls outside today's ownership:
+ * `<base_ref>...<reviewed>` is the PR's own diff at the reviewed head. Throws
+ * on a read failure — every caller already treats that as "not trivial".
+ */
+export async function reviewedOwnership(adapter, pr, reviewedHead, delta, ownedNow) {
+    // Unknown ownership (a truncated listing) stays unknown.
+    if (!ownedNow)
+        return undefined;
+    const unowned = delta.some((f) => !ownedBy(f, ownedNow));
+    if (!unowned || !adapter.getPr || !adapter.compareFiles)
+        return new Set(ownedNow);
+    const { base_ref } = await adapter.getPr(pr);
+    if (!base_ref)
+        return new Set(ownedNow);
+    const then = ownershipSet(await adapter.compareFiles(base_ref, reviewedHead));
+    return then ? new Set([...ownedNow, ...then]) : undefined;
+}
+/**
+ * The files hand-resolved inside the merges of `from..to` — the one reading
+ * of the merge check both the recheck and dispatch's system re-trigger
+ * classifier make. No check wired ⇒ none. Degraded (git could not tell) keeps
+ * the delta-only classification, but is recorded as an event and a durable
+ * anomaly row — never silently quieter. `via` names a caller other than the
+ * recheck.
+ */
+export async function verifyMerges(store, resolve, from, to, pr, via) {
+    if (!resolve)
+        return [];
+    const res = await resolve(from, to, pr);
+    if (res.degraded) {
+        store.logEvent("recheck_merge_verify_degraded", pr, { from, to, ...(via ? { via } : {}) });
+        store.logAnomaly("recheck_merge_verify_degraded", pr, null, `merge-verify degraded ${from.slice(0, 7)}→${to.slice(0, 7)}${via ? ` at ${via}` : ""} — delta-only classification kept`);
+    }
+    return res.files;
+}
+/**
+ * One trigger, start to finish. Returns the plan so callers (and tests) can see
+ * exactly why a trigger cost nothing.
+ */
+export async function runRecheck(deps, req) {
+    const { cfg, store } = deps;
+    const log = deps.log ?? (() => { });
+    const now = deps.now ?? (() => new Date());
+    const done = (plan) => {
+        if (plan.action === "noop")
+            store.logEvent("recheck_noop", req.pr, {
+                trigger: req.trigger,
+                reason: plan.reason,
+                delta_class: plan.class,
+                files: plan.classification?.files.map((f) => `${f.filename} (${f.reason})`) ?? [],
+            });
+        return plan;
+    };
+    // Deploy-window drain: generate no recheck nudge at all —
+    // prefer not creating work over hold-then-flush, because the session the
+    // nudge would wake is about to be killed by the deploy. The reconcile
+    // push-backstop re-raises the trigger after the lift.
+    if (store.drainState().draining)
+        return done({ action: "noop", reason: "draining", class: "empty" });
+    if (!cfg.recheck.enabled || !triggerEnabled(cfg, req.trigger))
+        return done({ action: "noop", reason: "disabled", class: "empty" });
+    // Cheapest refusal first: ping-pong owns the author reply.
+    if (req.trigger === "author_reply")
+        return done(planRecheck({ ...emptyPlanInput(req), standing: "APPROVE" }));
+    const mark = store.reviewedHead(req.pr);
+    if (standingVerdict(mark) !== "APPROVE")
+        return done({ action: "noop", reason: "no-standing-approval", class: "empty" });
+    const row = store.getPr(req.pr);
+    if (!row || row.state === "closed")
+        return done({ action: "noop", reason: "pr-not-open", class: "empty" });
+    // A pause stops this PR's review work, a nudge included — it defers the
+    // question, never loses it. A push question is asked again by the reconcile
+    // backstop once the pause lifts; a CI or base-advance question has no such
+    // sweep, so it goes on to its claim and its nudge is held until the resume
+    // (`deferWhilePaused` below).
+    if (row.paused && req.trigger === "push")
+        return done({ action: "noop", reason: "paused", class: "empty" });
+    const head = req.head_sha || row.head_sha;
+    if (head.toLowerCase() !== row.head_sha.toLowerCase())
+        return done({ action: "noop", reason: "stale-head", class: "empty" });
+    const lastReviewed = mark.head_sha;
+    // Refuse before spending a single API call on a head we already decided.
+    if (unchangedHeadNoop(req.trigger, head, lastReviewed, req.ci))
+        return done({ action: "noop", reason: "unchanged-head", class: "empty" });
+    // The range the delta is read over — and the one its merges are checked in.
+    const range = req.trigger === "base_advance" && req.base
+        ? { from: req.base.before, to: req.base.after }
+        : { from: lastReviewed, to: head };
+    if (!deps.adapter.compareFiles || !deps.adapter.listPrFiles)
+        return done({ action: "noop", reason: "no-delta-source", class: "empty" });
+    let delta;
+    let prFiles;
+    try {
+        delta = await deps.adapter.compareFiles(range.from, range.to);
+        prFiles = ownershipSet(await deps.adapter.listPrFiles(req.pr));
+        // Ownership is the union of the reviewed head's and the current head's —
+        // see reviewedOwnership. A base advance leaves the
+        // head where it was reviewed, so there is nothing to revert. A truncated
+        // listing leaves ownership unknown (undefined): every delta file is then
+        // significant.
+        if (req.trigger !== "base_advance")
+            prFiles = await reviewedOwnership(deps.adapter, req.pr, lastReviewed, delta, prFiles);
+    }
+    catch (err) {
+        // A read failure is not evidence of anything. A question the reconcile
+        // push backstop asks again — a push, or a benign CI result at a new head,
+        // whose push question is the same — upholds and is asked once the read
+        // recovers. An adverse CI result is asked whatever its delta holds, so it
+        // goes on with the delta UNREAD and the session is told so. A base advance
+        // is NOT asked unread: almost every one touches no PR-owned file, and
+        // waking a session on an advance nobody could classify is the delta-blind
+        // staleness check the recheck exists to avoid. It upholds, with this
+        // anomaly row as its record — nothing asks it again.
+        const askUnread = ciIsAdverse(req.ci?.conclusion);
+        log(`recheck: #${req.pr} delta read failed`, err);
+        store.logEvent("recheck_delta_failed", req.pr, {
+            trigger: req.trigger,
+            error: String(err),
+            asked_unread: askUnread,
+        });
+        // Durable anomaly row, quiet class: DB-only, reviewed at the daily
+        // heartbeat.
+        store.logAnomaly("recheck_delta_failed", req.pr, null, `delta read failed (${req.trigger}): ${String(err)} — ${askUnread
+            ? "asked with the delta unread"
+            : req.trigger === "base_advance"
+                ? "upheld unread; nothing asks this base advance again"
+                : "the reconcile push backstop asks again"}`);
+        if (!askUnread)
+            return done({ action: "noop", reason: "no-delta-source", class: "empty" });
+        delta = unreadDelta();
+        prFiles = undefined;
+    }
+    // Conflict resolutions are never trivial: ask git which files in this
+    // delta's merges were hand-resolved.
+    const resolvedFiles = await verifyMerges(store, deps.resolvedFilesInMerges, range.from, range.to, req.pr);
+    const plan = planRecheck({
+        trigger: req.trigger,
+        standing: standingVerdict(mark),
+        last_reviewed_sha: lastReviewed,
+        head_sha: head,
+        delta,
+        ...(prFiles ? { prFiles: [...prFiles] } : {}),
+        resolvedFiles,
+        ...(req.ci ? { ci: req.ci } : {}),
+    });
+    if (store.getPr(req.pr)?.head_sha.toLowerCase() !== head.toLowerCase())
+        return done({ action: "noop", reason: "stale-head", class: "empty" });
+    // Carry-forward: a withheld approval pinned to an old sha would be stranded
+    // — the retry no-ops on "head-moved", and the recheck can never approve.
+    // When the delta itself upholds (empty/trivial), the never-posted approval
+    // moves with the head, so green CI at the NEW head releases it. A
+    // significant delta carries only after the session's explicit uphold
+    // (watcher below).
+    if (plan.action === "noop") {
+        if ((plan.reason === "empty-delta" || plan.reason === "trivial-delta") &&
+            head !== lastReviewed) {
+            carryWithheldMark(store, req.pr, head, `recheck-noop:${plan.reason}`, log);
+            // A trivial/empty answer is terminal for this head: claim it, so the
+            // reconcile backstop (below in reconcile.ts) never re-classifies the
+            // same question every sweep. No wake goes out, so no receipt token can
+            // ever exist for it: `nudge: false` keeps the undelivered sweep from
+            // reading its absence as a lost nudge and releasing it.
+            store.claimRecheck(req.pr, recheckFingerprint(req, head), {
+                head_sha: head,
+                trigger: req.trigger,
+                reason: `noop:${plan.reason}`,
+                nudge: false,
+            });
+        }
+        return done(plan);
+    }
+    // The runaway guard: one nudge per (trigger, head, evidence). Without it a
+    // reconcile replay or a redelivered webhook re-asks the same question and
+    // pays for it every time.
+    const fingerprint = recheckFingerprint(req, head);
+    if (store.hasRecheck(req.pr, fingerprint))
+        return done({
+            action: "noop",
+            reason: "already-rechecked",
+            class: plan.class,
+            classification: plan.classification,
+        });
+    const order = {
+        pr: req.pr,
+        title: row.title,
+        trigger: req.trigger,
+        standing_verdict: "APPROVE",
+        last_reviewed_sha: lastReviewed,
+        head_sha: head,
+        worktree: (deps.worktreeFor ?? prWorktreeRel)(req.pr),
+        // A base advance's delta is the base branch's range, not anything since
+        // the reviewed head: the evidence names the range that was compared.
+        evidence: req.trigger === "base_advance" && req.base
+            ? `the base branch \`${req.base.branch}\` advanced ${range.from.slice(0, 12)}→${range.to.slice(0, 12)}; ${plan.evidence}`
+            : plan.evidence,
+        files: plan.classification.files,
+        resolved_files: resolvedFiles,
+        decision_file: recheckDecisionFile(req.pr, head),
+        issued_at: now().toISOString(),
+    };
+    const render = deps.renderPrompt ?? defaultRecheckPrompt;
+    // The repo facts for the files the session must review
+    // (the significant ones; every delta file when none is) — "" unless
+    // lessons are delivered. Bounded and total: never a reason to hold or lose
+    // the nudge.
+    let facts = "";
+    if (deps.repoFacts) {
+        const touched = plan.classification.significant.length
+            ? plan.classification.significant.map((f) => f.filename)
+            : plan.classification.files.map((f) => f.filename);
+        try {
+            facts = await deps.repoFacts({
+                pr: req.pr,
+                title: row.title,
+                paths: touched,
+                head_sha: head,
+                purpose: "recheck",
+            });
+        }
+        catch (err) {
+            log(`recheck: #${req.pr} repo facts unavailable (ignored)`, err);
+            facts = "";
+        }
+        if (typeof facts !== "string")
+            facts = "";
+    }
+    // Mid-round nudges are held and flushed at round end — the PR's one main
+    // pi is never given two instructions at once.
+    let delivered;
+    let claimed = false;
+    try {
+        const payload = stampPrompt(withRepoFacts(render(order), facts), recheckPromptMarker(req.pr, fingerprint));
+        if (store.getPr(req.pr)?.head_sha.toLowerCase() !== head.toLowerCase())
+            return done({ action: "noop", reason: "stale-head", class: "empty" });
+        if (standingVerdict(store.reviewedHead(req.pr)) !== "APPROVE")
+            return done({ action: "noop", reason: "no-standing-approval", class: "empty" });
+        // A pause that landed while the reads ran: a push question is asked again
+        // by the reconcile backstop once it lifts.
+        if (req.trigger === "push" && store.getPr(req.pr)?.paused)
+            return done({ action: "noop", reason: "paused", class: "empty" });
+        claimed = store.db.transaction(() => {
+            if (!store.claimRecheck(req.pr, fingerprint, {
+                head_sha: head,
+                trigger: req.trigger,
+                reason: plan.evidence,
+                ...(req.trigger !== "push"
+                    ? { delivery: { payload, reason: recheckWakeReason(req.trigger) } }
+                    : {}),
+            }))
+                return false;
+            // A same-head question (an adverse CI conclusion, a base advance) is new
+            // evidence at a head already reviewed. Recorded on the mark the posting
+            // guard reads, so the change request it may lead to is not refused as a
+            // duplicate of the review that stands (guard 2).
+            if (head === lastReviewed) {
+                store.noteNewEvidence(req.pr, now().toISOString());
+                store.logEvent("recheck_evidence_noted", req.pr, {
+                    trigger: req.trigger,
+                    head_sha: head,
+                    evidence: plan.evidence,
+                });
+            }
+            return true;
+        })();
+        if (!claimed)
+            return done({
+                action: "noop",
+                reason: "already-rechecked",
+                class: plan.class,
+                classification: plan.classification,
+            });
+        delivered = await wakeOrHold({ store, inject: deps.inject, log }, req.pr, 
+        // The receipt token distinguishes confirmed delivery from owed work.
+        // Pushes can be regenerated; CI/base questions retain these exact bytes.
+        payload, recheckWakeReason(req.trigger), 
+        // A push question the reconcile backstop asks again; a CI or base-advance
+        // question uses its durable payload, so its claim stays and the wake is held
+        // for the flush paths rather than released on a failed injection — and
+        // held, not delivered, while the PR is paused.
+        { holdOnFailure: req.trigger !== "push", deferWhilePaused: req.trigger !== "push" });
+    }
+    catch (err) {
+        // Pushes have a backstop. Other triggers retain the claim and exact
+        // payload so a failed injection cannot consume their only question.
+        if (claimed && req.trigger === "push")
+            store.releaseRecheck(req.pr, fingerprint);
+        store.logEvent("recheck_delivery_failed", req.pr, {
+            trigger: req.trigger,
+            head_sha: head,
+            error: String(err),
+        });
+        log(`recheck: #${req.pr} delivery failed — ${req.trigger === "push" ? "claim released for retry" : "durable question retained when claimed"}`, err);
+        return done({
+            action: "noop",
+            reason: "delivery-failed",
+            class: plan.class,
+            classification: plan.classification,
+        });
+    }
+    store.logEvent("recheck_nudged", req.pr, {
+        trigger: req.trigger,
+        head_sha: head,
+        last_reviewed_sha: lastReviewed,
+        delta_class: plan.class,
+        significant: plan.classification.significant.map((f) => f.filename),
+        evidence: plan.evidence,
+        delivered,
+    });
+    log(`recheck: #${req.pr} nudged (${req.trigger}, ${plan.classification.significant.length} file(s)) — ${delivered}`);
+    return { ...plan, delivered, order };
+}
+function triggerEnabled(cfg, trigger) {
+    switch (trigger) {
+        case "push":
+            return cfg.recheck.on_push;
+        case "ci":
+            return cfg.recheck.on_ci;
+        case "base_advance":
+            return cfg.recheck.on_base_advance;
+        case "author_reply":
+            return true; // always reaches the ping-pong no-op
+    }
+}
+function emptyPlanInput(req) {
+    return {
+        trigger: req.trigger,
+        standing: null,
+        last_reviewed_sha: "",
+        head_sha: req.head_sha ?? "",
+        delta: [],
+    };
+}
+/**
+ * A base branch moved: fan the advance out to the PRs that target it and hold
+ * a standing approval. Every other PR is skipped without an API call.
+ */
+export async function runBaseAdvance(deps, advance) {
+    const out = new Map();
+    const log = deps.log ?? (() => { });
+    if (!deps.cfg.recheck.enabled || !deps.cfg.recheck.on_base_advance)
+        return out;
+    // Deploy-window drain: skip the whole fan-out before it spends per-PR API
+    // calls (runRecheck would refuse each one anyway).
+    if (deps.store.drainState().draining)
+        return out;
+    for (const row of deps.store.allPrs()) {
+        if (row.state === "closed")
+            continue;
+        if (standingVerdict(deps.store.reviewedHead(row.number)) !== "APPROVE")
+            continue;
+        if (deps.adapter.getPr) {
+            try {
+                // Called on the adapter, never through a detached reference: the real
+                // GitHubAdapter's methods are class methods and need their `this`.
+                const ref = await deps.adapter.getPr(row.number);
+                // GitHub already says closed: there is nothing left to audit, and the
+                // reconcile closed-sync settles the row.
+                if (ref.state === "closed" || ref.merged)
+                    continue;
+                if (ref.base_ref && ref.base_ref !== advance.branch)
+                    continue;
+            }
+            catch (err) {
+                log(`recheck: #${row.number} base ref lookup failed`, err);
+                continue;
+            }
+        }
+        out.set(row.number, await runRecheck(deps, { pr: row.number, trigger: "base_advance", base: advance }));
+    }
+    return out;
+}
+export function validateRecheckDecision(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return { ok: false, error: "not an object" };
+    const v = raw;
+    if (typeof v.pr === "string" && /^\d+$/.test(v.pr))
+        v.pr = Number(v.pr);
+    if (typeof v.pr !== "number" || !Number.isInteger(v.pr))
+        return { ok: false, error: "pr must be an integer" };
+    if (typeof v.head_sha !== "string" || v.head_sha.length === 0)
+        return { ok: false, error: "head_sha must be a non-empty string" };
+    const raw_outcome = typeof v.outcome === "string" ? v.outcome.trim().toLowerCase() : "";
+    // NOT a rejection: an unrecognised outcome (including "approve" and
+    // "needs_human", which a session may reach for out of round habit) becomes
+    // the default — uphold. The recheck path has no other verdict to give.
+    const coerced = raw_outcome === "uphold" || raw_outcome === "request_changes"
+        ? undefined
+        : String(v.outcome ?? "");
+    const outcome = raw_outcome === "request_changes" ? "request_changes" : "uphold";
+    return {
+        ok: true,
+        decision: {
+            pr: v.pr,
+            head_sha: v.head_sha,
+            outcome,
+            ...(typeof v.reason === "string" ? { reason: v.reason.trim().slice(0, 800) } : {}),
+        },
+        ...(coerced !== undefined ? { coerced } : {}),
+    };
+}
+/**
+ * Consumes `verdict/pr-<n>-recheck-<head12>.json`. It touches GitHub not at
+ * all: on `uphold` there is nothing to say, and on `request_changes` the
+ * session has already posted the review through the gated scripts — the daemon
+ * only moves the lifecycle state.
+ *
+ * Neither outcome moves the reviewed-head mark to a new head. The mark
+ * records what was really REVIEWED and posted; an upheld recheck posted
+ * nothing, and stamping it would make the no-new-evidence guard swallow a
+ * genuine review re-request at that head. A change request the session posted
+ * was stamped by the posting route itself; the watcher only writes its
+ * decided verdict onto that stamp (`settleChangeRequest`). The recheck's own
+ * runaway guard is the `rechecks` claim table.
+ */
+export class RecheckWatcher {
+    deps;
+    watcher = null;
+    inFlight = new Set();
+    processedDir;
+    constructor(deps) {
+        this.deps = deps;
+        this.processedDir = join(deps.verdictDir, "processed");
+    }
+    start() {
+        mkdirSync(this.deps.verdictDir, { recursive: true });
+        void this.sweep();
+        this.watcher = watch(this.deps.verdictDir, (_event, filename) => {
+            const name = filename ? String(filename) : "";
+            if (RECHECK_FILE_RE.test(name))
+                void this.handleFile(name);
+        });
+    }
+    stop() {
+        this.watcher?.close();
+        this.watcher = null;
+    }
+    /** One PR's decisions in name order, different PRs side by side: a file
+     * still being written is waited out for seconds and must not
+     * hold another PR's decision behind it. */
+    async sweep() {
+        if (!existsSync(this.deps.verdictDir))
+            return [];
+        const byPr = new Map();
+        for (const name of readdirSync(this.deps.verdictDir).sort()) {
+            const match = RECHECK_FILE_RE.exec(name);
+            if (!match)
+                continue;
+            byPr.set(match[1], [...(byPr.get(match[1]) ?? []), name]);
+        }
+        const done = [];
+        await Promise.all([...byPr.values()].map(async (names) => {
+            for (const name of names)
+                if (await this.handleFile(name))
+                    done.push(name);
+        }));
+        return done.sort();
+    }
+    archive(name) {
+        mkdirSync(this.processedDir, { recursive: true });
+        const ts = (this.deps.now ?? (() => new Date()))().toISOString().replace(/[:.]/g, "-");
+        try {
+            renameSync(join(this.deps.verdictDir, name), join(this.processedDir, `${ts}-${name}`));
+        }
+        catch (err) {
+            this.deps.log?.(`recheck: could not archive ${name}`, err);
+        }
+    }
+    /**
+     * Parse `state/findings/pr-<n>-recheck-<head12>.json` into `round_findings`.
+     *
+     * A recheck owns no round row, so its entries are attributed to the round
+     * whose verdict it just moved — the PR's reviewed-head mark, falling back to
+     * its highest round number. Keys are prefixed `recheck:<head12>:` so a
+     * recheck's rows can never collide with that round's own.
+     */
+    async recordRecheckFindings(pr, headSha) {
+        const dir = this.deps.findingsDir;
+        if (!dir)
+            return;
+        try {
+            const path = join(dir, recheckDecisionFile(pr, headSha));
+            const store = this.deps.store;
+            const roundNo = store.reviewedHead(pr)?.round_no ??
+                store.roundsFor(pr).reduce((m, r) => (r.round_no > m ? r.round_no : m), 0);
+            const parsed = readFindingsRecord(path, pr, roundNo);
+            if (parsed.status !== "ok" || !parsed.record) {
+                store.logEvent("recheck_findings_record_absent", pr, {
+                    head_sha: headSha,
+                    status: parsed.status,
+                });
+                this.deps.log?.(`recheck: #${pr} moved the verdict with no findings record (${parsed.status}) — decision stands`);
+                return;
+            }
+            const entries = parsed.record.findings.map((f) => ({
+                ...f,
+                key: `${recheckKeyPrefix(headSha)}${f.key}`,
+            }));
+            store.recordRoundFindings({ pr, round_id: null, round_no: roundNo, head_sha: headSha }, entries);
+            store.logEvent("recheck_findings_recorded", pr, {
+                head_sha: headSha,
+                round_no: roundNo,
+                entries: entries.length,
+            });
+        }
+        catch (err) {
+            this.deps.log?.(`recheck: #${pr} findings record read failed`, err);
+        }
+    }
+    /**
+     * The lifecycle half of a change request the session posted. The review on
+     * GitHub is the standing decision at its head: when the shell stamped it at
+     * the head the mark already held, the mark keeps the verdict it had, so the
+     * decided verdict is written here — whether it posted as REQUEST_CHANGES or
+     * guard 1 softened it to a COMMENT (a person approved the head), the same
+     * enrichment a round's verdict gets. A mark still reading APPROVE posted
+     * holds no post of this decision and is left as it is. The lifecycle moves to awaiting_author
+     * unless newer work owns the PR — a round running, or a person's queued
+     * re-review request — which this answer must not settle or erase; that
+     * work's own verdict decides. The PR's head is GitHub's and is never
+     * rewound to the decision's.
+     */
+    settleChangeRequest(pr, headSha, file) {
+        const { store } = this.deps;
+        const mark = store.reviewedHead(pr);
+        if (mark &&
+            mark.head_sha.toLowerCase() === headSha.toLowerCase() &&
+            (mark.posted_event === "REQUEST_CHANGES" || mark.posted_event === "COMMENT") &&
+            standingVerdict(mark) !== "REQUEST_CHANGES")
+            store.recordReviewedVerdict(pr, mark.head_sha, "REQUEST_CHANGES");
+        const row = store.getPr(pr);
+        if (row?.state === "reviewing" ||
+            (row?.state === "queued" && row.trigger_provenance === "human")) {
+            store.logEvent("recheck_lifecycle_deferred", pr, {
+                file,
+                head_sha: headSha,
+                state: row.state,
+                trigger_provenance: row.trigger_provenance ?? null,
+            });
+            return;
+        }
+        applyEvent(store, pr, { type: "verdict", verdict: "REQUEST_CHANGES" }, {}, {
+            botLogin: this.deps.cfg.github.bot_login,
+            ...(this.deps.now ? { now: this.deps.now } : {}),
+            reason: "recheck:request-changes",
+        });
+    }
+    superseded(pr, head) {
+        const { store } = this.deps;
+        const mark = store.reviewedHead(pr);
+        if (!mark || mark.head_sha.toLowerCase() === head.toLowerCase())
+            return false;
+        if (mark.head_sha.toLowerCase() === store.getPr(pr)?.head_sha.toLowerCase())
+            return true;
+        const claims = store
+            .rechecksFor(pr)
+            .filter((claim) => claim.head_sha.toLowerCase() === head.toLowerCase());
+        return claims.some((claim) => mark.reviewed_at > claim.created_at);
+    }
+    async handleFile(name) {
+        const match = RECHECK_FILE_RE.exec(name);
+        if (!match || this.inFlight.has(name))
+            return false;
+        this.inFlight.add(name);
+        try {
+            const path = join(this.deps.verdictDir, name);
+            if (!existsSync(path))
+                return false;
+            const pr = Number(match[1]);
+            // fs.watch fires the moment the file appears, often before the
+            // session's write completes, so a single eager read would discard valid
+            // decisions as "unparseable". An unparseable file is waited out while
+            // it is still moving; one that parses is judged at once.
+            const read = await readSettledJson(path, resolvePartialWritePolicy(this.deps.partialWrite));
+            if (read.kind === "missing")
+                return false;
+            const reads = read.reads;
+            const parsed = read.kind === "parsed"
+                ? validateRecheckDecision(read.value)
+                : { ok: false, error: `unparseable: ${read.error}` };
+            if (!parsed.ok || !parsed.decision) {
+                // Malformed is the safe direction here — the standing verdict simply
+                // stays standing. No park, no anomaly round, nothing posted. But say
+                // so out loud: a silent drop would hide a partial-read race.
+                this.deps.store.logEvent("recheck_decision_malformed", pr, {
+                    file: name,
+                    error: parsed.error ?? "unknown",
+                });
+                this.deps.log?.(`recheck: #${pr} decision ${name} malformed after ${reads} read(s) — standing verdict kept (${parsed.error ?? "unknown"})`);
+                this.archive(name);
+                return true;
+            }
+            const d = parsed.decision;
+            if (d.pr !== pr || recheckHead12(d.head_sha) !== match[2].toLowerCase()) {
+                this.deps.store.logEvent("recheck_decision_rejected", pr, {
+                    file: name,
+                    reason: "pr/head do not match the filename",
+                });
+                this.archive(name);
+                return true;
+            }
+            if (parsed.coerced !== undefined)
+                this.deps.store.logEvent("recheck_outcome_coerced", pr, {
+                    file: name,
+                    given: parsed.coerced,
+                    applied: "uphold",
+                });
+            if (this.superseded(pr, d.head_sha)) {
+                this.deps.store.logEvent("recheck_decision_superseded", pr, {
+                    file: name,
+                    head_sha: d.head_sha,
+                });
+                this.archive(name);
+                return true;
+            }
+            if (d.outcome === "request_changes") {
+                // The reasoning behind a backed-down approval. Best-effort
+                // and strictly additive: a missing record here is logged and nothing
+                // else — the decision above is what moves the PR.
+                await this.recordRecheckFindings(pr, d.head_sha);
+                // Ingestion yields: a newer round may have settled in the meantime.
+                if (this.superseded(pr, d.head_sha)) {
+                    this.archive(name);
+                    return true;
+                }
+                // Approval is off the table now — a lingering withheld mark would let
+                // a later green CI re-queue "for the withheld approval" of a PR whose
+                // standing verdict this very decision just flipped.
+                this.deps.store.clearApprovalWithheld(pr);
+                this.settleChangeRequest(pr, d.head_sha, name);
+            }
+            if (d.outcome === "uphold") {
+                // Session-examined significant delta, verdict upheld: the withheld
+                // approval (if any) follows the head.
+                carryWithheldMark(this.deps.store, pr, d.head_sha, "recheck-uphold", (m) => this.deps.log?.(m));
+                // Ledger freshness after the uphold (optional wiring).
+                if (this.deps.checkLedger && this.deps.store.getPr(pr)?.state !== "closed") {
+                    try {
+                        await this.deps.checkLedger(pr, d.head_sha);
+                    }
+                    catch (err) {
+                        this.deps.log?.(`recheck: ledger check failed on #${pr}`, err);
+                    }
+                }
+            }
+            this.deps.store.logEvent(d.outcome === "request_changes" ? "recheck_request_changes" : "recheck_upheld", pr, {
+                file: name,
+                head_sha: d.head_sha,
+                reason: d.reason ?? null,
+            });
+            this.deps.log?.(`recheck: #${pr} ${d.outcome} at ${d.head_sha.slice(0, 7)}`);
+            this.archive(name);
+            return true;
+        }
+        catch (err) {
+            this.deps.log?.(`recheck: ${name} failed`, err);
+            return false;
+        }
+        finally {
+            this.inFlight.delete(name);
+        }
+    }
+}
+//# sourceMappingURL=recheck.js.map