alissa-tools-github-revloop 0.16.11__tar.gz → 0.16.13__tar.gz

{alissa_tools_github_revloop-0.16.11/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.16.13}/PKG-INFO

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

{alissa_tools_github_revloop-0.16.11 → alissa_tools_github_revloop-0.16.13}/src/main/alissa/tools/github/revloop/__main__.py

@@ -122,6 +122,13 @@ def build_parser() -> argparse.ArgumentParser:
         help="page-worthy threshold: more live reviewer sessions than this "
         "after a sweep and the daemon logs loudly",
     )
+    over.add_argument(
+        "--max-concurrent-sessions",
+        type=int,
+        metavar="N",
+        help="spawn gate: at this many live reviewer sessions an owed round "
+        "waits for a slot instead of spawning (must be <= --reap-session-cap)",
+    )
     over.add_argument(
         "--checks-wait-seconds",
         type=int,
@@ -165,6 +172,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "on_missing_hub": args.on_missing_hub,
         "reap_grace_seconds": args.reap_grace_seconds,
         "reap_session_cap": args.reap_session_cap,
+        "max_concurrent_sessions": args.max_concurrent_sessions,
         "checks_wait_seconds": args.checks_wait_seconds,
         "dry_run": args.dry_run,
     }

{alissa_tools_github_revloop-0.16.11 → alissa_tools_github_revloop-0.16.13}/src/main/alissa/tools/github/revloop/alissa.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import logging
 import re
 from dataclasses import dataclass
+from datetime import datetime
 from pathlib import Path
 
 from .proc import CommandError, run, run_json
@@ -190,17 +191,25 @@ def _task_from_row(row: object) -> "Task | None":
 
 @dataclass(frozen=True)
 class TaskDetail:
-    """One task as `alissa task get` sees it: the task itself, plus the CR6
-    verdict envelopes already on it.
-
-    The two travel together because they come out of ONE payload. The decide
-    path needs both (is this still the PR's open review task? how many rounds
-    has it recorded?), and reading them separately would cost two task fetches
-    per PR per poll where the CLI already returns everything in one.
+    """One task as `alissa task get` sees it: the task itself, plus everything
+    the decide path reads off its CR6 verdict evidence.
+
+    All three travel together because they come out of ONE payload. The decide
+    path needs every one of them (is this still the PR's open review task? how
+    many rounds has it recorded? what did the newest round decide?), and
+    `_count_verdicts` and `_newest_verdict` are deliberately written as mirrors
+    over the same evidence array -- so reading them apart would mean fetching
+    and re-parsing the same task two and three times per PR per poll, which is
+    the exact cost this whole path exists to stop paying.
+
+    `verdict` is None when no envelope on the task parses -- the normal round-1
+    case, indistinguishable here from "no verdict of record yet", which is what
+    the caller wants it to mean anyway.
     """
 
     task: Task
     verdicts: int
+    verdict: "str | None"
 
 
 class Alissa:
@@ -251,7 +260,11 @@ class Alissa:
             task = _task_from_row(data)
             if task is None:
                 return None
-            return TaskDetail(task=task, verdicts=self._count_verdicts(data))
+            return TaskDetail(
+                task=task,
+                verdicts=self._count_verdicts(data),
+                verdict=self._newest_verdict(data),
+            )
         except Exception:  # pragma: no cover - defence in depth
             log.exception("could not parse task payload for %s", ref)
             return None
@@ -316,6 +329,44 @@ class Alissa:
             log.exception("could not parse verdict evidence for %s", task_ref)
             return None
 
+    @staticmethod
+    def _created_key(value: object) -> tuple[int, float]:
+        """One evidence item's `createdAt`, as a sortable stamp.
+
+        `alissa task get --json` dates evidence with epoch MILLISECONDS as an
+        int; the API's other surfaces (and hand-written fixtures) use an ISO-8601
+        string. Both are normalised here to one float, because the previous key
+        -- `created if isinstance(created, str) else ""` -- collapsed every real
+        item to the empty string, leaving `max` to keep the FIRST element of an
+        all-equal set. Evidence comes back oldest-first, so on live data the
+        OLDEST verdict won: a PR whose round 1 was request_changes and round 2
+        approve never converged through the envelope branch (TASK-194837655).
+
+        Normalising rather than widening the isinstance is deliberate: a task
+        carrying both shapes would produce `(str, ...)` and `(int, ...)` keys
+        that raise TypeError the moment sorting compared them.
+
+        Returns `(has_stamp, seconds)`. An absent or unparseable stamp is
+        `(0, 0.0)` and sorts FIRST, preserving the old rule that a dated
+        envelope always beats one that lost its timestamp.
+        """
+        if isinstance(value, bool):  # bool is an int; never a timestamp
+            return (0, 0.0)
+        if isinstance(value, (int, float)):
+            seconds = float(value)
+            # Milliseconds, by magnitude: 1e11 seconds is the year 5138, while
+            # 1e11 milliseconds is 1973 -- so anything above it is ms, and a
+            # task holding both units still orders correctly.
+            if abs(seconds) > 1e11:
+                seconds /= 1000.0
+            return (1, seconds)
+        if isinstance(value, str) and value:
+            try:
+                return (1, datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp())
+            except ValueError:
+                return (0, 0.0)
+        return (0, 0.0)
+
     @staticmethod
     def _newest_verdict(payload: object) -> str | None:
         """Pick the newest parseable verdict out of a task's evidence array.
@@ -329,8 +380,8 @@ class Alissa:
         if not isinstance(evidence, list):
             return None
 
-        found: list[tuple[str, str]] = []
-        for item in evidence:
+        found: list[tuple[tuple[int, float], int, str]] = []
+        for index, item in enumerate(evidence):
             if not isinstance(item, dict):
                 continue
             title = item.get("title")
@@ -340,18 +391,21 @@ class Alissa:
                     continue
                 match = _VERDICT_RE.search(blob)
                 if match:
-                    created = item.get("createdAt")
                     found.append(
-                        (created if isinstance(created, str) else "", match.group(1).lower())
+                        (Alissa._created_key(item.get("createdAt")),
+                         index,
+                         match.group(1).lower())
                     )
                     break
 
         if not found:
             return None
-        # ISO-8601 timestamps sort lexicographically. Undated evidence sorts
-        # first (empty string), so a dated envelope always wins over one that
-        # lost its timestamp.
-        return max(found, key=lambda pair: pair[0])[1]
+        # Newest stamp wins; undated evidence sorts first, so a dated envelope
+        # always beats one that lost its timestamp (see _created_key). The
+        # append INDEX breaks ties: evidence comes back oldest-first, so two
+        # envelopes sharing a stamp resolve to the later-recorded one rather
+        # than to whichever `max` happened to reach first.
+        return max(found, key=lambda item: (item[0], item[1]))[2]
 
     def count_verdicts(self, task_ref: str) -> int:
         """How many CR6 verdict envelopes are on the review task.

{alissa_tools_github_revloop-0.16.11 → alissa_tools_github_revloop-0.16.13}/src/main/alissa/tools/github/revloop/config.py

@@ -129,6 +129,7 @@ CONFIG_KEYS = (
     "on_missing_hub",
     "reap_grace_seconds",
     "reap_session_cap",
+    "max_concurrent_sessions",
     "checks_wait_seconds",
     "dry_run",
 )
@@ -170,6 +171,25 @@ DEFAULT_REAP_GRACE_SECONDS = 30 * 60
 # healthy deployment reaches, not a capacity limit.
 DEFAULT_REAP_SESSION_CAP = 6
 
+# The spawn gate: how many reviewer sessions of THIS daemon's own grammar may be
+# live before an owed round waits for a slot instead of spawning (issue #70).
+#
+# Distinct from `reap_session_cap` above in kind, not just in number: that one is
+# an ALARM on a condition the loop cannot fix (sessions the sweep could not
+# reap), this one is a LIMIT the loop enforces on itself before it acts. Nothing
+# bounded concurrency before it -- `round_cap` bounds rounds per PR, and the
+# alarm only logs -- so a merge wave spawned one interactive claude session per
+# PR, all at once, against a fixed container budget. On 2026-07-29 the 18:45-19:00Z
+# burst pegged the deployment's 2 vCPU ceiling with 4+ concurrent reviewers plus
+# the poll loop; throttled sessions review slower, hold their round slots longer,
+# and widen the very burst that is starving them.
+#
+# 4 is the deployed shape's honest ceiling: two vCPUs, and a reviewer session is
+# a full interactive agent. It is deliberately BELOW the reap alarm (6) so the
+# steady state never pages -- and `Config.build` refuses a config where the alarm
+# sits under the limit, which would page on healthy load.
+DEFAULT_MAX_CONCURRENT_SESSIONS = 4
+
 # How long a round holds its APPROVE while the head's CI rollup is still
 # running (or unreadable) before it gives up and records the verdict as a
 # COMMENT instead. An approve from the reviewer identity is the operator's cue
@@ -233,6 +253,11 @@ class Config:
     reap_grace_seconds: int = DEFAULT_REAP_GRACE_SECONDS
     reap_session_cap: int = DEFAULT_REAP_SESSION_CAP
 
+    # The spawn gate's limit -- see DEFAULT_MAX_CONCURRENT_SESSIONS. At or above
+    # it an owed round defers to a later poll instead of spawning; it burns no
+    # round number and no attempt while it waits.
+    max_concurrent_sessions: int = DEFAULT_MAX_CONCURRENT_SESSIONS
+
     # The bound on holding a round's approve for a rollup that has not settled;
     # see DEFAULT_CHECKS_WAIT_SECONDS. 0 is legal and means "never hold": a
     # rollup that is not already green degrades the verdict to a comment on the
@@ -357,6 +382,28 @@ class Config:
             # state of a working loop -- an alarm that always fires is noise.
             raise ValueError(f"reap_session_cap must be >= 1, got {session_cap}")
 
+        max_sessions = int(
+            raw.get("max_concurrent_sessions", cls.max_concurrent_sessions)
+        )
+        if max_sessions < 1:
+            # 0 would defer every round forever: no session may spawn, so no
+            # slot ever frees. "Review nothing" is not a tuning value.
+            raise ValueError(
+                f"max_concurrent_sessions must be >= 1, got {max_sessions}"
+            )
+        if session_cap < max_sessions:
+            # The alarm would then fire on load the gate considers healthy --
+            # every poll of a fully-loaded, correctly-behaving daemon pages the
+            # operator, and a page that fires in the steady state trains people
+            # to ignore the one that matters. Refused at load rather than
+            # discovered at 3am.
+            raise ValueError(
+                f"reap_session_cap ({session_cap}) must be >= "
+                f"max_concurrent_sessions ({max_sessions}): the cap is the "
+                f"page-worthy alarm and the gate is the spawn limit, so an "
+                f"alarm below the limit pages on healthy load"
+            )
+
         checks_wait = int(raw.get("checks_wait_seconds", cls.checks_wait_seconds))
         if checks_wait < 0:
             raise ValueError(f"checks_wait_seconds must be >= 0, got {checks_wait}")
@@ -404,6 +451,7 @@ class Config:
             on_missing_hub=hub_mode,
             reap_grace_seconds=grace,
             reap_session_cap=session_cap,
+            max_concurrent_sessions=max_sessions,
             checks_wait_seconds=checks_wait,
             dry_run=bool(raw.get("dry_run", False)),
         )

{alissa_tools_github_revloop-0.16.11 → alissa_tools_github_revloop-0.16.13}/src/main/alissa/tools/github/revloop/loop.py

@@ -27,6 +27,7 @@ from .alissa import (
     ManagedSession,
     SessionRef,
     Task,
+    TaskDetail,
     is_review_task_for,
     session_repo_slug,
 )
@@ -140,6 +141,81 @@ POLL_FAILURE_LOG_EVERY = 10
 EXPECTED_POLL_FAILURES = (CommandError,)
 
 
+# -- the spawn gate (issue #70) -----------------------------------------------
+#
+# The one INFO line a poll pass emits about deferrals, summarizing them all.
+# Per PASS, never per round: a wave of eight PRs behind a gate of four is one
+# fact about the container, not eight facts about PRs, and the deployed daemon
+# polls every 30s. Streak-limited on the same rule as the poll firewall (the
+# first few in full, then one in ten) so a long queue costs a handful of lines
+# an hour.
+DEFERRAL_SUMMARY = (
+    "spawn gate: %d round(s) deferred — %d/%d reviewer sessions live. "
+    "%s Nothing is lost: a deferred round burns no round number and no "
+    "attempt, and the oldest waiter takes the next free slot."
+)
+
+# What the summary becomes once the gate has been shut, with NOTHING spawning,
+# for longer than POLL_ESCALATE_SECONDS (PR #71 round-1 [major]). Deferral
+# itself is never page-worthy -- a container at its limit that keeps handing
+# out freed slots is the gate working -- but a gate that has spawned nothing
+# for half an hour is not that. Three session classes can hold it shut with the
+# reap alarm silent: a BUSY session is never reaped whatever its PR's state, a
+# hand-spawned `review-pr-<n>` on an OPEN PR is out of the reaper's scope by
+# design (issue #46), and an undecidable session is spared every poll. Four of
+# those against the shipped defaults (limit 4, alarm 6) is a fleet-wide review
+# outage that no other channel reports: the gated rounds write no ledger row,
+# so the stale-round probe cannot see them either.
+DEFERRAL_STALLED = (
+    "spawn gate: %d round(s) deferred — %d/%d reviewer sessions live, and "
+    "NOTHING has spawned for %.0f min. %s This is no longer back-pressure "
+    "doing its job: the reap sweep never frees a busy session, and never "
+    "frees a hand-spawned review-pr-<n> on an open PR, so a wedged session "
+    "holds its slot indefinitely — check the sweep's survivors above."
+)
+
+# The recovery line for an ESCALATED stall: the gate started something again
+# while rounds are still waiting. Logged unconditionally, outside the streak
+# limit, on the rule _note_ledger_writable states -- the operator's last word
+# on a degraded daemon must not be the degradation.
+GATE_STALL_CLEARED = (
+    "spawn gate: spawning again after %d pass(es) over %.0f min with nothing "
+    "started — %d round(s) still waiting, and the queue is moving"
+)
+
+# The recovery line, logged once when a deferral streak ends -- the operator's
+# only evidence in the log that a queue drained on its own.
+DEFERRAL_CLEARED = (
+    "spawn gate: clear after %d pass(es) over %.0f min — every owed round "
+    "spawned"
+)
+
+
+@dataclass(frozen=True)
+class Waiting:
+    """One round's place in the spawn queue, from its FIRST deferral.
+
+    `seq` is the ordering key and it is a COUNTER, not a clock: two rounds
+    deferred in the same pass are microseconds apart, and a wall-clock tie
+    would be broken by whatever `sorted` felt like -- which is the search's own
+    order, i.e. the starvation this exists to prevent. `since` is monotonic and
+    only ever reported, never compared.
+    """
+
+    seq: int
+    since: float
+
+
+def _slug_key(slug: str) -> tuple[str, int]:
+    """`acme/widgets#7` -> the `_waiting` key `("acme/widgets", 7)`.
+
+    The poll walk carries decisions keyed by slug and the gate keys by
+    (repo, number); this is the one place the two spellings meet.
+    """
+    repo, _, number = slug.partition("#")
+    return repo, int(number)
+
+
 class LedgerUnwritable(RuntimeError):
     """Raised by `poll_once` when the ledger gate refuses the pass.
 
@@ -850,6 +926,17 @@ class Action(str, Enum):
     # this one has given up, and the poll snapshot and console aggregate the
     # action rather than the reason.
     ABANDONED = "abandoned"
+    # The round is owed and nothing about the PR blocks it -- the SPAWN GATE
+    # does: `max_concurrent_sessions` reviewer sessions are already live, so it
+    # waits for a slot and is retried on a later poll (issue #70).
+    #
+    # NOT folded into the liveness deferral's IN_FLIGHT/`deferred` pair, which
+    # it superficially resembles: that one names a live session still working
+    # its round, and the console counts it as an ACTIVE SESSION
+    # (webui.sources: in_flight + deferred). A gated round has no session at
+    # all -- counting it as one would inflate exactly the number this gate
+    # exists to hold down.
+    QUEUED = "queued"
 
 
 @dataclass(frozen=True)
@@ -872,6 +959,56 @@ class Decision:
     reenqueued: bool = False
 
 
+@dataclass(frozen=True)
+class ResolvedTask:
+    """One PR's review task as the decide path resolved it THIS pass.
+
+    Carries what the resolution happened to learn, and -- the part that matters
+    -- whether it learned it. The two resolution paths read different things:
+
+    * the CACHED path fetches the task by ref to check the mapping still holds,
+      so the whole evidence array comes with it and both the round count and the
+      newest verdict are free;
+    * the SEARCH path matches TITLES out of the task corpus, so it reads the
+      matched task afterwards to learn both -- and only when THAT read fails
+      does it fall back to a bare `count_verdicts` and know no verdict.
+
+    Hence `verdict_read`, rather than letting `verdict=None` stand for both "no
+    envelope parses" and "nobody looked". Convergence treats a None verdict as
+    "not approved"; conflating the two would silently refuse to close a round
+    that had in fact approved, every time the mapping was resolved by search.
+    """
+
+    task: "Task | None"
+    verdicts: int = 0
+    verdict: "str | None" = None
+    verdict_read: bool = False
+
+    @classmethod
+    def from_detail(cls, detail: TaskDetail) -> "ResolvedTask":
+        """One `alissa task get` payload answered all three questions.
+
+        The `verdict_read=True` invariant lives here rather than at the call
+        sites: it is a property of having read a task detail, and every path
+        that reads one gets it the same way.
+        """
+        return cls(
+            task=detail.task,
+            verdicts=detail.verdicts,
+            verdict=detail.verdict,
+            verdict_read=True,
+        )
+
+    def newest_verdict(self, alissa: Alissa) -> "str | None":
+        """The newest CR6 verdict envelope, fetching it only if this resolution
+        did not already have it in hand."""
+        if self.task is None:
+            return None
+        if self.verdict_read:
+            return self.verdict
+        return alissa.latest_verdict(self.task.ref)
+
+
 @dataclass(frozen=True)
 class ChecksGate:
     """What the head's CI rollup does to a round's APPROVE verdict.
@@ -966,6 +1103,38 @@ class ReviewWatcher:
         # de-duplication, and a corpus that outlived its pass would answer the
         # next one from titles and statuses that have since moved.
         self._pass_tasks: list[Task] | None = None
+        # -- the spawn gate's per-pass and cross-pass state (issue #70) ------
+        # How many own-grammar reviewer sessions are live THIS pass, and
+        # whether anyone has looked. The sweep seeds both (it lists the
+        # sessions anyway); a count of None with `_census_probed` True means
+        # the list could not be read, which the gate treats as "unknown" and
+        # fails OPEN -- see _live_session_count.
+        self._session_census: int | None = None
+        self._census_probed = False
+        self._census_warned = False
+        # (repo full name, PR number) -> where that round sits in the spawn
+        # queue, from the first pass that deferred it. Cross-pass and
+        # in-memory: it is a FAIRNESS ORDER, not a decision the daemon must
+        # remember -- a restart costs the queue its order for one pass (every
+        # waiter is re-stamped on its next deferral) and nothing else, which
+        # does not justify a ledger table on the poll path. Pruned every pass
+        # against the live candidate set, so a merged or converged PR cannot
+        # hold a place forever.
+        self._waiting: dict[tuple[str, int], Waiting] = {}
+        self._wait_seq = 0
+        # Consecutive passes that deferred at least one round -- the summary
+        # line's streak limiter, and ONLY that. It never escalates: a queue
+        # that keeps draining is the gate working, and a wave permanently
+        # larger than the limit would otherwise page forever on a daemon that
+        # is reviewing everything, just serially.
+        self._gate_streak = Streak()
+        # Consecutive passes that deferred a round and spawned NOTHING -- the
+        # escalating one (PR #71 round-1 [major]). Cleared by any spawn,
+        # because a spawn is the proof the queue is moving; once it outlasts
+        # POLL_ESCALATE_SECONDS the summary switches to DEFERRAL_STALLED at
+        # WARNING. Separate from the limiter above so the predicate that pages
+        # is "the gate is stuck", not "the gate is busy".
+        self._gate_stall = Streak()
         # Consecutive passes refused by the ledger gate in poll_once, and when
         # the refusal began -- the same streak-limit-then-escalate shape the
         # poll firewall uses, for the same reason: a read-only volume refuses
@@ -994,8 +1163,8 @@ class ReviewWatcher:
             self._pass_tasks = self.alissa.list_tasks()
         return self._pass_tasks
 
-    def _review_task(self, pr: PullRequest) -> tuple["Task | None", int]:
-        """This PR's open CR2 review task and its verdict count, cheaply.
+    def _review_task(self, pr: PullRequest) -> "ResolvedTask":
+        """This PR's open CR2 review task and what its evidence says, cheaply.
 
         The decide path needs the review task on every pass of every open
         round, and the only way to FIND one is to search the actor's whole
@@ -1019,13 +1188,31 @@ class ReviewWatcher:
         Fail-open is the whole contract: every degradation here lands on "do
         what the daemon did before the cache existed", and none of them can
         answer "no review task" unless a successful search actually said so.
+
+        TWO consequences of resolving from cache, both accepted rather than
+        overlooked (PR #68 round 1):
+
+        * A cached hit does NOT re-check CR2 uniqueness. The duplicate-task
+          alarm lives in `find_review_task`, which only runs on a miss, so a
+          second open review task created for this PR AFTER the mapping was
+          cached goes unreported and the daemon keeps counting envelopes on the
+          one it pinned. Detecting it needs the corpus, and not fetching the
+          corpus is the point -- relocating the check is TASK-317167904.
+        * VALIDATING the review task drops the mapping, because
+          `is_review_task_for` requires an open task and the search cannot find
+          a terminal one either, so `evaluate` falls back to the GitHub review
+          count -- the fallback `_completed_rounds` deliberately avoids. That is
+          pre-existing and unchanged, but this path now HAS a durable ref that
+          could survive validation; it is not used because a terminal task can
+          never become open again, so a retained ref would have no disproof and
+          its row would be immortal. Settling that is TASK-1897198077.
         """
         cached = self.state.review_task(pr.full_name, pr.number)
         if cached is not None:
             detail = self.alissa.get_task(cached)
             if detail is not None:
                 if is_review_task_for(pr.owner, pr.repo, pr.number, detail.task):
-                    return detail.task, detail.verdicts
+                    return ResolvedTask.from_detail(detail)
                 log.info(
                     "%s: cached review task %s no longer matches (title=%r "
                     "status=%s) — re-resolving",
@@ -1048,10 +1235,24 @@ class ReviewWatcher:
             # no open review task for this PR, whatever the cache said.
             if cached is not None:
                 self.state.forget_review_task(pr.full_name, pr.number)
-            return None, 0
+            return ResolvedTask(task=None)
 
         self.state.record_review_task(pr.full_name, pr.number, task.ref)
-        return task, self.alissa.count_verdicts(task.ref)
+        # The search matched a TITLE out of the corpus; the round count and the
+        # verdict both live in the task's evidence, and ONE read returns both.
+        # Reading it here rather than paying `count_verdicts` now and
+        # `latest_verdict` again from convergence is the same saving the cached
+        # path makes -- and it matters most in the degraded state this whole
+        # change serves: an unreadable ledger sends EVERY PR down this path on
+        # EVERY pass (PR #69 round 1).
+        detail = self.alissa.get_task(task.ref)
+        if detail is not None:
+            return ResolvedTask.from_detail(detail)
+        # That read failed, so the verdict is genuinely unknown -- left UNREAD
+        # rather than defaulted to None, which convergence would take as "no
+        # approve" and lose a closed round. Falls back to exactly the two-read
+        # behaviour this path had before.
+        return ResolvedTask(task=task, verdicts=self.alissa.count_verdicts(task.ref))
 
     # -- per-PR decision ---------------------------------------------------
 
@@ -1082,9 +1283,10 @@ class ReviewWatcher:
         # Fall back to the substantive-review count only before the review task
         # exists (round 1). Looked up here (not in _spawn) because both the count
         # and convergence need it.
-        task, verdicts = self._review_task(pr)
+        resolved = self._review_task(pr)
+        task = resolved.task
         native = countable_rounds(my_reviews)
-        completed = verdicts if task is not None else native
+        completed = resolved.verdicts if task is not None else native
 
         # A round is not over until its verdict exists as a native review by
         # the reviewer identity (issue #51). An envelope ahead of the native
@@ -1114,7 +1316,7 @@ class ReviewWatcher:
             # anything else the round is still open and nothing may follow it.
             return self._close_round_natively(pr, task, round_=completed)
 
-        converged = self._convergence_reason(my_reviews, task, pr.head_sha)
+        converged = self._convergence_reason(my_reviews, resolved, pr.head_sha)
         if converged is not None:
             # THE terminal branch: a verdict of record exists at the current
             # head, so no round k+1 can be owed from here -- every path that
@@ -1156,6 +1358,22 @@ class ReviewWatcher:
             deferred = self._defer_stale_round(pr, round_, age, cap)
             if deferred is not None:
                 return deferred
+
+        # THE SPAWN GATE, and it sits here -- past every branch that decides
+        # WHETHER a round is owed, immediately before the one that acts.
+        # Upstream of it the loop is only reading; downstream it starts an
+        # interactive agent. So a gated round has passed convergence, the cap
+        # and CR9 re-entry identically to one that spawns: re-entry-granted
+        # rounds queue through the gate like any other, delayed and never
+        # denied. A stale-round respawn is gated too -- it is a spawn, and the
+        # dead session it replaces is exactly as absent next poll.
+        held = self._gate_spawn(pr, round_)
+        if held is not None:
+            return held
+
+        if age is not None:
+            # Logged only once the gate has let the respawn through, so the
+            # line cannot claim a re-enqueue that back-pressure then deferred.
             log.warning(
                 "%s round %d has been in flight %.0f min with no submitted review "
                 "and its session is gone or finished — re-enqueuing (reviewer "
@@ -1167,6 +1385,206 @@ class ReviewWatcher:
 
         return self._spawn(pr, round_, task, cap, reenqueued=age is not None)
 
+    # -- the spawn gate ----------------------------------------------------
+
+    def _gate_spawn(self, pr: PullRequest, round_: int) -> Decision | None:
+        """Hold an owed round back when the container is already full.
+
+        Returns a QUEUED Decision when the round must wait, or None to spawn.
+
+        DEFERRAL IS NOT FAILURE, and every part of that is load-bearing:
+
+        * it writes NO spawn-ledger row, so the round number is untouched (the
+          next poll computes the same `completed + 1`) and no attempt is spent;
+        * with no row there is no `spawn_age`, so the stale-round probe and its
+          respawn branch cannot see the round at all -- a round can sit gated
+          for hours without ever being "in flight 90 minutes";
+        * it posts nothing: no PR comment, no operator page, no escalation.
+          The only trace is one summary line per pass (see _note_deferrals).
+
+        The count is of sessions matching THIS package's grammar and no other
+        (`Alissa.list_review_sessions` filters on `parse_session_name`), which
+        is the same ownership boundary the reaper draws: other lanes share the
+        container and are invisible here in both directions. Hand-spawned
+        `review-pr-<n>` sessions are ours by that grammar and DO count -- they
+        consume the same CPU, and a gate that ignored them would let a
+        hand-driven round and a daemon round each think it had the last slot.
+
+        Sessions this pass has already enqueued count too (`_spawn` increments
+        the census): the census is read once per pass, so without that a single
+        pass would hand the same free slot to every PR in the wave.
+        """
+        limit = self.config.max_concurrent_sessions
+        live = self._live_session_count()
+        key = (pr.full_name, pr.number)
+        if live is None or live < limit:
+            # Spawning: this round is no longer waiting on anything. Dropped
+            # here rather than in `_spawn`, which can still bail on a missing
+            # hub or review task -- a round that never reaches the enqueue is
+            # not holding a queue place either.
+            self._waiting.pop(key, None)
+            return None
+
+        wait = self._waiting.get(key)
+        if wait is None:
+            self._wait_seq += 1
+            wait = Waiting(seq=self._wait_seq, since=time.monotonic())
+            self._waiting[key] = wait
+        return Decision(
+            Action.QUEUED,
+            f"round {round_} deferred — {live}/{limit} reviewer sessions live "
+            f"(waiting {int(time.monotonic() - wait.since)}s)",
+            round_,
+        )
+
+    def _live_session_count(self) -> int | None:
+        """Own-grammar reviewer sessions live this pass, or None if unknown.
+
+        Seeded by the reap sweep, which lists them anyway, so the gate costs no
+        extra `alissa tmux ls` in the daemon. A caller that reaches the gate
+        without a sweep (a direct `evaluate`, or a pass whose sweep bailed
+        early) probes once and memoizes for the pass.
+
+        None -- the list could not be read -- FAILS OPEN: the spawn proceeds.
+        The alternative was tried on paper and rejected: `alissa tmux ls` is
+        also the reaper's only input, so a CLI that cannot answer it means
+        nothing is being reaped either, and refusing every spawn would turn one
+        broken subprocess into a fleet-wide review outage while the container
+        sat idle. Failing open restores exactly the pre-gate behaviour for as
+        long as the outage lasts, and it is loud (once per pass) about doing
+        so.
+        """
+        if not self._census_probed:
+            self._census_probed = True
+            try:
+                self._session_census = len(self.alissa.list_review_sessions())
+            except CommandError as exc:
+                self._session_census = None
+                log.warning(
+                    "spawn gate: could not count live reviewer sessions (%s) — "
+                    "allowing spawns this pass rather than stalling the loop on "
+                    "a session list the reaper cannot read either",
+                    exc,
+                )
+                self._census_warned = True
+        if self._session_census is None and not self._census_warned:
+            self._census_warned = True
+            log.warning(
+                "spawn gate: the live reviewer-session count is unknown this "
+                "pass — allowing spawns (the gate is back-pressure, not a "
+                "safety interlock)"
+            )
+        return self._session_census
+
+    def _gate_order(
+        self, requests: list[tuple[str, str, int]]
+    ) -> list[tuple[str, str, int]]:
+        """This pass's candidates, oldest waiter first.
+
+        FIFO fairness, and it needs its own order because the walk order it
+        replaces is NOT fair: `review_requests` is a `search/issues` query, and
+        that API sorts by best match by default -- a relevance ranking with no
+        relation to how long a round has been waiting, and not even stable
+        between calls. Under a gate that hands out one slot per freed session,
+        an unstable order starves whichever PR keeps losing the coin toss.
+
+        So: everything that has already been deferred goes first, in the order
+        it was FIRST deferred (`Waiting.seq`), then everything else in the
+        search's own order. A round that has waited two passes therefore takes
+        the next free slot ahead of one that has waited none -- which is the
+        whole anti-starvation guarantee -- and a pass with no deferrals is
+        byte-for-byte the old walk.
+        """
+        if not self._waiting:
+            return requests
+        return sorted(
+            requests,
+            key=lambda item: (
+                self._waiting[(f"{item[0]}/{item[1]}", item[2])].seq
+                if (f"{item[0]}/{item[1]}", item[2]) in self._waiting
+                else self._wait_seq + 1
+            ),
+        )
+
+    def _note_deferrals(self, results: list[tuple[str, Decision]]) -> None:
+        """One streak-limited line per pass summarizing the gate.
+
+        INFO while the queue MOVES -- a full container that keeps handing out
+        freed slots is the gate working, and paging on it would make normal
+        load indistinguishable from a leak. It escalates to WARNING on a
+        different predicate: passes that deferred and spawned NOTHING,
+        consecutively, for longer than POLL_ESCALATE_SECONDS. That is not
+        back-pressure, it is a review outage the reap alarm can miss entirely
+        (see DEFERRAL_STALLED), and this module's own rule for it is stated at
+        _note_ledger_unwritable: a daemon that is up, polling, and deciding
+        nothing is the most misleading state it can be in.
+
+        The two are separate streaks on purpose. One spawn proves the queue is
+        moving and clears the stall, but it does NOT end the deferral episode
+        the log limiter is rationing -- collapsing them would either page on a
+        draining wave or reset the limiter every pass and log one line per
+        poll, which is the spam the summary exists to avoid.
+        """
+        now = time.monotonic()
+        held = [(slug, d) for slug, d in results if d.action is Action.QUEUED]
+        if not held:
+            self._gate_stall.clear()
+            ended = self._gate_streak.resolve(now)
+            if ended is not None:
+                passes, seconds = ended
+                log.info(DEFERRAL_CLEARED, passes, seconds / 60)
+            return
+
+        should_log, _ = self._gate_streak.record(now)
+        if any(d.action is Action.SPAWNED for _, d in results):
+            # The queue is draining: rounds waited, but a slot freed and the
+            # oldest waiter took it. Whatever the backlog, this is not a stall.
+            # A stall that had ESCALATED says so out loud on its way out, past
+            # the streak limit -- otherwise the last word an operator has on
+            # the gate is a WARNING the daemon has already recovered from.
+            escalated = self._gate_stall.escalated
+            ended = self._gate_stall.resolve(now)
+            if escalated and ended is not None:
+                passes, seconds = ended
+                log.info(GATE_STALL_CLEARED, passes, seconds / 60, len(held))
+        else:
+            _, crossing = self._gate_stall.record(now)
+            # The crossing BYPASSES the streak limit, on the same reasoning as
+            # the ledger gate's: it is a state change, and suppressing it would
+            # hide the one transition the line exists to show.
+            should_log = should_log or crossing
+        if not should_log:
+            return
+        # A round is only ever deferred against a census the gate could read,
+        # so this is never the fallback -- an unreadable count fails open and
+        # produces no deferrals at all.
+        live = self._session_census or 0
+        waiting = "Waiting, oldest first: " + ", ".join(
+            slug for slug, _ in sorted(
+                held,
+                key=lambda item: self._waiting.get(
+                    _slug_key(item[0]), Waiting(seq=0, since=0.0)
+                ).seq,
+            )
+        ) + "."
+        if self._gate_stall.escalated:
+            log.warning(
+                DEFERRAL_STALLED,
+                len(held),
+                live,
+                self.config.max_concurrent_sessions,
+                self._gate_stall.held(now) / 60,
+                waiting,
+            )
+            return
+        log.info(
+            DEFERRAL_SUMMARY,
+            len(held),
+            live,
+            self.config.max_concurrent_sessions,
+            waiting,
+        )
+
     # -- native verdict post -----------------------------------------------
 
     def _close_round_natively(
@@ -1972,7 +2390,7 @@ class ReviewWatcher:
         )
 
     def _convergence_reason(
-        self, my_reviews: list[Review], task: Task | None, head_sha: str
+        self, my_reviews: list[Review], resolved: "ResolvedTask", head_sha: str
     ) -> str | None:
         """Why the loop is done, or None if it is not.
 
@@ -2033,9 +2451,14 @@ class ReviewWatcher:
             return None
 
         # Only checkable once a review task exists; before that there is
-        # nowhere for a verdict to have been recorded.
-        if task is not None and self.alissa.latest_verdict(task.ref) == VERDICT_APPROVE:
-            return f"newest verdict envelope on {task.ref} reads approve"
+        # nowhere for a verdict to have been recorded. On the cached path the
+        # envelope was already read back with the task, so this costs nothing;
+        # on the search path it is the one fetch that still has to happen.
+        if (
+            resolved.task is not None
+            and resolved.newest_verdict(self.alissa) == VERDICT_APPROVE
+        ):
+            return f"newest verdict envelope on {resolved.task.ref} reads approve"
 
         return None
 
@@ -2313,6 +2736,10 @@ class ReviewWatcher:
             sessions = self.alissa.list_review_sessions()
         except CommandError as exc:
             log.warning("reap sweep skipped: could not list sessions: %s", exc)
+            # Probed and unanswerable. The spawn gate reads the same list, so
+            # it is told the count is unknown rather than left to pay for a
+            # second failing subprocess per candidate PR.
+            self._census_probed, self._session_census = True, None
             return 0
 
         # Drop cached resolutions for sessions that are gone. Names are unique
@@ -2333,6 +2760,13 @@ class ReviewWatcher:
         completed_cache: dict[tuple[str, int, str | None], float | None] = {}
         holdouts: dict[str, str] = {}
         reaped: list[str] = []
+        # Dry-run only: what a production sweep would have killed here. The
+        # spawn gate's census has to be seeded with production's slot count or
+        # `--dry-run` reports rounds QUEUED that production would spawn -- the
+        # opposite error to the one _spawn's self-increment fixes, in the one
+        # tool an operator reaches for during exactly this incident class (PR
+        # #71 round-1 [minor]). Empty in production, where `reaped` carries it.
+        would_reap: list[str] = []
 
         for ses in sessions:
             idle_for = time.time() - ses.last_activity
@@ -2380,6 +2814,7 @@ class ReviewWatcher:
             if self.config.dry_run:
                 log.info("[dry-run] would reap reviewer session %s (%s)", ses.name, evidence)
                 holdouts[ses.name] = f"dry-run: would have reaped ({evidence})"
+                would_reap.append(ses.name)
                 continue
             try:
                 self.alissa.kill_session(ses.name)
@@ -2394,7 +2829,7 @@ class ReviewWatcher:
             reaped.append(ses.name)
             log.info("reaped reviewer session %s (%s)", ses.name, evidence)
 
-        self._check_session_cap(sessions, reaped, holdouts)
+        self._check_session_cap(sessions, reaped, holdouts, would_reap)
         return len(reaped)
 
     def _hold(self, holdouts: dict[str, str], ses: ManagedSession, why: str) -> None:
@@ -2557,6 +2992,7 @@ class ReviewWatcher:
         sessions: list[ManagedSession],
         reaped: list[str],
         holdouts: dict[str, str],
+        would_reap: list[str] | None = None,
     ) -> None:
         """Page-worthy log when the sweep is not keeping up.
 
@@ -2584,6 +3020,23 @@ class ReviewWatcher:
         """
         killed = set(reaped)
         remaining = sorted(s.name for s in sessions if s.name not in killed)
+        # The spawn gate's census for this pass, taken from the same post-sweep
+        # list the alarm counts: what the sweep could not free is exactly what
+        # is still holding CPU when the gate decides. Seeded here so the gate
+        # never runs its own `alissa tmux ls`.
+        #
+        # `would_reap` is the dry-run correction and nothing else: a dry-run
+        # sweep kills nothing, so without it the census counts slots production
+        # would have freed and the diagnostic reports rounds gated that
+        # production spawns. Deliberately NOT subtracted from `remaining`
+        # below -- the alarm's own count is documented as "sessions this pass
+        # could not free", and a dry-run pass genuinely freed none of them
+        # (each carries a `dry-run: would have reaped` holdout reason that says
+        # so). That reading predates the gate; the census is the part the gate
+        # owns.
+        pretend = set(would_reap or ())
+        self._census_probed = True
+        self._session_census = sum(1 for name in remaining if name not in pretend)
         if len(remaining) <= self.config.reap_session_cap:
             self._paged_cap = None
             return
@@ -2715,6 +3168,16 @@ class ReviewWatcher:
             dry_run=self.config.dry_run,
         )
 
+        # This pass's own spawns count against the gate immediately (issue
+        # #70). The census is read once per pass and a just-enqueued session
+        # takes a moment to appear in `alissa tmux ls`, so without this a
+        # merge wave would hand one free slot to every PR in it -- the
+        # unbounded burst the gate exists to prevent, reintroduced by a
+        # caching detail. Incremented in dry-run too: the diagnostic's job is
+        # to report the decisions production would take.
+        if self._session_census is not None:
+            self._session_census += 1
+
         if not self.config.dry_run:
             self.state.record_spawn(
                 repo=pr.full_name,
@@ -3015,6 +3478,14 @@ class ReviewWatcher:
         # to this one's title searches as if it were current, and it is the one
         # piece of per-pass state whose staleness would be invisible.
         self._pass_tasks = None
+        # ...and so does the spawn gate's session census: a count carried over
+        # from the previous pass would gate this one on sessions that have
+        # since been reaped (or miss ones that have since spawned). Cleared
+        # with `_pass_tasks` and for the same reason. The `_waiting` queue is
+        # deliberately NOT cleared -- it is what remembers who has waited
+        # longest ACROSS passes.
+        self._session_census = None
+        self._census_probed = self._census_warned = False
 
         # THE LEDGER GATE (issue #62, PR #63 round-1 blocker). Nothing below
         # may run when the ledger cannot record what it does.
@@ -3043,9 +3514,18 @@ class ReviewWatcher:
         # DRY-RUN IS EXEMPT, and vacuously so: it already suppresses every side
         # effect AND every correctness write (`_spawn` skips record_spawn, the
         # reaper logs instead of killing, the drift/cap-out/deferral paths
-        # return before both their comment and their record). Its only ledger
-        # write is the snapshot, which this module classifies as best-effort
-        # telemetry and which _write_snapshot writes in dry-run deliberately.
+        # return before both their comment and their record). The ledger writes
+        # it may still take are the snapshot and the review-task cache
+        # (`_review_task` runs in dry-run and both records and forgets
+        # mappings) -- both classified by this module as best-effort telemetry,
+        # both absorbed by _write_telemetry, and neither a decision the daemon
+        # has to remember. Writing the cache in dry-run is deliberate: a
+        # dry-run pass that learns a mapping hands it to the next production
+        # pass, and suppressing it would make the two disagree about ledger
+        # contents for no correctness reason. The cost on a read-only volume is
+        # a reconnect attempt on the first failure of the streak plus
+        # streak-limited warnings, which is the same best-effort behaviour the
+        # snapshot has always had there.
         # So the gate would protect nothing there and cost the operator the one
         # tool that answers "what would you do right now" -- asked, precisely,
         # during the substrate incident this whole change is about.
@@ -3064,8 +3544,17 @@ class ReviewWatcher:
         requests = self.github.review_requests(self.config.repos)
         log.info("%d PR(s) with a review pending from %s", len(requests), self.github.login)
 
+        # Forget queue places belonging to PRs this pass cannot act on at all
+        # (merged, converged, withdrawn): they are gone from the search, so
+        # nothing would ever clear them and the oldest-first order would be
+        # anchored to a PR that is never coming back.
+        live_keys = {(f"{owner}/{repo}", number) for owner, repo, number in requests}
+        self._waiting = {
+            key: wait for key, wait in self._waiting.items() if key in live_keys
+        }
+
         results = []
-        for owner, repo, number in requests:
+        for owner, repo, number in self._gate_order(requests):
             slug = f"{owner}/{repo}#{number}"
             if not self.config.watches(f"{owner}/{repo}"):
                 continue
@@ -3081,6 +3570,8 @@ class ReviewWatcher:
             log.log(level, "%s → %s (%s)", slug, decision.action.value, decision.reason)
             results.append((slug, decision))
 
+        self._note_deferrals(results)
+
         # Persist one poll_snapshots row per pass, built entirely from the
         # Decision list already in hand plus the reap count -- no new GitHub
         # calls. Written in dry-run too: a snapshot OBSERVES the pass, it is
@@ -3191,6 +3682,7 @@ class ReviewWatcher:
             if d.action is Action.IN_FLIGHT and d.deferred
         )
         self.state.record_snapshot(
+            queued=counts[Action.QUEUED],
             duration_ms=duration_ms,
             candidates=len(results),
             spawned=spawned,

{alissa_tools_github_revloop-0.16.11 → alissa_tools_github_revloop-0.16.13}/src/main/alissa/tools/github/revloop/state.py

@@ -157,6 +157,12 @@ CREATE TABLE IF NOT EXISTS verdict_posts (
 -- losing the whole table only costs one title search per PR (see
 -- loop._review_task). That is why this is best-effort like the snapshots
 -- above, not a correctness write.
+--
+-- Rows are never pruned, unlike poll_snapshots and like grants: one row per PR
+-- ever sighted (a few hundred, for this daemon's repo set, forever), and a
+-- stale row costs exactly one disproved read the first time that PR is seen
+-- again. `resolved_at` is retained for inspection -- when was this mapping last
+-- confirmed by a search -- and nothing in the daemon reads it.
 CREATE TABLE IF NOT EXISTS review_tasks (
     repo        TEXT    NOT NULL,
     number      INTEGER NOT NULL,
@@ -182,6 +188,12 @@ CREATE TABLE IF NOT EXISTS poll_snapshots (
     posted            INTEGER NOT NULL DEFAULT 0,
     awaiting_post     INTEGER NOT NULL DEFAULT 0,
     abandoned         INTEGER NOT NULL DEFAULT 0,
+    -- Rounds the spawn gate held back this pass because the container was
+    -- already at max_concurrent_sessions (issue #70). Its own column rather
+    -- than a share of `deferred`: that one counts rounds whose LIVE session is
+    -- still working, and the console reads the two together as active
+    -- sessions -- a gated round has no session at all.
+    queued            INTEGER NOT NULL DEFAULT 0,
     stages_json       TEXT    NOT NULL
 );
 """
@@ -198,6 +210,7 @@ _ADDED_COLUMNS = {
         ("posted", "INTEGER NOT NULL DEFAULT 0"),
         ("awaiting_post", "INTEGER NOT NULL DEFAULT 0"),
         ("abandoned", "INTEGER NOT NULL DEFAULT 0"),
+        ("queued", "INTEGER NOT NULL DEFAULT 0"),
     ),
     "verdict_posts": (
         ("checks_held_at", "INTEGER"),
@@ -905,8 +918,10 @@ class State:
         """Remember which review task a PR resolved to. Best-effort.
 
         REPLACE, not IGNORE: re-resolving is how a mapping is corrected, so the
-        newest answer has to win. `resolved_at` is when the mapping was last
-        confirmed by a search, which is the audit question worth answering.
+        newest answer has to win. `resolved_at` records when the mapping was
+        last confirmed by a search; it is kept for inspection (the age of a
+        mapping is the first thing worth knowing if one is ever suspected) and
+        no query, log line or console view reads it.
 
         A database error here is absorbed exactly like a snapshot's: the cache
         is an optimization, and a pass that cannot persist it still decides the
@@ -962,6 +977,7 @@ class State:
         posted: int = 0,
         awaiting_post: int = 0,
         abandoned: int = 0,
+        queued: int = 0,
         stages: list[dict],
     ) -> bool:
         """Append one poll-pass observation, then prune to the newest
@@ -996,6 +1012,7 @@ class State:
                 posted=posted,
                 awaiting_post=awaiting_post,
                 abandoned=abandoned,
+                queued=queued,
                 stages=stages,
             ),
             "poll snapshot",
@@ -1018,6 +1035,7 @@ class State:
         posted: int,
         awaiting_post: int,
         abandoned: int,
+        queued: int,
         stages: list[dict],
     ) -> None:
         """The snapshot INSERT + prune itself, strict. Split out so the
@@ -1026,8 +1044,8 @@ class State:
             "INSERT INTO poll_snapshots "
             "(ts, duration_ms, candidates, spawned, stale_reenqueued, "
             "in_flight, deferred, converged, capped, escalated, skipped, "
-            "reaped, posted, awaiting_post, abandoned, stages_json) "
-            "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+            "reaped, posted, awaiting_post, abandoned, queued, stages_json) "
+            "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
             (
                 int(time.time()),
                 duration_ms,
@@ -1044,6 +1062,7 @@ class State:
                 posted,
                 awaiting_post,
                 abandoned,
+                queued,
                 json.dumps(stages, separators=(",", ":")),
             ),
         )

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

@@ -0,0 +1 @@
+0.16.13

{alissa_tools_github_revloop-0.16.11 → alissa_tools_github_revloop-0.16.13}/src/main/alissa/tools/github/revloop/webui/page.py

@@ -204,7 +204,7 @@ section.panel {
   border-color: var(--status-in-progress); background: var(--status-in-progress-bg); }
 .pill.in-flight { color: var(--status-committed);
   border-color: var(--status-committed); background: var(--status-committed-bg); }
-.pill.deferred { color: var(--status-pending);
+.pill.deferred, .pill.queued { color: var(--status-pending);
   border-color: var(--status-pending); background: var(--status-pending-bg); }
 .pill.converged, .pill.posted { color: var(--status-in-progress);
   border-color: var(--status-in-progress); background: var(--status-in-progress-bg); }

{alissa_tools_github_revloop-0.16.11 → alissa_tools_github_revloop-0.16.13/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

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

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

@@ -1 +0,0 @@
-0.16.11