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

{alissa_tools_github_revloop-0.16.10/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.16.12}/PKG-INFO

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

{alissa_tools_github_revloop-0.16.10 → alissa_tools_github_revloop-0.16.12}/src/main/alissa/tools/github/revloop/alissa.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import logging
 import re
 from dataclasses import dataclass
+from datetime import datetime
 from pathlib import Path
 
 from .proc import CommandError, run, run_json
@@ -153,29 +154,139 @@ def _title_pattern(owner: str, repo: str, number: int) -> re.Pattern[str]:
     )
 
 
+def is_review_task_for(owner: str, repo: str, number: int, task: "Task") -> bool:
+    """Whether `task` is THE open CR2 review task for this PR.
+
+    The one predicate, shared by the search (`find_review_task`, over a whole
+    task list) and by the cache check (loop._review_task, over a single task
+    read back by ref). They must agree: a cached ref that the search would not
+    have returned is a mapping the daemon has to drop, and a divergence here
+    would either pin a wrong task forever or re-fetch the corpus every pass
+    while disagreeing with itself.
+    """
+    return bool(_title_pattern(owner, repo, number).match(task.title)) and task.is_open
+
+
+def _task_from_row(row: object) -> "Task | None":
+    """One task out of a CLI payload row, or None when it carries no usable ref.
+
+    Shared by the list reader and the single-task reader so both agree on which
+    field is the resolvable ref.
+    """
+    if not isinstance(row, dict):
+        return None
+    # `taskNumber` is the ref the API resolves; `taskSeq` is a display
+    # ordinal and 404s as `TASK-<seq>`.
+    number = row.get("taskNumber")
+    if number is None:
+        return None
+    title = row.get("title")
+    status = row.get("status")
+    return Task(
+        ref=f"TASK-{number}",
+        title=title if isinstance(title, str) else "",
+        status=status if isinstance(status, str) else "",
+    )
+
+
+@dataclass(frozen=True)
+class TaskDetail:
+    """One task as `alissa task get` sees it: the task itself, plus everything
+    the decide path reads off its CR6 verdict evidence.
+
+    All three travel together because they come out of ONE payload. The decide
+    path needs every one of them (is this still the PR's open review task? how
+    many rounds has it recorded? what did the newest round decide?), and
+    `_count_verdicts` and `_newest_verdict` are deliberately written as mirrors
+    over the same evidence array -- so reading them apart would mean fetching
+    and re-parsing the same task two and three times per PR per poll, which is
+    the exact cost this whole path exists to stop paying.
+
+    `verdict` is None when no envelope on the task parses -- the normal round-1
+    case, indistinguishable here from "no verdict of record yet", which is what
+    the caller wants it to mean anyway.
+    """
+
+    task: Task
+    verdicts: int
+    verdict: "str | None"
+
+
 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).
+        """
         data = run_json(["alissa", "task", "list", "--json"], timeout=90) or []
         tasks = []
-        for row in data:
-            # `taskNumber` is the ref the API resolves; `taskSeq` is a display
-            # ordinal and 404s as `TASK-<seq>`.
-            number = row.get("taskNumber")
-            if number is None:
-                continue
-            tasks.append(
-                Task(
-                    ref=f"TASK-{number}",
-                    title=row.get("title", ""),
-                    status=row.get("status", ""),
-                )
-            )
+        for row in data if isinstance(data, list) else []:
+            task = _task_from_row(row)
+            if task is not None:
+                tasks.append(task)
         return tasks
 
-    def find_review_task(self, owner: str, repo: str, number: int) -> Task | None:
-        """CR2: exactly one review task per PR. Reuse it across rounds (CR7)."""
-        pattern = _title_pattern(owner, repo, number)
-        matches = [t for t in self.list_tasks() if pattern.match(t.title) and t.is_open]
+    def get_task(self, ref: str) -> "TaskDetail | None":
+        """Read ONE task by ref: title, status and verdict count in one call.
+
+        This is what makes a cached PR -> review-task mapping usable. Resolving
+        the task by ref costs a single-task fetch; resolving it by searching
+        titles costs the actor's entire corpus, which is the read this whole
+        path exists to stop paying every poll.
+
+        None means "could not be read" and NOTHING more -- a deleted task and a
+        transient CLI failure are indistinguishable from here, so a caller must
+        not treat None as proof that a cached mapping is wrong (see
+        loop._review_task, which keeps the row and falls back to the search).
+        Never raises: the daemon polls forever and this runs inside every pass.
+        """
+        try:
+            data = run_json(["alissa", "task", "get", ref, "--json"], timeout=90)
+        except CommandError as exc:
+            log.warning("could not read task %s: %s", ref, exc)
+            return None
+        except Exception:  # pragma: no cover - defence in depth
+            log.exception("unexpected failure reading task %s", ref)
+            return None
+
+        try:
+            task = _task_from_row(data)
+            if task is None:
+                return None
+            return TaskDetail(
+                task=task,
+                verdicts=self._count_verdicts(data),
+                verdict=self._newest_verdict(data),
+            )
+        except Exception:  # pragma: no cover - defence in depth
+            log.exception("could not parse task payload for %s", ref)
+            return None
+
+    def find_review_task(
+        self,
+        owner: str,
+        repo: str,
+        number: int,
+        *,
+        tasks: "list[Task] | None" = None,
+    ) -> Task | None:
+        """CR2: exactly one review task per PR. Reuse it across rounds (CR7).
+
+        `tasks` supplies a corpus the caller already fetched, so several PRs
+        missing the cache in the SAME poll pass share one list call instead of
+        issuing an identical one each (the observed 2-4 same-second bursts).
+        Omitted -- the console-script path, and any caller with no pass to
+        scope to -- fetches its own.
+        """
+        pool = self.list_tasks() if tasks is None else tasks
+        matches = [t for t in pool if is_review_task_for(owner, repo, number, t)]
 
         if not matches:
             return None
@@ -218,6 +329,44 @@ class Alissa:
             log.exception("could not parse verdict evidence for %s", task_ref)
             return None
 
+    @staticmethod
+    def _created_key(value: object) -> tuple[int, float]:
+        """One evidence item's `createdAt`, as a sortable stamp.
+
+        `alissa task get --json` dates evidence with epoch MILLISECONDS as an
+        int; the API's other surfaces (and hand-written fixtures) use an ISO-8601
+        string. Both are normalised here to one float, because the previous key
+        -- `created if isinstance(created, str) else ""` -- collapsed every real
+        item to the empty string, leaving `max` to keep the FIRST element of an
+        all-equal set. Evidence comes back oldest-first, so on live data the
+        OLDEST verdict won: a PR whose round 1 was request_changes and round 2
+        approve never converged through the envelope branch (TASK-194837655).
+
+        Normalising rather than widening the isinstance is deliberate: a task
+        carrying both shapes would produce `(str, ...)` and `(int, ...)` keys
+        that raise TypeError the moment sorting compared them.
+
+        Returns `(has_stamp, seconds)`. An absent or unparseable stamp is
+        `(0, 0.0)` and sorts FIRST, preserving the old rule that a dated
+        envelope always beats one that lost its timestamp.
+        """
+        if isinstance(value, bool):  # bool is an int; never a timestamp
+            return (0, 0.0)
+        if isinstance(value, (int, float)):
+            seconds = float(value)
+            # Milliseconds, by magnitude: 1e11 seconds is the year 5138, while
+            # 1e11 milliseconds is 1973 -- so anything above it is ms, and a
+            # task holding both units still orders correctly.
+            if abs(seconds) > 1e11:
+                seconds /= 1000.0
+            return (1, seconds)
+        if isinstance(value, str) and value:
+            try:
+                return (1, datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp())
+            except ValueError:
+                return (0, 0.0)
+        return (0, 0.0)
+
     @staticmethod
     def _newest_verdict(payload: object) -> str | None:
         """Pick the newest parseable verdict out of a task's evidence array.
@@ -231,8 +380,8 @@ class Alissa:
         if not isinstance(evidence, list):
             return None
 
-        found: list[tuple[str, str]] = []
-        for item in evidence:
+        found: list[tuple[tuple[int, float], int, str]] = []
+        for index, item in enumerate(evidence):
             if not isinstance(item, dict):
                 continue
             title = item.get("title")
@@ -242,18 +391,21 @@ class Alissa:
                     continue
                 match = _VERDICT_RE.search(blob)
                 if match:
-                    created = item.get("createdAt")
                     found.append(
-                        (created if isinstance(created, str) else "", match.group(1).lower())
+                        (Alissa._created_key(item.get("createdAt")),
+                         index,
+                         match.group(1).lower())
                     )
                     break
 
         if not found:
             return None
-        # ISO-8601 timestamps sort lexicographically. Undated evidence sorts
-        # first (empty string), so a dated envelope always wins over one that
-        # lost its timestamp.
-        return max(found, key=lambda pair: pair[0])[1]
+        # Newest stamp wins; undated evidence sorts first, so a dated envelope
+        # always beats one that lost its timestamp (see _created_key). The
+        # append INDEX breaks ties: evidence comes back oldest-first, so two
+        # envelopes sharing a stamp resolve to the later-recorded one rather
+        # than to whichever `max` happened to reach first.
+        return max(found, key=lambda item: (item[0], item[1]))[2]
 
     def count_verdicts(self, task_ref: str) -> int:
         """How many CR6 verdict envelopes are on the review task.

{alissa_tools_github_revloop-0.16.10 → alissa_tools_github_revloop-0.16.12}/src/main/alissa/tools/github/revloop/loop.py

@@ -27,6 +27,8 @@ from .alissa import (
     ManagedSession,
     SessionRef,
     Task,
+    TaskDetail,
+    is_review_task_for,
     session_repo_slug,
 )
 from .config import (
@@ -871,6 +873,56 @@ class Decision:
     reenqueued: bool = False
 
 
+@dataclass(frozen=True)
+class ResolvedTask:
+    """One PR's review task as the decide path resolved it THIS pass.
+
+    Carries what the resolution happened to learn, and -- the part that matters
+    -- whether it learned it. The two resolution paths read different things:
+
+    * the CACHED path fetches the task by ref to check the mapping still holds,
+      so the whole evidence array comes with it and both the round count and the
+      newest verdict are free;
+    * the SEARCH path matches TITLES out of the task corpus, so it reads the
+      matched task afterwards to learn both -- and only when THAT read fails
+      does it fall back to a bare `count_verdicts` and know no verdict.
+
+    Hence `verdict_read`, rather than letting `verdict=None` stand for both "no
+    envelope parses" and "nobody looked". Convergence treats a None verdict as
+    "not approved"; conflating the two would silently refuse to close a round
+    that had in fact approved, every time the mapping was resolved by search.
+    """
+
+    task: "Task | None"
+    verdicts: int = 0
+    verdict: "str | None" = None
+    verdict_read: bool = False
+
+    @classmethod
+    def from_detail(cls, detail: TaskDetail) -> "ResolvedTask":
+        """One `alissa task get` payload answered all three questions.
+
+        The `verdict_read=True` invariant lives here rather than at the call
+        sites: it is a property of having read a task detail, and every path
+        that reads one gets it the same way.
+        """
+        return cls(
+            task=detail.task,
+            verdicts=detail.verdicts,
+            verdict=detail.verdict,
+            verdict_read=True,
+        )
+
+    def newest_verdict(self, alissa: Alissa) -> "str | None":
+        """The newest CR6 verdict envelope, fetching it only if this resolution
+        did not already have it in hand."""
+        if self.task is None:
+            return None
+        if self.verdict_read:
+            return self.verdict
+        return alissa.latest_verdict(self.task.ref)
+
+
 @dataclass(frozen=True)
 class ChecksGate:
     """What the head's CI rollup does to a round's APPROVE verdict.
@@ -955,6 +1007,16 @@ class ReviewWatcher:
         # rollup (two API calls) on every poll, forever, for every PR with an
         # owed approve. In-memory for the same reason _dry_run_drift is.
         self._dry_run_rollups: dict[tuple[str, int, int, str], str] = {}
+        # The task corpus THIS poll pass already fetched, or None until some
+        # PR in it misses the review-task cache. `alissa task list` returns
+        # every non-terminal task this actor owns (hundreds of rows, ~250 KB)
+        # and the list that answers one PR's search answers all of them, so a
+        # pass pays for it at most once instead of once per missing PR -- the
+        # same-second bursts of 2-4 identical fetches the census caught.
+        # In memory and reset per pass on purpose: this is a within-pass
+        # de-duplication, and a corpus that outlived its pass would answer the
+        # next one from titles and statuses that have since moved.
+        self._pass_tasks: list[Task] | None = None
         # Consecutive passes refused by the ledger gate in poll_once, and when
         # the refusal began -- the same streak-limit-then-escalate shape the
         # poll firewall uses, for the same reason: a read-only volume refuses
@@ -964,6 +1026,116 @@ class ReviewWatcher:
         # that cannot be written.
         self._ledger_streak = Streak()
 
+    # -- the PR -> review-task mapping ---------------------------------------
+
+    def _pass_task_list(self) -> list[Task]:
+        """The actor's task corpus, fetched AT MOST ONCE per poll pass.
+
+        The fallback behind the review-task cache. Every PR that misses the
+        cache in a given pass needs the same corpus, so the first miss pays for
+        it and the rest read the memo -- see `_pass_tasks` for why it never
+        outlives the pass.
+
+        A fetch that raises propagates, exactly as the unmemoized call did: the
+        pass's caller turns it into a SKIPPED decision for that one PR and the
+        memo stays empty, so the next PR retries rather than inheriting a
+        failure it never saw.
+        """
+        if self._pass_tasks is None:
+            self._pass_tasks = self.alissa.list_tasks()
+        return self._pass_tasks
+
+    def _review_task(self, pr: PullRequest) -> "ResolvedTask":
+        """This PR's open CR2 review task and what its evidence says, cheaply.
+
+        The decide path needs the review task on every pass of every open
+        round, and the only way to FIND one is to search the actor's whole
+        non-terminal task corpus by title -- a ~250 KB read that the daemon was
+        paying once per candidate PR per poll, forever (issue #66). CR2 gives
+        one review task per PR and CR7 reuses it across rounds, so the answer
+        does not move once known: it is resolved once, persisted, and from then
+        on read back by ref (one small task fetch, which the round count needed
+        anyway).
+
+        Three outcomes, in the order they are tried:
+
+        * a cached ref that still reads as this PR's open review task -- the
+          steady state, and no search at all;
+        * a cached ref that is READABLE and no longer matches (validated,
+          cancelled, retitled, or plain wrong) -- dropped, then searched for;
+        * no cached ref, or one that could not be read -- searched for. An
+          unreadable task is NOT a disproof, so the row survives a transient
+          CLI failure and the pass just degrades to the old behaviour.
+
+        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.
+
+        TWO consequences of resolving from cache, both accepted rather than
+        overlooked (PR #68 round 1):
+
+        * A cached hit does NOT re-check CR2 uniqueness. The duplicate-task
+          alarm lives in `find_review_task`, which only runs on a miss, so a
+          second open review task created for this PR AFTER the mapping was
+          cached goes unreported and the daemon keeps counting envelopes on the
+          one it pinned. Detecting it needs the corpus, and not fetching the
+          corpus is the point -- relocating the check is TASK-317167904.
+        * VALIDATING the review task drops the mapping, because
+          `is_review_task_for` requires an open task and the search cannot find
+          a terminal one either, so `evaluate` falls back to the GitHub review
+          count -- the fallback `_completed_rounds` deliberately avoids. That is
+          pre-existing and unchanged, but this path now HAS a durable ref that
+          could survive validation; it is not used because a terminal task can
+          never become open again, so a retained ref would have no disproof and
+          its row would be immortal. Settling that is TASK-1897198077.
+        """
+        cached = self.state.review_task(pr.full_name, pr.number)
+        if cached is not None:
+            detail = self.alissa.get_task(cached)
+            if detail is not None:
+                if is_review_task_for(pr.owner, pr.repo, pr.number, detail.task):
+                    return ResolvedTask.from_detail(detail)
+                log.info(
+                    "%s: cached review task %s no longer matches (title=%r "
+                    "status=%s) — re-resolving",
+                    pr.slug, cached, detail.task.title, detail.task.status,
+                )
+                self.state.forget_review_task(pr.full_name, pr.number)
+            else:
+                log.warning(
+                    "%s: could not read cached review task %s — falling back "
+                    "to the task search for this pass (the mapping is kept: "
+                    "an unreadable task is not a wrong one)",
+                    pr.slug, cached,
+                )
+
+        task = self.alissa.find_review_task(
+            pr.owner, pr.repo, pr.number, tasks=self._pass_task_list()
+        )
+        if task is None:
+            # A search that completed and found nothing IS a disproof: there is
+            # 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)
+            return ResolvedTask(task=None)
+
+        self.state.record_review_task(pr.full_name, pr.number, task.ref)
+        # The search matched a TITLE out of the corpus; the round count and the
+        # verdict both live in the task's evidence, and ONE read returns both.
+        # Reading it here rather than paying `count_verdicts` now and
+        # `latest_verdict` again from convergence is the same saving the cached
+        # path makes -- and it matters most in the degraded state this whole
+        # change serves: an unreadable ledger sends EVERY PR down this path on
+        # EVERY pass (PR #69 round 1).
+        detail = self.alissa.get_task(task.ref)
+        if detail is not None:
+            return ResolvedTask.from_detail(detail)
+        # That read failed, so the verdict is genuinely unknown -- left UNREAD
+        # rather than defaulted to None, which convergence would take as "no
+        # approve" and lose a closed round. Falls back to exactly the two-read
+        # behaviour this path had before.
+        return ResolvedTask(task=task, verdicts=self.alissa.count_verdicts(task.ref))
+
     # -- per-PR decision ---------------------------------------------------
 
     def evaluate(self, owner: str, repo: str, number: int) -> Decision:
@@ -993,11 +1165,10 @@ class ReviewWatcher:
         # Fall back to the substantive-review count only before the review task
         # exists (round 1). Looked up here (not in _spawn) because both the count
         # and convergence need it.
-        task = self.alissa.find_review_task(owner, repo, number)
+        resolved = self._review_task(pr)
+        task = resolved.task
         native = countable_rounds(my_reviews)
-        completed = (
-            self.alissa.count_verdicts(task.ref) if task is not None else native
-        )
+        completed = resolved.verdicts if task is not None else native
 
         # A round is not over until its verdict exists as a native review by
         # the reviewer identity (issue #51). An envelope ahead of the native
@@ -1027,7 +1198,7 @@ class ReviewWatcher:
             # anything else the round is still open and nothing may follow it.
             return self._close_round_natively(pr, task, round_=completed)
 
-        converged = self._convergence_reason(my_reviews, task, pr.head_sha)
+        converged = self._convergence_reason(my_reviews, resolved, pr.head_sha)
         if converged is not None:
             # THE terminal branch: a verdict of record exists at the current
             # head, so no round k+1 can be owed from here -- every path that
@@ -1885,7 +2056,7 @@ class ReviewWatcher:
         )
 
     def _convergence_reason(
-        self, my_reviews: list[Review], task: Task | None, head_sha: str
+        self, my_reviews: list[Review], resolved: "ResolvedTask", head_sha: str
     ) -> str | None:
         """Why the loop is done, or None if it is not.
 
@@ -1946,9 +2117,14 @@ class ReviewWatcher:
             return None
 
         # Only checkable once a review task exists; before that there is
-        # nowhere for a verdict to have been recorded.
-        if task is not None and self.alissa.latest_verdict(task.ref) == VERDICT_APPROVE:
-            return f"newest verdict envelope on {task.ref} reads approve"
+        # nowhere for a verdict to have been recorded. On the cached path the
+        # envelope was already read back with the task, so this costs nothing;
+        # on the search path it is the one fetch that still has to happen.
+        if (
+            resolved.task is not None
+            and resolved.newest_verdict(self.alissa) == VERDICT_APPROVE
+        ):
+            return f"newest verdict envelope on {resolved.task.ref} reads approve"
 
         return None
 
@@ -2923,6 +3099,12 @@ class ReviewWatcher:
     # -- polling -----------------------------------------------------------
 
     def poll_once(self) -> list[tuple[str, Decision]]:
+        # A new pass sees a new corpus. Cleared FIRST, before any early return
+        # can skip it: a memo left over from the previous pass would be handed
+        # to this one's title searches as if it were current, and it is the one
+        # piece of per-pass state whose staleness would be invisible.
+        self._pass_tasks = None
+
         # THE LEDGER GATE (issue #62, PR #63 round-1 blocker). Nothing below
         # may run when the ledger cannot record what it does.
         #
@@ -2950,9 +3132,18 @@ class ReviewWatcher:
         # DRY-RUN IS EXEMPT, and vacuously so: it already suppresses every side
         # 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). Its only ledger
-        # write is the snapshot, which this module classifies as best-effort
-        # telemetry and which _write_snapshot writes in dry-run deliberately.
+        # 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
+        # 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.
         # So the gate would protect nothing there and cost the operator the one
         # tool that answers "what would you do right now" -- asked, precisely,
         # during the substrate incident this whole change is about.

{alissa_tools_github_revloop-0.16.10 → alissa_tools_github_revloop-0.16.12}/src/main/alissa/tools/github/revloop/state.py

@@ -9,6 +9,12 @@ was already escalated, and to count the operator re-entry acks that raise a
 single PR's effective cap. The ledger tolerates sessions dying or being
 killed behind its back: a reap record is bookkeeping, never a precondition.
 
+The `review_tasks` table is a cache, not a ledger: it remembers which CR2
+review task each PR resolved to so the decide path can read that one task by
+ref instead of searching the actor's whole task corpus every poll. Every row is
+re-checked on use and dropped when it stops matching, and losing the table
+costs nothing but the search it was avoiding.
+
 The `poll_snapshots` table is a different animal from the ledger above: it
 records what each poll pass OBSERVED, not what the daemon must remember to
 avoid double-work. One row per pass carries the timing, the candidate count,
@@ -143,6 +149,28 @@ CREATE TABLE IF NOT EXISTS verdict_posts (
     PRIMARY KEY (repo, number, round)
 );
 
+-- The PR -> CR2 review-task mapping, remembered so the decide path does not
+-- have to search for it. CR2 guarantees one review task per PR and CR7 reuses
+-- it across every round, so the mapping is stable for the PR's whole life --
+-- which is exactly what makes it cacheable. A row here is a HINT, never a
+-- fact: it is re-checked by ref on use and dropped when it stops matching, and
+-- losing the whole table only costs one title search per PR (see
+-- loop._review_task). That is why this is best-effort like the snapshots
+-- above, not a correctness write.
+--
+-- Rows are never pruned, unlike poll_snapshots and like grants: one row per PR
+-- ever sighted (a few hundred, for this daemon's repo set, forever), and a
+-- stale row costs exactly one disproved read the first time that PR is seen
+-- again. `resolved_at` is retained for inspection -- when was this mapping last
+-- confirmed by a search -- and nothing in the daemon reads it.
+CREATE TABLE IF NOT EXISTS review_tasks (
+    repo        TEXT    NOT NULL,
+    number      INTEGER NOT NULL,
+    task_ref    TEXT    NOT NULL,
+    resolved_at INTEGER NOT NULL,
+    PRIMARY KEY (repo, number)
+);
+
 CREATE TABLE IF NOT EXISTS poll_snapshots (
     id                INTEGER PRIMARY KEY AUTOINCREMENT,
     ts                INTEGER NOT NULL,
@@ -852,6 +880,79 @@ class State:
 
     # -- poll snapshots (the console sidecar's exhaust buffer) -------------
 
+    def review_task(self, repo: str, number: int) -> "str | None":
+        """The review-task ref last resolved for this PR, or None.
+
+        None is the FIRST-SIGHTING answer and also the answer after a database
+        that could not be written: both mean "search for it", which is what the
+        daemon did unconditionally before this table existed. There is nothing
+        a caller may conclude from None beyond that.
+
+        The only READ in this class that absorbs a database error, and for the
+        same reason its writes do: this table is an optimization, so a ledger
+        that cannot answer must cost the daemon a task search, never a review.
+        Everything else here is ledger state whose loss the caller has to see.
+        """
+        try:
+            row = self._db.execute(
+                "SELECT task_ref FROM review_tasks WHERE repo=? AND number=?",
+                (repo, number),
+            ).fetchone()
+        except sqlite3.DatabaseError as exc:
+            log.warning(
+                "state: review-task cache unreadable (%s: %s) — this pass "
+                "resolves %s#%d by searching, as it did before the cache",
+                type(exc).__name__, exc, repo, number,
+            )
+            return None
+        return None if row is None else str(row["task_ref"])
+
+    def record_review_task(self, repo: str, number: int, task_ref: str) -> bool:
+        """Remember which review task a PR resolved to. Best-effort.
+
+        REPLACE, not IGNORE: re-resolving is how a mapping is corrected, so the
+        newest answer has to win. `resolved_at` records when the mapping was
+        last confirmed by a search; it is kept for inspection (the age of a
+        mapping is the first thing worth knowing if one is ever suspected) and
+        no query, log line or console view reads it.
+
+        A database error here is absorbed exactly like a snapshot's: the cache
+        is an optimization, and a pass that cannot persist it still decides the
+        round correctly -- it just pays the search again next time.
+        """
+        return self._write_telemetry(
+            lambda: self._replace_review_task(repo, number, task_ref),
+            "review-task cache write",
+        )
+
+    def _replace_review_task(self, repo: str, number: int, task_ref: str) -> None:
+        self._db.execute(
+            "INSERT OR REPLACE INTO review_tasks "
+            "(repo, number, task_ref, resolved_at) VALUES (?,?,?,?)",
+            (repo, number, task_ref, int(time.time())),
+        )
+        self._db.commit()
+
+    def forget_review_task(self, repo: str, number: int) -> bool:
+        """Drop a mapping that has been DISPROVED. Best-effort.
+
+        Only ever called on a positive disproof -- the task was read and is no
+        longer this PR's open review task, or a fresh search found none. Never
+        on a failed read: an unreadable task is not a wrong mapping, and
+        forgetting one on a transient CLI error would throw away a good cache
+        entry every time the API hiccups.
+        """
+        return self._write_telemetry(
+            lambda: self._delete_review_task(repo, number),
+            "review-task cache invalidation",
+        )
+
+    def _delete_review_task(self, repo: str, number: int) -> None:
+        self._db.execute(
+            "DELETE FROM review_tasks WHERE repo=? AND number=?", (repo, number)
+        )
+        self._db.commit()
+
     def record_snapshot(
         self,
         *,

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

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

{alissa_tools_github_revloop-0.16.10 → alissa_tools_github_revloop-0.16.12/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

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

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

@@ -1 +0,0 @@
-0.16.10