alissa-tools-github-revloop 0.17.0__tar.gz → 0.19.0__tar.gz

{alissa_tools_github_revloop-0.17.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.19.0}/PKG-INFO

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

{alissa_tools_github_revloop-0.17.0 → alissa_tools_github_revloop-0.19.0}/src/main/alissa/tools/github/revloop/__main__.py

@@ -146,6 +146,32 @@ def build_parser() -> argparse.ArgumentParser:
         "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(
         "--dry-run",
@@ -183,6 +209,8 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "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,
     }
 
@@ -226,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.17.0 → alissa_tools_github_revloop-0.19.0}/src/main/alissa/tools/github/revloop/alissa.py

@@ -16,6 +16,94 @@ 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
+
+
+# How deeply an OPTION may be indented in a commander help listing. Commander
+# puts option names in a fixed left column (two spaces) and wraps each
+# description onto continuation lines indented to the DESCRIPTION column, which
+# is much further right -- 22 in the CLI this daemon ships against. So a small
+# bounded indent is what separates an option from a wrapped description, without
+# depending on the exact description-column width, which varies with the longest
+# option name in the listing.
+#
+# Anchoring merely to line START is not enough, and that was the round-1 finding
+# on PR #88: a description that wraps such that its second line BEGINS with
+# `--status` reads as an offer of `--status`, and 0.1.0's own help already wraps
+# `--self`'s description onto its own line, so the shape is not hypothetical.
+MAX_OPTION_INDENT = 3
+
+
+def _advertises(helptext: str, flag: str) -> bool:
+    """Whether `flag` appears as an OPTION in a CLI help listing.
+
+    Anchored to the option COLUMN (see MAX_OPTION_INDENT), allowing a short alias
+    in front as in `-h, --help`, so a flag merely NAMED in another option's
+    description is not read as an offer of that flag -- whether it is named
+    mid-line ("Pair with --include-shared" is in this very help text) or at the
+    start of a wrapped continuation line. The trailing guard rejects a longer
+    flag that merely starts with this one (`--self-only` is not `--self`).
+
+    The consequence of a false positive is bounded rather than silent -- the flag
+    is sent, `alissa` exits non-zero, and `list_tasks` retries plain -- but it
+    costs a whole-corpus fetch, which is the thing this module is here to stop
+    spending.
+    """
+    return re.search(
+        rf"(?m)^[ \t]{{0,{MAX_OPTION_INDENT}}}(?:-\w,\s+)?{re.escape(flag)}(?![\w-])",
+        helptext,
+    ) is not None
+
+
 # CR6 verdict envelope outcomes.
 VERDICT_APPROVE = "approve"
 VERDICT_REQUEST_CHANGES = "request_changes"
@@ -213,19 +301,163 @@ 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 or self._task_list_narrowing_disabled:
+            # The third clause is the `except` branch above having already
+            # retried `plain`: without it, a retry that legitimately answers an
+            # EMPTY corpus falls into the cross-check below and calls `plain` a
+            # second time -- three subprocess calls where two happened, inside
+            # the change whose purpose is removing whole-corpus fetches -- and
+            # warns about a narrowed call that in fact errored and never
+            # answered (PR #88 round 1).
+            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.17.0 → alissa_tools_github_revloop-0.19.0}/src/main/alissa/tools/github/revloop/config.py

@@ -132,6 +132,8 @@ CONFIG_KEYS = (
     "max_concurrent_sessions",
     "checks_wait_seconds",
     "checks_spawn_wait_seconds",
+    "review_task_miss_ttl_polls",
+    "task_list_self_scope",
     "dry_run",
 )
 
@@ -223,6 +225,26 @@ DEFAULT_CHECKS_WAIT_SECONDS = 30 * 60
 # 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"
@@ -291,6 +313,20 @@ class Config:
     # 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:
@@ -443,6 +479,22 @@ class Config:
                 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()
@@ -489,6 +541,8 @@ class Config:
             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)),
         )
 

{alissa_tools_github_revloop-0.17.0 → alissa_tools_github_revloop-0.19.0}/src/main/alissa/tools/github/revloop/ghclient.py

@@ -112,6 +112,20 @@ _STATUS_CONCLUSIONS = {
 # rather than green -- a partial read cannot support an approve.
 CHECK_RUN_PAGE_LIMIT = 5
 
+# What a fallback-answered rollup says about itself, in the log line and in the
+# `summary` that reaches a verdict body. The Actions API sees only contexts
+# GitHub Actions produced -- a check run posted by a third-party check app is
+# invisible to it, so a fallback rollup could call green a commit whose
+# non-Actions check failed. Every repo this fleet reviews runs Actions-only CI,
+# which is why the fallback is taken at all; the note is how an operator reading
+# "approved on green" can tell that this is the narrower read.
+ACTIONS_FALLBACK_NOTE = "via the Actions API — check-runs forbidden for this credential"
+
+# The workflow-run states that mean "this run has finished". Read exactly like a
+# check run's `status`: anything else is still going, whatever conclusion the
+# payload carries.
+_RUN_COMPLETED = "completed"
+
 # The hidden marker the daemon stamps into every native verdict review it
 # submits, carrying the round it closes. Two jobs, both load-bearing:
 #
@@ -251,17 +265,31 @@ class CheckRollup:
     # from GitHub and reaches loop._abandon_verdict, which proves absence from
     # the PR's commit list rather than trusting the message.
     unreadable: str = ""
+    # True when the contexts came from the Actions API instead of the check-runs
+    # rollup, because the credential cannot read checks. That read is NARROWER
+    # than the one it stands in for (see ACTIONS_FALLBACK_NOTE), so the answer
+    # carries which path produced it everywhere the rollup is reported.
+    via_actions_fallback: bool = False
 
     @property
     def summary(self) -> str:
-        """One log-line description of the rollup."""
+        """One log-line description of the rollup.
+
+        The fallback marker rides on EVERY state, not just green: an operator
+        reading "approved on green" has to be able to see which read path
+        answered, and so does one reading a request_changes that named a job.
+        """
         if self.state == CHECKS_RED:
-            return f"red — failing: {check_names(self.failing)}"
-        if self.state == CHECKS_PENDING:
-            return f"pending — still running: {check_names(self.running)}"
-        if self.state == CHECKS_UNKNOWN:
-            return f"unreadable — {self.unreadable or 'no reason recorded'}"
-        return f"green — {self.total} context(s), none failing or running"
+            base = f"red — failing: {check_names(self.failing)}"
+        elif self.state == CHECKS_PENDING:
+            base = f"pending — still running: {check_names(self.running)}"
+        elif self.state == CHECKS_UNKNOWN:
+            base = f"unreadable — {self.unreadable or 'no reason recorded'}"
+        else:
+            base = f"green — {self.total} context(s), none failing or running"
+        if self.via_actions_fallback:
+            return f"{base} [{ACTIONS_FALLBACK_NOTE}]"
+        return base
 
 
 def check_names(contexts: "tuple[CheckContext, ...]") -> str:
@@ -269,7 +297,37 @@ def check_names(contexts: "tuple[CheckContext, ...]") -> str:
     return ", ".join(c.name for c in contexts) or "none"
 
 
-def rollup_of(contexts: "list[CheckContext]") -> CheckRollup:
+def _completed_conclusion(payload: dict) -> str:
+    """A check run's / workflow job's conclusion, EMPTY unless it finished.
+
+    The one discriminator both read paths share: a payload that is not
+    `completed` carries no conclusion here whatever it says, so "queued",
+    "in_progress", "waiting" and whatever GitHub adds next all read as running
+    -- exactly the states a gate must not mistake for a verdict.
+    """
+    completed = str(payload.get("status") or "").lower() == _RUN_COMPLETED
+    return str(payload.get("conclusion") or "").lower() if completed else ""
+
+
+def _run_order(run_: dict) -> "tuple[int, int]":
+    """How recent a workflow run is, among runs of the same workflow.
+
+    `run_number` is the workflow's own monotonic counter and `id` breaks its
+    ties. A payload missing either sorts LAST (-1), so a malformed entry can
+    never displace a run that identifies itself.
+    """
+    def as_int(value: object) -> int:
+        try:
+            return int(str(value))
+        except (TypeError, ValueError):
+            return -1
+
+    return (as_int(run_.get("run_number")), as_int(run_.get("id")))
+
+
+def rollup_of(
+    contexts: "list[CheckContext]", via_actions_fallback: bool = False
+) -> CheckRollup:
     """Reduce read contexts to a rollup state.
 
     Precedence is failure over running, deliberately: a commit with one job
@@ -289,7 +347,11 @@ def rollup_of(contexts: "list[CheckContext]") -> CheckRollup:
     else:
         state = CHECKS_GREEN
     return CheckRollup(
-        state=state, failing=failing, running=running, total=len(contexts)
+        state=state,
+        failing=failing,
+        running=running,
+        total=len(contexts),
+        via_actions_fallback=via_actions_fallback,
     )
 
 
@@ -354,6 +416,26 @@ class ReviewerTokenUnset(RuntimeError):
     """`reviewer_token_env` names a variable that is absent or empty."""
 
 
+def _is_authorization_forbidden(exc: CommandError) -> bool:
+    """Is this a 403 about PERMISSION rather than about throttling?
+
+    GitHub answers a secondary rate limit with 403 too, and the two want
+    opposite responses: throttling is waited out, a missing permission never
+    resolves itself. `_api(forbidden_is_rate_limit=False)` already raises
+    RateLimited for anything carrying an explicit throttling marker, so today
+    every CommandError reaching a caller with a 403 in it is an authorization
+    fact. The markers are re-checked anyway rather than inherited from that
+    contract, because what this answer decides is whether to answer the gate
+    from a NARROWER source -- and doing that for a condition that clears itself
+    in seconds is the wrong trade in the one component whose job is to fail
+    closed.
+    """
+    blob = (exc.stderr or "").lower()
+    if any(marker in blob for marker in RATE_LIMIT_MARKERS):
+        return False
+    return "403" in blob
+
+
 class TruncatedListing(RuntimeError):
     """A paged listing exceeded its page bound, so absence cannot be inferred."""
 
@@ -659,13 +741,37 @@ class GitHub:
         is dropped rather than read as "something is running" -- otherwise every
         approve on every Actions-only repo would hold until the wait bound.
 
+        A check-runs read that answers an authorization 403 does NOT stop here.
+        A fine-grained PAT cannot hold GitHub's `Checks` permission at all, so
+        on such a deployment that 403 is permanent and CHECKS_UNKNOWN would mean
+        no round can ever approve, on any repo, forever. The same credential's
+        `Actions: Read` answers for the same commit, so the rollup is read
+        through `_actions_contexts` instead and the answer is LABELLED as the
+        narrower read it is. Everything else about the failure handling is
+        unchanged: a 403 from the Actions API too, a TruncatedListing from
+        either listing, or any other error is still CHECKS_UNKNOWN, and
+        RateLimited still propagates.
+
         Never raises except RateLimited (which run_forever's backoff owns): an
         unreadable rollup is a CHECKS_UNKNOWN answer the caller can hold on, not
         a reason to abort a poll pass that has other PRs to decide.
         """
         contexts: list[CheckContext] = []
+        fallback = False
         try:
-            contexts.extend(self._check_runs(owner, repo, sha))
+            try:
+                contexts.extend(self._check_runs(owner, repo, sha))
+            except CommandError as exc:
+                if not _is_authorization_forbidden(exc):
+                    raise
+                log.warning(
+                    "%s/%s %s: check-runs is forbidden for this credential — "
+                    "reading CI %s instead (%s)",
+                    owner, repo, sha[:8], ACTIONS_FALLBACK_NOTE,
+                    str(exc)[:200],
+                )
+                contexts.extend(self._actions_contexts(owner, repo, sha))
+                fallback = True
             contexts.extend(self._commit_statuses(owner, repo, sha))
         except RateLimited:
             raise
@@ -675,9 +781,11 @@ class GitHub:
             return CheckRollup(
                 CHECKS_UNKNOWN, unreadable=f"{type(exc).__name__}: {exc}"[:300]
             )
-        return rollup_of(contexts)
+        return rollup_of(contexts, via_actions_fallback=fallback)
 
-    def _rollup_listing(self, path: str, key: str, what: str) -> list[dict]:
+    def _rollup_listing(
+        self, path: str, key: str, what: str, params: "tuple[str, ...]" = ()
+    ) -> list[dict]:
         """Page ONE rollup listing to completion, or refuse to answer.
 
         Completeness is decided by two signals, and the pair is the point --
@@ -701,11 +809,17 @@ class GitHub:
         30 successes and called a red head green -- and the direction has to be
         "cannot answer", never "nothing failing in what I got".
 
+        `params` are extra `-f key=value` query fields for endpoints that need
+        one (`actions/runs` is per-commit only via `head_sha=`), carried through
+        every page so the filter cannot silently drop off the second one.
+
         `forbidden_is_rate_limit=False` for the same reason `submit_review`
         passes it: a 403 here is an authorization fact about the deployment (a
         credential without `checks: read`) with its own handling one layer up,
         and collapsing it into RateLimited would abort the whole poll pass and
         double run_forever's backoff instead of degrading this one verdict.
+        That handling is now `check_rollup`'s Actions fallback, which is why the
+        CommandError has to arrive intact rather than as RateLimited.
         """
         out: list[dict] = []
         total: int | None = None
@@ -719,6 +833,7 @@ class GitHub:
                     f"per_page={PER_PAGE}",
                     "-f",
                     f"page={page}",
+                    *[arg for param in params for arg in ("-f", param)],
                     forbidden_is_rate_limit=False,
                 )
                 or {}
@@ -754,18 +869,119 @@ class GitHub:
         )
         out: list[CheckContext] = []
         for run_ in runs:
-            completed = str(run_.get("status") or "").lower() == "completed"
             out.append(
                 CheckContext(
                     name=str(run_.get("name") or "unnamed check"),
-                    conclusion=(
-                        str(run_.get("conclusion") or "").lower() if completed else ""
-                    ),
+                    conclusion=_completed_conclusion(run_),
                     url=str(run_.get("html_url") or run_.get("details_url") or ""),
                 )
             )
         return out
 
+    def _actions_contexts(self, owner: str, repo: str, sha: str) -> list[CheckContext]:
+        """The commit's CI as GitHub ACTIONS sees it -- the fallback read.
+
+        Taken only when the check-runs rollup answered an authorization 403.
+        GitHub does not offer the `Checks` permission on fine-grained PATs at
+        all (community discussion 129512), so on a fine-grained-PAT deployment
+        that read is not "sometimes unavailable", it is a permanent dead end:
+        `check_rollup` degrades to CHECKS_UNKNOWN forever and no round can ever
+        approve. The same credential's `Actions: Read` answers 200 for the same
+        commit's CI, one layer lower down -- workflow runs, and each run's jobs.
+
+        The jobs, not the runs, are the contexts: a job maps one-to-one onto the
+        check run GitHub would have published for it (same name, same status,
+        same conclusion), so `rollup_of` judges the fallback answer under
+        exactly the rules it judges the real one under, including `skipped` and
+        `neutral` passing for a path-filtered matrix.
+
+        What this read CANNOT see is any check run posted by a third-party check
+        app; see ACTIONS_FALLBACK_NOTE for why that is accepted here and how the
+        answer says so.
+
+        COST: this path costs one call for the run listing plus one per kept
+        workflow, where the read it replaces cost one. It is taken only where
+        the alternative is a permanent CHECKS_UNKNOWN, and only on the rollup
+        reads the caller already decided to make -- the gate's existing
+        per-round caching is what bounds how often that is. On this fleet's
+        repos (one or two workflows per commit) it is two or three calls.
+        """
+        runs = self._rollup_listing(
+            f"repos/{owner}/{repo}/actions/runs",
+            "workflow_runs",
+            "workflow runs",
+            params=(f"head_sha={sha}",),
+        )
+        out: list[CheckContext] = []
+        for run_ in self._latest_run_per_workflow(runs):
+            out.extend(self._run_contexts(owner, repo, run_))
+        return out
+
+    @staticmethod
+    def _latest_run_per_workflow(runs: list[dict]) -> list[dict]:
+        """One run per workflow: the most recent.
+
+        A sha carries more than one run of the same workflow whenever it was
+        triggered more than once -- a re-run shares its run id, but a distinct
+        trigger event (a `push` and a `pull_request` on the same commit, a
+        workflow re-dispatched by hand) creates a distinct run. Reading all of
+        them would judge the commit on a superseded attempt: an earlier failed
+        run whose re-trigger passed would hold the head red forever.
+
+        Recency is `run_number` then `id`, both monotonic per workflow and both
+        integers -- deliberately not a timestamp string, which is the field a
+        re-run rewrites. A run with no `workflow_id` is not grouped with
+        anything (its position in the listing is its key), because collapsing
+        unidentified runs together would silently drop contexts.
+        """
+        latest: dict[object, dict] = {}
+        for index, run_ in enumerate(runs):
+            workflow_id = run_.get("workflow_id")
+            key: object = (
+                ("workflow", workflow_id)
+                if workflow_id is not None
+                else ("unidentified", index)
+            )
+            current = latest.get(key)
+            if current is None or _run_order(run_) >= _run_order(current):
+                latest[key] = run_
+        return list(latest.values())
+
+    def _run_contexts(self, owner: str, repo: str, run_: dict) -> list[CheckContext]:
+        """One workflow run's jobs as contexts, or the run itself if it has none.
+
+        A run exposes no jobs while it is still queued, and the empty list must
+        never read as "nothing failing here". So a run with no readable jobs
+        contributes ITSELF as one context, under the same completed/conclusion
+        rule: not completed reads as running (the case the gate exists for), and
+        a completed run with no jobs is judged on its own conclusion rather than
+        vanishing from the rollup.
+        """
+        run_id = run_.get("id")
+        run_name = str(run_.get("name") or run_.get("display_title") or "workflow run")
+        run_url = str(run_.get("html_url") or "")
+        jobs: list[dict] = []
+        if run_id is not None:
+            jobs = self._rollup_listing(
+                f"repos/{owner}/{repo}/actions/runs/{run_id}/jobs", "jobs", "jobs"
+            )
+        if not jobs:
+            return [
+                CheckContext(
+                    name=run_name,
+                    conclusion=_completed_conclusion(run_),
+                    url=run_url,
+                )
+            ]
+        return [
+            CheckContext(
+                name=str(job.get("name") or "unnamed job"),
+                conclusion=_completed_conclusion(job),
+                url=str(job.get("html_url") or run_url),
+            )
+            for job in jobs
+        ]
+
     def _commit_statuses(self, owner: str, repo: str, sha: str) -> list[CheckContext]:
         """The commit's legacy statuses, one context each.
 

{alissa_tools_github_revloop-0.17.0 → alissa_tools_github_revloop-0.19.0}/src/main/alissa/tools/github/revloop/loop.py

@@ -586,6 +586,25 @@ _CHECKS_BEFORE_VERDICT = (
     "never conclude within that bound, do NOT approve either — request_changes, "
     "saying plainly that the checks at that sha never settled; the next round can "
     "approve the same code on a green head. "
+    "(2b) IF THE CHECK-RUNS READ IS FORBIDDEN — a `403 Resource not accessible "
+    "by personal access token` means this deployment's credential cannot read "
+    "check runs at all, NOT that the commit has no checks: never approve on it. "
+    "Read the same commit's CI through the Actions API instead, which the same "
+    "credential can read: `gh api "
+    "'repos/<org>/<repo>/actions/runs?head_sha=<sha>' --jq "
+    "'.workflow_runs[]|[.id,.name,.status,.conclusion,.html_url]|@tsv'`, keep "
+    "only the MOST RECENT run per workflow (one sha can carry several runs of "
+    "the same workflow, and a superseded attempt is not the answer), then for "
+    "each kept run `gh api repos/<org>/<repo>/actions/runs/<run_id>/jobs --jq "
+    "'.jobs[]|[.name,.status,.conclusion,.html_url]|@tsv'`. Judge those jobs "
+    "under exactly the rules above — concluded and none failed to approve, wait "
+    "and re-read within the same bound while any is still running, "
+    "request_changes naming the job and linking its run if one failed. A run "
+    "that is not `completed` and exposes no jobs yet is still running, never "
+    "green. Say in your verdict that the rollup was read through the Actions "
+    "API: it sees only Actions-produced contexts, so an operator has to be able "
+    "to tell that read from the full one. If the Actions read is forbidden too, "
+    "the rollup is unreadable — do not approve. "
 )
 
 # The floor under the wait the directive asks a session to observe. The bound
@@ -621,9 +640,24 @@ MIN_SESSION_CHECKS_WAIT_SECONDS = 5 * 60
 # contexts x item, leaving the character cap as the backstop for a pathological
 # item rather than the thing that decides how many jobs a reviewer hears about.
 # 200 fits a GitHub Actions run URL (~105) plus a generous name and conclusion.
+# The marker an item cut to fit carries. Defined here, next to the caps, because
+# the derived budget below has to count it: it is part of what a full list of
+# capped items actually measures (PR #85 round-3 nit).
+DIRECTIVE_ITEM_TRUNCATED = "…"
+
 MAX_DIRECTIVE_ITEM_CHARS = 200
 MAX_DIRECTIVE_CONTEXTS = 10
-MAX_DIRECTIVE_DATA_CHARS = MAX_DIRECTIVE_CONTEXTS * MAX_DIRECTIVE_ITEM_CHARS
+# The widest list the COUNT cap can pass, exactly: every item at its cap, every
+# one of them carrying the cut marker, joined by "; ". The naive
+# contexts x item was 28 characters short of that, so ten items at the item cap
+# tripped the character backstop and nine were kept -- the character budget
+# deciding how many jobs a reviewer hears about, which is the inversion the
+# round-2 major was about, surviving at an input no real rollup produces. Stated
+# as arithmetic so it stays true if either cap is retuned.
+MAX_DIRECTIVE_DATA_CHARS = (
+    MAX_DIRECTIVE_CONTEXTS * (MAX_DIRECTIVE_ITEM_CHARS + len(DIRECTIVE_ITEM_TRUNCATED))
+    + (MAX_DIRECTIVE_CONTEXTS - 1) * len("; ")
+)
 
 # The fence around interpolated data. A lead-in alone says where the data starts
 # and nothing says where it stops -- and in all three clauses the span is
@@ -642,7 +676,24 @@ DATA_CLOSE = "⟦end data⟧"
 # (PR #85 round-2 minor, with a working repro). Newlines and control characters
 # go for the same reason -- a fresh line reads as fresh prose -- and the fence's
 # own brackets go so the END marker cannot be forged.
-_DIRECTIVE_STRIP_RE = re.compile("[`\x00-\x1f\x7f" + re.escape("⟦⟧") + "]")
+#
+# The class is deliberately NOT ASCII-only, because the input is not: the first
+# version stripped C0 and left U+0085, U+2028 and U+2029, every one of which
+# renders as a line break, so the mitigation applied to one ENCODING of "start a
+# fresh line" rather than to the effect (PR #85 round-3 minor). C1 goes with
+# them, and so do the bidi controls -- U+202A-E and U+2066-9 reorder the rendered
+# run, which is the same class of "what is displayed is not what the string
+# says".
+# Written as escapes, never as the characters themselves: every one of them
+# is invisible or reorders its neighbours in an editor, which is precisely
+# why they are stripped.
+_DIRECTIVE_STRIP_RE = re.compile(
+    "[`\\x00-\\x1f\\x7f-\\x9f\\u2028\\u2029\\u202a-\\u202e\\u2066-\\u2069"
+    # The fence's BRACKETS only -- putting the whole markers in a character
+    # class would strip their letters out of every check name too.
+    + re.escape("⟦⟧")
+    + "]"
+)
 
 # Says out loud that what follows is data, and exactly where it ends. A session
 # reading its directive has no other way to tell the daemon's instructions from a
@@ -711,12 +762,11 @@ CHECKS_AT_SPAWN_UNREADABLE = (
 # quotes mean something. Inside ⟦data⟧ the fence is the boundary.
 CHECKS_AT_SPAWN_FAILING = "{name} ({conclusion}){url}"
 
-# What the list becomes once the count cap has bitten, and what one over-long
-# item becomes. Both are visible on purpose: every truncation in this module has
+# What the list becomes once the count cap has bitten. Visible on purpose, like
+# the per-item marker beside the caps above: every truncation in this module has
 # to be readable in the directive, or a reviewer session cannot tell "these are
 # the failing checks" from "these are some of them".
 DIRECTIVE_DATA_TRUNCATED = " …(truncated: {dropped} more)"
-DIRECTIVE_ITEM_TRUNCATED = "…"
 
 
 def directive_text(value: str) -> str:
@@ -1350,7 +1400,9 @@ class ReviewWatcher:
         self.github = github or GitHub(
             config.reviewer_login, token_env=config.reviewer_token_env
         )
-        self.alissa = alissa or Alissa()
+        self.alissa = alissa or Alissa(
+            task_list_self_scope=config.task_list_self_scope
+        )
         self.state = state or State(config.state_db)
         # (repo, number, comment id) of every re-entry directive already
         # refused in this process -- see _log_ignored_ack.
@@ -1476,9 +1528,29 @@ class ReviewWatcher:
           unreadable task is NOT a disproof, so the row survives a transient
           CLI failure and the pass just degrades to the old behaviour.
 
+        ...and a FOURTH outcome that is none of those (issue #87): no cached ref
+        and a recent search that already found nothing. The three above bound
+        the cost of a PR whose review task EXISTS; a PR that has none missed
+        every one of them on every pass and paid the corpus fetch for the same
+        answer forever -- 1,440 whole-corpus reads a day, per unmapped PR, at a
+        60s poll. So a completed search that finds nothing is recorded as such
+        and taken on trust for `review_task_miss_ttl_polls` further polls.
+
+        That negative answer is consulted ONLY when there is no cached ref at
+        all, which is what keeps it from ever competing with the three outcomes
+        above: a cached ref that reads and matches never reaches it, a cached
+        ref that is DISPROVED must re-search on the strength of that fresh
+        disproof (and only records a miss if that search also comes up empty),
+        and a cached ref that could not be READ must fall back to the search,
+        because an unreadable task is not a wrong one.
+
         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.
+        answer "no review task" unless a successful search actually said so --
+        including the negative cache, which is written only from a search that
+        RAN and returned nothing, and which suppresses a pass only when the
+        ledger accepted the write that spends it (see
+        State.consume_review_task_miss).
 
         TWO consequences of resolving from cache, both accepted rather than
         overlooked (PR #68 round 1):
@@ -1517,6 +1589,24 @@ class ReviewWatcher:
                     "an unreadable task is not a wrong one)",
                     pr.slug, cached,
                 )
+        elif self._pass_tasks is None and self.state.consume_review_task_miss(
+            pr.full_name, pr.number
+        ):
+            # The negative answer is worth having only while the corpus has NOT
+            # been fetched this pass. Once the memo is populated -- some earlier
+            # PR of this pass re-armed and paid for it -- answering from the
+            # ledger saves nothing at all (the search is a list comprehension
+            # over rows already in memory) and still spends the window, so a
+            # review task created since this PR's last search would stay
+            # invisible for up to `review_task_miss_ttl_polls` more polls with
+            # the evidence for it sitting right there. Order-dependent within a
+            # pass, and therefore a partial win -- but never a read added, and
+            # sometimes a whole window of latency removed (PR #88 round 1).
+            log.debug(
+                "%s: a recent search found no review task and the answer has "
+                "polls left — skipping the corpus fetch this pass", pr.slug,
+            )
+            return ResolvedTask(task=None)
 
         task = self.alissa.find_review_task(
             pr.owner, pr.repo, pr.number, tasks=self._pass_task_list()
@@ -1526,6 +1616,29 @@ 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)
+            # ...and it is the ONLY thing this daemon may record a negative
+            # answer from. Recorded here rather than at the call sites because
+            # this is the one place that knows the search RAN: a search that
+            # raised never reaches this line at all (it propagates out of
+            # `_pass_task_list` and the pass turns it into one PR's SKIPPED),
+            # so a transient CLI failure can never buy itself a window of
+            # silence.
+            #
+            # KNOWN GAP, not reachable on any shipping CLI (PR #88 round 1): a
+            # search "ran" is only as good as the corpus it ran over. The two
+            # runtime disproofs in `Alissa.list_tasks` catch a narrowed call that
+            # FAILS and one that answers EMPTY; neither catches one that answers
+            # NON-EMPTY but INCOMPLETE -- a `--status` the API accepts and serves
+            # partially, say. The search then legitimately finds nothing and this
+            # line makes that wrong answer STICKY for a window, where before the
+            # negative cache it was wrong but self-correcting on the next pass.
+            # No CLI generation offers `--status` or `--view digest` yet, so
+            # nothing can reach it today; the first one that does must prove
+            # itself before this row may be trusted. See the operator's-gate
+            # checklist on PR #88.
+            self.state.record_review_task_miss(
+                pr.full_name, pr.number, self.config.review_task_miss_ttl_polls
+            )
             return ResolvedTask(task=None)
 
         self.state.record_review_task(pr.full_name, pr.number, task.ref)
@@ -3863,6 +3976,19 @@ class ReviewWatcher:
                 f"not an Alissa Code Workspace yet (`alissa code workspace init`)"
             )
 
+        # The task-list narrowing probe (issue #87), run at BOOT so the answer
+        # is memoized before the first pass and, more usefully, so the call the
+        # daemon will actually make is in the startup log next to the config
+        # that shaped it. Nothing here can fail the daemon: an unprobeable CLI
+        # degrades to the unnarrowed call and says so.
+        log.info("task list: %s", " ".join(self.alissa.task_list_argv()))
+        if self.config.task_list_self_scope and not self.alissa.probe_task_list().self_scope:
+            warnings.append(
+                "task_list_self_scope is set but the installed `alissa` CLI "
+                "does not advertise `task list --self` — the task list is not "
+                "actor-scoped; upgrade the CLI or drop the key"
+            )
+
         if not self.config.dry_run and not self.alissa.worker_running():
             warnings.append(
                 "`alissa worker` does not appear to be running — queued reviewer "
@@ -4072,14 +4198,14 @@ class ReviewWatcher:
         # 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). 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
+        # it may still take are the snapshot and the review-task cache, both
+        # halves (`_review_task` runs in dry-run and records, forgets and spends
+        # both mappings and misses) -- all classified by this module as
+        # best-effort telemetry, all absorbed by _write_telemetry, and none 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.

{alissa_tools_github_revloop-0.17.0 → alissa_tools_github_revloop-0.19.0}/src/main/alissa/tools/github/revloop/prreview.py

@@ -74,11 +74,17 @@ def _review_task_ref(alissa: Alissa, owner: str, repo: str, number: int) -> str
 
     Deliberately not `Alissa.find_review_task` (which filters to open tasks): we
     still want the ref just after the task is validated, to read its verdict.
+    `narrow_status=False` says the same thing to the LIST call for the same
+    reason -- the daemon's server-side status filter is exactly its `is_open`
+    set, and narrowing by it here would re-impose the filter this function
+    exists to avoid.
     """
     pattern = re.compile(
         rf"^Review PR\s+{re.escape(owner)}/{re.escape(repo)}#{number}\b", re.IGNORECASE
     )
-    matches = [t for t in alissa.list_tasks() if pattern.match(t.title)]
+    matches = [
+        t for t in alissa.list_tasks(narrow_status=False) if pattern.match(t.title)
+    ]
     return matches[0].ref if matches else None
 
 

{alissa_tools_github_revloop-0.17.0 → alissa_tools_github_revloop-0.19.0}/src/main/alissa/tools/github/revloop/state.py

@@ -171,6 +171,33 @@ CREATE TABLE IF NOT EXISTS review_tasks (
     PRIMARY KEY (repo, number)
 );
 
+-- The NEGATIVE half of the mapping above: PRs a completed search found NO open
+-- review task for (issue #87). The table above can only remember an answer that
+-- exists, so a PR without one missed the cache on every single pass and paid the
+-- full corpus fetch for it -- 1,440 whole-corpus reads a day from one unmapped
+-- PR, forever, because nothing about "there is no review task" ever changes on
+-- its own. That is the widest read this daemon makes, on the path that repeats
+-- most often.
+--
+-- `polls_left` is a COUNTDOWN, not a deadline: each pass that consults the row
+-- burns one and the row is deleted at zero, so the suppression is measured in
+-- polls of THIS PR (the unit the knob is written in) rather than in wall-clock
+-- or in global passes -- a PR nobody is requesting a review on burns nothing.
+-- It also makes the row self-cleaning, which matters because a negative answer
+-- must never outlive its own re-check.
+--
+-- Best-effort like `review_tasks`, and fail-open in the same direction: a row
+-- that cannot be written or decremented simply does not suppress anything, and
+-- the pass pays the fetch it always paid. The one thing this table may never do
+-- is answer "no review task" for longer than it was asked to.
+CREATE TABLE IF NOT EXISTS review_task_misses (
+    repo       TEXT    NOT NULL,
+    number     INTEGER NOT NULL,
+    polls_left INTEGER NOT NULL,
+    first_at   INTEGER NOT NULL,
+    PRIMARY KEY (repo, number)
+);
+
 -- One row per (PR, round, head) whose reviewer the pre-spawn CI gate has held
 -- back, stamped when the wait BEGAN (issue #84). That stamp is the only thing
 -- the gate needs to remember: everything else about the decision -- what is
@@ -1019,8 +1046,147 @@ class State:
             "(repo, number, task_ref, resolved_at) VALUES (?,?,?,?)",
             (repo, number, task_ref, int(time.time())),
         )
+        # A mapping DISPROVES an outstanding negative answer, so the two tables
+        # can never both speak for one PR. Dropped in the same transaction as
+        # the mapping rather than by a separate call: a negative row that
+        # survived a recorded mapping would keep the suppression running against
+        # a PR the daemon can now resolve by ref -- which is not a wasted fetch
+        # (the cached path skips the corpus anyway) but a stale claim in the
+        # ledger, and it is the "mapping recorded mid-TTL re-arms" contract.
+        self._db.execute(
+            "DELETE FROM review_task_misses WHERE repo=? AND number=?",
+            (repo, number),
+        )
+        self._db.commit()
+
+    # -- the NEGATIVE half: PRs with no review task at all (issue #87) ------
+
+    def record_review_task_miss(self, repo: str, number: int, polls: int) -> bool:
+        """Remember that a COMPLETED search found no review task for this PR.
+
+        `polls` is how many later passes may take that answer on trust before
+        the search is re-armed. REPLACE, not IGNORE: every fresh disproof
+        restarts the countdown, which is what makes a run of misses cost one
+        fetch per window rather than one per pass.
+
+        Only ever called on a search that RAN and found nothing -- never on a
+        failed one. A miss recorded because the CLI hiccuped would suppress the
+        retry that was supposed to correct it, which is the one way this table
+        could cost a review instead of a read.
+
+        Best-effort, like every write in this class's optimization half: a
+        `polls < 1` request records nothing (there is no window to remember),
+        and a database error records nothing either. Both mean the next pass
+        searches, which is what the daemon did before this table existed.
+        """
+        if polls < 1:
+            return False
+        return self._write_telemetry(
+            lambda: self._replace_review_task_miss(repo, number, polls),
+            "review-task miss write",
+        )
+
+    def _replace_review_task_miss(self, repo: str, number: int, polls: int) -> None:
+        self._db.execute(
+            "INSERT OR REPLACE INTO review_task_misses "
+            "(repo, number, polls_left, first_at) VALUES (?,?,?,?)",
+            (repo, number, int(polls), int(time.time())),
+        )
         self._db.commit()
 
+    def consume_review_task_miss(self, repo: str, number: int) -> bool:
+        """Spend one poll of this PR's negative answer. True = skip the search.
+
+        True is the ONLY answer that suppresses a corpus fetch, and it is
+        returned only when a live row was read AND its countdown was
+        successfully decremented. That coupling is the read-only-ledger
+        contract: on a volume that flips read-only after a row was written, the
+        row is still readable and would otherwise say "skip" forever, because
+        nothing could ever burn it down. Requiring the write means such a ledger
+        answers False every pass -- one fetch per pass, exactly today's
+        behaviour -- rather than silently answering "no review task" until
+        someone restarts the daemon.
+
+        False therefore means all of: no row, an exhausted row, an unreadable
+        database, and a decrement that would not persist. The caller may
+        conclude nothing from it beyond "search for it", which is what it did
+        unconditionally before this table existed.
+        """
+        try:
+            row = self._db.execute(
+                "SELECT polls_left FROM review_task_misses WHERE repo=? AND number=?",
+                (repo, number),
+            ).fetchone()
+        except sqlite3.DatabaseError as exc:
+            log.warning(
+                "state: review-task miss cache unreadable (%s: %s) — this pass "
+                "resolves %s#%d by searching, as it did before the cache",
+                type(exc).__name__, exc, repo, number,
+            )
+            return False
+        if row is None or int(row["polls_left"]) < 1:
+            # An exhausted row cannot occur through this method (the decrement
+            # deletes at zero) but can through a hand-edited ledger; treat it as
+            # the re-armed state it describes and clear it.
+            if row is not None:
+                self.forget_review_task_miss(repo, number)
+            return False
+        return self._write_telemetry(
+            lambda: self._burn_review_task_miss(repo, number),
+            "review-task miss decrement",
+        )
+
+    def _burn_review_task_miss(self, repo: str, number: int) -> None:
+        """One poll off the countdown, and the row goes when it runs out.
+
+        Both statements in one transaction so a row can never be left claiming a
+        window it has already spent.
+        """
+        self._db.execute(
+            "UPDATE review_task_misses SET polls_left = polls_left - 1 "
+            "WHERE repo=? AND number=?",
+            (repo, number),
+        )
+        self._db.execute(
+            "DELETE FROM review_task_misses WHERE repo=? AND number=? AND polls_left < 1",
+            (repo, number),
+        )
+        self._db.commit()
+
+    def forget_review_task_miss(self, repo: str, number: int) -> bool:
+        """Re-arm the search for this PR now. Best-effort.
+
+        The manual counterpart to the countdown: `--pr` runs it so a one-shot
+        diagnostic always reports what a search would find, never what a
+        suppressed one was told to assume.
+        """
+        return self._write_telemetry(
+            lambda: self._delete_review_task_miss(repo, number),
+            "review-task miss invalidation",
+        )
+
+    def _delete_review_task_miss(self, repo: str, number: int) -> None:
+        self._db.execute(
+            "DELETE FROM review_task_misses WHERE repo=? AND number=?", (repo, number)
+        )
+        self._db.commit()
+
+    def review_task_miss(self, repo: str, number: int) -> "int | None":
+        """Polls left on this PR's negative answer, or None when it has none.
+
+        A read for tests and for an operator poking at the ledger; the decide
+        path uses `consume_review_task_miss`, which is the only caller allowed
+        to act on the answer (it burns a poll for the pass it grants).
+        """
+        try:
+            row = self._db.execute(
+                "SELECT polls_left FROM review_task_misses WHERE repo=? AND number=?",
+                (repo, number),
+            ).fetchone()
+        except sqlite3.DatabaseError:
+            return None
+        return None if row is None else int(row["polls_left"])
+
     def forget_review_task(self, repo: str, number: int) -> bool:
         """Drop a mapping that has been DISPROVED. Best-effort.
 

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

@@ -0,0 +1 @@
+0.19.0

{alissa_tools_github_revloop-0.17.0 → alissa_tools_github_revloop-0.19.0/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.17.0
+Version: 0.19.0
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

@@ -1 +0,0 @@
-0.17.0