@quickchatai/quickreview 0.0.0-stage → 1.2.0

package/dist/src/reconcile.js

@@ -0,0 +1,840 @@
+// The reconcile poll — the correctness backbone.
+// GitHub never redelivers a failed webhook, so every 5 minutes (and on
+// startup) the daemon rebuilds the truth from the API and forces local state
+// to match. GitHub always wins. Every correction is logged as a
+// `reconcile_correction` event: a rising correction rate is the webhook-health
+// signal the operator watches.
+import { capturedFromIssueComment, capturedFromReview, capturedFromReviewComment, isHumanCapture, recordCapturedComment, } from "./capture.js";
+import { retryWithheldApproval } from "./ciretry.js";
+import { auditUngatedReviews, commentsByReview, hasUngatedApproval, ungatedReviewMessage, } from "./execboundary.js";
+import { ledgerFeedbackSignal } from "./feedback.js";
+import { wakeOrHold } from "./wakes.js";
+import { recheckFingerprint } from "./recheck.js";
+import { recheckPromptMarker } from "@quickchatai/pi-quickreview/src/types.js";
+import { standingVerdict } from "@quickchatai/pi-quickreview/src/standing-review.js";
+import { DEFAULT_ROUND_STALL_GRACE_MIN } from "./config.js";
+import { applyEvent, isBotAuthor, mergedOverBlock } from "./statemachine.js";
+import { botAccountLogin, isOwnContent, isPersonMode, } from "@quickchatai/pi-quickreview/src/identity.js";
+import { performance } from "node:perf_hooks";
+import { yieldToLoop } from "@quickchatai/pi-quickreview/src/yieldloop.js";
+/**
+ * Per-pass bound on the comment-capture sweep: three API reads per
+ * PR, so the sweep must never grow with the whole tracked history. Freshest
+ * local activity first — a PR nobody has touched in weeks is not where a
+ * missed comment lives, and the ones left out are picked up on a later pass as
+ * soon as they move.
+ */
+export const COMMENT_SWEEP_MAX_PRS = 25;
+/**
+ * How long after a PR closes the capture sweep still includes it. The
+ * closed-sync step earlier in the SAME pass is what marks a PR closed, so a
+ * blanket `state !== "closed"` filter would skip exactly the PR that closed
+ * while the daemon was down — the scenario the sweep exists to recover. The
+ * rule: a closed PR is swept when it transitioned this pass, or when its row
+ * last moved (which for a closed PR is the close itself — nothing writes the
+ * row after that) within this window. The watermark below makes the repeat
+ * cost of the window three API reads an hour per closed PR (a closed PR has
+ * no GitHub timestamp in the open list to say a comment arrived), and one
+ * skipped filter check on every other pass.
+ */
+export const COMMENT_SWEEP_CLOSED_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * Wall-clock budget of the undelivered-recheck sweep per pass. Every read in
+ * it is asynchronous and chunked, so this bounds how long the PASS takes (the
+ * steps after it wait), not how long the loop blocks — that is a chunk.
+ */
+export const RECEIPT_SWEEP_BUDGET_MS = 20_000;
+function correction(deps, pr, what, detail, report) {
+    report.corrections++;
+    deps.store.logEvent("reconcile_correction", pr, { what, ...detail });
+    (deps.log ?? (() => { }))(`reconcile: correction ${what}${pr ? ` #${pr}` : ""}`, detail);
+}
+/** Startup repair: a DB round marked running whose worker did not survive the
+ * restart will never produce a verdict — it would sit as a phantom until its
+ * deadline, holding a capacity slot and then corrupting the PR via the
+ * overdue path. Cancel it; if it was the PR's newest round and the PR still
+ * says reviewing, requeue so the lost work is redone. `inFlightPrs` are the
+ * PRs a worker still runs for, or whose round command waits for the next one
+ * (`inFlightPrs` in src/workerliveness.ts); a boot that finds no worker at all
+ * finds every PR idle with its JSONL.
+ *
+ * A round that still owes a POSTING is no phantom: its review is finished and
+ * the outbox delivers it without any session (docs/architecture/
+ * posting-delivery.md). Nor is one whose review is already posted but not yet
+ * settled. Cancelling either would make the outbox abandon the review or the
+ * requeue run the lenses again for a review already on GitHub, so it is left
+ * running (`postingOwed`) and settles from its receipt like any delivered
+ * round. */
+export function reconcileOrphanedRounds(store, inFlightPrs, opts) {
+    const live = new Set(inFlightPrs);
+    const now = opts.now ?? (() => new Date());
+    const log = opts.log ?? (() => { });
+    const cancelled = [];
+    const requeued = [];
+    const keptForPosting = [];
+    for (const round of store.runningRounds()) {
+        if (live.has(round.pr))
+            continue;
+        let owed = false;
+        try {
+            owed = opts.postingOwed?.(round) === true;
+        }
+        catch (err) {
+            log(`startup: #${round.pr} round ${round.round_no} posting debt unreadable`, err);
+        }
+        if (owed) {
+            store.logEvent("orphaned_round_posting_owed", round.pr, {
+                round_id: round.id,
+                round_no: round.round_no,
+                posting_key: round.posting_key,
+            });
+            keptForPosting.push(round.pr);
+            log(`startup: #${round.pr} round ${round.round_no} kept — session lost, but its review posting is still owed or unsettled`);
+            continue;
+        }
+        // `orphan_sweep` is the quiet cause: a worker lives and dies with its
+        // container, so a clean redeploy orphans every round in flight by
+        // construction. It is counted and grouped like every other cause, and it
+        // raises nothing.
+        const replaced = store.db.transaction(() => {
+            store.markRoundCancelled(round.id, "orphaned — worker lost across a restart", "orphan_sweep");
+            store.logEvent("round_orphaned", round.pr, { round_id: round.id, round_no: round.round_no });
+            const row = store.getPr(round.pr);
+            if (row?.state !== "reviewing" || store.hasLaterRound(round.pr, round.round_no))
+                return false;
+            const successorPromoted = store.promoteSuccessor(round.pr);
+            if (!successorPromoted)
+                store.upsertPr({ ...row, state: "queued", trigger_ts: now().toISOString() });
+            store.logEvent("orphaned_round_requeued", round.pr, {
+                round_id: round.id,
+                round_no: round.round_no,
+                successor_promoted: successorPromoted,
+            });
+            return true;
+        })();
+        cancelled.push(round.pr);
+        log(`startup: #${round.pr} round ${round.round_no} cancelled (session lost)`);
+        if (replaced) {
+            requeued.push(round.pr);
+            log(`startup: #${round.pr} requeued — its in-flight round was lost`);
+        }
+    }
+    return { cancelled, requeued, kept_for_posting: keptForPosting };
+}
+/** One reconcile pass. Never throws: per-step failures land in
+ * `report.errors` so a single bad PR or a flaky API call cannot stall the
+ * daemon. */
+export async function reconcileOnce(deps) {
+    const { store, cfg, adapter } = deps;
+    const now = deps.now ?? (() => new Date());
+    // The bot ACCOUNT: whose PRs are a bot's and whose captured comments are not
+    // a human's. "" in person mode (`[github] auth = "user"`), where the
+    // configured login is the person's: their PRs are reviewed, and their own
+    // comments are told from the reviewer's by its marker (identity.ts).
+    const botLogin = botAccountLogin(cfg.github);
+    const report = {
+        ran_at: now().toISOString(),
+        open_prs: 0,
+        triggered: [],
+        closed: [],
+        backfilled_comments: 0,
+        captured_comments: 0,
+        corrections: 0,
+        errors: [],
+    };
+    const step = async (name, fn) => {
+        try {
+            // Every step starts on a fresh event-loop turn, so a pass is never one
+            // synchronous span even when its reads answer without real I/O (a
+            // cache, a stub) — the longest span is one step's own work.
+            await yieldToLoop();
+            await fn();
+        }
+        catch (err) {
+            report.errors.push(`${name}: ${String(err)}`);
+            (deps.log ?? (() => { }))(`reconcile: step ${name} failed`, err);
+        }
+    };
+    // ---- 1. open-PR truth ---------------------------------------------------
+    const open = new Map();
+    let openListed = false;
+    await step("listOpenPrs", async () => {
+        for (const pr of await adapter.listOpenPrs())
+            open.set(pr.number, pr);
+        openListed = true;
+        report.open_prs = open.size;
+        report.open_list = [...open.values()].map((p) => ({
+            number: p.number,
+            title: p.title,
+            author: p.author,
+            draft: p.draft,
+            updated_at: p.updated_at,
+        }));
+        for (const pr of open.values()) {
+            if (isBotAuthor(pr.author, botLogin))
+                continue;
+            const local = store.getPr(pr.number);
+            if (!local)
+                continue; // untriggered PRs are not tracked (no sweeps)
+            if (local.head_sha !== pr.head_sha || local.title !== pr.title) {
+                const pushed = store.db.transaction(() => {
+                    const before = store.getPr(pr.number);
+                    const result = applyEvent(store, pr.number, { type: "track" }, { title: pr.title, head_sha: pr.head_sha, author: pr.author }, { botLogin, now });
+                    const changed = !result.skipped && before !== undefined && before.head_sha !== pr.head_sha;
+                    if (changed)
+                        store.logEvent("head_push", pr.number, { head_sha: pr.head_sha, source: "reconcile" });
+                    return changed;
+                })();
+                if (pushed && deps.onHeadPush) {
+                    // After the track so the recheck reads the updated row. Errors are
+                    // contained: a failed recheck must not abort the reconcile pass.
+                    try {
+                        await deps.onHeadPush(pr.number, pr.head_sha);
+                    }
+                    catch (err) {
+                        report.errors.push(`onHeadPush #${pr.number}: ${String(err)}`);
+                        (deps.log ?? (() => { }))(`reconcile: onHeadPush failed #${pr.number}`, err);
+                    }
+                }
+            }
+            else if (deps.onHeadPush) {
+                // Lost-recheck backstop: change-detection
+                // fires onHeadPush exactly once, so a recheck that failed to deliver
+                // (or died with the process) never retried once the head was tracked.
+                // A standing reviewed head that differs from the current head, with
+                // this exact question unclaimed, is re-asked; claimed questions
+                // (nudged, or answered trivially) dedupe before any classification.
+                const reviewed = store.reviewedHead(pr.number);
+                if (reviewed &&
+                    standingVerdict(reviewed) === "APPROVE" &&
+                    reviewed.head_sha !== pr.head_sha &&
+                    !store.hasRecheck(pr.number, recheckFingerprint({ trigger: "push" }, pr.head_sha))) {
+                    (deps.log ?? (() => { }))(`reconcile: recheck backstop #${pr.number} — reviewed ${reviewed.head_sha.slice(0, 7)} != head ${pr.head_sha.slice(0, 7)}, unclaimed`);
+                    try {
+                        await deps.onHeadPush(pr.number, pr.head_sha);
+                    }
+                    catch (err) {
+                        report.errors.push(`onHeadPush(backstop) #${pr.number}: ${String(err)}`);
+                        (deps.log ?? (() => { }))(`reconcile: onHeadPush backstop failed #${pr.number}`, err);
+                    }
+                }
+            }
+            // GitHub owns head truth. A successor can outlive its predecessor and
+            // can also survive a crash after the PR row was corrected, so enforce
+            // this independently of whether THIS pass observed a local head change.
+            // The store preserves predecessor, first-request FIFO time, and sticky
+            // human provenance while coalescing only the target head.
+            const successor = store.successorFor(pr.number);
+            if (successor && successor.head_sha !== pr.head_sha) {
+                store.recordSuccessor({
+                    pr: pr.number,
+                    predecessor_round_id: successor.predecessor_round_id,
+                    head_sha: pr.head_sha,
+                    provenance: successor.provenance,
+                    reason: "reconcile-authoritative-head",
+                });
+            }
+            if (local.state === "closed") {
+                // GitHub says open, we say closed → GitHub wins.
+                correction(deps, pr.number, "reopened", { local: local.state }, report);
+                applyEvent(store, pr.number, { type: "reopened" }, { title: pr.title, head_sha: pr.head_sha, author: pr.author }, { botLogin, now });
+            }
+        }
+    });
+    // ---- 2. triggered-set derivation (both searches) ------------------------
+    await step("triggered-set", async () => {
+        const [labelled, teamed] = await Promise.all([
+            adapter.searchLabelTriggered(),
+            adapter.searchTeamTriggered(),
+        ]);
+        const kinds = ["label", "team_request"];
+        const searches = { label: labelled, team_request: teamed };
+        const current = {
+            label: new Set(labelled.map((item) => item.number)),
+            team_request: new Set(teamed.map((item) => item.number)),
+        };
+        // Snapshot BEFORE writing this poll. GitHub searches expose current levels,
+        // not the edge that created them; this durable previous observation is what
+        // distinguishes a new human request from residue left by an older round.
+        const previous = new Map();
+        for (const pr of open.keys()) {
+            if (!store.getPr(pr))
+                continue; // untriggered PRs acquire observations when first triggered
+            for (const kind of kinds)
+                previous.set(`${pr}:${kind}`, store.triggerLevel(pr, kind));
+        }
+        const grouped = new Map();
+        for (const kind of kinds) {
+            for (const item of searches[kind]) {
+                if (isBotAuthor(item.user?.login ?? "", botLogin) || item.user?.type === "Bot")
+                    continue;
+                const group = grouped.get(item.number) ?? { item, kinds: [] };
+                group.kinds.push(kind);
+                grouped.set(item.number, group);
+            }
+        }
+        // Record both presence and absence. Remove→re-add is a fresh edge even
+        // when its webhook was lost; rows survive daemon restarts. A paused PR's
+        // presence is not recorded: the pause defers handling a fresh request, and
+        // acknowledging its level now would leave no edge to act on after the
+        // resume. Its absence is recorded — that only ever makes a later edge.
+        for (const pr of open.keys()) {
+            const row = store.getPr(pr);
+            if (!row && !grouped.has(pr))
+                continue;
+            for (const kind of kinds) {
+                const present = current[kind].has(pr);
+                if (row?.paused && present)
+                    continue;
+                store.observeTriggerLevel(pr, kind, present);
+            }
+        }
+        for (const [pr, group] of grouped) {
+            const ref = open.get(pr);
+            const local = store.getPr(pr);
+            // A search can lag the close: a PR closed with its trigger still on it
+            // is listed for a pass. Closed is terminal — nothing to queue, nothing
+            // to correct.
+            if (local?.state === "closed")
+                continue;
+            // A tracked PR the searches list but the open list (read this pass)
+            // does not is closed on GitHub with the search lagging, or the open
+            // list is the one lagging. The closed-sync below settles which, from
+            // the PR itself; triggering it first would overwrite the state that
+            // sync reads (a merge over a standing block) and count a correction
+            // for a PR that owes no review. A PR never tracked here is skipped the
+            // same way: nothing would close it, and a genuinely open one the list
+            // lags on is picked up by the next pass.
+            if (openListed && !ref)
+                continue;
+            const meta = {
+                title: ref?.title ?? group.item.title,
+                head_sha: ref?.head_sha ?? local?.head_sha ?? "",
+                author: ref?.author ?? group.item.user?.login ?? "",
+                trigger_ts: local?.trigger_ts ?? group.item.updated_at ?? now().toISOString(),
+            };
+            report.triggered.push(pr);
+            if (local?.paused)
+                continue; // overseer pause-pr: no re-trigger until resumed
+            // Only an observed absent→present transition is a fresh edge. Undefined
+            // is bootstrap history for an existing row (the table is additive on
+            // deploy), not proof a person just acted. A PR never tracked before is
+            // different: its first trigger is the human ask that brings it in.
+            const freshKind = local === undefined
+                ? group.kinds[0]
+                : group.kinds.find((kind) => store.triggerEdgePending(pr, kind) || previous.get(`${pr}:${kind}`) === false);
+            if (local?.state === "reviewing") {
+                // A fresh request can upgrade an already-recorded pushed-head
+                // successor to human provenance. Same-head requests need no second
+                // round: the active one already covers that head.
+                if (freshKind)
+                    applyEvent(store, pr, { type: "trigger", source: freshKind }, meta, {
+                        botLogin,
+                        now,
+                        reason: `reconcile:${freshKind}:reviewing`,
+                    });
+                continue;
+            }
+            if (local?.state === "queued") {
+                // Already queued, but a fresh request upgrades a system-queued round
+                // to the person's ask, so dispatch never skips it as a trivial
+                // system re-trigger. The edge is recorded above and will not be seen
+                // again.
+                if (freshKind)
+                    applyEvent(store, pr, { type: "trigger", source: freshKind }, meta, {
+                        botLogin,
+                        now,
+                        reason: `reconcile:${freshKind}:queued`,
+                    });
+                continue;
+            }
+            const reviewed = store.reviewedHead(pr);
+            const pushHandled = !freshKind &&
+                reviewed !== undefined &&
+                standingVerdict(reviewed) === "APPROVE" &&
+                reviewed.head_sha !== meta.head_sha &&
+                store.hasRecheck(pr, recheckFingerprint({ trigger: "push" }, meta.head_sha));
+            if (pushHandled) {
+                // The targeted APPROVE path already owns this head. A standing label or
+                // team request is residue, not a second blank-slate review. A genuinely
+                // new edge still bypasses this branch and gets a full review.
+                store.logEvent("standing_trigger_suppressed", pr, {
+                    head_sha: meta.head_sha,
+                    kinds: group.kinds,
+                });
+                deps.log?.(`reconcile: suppressed standing trigger for #${pr} at rechecked head ${meta.head_sha.slice(0, 10)}`);
+                continue;
+            }
+            // Dry-run never consumes triggers on GitHub, so an already-reviewed
+            // head would re-queue forever; suppress until the head moves.
+            if (cfg.dry_run && meta.head_sha && store.lastVerdictHead(pr) === meta.head_sha) {
+                if (freshKind)
+                    store.acknowledgeTriggerEdges(pr);
+                deps.log?.(`dry-run: suppressing re-trigger of #${pr} at reviewed head ${meta.head_sha.slice(0, 10)}`);
+                continue;
+            }
+            const source = freshKind ?? "reconcile";
+            correction(deps, pr, "triggered-not-queued", { local: local?.state ?? null, source, kinds: group.kinds }, report);
+            applyEvent(store, pr, { type: "trigger", source }, meta, {
+                botLogin,
+                now,
+                reason: `reconcile:${source}`,
+            });
+        }
+    });
+    // Commits outside a round never dispatch a review. A head advance WHILE an
+    // older round owns the PR is different: it is recorded as durable successor
+    // work. Promote obligations whose predecessor became terminal across a
+    // crash/restart; queue publication is idempotent and retains the evidence.
+    await step("successor-obligations", async () => {
+        for (const row of store.allPrs()) {
+            if (store.successorFor(row.number))
+                store.promoteSuccessor(row.number);
+        }
+    });
+    // ---- 2b. undelivered recheck-claim sweep ---------------------------------
+    // `claimRecheck` is written BEFORE the nudge goes out, `releaseRecheck`
+    // fires only on a synchronous throw (which a bridge-level drop is not), and
+    // `rechecks` has no deadline or expiry of its own. Without this sweep a
+    // dropped nudge would leave a claim that suppresses the push-backstop above
+    // (`!store.hasRecheck(...)`) forever: a delta on an APPROVED PR would never
+    // be audited, and the approval would stand over code nobody read.
+    //
+    // The receipt makes it recoverable. A claim past the grace window whose
+    // marker never reached the session is released, and the backstop re-asks on
+    // the next pass. Every ambiguity is a no-op: only a provable absence counts.
+    //
+    // Bounded so it never holds the event loop: it asks only about claims that
+    // can still be lost nudges (`recheckClaimsAwaitingReceipt` — a real nudge,
+    // receipt not yet found, PR not closed), records a found receipt so it is
+    // never asked again, yields a real event-loop turn between claims, stops starting new
+    // claims past its time budget (the rest are asked next pass, least
+    // recently asked first), and is skipped on the boot's first pass, whose
+    // health is what lifts a deploy drain.
+    await step("undelivered-rechecks", async () => {
+        const receipt = deps.hooks.wakeReceiptPresent;
+        if (!receipt)
+            return;
+        if (deps.receiptSweep === false) {
+            (deps.log ?? (() => { }))("reconcile: undelivered-recheck sweep deferred to the next pass (boot)");
+            return;
+        }
+        const graceMs = (cfg.daemon.round_stall_grace_min ?? DEFAULT_ROUND_STALL_GRACE_MIN) * 60_000;
+        const cutoff = new Date(now().getTime() - graceMs).toISOString();
+        const budgetMs = deps.receiptSweepBudgetMs ?? RECEIPT_SWEEP_BUDGET_MS;
+        const claims = store.recheckClaimsAwaitingReceipt(cutoff);
+        const sweep = { asked: 0, delivered: 0, released: 0, carried: 0 };
+        const started = performance.now();
+        for (const [i, claim] of claims.entries()) {
+            // Always at least one claim, so a tiny budget still makes progress.
+            if (i > 0 && performance.now() - started > budgetMs) {
+                sweep.carried = claims.length - i;
+                break;
+            }
+            // A real macrotask turn per claim: whatever the receipt hook does, the
+            // sweep is never one synchronous span.
+            await yieldToLoop();
+            // A held or still-pending nudge is not a lost one.
+            if (store.hasRunningRound(claim.pr) || store.hasHeldWakes(claim.pr)) {
+                store.markRecheckReceiptChecked(claim.pr, claim.fingerprint);
+                continue;
+            }
+            const claimedMs = Date.parse(claim.created_at);
+            if (!Number.isFinite(claimedMs))
+                continue;
+            sweep.asked++;
+            const landed = await receipt.call(deps.hooks, claim.pr, recheckPromptMarker(claim.pr, claim.fingerprint), claimedMs);
+            if (landed === true) {
+                // Delivered is a fact: recorded once, never re-read.
+                store.markRecheckReceipt(claim.pr, claim.fingerprint);
+                sweep.delivered++;
+                continue;
+            }
+            if (landed !== false) {
+                // No evidence either way — never guess; ask again on a later pass.
+                store.markRecheckReceiptChecked(claim.pr, claim.fingerprint);
+                continue;
+            }
+            if (claim.trigger === "ci" || claim.trigger === "base_advance") {
+                const enabled = cfg.recheck.enabled &&
+                    (claim.trigger === "ci" ? cfg.recheck.on_ci : cfg.recheck.on_base_advance);
+                if (!enabled || store.drainState().draining) {
+                    store.markRecheckReceiptChecked(claim.pr, claim.fingerprint);
+                    continue;
+                }
+                const delivery = store.recheckDelivery(claim.pr, claim.fingerprint);
+                if (!delivery ||
+                    delivery.reason !== `recheck:${claim.trigger}` ||
+                    !delivery.payload
+                        .split(/\r?\n/)
+                        .includes(recheckPromptMarker(claim.pr, claim.fingerprint))) {
+                    store.markRecheckReceiptChecked(claim.pr, claim.fingerprint);
+                    if (!store.lastEventAt("recheck_payload_unknown", claim.pr))
+                        store.logEvent("recheck_payload_unknown", claim.pr, { fingerprint: claim.fingerprint });
+                    continue;
+                }
+                const row = store.getPr(claim.pr);
+                const standing = store.reviewedHead(claim.pr);
+                if (row?.head_sha.toLowerCase() !== claim.head_sha.toLowerCase() ||
+                    (standing && standingVerdict(standing) !== "APPROVE")) {
+                    store.releaseRecheck(claim.pr, claim.fingerprint);
+                    store.logEvent("recheck_delivery_superseded", claim.pr, {
+                        fingerprint: claim.fingerprint,
+                    });
+                    continue;
+                }
+                if (!standing) {
+                    store.markRecheckReceiptChecked(claim.pr, claim.fingerprint);
+                    continue;
+                }
+                await wakeOrHold({ store, inject: deps.hooks.inject.bind(deps.hooks), log: deps.log }, claim.pr, delivery.payload, delivery.reason, { holdOnFailure: true, deferWhilePaused: true });
+                store.markRecheckReceiptChecked(claim.pr, claim.fingerprint);
+                continue;
+            }
+            store.releaseRecheck(claim.pr, claim.fingerprint);
+            sweep.released++;
+            correction(deps, claim.pr, "recheck-claim-released-undelivered", {
+                fingerprint: claim.fingerprint,
+                head_sha: claim.head_sha,
+                trigger: claim.trigger,
+                claimed_at: claim.created_at,
+            }, report);
+        }
+        report.receipt_sweep = sweep;
+        if (sweep.carried > 0)
+            (deps.log ?? (() => { }))(`reconcile: undelivered-recheck sweep hit its ${budgetMs} ms budget — ${sweep.carried} claim(s) carried to the next pass`);
+    });
+    // ---- 2c. stale-trigger residue sweep -------------------------------------
+    // A settled PR (tracked/awaiting_author, no round running) never
+    // legitimately carries `stale_recheck` or a `trigger_ts`: both are consumed
+    // by dispatch and cleared when a round settles. Left behind, they would
+    // misclassify the NEXT explicit re-review as a staleness round and let it
+    // jump the FIFO on an old timestamp. Swept after the triggered-set step, so
+    // a PR GitHub still lists as triggered has already been re-queued and is
+    // never touched.
+    await step("stale-trigger-residue", async () => {
+        for (const local of store.allPrs()) {
+            if (local.state !== "tracked" && local.state !== "awaiting_author")
+                continue;
+            if (!local.stale_recheck && local.trigger_ts === null)
+                continue;
+            if (store.hasRunningRound(local.number))
+                continue;
+            correction(deps, local.number, "stale-trigger-residue-cleared", { state: local.state, stale_recheck: local.stale_recheck, trigger_ts: local.trigger_ts }, report);
+            store.upsertPr({ ...local, stale_recheck: 0, trigger_ts: null });
+        }
+    });
+    // ---- 3. open-PR sync: locally-live PRs GitHub no longer lists as open ----
+    await step("closed-sync", async () => {
+        for (const local of store.allPrs()) {
+            if (local.state === "closed")
+                continue;
+            if (open.has(local.number))
+                continue;
+            let ref = null;
+            try {
+                ref = await adapter.getPr(local.number);
+            }
+            catch (err) {
+                report.errors.push(`getPr #${local.number}: ${String(err)}`);
+                continue;
+            }
+            if (ref.state !== "closed")
+                continue; // listing lag — leave it alone
+            correction(deps, local.number, "pr-closed", { merged: ref.merged, local: local.state }, report);
+            // The existing feedback ledger is the durable owed-memory intent. Commit
+            // it with closure, before a callback can fail or the process can stop.
+            const overBlock = store.db.transaction(() => {
+                const priorState = store.getPr(local.number)?.state;
+                if (priorState === "closed")
+                    return false;
+                const result = applyEvent(store, local.number, { type: "closed" }, { title: ref.title, head_sha: ref.head_sha, author: ref.author }, { botLogin, now });
+                if (result.skipped)
+                    return false;
+                store.logEvent("pr_closed", local.number, { merged: ref.merged, source: "reconcile" });
+                const over = mergedOverBlock(ref.merged, priorState);
+                if (over)
+                    ledgerFeedbackSignal(store, { kind: "merged_over_block", pr: local.number }, {
+                        timezone: cfg.ops.timezone,
+                        now: now(),
+                        memoryEnabled: cfg.openviking.enabled,
+                    });
+                return over;
+            })();
+            if (overBlock && deps.onMergedOverBlock) {
+                try {
+                    await deps.onMergedOverBlock(local.number);
+                }
+                catch (err) {
+                    report.errors.push(`onMergedOverBlock #${local.number}: ${String(err)}`);
+                }
+            }
+            report.closed.push(local.number);
+            try {
+                await deps.hooks.archiveAndClose(local.number);
+            }
+            catch (err) {
+                report.errors.push(`archiveAndClose #${local.number}: ${String(err)}`);
+            }
+        }
+    });
+    // ---- 4. withheld-approval backstop ---------------------------------------
+    // cigate.ts promises that a PR whose approval was withheld for red CI is
+    // re-queued "by the next completion (or the reconcile poll)". The
+    // `ci_completed` webhook is the fast path; this sweep is the backstop for a
+    // lost delivery — without it a missed green would leave the PR waiting on a
+    // verdict that is never re-attempted. Same idiom as every other step:
+    // GitHub (the CI state at the recorded head) always wins, corrections
+    // logged. The retry itself is retryWithheldApproval — the exact function the
+    // webhook path calls — never a copy.
+    if (adapter.listChecks) {
+        await step("withheld-approvals", async () => {
+            for (const local of store.allPrs()) {
+                if (local.state === "closed")
+                    continue;
+                const mark = store.approvalWithheld(local.number);
+                if (!mark)
+                    continue;
+                const outcome = await retryWithheldApproval({
+                    cfg,
+                    store,
+                    adapter: { listChecks: (ref) => adapter.listChecks(ref) },
+                    now,
+                    ...(deps.log ? { log: deps.log } : {}),
+                }, { pr: local.number, head_sha: mark.head_sha });
+                if (outcome.action === "requeued")
+                    correction(deps, local.number, "withheld-approval-requeued", { head_sha: mark.head_sha, ci: outcome.ci }, report);
+            }
+        });
+    }
+    // ---- 5. bot-comment registry backfill ----------------------------------
+    if (deps.backfillRegistry !== false) {
+        await step("registry-backfill", async () => {
+            for (const local of store.allPrs()) {
+                if (local.state === "closed")
+                    continue;
+                try {
+                    for (const id of await adapter.listBotReviewComments(local.number)) {
+                        if (store.isBotComment(id, "review_comment"))
+                            continue;
+                        store.registerBotComment(id, local.number);
+                        report.backfilled_comments++;
+                    }
+                }
+                catch (err) {
+                    report.errors.push(`backfill #${local.number}: ${String(err)}`);
+                }
+            }
+        });
+    }
+    // ---- 5b. human-comment capture sweep -------------------------------------
+    // The webhook is the fast path and GitHub never redelivers, so a comment
+    // posted while the daemon was down would otherwise be permanent evidence
+    // loss rather than a delayed signal. This is the backstop, and it
+    // is deliberately shaped like every other sweep here: READ-ONLY (three list
+    // calls per PR, no mutation anywhere in the path), bounded
+    // (COMMENT_SWEEP_MAX_PRS, freshest first, one API page per source), and
+    // idempotent — dedupe is GitHub's own `(source, comment_id)` identity in
+    // `pr_comments`, so re-running captures nothing twice and an edited comment
+    // is still the same comment.
+    //
+    // It captures ONLY: nothing here routes, wakes a session, stamps a mark or
+    // feeds the [feedback] engine. A tagged comment picked up here gets the tag
+    // recorded and nothing else — the same-day addendum stays tag-gated on the
+    // webhook's feedback path, where a human is in the loop.
+    if (deps.captureComments !== false &&
+        adapter.listReviewCommentsFull &&
+        adapter.listIssueComments &&
+        adapter.listReviewsFull) {
+        await step("comment-capture", async () => {
+            // Recently-closed PRs stay in: closed-sync above marks a
+            // closed-during-downtime PR closed in this very pass, and its comments
+            // are what this backstop exists to recover. `updated_at` is the close
+            // instant for a closed row.
+            const nowMs = now().getTime();
+            const closedRecently = (updated_at) => {
+                const t = Date.parse(updated_at);
+                return Number.isFinite(t) && nowMs - t <= COMMENT_SWEEP_CLOSED_WINDOW_MS;
+            };
+            // A failed open-PR list is UNKNOWN remote state, not a change: keep the
+            // stored remote half, or every PR would re-sweep on the failing pass
+            // and again on the recovering one. A closed PR has left the open list
+            // and with it GitHub's timestamp, so nothing remote moves when a
+            // comment lands on it after the close: inside the recent-close window
+            // its remote half is the current hour instead, and it is re-swept once
+            // an hour.
+            const nowHour = now().toISOString().slice(0, 13);
+            const remoteHalf = (p) => {
+                if (!openListed)
+                    return store.lastCommentSweep(p.number)?.split("|")[1] ?? "";
+                const listed = open.get(p.number);
+                if (listed)
+                    return listed.updated_at;
+                return p.state === "closed" ? `closed@${nowHour}` : "";
+            };
+            const sweepMark = (p) => `${p.updated_at}|${remoteHalf(p)}`;
+            const candidates = store
+                .allPrs()
+                .filter((p) => p.state !== "closed" ||
+                report.closed.includes(p.number) ||
+                closedRecently(p.updated_at))
+                // Change gating (without it every tracked PR costs three reads every
+                // pass): a PR whose row has not moved since the last successful sweep
+                // of it has produced no webhook the sweep could have missed a
+                // *newer* version of than last time — skip it. The watermark is the
+                // row's own `updated_at` PAIRED with GitHub's `updated_at` for the PR
+                // (from the open-PR list above), recorded per PR after a clean sweep.
+                // The remote half is load-bearing: capturing a comment never moves
+                // the local row, so a comment whose webhook was lost (the daemon was
+                // down, no push, no title change) only shows up as GitHub's
+                // timestamp moving.
+                .filter((p) => store.lastCommentSweep(p.number) !== sweepMark(p))
+                .sort((a, b) => a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : a.number - b.number)
+                .slice(0, COMMENT_SWEEP_MAX_PRS);
+            for (const local of candidates) {
+                const n = local.number;
+                let rows;
+                let reviewsFetched = [];
+                let inlineFetched = [];
+                try {
+                    const [inline, top, reviews] = await Promise.all([
+                        adapter.listReviewCommentsFull(n),
+                        adapter.listIssueComments(n),
+                        adapter.listReviewsFull(n),
+                    ]);
+                    reviewsFetched = reviews;
+                    inlineFetched = inline;
+                    rows = [
+                        ...inline.map((c) => capturedFromReviewComment(n, c)),
+                        ...top.map((c) => capturedFromIssueComment(n, c)),
+                        ...reviews.map((r) => capturedFromReview(n, r)),
+                    ];
+                }
+                catch (err) {
+                    report.errors.push(`comment-capture #${n}: ${String(err)}`);
+                    continue;
+                }
+                // The bot's own inline comments in this very read are the
+                // link facts the outcome capture needs (which finding each one
+                // carried) — kept here, at no extra API call. Never breaks the sweep.
+                if (deps.outcomes) {
+                    try {
+                        deps.outcomes.observeBotComments(n, inlineFetched);
+                    }
+                    catch (err) {
+                        (deps.log ?? (() => { }))(`reconcile: outcome facts #${n} failed`, err);
+                    }
+                }
+                for (const c of rows) {
+                    if (!isHumanCapture(c, botLogin))
+                        continue;
+                    // Person mode: the reviewer's own words under the person's login.
+                    if (isOwnContent(cfg.github, c.author, c.body))
+                        continue;
+                    if (recordCapturedComment(store, c, "reconcile"))
+                        report.captured_comments++;
+                }
+                // ---- the exec boundary's OUTCOME layer ------------------------------
+                // The bot's OWN reviews, which `isHumanCapture` discards above, are the
+                // one piece of evidence that does not care HOW a write was made. The
+                // command-string guard is pattern-based and not closed; a review here
+                // that the daemon has no record of posting is a violation whichever
+                // way it got there — and this costs no
+                // API call, because `listReviewsFull` was already fetched above.
+                // Detection only: nothing below mutates GitHub, and nothing here can
+                // withdraw, retract or edit a review (AGENTS.md invariant 2 — structural,
+                // not prompted; there is no such call in this module or its imports).
+                try {
+                    const ungated = auditUngatedReviews(reviewsFetched, local.head_sha, {
+                        reviewIds: store.postedReviewIds(n),
+                        reviewedHead: store.reviewedHead(n) ?? undefined,
+                        migrationPrecheck: store.lastEventAt("migration_collision_comment", n) !== undefined,
+                        postingKeys: new Set(store.roundsFor(n).flatMap((r) => (r.posting_key ? [r.posting_key] : []))),
+                        reviewComments: commentsByReview(inlineFetched),
+                        gatedCommentIds: store.botCommentIds(n),
+                    }, {
+                        botLogin: cfg.github.bot_login,
+                        appSlug: cfg.github.app_slug,
+                        // Person mode: only marker-bearing reviews are the reviewer's.
+                        personMode: isPersonMode(cfg.github),
+                    });
+                    if (ungated.length > 0) {
+                        store.logEvent("ungated_review_detected", n, {
+                            head_sha: local.head_sha,
+                            reviews: ungated,
+                        });
+                        const message = ungatedReviewMessage(n, ungated);
+                        // An unaccounted APPROVE wakes; anything else stays a durable row.
+                        // The asymmetry is the blocker bar's: an approval posted outside
+                        // the gate defeats rule 1, the CI hard-gate and every posting
+                        // guard at once, and it is the outcome any bypass of the exec
+                        // boundary is reaching for.
+                        if (hasUngatedApproval(ungated))
+                            store.logAnomaly("ungated_approval", n, null, message, message);
+                        else
+                            store.logAnomaly("ungated_review", n, null, message);
+                        report.errors.push(`ungated-review #${n}: ${ungated.length} unaccounted bot review(s) at the head`);
+                    }
+                }
+                catch (err) {
+                    // Never let the audit break the sweep it rides on.
+                    report.errors.push(`ungated-review-audit #${n}: ${String(err)}`);
+                }
+                // Watermark only a CLEAN sweep of this PR — a failed read `continue`s
+                // above without one, so it is retried on the next pass.
+                store.markCommentSweep(n, sweepMark(local));
+            }
+        });
+    }
+    // ---- outcome capture -------------------------------------------------------
+    // What became of every posted finding: link each bot comment to its finding,
+    // then decide each finding's fate from the replies, thread decisions, pushes
+    // and later rounds already recorded. Local reads only (state.db and the base
+    // clone's git) — no GitHub call and no gate. Bounded and change-gated inside
+    // `sweep`, and never an error of this pass: it is bookkeeping.
+    if (deps.outcomes) {
+        try {
+            const swept = await deps.outcomes.sweep();
+            if (swept.captured > 0 || swept.errors.length > 0)
+                report.outcomes = swept;
+        }
+        catch (err) {
+            (deps.log ?? (() => { }))("reconcile: outcome capture failed", err);
+        }
+    }
+    // ---- the raw-tier sweep -----------------------------------------------------
+    // The `pr-<n>` OpenViking sessions of closed PRs that are still on the
+    // server (a delete that failed, a close the daemon never saw) — bounded per
+    // pass, every outcome logged by the hook. Run AFTER the closed-sync above,
+    // so a PR closed this pass is already closed in the registry. Never an
+    // error of this pass, whatever happens: memory never blocks reconcile.
+    if (deps.hooks.sweepStaleOvSessions) {
+        try {
+            const swept = await deps.hooks.sweepStaleOvSessions();
+            if (swept)
+                report.ov_sessions = swept;
+        }
+        catch (err) {
+            (deps.log ?? (() => { }))("reconcile: stale openviking-session sweep threw", err);
+        }
+    }
+    // No retired-park migration runs here: `awaiting_human` is not a member of
+    // `PrLifecycleState`, so no row can carry it for a pass to find.
+    store.logEvent("reconcile_pass", null, {
+        open_prs: report.open_prs,
+        triggered: report.triggered.length,
+        closed: report.closed.length,
+        captured_comments: report.captured_comments,
+        corrections: report.corrections,
+        errors: report.errors.length,
+        ...(report.ov_sessions
+            ? {
+                ov_sessions_deleted: report.ov_sessions.deleted.length,
+                ov_sessions_failed: report.ov_sessions.failed.length,
+                ...(report.ov_sessions.error ? { ov_sessions_error: report.ov_sessions.error } : {}),
+            }
+            : {}),
+    });
+    return report;
+}
+//# sourceMappingURL=reconcile.js.map