alissa-tools-github-reviewloop 0.8.0__tar.gz → 0.10.0__tar.gz

{alissa_tools_github_reviewloop-0.8.0/src/main/alissa_tools_github_reviewloop.egg-info → alissa_tools_github_reviewloop-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-reviewloop
-Version: 0.8.0
+Version: 0.10.0
 Summary: ALISSA-TOOLS-GITHUB-REVIEWLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_reviewloop-0.8.0 → alissa_tools_github_reviewloop-0.10.0}/src/main/alissa/tools/github/reviewloop/ghclient.py

@@ -46,6 +46,17 @@ class PullRequest:
         return self.merged or self.state != "open"
 
 
+@dataclass(frozen=True)
+class IssueComment:
+    """An issue comment on a PR (a PR is an issue). Distinct from Review:
+    issue comments live on the issues endpoints and never create review
+    records, so posting one can never disturb round counting."""
+
+    id: int
+    author: str
+    body: str
+
+
 @dataclass(frozen=True)
 class Review:
     author: str
@@ -221,3 +232,32 @@ class GitHub:
                 f"body={body}",
             ]
         )
+
+    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",
+            )
+            or []
+        )
+        return [
+            IssueComment(
+                id=int(c.get("id") or 0),
+                author=(c.get("user") or {}).get("login", ""),
+                body=c.get("body") or "",
+            )
+            for c in data
+        ]
+
+    def update_comment(self, owner: str, repo: str, comment_id: int, body: str) -> None:
+        self._api(
+            "-X",
+            "PATCH",
+            f"repos/{owner}/{repo}/issues/comments/{comment_id}",
+            "-f",
+            f"body={body}",
+        )

{alissa_tools_github_reviewloop-0.8.0 → alissa_tools_github_reviewloop-0.10.0}/src/main/alissa/tools/github/reviewloop/loop.py

@@ -27,9 +27,25 @@ from .state import State
 log = logging.getLogger(__name__)
 
 # A reviewer session that has not submitted after this long is presumed dead
-# (skill failure mode: "reviewer session stalls"). The round is re-enqueued.
+# (skill failure mode: "reviewer session stalls"). The round is re-enqueued --
+# but only with a second signal agreeing: the timer alone cannot tell a dead
+# session from a slow one, and a timer-only re-enqueue double-spends the round
+# (two sessions review it, both submit -- observed live twice: double round-2
+# approves on devloop's PR #11, double approves on this repo's PR #19). See
+# _defer_stale_round for the liveness signal.
 STALE_ROUND_SECONDS = 90 * 60
 
+# The floor under the liveness deferral: a live session defers the stale
+# respawn indefinitely -- correct for a genuinely slow round, silent forever
+# for a session that is wedged but still registers tmux activity. Once the
+# newest spawn's age reaches this multiple of STALE_ROUND_SECONDS, the loop
+# posts one "stalled" operator comment per deferral episode (stalled_kind)
+# and keeps deferring. 2 means the deferral itself has lasted a full extra
+# stale window beyond the point the timer first fired -- long enough that a
+# healthy round has almost always submitted by then, early enough that a
+# wedged one surfaces the same day.
+STALLED_DEFER_MULTIPLE = 2
+
 # The sweep only reaps a session that has been idle AND quiet this long. The
 # GitHub review count increments the moment a review is submitted, but the
 # reviewer still has close-out work after that (CR6 envelope, task status) --
@@ -96,6 +112,64 @@ ESCALATION_COMMENT = (
     "Last verdict: `{last_state}` at `{sha}`."
 )
 
+STALLED_COMMENT = (
+    "**Review round stalled?** — round {round} has been in flight {minutes} min "
+    "(stale window: {stale} min), but its reviewer session `{session}` still "
+    "shows signs of life, so the daemon keeps deferring the respawn — "
+    "respawning over a live session double-spends the round: two reviewers "
+    "work it, both submit. Is that session actually making progress? Operator "
+    "options: inspect it (`alissa tmux ls`) and, if it is wedged, kill it "
+    "(`alissa tmux kill {session}`) so the respawn proceeds next poll, or "
+    "finish the round by hand."
+)
+
+# The hidden marker that identifies THE activity comment on a PR. Find-or-create
+# keys on it (plus own authorship -- anyone can paste the marker into their own
+# comment, and a spoofed marker must never be PATCHed), so every append lands in
+# the same single comment however many rounds run.
+ACTIVITY_MARKER = "<!-- alissa-reviewloop:activity -->"
+
+ACTIVITY_HEADER = (
+    ACTIVITY_MARKER + "\n"
+    "**Review-loop activity** — mechanical spawn/round log; the daemon appends "
+    "a line each time it queues (or defers) a reviewer round on this PR."
+)
+
+# The ping-ledger kind prefix for the stalled-deferral operator ping. Unlike
+# the cap-out escalation (terminal per head), a stall can recur, so the kind
+# is narrowed per episode -- see stalled_kind.
+ESCALATION_STALLED = "stalled"
+
+
+def deferral_activity_kind(session: str) -> str:
+    """The ping-ledger kind that dedupes ONE deferral episode's activity line.
+
+    A deferral is re-decided every poll, so appending per decision would grow
+    the activity comment by one identical line a minute for as long as the
+    session holds out. One line per episode carries the same information --
+    "the daemon is deferring behind this session" -- and the session name is
+    the episode identity (nonce-unique per spawn), exactly as stalled_kind
+    reasons for the operator ping. Recorded only after the append lands, so a
+    transient failure retries next poll.
+    """
+    return f"activity-deferred:{session}"
+
+
+def stalled_kind(session: str) -> str:
+    """The ping-ledger kind that dedupes ONE deferral episode's operator ping.
+
+    Devloop's stalled_kind reasoning, transposed: a stall can recur -- every
+    spawn of every round can wedge mid-flight, and episode k's ping must not
+    silence episode k+1's. Keyed on the bare kind (or even on the round), the
+    re-enqueue of a round that wedges AGAIN would defer silently forever. The
+    session name already IS the episode identity -- nonce-unique per spawn
+    (see session_name) -- so it folds into the key. Delivery contract: the
+    ledger row lands only AFTER the comment posts (see _escalate_stalled), so
+    a transient comment failure retries next poll and the ping lands exactly
+    once per episode.
+    """
+    return f"{ESCALATION_STALLED}:{session}"
+
 
 class Action(str, Enum):
     SPAWNED = "spawned"
@@ -192,15 +266,97 @@ 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)
+            if deferred is not None:
+                return deferred
             log.warning(
                 "%s round %d has been in flight %.0f min with no submitted review "
-                "— re-enqueuing (reviewer session presumed stalled)",
+                "and its session is gone or finished — re-enqueuing (reviewer "
+                "session presumed dead)",
                 pr.slug,
                 round_,
                 age / 60,
             )
 
-        return self._spawn(pr, round_, task)
+        return self._spawn(pr, round_, task, reenqueued=age is not None)
+
+    def _defer_stale_round(self, pr: PullRequest, round_: int, age: float) -> Decision | None:
+        """The liveness signal under the stale timer: a deferral, or None to
+        respawn.
+
+        Staleness needs TWO signals, not one: the ledger timer says the
+        newest spawn is old, but elapsed time alone cannot tell a dead
+        session from a slow one -- a thorough round can outlast
+        STALE_ROUND_SECONDS, and a timer-only re-enqueue respawns a reviewer
+        over the still-working first one; two sessions review the same
+        round and both submit. So before respawning, consult external
+        evidence of life: the round's recorded session in the live list
+        (the reap sweep's own probe). Busy, or idle without a real quiet
+        period (mid-close-out between turns; see REAP_QUIET_SECONDS) -> the
+        round is alive, defer with a reason. Gone, or idle-finished -> dead,
+        respawn (the sweep separately handles any corpse). An unprobeable
+        live list defers too: respawning on missing evidence is exactly the
+        double-spend, and the probe retries next poll.
+
+        The deferral is floored, not unbounded: past STALLED_DEFER_MULTIPLE
+        stale windows with the session still alive, one operator ping per
+        deferral episode (stalled_kind) -- then keep deferring. This method
+        never respawns over a live session; only the operator killing the
+        session (or it finishing/dying) unblocks the respawn.
+        """
+        row = self.state.get_spawn(pr.full_name, pr.number, round_)
+        if row is None:  # age came from this row; belt and braces
+            return None
+        session = row["session"]
+        try:
+            live = {s.name: s for s in self.alissa.list_review_sessions()}
+        except CommandError as exc:
+            log.warning(
+                "%s round %d is stale but the session list is unavailable (%s) "
+                "— deferring the respawn rather than risking a double-spawned "
+                "round; the probe retries next poll",
+                pr.slug,
+                round_,
+                exc,
+            )
+            return Decision(
+                Action.IN_FLIGHT,
+                f"round {round_} is stale but liveness is unprobeable — deferring",
+                round_,
+            )
+
+        ses = live.get(session)
+        if ses is None:
+            return None  # session gone -> presumed dead -> respawn
+        if ses.is_idle and time.time() - ses.last_activity >= REAP_QUIET_SECONDS:
+            return None  # idle-finished: it died without submitting -> respawn
+
+        if (
+            age >= STALLED_DEFER_MULTIPLE * STALE_ROUND_SECONDS
+            and not self.state.pinged(pr.full_name, pr.number, stalled_kind(session))
+        ):
+            self._escalate_stalled(pr, round_, session, age)
+
+        life = "active" if ses.is_idle else "busy"
+        if not self.state.pinged(pr.full_name, pr.number, deferral_activity_kind(session)):
+            appended = self._append_activity(
+                pr,
+                self._activity_line(
+                    session, round_, f"deferred — session `{session}` still {life}"
+                ),
+            )
+            if appended:
+                self.state.record_ping(
+                    pr.full_name, pr.number, deferral_activity_kind(session)
+                )
+
+        return Decision(
+            Action.IN_FLIGHT,
+            f"round {round_} is stale ({int(age / 60)} min) but session "
+            f"{session} is still {life} — not "
+            f"respawning over a live reviewer",
+            round_,
+        )
 
     def _convergence_reason(
         self, my_reviews: list[Review], task: Task | None, head_sha: str
@@ -379,7 +535,9 @@ class ReviewWatcher:
 
     # -- actions -----------------------------------------------------------
 
-    def _spawn(self, pr: PullRequest, round_: int, task: Task | None) -> Decision:
+    def _spawn(
+        self, pr: PullRequest, round_: int, task: Task | None, *, reenqueued: bool = False
+    ) -> Decision:
         if task is None:
             if self.config.on_missing_review_task == ON_MISSING_SKIP:
                 return Decision(
@@ -427,6 +585,13 @@ class ReviewWatcher:
                 task_ref=task.ref if task else None,
             )
 
+        # AFTER the enqueue on purpose: the activity comment is telemetry and
+        # must never gate the spawn it reports on.
+        context = (
+            "re-enqueued — previous session presumed dead" if reenqueued else "spawned"
+        )
+        self._append_activity(pr, self._activity_line(name, round_, context))
+
         return Decision(
             Action.SPAWNED,
             f"session {name} → {task.ref if task else 'no task'}",
@@ -505,6 +670,91 @@ 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 _append_activity(self, pr: PullRequest, line: str) -> bool:
+        """Append one line to THE activity comment on the PR; True if it landed.
+
+        Find-or-create: the PR's issue comments are filtered to OWN authorship
+        AND the hidden marker, and the line is PATCH-appended to the first
+        match; with no match, one marker-carrying comment is created. A marker
+        pasted by anyone else fails the author filter and is never touched.
+
+        Best-effort by contract: this is telemetry about a spawn that has
+        already happened, so no failure here may surface to the caller. The
+        except is deliberately broad -- _api turns rate-limit errors into
+        RateLimited (not CommandError), and letting that fly out of evaluate()
+        would fail the whole poll pass over a log line.
+        """
+        if self.config.dry_run:
+            log.info("[dry-run] would append activity line on %s: %s", pr.slug, line)
+            return False
+        try:
+            mine = [
+                c
+                for c in self.github.issue_comments(pr.owner, pr.repo, pr.number)
+                if c.author == self.github.login and ACTIVITY_MARKER in c.body
+            ]
+            if mine:
+                self.github.update_comment(
+                    pr.owner, pr.repo, mine[0].id, mine[0].body + "\n" + line
+                )
+            else:
+                self.github.comment(
+                    pr.owner, pr.repo, pr.number, ACTIVITY_HEADER + "\n" + line
+                )
+        except Exception as exc:
+            log.warning("could not append activity line on %s: %s", pr.slug, exc)
+            return False
+        return True
+
+    def _escalate_stalled(
+        self, pr: PullRequest, round_: int, session: str, age: float
+    ) -> None:
+        """Operator ping when the liveness deferral itself runs long: the
+        session showing life is the only thing holding the respawn back, so
+        a human must check whether it is progressing or wedged. Posted once
+        per deferral EPISODE (the ping ledger row is keyed
+        stalled_kind(session); a re-enqueued round that stalls again is a
+        new session, so it pings again), and the row is recorded only AFTER
+        the comment posts: this ping is the operator's only signal for the
+        episode, so a transient comment failure must retry next poll --
+        exactly-once delivered, unlike the cap-out page (a terminal state,
+        recorded despite failure). The decision stays a deferral either way
+        -- this comments, it never respawns."""
+        body = STALLED_COMMENT.format(
+            round=round_,
+            minutes=int(age / 60),
+            stale=STALE_ROUND_SECONDS // 60,
+            session=session,
+        )
+        log.warning(
+            "STALLED %s round %d has been deferred %.0f min behind live session "
+            "%s — escalating to operator (once per episode)",
+            pr.slug,
+            round_,
+            age / 60,
+            session,
+        )
+
+        if self.config.dry_run:
+            log.info("[dry-run] would comment on %s:\n%s", pr.slug, body)
+            return
+
+        try:
+            self.github.comment(pr.owner, pr.repo, pr.number, body)
+        except CommandError as exc:
+            log.error(
+                "could not post the stalled-round comment on %s: %s — not "
+                "recording the episode; the ping retries next poll",
+                pr.slug,
+                exc,
+            )
+            return
+        self.state.record_ping(pr.full_name, pr.number, stalled_kind(session))
+
     def _escalate(self, pr: PullRequest, last_state: str, rounds: int) -> None:
         body = ESCALATION_COMMENT.format(
             rounds=rounds, last_state=last_state.lower(), sha=pr.head_sha[:8]

{alissa_tools_github_reviewloop-0.8.0 → alissa_tools_github_reviewloop-0.10.0}/src/main/alissa/tools/github/reviewloop/state.py

@@ -44,6 +44,14 @@ CREATE TABLE IF NOT EXISTS reaps (
     session   TEXT    NOT NULL PRIMARY KEY,
     reaped_at INTEGER NOT NULL
 );
+
+CREATE TABLE IF NOT EXISTS pings (
+    repo      TEXT    NOT NULL,
+    number    INTEGER NOT NULL,
+    kind      TEXT    NOT NULL,
+    pinged_at INTEGER NOT NULL,
+    PRIMARY KEY (repo, number, kind)
+);
 """
 
 
@@ -168,6 +176,32 @@ class State:
         )
         self._db.commit()
 
+    def pinged(self, repo: str, number: int, kind: str) -> bool:
+        """Whether this KIND of operator ping already went out for the PR.
+
+        Kind is free-form TEXT (devloop's escalation-kind pattern): a caller
+        narrows a kind's dedupe scope by folding identity into the string --
+        e.g. one stalled ping per deferral episode, "stalled:<session>" (see
+        loop.stalled_kind). Kept apart from `escalations`, whose key is
+        (repo, number, head_sha) and whose rows page terminal states.
+        """
+        row = self._db.execute(
+            "SELECT 1 FROM pings WHERE repo=? AND number=? AND kind=?",
+            (repo, number, kind),
+        ).fetchone()
+        return row is not None
+
+    def record_ping(self, repo: str, number: int, kind: str) -> None:
+        """Idempotent per kind: OR IGNORE keeps the FIRST ping's timestamp,
+        so `pinged_at` is an audit field for when the episode was first
+        raised, not the most recent re-raise."""
+        self._db.execute(
+            "INSERT OR IGNORE INTO pings (repo, number, kind, pinged_at) "
+            "VALUES (?,?,?,?)",
+            (repo, number, kind, int(time.time())),
+        )
+        self._db.commit()
+
     def escalated(self, repo: str, number: int, head_sha: str) -> bool:
         row = self._db.execute(
             "SELECT 1 FROM escalations WHERE repo=? AND number=? AND head_sha=?",

alissa_tools_github_reviewloop-0.10.0/src/main/alissa/tools/github/reviewloop/version

@@ -0,0 +1 @@
+0.10.0

{alissa_tools_github_reviewloop-0.8.0 → alissa_tools_github_reviewloop-0.10.0/src/main/alissa_tools_github_reviewloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-reviewloop
-Version: 0.8.0
+Version: 0.10.0
 Summary: ALISSA-TOOLS-GITHUB-REVIEWLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_reviewloop-0.8.0/src/main/alissa/tools/github/reviewloop/version

@@ -1 +0,0 @@
-0.8.0