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

{alissa_tools_github_revloop-0.17.0/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.17.0
+Version: 0.18.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.18.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.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.17.0 → alissa_tools_github_revloop-0.18.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.18.0}/src/main/alissa/tools/github/revloop/loop.py

@@ -621,9 +621,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 +657,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 +743,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 +1381,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 +1509,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 +1570,12 @@ class ReviewWatcher:
                     "an unreadable task is not a wrong one)",
                     pr.slug, cached,
                 )
+        elif self.state.consume_review_task_miss(pr.full_name, pr.number):
+            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 +1585,16 @@ 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.
+            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 +3932,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 +4154,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.18.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.18.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.18.0/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.18.0

{alissa_tools_github_revloop-0.17.0 → alissa_tools_github_revloop-0.18.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.18.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