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

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

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

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

@@ -94,12 +94,34 @@ def build_parser() -> argparse.ArgumentParser:
     over.add_argument("--hub-template", metavar="TEMPLATE")
     over.add_argument("--agent-profile", metavar="NAME")
     over.add_argument("--reviewer-login", metavar="LOGIN")
+    over.add_argument(
+        "--reviewer-token-env",
+        metavar="VAR",
+        help="NAME of the environment variable holding the reviewer "
+        "identity's GitHub token (never the token itself). Set it and every "
+        "`gh` call runs under that credential explicitly instead of whatever "
+        "the container happened to export",
+    )
     over.add_argument("--state-path", type=Path, metavar="PATH")
     over.add_argument(
         "--on-missing-review-task",
         choices=[ON_MISSING_SPAWN, ON_MISSING_CREATE, ON_MISSING_SKIP],
     )
     over.add_argument("--on-missing-hub", choices=[HUB_SKIP, HUB_ADD])
+    over.add_argument(
+        "--reap-grace-seconds",
+        type=int,
+        metavar="SECONDS",
+        help="how long a reviewer session must be idle AND quiet before the "
+        "sweep reaps it (and before a stale round reads it as dead)",
+    )
+    over.add_argument(
+        "--reap-session-cap",
+        type=int,
+        metavar="N",
+        help="page-worthy threshold: more live reviewer sessions than this "
+        "after a sweep and the daemon logs loudly",
+    )
 
     dry = over.add_mutually_exclusive_group()
     dry.add_argument(
@@ -129,9 +151,12 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "hub_template": args.hub_template,
         "agent_profile": args.agent_profile,
         "reviewer_login": args.reviewer_login,
+        "reviewer_token_env": args.reviewer_token_env,
         "state_path": args.state_path,
         "on_missing_review_task": args.on_missing_review_task,
         "on_missing_hub": args.on_missing_hub,
+        "reap_grace_seconds": args.reap_grace_seconds,
+        "reap_session_cap": args.reap_session_cap,
         "dry_run": args.dry_run,
     }
 

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

@@ -44,10 +44,87 @@ class Task:
         return self.status in OPEN_STATUSES
 
 
-# The namespace loop.session_name() spawns reviewers into; the reap sweep only
-# ever considers sessions under it.
+# The namespace loop.session_name() spawns reviewers into. Kept as the
+# display-level answer to "is this session in the reviewer namespace?" (the
+# console marks unmanaged sessions with it); the REAP path uses the stricter
+# grammar below, because a prefix is not a strong enough claim of ownership to
+# kill on.
 REVIEW_SESSION_PREFIX = "review-"
 
+# The reviewer-session GRAMMAR. The sweep kills sessions and the worker
+# container is shared with other lanes (`develop-*`, `fix-*`, `maintain-*`,
+# ...), so only a name that parses as one of the two shapes the review loop
+# itself produces is ever a reap candidate; anything else is another daemon's
+# (or a human's) and is never touched. Two shapes, both ours:
+#
+#   review-<repo>-pr<n>-r<k>-<nonce>   this daemon's spawns (loop.session_name)
+#   review-pr-<n>[-r<k>]               the alissa-code-review skill's own
+#                                      procedures (spawn-a-reviewer-session.md,
+#                                      run-the-review-loop.md) -- hand-driven
+#                                      rounds of the SAME loop. No spawn ledger
+#                                      knows about those and nothing reaped
+#                                      them: every session in the 2026-07-28
+#                                      memory incident was of this shape.
+#
+# The daemon shape is matched with a non-greedy repo so a hyphenated repo name
+# (`alissa-github-review-daemon`) still lands in the repo group, and it is
+# anchored on the `-pr<n>-r<k>-<nonce>` tail that loop.session_name always
+# emits. The skill shape carries no repo and no nonce -- that is the whole
+# reason a bare `review-pr-<n>` needs the repos allowlist to be resolvable at
+# all (see loop.ReviewWatcher._resolve_pr).
+_DAEMON_SESSION_RE = re.compile(
+    r"^review-(?P<repo>[a-z0-9-]+?)-pr(?P<number>\d+)-r(?P<round>\d+)-[0-9a-f]{4,16}$"
+)
+_SKILL_SESSION_RE = re.compile(
+    r"^review-pr-(?P<number>\d+)(?:-r(?P<round>\d+))?$"
+)
+
+
+@dataclass(frozen=True)
+class SessionRef:
+    """What a reviewer session's NAME says about the round it is running.
+
+    `repo` is the sanitized repo slug (`session_repo_slug`), not an
+    `owner/repo`: session names never carry the owner. `repo` and `round` are
+    None for the skill shape, which encodes neither.
+    """
+
+    number: int
+    repo: "str | None" = None
+    round: "int | None" = None
+
+
+def session_repo_slug(repo: str) -> str:
+    """The repo component of a session name: tmux-safe, lowercase, no dots.
+
+    Shared by the producer (loop.session_name) and the parser below so the two
+    can never drift -- a rename here that the matcher did not follow would make
+    the daemon stop recognizing its own sessions.
+    """
+    return re.sub(r"[^A-Za-z0-9-]", "-", repo).strip("-").lower()
+
+
+def parse_session_name(name: "str | None") -> "SessionRef | None":
+    """Parse a reviewer session name, or None when it is not one of ours.
+
+    None is the security-relevant answer: it is what keeps the sweep off every
+    other lane's sessions in a shared container.
+    """
+    if not isinstance(name, str):
+        return None
+    for pattern in (_SKILL_SESSION_RE, _DAEMON_SESSION_RE):
+        match = pattern.match(name)
+        if match is None:
+            continue
+        parts = match.groupdict()
+        round_ = parts.get("round")
+        return SessionRef(
+            number=int(parts["number"]),
+            repo=parts.get("repo"),
+            round=int(round_) if round_ else None,
+        )
+    return None
+
 
 @dataclass(frozen=True)
 class ManagedSession:
@@ -62,6 +139,11 @@ class ManagedSession:
     def is_idle(self) -> bool:
         return self.status == "idle"
 
+    @property
+    def ref(self) -> "SessionRef | None":
+        """What the name says about the round -- see parse_session_name."""
+        return parse_session_name(self.name)
+
 
 def _title_pattern(owner: str, repo: str, number: int) -> re.Pattern[str]:
     """CR2 title convention: `Review PR <org>/<repo>#<n> (TASK-<origin>)`."""
@@ -257,7 +339,7 @@ class Alissa:
             log.warning("could not set respawn off for %s", session)
 
     def list_review_sessions(self) -> list[ManagedSession]:
-        """The live `review-*` managed sessions, from `alissa tmux ls`.
+        """The live reviewer-grammar managed sessions, from `alissa tmux ls`.
 
         The reap sweep's starting point. Unlike the review-requested search,
         the live session list cannot lose a finished session, so every reap
@@ -265,6 +347,11 @@ class Alissa:
         already gone (self-killed, or killed by an operator) holds no worker
         slot and needs no reap. Raises CommandError upward -- the sweep skips
         this pass and tries again next poll.
+
+        The filter is `parse_session_name`, not the bare `review-` prefix: this
+        list is what the sweep kills from, the container is shared with other
+        daemons, and a name that does not parse as a reviewer session is never
+        enumerated here at all -- so no later bug in the sweep can reach one.
         """
         data = run_json(["alissa", "tmux", "ls", "--json", "--live"], timeout=60) or []
         sessions = []
@@ -272,7 +359,7 @@ class Alissa:
             if not isinstance(row, dict):
                 continue
             name = row.get("name")
-            if isinstance(name, str) and name.startswith(REVIEW_SESSION_PREFIX):
+            if isinstance(name, str) and parse_session_name(name) is not None:
                 last = row.get("lastActivity")
                 sessions.append(
                     ManagedSession(
@@ -284,7 +371,13 @@ class Alissa:
         return sessions
 
     def kill_session(self, session: str) -> None:
-        """Kill a finished reviewer's managed session to free its worker slot.
+        """Kill ONE finished reviewer's managed session to free its worker slot.
+
+        Per-session, always: `alissa tmux kill <name>` and never a server-wide
+        kill. The worker container is shared with every other lane, so a
+        `kill-server` here would take down unrelated daemons' sessions along
+        with the one that is actually finished. A test pins the absence of that
+        verb across the whole package.
 
         Best-effort and idempotent-friendly: the session may already be gone (the
         reviewer self-killed), so a non-zero exit is not an error here. Dry-run

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

@@ -15,10 +15,65 @@ daemons over different workspaces on the same machine, each pointed with
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping
 
+# A POSIX-ish environment variable name -- what `reviewer_token_env` must be.
+_ENV_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+# ...which, on its own, accepts every GitHub credential format: `ghp_`, `gho_`,
+# `ghu_`, `ghs_`, `ghr_` and `github_pat_` tokens are `[A-Za-z0-9_]` throughout
+# and therefore valid identifiers. So the shape has to be rejected explicitly,
+# or the one mistake this validation exists to catch -- pasting the token where
+# its variable's NAME belongs -- sails through.
+_TOKEN_SHAPE_RE = re.compile(r"^(gh[pousr]_|github_pat_)", re.IGNORECASE)
+
+# No environment variable name comes close (`REVLOOP_REVIEWER_GH_TOKEN` is 25);
+# every GitHub token, including the 40-character legacy hex ones, exceeds it.
+MAX_ENV_NAME_LENGTH = 32
+
+# Length is not the whole discriminator, because a secret can be short enough
+# to fit under the ceiling. The shape is: a long, undifferentiated run of
+# alphanumerics. Names are conventionally SCREAMING_SNAKE and separated -- the
+# underscore is what a legacy 40-hex token and a generic alnum API key lack.
+MIN_SECRET_RUN_LENGTH = 20
+
+
+def _is_credential_shaped(value: str) -> bool:
+    """Whether a `reviewer_token_env` value looks like a pasted secret.
+
+    A heuristic, and deliberately one that errs toward accusing: the cost of a
+    false positive is renaming a variable, and the cost of a false negative is
+    a live credential sitting in a config file on a shared volume.
+    """
+    return bool(
+        _TOKEN_SHAPE_RE.match(value)
+        or len(value) > MAX_ENV_NAME_LENGTH
+        or (
+            len(value) >= MIN_SECRET_RUN_LENGTH
+            and "_" not in value
+            and value.isalnum()
+        )
+    )
+
+
+def _describe(value: str) -> str:
+    """Name a rejected value in the error -- redacted only when it has to be.
+
+    `__main__` prints this to stderr as `config error: …`, straight into the
+    container log, so a pasted secret must not be duplicated there: those get
+    length plus a short prefix. But the other way to fail this check is an
+    ordinary typo (`REVLOOP-REVIEWER-GH-TOKEN`), and there the value IS the
+    diagnostic -- redacting it turns a one-glance fix into a puzzle. The two
+    are separable now that credential shapes are identified explicitly.
+    """
+    if _is_credential_shaped(value):
+        return f'a {len(value)}-character value starting "{value[:4]}…"'
+    return repr(value)
+
+
 # What to do when a PR has a pending review request but no matching Alissa
 # review task (CR2 is implementer-side, so a third-party PR may not have one).
 ON_MISSING_SPAWN = "spawn_anyway"  # review anyway, PR URL carries the context
@@ -44,14 +99,52 @@ CONFIG_KEYS = (
     "operators",
     "agent_profile",
     "reviewer_login",
+    "reviewer_token_env",
     "state_path",
     "on_missing_review_task",
     "on_missing_hub",
+    "reap_grace_seconds",
+    "reap_session_cap",
     "dry_run",
 )
 
 MIN_POLL_INTERVAL = 10  # the search API allows 30 req/min
 
+# A reviewer session that has not submitted after this long is presumed dead
+# (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
+# loop._defer_stale_round for the liveness signal.
+#
+# It lives here rather than in `loop` (which re-exports it, so every import
+# site is unchanged) because `reap_grace_seconds` is validated against it, and
+# config cannot import loop without a cycle.
+STALE_ROUND_SECONDS = 90 * 60
+
+# How long a reviewer session must have been idle AND quiet (no tmux activity)
+# before the sweep may reap it, and before the stale-round liveness probe
+# reads it as finished rather than working.
+#
+# Both readings need the same number because they ask the same question -- "is
+# this session done?" -- and a claude session parked at its prompt between
+# turns reports "idle", so only the absence of activity can answer it. The
+# default is generous on purpose: a just-merged PR's reviewer still has
+# in-session close-out to do (CR6 envelope, task move, its own self-kill), and
+# reaping under it loses that work for nothing. Configurable because the right
+# value tracks how long a round's close-out takes on a given deployment.
+DEFAULT_REAP_GRACE_SECONDS = 30 * 60
+
+# Post-sweep alarm threshold: more live reviewer sessions than this and the
+# sweep logs page-worthy, because the reaper is not keeping up with the spawn
+# rate. Each idle agent session holds hundreds of MB forever, and the worker
+# container is shared -- the 2026-07-28 incident was this exact drift, climbing
+# past 10 GB with every review session idle and its PR long merged. A healthy
+# loop runs a couple of concurrent rounds, so the default is a threshold no
+# healthy deployment reaches, not a capacity limit.
+DEFAULT_REAP_SESSION_CAP = 6
+
 
 def default_state_path(workspace_root: Path) -> Path:
     return Path(workspace_root) / ".revloop" / "state.db"
@@ -80,12 +173,27 @@ class Config:
     agent_profile: str = "claude"
     reviewer_login: str | None = None  # None -> resolve once via `gh api user`
 
+    # NAME of the environment variable holding the reviewer identity's GitHub
+    # token -- never the token itself, which has no business in a config file
+    # on a mounted volume. Set it and every `gh` call the daemon makes runs
+    # under that credential explicitly, with the container's inherited
+    # GH_TOKEN/GITHUB_TOKEN stripped; leave it None and the daemon inherits,
+    # which is the pre-#51 behaviour and warns loudly at preflight because a
+    # shared container is exactly where inheritance picks the wrong identity.
+    reviewer_token_env: str | None = None
+
     # None means "derive from the workspace" -- read `state_db` for the
     # resolved location, never this field.
     state_path: Path | None = None
 
     on_missing_review_task: str = ON_MISSING_SPAWN
     on_missing_hub: str = HUB_SKIP
+
+    # The reap sweep's two knobs -- see the constants above for what each one
+    # buys and why it is tunable rather than pinned.
+    reap_grace_seconds: int = DEFAULT_REAP_GRACE_SECONDS
+    reap_session_cap: int = DEFAULT_REAP_SESSION_CAP
+
     dry_run: bool = False
 
     def __post_init__(self) -> None:
@@ -180,6 +288,52 @@ class Config:
                 f"poll_interval must be >= {MIN_POLL_INTERVAL} seconds, got {interval}"
             )
 
+        grace = int(raw.get("reap_grace_seconds", cls.reap_grace_seconds))
+        if grace < 0:
+            raise ValueError(f"reap_grace_seconds must be >= 0, got {grace}")
+        if grace >= STALE_ROUND_SECONDS:
+            # The same number answers the stale-round liveness probe, whose
+            # own window is STALE_ROUND_SECONDS. At or above it the
+            # "idle-finished -> dead -> respawn" branch is unreachable: a
+            # session can never have been quiet longer than the grace by the
+            # time its round goes stale, so every stale round defers forever
+            # and only the operator ping ever fires. Loud here rather than
+            # silently wedged there.
+            raise ValueError(
+                f"reap_grace_seconds must be well under the {STALE_ROUND_SECONDS}s "
+                f"stale-round window (it also gates the stale-round liveness "
+                f"probe, whose respawn branch it would make unreachable), "
+                f"got {grace}"
+            )
+
+        session_cap = int(raw.get("reap_session_cap", cls.reap_session_cap))
+        if session_cap < 1:
+            # 0 would page on every single live reviewer, which is the normal
+            # state of a working loop -- an alarm that always fires is noise.
+            raise ValueError(f"reap_session_cap must be >= 1, got {session_cap}")
+
+        token_env = raw.get("reviewer_token_env")
+        if token_env is not None:
+            token_env = str(token_env).strip()
+            # The overwhelmingly likely way to get here is pasting the TOKEN in
+            # place of the variable's name, which would leave a live credential
+            # in a config file on a shared volume and then fail as "unset
+            # variable" — an error that reads as though the secret were missing
+            # rather than exposed. So the check is two-sided: it must LOOK like
+            # a name, and it must not look like a credential. The value itself
+            # is never echoed back (see _redact).
+            if not _ENV_NAME_RE.match(token_env) or _is_credential_shaped(token_env):
+                rotate = (
+                    " If that is a credential, rotate it: it is now in a config file."
+                    if _is_credential_shaped(token_env)
+                    else ""
+                )
+                raise ValueError(
+                    f"reviewer_token_env must be an environment variable NAME "
+                    f"(e.g. 'REVLOOP_REVIEWER_GH_TOKEN'), not a value or a "
+                    f"token — got {_describe(token_env)}.{rotate}"
+                )
+
         state_path = raw.get("state_path")
         return cls(
             workspace_root=Path(workspace_root),
@@ -190,9 +344,12 @@ class Config:
             operators=operators,
             agent_profile=raw.get("agent_profile", "claude"),
             reviewer_login=raw.get("reviewer_login"),
+            reviewer_token_env=token_env or None,
             state_path=Path(state_path).expanduser() if state_path else None,
             on_missing_review_task=mode,
             on_missing_hub=hub_mode,
+            reap_grace_seconds=grace,
+            reap_session_cap=session_cap,
             dry_run=bool(raw.get("dry_run", False)),
         )