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

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

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

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.31.0}/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.31.0}/src/main/alissa/tools/github/revloop/alissa.py

@@ -233,6 +233,53 @@ _VERDICT_RE = re.compile(
     re.IGNORECASE,
 )
 
+# The envelope's merge-readiness judgment (issue #130). The alissa-code-review
+# skill writes it as one list line in the verdict envelope:
+#   - **Merge-Readiness:** auto
+#   - **Merge-Readiness:** operator — touches convex/schema.ts
+# Tolerant of the markdown around the label -- an optional bullet, optional
+# `**` bold around the label (with the colon inside or outside it), optional
+# bold around the value -- but NOT of the value's case: `Auto` is not a
+# judgment this daemon will carry, so it reads as missing and fails closed to
+# `operator` downstream. Line-anchored, first match wins, like the consumer's
+# own grammar; the reason runs to the end of the line and no further.
+READINESS_AUTO = "auto"
+READINESS_OPERATOR = "operator"
+_READINESS_RE = re.compile(
+    r"^[ \t]*(?:[-*+][ \t]+)?(?:\*\*)?[ \t]*Merge-Readiness[ \t]*:?[ \t]*(?:\*\*)?"
+    r"[ \t]*:?[ \t]*(?:\*\*)?(auto|operator)\b(?:\*\*)?"
+    r"(?:[ \t]*[—–-][ \t]*(.*?))?[ \t]*$",
+    re.MULTILINE,
+)
+
+# The reason lands in a GitHub review body (as a line-anchored trailer) and in
+# a log line, so it is bounded and flattened at the parser: one line, no
+# backticks (a fence would swallow the trailer and everything after it), and
+# no more than this many characters.
+MAX_READINESS_REASON_CHARS = 200
+
+
+def clean_readiness_reason(text: object) -> str:
+    """Flatten a Merge-Readiness reason to one bounded, backtick-free line."""
+    if not isinstance(text, str):
+        return ""
+    flat = " ".join(text.replace("`", "").split())
+    return flat[:MAX_READINESS_REASON_CHARS].rstrip()
+
+
+def parse_readiness(blob: object) -> "tuple[str | None, str]":
+    """`(value, reason)` from the first Merge-Readiness line in `blob`.
+
+    `value` is READINESS_AUTO / READINESS_OPERATOR, or None when no line
+    parses; `reason` is the cleaned trailing text (empty when there is none).
+    """
+    if not isinstance(blob, str):
+        return (None, "")
+    match = _READINESS_RE.search(blob)
+    if match is None:
+        return (None, "")
+    return (match.group(1), clean_readiness_reason(match.group(2)))
+
 
 @dataclass(frozen=True)
 class Task:
@@ -389,6 +436,23 @@ def _task_from_row(row: object) -> "Task | None":
     )
 
 
+@dataclass(frozen=True)
+class VerdictEnvelope:
+    """One parsed CR6 verdict envelope: the verdict, plus the merge-readiness
+    judgment the same envelope carries (issue #130).
+
+    `readiness` is READINESS_AUTO / READINESS_OPERATOR, or None when the
+    envelope has no parseable `Merge-Readiness` line -- the case the native
+    post fails closed on. `readiness_reason` is already one bounded,
+    backtick-free line (see clean_readiness_reason); empty when the envelope
+    gave none.
+    """
+
+    verdict: str
+    readiness: "str | None" = None
+    readiness_reason: str = ""
+
+
 @dataclass(frozen=True)
 class TaskDetail:
     """One task as `alissa task get` sees it: the task itself, plus everything
@@ -774,16 +838,29 @@ class Alissa:
         return matches[0]
 
     def latest_verdict(self, task_ref: str) -> str | None:
-        """The newest CR6 verdict envelope on a review task, or None.
+        """The newest CR6 verdict envelope's verdict on a review task, or None.
 
         Returns VERDICT_APPROVE / VERDICT_REQUEST_CHANGES. This is the verdict
         of record: reviewers post comment-mode reviews, so the GitHub review
         state is always COMMENTED and cannot express approval at all.
 
+        The word alone; `latest_envelope` returns the whole record (verdict
+        plus merge-readiness) off the same read for the caller that posts it.
+
         Never raises. The daemon polls forever and this runs inside every pass,
         so absent, empty or malformed evidence degrades to "no verdict" rather
         than taking the loop down.
         """
+        envelope = self.latest_envelope(task_ref)
+        return None if envelope is None else envelope.verdict
+
+    def latest_envelope(self, task_ref: str) -> "VerdictEnvelope | None":
+        """The newest CR6 verdict envelope on a review task, parsed, or None.
+
+        Same read and same tolerance as `latest_verdict`; this is the record
+        the native post carries onto GitHub (issue #130), so it needs the
+        envelope's Merge-Readiness line alongside the verdict word.
+        """
         try:
             data = run_json(["alissa", "task", "get", task_ref, "--json"], timeout=90)
         except CommandError as exc:
@@ -794,7 +871,7 @@ class Alissa:
             return None
 
         try:
-            return self._newest_verdict(data)
+            return self._newest_envelope(data)
         except Exception:  # pragma: no cover - defence in depth
             log.exception("could not parse verdict evidence for %s", task_ref)
             return None
@@ -839,10 +916,23 @@ class Alissa:
 
     @staticmethod
     def _newest_verdict(payload: object) -> str | None:
-        """Pick the newest parseable verdict out of a task's evidence array.
+        """The newest parseable verdict WORD out of a task's evidence array;
+        `_newest_envelope` with the readiness dropped, for the callers that
+        only decide on the word."""
+        envelope = Alissa._newest_envelope(payload)
+        return None if envelope is None else envelope.verdict
+
+    @staticmethod
+    def _newest_envelope(payload: object) -> "VerdictEnvelope | None":
+        """Pick the newest parseable verdict envelope out of a task's evidence
+        array, with the Merge-Readiness judgment it carries (issue #130).
 
         Every layer is optional by design -- the payload shape is whatever the
         CLI printed, and a task with no evidence is the normal round-1 case.
+
+        The readiness is read off the SAME evidence item as the verdict (its
+        body first, then its title), never off a neighbour: a stray line on an
+        older envelope must not decorate a newer round's verdict.
         """
         if not isinstance(payload, dict):
             return None
@@ -850,7 +940,7 @@ class Alissa:
         if not isinstance(evidence, list):
             return None
 
-        found: list[tuple[tuple[int, float], int, str]] = []
+        found: list[tuple[tuple[int, float], int, VerdictEnvelope]] = []
         for index, item in enumerate(evidence):
             if not isinstance(item, dict):
                 continue
@@ -861,10 +951,17 @@ class Alissa:
                     continue
                 match = _VERDICT_RE.search(blob)
                 if match:
+                    readiness, reason = parse_readiness(content)
+                    if readiness is None:
+                        readiness, reason = parse_readiness(title)
                     found.append(
                         (Alissa._created_key(item.get("createdAt")),
                          index,
-                         match.group(1).lower())
+                         VerdictEnvelope(
+                             verdict=match.group(1).lower(),
+                             readiness=readiness,
+                             readiness_reason=reason,
+                         ))
                     )
                     break
 

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.31.0}/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.31.0}/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.31.0}/src/main/alissa/tools/github/revloop/loop.py

@@ -16,13 +16,17 @@ 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
 
 from .alissa import (
+    READINESS_AUTO,
+    READINESS_OPERATOR,
     VERDICT_APPROVE,
     VERDICT_REQUEST_CHANGES,
+    VerdictEnvelope,
     Alissa,
     ManagedSession,
     SessionRef,
@@ -55,6 +59,7 @@ from .ghclient import (
     PullRequest,
     RateLimited,
     Review,
+    TimelineTruncated,
     TruncatedListing,
     countable_rounds,
     verdict_marker,
@@ -211,6 +216,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.
@@ -377,10 +394,50 @@ NATIVE_VERDICT_BODY = (
     "Submitted by the review daemon under the configured reviewer identity, so "
     "this round has a verdict of record on GitHub. The round's findings and "
     "reasoning are in the reviewer session's own comments on this PR{task_note}."
-    "{head_note}\n\n"
+    "{head_note}{readiness}\n\n"
     "{marker}"
 )
 
+# The merge-readiness trailer (issue #130). orcloop's opt-in merge edge merges
+# a PR only when the reviewer's APPROVE on the current head carries
+# `Merge-Readiness: auto`; the judgment is the reviewer session's (the
+# envelope's `- **Merge-Readiness:**` line) and this daemon only CARRIES it,
+# in a grammar the consumer can parse: one plain-text line, line-anchored,
+# the last non-empty line before the hidden verdict marker --
+#
+#   Merge-Readiness: auto
+#   Merge-Readiness: operator — <one-line reason>
+#
+# The rules that make it safe to consume: it is emitted on APPROVE events
+# ONLY (a request_changes envelope with a stray `auto` line carries nothing;
+# an approve the checks gate downgraded carries nothing), and an envelope
+# with no parseable line fails CLOSED to `operator`, with a reason that tells
+# the operator why the merge waited on them.
+READINESS_TRAILER_LABEL = "Merge-Readiness:"
+READINESS_MISSING_REASON = "envelope carries no Merge-Readiness line"
+
+
+def readiness_trailer(envelope: "VerdictEnvelope | None") -> str:
+    """The line the native APPROVE carries for `envelope`'s judgment.
+
+    The caller has already decided the event is an APPROVE; this only maps
+    the envelope onto the grammar. `auto` is emitted bare -- the consumer
+    keys on the value, and an operator reads a reason only when the merge is
+    theirs to make. A missing or unparseable judgment (None envelope, or one
+    whose readiness did not parse) is `operator` with a reason saying so.
+    """
+    if envelope is not None and envelope.readiness == READINESS_AUTO:
+        return f"{READINESS_TRAILER_LABEL} {READINESS_AUTO}"
+    if envelope is not None and envelope.readiness == READINESS_OPERATOR:
+        if envelope.readiness_reason:
+            return (
+                f"{READINESS_TRAILER_LABEL} {READINESS_OPERATOR} — "
+                f"{envelope.readiness_reason}"
+            )
+        return f"{READINESS_TRAILER_LABEL} {READINESS_OPERATOR}"
+    return f"{READINESS_TRAILER_LABEL} {READINESS_OPERATOR} — {READINESS_MISSING_REASON}"
+
+
 # Appended to the body when the round's review task is known.
 _VERDICT_TASK_NOTE = ", and the CR6 verdict envelope is on `{task_ref}`"
 
@@ -587,6 +644,17 @@ _RECORD_THE_CAP = (
     "from a stale template default. "
 )
 
+# The merge-readiness line (issue #130). The verdict envelope is where the
+# reviewer's judgment lives; the daemon copies it onto the native review as a
+# trailer the merge edge reads, and an envelope without the line posts as
+# `operator` -- so a reviewer who skips it has silently withheld auto-merge.
+_MERGE_READINESS_LINE = (
+    "Your verdict envelope MUST carry the skill's `- **Merge-Readiness:** auto | "
+    "operator — <reason>` line — the daemon copies it onto the native review as "
+    "the `Merge-Readiness:` trailer the merge edge reads, and an envelope "
+    "without the line posts as `operator`. "
+)
+
 # -- the reviewer session's own CI gate (issue #84) ---------------------------
 #
 # _gate_on_checks (issue #58) gates the verdict the DAEMON posts. It cannot gate the
@@ -867,6 +935,7 @@ ROUND_1_DIRECTIVE = (
     "severity-tagged comments via gh pr review, record the verdict evidence, "
     "move the task to pending_validation. "
     + _RECORD_THE_CAP
+    + _MERGE_READINESS_LINE
     + "{credential}"
     + _CHECKS_BEFORE_VERDICT
     + "{checks}"
@@ -885,6 +954,7 @@ ROUND_K_DIRECTIVE = (
     "verify the fixes, sweep the new diff with the full rubric, record a "
     "round-{round} verdict envelope, move the task to pending_validation. "
     + _RECORD_THE_CAP
+    + _MERGE_READINESS_LINE
     + "{credential}"
     + _CHECKS_BEFORE_VERDICT
     + "{checks}"
@@ -1251,6 +1321,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 +1795,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 +2272,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 +2420,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:
@@ -2932,9 +3225,10 @@ class ReviewWatcher:
         Never raises past RateLimited: a broken post must stall this PR, not
         the whole poll pass.
         """
-        verdict = self.alissa.latest_verdict(task.ref)
+        envelope = self.alissa.latest_envelope(task.ref)
+        verdict = None if envelope is None else envelope.verdict
         if verdict not in (VERDICT_APPROVE, VERDICT_REQUEST_CHANGES):
-            # count_verdicts and latest_verdict read the same envelopes with
+            # count_verdicts and latest_envelope read the same envelopes with
             # the same pattern, so this is nearly unreachable -- but "I know a
             # round finished and cannot tell you its verdict" must never be
             # resolved by guessing one onto the PR.
@@ -3029,6 +3323,11 @@ class ReviewWatcher:
                 return gate.hold
             event = gate.event
 
+        # The trailer follows the EVENT, not the envelope: an approve the
+        # checks gate turned into a REQUEST_CHANGES or COMMENT carries none,
+        # because `auto` on anything but an APPROVE is exactly what the
+        # consumer must never see (issue #130).
+        trailer = readiness_trailer(envelope) if event == EVENT_APPROVE else ""
         body = gate.lead + NATIVE_VERDICT_BODY.format(
             round=round_,
             verdict=verdict,
@@ -3038,6 +3337,7 @@ class ReviewWatcher:
                 if moved
                 else ""
             ),
+            readiness=f"\n\n{trailer}" if trailer else "",
             marker=verdict_marker(round_),
         )
         try:
@@ -3069,14 +3369,26 @@ 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 ""
+        )
+        # The readiness carried on the post, in the same three records. Only
+        # an APPROVE carries one, so only an APPROVE names it.
+        readiness_value = trailer[len(READINESS_TRAILER_LABEL):].strip()
+        readiness_note = f" readiness={readiness_value}" if trailer else ""
         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,
+            "%s round %d closed: native %s review submitted as %s (%s)%s%s",
+            pr.slug, round_, event, self.github.login, url or "no url",
+            readiness_note, gate_note,
         )
         self._append_activity(
             pr,
             f"- {_now()} — round {round_} — native `{event}` review submitted "
-            f"as `{self.github.login}` (verdict of record){gate_note}",
+            f"as `{self.github.login}` (verdict of record){gate_note}"
+            + (f" — merge-readiness: `{readiness_value}`" if trailer else ""),
         )
         if event == EVENT_COMMENT:
             # A degraded verdict takes the PR out of the loop (the review
@@ -4920,6 +5232,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.31.0}/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.31.0/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.31.0

{alissa_tools_github_revloop-0.30.0 → alissa_tools_github_revloop-0.31.0/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.31.0
 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