@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/reconcile.ts

@@ -0,0 +1,1030 @@
+// 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,
+  type CapturedComment,
+} from "./capture.js";
+import type { CheckSummary } from "@quickchatai/pi-quickreview/src/cigate.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, type Config } from "./config.js";
+import type { IssueCommentFull, PrRef, ReviewCommentFull, ReviewFull } from "./github.js";
+import type { OutcomeCapture, OutcomeSweepReport } from "./outcomes.js";
+import { applyEvent, isBotAuthor, mergedOverBlock } from "./statemachine.js";
+import type { RoundRow, StateStore } from "./state.js";
+import type { OvSessionSweepReport, SessionHooks } from "@quickchatai/pi-quickreview/src/types.js";
+import { performance } from "node:perf_hooks";
+import { yieldToLoop } from "@quickchatai/pi-quickreview/src/yieldloop.js";
+
+export interface ReconcileSearchItem {
+  number: number;
+  title: string;
+  user: { login: string; type: string };
+  updated_at: string;
+}
+
+/** The read-only slice of GitHubAdapter reconcile needs. */
+export interface ReconcileAdapter {
+  searchLabelTriggered(): Promise<ReconcileSearchItem[]>;
+  searchTeamTriggered(): Promise<ReconcileSearchItem[]>;
+  listOpenPrs(): Promise<PrRef[]>;
+  getPr(n: number): Promise<PrRef>;
+  listBotReviewComments(n: number): Promise<number[]>;
+  /** Checks at a ref — the withheld-approval backstop reads CI through this.
+   * Optional: a stub-wired daemon without it simply has no backstop. */
+  listChecks?(ref: string): Promise<CheckSummary[]>;
+  /** The comment-capture sweep's three READ sources. All optional and
+   * all-or-nothing: a stub-wired daemon without them simply has no backstop.
+   * Reads only — capture never writes to GitHub. */
+  listReviewCommentsFull?(n: number): Promise<ReviewCommentFull[]>;
+  listIssueComments?(n: number): Promise<IssueCommentFull[]>;
+  listReviewsFull?(n: number): Promise<ReviewFull[]>;
+}
+
+/**
+ * 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;
+
+export interface ReconcileDeps {
+  cfg: Config;
+  store: StateStore;
+  adapter: ReconcileAdapter;
+  hooks: SessionHooks;
+  now?: () => Date;
+  log?: (msg: string, extra?: unknown) => void;
+  /** Registry backfill is an API call per open PR; the daemon runs it every
+   * Nth poll. Default true. */
+  backfillRegistry?: boolean;
+  /** Backstop for the recheck's push trigger: the webhook's `onSynchronize`
+   * is the fast path, but a lost/dead webhook means a post-review push is
+   * otherwise never rechecked — the withheld-approval retry no-ops on a moved
+   * head ("a push re-reviews through its own route") while that route never
+   * fires. Same idiom as the withheld-approval sweep: the daemon wires
+   * runRecheck here, never a copy. */
+  onHeadPush?: (pr: number, head_sha: string) => Promise<void>;
+  /** Backstop: the merged-over-block feedback signal for closes the
+   * webhook missed (GitHub never redelivers). The daemon wires the same
+   * engine sink the webhook path uses; dedupe is the store's. */
+  onMergedOverBlock?: (pr: number) => Promise<void> | void;
+  /** Backstop: capture comments the webhook never saw (GitHub never
+   * redelivers, so a comment posted while the daemon was down would otherwise
+   * be permanent evidence loss). Default on when the adapter can read;
+   * `false` disables it for a poll that must stay cheap. */
+  captureComments?: boolean;
+  /** The outcome capture: handed the bot's OWN inline comments
+   * from the comment sweep's existing read (no extra GitHub call), then run
+   * as its own bounded step after it. Absent ⇒ no outcome capture. Its
+   * failures are its own and never reach `errors`. */
+  outcomes?: Pick<OutcomeCapture, "observeBotComments" | "sweep">;
+  /** The undelivered-recheck sweep. `false` skips it for this pass — the
+   * daemon's boot pass, whose health lifts a deploy drain and which must not
+   * wait on reading session transcripts. */
+  receiptSweep?: boolean;
+  /** How long the sweep may keep STARTING claims in one pass; the rest are
+   * carried to the next. Default RECEIPT_SWEEP_BUDGET_MS. */
+  receiptSweepBudgetMs?: number;
+}
+
+/**
+ * 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;
+
+export interface ReconcileReport {
+  ran_at: string;
+  open_prs: number;
+  triggered: number[];
+  closed: number[];
+  backfilled_comments: number;
+  /** Human comments the sweep captured that the webhook had missed.
+   * A rising number is the same webhook-health signal `corrections` is. */
+  captured_comments: number;
+  corrections: number;
+  errors: string[];
+  /** The raw-tier sweep's outcome — present only when the hooks
+   * manage a raw tier. Deliberately NOT part of `errors`: memory never
+   * blocks, and the boot's first healthy pass (which lifts a deploy drain)
+   * must not wait on the memory engine. */
+  ov_sessions?: OvSessionSweepReport;
+  /** The outcome capture's pass, when it captured anything or
+   * failed. Like `ov_sessions`, deliberately NOT part of `errors`: it is
+   * bookkeeping, and the boot's first healthy pass must not wait on it. */
+  outcomes?: OutcomeSweepReport;
+  /** The undelivered-recheck sweep's pass: claims
+   * asked, found delivered (recorded, never asked again), released as lost,
+   * and carried to the next pass by the budget. Absent when it did not run. */
+  receipt_sweep?: { asked: number; delivered: number; released: number; carried: number };
+}
+
+function correction(
+  deps: ReconcileDeps,
+  pr: number | null,
+  what: string,
+  detail: unknown,
+  report: ReconcileReport,
+): void {
+  report.corrections++;
+  deps.store.logEvent("reconcile_correction", pr, { what, ...(detail as object) });
+  (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: StateStore,
+  inFlightPrs: Iterable<number>,
+  opts: {
+    now?: () => Date;
+    log?: (msg: string, extra?: unknown) => void;
+    /** Does this round still owe a review posting the outbox delivers on its
+     * own, or the settlement of one already posted? Absent ⇒ no round does. */
+    postingOwed?: (round: RoundRow) => boolean;
+  },
+): { cancelled: number[]; requeued: number[]; kept_for_posting: number[] } {
+  const live = new Set(inFlightPrs);
+  const now = opts.now ?? (() => new Date());
+  const log = opts.log ?? (() => {});
+  const cancelled: number[] = [];
+  const requeued: number[] = [];
+  const keptForPosting: number[] = [];
+  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: ReconcileDeps): Promise<ReconcileReport> {
+  const { store, cfg, adapter } = deps;
+  const now = deps.now ?? (() => new Date());
+  const botLogin = cfg.github.bot_login;
+  const report: ReconcileReport = {
+    ran_at: now().toISOString(),
+    open_prs: 0,
+    triggered: [],
+    closed: [],
+    backfilled_comments: 0,
+    captured_comments: 0,
+    corrections: 0,
+    errors: [],
+  };
+
+  const step = async (name: string, fn: () => Promise<void>): Promise<void> => {
+    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<number, PrRef>();
+  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;
+    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"] as const;
+    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<string, boolean | undefined>();
+    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<
+      number,
+      { item: ReconcileSearchItem; kinds: Array<(typeof kinds)[number]> }
+    >();
+    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: PrRef | null = 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: string): boolean => {
+        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: { number: number; state: string }): string => {
+        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: { number: number; state: string; updated_at: string }): string =>
+        `${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: CapturedComment[];
+        let reviewsFetched: ReviewFull[] = [];
+        let inlineFetched: ReviewCommentFull[] = [];
+        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;
+          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, appSlug: cfg.github.app_slug },
+          );
+          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;
+}