alissa-tools-github-revloop 0.14.0__tar.gz → 0.16.0__tar.gz

{alissa_tools_github_revloop-0.14.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.16.0}/PKG-INFO

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

{alissa_tools_github_revloop-0.14.0 → alissa_tools_github_revloop-0.16.0}/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.14.0 → alissa_tools_github_revloop-0.16.0}/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.14.0 → alissa_tools_github_revloop-0.16.0}/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.14.0 → alissa_tools_github_revloop-0.16.0}/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.14.0 → alissa_tools_github_revloop-0.16.0}/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.0/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.16.0

{alissa_tools_github_revloop-0.14.0 → alissa_tools_github_revloop-0.16.0}/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.14.0 → alissa_tools_github_revloop-0.16.0/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

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

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

@@ -1 +0,0 @@
-0.14.0