alissa-tools-github-revloop 0.15.0__tar.gz → 0.16.1__tar.gz

alissa_tools_github_revloop-0.16.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/MANIFEST.in

@@ -1,2 +1,4 @@
 include requirements.txt
 include src/main/alissa/tools/github/revloop/version
+include LICENSE
+include NOTICE

alissa_tools_github_revloop-0.16.1/NOTICE

@@ -0,0 +1,5 @@
+alissa-tools-github-revloop
+Copyright 2026 CORE FAHERA ENTERPRISE HOLDINGS S. DE R.L.
+
+"Alissa" and "Fahera" are trademarks of CORE FAHERA ENTERPRISE HOLDINGS S. DE R.L.
+This NOTICE and the accompanying license do not grant permission to use these trademarks.

{alissa_tools_github_revloop-0.15.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.16.1}/PKG-INFO

@@ -1,17 +1,22 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.15.0
+Version: 0.16.1
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera
 Author-email: support@alissa.app
+License: Apache-2.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
 Dynamic: author
 Dynamic: author-email
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
 Dynamic: requires-python
 Dynamic: summary
 
@@ -59,3 +64,11 @@ pip install -e ./alissa-tools-github-revloop
 distribution version lives in the plain-text `version` file next to the module
 it versions (`src/main/alissa/tools/github/revloop/version`), read by both
 `setup.py` and `version.py`.
+
+## License
+
+Licensed under the Apache License 2.0 — see the `LICENSE` and `NOTICE` files
+shipped with this distribution.
+
+"Alissa" and "Fahera" are trademarks of CORE FAHERA ENTERPRISE HOLDINGS S. DE
+R.L.; the license does not grant permission to use them.

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/README.md

@@ -42,3 +42,11 @@ pip install -e ./alissa-tools-github-revloop
 distribution version lives in the plain-text `version` file next to the module
 it versions (`src/main/alissa/tools/github/revloop/version`), read by both
 `setup.py` and `version.py`.
+
+## License
+
+Licensed under the Apache License 2.0 — see the `LICENSE` and `NOTICE` files
+shipped with this distribution.
+
+"Alissa" and "Fahera" are trademarks of CORE FAHERA ENTERPRISE HOLDINGS S. DE
+R.L.; the license does not grant permission to use them.

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/setup.py

@@ -28,6 +28,8 @@ with open("README.md") as file:
 setup(
     name="alissa-tools-github-revloop",
     version=version,
+    license="Apache-2.0",
+    license_files=("LICENSE", "NOTICE"),
     description="ALISSA-TOOLS-GITHUB-REVLOOP",
     long_description=readme,
     long_description_content_type='text/markdown',

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/src/main/alissa/tools/github/revloop/__main__.py

@@ -80,6 +80,15 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="OWNER/REPO",
         help="only watch this repo; repeatable. Replaces the config list entirely.",
     )
+    over.add_argument(
+        "--operator",
+        dest="operators",
+        action="append",
+        metavar="LOGIN",
+        help="GitHub login allowed to ack a review-loop re-entry "
+        "(`alissa-review: re-enter +N` on a capped PR); repeatable. Replaces "
+        "the config list entirely. Empty = no ack is ever honoured.",
+    )
     over.add_argument("--poll-interval", type=int, metavar="SECONDS")
     over.add_argument("--round-cap", type=int, metavar="N", help="CR9 round cap")
     over.add_argument("--hub-template", metavar="TEMPLATE")
@@ -114,6 +123,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
     through. `repos` becomes a tuple so it matches the config-file form."""
     return {
         "repos": tuple(args.repos) if args.repos else None,
+        "operators": tuple(args.operators) if args.operators else None,
         "poll_interval": args.poll_interval,
         "round_cap": args.round_cap,
         "hub_template": args.hub_template,

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/src/main/alissa/tools/github/revloop/config.py

@@ -41,6 +41,7 @@ CONFIG_KEYS = (
     "poll_interval",
     "round_cap",
     "repos",
+    "operators",
     "agent_profile",
     "reviewer_login",
     "state_path",
@@ -68,6 +69,14 @@ class Config:
     # Empty tuple means "every repo that requests a review from me".
     repos: tuple[str, ...] = ()
 
+    # GitHub logins whose re-entry ack may raise a capped PR's effective cap
+    # (loop.parse_reentry_ack). Empty -- the default -- means NO ack is ever
+    # honoured: the lever fails closed, because anyone who can comment on a PR
+    # could otherwise buy it more rounds. The reviewer identity itself is never
+    # an operator however it is configured (the daemon's own escalation quotes
+    # the grammar, and self-granting would defeat CR9's cap outright).
+    operators: tuple[str, ...] = ()
+
     agent_profile: str = "claude"
     reviewer_login: str | None = None  # None -> resolve once via `gh api user`
 
@@ -148,7 +157,10 @@ class Config:
                 f"on_missing_hub must be one of {sorted(_HUB_MODES)}, got {hub_mode!r}"
             )
 
-        repos = tuple(raw.get("repos", ()))
+        repos = _string_list(raw.get("repos", ()), "repos", "owner/repo entries")
+        operators = _string_list(
+            raw.get("operators", ()), "operators", "GitHub logins"
+        )
         if hub_mode == HUB_ADD and not repos:
             # Anyone who can request a review could otherwise cause an arbitrary
             # repo to be cloned onto this machine and opened as an agent's cwd.
@@ -175,6 +187,7 @@ class Config:
             poll_interval=interval,
             round_cap=cap,
             repos=repos,
+            operators=operators,
             agent_profile=raw.get("agent_profile", "claude"),
             reviewer_login=raw.get("reviewer_login"),
             state_path=Path(state_path).expanduser() if state_path else None,
@@ -184,6 +197,22 @@ class Config:
         )
 
 
+def _string_list(value: Any, key: str, what: str) -> tuple[str, ...]:
+    """A config list key as a tuple of non-empty, stripped strings.
+
+    The guard is the point: JSON makes `"repos": "org/repo"` an easy typo, and
+    Python would iterate it into single CHARACTERS -- an allowlist of 30-odd
+    one-character names, which `watches()` then matches against nothing and the
+    daemon quietly reviews no PR at all. Both list keys go through here so
+    neither can grow the footgun back.
+    """
+    if isinstance(value, str):
+        raise ValueError(
+            f"{key} must be a list of {what}, not a string (got {value!r})"
+        )
+    return tuple(str(item).strip() for item in value if str(item).strip())
+
+
 def load_config_file(path: Path) -> dict[str, Any]:
     data = json.loads(Path(path).expanduser().read_text())
     if not isinstance(data, dict):

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/src/main/alissa/tools/github/revloop/ghclient.py

@@ -17,6 +17,19 @@ log = logging.getLogger(__name__)
 # was never submitted, so it does not close a round.
 SUBMITTED_STATES = {"APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"}
 
+# GitHub's page size ceiling, and how many pages of issue comments we will walk.
+# Both readers of the comment list need the WHOLE thread, and a truncated read
+# fails silently in each: the activity-comment finder would stop seeing its own
+# comment and fork a second one, and the re-entry ack scan would drop an
+# operator's ack on the floor -- on exactly the long-lived, capped-out PRs where
+# the thread is longest and the ack matters most. Bounded anyway so a
+# pathological thread cannot stall a poll pass; 20 pages is 2000 comments, and
+# the truncation is logged rather than assumed away. Paged explicitly rather
+# than with `gh api --paginate`: this targets gh 2.4.0, whose --paginate
+# concatenates one JSON document per page and would not parse.
+PER_PAGE = 100
+COMMENT_PAGE_LIMIT = 20
+
 
 @dataclass(frozen=True)
 class PullRequest:
@@ -234,24 +247,40 @@ class GitHub:
         )
 
     def issue_comments(self, owner: str, repo: str, number: int) -> list[IssueComment]:
-        data = (
-            self._api(
-                "-X",
-                "GET",
-                f"repos/{owner}/{repo}/issues/{number}/comments",
-                "-f",
-                "per_page=100",
+        """Every issue comment on the PR, oldest first -- see COMMENT_PAGE_LIMIT
+        for why this pages instead of reading the first 100 and hoping."""
+        out: list[IssueComment] = []
+        for page in range(1, COMMENT_PAGE_LIMIT + 1):
+            data = (
+                self._api(
+                    "-X",
+                    "GET",
+                    f"repos/{owner}/{repo}/issues/{number}/comments",
+                    "-f",
+                    f"per_page={PER_PAGE}",
+                    "-f",
+                    f"page={page}",
+                )
+                or []
             )
-            or []
-        )
-        return [
-            IssueComment(
-                id=int(c.get("id") or 0),
-                author=(c.get("user") or {}).get("login", ""),
-                body=c.get("body") or "",
+            out.extend(
+                IssueComment(
+                    id=int(c.get("id") or 0),
+                    author=(c.get("user") or {}).get("login", ""),
+                    body=c.get("body") or "",
+                )
+                for c in data
             )
-            for c in data
-        ]
+            if len(data) < PER_PAGE:
+                break
+        else:
+            log.warning(
+                "%s/%s#%d has more than %d comments — only the first %d were "
+                "read; an operator re-entry ack past that point cannot be seen",
+                owner, repo, number, COMMENT_PAGE_LIMIT * PER_PAGE,
+                COMMENT_PAGE_LIMIT * PER_PAGE,
+            )
+        return out
 
     def update_comment(self, owner: str, repo: str, comment_id: int, body: str) -> None:
         self._api(

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/src/main/alissa/tools/github/revloop/loop.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 import logging
 import re
 import secrets
+import sqlite3
 import time
 from collections import Counter
 from dataclasses import dataclass
@@ -21,7 +22,7 @@ from pathlib import Path
 
 from .alissa import VERDICT_APPROVE, Alissa, Task
 from .config import HUB_ADD, ON_MISSING_SKIP, Config
-from .ghclient import GitHub, PullRequest, RateLimited, Review
+from .ghclient import GitHub, IssueComment, PullRequest, RateLimited, Review
 from .proc import CommandError
 from .state import State
 
@@ -79,12 +80,27 @@ _RELEASE_SLOT = (
     "`alissa tmux kill {session}`. Do nothing after it."
 )
 
+# The cap the reviewer must write down. The review-task description template in
+# the alissa-code-review skill documents a default of 3, which this daemon's
+# config has not used since the cap moved to 10 -- so round 1 (the round that
+# CREATES the review task) has to carry the effective number, or every task
+# description keeps repeating the stale one. Both directives say it: a round-k
+# reviewer reading a task that records the wrong cap is the case that surfaced
+# the drift in the first place.
+_RECORD_THE_CAP = (
+    "This loop's EFFECTIVE round cap is {cap} (the daemon's config, plus any "
+    "operator re-entry grants) — record THAT number in the review task "
+    "description, and correct it if the description carries a different cap "
+    "from a stale template default. "
+)
+
 ROUND_1_DIRECTIVE = (
     "You are a PR REVIEWER, not an implementer. {assignment} "
     "Load the alissa-code-review skill and follow procedures/review-a-pr.md: "
     "hydrate the task and the PR it names, review per the rubric, post "
     "severity-tagged comments via gh pr review, record the verdict evidence, "
     "move the task to pending_validation. "
+    + _RECORD_THE_CAP
     + _CLOSE_THE_ROUND +
     "NEVER push commits, merge, or change PR state. "
     "Do NOT create further ali-* sessions. "
@@ -98,19 +114,88 @@ ROUND_K_DIRECTIVE = (
     "including its round-k section: verify the triage of every prior finding, "
     "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
     + _CLOSE_THE_ROUND +
     "NEVER push commits, merge, or change PR state. "
     "Do NOT create further ali-* sessions. "
     + _RELEASE_SLOT
 )
 
+# The operator re-entry ack (issue #42). A capped PR is unreviewable until an
+# operator says otherwise, and the cap-out message used to OFFER "re-enter with
+# a fresh cap" without any mechanism existing: the only lever was raising
+# round_cap for every PR and restarting the daemon. The grammar below is that
+# mechanism, and it is deliberately dull -- one line, a literal prefix, an
+# explicit +N -- so it is trivially auditable in the PR's comment history and
+# impossible to fire by accident.
+REENTRY_GRAMMAR = "alissa-review: re-enter +N"
+
+# The ceiling on a single ack. A constant, not a config key: the point of the
+# ack is a SMALL bounded re-entry (the live case wanted exactly one round), and
+# an operator who needs more says so again in another comment -- which leaves
+# two auditable rows instead of one giant grant. Pinned by a test.
+MAX_REENTRY_ROUNDS = 5
+
+# "Is this line trying to be a directive?" -- the loose sieve. A line that
+# reaches for the prefix but misses the grammar is reported as malformed
+# (a silent typo would look exactly like a cap that refuses to lift).
+_ACK_LEAD_RE = re.compile(r"^`?\s*alissa-review\s*:", re.IGNORECASE)
+
+# The grammar itself: the WHOLE line, optionally wrapped in backticks, is the
+# directive. Anchored on both ends so a mention inside prose ("just post
+# `alissa-review: re-enter +1`") is not a directive, and quoted lines (`>`) are
+# dropped before matching so replying to the escalation cannot re-grant it.
+_ACK_RE = re.compile(
+    r"^`?\s*alissa-review:\s+re-enter\s+\+(\d{1,3})\s*`?$", re.IGNORECASE
+)
+
 ESCALATION_COMMENT = (
     "**Review loop cap-out (CR9)** — {rounds} rounds ran on this PR without "
-    "converging on `approve`. Per the alissa-code-review skill the loop does not "
-    "run past the cap and never silently merges; this needs an operator decision "
-    "(merge with a recorded waiver, direct specific fixes and re-enter with a "
-    "fresh cap, or park it).\n\n"
-    "Last verdict: `{last_state}` at `{sha}`."
+    "converging on `approve` (effective cap {cap}).{grant_note} Per the "
+    "alissa-code-review skill the loop does not run past the cap and never "
+    "silently merges, so it stops here: this needs an operator decision.\n\n"
+    "{verdict_line}\n"
+    "{verification}"
+    "\n**Operator re-entry — grant N more rounds.** Comment with a line that "
+    "reads exactly:\n\n"
+    "```\n" + REENTRY_GRAMMAR + "\n```\n\n"
+    "…with `N` from 1 to {max_rounds}. It is honoured only from an allowlisted "
+    "operator account (the daemon's `operators` config), counted once per "
+    "comment — a further grant needs a further comment — logged, and appended "
+    "to the review-loop activity comment. Anything else is ignored: a quoted "
+    "line, another wording, a bigger N, any other author.\n\n"
+    "Without an ack no further round runs. The other options are unchanged: "
+    "merge with a recorded waiver, or park it."
+)
+
+# The last-verdict line. Two shapes, because one sha is not enough once the
+# head can have moved: the page has to say what was judged AND what is sitting
+# there now, or an operator reading "last verdict at <current head>" concludes
+# the verdict already covers the pushed fixes -- the exact opposite of what the
+# verification hint below is telling them.
+VERDICT_LINE = "Last verdict: `{last_state}` at `{sha}`."
+VERDICT_LINE_MOVED = (
+    "Last verdict: `{last_state}` on `{reviewed}` — the head is now `{sha}`."
+)
+
+# Only when the head has moved past the head the last verdict was written
+# against -- the PR #277 shape, where the fixes are already pushed and sitting
+# unreviewed. That case wants exactly one round, and saying so at the moment
+# the operator reads the page is the whole point of the lever being
+# discoverable.
+VERIFICATION_HINT = (
+    "\n**The head has moved since that verdict** (`{sha}`, reviewed at "
+    "`{reviewed}`) — fixes are already pushed and unreviewed, so one round is "
+    "usually all this needs: ack `alissa-review: re-enter +1` and the next "
+    "reviewer verifies the fix against its own final findings and flips to "
+    "approve (or re-requests, consuming the grant).\n"
+)
+
+# Named in the fresh escalation that fires once a grant has been spent without
+# an approve, so the page says which decision was already tried.
+GRANT_CONSUMED_NOTE = (
+    " The re-entry granted by @{author} (`+{rounds}`, comment {comment_id}) "
+    "has been consumed without an approve."
 )
 
 STALLED_COMMENT = (
@@ -172,6 +257,106 @@ def stalled_kind(session: str) -> str:
     return f"{ESCALATION_STALLED}:{session}"
 
 
+def capout_kind(head_sha: str, granted: int) -> str:
+    """The ping-ledger kind that dedupes ONE cap-out page.
+
+    `escalations` is keyed by head alone, which was the whole story while the
+    cap was global: same head, same decision, one page. A re-entry grant breaks
+    that -- rounds run on the operator's own authority and end without an
+    approve on the very SAME head, and that is a new decision, not a repeat of
+    the page the operator already answered. Folding the PR's granted total into
+    the kind says exactly that: one page per (head, grant total), so a consumed
+    grant pages once more and then goes quiet until the next ack. Deliberately
+    not a timestamp comparison against the escalation row -- ordering by
+    wall-clock seconds ties when two events land in the same second, and the
+    tie fails in the loud direction (a page every poll).
+    """
+    return f"capout:{head_sha}:{granted}"
+
+
+def _now() -> str:
+    """The activity comment's timestamp format (UTC, seconds)."""
+    return time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime())
+
+
+def grant_activity_kind(comment_id: int) -> str:
+    """The ping-ledger kind that dedupes ONE grant's activity line.
+
+    The grant itself is recorded the moment it is honoured (the effective cap
+    must not depend on a comment API call succeeding), but the activity line is
+    a separate best-effort append -- so the ledger row lands only AFTER the
+    append does, and a failed append is retried on the next poll instead of
+    losing the audit line the grant is supposed to leave.
+    """
+    return f"activity-grant:{comment_id}"
+
+
+@dataclass(frozen=True)
+class Ack:
+    """One comment read against the re-entry grammar.
+
+    Three outcomes, deliberately distinguishable: not a directive at all
+    (`rounds` and `problem` both None -- an ordinary comment, no log), a
+    directive that cannot be honoured (`problem` set -- ignored WITH a log
+    line, because a silent typo is indistinguishable from a cap that refuses
+    to lift), or a good ack (`rounds` set).
+    """
+
+    rounds: int | None = None
+    problem: str | None = None
+
+    @property
+    def is_directive(self) -> bool:
+        return self.rounds is not None or self.problem is not None
+
+
+def parse_reentry_ack(body: str) -> Ack:
+    """Parse a comment body for the operator re-entry directive.
+
+    The grammar is one whole line, `alissa-review: re-enter +N`, optionally
+    wrapped in backticks. Everything else about the comment is ignored, so an
+    operator may explain themselves above or below the line -- but the line
+    itself has to be exact, and a quoted (`>`) line never counts, which is what
+    stops a reply that quotes the escalation from re-granting it.
+
+    Two or more directives disagreeing in one comment is a refusal, not a
+    guess: "acks are counted, never inferred". Repeating the SAME `+N` is fine
+    (it is still one grant, and one comment is one grant however many times it
+    says so).
+    """
+    lead = False
+    found: set[int] = set()
+    for raw in (body or "").splitlines():
+        line = raw.strip()
+        if line.startswith(">"):  # a quoted escalation is not a directive
+            continue
+        if not _ACK_LEAD_RE.match(line):
+            continue
+        lead = True
+        match = _ACK_RE.match(line)
+        if match:
+            found.add(int(match.group(1)))
+
+    if not found:
+        if lead:
+            return Ack(
+                problem=f"malformed re-entry directive (expected `{REENTRY_GRAMMAR}`)"
+            )
+        return Ack()
+    if len(found) > 1:
+        return Ack(
+            problem="contradictory re-entry directives in one comment "
+            f"(+{', +'.join(str(n) for n in sorted(found))})"
+        )
+    rounds = found.pop()
+    if not 1 <= rounds <= MAX_REENTRY_ROUNDS:
+        return Ack(
+            problem=f"+{rounds} is outside the re-entry ceiling "
+            f"(+1 to +{MAX_REENTRY_ROUNDS})"
+        )
+    return Ack(rounds=rounds)
+
+
 class Action(str, Enum):
     SPAWNED = "spawned"
     IN_FLIGHT = "in-flight"
@@ -227,6 +412,9 @@ class ReviewWatcher:
         self.github = github or GitHub(config.reviewer_login)
         self.alissa = alissa or Alissa()
         self.state = state or State(config.state_db)
+        # (repo, number, comment id) of every re-entry directive already
+        # refused in this process -- see _log_ignored_ack.
+        self._ignored_acks: set[tuple[str, int, int]] = set()
 
     # -- per-PR decision ---------------------------------------------------
 
@@ -267,11 +455,26 @@ class ReviewWatcher:
         if converged is not None:
             return Decision(Action.CONVERGED, converged, completed)
 
-        # CR9: never queue round cap+1.
-        if completed >= self.config.round_cap:
-            if self.state.escalated(pr.full_name, number, pr.head_sha):
+        # The effective cap is the configured one plus every re-entry an
+        # operator has explicitly acked on THIS PR (issue #42). The sum is a
+        # local read, so it costs nothing on the common path; the GitHub scan
+        # that can DISCOVER a new ack runs only when the loop would otherwise
+        # be capped -- exactly the state an ack exists to unstick, and the only
+        # one where an extra comments fetch per poll is worth paying for.
+        granted = self.state.granted_rounds(pr.full_name, number)
+        if completed >= self.config.round_cap + granted:
+            granted = self._collect_acks(pr, granted)
+            self._announce_grants(pr)
+        cap = self.config.round_cap + granted
+
+        # CR9: never queue round cap+1 -- where "cap" is now the effective one.
+        # No ack, no rounds: with no grant this is byte-for-byte the old
+        # behaviour.
+        if completed >= cap:
+            if not self._escalation_owed(pr, granted):
                 return Decision(Action.CAPPED, "already escalated", completed)
-            self._escalate(pr, my_reviews[-1].state if my_reviews else "none", completed)
+            grant = self.state.newest_grant(pr.full_name, number)
+            self._escalate(pr, my_reviews, completed, cap, grant)
             return Decision(Action.ESCALATED, f"{completed} rounds, no approve", completed)
 
         round_ = completed + 1
@@ -280,7 +483,7 @@ class ReviewWatcher:
         if age is not None and age < STALE_ROUND_SECONDS:
             return Decision(Action.IN_FLIGHT, f"round {round_} enqueued {int(age)}s ago", round_)
         if age is not None:
-            deferred = self._defer_stale_round(pr, round_, age)
+            deferred = self._defer_stale_round(pr, round_, age, cap)
             if deferred is not None:
                 return deferred
             log.warning(
@@ -292,9 +495,188 @@ class ReviewWatcher:
                 age / 60,
             )
 
-        return self._spawn(pr, round_, task, reenqueued=age is not None)
+        return self._spawn(pr, round_, task, cap, reenqueued=age is not None)
+
+    # -- operator re-entry -------------------------------------------------
+
+    def _is_operator(self, author: str) -> bool:
+        """Whether an ack from this author may be honoured.
+
+        Allowlist membership, case-insensitively (GitHub logins are), minus the
+        reviewer identity itself: the daemon's own escalation comment carries
+        the grammar, so an identity that could ack its own page would be able
+        to lift CR9's cap without a human ever touching it.
+
+        The PR author is deliberately NOT excluded the same way. Refusing them
+        outright would block the ordinary case -- an operator who opened the PR
+        by hand -- and the protection that matters is structural rather than
+        per-identity: the allowlist is opt-in and empty by default, so putting
+        an AGENT identity on it (an implementer that can comment on its own PR
+        and has read the escalation) is an operator's deliberate choice, not
+        something the daemon does for them. The reviewer identity is different
+        in kind because it is not opt-in at all.
+        """
+        if not author or author.lower() == (self.github.login or "").lower():
+            return False
+        return author.lower() in {o.lower() for o in self.config.operators}
+
+    def _collect_acks(self, pr: PullRequest, granted: int) -> int:
+        """Scan the capped PR's comments for operator acks; record new grants.
+
+        Returns the PR's total granted rounds. Every honoured ack is recorded
+        under its comment id, so the same comment can never grant twice however
+        many polls read it, and the log/announce side effects fire once.
+
+        With no operator allowlist -- the default, and what the container bakes
+        on purpose -- NO ack can ever be honoured, so the scan does not run at
+        all: a capped PR keeps its review request pending and therefore stays
+        in the search result set indefinitely, which would make this a full
+        comment-thread fetch (up to COMMENT_PAGE_LIMIT paged requests, on
+        exactly the long threads paging exists for) every poll, forever, to
+        discard everything it found. The fail-closed default stays free.
+
+        Comment reads are best-effort: an unreadable comment list leaves the PR
+        capped for this pass (the conservative direction -- it can only ever
+        withhold rounds, never invent them) and the scan retries next poll.
+        """
+        if not self.config.operators:
+            return granted
+
+        try:
+            comments = self.github.issue_comments(pr.owner, pr.repo, pr.number)
+        except RateLimited:
+            # Not swallowed: run_forever's backoff is the whole response to a
+            # rate limit, and eating it here would keep the pass hammering.
+            raise
+        except Exception as exc:
+            log.warning(
+                "%s is at its cap but its comments are unreadable (%s) — no "
+                "re-entry ack can be honoured this pass; retrying next poll",
+                pr.slug,
+                exc,
+            )
+            return granted
+
+        for comment in comments:
+            # Our own comments are never directives -- the escalation itself
+            # quotes the grammar.
+            if comment.author == self.github.login:
+                continue
+            ack = parse_reentry_ack(comment.body)
+            if not ack.is_directive:
+                continue
+            if not self._is_operator(comment.author):
+                self._log_ignored_ack(
+                    pr, comment, f"{comment.author} is not an allowlisted operator"
+                )
+                continue
+            if ack.rounds is None:
+                self._log_ignored_ack(pr, comment, ack.problem or "malformed directive")
+                continue
+            if self.config.dry_run:
+                log.info(
+                    "[dry-run] would honour re-entry ack +%d from %s on %s "
+                    "(comment %d)",
+                    ack.rounds, comment.author, pr.slug, comment.id,
+                )
+                granted += ack.rounds
+                continue
+            if not self.state.record_grant(
+                pr.full_name, pr.number, comment.id, comment.author, ack.rounds
+            ):
+                continue  # already counted in `granted`
+            granted += ack.rounds
+            log.warning(
+                "RE-ENTRY GRANT %s — operator %s acked +%d round(s) in comment "
+                "%d; effective cap %d → %d",
+                pr.slug,
+                comment.author,
+                ack.rounds,
+                comment.id,
+                self.config.round_cap + granted - ack.rounds,
+                self.config.round_cap + granted,
+            )
+        return granted
 
-    def _defer_stale_round(self, pr: PullRequest, round_: int, age: float) -> Decision | None:
+    def _log_ignored_ack(
+        self, pr: PullRequest, comment: IssueComment, why: str
+    ) -> None:
+        """Report an ack that will not be honoured — once per comment.
+
+        A capped PR is re-scanned every poll, so an unconditional warning would
+        repeat a line a minute for as long as the PR stays capped. The comment
+        id is the identity of the thing being refused, and an in-memory set is
+        the right scope for it: this is a log line, not a delivery guarantee,
+        so a daemon restart re-stating the refusal once is fine (and a ledger
+        row per typo is not).
+        """
+        key = (pr.full_name, pr.number, comment.id)
+        if key in self._ignored_acks:
+            return
+        self._ignored_acks.add(key)
+        log.warning(
+            "ignoring re-entry directive on %s (comment %d by %s): %s — the PR "
+            "stays capped",
+            pr.slug,
+            comment.id,
+            comment.author,
+            why,
+        )
+
+    def _announce_grants(self, pr: PullRequest) -> None:
+        """Append the activity line of every grant that has not had one yet.
+
+        Separate from recording the grant on purpose: the cap change is
+        authoritative state and must not hinge on a comment API call, while the
+        audit line must survive one failing -- so it is retried here on later
+        polls until it lands (see grant_activity_kind).
+
+        Walked OLDEST first (read_grants is newest-first, like its siblings)
+        with a running total, so each line reports its OWN transition rather
+        than the PR's total: two acks read in one pass -- or, more commonly, a
+        retried append landing beside a newer grant, which is the whole reason
+        this retries -- would otherwise both claim the same before/after cap
+        and go out in reverse order into an append-only log.
+        """
+        running = self.config.round_cap
+        for row in reversed(self.state.read_grants(pr.full_name, pr.number)):
+            before, running = running, running + row["rounds"]
+            kind = grant_activity_kind(row["comment_id"])
+            if self.state.pinged(pr.full_name, pr.number, kind):
+                continue
+            line = (
+                f"- {_now()} — operator `{row['author']}` — re-entry ack "
+                f"(comment {row['comment_id']}) — +{row['rounds']} round(s) — "
+                f"effective cap {before} → {running}"
+            )
+            if self._append_activity(pr, line):
+                self.state.record_ping(pr.full_name, pr.number, kind)
+
+    def _escalation_owed(self, pr: PullRequest, granted: int) -> bool:
+        """Whether a cap-out page is owed, or already delivered.
+
+        Two ways a page is owed: this head has never been paged (a fresh
+        cap-out, or the implementer pushed since -- the decision is about the
+        new state), or rounds granted by an operator ack have since been
+        consumed without an approve, which is a new decision on an unmoved head
+        (capout_kind). Everything else is the same page the operator already
+        has, and CR9's escalation stays once-only.
+
+        A PR with no grant takes the first branch alone, so the pre-#42
+        behaviour -- and any state.db written by it -- is untouched: no
+        already-escalated PR re-pages just because the daemon was upgraded.
+        """
+        if not self.state.escalated(pr.full_name, pr.number, pr.head_sha):
+            return True
+        if granted == 0:
+            return False
+        return not self.state.pinged(
+            pr.full_name, pr.number, capout_kind(pr.head_sha, granted)
+        )
+
+    def _defer_stale_round(
+        self, pr: PullRequest, round_: int, age: float, cap: int
+    ) -> Decision | None:
         """The liveness signal under the stale timer: a deferral, or None to
         respawn.
 
@@ -358,7 +740,7 @@ class ReviewWatcher:
             appended = self._append_activity(
                 pr,
                 self._activity_line(
-                    session, round_, f"deferred — session `{session}` still {life}"
+                    session, round_, f"deferred — session `{session}` still {life}", cap
                 ),
             )
             if appended:
@@ -562,7 +944,13 @@ class ReviewWatcher:
     # -- actions -----------------------------------------------------------
 
     def _spawn(
-        self, pr: PullRequest, round_: int, task: Task | None, *, reenqueued: bool = False
+        self,
+        pr: PullRequest,
+        round_: int,
+        task: Task | None,
+        cap: int,
+        *,
+        reenqueued: bool = False,
     ) -> Decision:
         if task is None:
             if self.config.on_missing_review_task == ON_MISSING_SKIP:
@@ -585,7 +973,7 @@ class ReviewWatcher:
         name = session_name(pr, round_)
         template = ROUND_1_DIRECTIVE if round_ == 1 else ROUND_K_DIRECTIVE
         directive = template.format(
-            assignment=assignment, round=round_, cap=self.config.round_cap, session=name
+            assignment=assignment, round=round_, cap=cap, session=name
         )
 
         hub, problem = self._ensure_hub(pr)
@@ -616,7 +1004,7 @@ class ReviewWatcher:
         context = (
             "re-enqueued — previous session presumed dead" if reenqueued else "spawned"
         )
-        self._append_activity(pr, self._activity_line(name, round_, context))
+        self._append_activity(pr, self._activity_line(name, round_, context, cap))
 
         return Decision(
             Action.SPAWNED,
@@ -699,9 +1087,11 @@ class ReviewWatcher:
 
         return warnings
 
-    def _activity_line(self, session: str, round_: int, context: str) -> str:
-        ts = time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime())
-        return f"- {ts} — `{session}` — round {round_} of {self.config.round_cap} — {context}"
+    def _activity_line(self, session: str, round_: int, context: str, cap: int) -> str:
+        """One mechanical line. `cap` is the PR's EFFECTIVE cap (config plus
+        granted re-entries) -- printing the config value would render a granted
+        round 11 as "round 11 of 10"."""
+        return f"- {_now()} — `{session}` — round {round_} of {cap} — {context}"
 
     def _append_activity(self, pr: PullRequest, line: str) -> bool:
         """Append one line to THE activity comment on the PR; True if it landed.
@@ -784,11 +1174,57 @@ class ReviewWatcher:
             return
         self.state.record_ping(pr.full_name, pr.number, stalled_kind(session))
 
-    def _escalate(self, pr: PullRequest, last_state: str, rounds: int) -> None:
+    def _escalate(
+        self,
+        pr: PullRequest,
+        my_reviews: list[Review],
+        rounds: int,
+        cap: int,
+        grant: sqlite3.Row | None = None,
+    ) -> None:
+        """Page the operator, and teach the lever that gets past the page.
+
+        The message carries the re-entry grammar because the cap-out is exactly
+        the moment an operator needs it, and -- when the head has moved past
+        the head the last verdict was written against -- the recommendation to
+        grant a single verification round. A `grant` names the re-entry that
+        was already spent, so a second page cannot read as a repeat of the
+        first.
+        """
+        last = my_reviews[-1] if my_reviews else None
+        last_state = (last.state if last else "none").lower()
+        reviewed = (last.commit_id if last else "") or ""
+        moved = bool(reviewed) and reviewed != pr.head_sha
+        verification = ""
+        if moved:
+            verification = VERIFICATION_HINT.format(
+                sha=pr.head_sha[:8], reviewed=reviewed[:8]
+            )
+        template = VERDICT_LINE_MOVED if moved else VERDICT_LINE
+        verdict_line = template.format(
+            last_state=last_state, sha=pr.head_sha[:8], reviewed=reviewed[:8]
+        )
+        grant_note = ""
+        if grant is not None:
+            grant_note = GRANT_CONSUMED_NOTE.format(
+                author=grant["author"],
+                rounds=grant["rounds"],
+                comment_id=grant["comment_id"],
+            )
         body = ESCALATION_COMMENT.format(
-            rounds=rounds, last_state=last_state.lower(), sha=pr.head_sha[:8]
+            rounds=rounds,
+            cap=cap,
+            grant_note=grant_note,
+            verdict_line=verdict_line,
+            verification=verification,
+            max_rounds=MAX_REENTRY_ROUNDS,
+        )
+        log.error(
+            "CAP-OUT %s after %d rounds (effective cap %d) — escalating to operator",
+            pr.slug,
+            rounds,
+            cap,
         )
-        log.error("CAP-OUT %s after %d rounds — escalating to operator", pr.slug, rounds)
 
         if self.config.dry_run:
             log.info("[dry-run] would comment on %s:\n%s", pr.slug, body)
@@ -798,7 +1234,14 @@ class ReviewWatcher:
             self.github.comment(pr.owner, pr.repo, pr.number, body)
         except CommandError as exc:
             log.error("could not post escalation comment on %s: %s", pr.slug, exc)
+        # Recorded even when the comment failed: a cap-out is terminal state,
+        # and re-paging it every poll because GitHub was briefly unavailable
+        # would be worse than the one missed comment (the log line above and
+        # the escalations row both survive it).
         self.state.record_escalation(pr.full_name, pr.number, pr.head_sha)
+        self.state.record_ping(
+            pr.full_name, pr.number, capout_kind(pr.head_sha, cap - self.config.round_cap)
+        )
 
     # -- polling -----------------------------------------------------------
 

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/src/main/alissa/tools/github/revloop/state.py

@@ -4,8 +4,9 @@ Deliberately thin: GitHub is the source of truth for how many rounds have run
 (one submitted review per round). This table exists only to stop the daemon
 double-spawning a reviewer while a round is still in flight, to map a live
 session name back to the round it was spawned for (so the reap sweep can tell
-a finished round's session from an in-flight one), and to remember that a
-cap-out was already escalated. The ledger tolerates sessions dying or being
+a finished round's session from an in-flight one), to remember that a cap-out
+was already escalated, and to count the operator re-entry acks that raise a
+single PR's effective cap. The ledger tolerates sessions dying or being
 killed behind its back: a reap record is bookkeeping, never a precondition.
 
 The `poll_snapshots` table is a different animal from the ledger above: it
@@ -67,6 +68,16 @@ CREATE TABLE IF NOT EXISTS reaps (
     reaped_at INTEGER NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS grants (
+    repo       TEXT    NOT NULL,
+    number     INTEGER NOT NULL,
+    comment_id INTEGER NOT NULL,
+    author     TEXT    NOT NULL,
+    rounds     INTEGER NOT NULL,
+    granted_at INTEGER NOT NULL,
+    PRIMARY KEY (repo, number, comment_id)
+);
+
 CREATE TABLE IF NOT EXISTS pings (
     repo      TEXT    NOT NULL,
     number    INTEGER NOT NULL,
@@ -269,6 +280,10 @@ class State:
         self._db.commit()
 
     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
+        new decision on the SAME head, deduped through the ping ledger; see
+        loop._escalation_owed."""
         row = self._db.execute(
             "SELECT 1 FROM escalations WHERE repo=? AND number=? AND head_sha=?",
             (repo, number, head_sha),
@@ -283,6 +298,76 @@ class State:
         )
         self._db.commit()
 
+    # -- operator re-entry grants ------------------------------------------
+    #
+    # One row per HONOURED operator ack comment (issue #42): a capped PR is
+    # re-entered only by an explicit, allowlisted, bounded ack, and this table
+    # is what makes the grant *counted* rather than inferred. The comment id is
+    # the grant's identity, so the same ack is honoured exactly once however
+    # many polls read it, and a second grant genuinely requires a second
+    # comment. Rows are never pruned: the effective cap of a PR is
+    # `round_cap + sum(rounds)` over its grants, so dropping one would silently
+    # lower the cap and re-escalate a PR that was already re-entered.
+
+    def record_grant(
+        self, repo: str, number: int, comment_id: int, author: str, rounds: int
+    ) -> bool:
+        """Record one honoured ack. True when it is NEW (first sighting).
+
+        INSERT OR IGNORE keyed on the comment id: re-reading the same ack on
+        every poll must not re-grant its rounds, and the caller uses the return
+        value to log/announce the grant exactly once.
+        """
+        cur = self._db.execute(
+            "INSERT OR IGNORE INTO grants "
+            "(repo, number, comment_id, author, rounds, granted_at) "
+            "VALUES (?,?,?,?,?,?)",
+            (repo, number, int(comment_id), author, int(rounds), int(time.time())),
+        )
+        self._db.commit()
+        return cur.rowcount > 0
+
+    def granted_rounds(self, repo: str, number: int) -> int:
+        """Extra rounds this PR has been granted, summed over its acks."""
+        row = self._db.execute(
+            "SELECT COALESCE(SUM(rounds), 0) AS total FROM grants "
+            "WHERE repo=? AND number=?",
+            (repo, number),
+        ).fetchone()
+        return int(row["total"]) if row is not None else 0
+
+    def newest_grant(self, repo: str, number: int) -> sqlite3.Row | None:
+        """The most recently recorded ack for this PR, or None.
+
+        The escalation names it ("the re-entry granted by @x was consumed"),
+        and it is the newest ack by `granted_at`, so a second grant supersedes
+        the first in the page's wording. Nothing compares that timestamp with
+        the escalation row -- the once-only dedupe is the ping-ledger key; see
+        loop.capout_kind for why not a wall-clock comparison.
+        """
+        return self._db.execute(
+            "SELECT * FROM grants WHERE repo=? AND number=? "
+            "ORDER BY granted_at DESC, rowid DESC LIMIT 1",
+            (repo, number),
+        ).fetchone()
+
+    def read_grants(self, repo: str, number: int) -> list[dict]:
+        """One PR's grant rows, newest first (like every reader here).
+
+        Deliberately narrow: no unfiltered form and no `limit` until something
+        needs them. The console does not read this table yet -- showing "this
+        PR was re-entered by @x" in the operator inbox wants rendering as well
+        as data, so it lands as its own change rather than as unused
+        parameters here.
+        """
+        return self._read_rows(
+            "SELECT repo, number, comment_id, author, rounds, granted_at "
+            "FROM grants WHERE repo=? AND number=? "
+            "ORDER BY granted_at DESC, rowid DESC",
+            None,
+            (repo, number),
+        )
+
     # -- poll snapshots (the console sidecar's exhaust buffer) -------------
 
     def record_snapshot(

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

@@ -0,0 +1 @@
+0.16.1

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/src/main/alissa/tools/github/revloop/webui/sources.py

@@ -414,6 +414,10 @@ class Sources:
         return {
             "workspace_root": str(c.workspace_root),
             "repos": list(c.repos),
+            # Who may re-open a capped PR with a re-entry ack. Part of the
+            # operator's own picture: the escalation inbox below is where that
+            # lever gets used.
+            "operators": list(c.operators),
             "hub_template": c.hub_template,
             "poll_interval": c.poll_interval,
             "round_cap": c.round_cap,

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

@@ -1,17 +1,22 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.15.0
+Version: 0.16.1
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera
 Author-email: support@alissa.app
+License: Apache-2.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
 Dynamic: author
 Dynamic: author-email
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
 Dynamic: requires-python
 Dynamic: summary
 
@@ -59,3 +64,11 @@ pip install -e ./alissa-tools-github-revloop
 distribution version lives in the plain-text `version` file next to the module
 it versions (`src/main/alissa/tools/github/revloop/version`), read by both
 `setup.py` and `version.py`.
+
+## License
+
+Licensed under the Apache License 2.0 — see the `LICENSE` and `NOTICE` files
+shipped with this distribution.
+
+"Alissa" and "Fahera" are trademarks of CORE FAHERA ENTERPRISE HOLDINGS S. DE
+R.L.; the license does not grant permission to use them.

{alissa_tools_github_revloop-0.15.0 → alissa_tools_github_revloop-0.16.1}/src/main/alissa_tools_github_revloop.egg-info/SOURCES.txt

@@ -1,4 +1,6 @@
+LICENSE
 MANIFEST.in
+NOTICE
 README.md
 requirements.txt
 setup.py

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

@@ -1 +0,0 @@
-0.15.0