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

{alissa_tools_github_revloop-0.16.12/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.12
+Version: 0.16.13
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.16.12 → 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.12 → 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.12 → alissa_tools_github_revloop-0.16.13}/src/main/alissa/tools/github/revloop/loop.py

@@ -141,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.
 
@@ -851,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)
@@ -1017,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
@@ -1240,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 "
@@ -1251,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(
@@ -2402,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
@@ -2422,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
@@ -2469,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)
@@ -2483,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:
@@ -2646,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.
 
@@ -2673,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
@@ -2804,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,
@@ -3104,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.
@@ -3162,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
@@ -3179,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
@@ -3289,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.12 → alissa_tools_github_revloop-0.16.13}/src/main/alissa/tools/github/revloop/state.py

@@ -188,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
 );
 """
@@ -204,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"),
@@ -970,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
@@ -1004,6 +1012,7 @@ class State:
                 posted=posted,
                 awaiting_post=awaiting_post,
                 abandoned=abandoned,
+                queued=queued,
                 stages=stages,
             ),
             "poll snapshot",
@@ -1026,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
@@ -1034,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,
@@ -1052,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.12 → 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.12 → 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.12
+Version: 0.16.13
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

@@ -1 +0,0 @@
-0.16.12