alissa-tools-github-revloop 0.16.6__tar.gz → 0.16.7__tar.gz

{alissa_tools_github_revloop-0.16.6/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.16.7}/PKG-INFO

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

{alissa_tools_github_revloop-0.16.6 → alissa_tools_github_revloop-0.16.7}/src/main/alissa/tools/github/revloop/__main__.py

@@ -122,6 +122,14 @@ def build_parser() -> argparse.ArgumentParser:
         help="page-worthy threshold: more live reviewer sessions than this "
         "after a sweep and the daemon logs loudly",
     )
+    over.add_argument(
+        "--checks-wait-seconds",
+        type=int,
+        metavar="SECONDS",
+        help="how long a round holds its approve while the judged head's CI "
+        "rollup is still running (or unreadable) before recording the verdict "
+        "as a comment instead; a red rollup never waits and never approves",
+    )
 
     dry = over.add_mutually_exclusive_group()
     dry.add_argument(
@@ -157,6 +165,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "on_missing_hub": args.on_missing_hub,
         "reap_grace_seconds": args.reap_grace_seconds,
         "reap_session_cap": args.reap_session_cap,
+        "checks_wait_seconds": args.checks_wait_seconds,
         "dry_run": args.dry_run,
     }
 

{alissa_tools_github_revloop-0.16.6 → alissa_tools_github_revloop-0.16.7}/src/main/alissa/tools/github/revloop/config.py

@@ -129,6 +129,7 @@ CONFIG_KEYS = (
     "on_missing_hub",
     "reap_grace_seconds",
     "reap_session_cap",
+    "checks_wait_seconds",
     "dry_run",
 )
 
@@ -169,6 +170,20 @@ DEFAULT_REAP_GRACE_SECONDS = 30 * 60
 # healthy deployment reaches, not a capacity limit.
 DEFAULT_REAP_SESSION_CAP = 6
 
+# How long a round holds its APPROVE while the head's CI rollup is still
+# running (or unreadable) before it gives up and records the verdict as a
+# COMMENT instead. An approve from the reviewer identity is the operator's cue
+# to merge, so it must never claim a head whose checks this loop did not see
+# conclude -- but the round cannot hold open forever either, or a CI system that
+# never reports strands the PR outside the loop.
+#
+# 30 minutes is the trade: longer than any check suite in this fleet (the studio
+# runs finish in single-digit minutes), short enough that a stuck rollup
+# surfaces as a comment within the same working hour instead of the following
+# day. Configurable because the right value is a property of a deployment's CI,
+# not of the daemon.
+DEFAULT_CHECKS_WAIT_SECONDS = 30 * 60
+
 
 def default_state_path(workspace_root: Path) -> Path:
     return Path(workspace_root) / ".revloop" / "state.db"
@@ -218,6 +233,12 @@ class Config:
     reap_grace_seconds: int = DEFAULT_REAP_GRACE_SECONDS
     reap_session_cap: int = DEFAULT_REAP_SESSION_CAP
 
+    # The bound on holding a round's approve for a rollup that has not settled;
+    # see DEFAULT_CHECKS_WAIT_SECONDS. 0 is legal and means "never hold": a
+    # rollup that is not already green degrades the verdict to a comment on the
+    # first poll that would have posted it.
+    checks_wait_seconds: int = DEFAULT_CHECKS_WAIT_SECONDS
+
     dry_run: bool = False
 
     def __post_init__(self) -> None:
@@ -336,6 +357,10 @@ class Config:
             # state of a working loop -- an alarm that always fires is noise.
             raise ValueError(f"reap_session_cap must be >= 1, got {session_cap}")
 
+        checks_wait = int(raw.get("checks_wait_seconds", cls.checks_wait_seconds))
+        if checks_wait < 0:
+            raise ValueError(f"checks_wait_seconds must be >= 0, got {checks_wait}")
+
         token_env = raw.get("reviewer_token_env")
         if token_env is not None:
             token_env = str(token_env).strip()
@@ -379,6 +404,7 @@ class Config:
             on_missing_hub=hub_mode,
             reap_grace_seconds=grace,
             reap_session_cap=session_cap,
+            checks_wait_seconds=checks_wait,
             dry_run=bool(raw.get("dry_run", False)),
         )
 

{alissa_tools_github_revloop-0.16.6 → alissa_tools_github_revloop-0.16.7}/src/main/alissa/tools/github/revloop/ghclient.py

@@ -62,11 +62,55 @@ GH_TOKEN_VARS = ("GH_TOKEN", "GITHUB_TOKEN")
 # throttling from an authorization failure -- these can. See `_api`.
 RATE_LIMIT_MARKERS = ("rate limit", "abuse detection", "429")
 
-# The review events the daemon may submit. COMMENT is deliberately absent: a
-# comment-mode review cannot express approval, which is the whole reason the
-# GitHub state was useless as a convergence signal in the first place.
+# The review events the daemon may submit.
 EVENT_APPROVE = "APPROVE"
 EVENT_REQUEST_CHANGES = "REQUEST_CHANGES"
+# COMMENT cannot express approval, which is exactly why it exists here: it is
+# the DEGRADED form of an approve the CI gate refused to post (a rollup that
+# never concluded). It is never a verdict the loop chooses on its own -- see
+# loop._gate_on_checks -- and `submit_review` still refuses anything else.
+EVENT_COMMENT = "COMMENT"
+
+# -- CI check rollup ------------------------------------------------------
+#
+# An APPROVE by the reviewer identity is the operator's cue to merge, so it has
+# to mean "reviewed AND green". These read one commit's rollup so the verdict
+# path can hold that promise; see loop._gate_on_checks for what each state does
+# to a round.
+
+CHECKS_GREEN = "green"
+CHECKS_PENDING = "pending"
+CHECKS_RED = "red"
+# The rollup could not be read at all (an API failure, or more check runs than
+# the page bound). Deliberately its own state rather than folded into either
+# neighbour: unreadable must never approve, and must never post a red verdict
+# naming checks nobody has seen fail.
+CHECKS_UNKNOWN = "unknown"
+
+# Conclusions that do NOT block an approve. `skipped` and `neutral` are the
+# normal answer for a path-filtered matrix job (studio #323's api/cli/mcp/plugin
+# jobs), so treating them as red would block every approve on every repo that
+# filters by path. Every OTHER completed conclusion blocks -- including ones
+# GitHub may add later, which is the conservative direction for a gate whose
+# whole job is to not approve a head it cannot vouch for.
+CHECKS_PASSING_CONCLUSIONS = frozenset({"success", "skipped", "neutral"})
+
+# Legacy commit-status states, mapped into the check-run conclusion vocabulary
+# so both kinds of context classify through one rule. `pending` becomes the
+# empty conclusion -- "still running" -- and an unrecognised state stays itself,
+# which lands it on the blocking side above.
+_STATUS_CONCLUSIONS = {
+    "success": "success",
+    "failure": "failure",
+    "error": "error",
+    "pending": "",
+}
+
+# How many pages either rollup listing will walk. A matrix job set can be large;
+# it cannot plausibly be 500 contexts on one commit, and a bound is what keeps a
+# pathological commit from stalling a poll pass. Past it the rollup is UNKNOWN
+# rather than green -- a partial read cannot support an approve.
+CHECK_RUN_PAGE_LIMIT = 5
 
 # The hidden marker the daemon stamps into every native verdict review it
 # submits, carrying the round it closes. Two jobs, both load-bearing:
@@ -159,6 +203,96 @@ class Review:
         return int(match.group(1)) if match else None
 
 
+@dataclass(frozen=True)
+class CheckContext:
+    """One check on a commit -- a check run or a legacy commit status.
+
+    `conclusion` is normalised lowercase and EMPTY while the check is still
+    running, which is the whole discriminator the rollup needs: a context with
+    no conclusion yet cannot vouch for the commit, and one with a conclusion
+    outside CHECKS_PASSING_CONCLUSIONS votes against it.
+    """
+
+    name: str
+    conclusion: str = ""
+    url: str = ""
+
+    @property
+    def running(self) -> bool:
+        return not self.conclusion
+
+    @property
+    def passing(self) -> bool:
+        return self.conclusion in CHECKS_PASSING_CONCLUSIONS
+
+
+@dataclass(frozen=True)
+class CheckRollup:
+    """One commit's CI rollup, reduced to the question the verdict path asks:
+    may an APPROVE claim this head?
+
+    `failing` and `running` carry the contexts behind the answer, because a
+    verdict that declines to approve has to say WHICH check it is declining on
+    (with its run URL) or the operator is left to go find it.
+    """
+
+    state: str
+    failing: tuple[CheckContext, ...] = ()
+    running: tuple[CheckContext, ...] = ()
+    total: int = 0
+    # Why `state` is CHECKS_UNKNOWN -- an API error, or the page bound. EVERY
+    # read failure lands here, including a 404: this deliberately does not try
+    # to tell "the commit is gone" from any other failure by its error string.
+    # A 404 also answers "the token cannot see this private repo", and the
+    # branch that stepped aside for a presumed force-push posted an UNGATED
+    # approve on a head whose rollup was never read -- fail-open, on a substring
+    # match, in the one component whose contract is to fail closed. The
+    # force-push case is still released: the degraded post gets the same 422
+    # from GitHub and reaches loop._abandon_verdict, which proves absence from
+    # the PR's commit list rather than trusting the message.
+    unreadable: str = ""
+
+    @property
+    def summary(self) -> str:
+        """One log-line description of the rollup."""
+        if self.state == CHECKS_RED:
+            return f"red — failing: {check_names(self.failing)}"
+        if self.state == CHECKS_PENDING:
+            return f"pending — still running: {check_names(self.running)}"
+        if self.state == CHECKS_UNKNOWN:
+            return f"unreadable — {self.unreadable or 'no reason recorded'}"
+        return f"green — {self.total} context(s), none failing or running"
+
+
+def check_names(contexts: "tuple[CheckContext, ...]") -> str:
+    """The contexts' names for a log line, or "none"."""
+    return ", ".join(c.name for c in contexts) or "none"
+
+
+def rollup_of(contexts: "list[CheckContext]") -> CheckRollup:
+    """Reduce read contexts to a rollup state.
+
+    Precedence is failure over running, deliberately: a commit with one job
+    already red and three still going is not "wait and see" -- it cannot be
+    approved at all, and saying so now beats saying it half an hour later.
+
+    NO contexts is GREEN, not pending. A repo (or a commit) with no CI is the
+    pre-gate behaviour and must approve exactly as it always did; the pending
+    hold is for checks that exist and have not finished.
+    """
+    failing = tuple(c for c in contexts if not c.running and not c.passing)
+    running = tuple(c for c in contexts if c.running)
+    if failing:
+        state = CHECKS_RED
+    elif running:
+        state = CHECKS_PENDING
+    else:
+        state = CHECKS_GREEN
+    return CheckRollup(
+        state=state, failing=failing, running=running, total=len(contexts)
+    )
+
+
 def countable_rounds(reviews: list["Review"]) -> int:
     """Rounds represented by the reviewer's substantive reviews.
 
@@ -504,6 +638,161 @@ class GitHub:
                 return out
             page += 1
 
+    # -- CI check rollup ---------------------------------------------------
+
+    def check_rollup(self, owner: str, repo: str, sha: str) -> CheckRollup:
+        """The CI rollup for ONE commit -- never for "the PR".
+
+        Pinned to a SHA on purpose, and the SHA the caller passes is the one its
+        verdict is recorded against: `gh pr checks` (and the GraphQL
+        `statusCheckRollup` behind it) answers for whatever the PR's head is at
+        the moment of the call, which is a different commit as soon as the
+        implementer pushes mid-round. Approving commit A on commit B's rollup is
+        the failure this whole path exists to prevent, so the commit endpoints
+        are read instead: they answer about the commit named in the URL and
+        nothing else.
+
+        BOTH kinds of context are read. Check runs are what GitHub Actions
+        produces; legacy commit statuses are what external CI still posts, and a
+        repo can have either or both. The combined-status endpoint answers
+        `state: pending` for a commit with NO statuses at all, so an empty list
+        is dropped rather than read as "something is running" -- otherwise every
+        approve on every Actions-only repo would hold until the wait bound.
+
+        Never raises except RateLimited (which run_forever's backoff owns): an
+        unreadable rollup is a CHECKS_UNKNOWN answer the caller can hold on, not
+        a reason to abort a poll pass that has other PRs to decide.
+        """
+        contexts: list[CheckContext] = []
+        try:
+            contexts.extend(self._check_runs(owner, repo, sha))
+            contexts.extend(self._commit_statuses(owner, repo, sha))
+        except RateLimited:
+            raise
+        except TruncatedListing as exc:
+            return CheckRollup(CHECKS_UNKNOWN, unreadable=str(exc)[:300])
+        except Exception as exc:
+            return CheckRollup(
+                CHECKS_UNKNOWN, unreadable=f"{type(exc).__name__}: {exc}"[:300]
+            )
+        return rollup_of(contexts)
+
+    def _rollup_listing(self, path: str, key: str, what: str) -> list[dict]:
+        """Page ONE rollup listing to completion, or refuse to answer.
+
+        Completeness is decided by two signals, and the pair is the point --
+        neither alone is sound here:
+
+        * the payload's own `total_count`. Verified against this repo's live
+          `check-runs` (6 runs, `total_count: 6`), and it is what makes the page
+          bound exact rather than off by one: a listing of exactly
+          CHECK_RUN_PAGE_LIMIT * PER_PAGE entries is COMPLETE and says so,
+          instead of reading as truncated because its last page happened to be
+          full.
+        * a short page, the standard end-of-listing signal, used when the
+          endpoint reports no count.
+
+        `total_count` never ends the read EARLY except by being satisfied, and a
+        page that comes back empty ends it too -- an endpoint that claims more
+        than it will serve must not spin the bound. But a count that is still
+        unsatisfied when the pages run out REFUSES: `TruncatedListing`, which
+        `check_rollup` turns into CHECKS_UNKNOWN. That is the case the finding
+        on this method was about -- an unpaged read of a 35-context commit saw
+        30 successes and called a red head green -- and the direction has to be
+        "cannot answer", never "nothing failing in what I got".
+
+        `forbidden_is_rate_limit=False` for the same reason `submit_review`
+        passes it: a 403 here is an authorization fact about the deployment (a
+        credential without `checks: read`) with its own handling one layer up,
+        and collapsing it into RateLimited would abort the whole poll pass and
+        double run_forever's backoff instead of degrading this one verdict.
+        """
+        out: list[dict] = []
+        total: int | None = None
+        for page in range(1, CHECK_RUN_PAGE_LIMIT + 1):
+            data = (
+                self._api(
+                    "-X",
+                    "GET",
+                    path,
+                    "-f",
+                    f"per_page={PER_PAGE}",
+                    "-f",
+                    f"page={page}",
+                    forbidden_is_rate_limit=False,
+                )
+                or {}
+            )
+            items = list(data.get(key) or [])
+            if total is None and isinstance(data.get("total_count"), int):
+                total = int(data["total_count"])
+            out.extend(items)
+            if total is None:
+                if len(items) < PER_PAGE:
+                    return out
+                continue
+            if len(out) >= total:
+                return out
+            if not items:
+                break
+        raise TruncatedListing(
+            f"{path} reports {total if total is not None else 'more'} {what} but "
+            f"served {len(out)} within {CHECK_RUN_PAGE_LIMIT} page(s); the rollup "
+            f"cannot be read completely, so it cannot be called green"
+        )
+
+    def _check_runs(self, owner: str, repo: str, sha: str) -> list[CheckContext]:
+        """The commit's check runs.
+
+        A run that is not `completed` carries no conclusion here whatever its
+        payload says, so "queued", "in_progress" and "waiting" all read as
+        running -- the states GitHub can add to that list are exactly the ones a
+        gate must not mistake for a verdict.
+        """
+        runs = self._rollup_listing(
+            f"repos/{owner}/{repo}/commits/{sha}/check-runs", "check_runs", "check runs"
+        )
+        out: list[CheckContext] = []
+        for run_ in runs:
+            completed = str(run_.get("status") or "").lower() == "completed"
+            out.append(
+                CheckContext(
+                    name=str(run_.get("name") or "unnamed check"),
+                    conclusion=(
+                        str(run_.get("conclusion") or "").lower() if completed else ""
+                    ),
+                    url=str(run_.get("html_url") or run_.get("details_url") or ""),
+                )
+            )
+        return out
+
+    def _commit_statuses(self, owner: str, repo: str, sha: str) -> list[CheckContext]:
+        """The commit's legacy statuses, one context each.
+
+        Paged like the check runs, and for a sharper reason: this endpoint's
+        default page size is 30, so the unpaged read this replaced could see 30
+        successes on a 35-context commit and call a red head green.
+
+        The combined `state` is deliberately ignored and only the `statuses`
+        array is read: the endpoint answers `state: pending` for a commit with NO
+        statuses at all (verified live: `total_count: 0`, `state: pending`), so
+        trusting it would hold every approve on every check-runs-only repo.
+        """
+        statuses = self._rollup_listing(
+            f"repos/{owner}/{repo}/commits/{sha}/status", "statuses", "statuses"
+        )
+        out: list[CheckContext] = []
+        for status in statuses:
+            state = str(status.get("state") or "").lower()
+            out.append(
+                CheckContext(
+                    name=str(status.get("context") or "unnamed status"),
+                    conclusion=_STATUS_CONCLUSIONS.get(state, state),
+                    url=str(status.get("target_url") or ""),
+                )
+            )
+        return out
+
     def my_reviews(self, owner: str, repo: str, number: int) -> list[Review]:
         """My substantive submitted reviews, oldest first -- one per round.
 
@@ -551,11 +840,16 @@ class GitHub:
         under any other login (see assert_review_identity). `commit_id` pins
         the review to the head it judged, so a later push cannot make an old
         verdict look current.
+
+        COMMENT is accepted, narrowly: it is what an approve DEGRADES to when
+        the head's CI rollup never concluded (loop._gate_on_checks). It still
+        cannot express approval -- that is why the gate reaches for it -- so a
+        round closed by one converges nothing.
         """
-        if event not in (EVENT_APPROVE, EVENT_REQUEST_CHANGES):
+        if event not in (EVENT_APPROVE, EVENT_REQUEST_CHANGES, EVENT_COMMENT):
             raise ValueError(
-                f"event must be {EVENT_APPROVE} or {EVENT_REQUEST_CHANGES}, "
-                f"got {event!r} — a COMMENT review cannot close a round"
+                f"event must be one of {EVENT_APPROVE}, {EVENT_REQUEST_CHANGES}, "
+                f"{EVENT_COMMENT}, got {event!r}"
             )
         login = self.assert_review_identity()
         log.info(

{alissa_tools_github_revloop-0.16.6 → alissa_tools_github_revloop-0.16.7}/src/main/alissa/tools/github/revloop/loop.py

@@ -36,8 +36,14 @@ from .config import (
     Config,
 )
 from .ghclient import (
+    CHECKS_GREEN,
+    CHECKS_PENDING,
+    CHECKS_RED,
+    CHECKS_UNKNOWN,
     EVENT_APPROVE,
+    EVENT_COMMENT,
     EVENT_REQUEST_CHANGES,
+    CheckRollup,
     GitHub,
     IssueComment,
     PullRequest,
@@ -93,6 +99,14 @@ MAX_VERDICT_POST_ATTEMPTS = 5
 # day, per stuck PR, with the operator paged exactly once.
 MAX_VERDICT_POST_BACKOFF_SECONDS = 60 * 60
 
+# The GitHub review states the CI gate can produce for a round it refused to
+# approve: a red head lands as CHANGES_REQUESTED, a rollup that never concluded
+# as COMMENTED. Read by _convergence_reason, which must not converge on an
+# approve envelope whose native verdict is one of these -- and must not be
+# broader than this, or it would silently redefine what a DISMISSED review means
+# for convergence (see the comment there).
+GATED_VERDICT_STATES = ("COMMENTED", "CHANGES_REQUESTED")
+
 
 def _post_delay_after(attempts: int) -> float:
     """Seconds to wait after attempt `attempts` before trying again.
@@ -138,6 +152,83 @@ HEAD_MOVED_NOTE = (
     "count as a verdict on the newer code — the next round is owed."
 )
 
+# Prepended to a verdict body whose APPROVE the CI gate turned into a
+# REQUEST_CHANGES: the head's own checks are red. It leads with the failing
+# names and run URLs because that is the only actionable content of the review
+# -- the code review found nothing (the envelope reads approve) and the operator
+# would otherwise have to go hunting for what "not approved" refers to.
+CHECKS_RED_LEAD = (
+    "**Not approving `{sha}` — its CI checks are red.**\n\n"
+    "{failing}\n\n"
+    "The code review itself reached `{verdict}`: nothing below is a new finding "
+    "about the diff. What blocks the approve is the head's own check rollup. An "
+    "approve from this identity is the operator's merge cue, so it has to mean "
+    "*reviewed AND green* — on 2026-07-29 (studio #323) a round approved 3.4 "
+    "hours after CI had gone red, and the red sat unaddressed because the "
+    "approve read as ready.\n\n"
+    "Fix (or re-run) the check(s) above and re-request review; the next round "
+    "can approve the same code on a green head. No label was touched.\n\n"
+)
+
+# One bullet per blocking context. The URL is what makes the finding walkable;
+# a check run without one (rare, and never for Actions) still names itself.
+CHECKS_FAILING_LINE = "- `{name}` — {conclusion}{url}"
+
+# Prepended when the gate held the approve for the whole wait bound and the
+# rollup still had not settled, so the verdict lands as a COMMENT.
+CHECKS_UNSETTLED_LEAD = (
+    "**Recorded as a comment, not an approve — the CI rollup at `{sha}` never "
+    "concluded.**\n\n"
+    "{detail}\n\n"
+    "This round's verdict was held for {waited} min waiting for the head's "
+    "checks to settle ({bound} min bound) and they did not, so it is recorded "
+    "as a comment: an approve would claim a head this loop never saw go green. "
+    "Nothing about the review itself changed — the verdict below is the round's "
+    "own.\n\n"
+    "Submitting this review consumes the pending review request, so the daemon "
+    "will not look at this PR again on its own: **conclude or fix the checks and "
+    "re-request review**, and the next round can approve the same code on a "
+    "green head. No label was touched.\n\n"
+)
+
+# The operator page that follows a DEGRADED verdict, and the reason it exists:
+# submitting any review -- `COMMENT` included -- consumes the pending review
+# request, so the PR leaves `review-requested:@me` the moment the degraded
+# verdict lands. Nothing then brings it back on its own: a `COMMENT` is not what
+# the DEV fix/re-request flow keys on (that reads REQUEST_CHANGES), and the
+# operator's own cue, an APPROVE, never comes. Without this the PR strands
+# silently with an unsettled rollup and no cap-out -- the same class as the #227
+# latch. The red path needs no page: REQUEST_CHANGES re-enters by itself.
+#
+# One page per (round, judged head) through the ping ledger, and it names what
+# to do rather than just what happened.
+CHECKS_UNSETTLED_PAGE = (
+    "**Review round {round} could not approve `{sha}` — its CI rollup never "
+    "concluded.**\n\n"
+    "{detail}\n\n"
+    "The round's verdict is on the PR as a comment-mode review ({url}) rather "
+    "than an approve: the code review itself reached `{verdict}`, but an approve "
+    "from `{reviewer}` is the merge cue and this loop never saw the head go "
+    "green.\n\n"
+    "**This needs a human, because the loop cannot re-enter on its own.** "
+    "Submitting that review consumed the pending review request, so this PR has "
+    "left the daemon's attention set. Two ways forward:\n\n"
+    "1. conclude or fix the checks, then **re-request review from "
+    "`{reviewer}`** — the next round reviews the same code and can approve it on "
+    "a green head;\n"
+    "2. merge with a recorded waiver, if the unsettled checks are known-broken "
+    "rather than known-red.\n\n"
+    "No label was touched and no further round is queued."
+)
+
+# The `{detail}` above, per reason the rollup did not settle.
+CHECKS_STILL_RUNNING = "Still running at the bound: {names}."
+CHECKS_UNREADABLE = (
+    "The rollup could not be read: `{why}`. An unreadable rollup is not a green "
+    "one — check that the reviewer credential carries `checks: read` on this "
+    "repo."
+)
+
 # The operator page for a native verdict post that keeps failing. Loud on
 # purpose: until it lands the round is NOT closed, so the loop is stalled on
 # this PR and no amount of waiting fixes it.
@@ -546,6 +637,33 @@ def parse_reentry_ack(body: str) -> Ack:
     return Ack(rounds=rounds)
 
 
+def checks_unsettled_kind(round_: int, head_sha: str) -> str:
+    """The ping-ledger kind that dedupes ONE degraded round's operator page.
+
+    Per (round, head) like the hold note, and recorded only AFTER the comment
+    lands: this page is the operator's only signal that a PR has left the loop
+    holding an unsettled rollup, so a transient comment failure must retry
+    rather than be swallowed.
+    """
+    return f"checks-unsettled:{round_}:{head_sha}"
+
+
+def checks_hold_kind(round_: int, head_sha: str) -> str:
+    """The ping-ledger kind that dedupes ONE held round's activity line.
+
+    A hold is re-decided every poll, so an append per decision would grow the
+    activity comment by an identical line a minute for as long as CI runs. One
+    line per (round, head) says the whole thing -- "this round is waiting on the
+    checks at this commit" -- and the head is in the key because a round whose
+    verdict is pinned to a different commit is a different wait.
+
+    The issue's contract is at most ONE waiting note per round and no new
+    comments; this appends to the existing mechanical activity comment rather
+    than posting its own, so a held round costs zero new comments.
+    """
+    return f"checks-hold:{round_}:{head_sha}"
+
+
 def verdict_post_kind(round_: int) -> str:
     """The ping-ledger kind that dedupes ONE round's failed-post page.
 
@@ -599,6 +717,32 @@ class Decision:
     reenqueued: bool = False
 
 
+@dataclass(frozen=True)
+class ChecksGate:
+    """What the head's CI rollup does to a round's APPROVE verdict.
+
+    Three shapes, matching the three things the gate can decide:
+
+    * `hold` set -- do not post at all this poll (the rollup has not settled and
+      the wait bound has not run out). The round stays open, exactly as it does
+      inside the pre-post grace window.
+    * `event` changed -- post, but not as an approve: REQUEST_CHANGES on a red
+      head, COMMENT when the rollup never settled. `lead` is prepended to the
+      verdict body and names the checks.
+    * neither -- green (or nothing to gate): the post proceeds unchanged.
+    """
+
+    hold: Decision | None = None
+    event: str = EVENT_APPROVE
+    lead: str = ""
+    # The rollup state that produced this decision, for the log/activity line.
+    state: str = CHECKS_GREEN
+    # The human-readable "why it did not settle", reused verbatim in the
+    # operator page that follows a degraded verdict (see _page_unsettled_checks)
+    # so the page and the review record cannot drift apart.
+    detail: str = ""
+
+
 def session_name(pr: PullRequest, round_: int) -> str:
     """A tmux-safe reviewer session name, unique per spawn.
 
@@ -651,6 +795,12 @@ class ReviewWatcher:
         # dry-run should not re-announce the same drift every poll either --
         # see _warn_identity_drift.
         self._dry_run_drift: set[tuple[str, int, str]] = set()
+        # (repo slug, number, round, judged head) -> the rollup summary this
+        # process already read for it in DRY-RUN. The dry-run branch returns
+        # before any ledger write, so without this the diagnostic re-reads the
+        # rollup (two API calls) on every poll, forever, for every PR with an
+        # owed approve. In-memory for the same reason _dry_run_drift is.
+        self._dry_run_rollups: dict[tuple[str, int, int, str], str] = {}
 
     # -- per-PR decision ---------------------------------------------------
 
@@ -809,14 +959,37 @@ class ReviewWatcher:
             )
 
         if self.config.dry_run:
+            # The rollup is READ here even in dry-run (a read takes nothing on
+            # GitHub and writes no ledger row), because "would this approve have
+            # been gated?" is exactly the question an operator reaches for
+            # dry-run to answer -- the same argument the identity-drift check
+            # makes for observing rather than staying silent.
+            # ...but ONCE per round per head, not every poll. A dry-run pass
+            # returns before the ledger bookkeeping (deliberately: it must write
+            # no durable state), so the dedupe is in-memory and
+            # process-lifetime, exactly as _dry_run_drift is and for the same
+            # reason -- a dry-run observation must never be silenced by
+            # something a production pass could have written, or the other way
+            # round.
+            checks = ""
+            if verdict == VERDICT_APPROVE:
+                judged = self._judged_head(pr, round_)
+                seen = (pr.full_name, pr.number, round_, judged)
+                if seen not in self._dry_run_rollups:
+                    rollup = self.github.check_rollup(pr.owner, pr.repo, judged)
+                    self._dry_run_rollups[seen] = rollup.summary
+                checks = (
+                    f"; CI rollup at the judged head is "
+                    f"{self._dry_run_rollups[seen]}"
+                )
             log.info(
-                "[dry-run] would submit a native %s review for round %d of %s",
-                verdict, round_, pr.slug,
+                "[dry-run] would submit a native %s review for round %d of %s%s",
+                verdict, round_, pr.slug, checks,
             )
             return Decision(
                 Action.AWAITING_POST,
                 f"[dry-run] round {round_} would be closed with a native "
-                f"{verdict} review",
+                f"{verdict} review{checks}",
                 round_,
                 task_ref=task.ref,
             )
@@ -853,7 +1026,18 @@ class ReviewWatcher:
         judged = str(row["head_sha"] or pr.head_sha)
         moved = bool(judged) and judged != pr.head_sha
         event = EVENT_APPROVE if verdict == VERDICT_APPROVE else EVENT_REQUEST_CHANGES
-        body = NATIVE_VERDICT_BODY.format(
+
+        # THE CI GATE (issue #58). Only an APPROVE is gated: a REQUEST_CHANGES on
+        # a red head is already a "not ready" signal and says nothing that CI
+        # could contradict.
+        gate = ChecksGate()
+        if event == EVENT_APPROVE:
+            gate = self._gate_on_checks(pr, task, round_, judged)
+            if gate.hold is not None:
+                return gate.hold
+            event = gate.event
+
+        body = gate.lead + NATIVE_VERDICT_BODY.format(
             round=round_,
             verdict=verdict,
             task_note=_VERDICT_TASK_NOTE.format(task_ref=task.ref),
@@ -881,24 +1065,226 @@ class ReviewWatcher:
             # take down a poll pass that has other PRs to decide.
             return self._verdict_post_failed(pr, task, round_, verdict, judged, exc)
 
+        # Named in all three records when the gate downgraded the verdict, so
+        # "the envelope says approve but GitHub says otherwise" is never a
+        # mystery in the log, the activity comment, or the poll snapshot.
+        gate_note = (
+            ""
+            if gate.state == CHECKS_GREEN
+            else f" — CI gate: the rollup at {judged[:8]} is {gate.state}, so the "
+            f"{verdict} envelope did not post as an APPROVE"
+        )
         self.state.record_verdict_post(pr.full_name, pr.number, round_, url)
         log.info(
-            "%s round %d closed: native %s review submitted as %s (%s)",
-            pr.slug, round_, event, self.github.login, url or "no url",
+            "%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,
         )
         self._append_activity(
             pr,
             f"- {_now()} — round {round_} — native `{event}` review submitted "
-            f"as `{self.github.login}` (verdict of record)",
+            f"as `{self.github.login}` (verdict of record){gate_note}",
         )
+        if event == EVENT_COMMENT:
+            # A degraded verdict takes the PR out of the loop (the review
+            # request is consumed) without leaving a signal anything acts on.
+            self._page_unsettled_checks(pr, round_, judged, verdict, url, gate.detail)
         return Decision(
             Action.POSTED,
             f"round {round_} closed with a native {event} review as "
-            f"{self.github.login}",
+            f"{self.github.login}{gate_note}",
             round_,
             task_ref=task.ref,
         )
 
+    def _gate_on_checks(
+        self, pr: PullRequest, task: Task, round_: int, judged: str
+    ) -> ChecksGate:
+        """Decide what the CI rollup at `judged` does to this round's approve.
+
+        The rule the gate exists to keep: an APPROVE by the reviewer identity
+        means *reviewed AND green*, because it is the operator's cue to merge.
+        On studio #323 a round approved 3.4 hours after the head's `test` check
+        had gone red, the operator's merge gate received an "approved, ready" PR
+        that was unmergeable-red, and the failure sat unaddressed until a human
+        noticed (issue #58).
+
+        Read on the head the verdict is PINNED to, never the PR's current head:
+        approving commit A on commit B's rollup is the same class of error as
+        stamping an old verdict onto a new head (see _judged_head). When the two
+        differ the existing head-moved handling still does its job -- the review
+        is recorded against `judged` and does not converge the loop -- and this
+        gate additionally refuses to call that commit green on someone else's
+        checks.
+
+        What it never does: touch labels. `alissa:maintain` and every other
+        cross-daemon trigger stays an operator/devloop concern; revloop shapes
+        its own verdict and nothing else. Nor does it post a comment of its own
+        while waiting -- the wait note goes into the existing mechanical activity
+        comment, once per held round (checks_hold_kind).
+        """
+        rollup = self.github.check_rollup(pr.owner, pr.repo, judged)
+
+        if rollup.state == CHECKS_GREEN:
+            log.debug(
+                "%s round %d: CI rollup at %s is %s — approving as usual",
+                pr.slug, round_, judged[:8], rollup.summary,
+            )
+            return ChecksGate()
+
+        if rollup.state == CHECKS_RED:
+            log.warning(
+                "%s round %d: NOT approving %s — its CI rollup is %s. The "
+                "%s envelope lands as a %s review instead",
+                pr.slug, round_, judged[:8], rollup.summary,
+                VERDICT_APPROVE, EVENT_REQUEST_CHANGES,
+            )
+            failing = "\n".join(
+                CHECKS_FAILING_LINE.format(
+                    name=context.name,
+                    conclusion=context.conclusion or "not concluded",
+                    url=f" — {context.url}" if context.url else "",
+                )
+                for context in rollup.failing
+            )
+            return ChecksGate(
+                event=EVENT_REQUEST_CHANGES,
+                lead=CHECKS_RED_LEAD.format(
+                    sha=judged[:8], failing=failing, verdict=VERDICT_APPROVE
+                ),
+                state=CHECKS_RED,
+            )
+
+        # PENDING (checks still running) or UNKNOWN (the rollup could not be
+        # read) -- neither can support an approve, and both can settle, so both
+        # HOLD the round first and only degrade at the bound.
+        #
+        # The clock is stamped against the CONDITION being waited on, and gets
+        # exactly one restart: when an `unknown` hold is promoted to a `pending`
+        # one. A transient read failure is not an observation of checks running,
+        # so it must not eat the bound a real suite is entitled to. One restart,
+        # never "restart whenever the state changes" -- a reader flapping between
+        # the two would then push the bound out forever, which is precisely the
+        # unbounded hold this bound exists to prevent.
+        held_at, held_state = self.state.checks_hold(pr.full_name, pr.number, round_)
+        promoted = held_state == CHECKS_UNKNOWN and rollup.state == CHECKS_PENDING
+        if held_at is None or promoted:
+            held_at = self.state.record_checks_hold(
+                pr.full_name, pr.number, round_, rollup.state
+            )
+        waited = max(time.time() - held_at, 0)
+        bound = self.config.checks_wait_seconds
+        if waited < bound:
+            # One line per poll, one activity note per held round; see
+            # checks_hold_kind.
+            log.info(
+                "%s round %d: holding its %s — CI rollup at %s is %s (%dm of the "
+                "%dm bound waited)",
+                pr.slug, round_, VERDICT_APPROVE, judged[:8], rollup.summary,
+                waited // 60, bound // 60,
+            )
+            self._note_checks_hold(pr, round_, judged, rollup)
+            return ChecksGate(
+                hold=Decision(
+                    Action.AWAITING_POST,
+                    f"round {round_} holds its {VERDICT_APPROVE} — the CI rollup "
+                    f"at {judged[:8]} is {rollup.summary}; "
+                    f"{int((bound - waited) // 60)}m of the wait bound left",
+                    round_,
+                    task_ref=task.ref,
+                ),
+                state=rollup.state,
+            )
+
+        log.warning(
+            "%s round %d: the CI rollup at %s is still %s after %dm — recording "
+            "the %s envelope as a %s review, never an APPROVE on an unverified "
+            "head",
+            pr.slug, round_, judged[:8], rollup.summary, waited // 60,
+            VERDICT_APPROVE, EVENT_COMMENT,
+        )
+        detail = (
+            CHECKS_STILL_RUNNING.format(
+                names=", ".join(f"`{c.name}`" for c in rollup.running) or "none"
+            )
+            if rollup.state == CHECKS_PENDING
+            else CHECKS_UNREADABLE.format(why=rollup.unreadable or "no reason recorded")
+        )
+        return ChecksGate(
+            event=EVENT_COMMENT,
+            lead=CHECKS_UNSETTLED_LEAD.format(
+                sha=judged[:8],
+                detail=detail,
+                waited=int(waited // 60),
+                bound=int(bound // 60),
+            ),
+            state=rollup.state,
+            detail=detail,
+        )
+
+    def _page_unsettled_checks(
+        self,
+        pr: PullRequest,
+        round_: int,
+        judged: str,
+        verdict: str,
+        url: str,
+        detail: str,
+    ) -> None:
+        """Page the operator ONCE for a round that degraded to a comment.
+
+        See CHECKS_UNSETTLED_PAGE for why this is owed: the degraded verdict
+        consumes the review request, so the PR silently leaves the poll set with
+        nothing downstream of it. The ledger row lands only AFTER the comment
+        does, as with every ping here -- but note this one may not get a second
+        chance, because the very post that made it necessary is what takes the
+        PR out of the search. So a failure logs at ERROR (with the body, which is
+        then the only place the diagnosis exists) rather than at warning.
+        """
+        kind = checks_unsettled_kind(round_, judged)
+        if self.state.pinged(pr.full_name, pr.number, kind):
+            return
+        body = CHECKS_UNSETTLED_PAGE.format(
+            round=round_,
+            sha=judged[:8],
+            detail=detail,
+            url=url or "no url recorded",
+            verdict=verdict,
+            reviewer=self.github.login,
+        )
+        try:
+            self.github.comment(pr.owner, pr.repo, pr.number, body)
+        except Exception as exc:
+            log.error(
+                "%s round %d: could not post the unsettled-checks page (%s). The "
+                "degraded verdict consumed the review request, so this PR has "
+                "left the poll set and the page may never be retried — it needed "
+                "to say:\n%s",
+                pr.slug, round_, exc, body,
+            )
+            return
+        self.state.record_ping(pr.full_name, pr.number, kind)
+
+    def _note_checks_hold(
+        self, pr: PullRequest, round_: int, judged: str, rollup: CheckRollup
+    ) -> None:
+        """Append ONE activity line for a round held on its checks.
+
+        Ledger row after the append, like every other activity note here, so a
+        transient comment failure retries next poll instead of losing the line.
+        """
+        kind = checks_hold_kind(round_, judged)
+        if self.state.pinged(pr.full_name, pr.number, kind):
+            return
+        if not self._append_activity(
+            pr,
+            f"- {_now()} — round {round_} — verdict held: the CI rollup at "
+            f"`{judged[:8]}` is {rollup.summary}. An approve has to mean "
+            f"reviewed AND green, so the round stays open "
+            f"(bound: {self.config.checks_wait_seconds // 60}m).",
+        ):
+            return
+        self.state.record_ping(pr.full_name, pr.number, kind)
+
     def _judged_head(self, pr: PullRequest, round_: int) -> str:
         """The head round `round_`'s verdict is ABOUT — not the current one.
 
@@ -1361,6 +1747,29 @@ class ReviewWatcher:
         if newest.state == "APPROVED":
             return "last GitHub review state is APPROVED"
 
+        # A native verdict THIS daemon posted at this head that is NOT an
+        # approve is the daemon's own refusal to approve the head, and it
+        # outranks the envelope it was posted from. Today only the CI gate
+        # produces that shape (issue #58): a red or never-concluded rollup turns
+        # an approve envelope into a REQUEST_CHANGES or COMMENT review. Without
+        # this, the very next poll would converge on the envelope, withdraw the
+        # review request, and take the PR out of the loop on a verdict the
+        # daemon deliberately declined to post as an APPROVE -- leaving nothing
+        # to re-enter and no later green round to approve it.
+        #
+        # Deliberately narrowed to the two states the gate can produce.
+        # `SUBMITTED_STATES` also includes DISMISSED, and a daemon-posted review
+        # carries its `verdict_round` forever -- so a broader test would ALSO
+        # change what a dismissed approve does to convergence (today the
+        # envelope still converges it). That may well be wrong, but it is
+        # pre-existing and its own question: TASK-939082213. This change is
+        # exactly the one its rationale claims.
+        if (
+            newest.verdict_round is not None
+            and newest.state in GATED_VERDICT_STATES
+        ):
+            return None
+
         # Only checkable once a review task exists; before that there is
         # nowhere for a verdict to have been recorded.
         if task is not None and self.alissa.latest_verdict(task.ref) == VERDICT_APPROVE:

{alissa_tools_github_revloop-0.16.6 → alissa_tools_github_revloop-0.16.7}/src/main/alissa/tools/github/revloop/state.py

@@ -107,6 +107,20 @@ CREATE TABLE IF NOT EXISTS verdict_posts (
     -- no longer a commit of the PR (a force-push landed under it). The round is
     -- then released rather than held open forever; see loop._abandon_verdict.
     abandoned_at  INTEGER,
+    -- When this round's APPROVE was FIRST held back because the judged head's
+    -- CI rollup had not settled. The wait bound is measured from here, so a
+    -- rollup that never concludes degrades the verdict to a comment at a fixed
+    -- distance from the first observation rather than from whenever the last
+    -- poll happened to land. NULL means the gate never held this round.
+    checks_held_at INTEGER,
+    -- WHICH unsettled condition that stamp belongs to ('pending' -- checks are
+    -- genuinely running -- or 'unknown' -- the rollup could not be read). The
+    -- bound is defined against the first observation of the condition being
+    -- waited on, and a transient read error is not that observation, so the
+    -- clock gets exactly one restart when an 'unknown' hold is promoted to a
+    -- 'pending' one. The policy lives in loop._gate_on_checks; this column is
+    -- what lets it be decided from the ledger instead of from memory.
+    checks_held_state TEXT,
     review_url    TEXT,
     last_error    TEXT,
     PRIMARY KEY (repo, number, round)
@@ -133,16 +147,24 @@ CREATE TABLE IF NOT EXISTS poll_snapshots (
 );
 """
 
-# Columns added to `poll_snapshots` after it first shipped. CREATE TABLE IF NOT
-# EXISTS is not a migration: an existing database keeps the ORIGINAL table, so
-# these are ALTERed in on open. Each carries a NOT NULL default, which is what
-# lets an ALTER backfill every historical row without a rewrite -- an old pass
-# genuinely posted no verdicts, so 0 is the true value, not a placeholder.
-_SNAPSHOT_ADDED_COLUMNS = (
-    ("posted", "INTEGER NOT NULL DEFAULT 0"),
-    ("awaiting_post", "INTEGER NOT NULL DEFAULT 0"),
-    ("abandoned", "INTEGER NOT NULL DEFAULT 0"),
-)
+# Columns added to a table after it first shipped. CREATE TABLE IF NOT EXISTS is
+# not a migration: an existing database keeps the ORIGINAL table, so these are
+# ALTERed in on open. A NOT NULL default is what lets an ALTER backfill every
+# historical row without a rewrite -- an old pass genuinely posted no verdicts,
+# so 0 is the true value, not a placeholder. Where "never happened" has no
+# numeric truth (`checks_held_at`), the column is nullable instead and NULL
+# means exactly that.
+_ADDED_COLUMNS = {
+    "poll_snapshots": (
+        ("posted", "INTEGER NOT NULL DEFAULT 0"),
+        ("awaiting_post", "INTEGER NOT NULL DEFAULT 0"),
+        ("abandoned", "INTEGER NOT NULL DEFAULT 0"),
+    ),
+    "verdict_posts": (
+        ("checks_held_at", "INTEGER"),
+        ("checks_held_state", "TEXT"),
+    ),
+}
 
 
 class State:
@@ -181,27 +203,26 @@ class State:
         if self._spawns_keyed_by_round():
             self._migrate_spawns()
         self._db.executescript(SCHEMA)
-        self._migrate_snapshot_columns()
+        self._migrate_added_columns()
         self._db.commit()
 
-    def _migrate_snapshot_columns(self) -> None:
-        """Add any `poll_snapshots` column a pre-existing database predates.
+    def _migrate_added_columns(self) -> None:
+        """Add any column a pre-existing database predates.
 
-        Runs after the schema script (which creates the table with the full
+        Runs after the schema script (which creates every table with its full
         column list on a fresh database, making this a no-op there) and is
         idempotent: the existing columns are read first, so a restart never
         re-ALTERs. Read-only openers never reach it -- the console must not
         migrate a database the daemon owns.
         """
-        existing = {
-            row["name"]
-            for row in self._db.execute("PRAGMA table_info(poll_snapshots)").fetchall()
-        }
-        for name, decl in _SNAPSHOT_ADDED_COLUMNS:
-            if name not in existing:
-                self._db.execute(
-                    f"ALTER TABLE poll_snapshots ADD COLUMN {name} {decl}"
-                )
+        for table, columns in _ADDED_COLUMNS.items():
+            existing = {
+                row["name"]
+                for row in self._db.execute(f"PRAGMA table_info({table})").fetchall()
+            }
+            for name, decl in columns:
+                if name not in existing:
+                    self._db.execute(f"ALTER TABLE {table} ADD COLUMN {name} {decl}")
 
     def _migrate_spawns(self) -> None:
         """Re-key an old round-keyed `spawns` by session, in ONE transaction.
@@ -488,6 +509,41 @@ class State:
         row = self.get_verdict_post(repo, number, round_)
         return int(row["attempts"]) if row else 0
 
+    def checks_hold(
+        self, repo: str, number: int, round_: int
+    ) -> "tuple[int | None, str | None]":
+        """When this round's approve was first held on CI, and on WHICH
+        condition -- (None, None) if it has never been held.
+
+        A read, deliberately: whether an existing stamp still applies is a
+        policy question about CI (see loop._gate_on_checks), and this table's job
+        is to remember the answer, not to make it.
+        """
+        row = self.get_verdict_post(repo, number, round_)
+        if row is None or not row["checks_held_at"]:
+            return None, None
+        return int(row["checks_held_at"]), (row["checks_held_state"] or None)
+
+    def record_checks_hold(
+        self, repo: str, number: int, round_: int, condition: str
+    ) -> int:
+        """Start (or restart) the hold clock for this round; return the stamp.
+
+        The caller decides WHEN to call this -- once when the hold begins, and at
+        most once more when an unreadable hold is promoted to a genuinely pending
+        one, because the bound is defined against the first observation of the
+        condition actually being waited on. Unconditional here so that policy
+        stays in one place instead of being half-expressed as a WHERE clause.
+        """
+        now = int(time.time())
+        self._db.execute(
+            "UPDATE verdict_posts SET checks_held_at = ?, checks_held_state = ? "
+            "WHERE repo=? AND number=? AND round=?",
+            (now, condition, repo, number, round_),
+        )
+        self._db.commit()
+        return now
+
     def record_verdict_post_abandoned(
         self, repo: str, number: int, round_: int, why: str
     ) -> None:
@@ -546,7 +602,8 @@ class State:
         """Verdict-post rows, newest observation first."""
         return self._read_rows(
             "SELECT repo, number, round, first_seen_at, head_sha, attempts, "
-            "last_attempt_at, posted_at, abandoned_at, review_url, last_error "
+            "last_attempt_at, posted_at, abandoned_at, checks_held_at, "
+            "checks_held_state, review_url, last_error "
             "FROM verdict_posts "
             "ORDER BY first_seen_at DESC, number DESC",
             limit,

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

@@ -0,0 +1 @@
+0.16.7

{alissa_tools_github_revloop-0.16.6 → alissa_tools_github_revloop-0.16.7/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.16.6
+Version: 0.16.7
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

@@ -1 +0,0 @@
-0.16.6