alissa-tools-github-revloop 0.30.0__tar.gz → 0.30.1__tar.gz

{alissa_tools_github_revloop-0.30.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.30.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.30.0
+Version: 0.30.1
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.30.1}/src/main/alissa/tools/github/revloop/__main__.py

@@ -201,6 +201,15 @@ def build_parser() -> argparse.ArgumentParser:
         "evidence; 0 queues immediately and relies on the directive alone",
     )
 
+    over.add_argument(
+        "--verdict-cooldown-s",
+        type=int,
+        metavar="SECONDS",
+        help="how long after a verdict lands on a head no round may be queued "
+        "on that same head, whatever the PR's requested_reviewers snapshot "
+        "says; 0 leaves the review_requested timeline check to decide alone",
+    )
+
     over.add_argument(
         "--review-task-miss-ttl-polls",
         type=int,
@@ -321,6 +330,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "max_concurrent_sessions": args.max_concurrent_sessions,
         "checks_wait_seconds": args.checks_wait_seconds,
         "checks_spawn_wait_seconds": args.checks_spawn_wait_seconds,
+        "verdict_cooldown_s": args.verdict_cooldown_s,
         "review_task_miss_ttl_polls": args.review_task_miss_ttl_polls,
         "task_list_self_scope": args.task_list_self_scope,
         "task_list_bow_id": args.task_list_bow_id,

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.30.1}/src/main/alissa/tools/github/revloop/config.py

@@ -190,6 +190,7 @@ CONFIG_KEYS = (
     "max_concurrent_sessions",
     "checks_wait_seconds",
     "checks_spawn_wait_seconds",
+    "verdict_cooldown_s",
     "review_task_miss_ttl_polls",
     "task_list_self_scope",
     "task_list_bow_id",
@@ -539,6 +540,24 @@ DEFAULT_CHECKS_WAIT_SECONDS = 30 * 60
 # still-running rollup, which is the directive-only posture.
 DEFAULT_CHECKS_SPAWN_WAIT_SECONDS = 15 * 60
 
+# How long, after a verdict lands on a head, NO round may be queued on that same
+# head -- whatever the PR's `requested_reviewers` snapshot says (issue #128).
+#
+# GitHub consumes a review request the moment the requested identity submits a
+# review, but not atomically with the daemon's reads: on studio #1243 a
+# `request_changes` verdict landed at 14:35:32 and the poll ten seconds later
+# still saw the reviewer in `requested_reviewers`, queued round 2 on the SAME
+# head, and that phantom round bounced on the CR8 triage gate -- which made the
+# devloop spawn a second fix session on one branch. The cooldown is the blunt
+# guard against that propagation lag: two polls' worth at the default cadence,
+# long enough for the request the verdict consumed to be gone from every read.
+# The precise guard is the timeline check in loop._admit_round, which admits a
+# same-head round only on a `review_requested` event NEWER than the verdict;
+# the cooldown spares that check a GitHub call in exactly the window where the
+# stale snapshot is most likely. 0 disables the cooldown and leaves the timeline
+# check to decide alone.
+DEFAULT_VERDICT_COOLDOWN_SECONDS = 120
+
 # How many polls a PR with NO review task may be taken on trust before the
 # daemon searches the task corpus for one again (issue #87).
 #
@@ -778,6 +797,12 @@ class Config:
     # timer to configure.
     checks_spawn_wait_seconds: int = DEFAULT_CHECKS_SPAWN_WAIT_SECONDS
 
+    # How long after a verdict lands on a head no round may be queued on that
+    # same head, regardless of the PR's `requested_reviewers` snapshot; see
+    # DEFAULT_VERDICT_COOLDOWN_SECONDS. 0 is legal and means "no cooldown": the
+    # timeline check alone decides whether a same-head round is admitted.
+    verdict_cooldown_s: int = DEFAULT_VERDICT_COOLDOWN_SECONDS
+
     # How many polls a PR with no review task is taken on trust before the
     # corpus is searched again; see DEFAULT_REVIEW_TASK_MISS_TTL_POLLS. Floor 1
     # -- there is no value that turns the negative cache off.
@@ -1145,6 +1170,10 @@ class Config:
                 f"checks_spawn_wait_seconds must be >= 0, got {spawn_wait}"
             )
 
+        cooldown = int(raw.get("verdict_cooldown_s", cls.verdict_cooldown_s))
+        if cooldown < 0:
+            raise ValueError(f"verdict_cooldown_s must be >= 0, got {cooldown}")
+
         miss_ttl = int(
             raw.get("review_task_miss_ttl_polls", cls.review_task_miss_ttl_polls)
         )
@@ -1213,6 +1242,7 @@ class Config:
             max_concurrent_sessions=max_sessions,
             checks_wait_seconds=checks_wait,
             checks_spawn_wait_seconds=spawn_wait,
+            verdict_cooldown_s=cooldown,
             review_task_miss_ttl_polls=miss_ttl,
             task_list_self_scope=bool(raw.get("task_list_self_scope", False)),
             task_list_bow_id=bow_id,

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.30.1}/src/main/alissa/tools/github/revloop/ghclient.py

@@ -41,6 +41,20 @@ SUBMITTED_STATES = {"APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"}
 # concatenates one JSON document per page and would not parse.
 PER_PAGE = 100
 COMMENT_PAGE_LIMIT = 20
+# The issue timeline grows with every label, push, comment and request over a
+# PR's life; the round-admission gate reads it for the newest
+# `review_requested` event and the bound keeps a long-lived PR from turning one
+# poll into an unbounded walk. The endpoint pages oldest-first with no
+# direction parameter, so past the bound it is the NEWEST events that go
+# unread, and the newest is exactly what the gate is asking about. So a walk
+# that hits the bound does NOT answer with the newest request it happened to
+# see (an old one, which would refuse every same-head round on that PR
+# forever): it raises TimelineTruncated, and the gate treats "could not see
+# the newest request" the same way whether it arrives as silence or as an
+# exception -- see loop._fresh_request_at. Whether the bound was actually
+# exceeded is settled by ONE probe past it, so exactly 2,000 events is a
+# complete read and not a false alarm (PR #129 round 1).
+TIMELINE_PAGE_LIMIT = 20
 
 # The compare endpoint's HARD cap on the `files` array, and it is a cap, not a
 # page: `files` is not paginated at all. Measured against api.github.com on
@@ -435,6 +449,13 @@ class RateLimited(RuntimeError):
     pass
 
 
+class TimelineTruncated(RuntimeError):
+    """The issue timeline has more events than TIMELINE_PAGE_LIMIT pages hold,
+    so the newest `review_requested` may lie past what was read. Raised
+    INSTEAD of a stale answer: a caller that compares request timestamps must
+    not mistake "the newest within the bound" for "the newest"."""
+
+
 class IdentityMismatch(RuntimeError):
     """Configured reviewer identity disagrees with the gh token."""
 
@@ -1187,6 +1208,67 @@ class GitHub:
             env=self._env(),
         )
 
+    def review_requested_at(
+        self, owner: str, repo: str, number: int, login: str
+    ) -> str | None:
+        """When `login` was most recently asked to review the PR, as the
+        timeline's `created_at` (ISO-8601), or None if it never was.
+
+        Read from `GET /repos/{owner}/{repo}/issues/{n}/timeline`, keeping only
+        `review_requested` events whose `requested_reviewer` is `login` (a team
+        request carries `requested_team` instead and is nobody's round). The
+        PR's own `requested_reviewers` array is NOT this: GitHub removes the
+        request there when the review lands, with a propagation lag the daemon
+        can read through, whereas the timeline event is immutable history --
+        the request's timestamp can be compared with the verdict's (issue
+        #128). Pages oldest-first like issue_comments, bounded by
+        TIMELINE_PAGE_LIMIT -- and past the bound it raises TimelineTruncated
+        rather than answering with an older request than the true newest
+        (the reasoning is at the constant). The bound is checked with one
+        probe past the last page, so a timeline of exactly
+        TIMELINE_PAGE_LIMIT * PER_PAGE events reads as complete.
+        """
+        wanted = login.casefold()
+        newest: str | None = None
+        for page in range(1, TIMELINE_PAGE_LIMIT + 2):
+            data = self._timeline_page(owner, repo, number, page)
+            if page > TIMELINE_PAGE_LIMIT:
+                # The probe: anything here means the bound was exceeded.
+                if data:
+                    raise TimelineTruncated(
+                        f"{owner}/{repo}#{number} has more than "
+                        f"{TIMELINE_PAGE_LIMIT * PER_PAGE} timeline events — the "
+                        f"newest review request to {login} may lie past the "
+                        f"{TIMELINE_PAGE_LIMIT * PER_PAGE} that were read"
+                    )
+                break
+            for event in data:
+                if (event or {}).get("event") != "review_requested":
+                    continue
+                who = ((event.get("requested_reviewer") or {}).get("login") or "")
+                if who.casefold() != wanted:
+                    continue
+                at = event.get("created_at") or ""
+                if at and (newest is None or at > newest):
+                    newest = at
+            if len(data) < PER_PAGE:
+                break
+        return newest
+
+    def _timeline_page(self, owner: str, repo: str, number: int, page: int) -> list:
+        return (
+            self._api(
+                "-X",
+                "GET",
+                f"repos/{owner}/{repo}/issues/{number}/timeline",
+                "-f",
+                f"per_page={PER_PAGE}",
+                "-f",
+                f"page={page}",
+            )
+            or []
+        )
+
     def issue_comments(self, owner: str, repo: str, number: int) -> list[IssueComment]:
         """Every issue comment on the PR, oldest first -- see COMMENT_PAGE_LIMIT
         for why this pages instead of reading the first 100 and hoping."""

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.30.1}/src/main/alissa/tools/github/revloop/loop.py

@@ -16,6 +16,7 @@ import secrets
 import sqlite3
 import time
 from collections import Counter
+from datetime import datetime, timezone
 from dataclasses import dataclass, field, replace
 from enum import Enum
 from pathlib import Path
@@ -55,6 +56,7 @@ from .ghclient import (
     PullRequest,
     RateLimited,
     Review,
+    TimelineTruncated,
     TruncatedListing,
     countable_rounds,
     verdict_marker,
@@ -211,6 +213,18 @@ DEFERRAL_CLEARED = (
 )
 
 
+@dataclass(frozen=True)
+class VerdictOfRecord:
+    """The newest verdict on a PR's current head, as the round-admission gate
+    needs it (issue #128): `at` is the newer of GitHub's `submitted_at` and
+    the ledger's local stamp -- the cooldown's clock -- and `github_at` is
+    GitHub's stamp alone (None while GitHub's reviews list has not yet shown
+    the verdict), the only one comparable with a timeline `created_at`."""
+
+    at: float
+    github_at: float | None
+
+
 @dataclass(frozen=True)
 class Waiting:
     """One round's place in the spawn queue, from its FIRST deferral.
@@ -1251,6 +1265,26 @@ def _now() -> str:
     return time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime())
 
 
+def _epoch(stamp: str) -> float | None:
+    """A GitHub ISO-8601 timestamp (`2026-09-15T14:35:32Z`) as epoch seconds,
+    or None for an empty or unparseable one. A naive stamp is read as UTC,
+    which is what GitHub emits."""
+    if not stamp:
+        return None
+    try:
+        parsed = datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.timestamp()
+
+
+def _stamp(epoch: float) -> str:
+    """The inverse of _epoch, for log lines: UTC, seconds, `Z`."""
+    return datetime.fromtimestamp(epoch, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
 def grant_activity_kind(comment_id: int) -> str:
     """The ping-ledger kind that dedupes ONE grant's activity line.
 
@@ -1705,6 +1739,18 @@ class ReviewWatcher:
         # has listed this pass (the preflight refresh, or a sweep whose list
         # failed), and the refresh lists for itself.
         self._pass_roster: list[ManagedSession] | None = None
+        # (repo full name, PR number) -> when the reviewer login was most
+        # recently asked to review that PR, per the issue timeline (an ISO
+        # stamp, or None for never) -- the round-admission gate's one GitHub
+        # read, memoised so a PR costs at most one timeline walk per pass
+        # (issue #128). Cleared with the other per-pass memos in poll_once.
+        self._pass_requests: dict[tuple[str, int], str | None] = {}
+        # (repo full name, PR number) -> (head, verdict epoch) of the last
+        # stale request the gate announced at INFO for that PR, so the line
+        # goes out once per ignored request and repeats at debug while the
+        # same request keeps being seen. In-memory on purpose: a restart
+        # costs one repeated line, not a ledger write per poll.
+        self._ignored_requests: dict[tuple[str, int], tuple[str, float]] = {}
         # (repo full name, PR number) -> where that round sits in the spawn
         # queue, from the first pass that deferred it. Cross-pass and
         # in-memory: it is a FAIRNESS ORDER, not a decision the daemon must
@@ -2170,6 +2216,17 @@ class ReviewWatcher:
             if deferred is not None:
                 return deferred
 
+        # THE ROUND-ADMISSION GATE (issue #128): a round on a head that already
+        # carries a verdict needs FRESH evidence of a request -- a
+        # `review_requested` event newer than that verdict -- and never starts
+        # inside the post-verdict cooldown at all. Below the in-flight and
+        # stale-round reads (a running round costs no timeline call) and above
+        # every other refusal, because a round this gate turns away must
+        # consume neither a rollup nor a place in the slot queue.
+        refused = self._admit_round(pr, my_reviews, round_)
+        if refused is not None:
+            return refused
+
         # THE SPAWN GATE, and it sits here -- past every branch that decides
         # WHETHER a round is owed, immediately before the one that acts.
         # Upstream of it the loop is only reading; downstream it starts an
@@ -2307,6 +2364,186 @@ class ReviewWatcher:
             round_,
         )
 
+    # -- round admission (issue #128) ----------------------------------------
+
+    def _admit_round(
+        self, pr: PullRequest, my_reviews: list[Review], round_: int
+    ) -> Decision | None:
+        """Refuse a round the PR's review-request snapshot alone would start,
+        or None to carry on.
+
+        The search set is `review-requested:@me`, and the loop's edge trigger
+        has always been GitHub consuming that request when the requested
+        identity submits a review. That consumption is not atomic with the
+        daemon's reads: on studio #1243 round 1 posted `request_changes` at
+        14:35:32 on head 0d9d66b7, the poll at 14:35:42 still found the PR in
+        the search with the reviewer in `requested_reviewers`, and queued round
+        2 on the same head -- a round nobody asked for, which then bounced on
+        the CR8 triage gate and made the devloop spawn a second fix session on
+        one branch. `requested_reviewers` is therefore a HINT here, never the
+        verdict. A round on head H is admitted only when
+
+        (a) no verdict of record exists for (PR, H) -- a push re-arms exactly
+            as before, since the newest review then judges an older commit; or
+        (b) the issue timeline shows a `review_requested` event for the
+            reviewer login NEWER than the last verdict on H.
+
+        And inside `verdict_cooldown_s` of that verdict nothing is admitted on
+        H at all, whatever the timeline says: the cooldown alone would have
+        prevented #1243, and (b) is what makes the gate correct rather than
+        merely rare. The verdict's timestamp is the newer of GitHub's own
+        review record and the ledger's (the daemon stamps its native posts the
+        moment they land, before GitHub's reviews list catches up).
+
+        A refused round is a SKIPPED decision and holds no queue place, like
+        the other pre-start refusals. Each ignored request is announced once at
+        INFO -- "stale request" must be tellable from "idle" in the log -- and
+        repeated at debug while the same request keeps being seen.
+
+        Two clocks, kept apart (PR #129 round 1): the cooldown is a duration
+        on THIS host's wall clock, measured from the newer of GitHub's stamp
+        and the ledger's local one; the comparison in (b) is GitHub's
+        `created_at` against GitHub's `submitted_at`, both GitHub's clock, so
+        a host running ahead of GitHub cannot make its own native post look
+        newer than a genuine re-request that followed it. The ledger's local
+        stamp enters (b) only while GitHub's reviews list has not yet shown
+        the verdict at all -- the window the ledger exists for.
+        """
+        verdict = self._last_verdict_at(pr, my_reviews)
+        if verdict is None:
+            return None
+        verdict_at = verdict.at
+
+        key = (pr.full_name, pr.number)
+        since = time.time() - verdict_at
+        cooldown = self.config.verdict_cooldown_s
+        # A verdict stamped in the FUTURE (clock skew between GitHub and this
+        # host) is not inside the window measured from it; the timeline check
+        # below still decides, so nothing is lost by not guessing.
+        if 0 <= since < cooldown:
+            self._waiting.pop(key, None)
+            log.info(
+                "%s round %d: the last verdict on head %s landed %.0fs ago (%s) "
+                "— inside the %ds post-verdict cooldown, not queuing whatever "
+                "the review-request snapshot says",
+                pr.slug, round_, pr.head_sha[:8], since, _stamp(verdict_at), cooldown,
+            )
+            return Decision(
+                Action.SKIPPED,
+                f"head {pr.head_sha[:8]} had a verdict {int(since)}s ago — inside "
+                f"the {cooldown}s post-verdict cooldown",
+                round_,
+            )
+
+        requested = self._fresh_request_at(pr)
+        if requested is None:
+            # The newest request could not be seen -- the timeline was
+            # unreadable or longer than the bound (logged there). The snapshot
+            # is all that is left, and past the cooldown it is the pre-#128
+            # trigger: a wedged loop on every read failure is the worse trade.
+            return None
+        request_at = _epoch(requested)
+        verdict_at = verdict.github_at if verdict.github_at is not None else verdict.at
+        if request_at is not None and request_at > verdict_at:
+            return None
+
+        self._waiting.pop(key, None)
+        seen = (
+            f"request seen at {requested}"
+            if request_at is not None
+            else f"no review_requested event for {self.github.login} on the timeline"
+        )
+        message = (
+            "%s round %d: %s is older than the last verdict at %s on head %s "
+            "— waiting for a fresh re-request"
+        )
+        args = (pr.slug, round_, seen, _stamp(verdict_at), pr.head_sha[:8])
+        if self._ignored_requests.get(key) == (pr.head_sha, verdict_at):
+            log.debug(message, *args)
+        else:
+            self._ignored_requests[key] = (pr.head_sha, verdict_at)
+            log.info(message, *args)
+        return Decision(
+            Action.SKIPPED,
+            f"{seen} is older than the last verdict on head {pr.head_sha[:8]} "
+            f"— waiting for a fresh re-request",
+            round_,
+        )
+
+    def _last_verdict_at(
+        self, pr: PullRequest, my_reviews: list[Review]
+    ) -> VerdictOfRecord | None:
+        """The newest verdict of record on the CURRENT head, or None when no
+        reviewer-identity review judges this head.
+
+        Two sources, the newer wins for the cooldown. GitHub's reviews list is
+        the authority for a verdict the reviewer SESSION posted (it never
+        passes through the daemon), and the newest review is the one that
+        matters: judging an older commit, it is not a verdict on this head at
+        all. The ledger covers the daemon's own native posts during the window
+        before GitHub's list shows them. A GitHub-observed verdict is written
+        back to the ledger as telemetry, so the ledger converges on GitHub's
+        truth and a row lost either way costs nothing. GitHub's own stamp is
+        carried out separately because it is the only one in the timeline's
+        clock domain -- see `_admit_round`.
+        """
+        newest = my_reviews[-1] if my_reviews else None
+        seen: float | None = None
+        if newest is not None and newest.commit_id and newest.commit_id == pr.head_sha:
+            seen = _epoch(newest.submitted_at)
+            if seen is not None:
+                self.state.note_observed_verdict(
+                    pr.full_name, pr.number, pr.head_sha, int(seen), newest.url
+                )
+        ledger = self.state.last_verdict_at(pr.full_name, pr.number, pr.head_sha)
+        candidates = [at for at in (seen, ledger) if at is not None]
+        if not candidates:
+            return None
+        return VerdictOfRecord(at=max(candidates), github_at=seen)
+
+    def _fresh_request_at(self, pr: PullRequest) -> str | None:
+        """When this login was most recently asked to review the PR, from the
+        issue timeline, memoised for the pass: one timeline walk per candidate
+        PR per poll, however many times the PR is evaluated. None when the
+        read failed (a RateLimited still propagates to run_forever's backoff,
+        exactly as every other read path lets it)."""
+        key = (pr.full_name, pr.number)
+        if key in self._pass_requests:
+            return self._pass_requests[key]
+        try:
+            requested = self.github.review_requested_at(
+                pr.owner, pr.repo, pr.number, self.github.login
+            )
+        except RateLimited:
+            raise
+        except TimelineTruncated as exc:
+            # Same epistemic state as an unreadable timeline -- the newest
+            # request cannot be seen -- so the same answer: fail OPEN. The
+            # alternative, comparing against the newest request WITHIN the
+            # bound, refuses every same-head round on a long-timelined PR
+            # forever with nothing but a warning (PR #129 round 1, major).
+            log.warning(
+                "%s: %s — admitting the round on the review-request snapshot "
+                "alone, which is what the post-verdict cooldown guards",
+                pr.slug, exc,
+            )
+            requested = None
+        except Exception as exc:
+            log.warning(
+                "%s: could not read the issue timeline for review requests to "
+                "%s (%s) — admitting the round on the review-request snapshot "
+                "alone, which is what the post-verdict cooldown guards",
+                pr.slug, self.github.login, exc,
+            )
+            requested = None
+        else:
+            # A timeline with no request at all is a real answer -- the
+            # snapshot said "requested" and history says nobody did -- and it
+            # is memoised as the empty string so the miss is not re-read.
+            requested = requested or ""
+        self._pass_requests[key] = requested
+        return requested
+
     def _refused_before_start(
         self, pr: PullRequest, round_: int, task: Task | None
     ) -> Decision | None:
@@ -3069,6 +3306,12 @@ class ReviewWatcher:
         self.state.record_verdict_post(
             pr.full_name, pr.number, round_, url, verdict=verdict
         )
+        # The round-admission gate's cooldown is measured from HERE for the
+        # daemon's own posts, so it holds even while GitHub's reviews list
+        # still lags the POST it just accepted (issue #128).
+        self.state.record_verdict(
+            pr.full_name, pr.number, judged, int(time.time()), url or ""
+        )
         log.info(
             "%s round %d closed: native %s review submitted as %s (%s)%s",
             pr.slug, round_, event, self.github.login, url or "no url", gate_note,
@@ -4920,6 +5163,7 @@ class ReviewWatcher:
         self._session_census = None
         self._census_probed = self._census_warned = False
         self._pass_roster = None
+        self._pass_requests = {}
 
         # THE LEDGER GATE (issue #62, PR #63 round-1 blocker). Nothing below
         # may run when the ledger cannot record what it does.

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.30.1}/src/main/alissa/tools/github/revloop/state.py

@@ -95,6 +95,26 @@ CREATE TABLE IF NOT EXISTS grants (
     PRIMARY KEY (repo, number, comment_id)
 );
 
+-- Every verdict of record the daemon knows about, keyed by the head it
+-- judged (issue #128): the round-admission gate refuses to queue a round on a
+-- head inside `verdict_cooldown_s` of the newest verdict on it, and past the
+-- cooldown admits one only on a `review_requested` event NEWER than that
+-- verdict. Two writers: loop._close_round_natively stamps its own post the
+-- moment it lands (so the cooldown holds even while GitHub's reviews list
+-- still lags the POST), and loop.evaluate stamps every reviewer-identity
+-- review it observes on the current head (a session's own `gh pr review`
+-- never passes through the daemon). Rows are never pruned -- one per verdict
+-- ever landed -- and a lost row costs nothing: GitHub's reviews list is read
+-- alongside it and the gate takes the newer of the two.
+CREATE TABLE IF NOT EXISTS verdicts (
+    repo       TEXT    NOT NULL,
+    number     INTEGER NOT NULL,
+    head_sha   TEXT    NOT NULL,
+    posted_at  INTEGER NOT NULL,
+    review_url TEXT,
+    PRIMARY KEY (repo, number, head_sha, posted_at)
+);
+
 CREATE TABLE IF NOT EXISTS pings (
     repo      TEXT    NOT NULL,
     number    INTEGER NOT NULL,
@@ -728,6 +748,57 @@ class State:
         )
         self._db.commit()
 
+    def record_verdict(
+        self, repo: str, number: int, head_sha: str, posted_at: int,
+        review_url: str = "",
+    ) -> None:
+        """Remember that a verdict of record landed on `head_sha` at
+        `posted_at` (epoch seconds). Idempotent per (PR, head, timestamp), so
+        the same GitHub review observed on every poll writes one row."""
+        self._db.execute(
+            "INSERT OR IGNORE INTO verdicts "
+            "(repo, number, head_sha, posted_at, review_url) VALUES (?,?,?,?,?)",
+            (repo, number, head_sha, int(posted_at), review_url),
+        )
+        self._db.commit()
+
+    def note_observed_verdict(
+        self, repo: str, number: int, head_sha: str, posted_at: int,
+        review_url: str = "",
+    ) -> bool:
+        """TELEMETRY write-back of a verdict the loop saw on GitHub, so the
+        ledger converges on GitHub's truth (issue #128). Absorbed like every
+        other telemetry write: GitHub already holds the record, so a row the
+        ledger cannot take costs nothing. `record_verdict` itself stays the
+        hard write the daemon's own native post makes -- that row IS the
+        record until GitHub's reviews list catches up. True on success."""
+        return self._write_telemetry(
+            lambda: self.record_verdict(repo, number, head_sha, posted_at, review_url),
+            f"recording the verdict on {repo}#{number} at {head_sha[:8]}",
+        )
+
+    def last_verdict_at(self, repo: str, number: int, head_sha: str) -> int | None:
+        """When the newest verdict of record on this head landed (epoch
+        seconds), or None when the ledger knows of none on it."""
+        row = self._db.execute(
+            "SELECT MAX(posted_at) AS at FROM verdicts "
+            "WHERE repo=? AND number=? AND head_sha=?",
+            (repo, number, head_sha),
+        ).fetchone()
+        return int(row["at"]) if row and row["at"] is not None else None
+
+    def read_verdicts(self, limit: int | None = None) -> list[dict]:
+        """Verdict-of-record rows, newest first. For inspection; nothing in
+        the loop reads it. Mind that a `read_only=True` opener skips SCHEMA,
+        so against a ledger whose daemon has not yet restarted onto a version
+        with the `verdicts` table this raises `no such table`, not `[]` --
+        whoever wires it into the console first should guard for that."""
+        return self._read_rows(
+            "SELECT repo, number, head_sha, posted_at, review_url FROM verdicts "
+            "ORDER BY posted_at DESC, number DESC",
+            limit,
+        )
+
     def escalated(self, repo: str, number: int, head_sha: str) -> bool:
         """Whether this head has been paged at all. Not the whole dedupe story
         once re-entry grants exist -- a grant consumed without an approve is a

alissa_tools_github_revloop-0.30.1/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.30.1

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.30.1/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.30.0
+Version: 0.30.1
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_revloop-0.30.0/src/main/alissa/tools/github/revloop/version

@@ -1 +0,0 @@
-0.30.0