alissa-tools-github-revloop 0.16.16__tar.gz → 0.18.0__tar.gz

{alissa_tools_github_revloop-0.16.16/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.18.0}/PKG-INFO

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

{alissa_tools_github_revloop-0.16.16 → alissa_tools_github_revloop-0.18.0}/src/main/alissa/tools/github/revloop/__main__.py

@@ -137,6 +137,40 @@ def build_parser() -> argparse.ArgumentParser:
         "rollup is still running (or unreadable) before recording the verdict "
         "as a comment instead; a red rollup never waits and never approves",
     )
+    over.add_argument(
+        "--checks-spawn-wait-seconds",
+        type=int,
+        metavar="SECONDS",
+        help="how long an owed round waits for the head's CI to conclude before "
+        "its reviewer is queued at all, so a session cannot approve ahead of the "
+        "evidence; 0 queues immediately and relies on the directive alone",
+    )
+
+    over.add_argument(
+        "--review-task-miss-ttl-polls",
+        type=int,
+        metavar="N",
+        help="how many polls a PR with NO review task is taken on trust before "
+        "the task corpus is searched for one again; must be >= 1",
+    )
+
+    scope = over.add_mutually_exclusive_group()
+    scope.add_argument(
+        "--task-list-self-scope",
+        dest="task_list_self_scope",
+        action="store_true",
+        default=None,
+        help="narrow `alissa task list` to this actor's own rows (--self), "
+        "dropping the sponsor's corpus. Only for deployments where EVERY "
+        "review task is created by this daemon's own sessions: a review task "
+        "the list cannot see is a round the daemon cannot count",
+    )
+    scope.add_argument(
+        "--no-task-list-self-scope",
+        dest="task_list_self_scope",
+        action="store_false",
+        help="list the sponsor-union corpus even if the config narrows it",
+    )
 
     dry = over.add_mutually_exclusive_group()
     dry.add_argument(
@@ -174,6 +208,9 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "reap_session_cap": args.reap_session_cap,
         "max_concurrent_sessions": args.max_concurrent_sessions,
         "checks_wait_seconds": args.checks_wait_seconds,
+        "checks_spawn_wait_seconds": args.checks_spawn_wait_seconds,
+        "review_task_miss_ttl_polls": args.review_task_miss_ttl_polls,
+        "task_list_self_scope": args.task_list_self_scope,
         "dry_run": args.dry_run,
     }
 
@@ -217,6 +254,14 @@ def main(argv: list[str] | None = None) -> int:
 
         if args.pr:
             owner, repo, number = parse_pr_ref(args.pr)
+            # This mode exists to tell "the search did not find it" apart from
+            # "the decision was no", so it must never be answered by the
+            # negative cache -- a suppressed pass would report "no review task"
+            # without looking, which is precisely the confusion the flag is for.
+            # Re-arming here (rather than plumbing a bypass through `evaluate`)
+            # keeps the poll path with exactly one way in, and costs the daemon
+            # one corpus fetch on a hand-run diagnostic.
+            watcher.state.forget_review_task_miss(f"{owner}/{repo}", number)
             decision = watcher.evaluate(owner, repo, number)
             print(f"\n{args.pr} → {decision.action.value}")
             print(f"  round:  {decision.round}")

{alissa_tools_github_revloop-0.16.16 → alissa_tools_github_revloop-0.18.0}/src/main/alissa/tools/github/revloop/alissa.py

@@ -16,6 +16,72 @@ log = logging.getLogger(__name__)
 # A review task is "open" while it can still receive a verdict.
 OPEN_STATUSES = {"committed", "in_progress", "pending_validation", "todo"}
 
+# -- narrowing the `alissa task list` call (issue #87) ------------------------
+#
+# `list_tasks` is the widest query this daemon issues -- no query string at all,
+# the actor's entire non-terminal corpus, sponsor-union scoped -- and it was the
+# single largest contributor to the Alissa deployment's #1 Database-I/O offender
+# over 2026-08-12..16. Everything below is applied ONLY when the installed CLI
+# advertises it (see Alissa.probe_task_list): an issue's claim about a flag is
+# not evidence, and this daemon turns a non-zero `alissa` exit into a SKIPPED
+# decision, so sending a flag the CLI does not have costs a review.
+
+# Statuses a LIVE review task can hold. Deliberately OPEN_STATUSES itself and
+# not a hand-written list: `is_review_task_for` already rejects every other
+# status client-side, so filtering server-side on exactly this set cannot change
+# which task the daemon resolves -- it only stops shipping the rows over the
+# wire. Any status added to `is_open` is added here by construction.
+TASK_LIST_STATUS_FLAG = "--status"
+TASK_LIST_STATUS_FILTER = ",".join(sorted(OPEN_STATUSES))
+
+# `--self` drops the SPONSOR's corpus and keeps only the calling actor's rows.
+#
+# NOT enabled by default, and the reason is measured rather than cautious. On
+# the live fleet corpus (2026-08-16, 932 non-terminal rows) `--self` removes 36
+# rows, 4% of the payload -- and 3 of the 371 `Review PR ...` tasks in it are
+# among the rows it removes: they are owned by another actor, not by the agent
+# actor whose sessions write the other 368. Review tasks are therefore
+# PREDOMINANTLY actor-owned but not exclusively so, and a review task this call
+# cannot see is a round the daemon cannot count. 4% of the wire is not worth
+# that, so the flag is opt-in per deployment (`task_list_self_scope`).
+TASK_LIST_SELF_FLAG = "--self"
+
+# A lean projection of each row. The daemon keeps only taskNumber/title/status
+# (see `_task_from_row`), so a digest view is pure saving with no semantics --
+# which is why it is adopted whenever it exists and has no knob. It ships in the
+# studio repo separately; until then the probe simply does not find it.
+TASK_LIST_VIEW_FLAG = "--view"
+TASK_LIST_DIGEST_VIEW = "digest"
+
+
+@dataclass(frozen=True)
+class TaskListFlags:
+    """What the installed `alissa task list` advertises in its own help.
+
+    All-False is both the "old CLI" answer and the "the probe could not run"
+    answer, and they are deliberately the same value: each means "make the call
+    the daemon has always made".
+    """
+
+    status: bool = False
+    self_scope: bool = False
+    digest: bool = False
+
+
+def _advertises(helptext: str, flag: str) -> bool:
+    """Whether `flag` appears as an OPTION in a CLI help listing.
+
+    Anchored to the start of a help line (allowing a short alias in front, as in
+    `-h, --help`) so a flag merely NAMED in some other option's prose -- "Pair
+    with --include-shared" is in this very help text -- is not read as an offer
+    of that flag. The trailing guard rejects a longer flag that merely starts
+    with this one (`--self-only` is not `--self`).
+    """
+    return re.search(
+        rf"(?m)^\s*(?:-\w,\s+)?{re.escape(flag)}(?![\w-])", helptext
+    ) is not None
+
+
 # CR6 verdict envelope outcomes.
 VERDICT_APPROVE = "approve"
 VERDICT_REQUEST_CHANGES = "request_changes"
@@ -213,19 +279,156 @@ class TaskDetail:
 
 
 class Alissa:
-    def list_tasks(self) -> list[Task]:
-        """EVERY non-terminal task owned by this actor -- the expensive call.
-
-        `alissa task list` (CLI 0.1.0) exposes no server-side narrowing at all:
-        its only flags are `--json` and `--include-terminal`. Omitting the
-        latter is therefore the whole of the available filtering, and it is
-        already the default here -- validated and cancelled tasks never come
-        back. What remains is the actor's live corpus (hundreds of tasks,
-        ~250 KB), so the daemon's job is to call this RARELY rather than to
-        call it narrowly: see loop._review_task (persisted PR -> task mapping)
-        and loop._pass_task_list (at most one fetch per poll pass).
+    def __init__(self, *, task_list_self_scope: bool = False) -> None:
+        """`task_list_self_scope` opts the list call into `--self`.
+
+        Default OFF, and that default is evidence, not caution -- see
+        TASK_LIST_SELF_FLAG. It is still a knob because ownership is a property
+        of a DEPLOYMENT (who creates its review tasks), not of this code, and an
+        operator who knows their review tasks are all actor-owned should be able
+        to say so.
+        """
+        self._task_list_self_scope = bool(task_list_self_scope)
+        # The probe's answer, memoized for the process; None = not probed yet.
+        # A probe that FAILS is deliberately not memoized (see probe_task_list).
+        self._task_list_flags: "TaskListFlags | None" = None
+        # Set when a narrowed call has been disproved at RUNTIME -- the CLI
+        # advertised a flag whose call then failed or came back empty. From then
+        # on this process makes the plain call, because a list that answers
+        # wrongly is worse than a list that is large: `find_review_task` reads an
+        # empty corpus as "this PR has no review task".
+        self._task_list_narrowing_disabled = False
+
+    # -- the `alissa task list` narrowing probe -----------------------------
+
+    def probe_task_list(self) -> "TaskListFlags":
+        """Which narrowing flags the INSTALLED `alissa task list` advertises.
+
+        Read off the CLI's own `--help`, which is local, tokenless and free.
+        The alternative -- send the flag and fall back when the call fails --
+        cannot tell an unknown flag from an auth hiccup, and this daemon turns a
+        non-zero `alissa` exit into a SKIPPED decision, so a mis-sent flag does
+        not cost a slower call, it costs a REVIEW.
+
+        Probed off the help OUTPUT rather than the exit status on purpose: this
+        CLI is commander-based and answers an unknown *subcommand* by printing
+        the parent help and exiting 0, so "it exited 0" reports every old CLI as
+        capable. (Flags are stricter than subcommands here, but the rule is the
+        same one and there is no reason to keep two.)
+
+        A probe that ANSWERS is memoized for the process -- the CLI cannot
+        change under a running daemon. A probe that FAILS is not: a transient
+        `alissa` failure then degrades one pass instead of pinning the daemon to
+        the widest call until someone restarts it.
+        """
+        if self._task_list_flags is not None:
+            return self._task_list_flags
+        try:
+            helptext = run(["alissa", "task", "list", "--help"], timeout=20)
+        except CommandError as exc:
+            log.warning(
+                "could not probe `alissa task list --help` (%s) — this pass "
+                "lists tasks unnarrowed, as the daemon always did", exc,
+            )
+            return TaskListFlags()
+        except Exception:  # pragma: no cover - defence in depth
+            log.exception("unexpected failure probing `alissa task list --help`")
+            return TaskListFlags()
+
+        flags = TaskListFlags(
+            status=_advertises(helptext, TASK_LIST_STATUS_FLAG),
+            self_scope=_advertises(helptext, TASK_LIST_SELF_FLAG),
+            digest=_advertises(helptext, TASK_LIST_VIEW_FLAG),
+        )
+        self._task_list_flags = flags
+        return flags
+
+    def task_list_argv(self, *, narrow_status: bool = True) -> list[str]:
+        """The narrowest `alissa task list` this CLI actually supports.
+
+        Every addition is probe-gated, so an older CLI -- today's, which offers
+        none of them -- produces exactly the call the daemon has always made.
         """
-        data = run_json(["alissa", "task", "list", "--json"], timeout=90) or []
+        argv = ["alissa", "task", "list", "--json"]
+        if self._task_list_narrowing_disabled:
+            return argv
+        flags = self.probe_task_list()
+        if flags.status and narrow_status:
+            argv += [TASK_LIST_STATUS_FLAG, TASK_LIST_STATUS_FILTER]
+        if flags.self_scope and self._task_list_self_scope:
+            argv.append(TASK_LIST_SELF_FLAG)
+        if flags.digest:
+            argv += [TASK_LIST_VIEW_FLAG, TASK_LIST_DIGEST_VIEW]
+        return argv
+
+    def list_tasks(self, *, narrow_status: bool = True) -> list[Task]:
+        """This actor's live task corpus -- the expensive call.
+
+        `alissa task list` (CLI 0.1.0) exposed no server-side narrowing at all:
+        its only flags were `--json` and `--include-terminal`, and omitting the
+        latter -- already the default -- was the whole of the available
+        filtering. Newer CLIs offer more, so the call is now assembled from a
+        boot-time probe of the installed CLI's help (`task_list_argv`): a status
+        filter covering exactly the statuses a live review task can hold, a lean
+        `--view digest`, and `--self` when the deployment says its review tasks
+        are actor-owned. None of it is required; an absent flag is simply not
+        sent.
+
+        Narrowing is still the SECOND line of defence, not the first. Even a
+        perfectly narrowed call is the actor's whole review-task corpus, so the
+        daemon's job remains to call this RARELY: see loop._review_task (the
+        persisted PR -> task mapping), loop._pass_task_list (at most one fetch
+        per poll pass) and the negative cache behind them (state's
+        `review_task_misses`, which bounds the ONE case where none of those
+        help -- a PR that has no review task at all).
+
+        `narrow_status=False` is for callers that must see review tasks the
+        daemon's own `is_open` predicate would reject (prreview reads a task's
+        verdict envelope after the round is over). It suppresses only the status
+        filter; every other narrowing still applies.
+
+        A narrowed call that FAILS, or that answers with an empty corpus, is
+        retried once unnarrowed and turns the narrowing off for the rest of the
+        process. Both are how a CLI that advertises a flag its API does not
+        serve would present, and either would otherwise read as "this actor has
+        no review tasks" -- which is a skipped review, not a slower one.
+        """
+        argv = self.task_list_argv(narrow_status=narrow_status)
+        plain = ["alissa", "task", "list", "--json"]
+        try:
+            data = run_json(argv, timeout=90) or []
+        except CommandError:
+            if argv == plain:
+                raise
+            log.warning(
+                "`%s` failed — retrying the plain task list and dropping the "
+                "narrowing for this process", " ".join(argv),
+            )
+            self._task_list_narrowing_disabled = True
+            data = run_json(plain, timeout=90) or []
+
+        tasks = self._tasks_from(data)
+        if tasks or argv == plain:
+            return tasks
+
+        # An empty answer from a narrowed call. A genuinely empty corpus is
+        # possible and costs one extra list; a filter the API does not serve
+        # would cost every review this actor owns.
+        log.warning(
+            "`%s` returned no tasks — retrying the plain task list to tell an "
+            "empty corpus from a filter this API does not serve", " ".join(argv),
+        )
+        tasks = self._tasks_from(run_json(plain, timeout=90) or [])
+        if tasks:
+            self._task_list_narrowing_disabled = True
+            log.warning(
+                "the plain task list returned %d task(s) — the narrowed call is "
+                "dropping rows, so this process stops narrowing", len(tasks),
+            )
+        return tasks
+
+    @staticmethod
+    def _tasks_from(data: object) -> list[Task]:
         tasks = []
         for row in data if isinstance(data, list) else []:
             task = _task_from_row(row)

{alissa_tools_github_revloop-0.16.16 → alissa_tools_github_revloop-0.18.0}/src/main/alissa/tools/github/revloop/config.py

@@ -131,6 +131,9 @@ CONFIG_KEYS = (
     "reap_session_cap",
     "max_concurrent_sessions",
     "checks_wait_seconds",
+    "checks_spawn_wait_seconds",
+    "review_task_miss_ttl_polls",
+    "task_list_self_scope",
     "dry_run",
 )
 
@@ -204,6 +207,44 @@ DEFAULT_MAX_CONCURRENT_SESSIONS = 4
 # not of the daemon.
 DEFAULT_CHECKS_WAIT_SECONDS = 30 * 60
 
+# How long an owed round waits for the head's checks to CONCLUDE before its
+# reviewer is queued at all (issue #84). The bound above protects the verdict
+# the DAEMON posts; this one protects the verdict the reviewer SESSION posts,
+# which is the normal path and the one that has no gate anywhere else: on
+# studio #560 a session approved a head 29 seconds before that same head's
+# `test` job failed, and the red PR carried a green approval for two hours. A
+# session that has not started cannot approve early, so the wait is applied to
+# the spawn.
+#
+# 15 minutes, not the 30 above, and the asymmetry is deliberate: this bound is
+# paid as LATENCY on every round of every PR whose checks are running, while the
+# verdict bound is paid only by a round that has already finished reviewing. CI
+# in this fleet concludes in 3-5 minutes, so 15 is several times the normal wait
+# and still bounded well inside one review round. 0 disables the pre-spawn wait
+# entirely -- the round is queued immediately and its directive carries the
+# still-running rollup, which is the directive-only posture.
+DEFAULT_CHECKS_SPAWN_WAIT_SECONDS = 15 * 60
+
+# How many polls a PR with NO review task may be taken on trust before the
+# daemon searches the task corpus for one again (issue #87).
+#
+# The review-task cache can only remember an answer that EXISTS, so a PR with no
+# review task -- a third-party PR, one whose task was validated or retitled --
+# missed it on every pass and paid the widest read this daemon makes for the
+# same answer every time: at a 60s poll, 1,440 full-corpus reads a day from one
+# unmapped PR, forever.
+#
+# 10 is the trade, and the thing being traded is LATENCY, not correctness: a
+# review task created while the window is open is picked up on the next search
+# rather than the next poll, so the cost of the default is up to ten minutes
+# before that PR's round 1 is queued -- against a 99% cut in the reads. Tune it
+# down on a deployment where review tasks appear after their PR does and the
+# wait is felt; tune it up on one where they are created up front.
+#
+# There is no "off" value: the floor is 1 (suppress one poll), because 0 would
+# not disable a cache, it would write rows nothing ever reads.
+DEFAULT_REVIEW_TASK_MISS_TTL_POLLS = 10
+
 
 def default_state_path(workspace_root: Path) -> Path:
     return Path(workspace_root) / ".revloop" / "state.db"
@@ -264,6 +305,28 @@ class Config:
     # first poll that would have posted it.
     checks_wait_seconds: int = DEFAULT_CHECKS_WAIT_SECONDS
 
+    # The bound on holding an owed round's SPAWN while the head's rollup is
+    # still running; see DEFAULT_CHECKS_SPAWN_WAIT_SECONDS. 0 is legal and means
+    # "never hold the spawn": the round is queued at once and told what the
+    # rollup was. The re-check cadence is `poll_interval` -- a held round is
+    # re-decided by the poll like every other owed round, so there is no second
+    # timer to configure.
+    checks_spawn_wait_seconds: int = DEFAULT_CHECKS_SPAWN_WAIT_SECONDS
+
+    # How many polls a PR with no review task is taken on trust before the
+    # corpus is searched again; see DEFAULT_REVIEW_TASK_MISS_TTL_POLLS. Floor 1
+    # -- there is no value that turns the negative cache off.
+    review_task_miss_ttl_polls: int = DEFAULT_REVIEW_TASK_MISS_TTL_POLLS
+
+    # Whether `alissa task list` may be narrowed to THIS actor's own rows
+    # (`--self`), dropping the sponsor's corpus. Off by default because on the
+    # live fleet a small minority of review tasks are NOT owned by the actor the
+    # daemon runs as, and a review task it cannot see is a round it cannot count
+    # -- see alissa.TASK_LIST_SELF_FLAG for the measurement. Turn it on only
+    # where every review task is created by this daemon's own sessions. Ignored
+    # when the installed CLI does not advertise the flag.
+    task_list_self_scope: bool = False
+
     dry_run: bool = False
 
     def __post_init__(self) -> None:
@@ -408,6 +471,30 @@ class Config:
         if checks_wait < 0:
             raise ValueError(f"checks_wait_seconds must be >= 0, got {checks_wait}")
 
+        spawn_wait = int(
+            raw.get("checks_spawn_wait_seconds", cls.checks_spawn_wait_seconds)
+        )
+        if spawn_wait < 0:
+            raise ValueError(
+                f"checks_spawn_wait_seconds must be >= 0, got {spawn_wait}"
+            )
+
+        miss_ttl = int(
+            raw.get("review_task_miss_ttl_polls", cls.review_task_miss_ttl_polls)
+        )
+        if miss_ttl < 1:
+            # Refused rather than clamped: 0 reads as "turn the negative cache
+            # off", but the cache is what bounds the widest read this daemon
+            # makes, and a 0 would keep writing ledger rows nothing consults. An
+            # operator who means "search every poll" has said something the
+            # daemon cannot do, and should hear that at load rather than
+            # discover it in the I/O bill.
+            raise ValueError(
+                f"review_task_miss_ttl_polls must be >= 1 (it is a number of "
+                f"polls to suppress, and there is no value that disables the "
+                f"negative cache), got {miss_ttl}"
+            )
+
         token_env = raw.get("reviewer_token_env")
         if token_env is not None:
             token_env = str(token_env).strip()
@@ -453,6 +540,9 @@ class Config:
             reap_session_cap=session_cap,
             max_concurrent_sessions=max_sessions,
             checks_wait_seconds=checks_wait,
+            checks_spawn_wait_seconds=spawn_wait,
+            review_task_miss_ttl_polls=miss_ttl,
+            task_list_self_scope=bool(raw.get("task_list_self_scope", False)),
             dry_run=bool(raw.get("dry_run", False)),
         )