Skip to contentSkip to conversation

review: track and browse every version of a tracked series

RFC PATCH New Christian Brauner 1 participant 26 messages Aug 12

lore
Share & tools
lore
#0 lore raw

v2 cover review: track and browse every version of a tracked series

The review TUI binds all mail visibility to the revision a series is tracked at. 'e' opens only the tracked thread, unread badges exist only on the series row, and u/U updates poll only the tracked revision. Earlier versions of a series are invisible.

Make every known version of a tracked series a first-class citizen of the mail-tracking machinery.

The revisions catalog becomes the only home for per-revision read state (schema v11).

Per-change_id state moves the other way, onto a new changes table (schema v12). There is one b4/review/<change_id> branch, so its sha should not be stored once per version and read back with an ORDER BY. The catalog-sync and the backward-search live there too.

u/U updates poll every cataloged revision for new mail using the same thread queries used elsewhere. Neither lore nor b4 really support incremental updates though. Lore misses that functionality afaict.

A new "Find older revisions" action runs the b4 am/mbox backward search. It uses the change-id query when the cover carries one and subject+sender otherwise. It records what it finds and polls the new entries immediately. A retitled series without a change-id still needs manual linking. The same limitation b4 am -vN has.

The tracker list gains expandable per-version rows. 'x' unfolds a series into child rows. The tracked revision is starred. 'X' toggles all series at once. Enter or 'e' on a child opens that version's thread with revision-correct. 'd' range-diffs it against the tracked revision directly.

Message-level read state was already keyed by message-id alone. So Seen/Flagged/Answered flags apply across versions unchanged. This series adds the count, badge and navigation layers on top.

---
Changes in v2:
- Redesign the whole approach.

---
Christian Brauner (25):
review-tui: fix rethreaded series thread viewing
review: do not clear fields a re-adding caller does not know
review-tui: keep the rethread flag on an upgraded series row
review: guard the tracking-commit amend on the worktree, not the checkout
review-tui: recompute an evicted A·R·T cache entry
review: test the prerequisite fixes
review: serialize schema migrations against a concurrent opener
review: test the migration serialization
review: track message counts for all revisions of a series
review: give per-change_id state its own table
review: test per-revision message tracking
review-tui: poll every revision on u/U updates
review: test the per-revision poll sweep
review-tui: resolve the tracked revision in revision lists
review-tui: fall back when a cached thread blob has no series
review-tui: test revision resolution and the range-diff fallback
review: skip the catalog mirror when nothing moved
review: match a stray posting by message-id
review: add backward discovery of older series revisions
review-tui: add a "Find older revisions" action
review: test the catalog mirror, stray matching and backward discovery
review-tui: extract the Msgs column renderer from TrackedSeriesItem
review-tui: give the unseen badge a column of its own
review-tui: expand tracked series into per-version rows
review-tui: test per-version tracker rows

 docs/maintainer/review.rst         |   49 +
 src/b4/__init__.py                 |   60 +
 src/b4/review/_review.py           |  284 +-
 src/b4/review/tracking.py          | 2378 ++++++++++++++--
 src/b4/review_tui/_common.py       |  177 +-
 src/b4/review_tui/_lite_app.py     |    1 +
 src/b4/review_tui/_modals.py       |   15 +
 src/b4/review_tui/_review_app.py   |    2 +-
 src/b4/review_tui/_tracking_app.py | 1083 ++++++--
 src/tests/conftest.py              |   23 +
 src/tests/test___init__.py         |   62 +
 src/tests/test_review.py           |  822 ++++++
 src/tests/test_review_tracking.py  | 5256 +++++++++++++++++++++++++++++++++++-
 src/tests/test_tui_modals.py       |    1 +
 src/tests/test_tui_review.py       |  274 +-
 src/tests/test_tui_tracking.py     | 1983 +++++++++++++-
 16 files changed, 11911 insertions(+), 559 deletions(-)

---
base-commit: 362b87aa4d036884c36e4bfb9cdbdee626aba3bf
change-id: 20260718-work-b4-multiver-rows-6032fb71e951

#1 lore raw

RFC PATCH v2 1/25 review-tui: fix rethreaded series thread viewing

The lite thread viewer does not put is_rethreaded into the series dict it hands to retrieve_series_messages(), so pressing 'e' on a rethreaded series fetches a single patch's thread instead of reassembling the series from its per-patch message-ids.

Forward the flag through tracking_info.

---
 src/b4/review_tui/_lite_app.py     | 1 +
 src/b4/review_tui/_tracking_app.py | 1 +
 2 files changed, 2 insertions(+)
src/b4/review_tui/_lite_app.py +1 -0
index 51e14378..a75536d1 100644
@@ -551,6 +551,7 @@ class LiteThreadScreen(ModalScreen[None]):
                 'message_id': self._message_id,
                 'change_id': ti.get('change_id', ''),
                 'revision': ti.get('revision'),
+                'is_rethreaded': bool(ti.get('is_rethreaded')),
             }
             identifier = ti.get('identifier', '')
             if identifier:
src/b4/review_tui/_tracking_app.py +1 -0
index 5b7a7563..9f0a0302 100644
@@ -1704,6 +1704,7 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
                 'identifier': self._identifier,
                 'change_id': self._selected_series.get('change_id', ''),
                 'revision': self._selected_series.get('revision', 1),
+                'is_rethreaded': bool(self._selected_series.get('is_rethreaded')),
             }
         self._focus_change_id = self._selected_series.get('change_id')
         from b4.review_tui._lite_app import LiteThreadScreen
Signature · 1 line
2.53.0
#2 lore raw

RFC PATCH v2 2/25 review: do not clear fields a re-adding caller does not know

In reply to Christian Brauner

add_series_to_db()'s UPSERT arm writes pw_series_id and fingerprint straight from the excluded row, so every re-add clears whatever the caller did not happen to know.

The callers do not all know both. The Patchwork tracker re-adds a series to attach its pw id and has no fingerprint. rescan_branches() replays a branch and has neither. A CLI re-track has the fingerprint and no pw id. Each one dropped what the others had recorded, leaving a series that no longer matched by content, or one that lost its Patchwork link.

Passing None means "not known here", not "clear it". Use COALESCE.

---
 src/b4/review/tracking.py | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)
src/b4/review/tracking.py +11 -3
index a0c4ca4f..52b9a897 100644
@@ -449,7 +449,15 @@ def add_series_to_db(
     added_at: Optional[str] = None,
     is_rethreaded: bool = False,
 ) -> int:
-    """Add a series to the tracking database. Returns the track_id."""
+    """Add a series to the tracking database. Returns the track_id.
+
+    On conflict the identity fields converge instead of overwriting: a
+    caller that does not know the Patchwork id or the fingerprint leaves
+    an existing one in place.  Re-adds come from callers that never
+    learned those fields -- the Patchwork tracker attaching its id,
+    rescan_branches replaying a branch -- and each used to wipe whatever
+    the others had recorded.
+    """
     if added_at is None:
         added_at = datetime.datetime.now(datetime.timezone.utc).isoformat()
     cursor = conn.execute(
@@ -466,8 +474,8 @@ def add_series_to_db(
             added_at = COALESCE(series.added_at, excluded.added_at),
             message_id = excluded.message_id,
             num_patches = excluded.num_patches,
-            pw_series_id = excluded.pw_series_id,
-            fingerprint = excluded.fingerprint,
+            pw_series_id = COALESCE(excluded.pw_series_id, series.pw_series_id),
+            fingerprint = COALESCE(excluded.fingerprint, series.fingerprint),
             is_rethreaded = excluded.is_rethreaded
         RETURNING track_id
     """,
Signature · 1 line
2.53.0
#3 lore raw

RFC PATCH v2 3/25 review-tui: keep the rethread flag on an upgraded series row

In reply to Christian Brauner

The upgrade path resolves whether the target revision needs rethreading and threads target_is_rethreaded through five call sites, then does not pass it to add_series_to_db(). The UPSERT arm writes is_rethreaded from the excluded row, so the parameter's False default lands on the row and clears an existing 1.

A series row saying 0 for a revision that really was stitched together from individually fetched patches sends retrieve_series_messages() down the single-msgid path: 'e' shows one patch's thread instead of the series, and the message count collapses to match.

Pass the flag the upgrade already computed, and stop depending on every caller remembering to. The flag describes the posting, which the revisions catalog already records, so resolve it from there on the way in and keep the argument for a first track, before there is a catalog row to ask. Make the UPSERT arm sticky rather than overwriting, as add_revision() already is.

---
 src/b4/review/tracking.py          | 20 +++++++++++++++++---
 src/b4/review_tui/_tracking_app.py |  6 ++++++
 2 files changed, 23 insertions(+), 3 deletions(-)
src/b4/review/tracking.py +17 -3
index 52b9a897..710b4a0d 100644
@@ -456,7 +456,16 @@ def add_series_to_db(
     an existing one in place.  Re-adds come from callers that never
     learned those fields -- the Patchwork tracker attaching its id,
     rescan_branches replaying a branch -- and each used to wipe whatever
-    the others had recorded.
+    the others had recorded.  ``is_rethreaded`` is sticky for the same
+    reason, matching the catalog's :func:`add_revision`.
+
+    ``is_rethreaded`` describes the posting, so the catalog's answer for
+    this revision wins over the argument on the way in.  The argument is
+    still what a first track supplies, before there is a catalog row to
+    ask.  Callers that hand-carry the flag from a catalog lookup are then
+    merely agreeing with the row rather than being the only thing standing
+    between it and a False default -- which is what made dropping it at
+    one call site quietly clear the column.
     """
     if added_at is None:
         added_at = datetime.datetime.now(datetime.timezone.utc).isoformat()
@@ -465,7 +474,9 @@ def add_series_to_db(
         INSERT INTO series
         (change_id, revision, subject, sender_name, sender_email, sent_at, added_at,
          message_id, num_patches, pw_series_id, fingerprint, is_rethreaded)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
+                MAX(?, COALESCE((SELECT is_rethreaded FROM revisions
+                                 WHERE change_id = ? AND revision = ?), 0)))
         ON CONFLICT (change_id, revision) DO UPDATE SET
             subject = excluded.subject,
             sender_name = excluded.sender_name,
@@ -476,7 +487,8 @@ def add_series_to_db(
             num_patches = excluded.num_patches,
             pw_series_id = COALESCE(excluded.pw_series_id, series.pw_series_id),
             fingerprint = COALESCE(excluded.fingerprint, series.fingerprint),
-            is_rethreaded = excluded.is_rethreaded
+            is_rethreaded = MAX(COALESCE(series.is_rethreaded, 0),
+                                excluded.is_rethreaded)
         RETURNING track_id
     """,
         (
@@ -492,6 +504,8 @@ def add_series_to_db(
             pw_series_id,
             fingerprint,
             int(is_rethreaded),
+            change_id,
+            revision,
         ),
     )
     track_id = cursor.fetchone()[0]
src/b4/review_tui/_tracking_app.py +6 -0
index 9f0a0302..69da8f58 100644
@@ -4462,6 +4462,12 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
                         sent_at,
                         target_msgid,
                         lser.expected or num_am,
+                        # The upgrade already resolved this; without it the
+                        # UPSERT writes the column's 0 default (and clears an
+                        # existing 1), which sends every later retrieval of
+                        # the now-tracked revision down the single-msgid path
+                        # instead of reassembling it from its member patches.
+                        is_rethreaded=bool(target_is_rethreaded),
                     )
                     b4.review.tracking.update_series_status(
                         conn, change_id, 'reviewing', revision=target_rev
Signature · 1 line
2.53.0
#4 lore raw

RFC PATCH v2 4/25 review: guard the tracking-commit amend on the worktree, not the checkout

In reply to Christian Brauner

save_tracking_ref() rewrites a review branch's tip with commit-tree plus update-ref. Unlike git branch -f, that pair will move a branch out from under a live worktree and strand an in-progress git am or rebase on a commit that is no longer the branch tip.

"Checked out" is the wrong test for it. The amend reuses the branch's own tree, so a quiescent checkout survives one untouched: HEAD moves, the working tree and index still match it, git status stays clean. Refusing every checkout would refuse the review UI amending the tracking commit on the branch it has just checked out itself, and would defer the sweep's own writes for as long as a series stays under review.

What the amend cannot survive is an operation in flight. A git am, rebase, merge, cherry-pick, revert or bisect keeps state that names the tip being replaced, and git records that per worktree.

Put the rule in the writer rather than in each caller, so the two writers that reach update-ref through _store_thread_blob() and ensure_thread_context_blob() are covered as well. A lookup that fails counts as busy, since this guards a ref move.

---
 src/b4/__init__.py        | 60 +++++++++++++++++++++++++++++++++++++++++++++++
 src/b4/review/_review.py  | 20 ++++++++++++++++
 src/b4/review/tracking.py |  7 ++++++
 3 files changed, 87 insertions(+)
src/b4/__init__.py +60 -0
index a52b0011..169547c0 100644
@@ -4601,6 +4601,66 @@ def git_branch_checked_out(gitdir: Optional[str], branch_name: str) -> bool:
     return False
 
 
+# What a git operation leaves in a worktree's own gitdir while it is in
+# flight.  Each of these names a sequencer or a state that remembers the
+# tip the operation started from.
+_WORKTREE_OP_STATE = (
+    'rebase-apply',  # git am, git rebase --apply
+    'rebase-merge',  # git rebase --merge / -i
+    'MERGE_HEAD',
+    'CHERRY_PICK_HEAD',
+    'REVERT_HEAD',
+    'BISECT_LOG',
+    'sequencer',
+)
+
+
+def git_worktree_busy(gitdir: Optional[str], branch_name: str) -> bool:
+    """Whether a git operation is in flight where *branch_name* is checked out.
+
+    The question anything rewriting a branch's tip commit in place has to
+    ask, and it is narrower than :func:`git_branch_checked_out`.  An amend
+    that reuses the branch's own tree moves HEAD and nothing else -- the
+    working tree and index still match it, and `git status` stays clean --
+    so a quiescent checkout survives one untouched.  Refusing every
+    checkout instead would refuse the review UI amending the tracking
+    commit on the branch it has just checked out itself, which is the
+    common and correct case.
+
+    What such an amend cannot survive is a `git am`, rebase, merge,
+    cherry-pick, revert or bisect in flight: those keep state naming the
+    tip they started from, and moving it out from under them strands the
+    operation.
+
+    Not knowing counts as busy.  This guards a ref move, so a lookup that
+    fails must not read as permission.
+    """
+    wantref = f'refs/heads/{branch_name.removeprefix("refs/heads/")}'
+    ecode, out = git_run_command(gitdir, ['worktree', 'list', '--porcelain'])
+    if ecode != 0:
+        logger.debug('Could not list worktrees, assuming %s is busy', branch_name)
+        return True
+    wtpath = None
+    current = None
+    for line in out.splitlines():
+        if line.startswith('worktree '):
+            current = line[9:].strip()
+        elif line.startswith('branch ') and line[7:].strip() == wantref:
+            wtpath = current
+            break
+    if not wtpath:
+        # Checked out nowhere, so there is no operation to strand.
+        return False
+    ecode, out = git_run_command(wtpath, ['rev-parse', '--absolute-git-dir'])
+    if ecode != 0:
+        logger.debug('Could not resolve the gitdir of %s, assuming busy', wtpath)
+        return True
+    wtgitdir = out.strip()
+    return any(
+        os.path.exists(os.path.join(wtgitdir, name)) for name in _WORKTREE_OP_STATE
+    )
+
+
 def git_revparse_tag(gitdir: Optional[str], tagname: str) -> Optional[str]:
     if not tagname.startswith('refs/tags/'):
         fulltag = f'refs/tags/{tagname}'
src/b4/review/_review.py +20 -0
index 5fa4d2ab..98f51363 100644
@@ -721,12 +721,32 @@ def save_tracking_ref(
     Uses git commit-tree + git update-ref so that commit.gpgsign and
     hooks are not triggered — tracking commits are ephemeral and do
     not benefit from signing.  Returns True on success.
+
+    Declines while the worktree holding *branch* has a git operation in
+    flight.  update-ref, unlike `git branch -f`, will happily move a
+    branch out from under a live worktree, and a `git am` or rebase keeps
+    state naming the tip this is about to replace.  The rule lives here
+    rather than in each caller because it is a property of the write:
+    every caller that moves this ref has to respect it, and the two that
+    reached update-ref through :func:`b4.review.tracking._store_thread_blob`
+    and :func:`b4.review.tracking.ensure_thread_context_blob` did not.
+
+    The tree is the branch's own, so a *quiescent* checkout is not a
+    reason to decline -- see :func:`b4.git_worktree_busy`.
     """
     if not branch.startswith(REVIEW_BRANCH_PREFIX):
         logger.critical(
             'Refusing to write tracking commit to non-review branch: %s', branch
         )
         return False
+    if b4.git_worktree_busy(topdir, branch):
+        # Said out loud, not at debug: :func:`save_tracking` turns a False
+        # into `Unable to amend tracking commit` and exits, and a maintainer
+        # who has a rebase in flight on the branch is owed the reason.  The
+        # sweep is the one caller that meets this routinely, and it runs
+        # inside _quiet_cron/_quiet_worker.
+        logger.info('%s is mid-operation, not amending its tracking commit', branch)
+        return False
     commit_msg = cover_text + '\n\n' + make_review_magic_json(tracking)
     ecode, out = b4.git_run_command(topdir, ['rev-parse', f'{branch}^{{tree}}'])
     if ecode > 0:
src/b4/review/tracking.py +7 -0
index 710b4a0d..2722e6c3 100644
@@ -1223,6 +1223,13 @@ def sync_revisions_catalog_to_branch(
     that cannot be re-derived from lore — travels with the branch on push.
     No-op (returns False) when there is no topdir, no such branch, or the
     catalog is already current.
+
+    A branch whose worktree is mid-operation is declined by
+    :func:`b4.review.save_tracking_ref` itself, so there is no test for it
+    here: the rule belongs to the write, and repeating it per caller is
+    how it came to be enforced for this one and not for the other two.
+    The catalog is mirrored again on the next sweep that finds the
+    worktree free.
     """
     if not topdir:
         return False
Signature · 1 line
2.53.0
#5 lore raw

RFC PATCH v2 5/25 review-tui: recompute an evicted A·R·T cache entry

In reply to Christian Brauner

_invalidate_caches(change_id) evicts a single series from the A·R·T count cache, but _load_series() only refills that cache when the whole dict is None, so the evicted entry is never recomputed. The series dicts are rebuilt from scratch on every load, so nothing carries the old value forward either, and the series renders '-' in the A·R·T column for the rest of the session.

Take, link, upgrade, snooze, unsnooze, waiting and thank all evict exactly one entry, so every one of them hits this.

Refill whenever a wanted branch is missing from the cache rather than only when the cache is gone, and merge rather than replace so an intact cache still skips the subprocess.

---
 src/b4/review_tui/_tracking_app.py | 34 +++++++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)
src/b4/review_tui/_tracking_app.py +31 -3
index 69da8f58..11e79ef2 100644
@@ -988,7 +988,11 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
         self._cached_newest_revisions: Optional[Dict[str, int]] = None
         self._cached_revision_counts: Optional[Dict[str, int]] = None
         self._cached_revisions: Optional[Dict[str, List[Dict[str, Any]]]] = None
-        self._cached_art_counts: Optional[Dict[str, Tuple[int, int, int]]] = None
+        # A None value is a branch whose tip carries no tracking trailer
+        # block; cached as a miss so the refill below converges.
+        self._cached_art_counts: Optional[Dict[str, Optional[Tuple[int, int, int]]]] = (
+            None
+        )
 
     def _invalidate_caches(self, change_id: Optional[str] = None) -> None:
         """Drop cached data so the next _load_series re-fetches.
@@ -1190,8 +1194,32 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
                     art_branches[branch_name] = branch_tips[branch_name]
 
         # --- Bulk ART counts (1 subprocess instead of N) ---
-        if self._cached_art_counts is None and art_branches and topdir:
-            self._cached_art_counts = _get_art_counts_batch(topdir, art_branches)
+        # Recompute whenever a wanted branch is missing, not only when the
+        # whole dict is gone: _invalidate_caches(change_id) evicts a single
+        # entry, which an `is None` test would never notice, leaving that
+        # series' A·R·T stuck at '-' for the session.
+        #
+        # Only the missing ones, though.  The targeted eviction keeps the
+        # other entries precisely so they are not recomputed, and handing
+        # the whole map to the batch spends that back: one tracking commit
+        # read per branch under review, on every take, link, snooze or
+        # thank, to re-derive counts nothing has invalidated.
+        art_missing = {
+            name: sha
+            for name, sha in art_branches.items()
+            if not self._cached_art_counts or name not in self._cached_art_counts
+        }
+        if topdir and art_missing:
+            counts = _get_art_counts_batch(topdir, art_missing)
+            if self._cached_art_counts is None:
+                self._cached_art_counts = {}
+            self._cached_art_counts.update(counts)
+            # Misses recorded too, or a branch _get_art_counts_batch declines
+            # to return stays absent, the difference above never empties and
+            # a `git cat-file` fires on every reload -- once a second while a
+            # cron sweep bumps the DB mtime.
+            for branch_name in art_missing:
+                self._cached_art_counts.setdefault(branch_name, None)
         art_map = self._cached_art_counts or {}
         for series in self._all_series:
             change_id = series.get('change_id', '')
Signature · 1 line
2.53.0
#6 lore raw

RFC PATCH v2 6/25 review: test the prerequisite fixes

In reply to Christian Brauner

Cover the four fixes the rest of the series builds on: the rethread flag reaching retrieve_series_messages() through tracking_info and the thread viewer's series dict, the UPSERT convergence of is_rethreaded plus the Patchwork id and fingerprint a re-adding caller does not know, the catalog mirror declining a branch whose worktree is mid-operation, and the A·R·T cache refilling an entry a targeted invalidation evicted.

---
 src/tests/conftest.py             |  23 ++++
 src/tests/test___init__.py        |  62 ++++++++++
 src/tests/test_review_tracking.py | 172 ++++++++++++++++++++++++++++
 src/tests/test_tui_tracking.py    | 235 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 492 insertions(+)
src/tests/conftest.py +23 -0
index aa6dbc84..a880e9af 100644
@@ -44,6 +44,29 @@ def settestdefaults(
     monkeypatch.setattr(sys, '_running_in_pytest', True, raising=False)
 
 
[email protected](scope='function', autouse=True)
+def clear_lore_cancel() -> Generator[None, None, None]:
+    """Clear liblore's cancel flag between tests.
+
+    The flag is process-global and sticky by design, and a TrackingApp sets
+    it on shutdown (LoreNodeShutdownMixin cancels the node so an in-flight
+    fetch stops).  Left set, it makes the next test that reaches lore raise
+    OperationCancelledError -- and only the TUI resets it, inside
+    lore_request(), so the plain sweep path in b4.review has no reset point
+    at all.
+
+    That turns a suite into an order-dependent one: any TUI test poisons a
+    later non-TUI one, and today only alphabetical file order hides it.  A
+    reorder -- pytest-randomly, --lf, a subset, CI sharding -- surfaces it,
+    pointing at the wrong file entirely.
+    """
+    yield
+    try:
+        b4.get_lore_node().reset_cancel()
+    except Exception:
+        pass
+
+
 @pytest.fixture(scope='function')
 def sampledir(request: pytest.FixtureRequest) -> str:
     return os.path.join(request.path.parent, 'samples')
src/tests/test___init__.py +62 -0

68 lines not on this page · raw message

src/tests/test_review_tracking.py +172 -0

181 lines not on this page · raw message

src/tests/test_tui_tracking.py +235 -0

244 lines not on this page · raw message

Signature · 1 line
2.53.0
#7 lore raw

RFC PATCH v2 7/25 review: serialize schema migrations against a concurrent opener

In reply to Christian Brauner

_migrate_db_if_needed() reads the schema version and then issues DDL in autocommit, so two processes opening the same database both decide to migrate. The loser dies on duplicate column name: message_count, or, having read the version before the winner's DROP COLUMN landed, on no such column: message_count. Reproduced 6/6 with two threads opening one v10 database.

busy_timeout, which _configure_conn sets for exactly this pair of writers, does not help: neither side ever asks for a lock.

The TUI and a b4 review cron sweep are that pair. The race has been latent since the v8 migrations because nothing has needed migrating since; the next schema bump makes it fire, once, on the first launch after an upgrade, for every maintainer with the timer installed. It does not corrupt anything, since the loser's work rolls back and the winner completes, but it surfaces as a raw sqlite traceback out of get_db(), and update_revision_message_counts() catches only FileNotFoundError.

Take the write lock before re-reading the version, so the second process finds the work already done. sqlite's DDL is transactional, so this also makes the migration atomic: the version bump can no longer commit separately from the schema it describes, and an interrupted migration rolls back whole rather than leaving a half-migrated database stamped with the old version.

The version is still read once without the lock first. The answer is "no migration pending" on every open but the one after an upgrade, and that path must not serialize every connection behind a write lock.

---
 src/b4/review/tracking.py | 44 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)
src/b4/review/tracking.py +42 -2
index 2722e6c3..cecfdb9c 100644
@@ -135,10 +135,45 @@ def init_db(identifier: str) -> sqlite3.Connection:
 
 
 def _migrate_db_if_needed(conn: sqlite3.Connection) -> None:
-    """Apply any pending schema migrations in-place."""
+    """Apply any pending schema migrations in-place.
+
+    Serialized against other processes, because the TUI and a
+    ``b4 review cron`` sweep open the same database and a pending
+    migration is exactly what both of them find on the first run after an
+    upgrade.  Reading the version and then issuing DDL in autocommit let
+    both decide to migrate: the loser died on `duplicate column name`, or
+    -- having read the version before the winner's DROP landed -- on
+    `no such column`.  busy_timeout cannot help, since neither side ever
+    asked for a lock.
+
+    BEGIN IMMEDIATE takes the write lock before the version is re-read, so
+    the second process finds the work already done.  It also makes the
+    whole migration one transaction -- sqlite's DDL is transactional -- so
+    the version bump can no longer commit separately from the schema it
+    describes, and an interrupted migration rolls back whole.
+
+    The version is read once without the lock first: the answer is "no" on
+    every open but the one after an upgrade, and that path must not
+    serialize every connection behind a write lock.
+    """
+    row = conn.execute('SELECT version FROM schema_version').fetchone()
+    if row is not None and row[0] >= SCHEMA_VERSION:
+        return
+    conn.execute('BEGIN IMMEDIATE')
+    try:
+        _run_migrations(conn)
+    except Exception:
+        conn.rollback()
+        raise
+
+
+def _run_migrations(conn: sqlite3.Connection) -> None:
+    """The migration ladder, under the write lock :func:`_migrate_db_if_needed` took."""
     row = conn.execute('SELECT version FROM schema_version').fetchone()
     version = row[0] if row else 0
     if version >= SCHEMA_VERSION:
+        # Another process migrated while we waited for the lock.
+        conn.rollback()
         return
     if version < 2:
         conn.execute('ALTER TABLE series ADD COLUMN branch_sha TEXT')
@@ -198,7 +233,12 @@ def _migrate_db_if_needed(conn: sqlite3.Connection) -> None:
             conn.execute(
                 'ALTER TABLE revisions ADD COLUMN is_rethreaded INTEGER DEFAULT 0'
             )
-    conn.execute('UPDATE schema_version SET version = ?', (SCHEMA_VERSION,))
+    # Not an UPDATE: `version` is the primary key, so an UPDATE writes
+    # nothing at all against an empty table -- and the read above maps "no
+    # row" to version 0, so such a database would re-run the whole ladder
+    # on every open and never record that it had finished.
+    conn.execute('DELETE FROM schema_version')
+    conn.execute('INSERT INTO schema_version (version) VALUES (?)', (SCHEMA_VERSION,))
     conn.commit()
 
 
Signature · 1 line
2.53.0
#8 lore raw

RFC PATCH v2 8/25 review: test the migration serialization

In reply to Christian Brauner

Cover the three claims: two processes opening one database both come away with a usable connection and the ladder having run once, a migration interrupted partway rolls back whole rather than leaving a half-migrated database stamped with the old version, and an up-to-date database is opened without taking the write lock at all.

The fixture builds a schema-version 1 database and asserts the ladder lands on SCHEMA_VERSION, so it needs no updating on the next bump.

---
 src/tests/test_review_tracking.py | 113 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
src/tests/test_review_tracking.py +113 -0
index 4cde7cdd..6394d332 100644
@@ -1721,6 +1721,119 @@ def _make_blob_tracking_data(
     }
 
 
+class TestMigrationSerialization:
+    """Two processes opening one database must not both migrate it.
+
+    The TUI and a ``b4 review cron`` sweep open the same file, and a
+    pending migration is exactly what both of them find on the first run
+    after an upgrade.  Reading the version and then issuing DDL in
+    autocommit let both decide to migrate: the loser died on `duplicate
+    column name`, or -- having read the version before the winner's DROP
+    landed -- on `no such column`.  busy_timeout cannot help, because
+    neither side ever asked for a lock.
+    """
+
+    @staticmethod
+    def _stale_db(identifier: str) -> str:
+        """A schema-version 1 database, whatever the current version is."""
+        db_path = review_tracking.get_db_path(identifier)
+        raw = sqlite3.connect(db_path)
+        raw.executescript("""
+            CREATE TABLE schema_version (version INTEGER PRIMARY KEY);
+            CREATE TABLE series (
+                track_id INTEGER PRIMARY KEY,
+                change_id TEXT NOT NULL,
+                revision INTEGER NOT NULL,
+                status TEXT DEFAULT 'new',
+                UNIQUE (change_id, revision)
+            );
+        """)
+        raw.execute('INSERT INTO schema_version (version) VALUES (1)')
+        raw.commit()
+        raw.close()
+        return db_path
+
+    def test_two_openers_both_survive_a_pending_migration(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Both get a usable connection, and the ladder runs once."""
+        import threading
+
+        db_path = self._stale_db('mig-race')
+        errors: list[Exception] = []
+        # Both inside _migrate_db_if_needed at once is the whole point; let
+        # them serialize and the test passes on code that cannot survive
+        # the overlap.
+        barrier = threading.Barrier(2)
+
+        def _open() -> None:
+            barrier.wait()
+            try:
+                review_tracking.get_db('mig-race').close()
+            except Exception as ex:
+                errors.append(ex)
+
+        threads = [threading.Thread(target=_open) for _ in range(2)]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join()
+
+        assert errors == []
+        raw = sqlite3.connect(db_path)
+        rows = raw.execute('SELECT version FROM schema_version').fetchall()
+        raw.close()
+        # One row at the current version: the loser found the work done
+        # rather than redoing it.
+        assert rows == [(review_tracking.SCHEMA_VERSION,)]
+
+    def test_an_interrupted_migration_rolls_back_whole(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Half a migration stamped with the old version is the bad state.
+
+        The next open would resume the ladder at a step whose work is
+        already there and die on it.  sqlite's DDL is transactional, so
+        wrapping the ladder makes the version bump and the schema it
+        describes commit together or not at all.
+        """
+        db_path = self._stale_db('mig-atomic')
+
+        def _boom(conn: sqlite3.Connection) -> None:
+            conn.execute('ALTER TABLE series ADD COLUMN halfway TEXT')
+            raise RuntimeError('interrupted')
+
+        monkeypatch.setattr(review_tracking, '_run_migrations', _boom)
+        with pytest.raises(RuntimeError):
+            review_tracking.get_db('mig-atomic')
+
+        raw = sqlite3.connect(db_path)
+        cols = {row[1] for row in raw.execute('PRAGMA table_info(series)')}
+        version = raw.execute('SELECT version FROM schema_version').fetchone()[0]
+        raw.close()
+        assert 'halfway' not in cols
+        assert version == 1
+
+    def test_an_up_to_date_database_takes_no_write_lock(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """The version is read once without the lock first.
+
+        Every open but the one after an upgrade answers "no migration
+        pending", and that path must not serialize every connection behind
+        a write lock -- a sweep mid-write would otherwise stall the TUI for
+        the whole busy_timeout on every single open.
+        """
+        review_tracking.init_db('mig-current').close()
+        holder = sqlite3.connect(review_tracking.get_db_path('mig-current'))
+        holder.execute('BEGIN IMMEDIATE')
+        try:
+            review_tracking.get_db('mig-current').close()
+        finally:
+            holder.rollback()
+            holder.close()
+
+
 class TestFollowupBlob:
     """Tests for _store_thread_blob() and get_thread_mbox()."""
 
Signature · 1 line
2.53.0
#9 lore raw

RFC PATCH v2 9/25 review: track message counts for all revisions of a series

In reply to Christian Brauner

The series table only carries message counts for the tracked revision, so new mail landing on an older version's thread is invisible.

Move per-revision read state onto the revisions catalog and leave it there. message_count, seen_message_count, last_update_check and last_mail_at become catalog columns (schema v11, backfilled from series rows including archived upgrade leftovers) and the series copies are dropped, so no reader has to know which of two copies wins.

Add update_revision_message_counts(), a per-revision poller. It works least-recently-checked first, writes counts only when the thread actually moved, reassembles rethreaded revisions from their per-patch threads, and caches the thread mbox as a git blob. The stitched series a range-diff needs is a different artifact for any version posted with broken threading, so it gets its own column beside that one.

The poller fetches and counts each thread rather than asking the archive what is new since it last looked. public-inbox has no thread-scoped search, and its only date-range query runs against the whole inbox, which costs more than the thread it would be probing. Comparing the fresh count against the stored one is correct on any public-inbox host. A quiet poll still records that it looked, since the rotation is ordered by that stamp and a column meaning "last changed" would pin the cap to whichever revisions keep changing.

refresh_message_count() and sync_seen_from_unseen_count() write the revision's catalog row whether or not a series currently tracks it, so the thread viewer's badge sync works for any revision.

---
 src/b4/review/_review.py           |    5 +-
 src/b4/review/tracking.py          | 1475 ++++++++++++++++++++++++++++++------
 src/b4/review_tui/_tracking_app.py |   37 +-
 src/tests/test_review_tracking.py  |   37 +-
 src/tests/test_tui_tracking.py     |   20 +-
 5 files changed, 1326 insertions(+), 248 deletions(-)
src/b4/review/_review.py +4 -1
index 98f51363..f566dbfd 100644
@@ -2470,7 +2470,10 @@ def update_series_tracking(
             _known = set()
 
         msgs = b4.mbox.get_extra_series(msgs, direction=1, nocache=True)
-        if current_rev > 1 and not _known:
+        # Discount the tracked revision's own entry.  The v11 backfill gives
+        # every series row one, so a plain "is the catalog empty?" test is
+        # never true again and this one-shot search stopped running at all.
+        if current_rev > 1 and not (_known - {current_rev}):
             msgs = b4.mbox.get_extra_series(
                 msgs, direction=-1, wantvers=list(range(1, current_rev)), nocache=True
             )
src/b4/review/tracking.py +1261 -214

1,776 lines not on this page · raw message

src/b4/review_tui/_tracking_app.py +24 -13
index 11e79ef2..42f0f46c 100644
@@ -4263,22 +4263,33 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
             prior_thread_blob = old_series.get('thread-context-blob', '')
             prior_msgid = old_series.get('header-info', {}).get('msgid', '')
 
-            # --- 1c. Record the current rev's mbox blob in the DB ---
-            # Do this before archiving so the blob SHA survives for range-diff.
-            # The blob may later be GC'd; callers must tolerate a missing blob.
-            if self._identifier:
-                cur_mbox_blob = old_series.get('thread-blob', '')
-                if cur_mbox_blob:
+            # --- 1c. Record the outgoing rev's mbox blob in the catalog ---
+            # Before anything fallible: every abort return below would skip
+            # this write, and the blob -- written with `hash-object -w` and
+            # referenced only from the database -- costs nothing to record
+            # now while the tracking commit is still the branch's.  The
+            # tracked revision's catalog row is guaranteed by
+            # add_series_to_db/_ensure_catalog_row and the v11 backfill; a
+            # row somehow missing degrades to a debug line and a later
+            # lore refetch.
+            cur_mbox_blob = old_series.get('thread-blob', '')
+            if self._identifier and cur_mbox_blob:
+                try:
+                    _conn = b4.review.tracking.get_db(self._identifier)
                     try:
-                        _conn = b4.review.tracking.get_db(self._identifier)
-                        b4.review.tracking.set_revision_thread_blob(
+                        if not b4.review.tracking.set_revision_thread_blob(
                             _conn, change_id, current_rev, cur_mbox_blob
-                        )
+                        ):
+                            logger.debug(
+                                'No catalog row for v%d, thread blob not recorded',
+                                current_rev,
+                            )
+                    finally:
                         _conn.close()
-                    except Exception as _ex:
-                        logger.debug(
-                            'Could not record thread blob for v%d: %s', current_rev, _ex
-                        )
+                except Exception as _ex:
+                    logger.debug(
+                        'Could not record thread blob for v%d: %s', current_rev, _ex
+                    )
 
             # --- 2. Resolve metadata for git-am ---
             top_msgid = None
src/tests/test_review_tracking.py +25 -12
index 6394d332..f65bbb4d 100644
@@ -1596,15 +1596,28 @@ class TestFollowupCounts:
     def test_schema_has_followup_columns(
         self, tmp_path: pytest.TempPathFactory
     ) -> None:
-        """Verify fresh DB has message_count, seen_message_count, last_update_check, last_activity_at."""
+        """Read state is the catalog's; `series` keeps only its own stamp."""
         conn = review_tracking.init_db('fc-schema-test')
-        cursor = conn.execute('PRAGMA table_info(series)')
-        col_names = {row[1] for row in cursor.fetchall()}
-        assert 'message_count' in col_names
-        assert 'seen_message_count' in col_names
-        assert 'last_update_check' in col_names
-        assert 'last_activity_at' in col_names
+        series_cols = {row[1] for row in conn.execute('PRAGMA table_info(series)')}
+        rev_cols = {row[1] for row in conn.execute('PRAGMA table_info(revisions)')}
         conn.close()
+        assert {
+            'message_count',
+            'seen_message_count',
+            'last_update_check',
+        } <= rev_cols
+        # One owner: no second copy on `series` for a reader to prefer.
+        assert (
+            not {
+                'message_count',
+                'seen_message_count',
+                'last_update_check',
+            }
+            & series_cols
+        )
+        # This one is the series' own maintainer-action stamp, not the
+        # catalog's last_mail_at, and it stays.
+        assert 'last_activity_at' in series_cols
 
     def test_migration_adds_followup_columns(
         self, tmp_path: pytest.TempPathFactory
@@ -1661,7 +1674,7 @@ class TestFollowupCounts:
         )
         # Manually set a delta
         conn.execute(
-            'UPDATE series SET message_count = 10, seen_message_count = 6'
+            'UPDATE revisions SET message_count = 10, seen_message_count = 6'
             ' WHERE change_id = ?',
             ('fc-seen',),
         )
@@ -1673,7 +1686,7 @@ class TestFollowupCounts:
         # Reopen with get_db to get row_factory for named column access
         conn = review_tracking.get_db('fc-seen-test')
         row = conn.execute(
-            'SELECT message_count, seen_message_count FROM series WHERE change_id = ?',
+            'SELECT message_count, seen_message_count FROM revisions WHERE change_id = ?',
             ('fc-seen',),
         ).fetchone()
         assert row['message_count'] == 10
@@ -2813,7 +2826,7 @@ class TestUpdateSeriesTrackingCounts:
         review_tracking.update_series_status(conn, change_id, 'accepted')
         # Baseline from the reviewing days: 5 messages, all seen
         conn.execute(
-            'UPDATE series SET message_count = 5, seen_message_count = 5'
+            'UPDATE revisions SET message_count = 5, seen_message_count = 5'
             ' WHERE change_id = ?',
             (change_id,),
         )
@@ -2854,7 +2867,7 @@ class TestUpdateSeriesTrackingCounts:
 
         conn = review_tracking.get_db(identifier)
         row = conn.execute(
-            'SELECT message_count, seen_message_count FROM series WHERE change_id = ?',
+            'SELECT message_count, seen_message_count FROM revisions WHERE change_id = ?',
             (change_id,),
         ).fetchone()
         conn.close()
@@ -4580,7 +4593,7 @@ class TestUpdateMessageCountSeenBump:
     @staticmethod
     def _get_counts(conn: sqlite3.Connection) -> tuple[int, int]:
         row = conn.execute(
-            'SELECT message_count, seen_message_count FROM series'
+            'SELECT message_count, seen_message_count FROM revisions'
             ' WHERE change_id = ? AND revision = ?',
             ('bump-cid', 1),
         ).fetchone()
src/tests/test_tui_tracking.py +12 -8
index 664956ec..cc80e7b1 100644
@@ -108,7 +108,7 @@ def _seed_db(identifier: str, series_list: List[Dict[str, Any]]) -> None:
         mc = s.get('message_count')
         if mc is not None:
             conn.execute(
-                'UPDATE series SET message_count = ?, seen_message_count = ? '
+                'UPDATE revisions SET message_count = ?, seen_message_count = ? '
                 'WHERE change_id = ? AND revision = ?',
                 (
                     mc,
@@ -965,7 +965,7 @@ class TestTrackingWithReviewBranch:
             # Verify message counts are equal in DB
             conn = tracking.get_db(identifier)
             cursor = conn.execute(
-                'SELECT message_count, seen_message_count FROM series WHERE change_id = ?',
+                'SELECT message_count, seen_message_count FROM revisions WHERE change_id = ?',
                 (change_id,),
             )
             row = cursor.fetchone()
@@ -1199,7 +1199,7 @@ class TestTrackingUpgradeNewSeries:
         )
         # Set message counts so we can verify they get reset
         conn.execute(
-            'UPDATE series SET message_count = 6, seen_message_count = 4'
+            'UPDATE revisions SET message_count = 6, seen_message_count = 4'
             ' WHERE change_id = ?',
             (change_id,),
         )
@@ -1230,18 +1230,22 @@ class TestTrackingUpgradeNewSeries:
             # Verify the DB was updated to v13 with counts reset
             conn = tracking.get_db(identifier)
             cursor = conn.execute(
-                'SELECT revision, message_id, message_count,'
-                ' seen_message_count FROM series'
-                ' WHERE change_id = ?',
+                'SELECT revision, message_id FROM series WHERE change_id = ?',
                 (change_id,),
             )
             row = cursor.fetchone()
+            # Counts are not on this row to reset: the series now points at
+            # v13's catalog entry, which starts out uncounted.
+            counts = conn.execute(
+                'SELECT message_count, seen_message_count FROM revisions'
+                ' WHERE change_id = ? AND revision = 13',
+                (change_id,),
+            ).fetchone()
             conn.close()
             assert row is not None
             assert row[0] == 13
             assert row[1] == '[email protected]'
-            assert row[2] is None  # message_count reset
-            assert row[3] is None  # seen_message_count reset
+            assert counts is None or (counts[0] is None and counts[1] is None)
 
 
 class TestTrackingSnooze:
Signature · 1 line
2.53.0
#10 lore raw

RFC PATCH v2 10/25 review: give per-change_id state its own table

In reply to Christian Brauner

series.branch_sha records the HEAD of b4/review/<change_id> so a rescan can skip a branch that has not moved. There is one such branch per change_id, but the column lives on a table keyed (change_id, revision), so the fact is stored once per version of the series.

That forces an arbitration nothing should have to make. rescan_branches() reads it back with ORDER BY revision DESC LIMIT 1, believing the highest revision's copy, while writing only the row whose revision the branch's tracking commit happens to name. A change_id with more than one live row, which rescan_branches() itself can produce, then has a stale copy sitting where the reader looks.

Give it a table of its own, keyed by change_id alone. The reader stops choosing, the writer stops picking a row, and delete_series() drops the entry with the rest of the change. The migration seeds each change_id from the same row the old reader believed, so nothing is reinterpreted on the way across. A wrong sha costs one extra tracking-commit read on the next rescan, since this is a cache key rather than data.

---
 src/b4/review/tracking.py         | 141 +++++++++++++++++++++++++++++++-------
 src/tests/test_review_tracking.py |   3 +-
 2 files changed, 120 insertions(+), 24 deletions(-)
src/b4/review/tracking.py +118 -23
index 7d42b160..68701238 100644
@@ -26,7 +26,7 @@ logger = b4.logger
 REVIEW_METADATA_DIR = 'b4-review'
 REVIEW_METADATA_FILE = 'metadata.json'
 
-SCHEMA_VERSION = 11
+SCHEMA_VERSION = 12
 
 SERIES_PATCHES_DDL = """
 CREATE TABLE IF NOT EXISTS series_patches (
@@ -53,7 +53,6 @@ CREATE TABLE IF NOT EXISTS series (
     pw_series_id INTEGER,
     status TEXT DEFAULT 'new',
     fingerprint TEXT,
-    branch_sha TEXT,
     -- Per-revision read state (message_count, seen_message_count,
     -- last_update_check) lives on `revisions` and only there: a series row
     -- names which revision it tracks, and that revision's catalog row
@@ -73,6 +72,28 @@ CREATE TABLE IF NOT EXISTS series (
     UNIQUE (change_id, revision)
 )"""
 
+# Per-change_id state: one row per change_id, never one per revision.
+#
+# These facts belong to the change, not to a version of it -- the review
+# branch is `b4/review/<change_id>` and there is exactly one, the backward
+# search runs once per change_id -- so a copy on every `series` row left
+# each writer updating them all and each reader arbitrating between them
+# (MAX(back_searched), ORDER BY revision DESC LIMIT 1 for the other two).
+# That is the same "which copy wins" question the per-revision read state
+# moved onto `revisions` to stop asking.
+CHANGES_DDL = """
+CREATE TABLE IF NOT EXISTS changes (
+    change_id TEXT PRIMARY KEY,
+    -- HEAD of b4/review/<change_id> at the last branch rescan.
+    branch_sha TEXT,
+    -- "<branch-sha>:<catalog-sha1>" at the last successful known-revisions
+    -- mirror; see sync_revisions_catalog_to_branch.
+    catalog_synced TEXT,
+    -- 1 once the one-shot backward revision search has run for this
+    -- change_id, found something or not; see set_back_searched().
+    back_searched INTEGER DEFAULT 0
+)"""
+
 SCHEMA_SQL = (
     """
 CREATE TABLE IF NOT EXISTS schema_version (
@@ -117,6 +138,8 @@ CREATE INDEX IF NOT EXISTS idx_revisions_fingerprint ON revisions(fingerprint);
 CREATE INDEX IF NOT EXISTS idx_revisions_message_id ON revisions(message_id);
 
 """
+    + CHANGES_DDL
+    + ';'
     + SERIES_PATCHES_DDL
     + ';'
 )
@@ -164,6 +187,21 @@ def init_db(identifier: str) -> sqlite3.Connection:
     return conn
 
 
+def _drop_column(conn: sqlite3.Connection, table: str, col: str) -> None:
+    """Drop *col* from *table*, tolerating an sqlite too old to do it.
+
+    DROP COLUMN wants sqlite 3.35 (2021).  On anything older the column
+    simply stays, unread by everything above -- dead weight in the row, not
+    a correctness problem, and not worth a twelve-step table rebuild.
+
+    *table* and *col* are literals supplied by this module.
+    """
+    try:
+        conn.execute(f'ALTER TABLE {table} DROP COLUMN {col}')
+    except sqlite3.OperationalError as ex:
+        logger.debug('Could not drop %s.%s: %s', table, col, ex)
+
+
 def _migrate_db_if_needed(conn: sqlite3.Connection) -> None:
     """Apply any pending schema migrations in-place.
 
@@ -339,20 +377,12 @@ def _run_migrations(conn: sqlite3.Connection) -> None:
             # column left behind invites the next writer to keep it warm.
             # Inside the backfill guard on purpose: dropping a copy that
             # was never carried across would just lose it.
-            #
-            # DROP COLUMN wants sqlite 3.35 (2021).  On anything older the
-            # columns simply stay, unread by everything below -- dead
-            # weight in the row, not a correctness problem, and not worth
-            # a twelve-step table rebuild to reclaim.
             for col in (
                 'message_count',
                 'seen_message_count',
                 'last_update_check',
             ):
-                try:
-                    conn.execute(f'ALTER TABLE series DROP COLUMN {col}')
-                except sqlite3.OperationalError as ex:
-                    logger.debug('Could not drop series.%s: %s', col, ex)
+                _drop_column(conn, 'series', col)
         # Matching a posting by message-id became a hot lookup at v11 --
         # [l], [o] and the conflict check all run it -- and it was a full
         # table scan, unlike its fingerprint twin.
@@ -360,6 +390,27 @@ def _run_migrations(conn: sqlite3.Connection) -> None:
             'CREATE INDEX IF NOT EXISTS idx_revisions_message_id'
             ' ON revisions(message_id)'
         )
+    if version < 12:
+        # Per-change_id state gets its own table.  `branch_sha` describes
+        # the one b4/review/<change_id> branch, so a copy on every series
+        # row meant writing them all and reading back with ORDER BY
+        # revision DESC LIMIT 1 -- an arbitration between copies that only
+        # existed because the fact was stored per revision.
+        conn.execute(CHANGES_DDL)
+        series_cols = {row[1] for row in conn.execute('PRAGMA table_info(series)')}
+        if 'branch_sha' in series_cols:
+            # Highest revision wins, which is the row the old reader picked
+            # with ORDER BY revision DESC LIMIT 1.  A wrong sha here costs
+            # one extra tracking-commit read on the next rescan, so there is
+            # nothing to reconcile: it is a cache key, not data.
+            conn.execute(
+                'INSERT OR IGNORE INTO changes (change_id, branch_sha)'
+                ' SELECT change_id, ('
+                '  SELECT s.branch_sha FROM series s WHERE s.change_id ='
+                '  series.change_id ORDER BY s.revision DESC LIMIT 1)'
+                ' FROM series GROUP BY change_id'
+            )
+            _drop_column(conn, 'series', 'branch_sha')
     # Not an UPDATE: `version` is the primary key, so an UPDATE writes
     # nothing at all against an empty table -- and the read above maps "no
     # row" to version 0, so such a database would re-run the whole ladder
@@ -1453,6 +1504,52 @@ def record_known_revisions(
     conn.commit()
 
 
+def _set_change_state(conn: sqlite3.Connection, change_id: str, **cols: Any) -> None:
+    """Upsert per-change_id state, creating the `changes` row if needed.
+
+    A change_id acquires its row the first time something needs to
+    remember anything about it; nothing else has to keep the table in
+    step with `series`.
+
+    *cols* keys are column names supplied by the wrappers below, never
+    caller input.
+    """
+    assignments = ', '.join(f'{col} = ?' for col in cols)
+    conn.execute(
+        f'INSERT INTO changes (change_id, {", ".join(cols)})'
+        f' VALUES (?, {", ".join("?" for _ in cols)})'
+        f' ON CONFLICT (change_id) DO UPDATE SET {assignments}',
+        (change_id, *cols.values(), *cols.values()),
+    )
+    conn.commit()
+
+
+def set_branch_sha(conn: sqlite3.Connection, change_id: str, branch_sha: str) -> None:
+    """Record the review branch's HEAD, so a rescan can skip an unmoved branch."""
+    _set_change_state(conn, change_id, branch_sha=branch_sha)
+
+
+def get_branch_sha(conn: sqlite3.Connection, change_id: str) -> Optional[str]:
+    """The review branch HEAD recorded at the last rescan, if any."""
+    row = conn.execute(
+        'SELECT branch_sha FROM changes WHERE change_id = ?', (change_id,)
+    ).fetchone()
+    return str(row[0]) if row is not None and row[0] else None
+
+
+def forget_change_state(conn: sqlite3.Connection, change_id: str) -> None:
+    """Drop the per-change_id row once nothing tracks that change_id.
+
+    `changes` outlives `series` on its own -- nothing joins them -- so a
+    change_id that stops existing leaves a row behind carrying
+    back_searched=1 and a branch sha.  Re-tracking it then skips the
+    one-shot backward search for ever, which is the exact opposite of what
+    the latch is for, and a resurrected branch landing on the recorded sha
+    is skipped by rescan_branches.
+    """
+    conn.execute('DELETE FROM changes WHERE change_id = ?', (change_id,))
+
+
 def sync_revisions_catalog_to_branch(
     topdir: Optional[str], identifier: str, change_id: str
 ) -> bool:
@@ -1922,6 +2019,7 @@ def absorb_series_as_revision(
         conn.execute(
             'DELETE FROM series_patches WHERE change_id = ?', (stray_change_id,)
         )
+        forget_change_state(conn, stray_change_id)
     conn.commit()
     return True
 
@@ -3923,13 +4021,7 @@ def rescan_branches(
             continue
         current_sha = sha_out.strip()
 
-        # Check the stored SHA for the most recent revision of this change_id.
-        stored = conn.execute(
-            'SELECT branch_sha FROM series WHERE change_id = ?'
-            ' ORDER BY revision DESC LIMIT 1',
-            (change_id_from_branch,),
-        ).fetchone()
-        if stored and stored['branch_sha'] == current_sha:
+        if get_branch_sha(conn, change_id_from_branch) == current_sha:
             # Branch HEAD unchanged — skip the expensive tracking-commit read.
             scanned_change_ids.add(change_id_from_branch)
             continue
@@ -4021,11 +4113,7 @@ def rescan_branches(
         record_known_revisions(conn, change_id, tracking.get('known-revisions'))
 
         # Persist the new HEAD SHA so future rescans can skip this branch.
-        conn.execute(
-            'UPDATE series SET branch_sha = ? WHERE change_id = ? AND revision = ?',
-            (current_sha, change_id, revision),
-        )
-        conn.commit()
+        set_branch_sha(conn, change_id, str(current_sha))
 
         logger.info('Rescanned: %s (status: %s)', change_id, status)
         changed += 1
@@ -4072,8 +4160,15 @@ def delete_series(
             'DELETE FROM series_patches WHERE change_id = ? AND revision = ?',
             (change_id, revision),
         )
+        # Only once nothing is left: the other revisions still share the
+        # one branch, and the search latch still describes them.
+        if not conn.execute(
+            'SELECT COUNT(*) FROM series WHERE change_id = ?', (change_id,)
+        ).fetchone()[0]:
+            forget_change_state(conn, change_id)
     else:
         conn.execute('DELETE FROM revisions WHERE change_id = ?', (change_id,))
         conn.execute('DELETE FROM series WHERE change_id = ?', (change_id,))
         conn.execute('DELETE FROM series_patches WHERE change_id = ?', (change_id,))
+        forget_change_state(conn, change_id)
     conn.commit()
src/tests/test_review_tracking.py +2 -1
index f65bbb4d..8611cd3d 100644
@@ -1646,7 +1646,8 @@ class TestFollowupCounts:
         conn = review_tracking.get_db('fc-migration-test')
         cursor = conn.execute('PRAGMA table_info(series)')
         col_names = {row[1] for row in cursor.fetchall()}
-        assert 'branch_sha' in col_names
+        # branch_sha is added by v2 and rehomed to `changes` by v12.
+        assert 'branch_sha' not in col_names
         assert 'message_count' in col_names
         assert 'seen_message_count' in col_names
         assert 'last_update_check' in col_names
Signature · 1 line
2.53.0
#11 lore raw

RFC PATCH v2 11/25 review: test per-revision message tracking

In reply to Christian Brauner

Cover the v11 migration (column adds, catalog backfill from live and archived series rows, idempotence), the catalog-owned count reads, the per-revision poller (first fetch, a quiet poll that records the check without moving the counts, new-mail bump, error paths, skip statuses, tracked-row guarantee, least-recently-checked rotation and the cap, rethreaded first fetch and per-patch incremental, thread-blob caching and the stitched series blob a re-store must not discard), and the revision-aware writes in refresh_message_count() and sync_seen_from_unseen_count().

---
 src/tests/test_review_tracking.py | 2902 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 2901 insertions(+), 1 deletion(-)
src/tests/test_review_tracking.py +2901 -1
index 8611cd3d..c1f20649 100644
@@ -7,7 +7,7 @@ import pathlib
 import re
 import sqlite3
 from email.message import EmailMessage
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 from unittest import mock
 
 import pytest
@@ -1918,6 +1918,30 @@ class TestFollowupBlob:
         result = review_tracking.get_thread_mbox(gitdir, 'deadbeef' * 5)
         assert result is None
 
+    def test_store_revision_thread_blob_reports_a_missing_catalog_row(
+        self, gitdir: str, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A no-op UPDATE must not read as a stored blob.
+
+        The tracked revision is not guaranteed a catalog row, so a caller
+        handed a synthesized entry took the silent no-op for a cache write
+        and refetched from lore on every call.
+        """
+        conn = review_tracking.init_db('blob-no-row')
+        msgs = [_make_test_msg('[email protected]')]
+
+        assert (
+            review_tracking.store_revision_thread_blob(conn, gitdir, 'cid', 1, msgs)
+            is None
+        )
+
+        review_tracking.add_revision(conn, 'cid', 1, '[email protected]')
+        sha = review_tracking.store_revision_thread_blob(conn, gitdir, 'cid', 1, msgs)
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        assert sha
+        assert revs[0]['thread_blob'] == sha
+
 
 class TestPatchState:
     """Tests for _get_patch_state() and _set_patch_state()."""
@@ -3357,6 +3381,66 @@ class TestAbsorbSeriesAsRevision:
         conn.close()
         assert srow[0] == 0
 
+    def test_absorbing_the_last_series_row_rehomes_the_catalog(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """The stray's other catalogued versions move to the target.
+
+        A stray tracked online carries auto-discovered sibling versions,
+        and a rethreaded one's per-patch message-ids exist nowhere else.
+        Deleting them with the stray's last series row made [l] on a
+        multi-version stray a silent data-loss action.
+        """
+        conn = review_tracking.init_db('mrl-absorb-rehome-test')
+        review_tracking.add_revision(conn, 'series-A', 1, '[email protected]')
+        _seed_stray_series(conn, 'series-B', 2, 'fp-stray-b')
+        # The stray's catalog knows more than its series row: a
+        # rethreaded v1 colliding with the target's, and a plain v3.
+        review_tracking.add_revision(
+            conn,
+            'series-B',
+            1,
+            '[email protected]',
+            source='discovered',
+            is_rethreaded=True,
+        )
+        _insert_patches(
+            conn, 'series-B', 1, ['[email protected]', '[email protected]']
+        )
+        review_tracking.add_revision(
+            conn, 'series-B', 3, '[email protected]', source='discovered'
+        )
+
+        absorbed = review_tracking.absorb_series_as_revision(
+            conn, 'series-A', 'series-B', 2
+        )
+        assert absorbed is True
+
+        revs_a = {
+            r['revision']: r for r in review_tracking.get_revisions(conn, 'series-A')
+        }
+        assert sorted(revs_a) == [1, 2, 3]
+        # The colliding v1 keeps the target's own row, but rescues the
+        # stray's patch list the target lacked -- and the rethread flag
+        # behind which that list is read.
+        assert revs_a[1]['message_id'] == '[email protected]'
+        assert revs_a[1]['is_rethreaded']
+        patches = review_tracking.get_series_patches(conn, 'series-A', 1)
+        assert [p['message_id'] for p in patches] == [
+            '[email protected]',
+            '[email protected]',
+        ]
+        # The non-colliding v3 is re-homed whole, provenance included.
+        assert revs_a[3]['message_id'] == '[email protected]'
+        assert revs_a[3]['source'] == 'discovered'
+        # Nothing left under the stray.
+        assert review_tracking.get_revisions(conn, 'series-B') == []
+        leftovers = conn.execute(
+            "SELECT COUNT(*) FROM series_patches WHERE change_id = 'series-B'"
+        ).fetchone()
+        conn.close()
+        assert leftovers[0] == 0
+
     def test_absorb_missing_stray_is_noop(
         self, tmp_path: pytest.TempPathFactory
     ) -> None:
@@ -4382,6 +4466,36 @@ class TestKnownRevisionsCatalog:
             '[email protected]',
         ]
 
+    def test_the_posting_date_survives_the_round_trip(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """add_revision() defaults found_at to now, which is wrong on replay.
+
+        The catalog is rebuilt from the review branch on a second machine,
+        or after the database is deleted.  Dropping found_at on the way
+        through re-dates every version to the moment of the rebuild, so the
+        version rows and 'posted <date>' all read as today and v1 sorts
+        after vN -- the case found_at was added to prevent.
+        """
+        conn = review_tracking.init_db('rt-found-at')
+        review_tracking.add_revision(
+            conn, 'cid', 1, '[email protected]', found_at='2025-11-02T09:15:00+00:00'
+        )
+        review_tracking.add_revision(
+            conn, 'cid', 2, '[email protected]', found_at='2026-01-20T18:40:00+00:00'
+        )
+        known = review_tracking.build_known_revisions(conn, 'cid')
+        conn.close()
+
+        conn2 = review_tracking.init_db('rt-found-at2')
+        review_tracking.record_known_revisions(conn2, 'cid', known)
+        revs = review_tracking.get_revisions(conn2, 'cid')
+        conn2.close()
+
+        by_rev = {r['revision']: r['found_at'] for r in revs}
+        assert by_rev[1] == '2025-11-02T09:15:00+00:00'
+        assert by_rev[2] == '2026-01-20T18:40:00+00:00'
+
     def test_record_is_sticky_and_no_downgrade(
         self, tmp_path: pytest.TempPathFactory
     ) -> None:
@@ -5163,3 +5277,2789 @@ class TestUpgradeKeepsTheRethreadFlag:
         )
         conn.close()
         assert rows == {2: 1, 3: 0}
+
+
+def _make_legacy_v10_db(identifier: str) -> str:
+    """Create a schema-v10 database (revisions without count columns)."""
+    path = review_tracking.get_db_path(identifier)
+    conn = sqlite3.connect(path)
+    conn.executescript(
+        """
+        CREATE TABLE schema_version (version INTEGER PRIMARY KEY);
+        CREATE TABLE series (
+            track_id INTEGER PRIMARY KEY,
+            change_id TEXT NOT NULL,
+            revision INTEGER NOT NULL,
+            subject TEXT,
+            sender_name TEXT,
+            sender_email TEXT,
+            sent_at TEXT,
+            added_at TEXT,
+            message_id TEXT,
+            num_patches INTEGER,
+            pw_series_id INTEGER,
+            status TEXT DEFAULT 'new',
+            fingerprint TEXT,
+            branch_sha TEXT,
+            message_count INT,
+            seen_message_count INT,
+            last_update_check TEXT,
+            last_activity_at TEXT,
+            snoozed_until TEXT,
+            attestation TEXT DEFAULT 'pending',
+            target_branch TEXT,
+            is_rethreaded INTEGER DEFAULT 0,
+            UNIQUE (change_id, revision)
+        );
+        CREATE TABLE revisions (
+            change_id   TEXT NOT NULL,
+            revision    INTEGER NOT NULL,
+            message_id  TEXT NOT NULL,
+            subject     TEXT,
+            link        TEXT,
+            found_at    TEXT,
+            thread_blob TEXT,
+            fingerprint TEXT,
+            source      TEXT DEFAULT 'heuristic',
+            is_rethreaded INTEGER DEFAULT 0,
+            PRIMARY KEY (change_id, revision)
+        );
+        """
+    )
+    conn.execute('INSERT INTO schema_version (version) VALUES (10)')
+    # (i) live tracked series with counts and a matching catalog row,
+    # plus a catalog-only older revision.
+    conn.execute(
+        'INSERT INTO series (change_id, revision, subject, message_id, status,'
+        ' message_count, seen_message_count, last_update_check,'
+        ' last_activity_at, added_at)'
+        " VALUES ('cid-live', 2, 'live v2', 'live-v2@x', 'reviewing',"
+        " 8, 6, '2026-07-01T00:00:00+00:00', '2026-06-30T00:00:00+00:00',"
+        " '2026-06-01T00:00:00+00:00')"
+    )
+    conn.execute(
+        'INSERT INTO revisions (change_id, revision, message_id)'
+        " VALUES ('cid-live', 2, 'live-v2@x')"
+    )
+    conn.execute(
+        'INSERT INTO revisions (change_id, revision, message_id)'
+        " VALUES ('cid-live', 1, 'live-v1@x')"
+    )
+    # (ii) archived series row (upgrade leftover) with old counts.
+    conn.execute(
+        'INSERT INTO series (change_id, revision, message_id, status,'
+        ' message_count, seen_message_count)'
+        " VALUES ('cid-live', 1, 'live-v1@x', 'archived', 4, 1)"
+    )
+    # (iii) tracked series with no catalog row at all.
+    conn.execute(
+        'INSERT INTO series (change_id, revision, message_id, status,'
+        ' message_count, seen_message_count)'
+        " VALUES ('cid-norow', 3, 'norow-v3@x', 'new', 5, 5)"
+    )
+    # (iv) series row without a message-id.
+    conn.execute(
+        'INSERT INTO series (change_id, revision, message_id, status)'
+        " VALUES ('cid-nomsgid', 1, '', 'new')"
+    )
+    conn.commit()
+    conn.close()
+    return path
+
+
+class TestSchemaV11RevisionCounts:
+    """Schema v11: per-revision unread tracking lands on the catalog."""
+
+    def test_schema_version_at_least_11(self) -> None:
+        assert review_tracking.SCHEMA_VERSION >= 11
+
+    def test_new_db_has_count_columns(self, tmp_path: pytest.TempPathFactory) -> None:
+        conn = review_tracking.init_db('v11-cols')
+        cols = {row[1] for row in conn.execute('PRAGMA table_info(revisions)')}
+        conn.close()
+        assert {
+            'message_count',
+            'seen_message_count',
+            'last_update_check',
+            'last_mail_at',
+        } <= cols
+
+    def test_migration_adds_columns_and_bumps_version(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        _make_legacy_v10_db('v11-migrate')
+        conn = review_tracking.get_db('v11-migrate')  # runs migration on open
+        cols = {row[1] for row in conn.execute('PRAGMA table_info(revisions)')}
+        version = conn.execute('SELECT version FROM schema_version').fetchone()[0]
+        conn.close()
+        assert 'message_count' in cols
+        assert version == review_tracking.SCHEMA_VERSION
+
+    def test_migration_backfills_catalog_rows(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        _make_legacy_v10_db('v11-backfill')
+        conn = review_tracking.get_db('v11-backfill')
+        norow = review_tracking.get_revisions(conn, 'cid-norow')
+        nomsgid = review_tracking.get_revisions(conn, 'cid-nomsgid')
+        conn.close()
+        # The series row without a catalog entry gets one, carrying counts.
+        assert len(norow) == 1
+        assert norow[0]['message_id'] == 'norow-v3@x'
+        assert norow[0]['message_count'] == 5
+        assert norow[0]['seen_message_count'] == 5
+        # No catalog row is invented without a message-id.
+        assert nomsgid == []
+
+    def test_migration_seeds_existing_catalog_rows(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        _make_legacy_v10_db('v11-seed')
+        conn = review_tracking.get_db('v11-seed')
+        revs = {
+            r['revision']: r for r in review_tracking.get_revisions(conn, 'cid-live')
+        }
+        conn.close()
+        # v2 counts come from the live series row via the stitched read.
+        assert revs[2]['message_count'] == 8
+        assert revs[2]['seen_message_count'] == 6
+        # v1 counts were seeded from the archived series row (the only
+        # historical data) into the catalog columns.
+        assert revs[1]['message_count'] == 4
+        assert revs[1]['seen_message_count'] == 1
+
+    def test_migration_leaves_catalog_activity_unseeded(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """series.last_activity_at is not this version's newest mail.
+
+        It also records maintainer actions, so seeding last_mail_at from it
+        would date a version's thread from the last time someone snoozed
+        the series.  Left NULL until a poll reads a real Date: header --
+        and with one owner there is no second column to fall through to.
+        """
+        _make_legacy_v10_db('v11-activity')
+        conn = review_tracking.get_db('v11-activity')
+        raw = conn.execute(
+            'SELECT last_mail_at FROM revisions'
+            " WHERE change_id = 'cid-live' AND revision = 2"
+        ).fetchone()[0]
+        revs = {
+            r['revision']: r for r in review_tracking.get_revisions(conn, 'cid-live')
+        }
+        conn.close()
+        assert raw is None
+        # ...and the read reports exactly that, rather than borrowing the
+        # series' maintainer-action stamp.
+        assert revs[2]['last_mail_at'] is None
+
+    def test_migration_idempotent(self, tmp_path: pytest.TempPathFactory) -> None:
+        _make_legacy_v10_db('v11-idem')
+        review_tracking.get_db('v11-idem').close()
+        conn = review_tracking.get_db('v11-idem')
+        nrevs = conn.execute('SELECT COUNT(*) FROM revisions').fetchone()[0]
+        version = conn.execute('SELECT version FROM schema_version').fetchone()[0]
+        conn.close()
+        assert nrevs == 3
+        assert version == review_tracking.SCHEMA_VERSION
+
+
+class TestStitchedRevisionReads:
+    """Per-revision counts stitch series (live) over catalog columns."""
+
+    def test_counts_come_from_the_catalog_row(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """One owner, so there is no second copy for a reader to prefer."""
+        conn = review_tracking.init_db('stitch-live')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        conn.execute(
+            'UPDATE revisions SET message_count = 10, seen_message_count = 7'
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        assert revs[0]['message_count'] == 10
+        assert revs[0]['seen_message_count'] == 7
+
+    def test_rethread_flag_is_stitched_too(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """It picks the retrieval path, so both rows must agree on it.
+
+        'e' on the tracked revision's own version row would otherwise
+        reassemble a different thread than 'e' on the series row directly
+        above it.
+        """
+        conn = review_tracking.init_db('stitch-rethread')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+            is_rethreaded=True,
+        )
+        # The catalog row predates the rethread being recognised.
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.commit()
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        assert bool(revs[0]['is_rethreaded'])
+
+    def test_archived_series_does_not_shadow(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        conn = review_tracking.init_db('stitch-arch')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=1,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v1@x',
+            num_patches=1,
+        )
+        conn.execute(
+            'UPDATE revisions SET message_count = 4, seen_message_count = 0'
+            " WHERE change_id = 'cid'"
+        )
+        conn.execute("UPDATE series SET status = 'archived' WHERE change_id = 'cid'")
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 6, seen_message_count = 6'
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        assert revs[0]['message_count'] == 6
+        assert revs[0]['seen_message_count'] == 6
+
+    def test_null_series_counts_fall_back(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        conn = review_tracking.init_db('stitch-null')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 9, seen_message_count = 9'
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        assert revs[0]['message_count'] == 9
+        assert revs[0]['seen_message_count'] == 9
+
+    def test_grouped_returns_full_columns(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        conn = review_tracking.init_db('stitch-grouped')
+        review_tracking.add_revision(
+            conn, 'cid', 1, 'v1@x', fingerprint='fp1', is_rethreaded=True
+        )
+        grouped = review_tracking.get_all_revisions_grouped(conn)
+        conn.close()
+        entry = grouped['cid'][0]
+        assert entry['is_rethreaded']
+        assert entry['fingerprint'] == 'fp1'
+        assert entry['source'] == 'heuristic'
+        assert entry['message_count'] is None
+
+    def test_series_list_agrees_with_its_own_version_row(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """The tracker list and the version rows read the same numbers.
+
+        An upgrade clears the series row's counts, so a raw read renders
+        the parent as '-' while the child row for that very revision,
+        sourced from the catalog, shows a count.
+        """
+        conn = review_tracking.init_db('stitch-list')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='[PATCH v2] thing',
+            sender_name='S',
+            sender_email='[email protected]',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        review_tracking.add_revision(conn, 'cid', 3, 'v3@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 20, seen_message_count = 12'
+            " WHERE change_id = 'cid' AND revision = 3"
+        )
+        conn.commit()
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, 'v3@x')
+        grouped = review_tracking.get_all_revisions_grouped(conn)
+        conn.close()
+
+        series = {
+            s['change_id']: s
+            for s in review_tracking.get_all_tracked_series('stitch-list')
+        }['cid']
+        child = {r['revision']: r for r in grouped['cid']}[3]
+        assert series['revision'] == 3
+        assert series['message_count'] == child['message_count'] == 20
+        assert series['seen_message_count'] == child['seen_message_count'] == 12
+
+
+def _thread_msgs(count: int, base: str = 'm') -> list[EmailMessage]:
+    """Build a minimal thread of EmailMessage objects with Date headers."""
+    msgs = []
+    for i in range(count):
+        msg = EmailMessage()
+        msg['Subject'] = f'Re: thread {i}'
+        msg['From'] = 'Dev <[email protected]>'
+        msg['Message-Id'] = f'<{base}-{i}@example.com>'
+        msg['Date'] = f'Thu, {i + 1:02d} Jul 2026 08:00:00 +0000'
+        msg.set_payload('body\n')
+        msgs.append(msg)
+    return msgs
+
+
+def _poller_series(
+    change_id: str, revision: int, message_id: str, status: str = 'new'
+) -> Dict[str, Any]:
+    """Series dict shaped like the TUI's loaded rows, for the poller."""
+    return {
+        'change_id': change_id,
+        'revision': revision,
+        'message_id': message_id,
+        'subject': 'test subject',
+        'status': status,
+    }
+
+
+class TestFailedPollsSpendTheBudget:
+    """The cap counts lore round-trips, and a fetch that fails made one.
+
+    Two deliberate rules combine badly otherwise: naming the revisions
+    lifts the two-in-a-row break (dead message-ids are exactly what a
+    backward search turns up), so a version whose ids all 404 walked every
+    one of them however small the cap.
+    """
+
+    @staticmethod
+    def _seed(identifier: str) -> None:
+        conn = review_tracking.init_db(identifier)
+        for rev in (1, 2, 3, 4, 5):
+            review_tracking.add_revision(conn, 'cid', rev, f'v{rev}@x')
+        conn.close()
+
+    def _run(
+        self, identifier: str, monkeypatch: pytest.MonkeyPatch, online: bool
+    ) -> list[int]:
+        self._seed(identifier)
+        tried: list[int] = []
+
+        def _fail(ident: str, conn: Any, change_id: str, rev: Dict[str, Any]) -> None:
+            tried.append(int(rev['revision']))
+            return None
+
+        monkeypatch.setattr(b4, 'can_network', online)
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _fail)
+        review_tracking.update_revision_message_counts(
+            identifier,
+            [_poller_series('cid', 6, 'v6@x')],
+            only_revisions={1, 2, 3, 4, 5},
+            max_revisions_per_series=2,
+        )
+        return tried
+
+    def test_the_cap_bounds_a_run_of_failures(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        assert len(self._run('poll-budget', monkeypatch, online=True)) == 2
+
+    def test_offline_spends_nothing(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """No request was made, so there is no round-trip to charge for.
+
+        Charging them would make an offline sweep look like a series that
+        had used up its budget, and the revisions behind the cap would wait
+        a sweep for nothing.
+        """
+        assert len(self._run('poll-budget-off', monkeypatch, online=False)) == 5
+
+
+class TestUpdateRevisionMessageCounts:
+    """The per-revision poller for non-tracked versions."""
+
+    def test_first_fetch_initializes_counts(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-first')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='test subject',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        # Leave only the manual-link gap the backfill exists to close.
+        conn.execute('DELETE FROM revisions WHERE revision = 2')
+        conn.commit()
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.close()
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(3),
+        )
+        result = review_tracking.update_revision_message_counts(
+            'poll-first', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result == {
+            'updated': 1,
+            'new_mail': 0,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 1,
+            'cancelled': 0,
+        }
+        conn = review_tracking.get_db('poll-first')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[1]['message_count'] == 3
+        assert revs[1]['seen_message_count'] == 3
+        assert revs[1]['last_update_check'] is not None
+        assert revs[1]['last_mail_at'] is not None
+        # The tracked revision's row was backfilled but not polled.
+        assert revs[2]['message_count'] is None
+
+    def test_quiet_poll_leaves_the_counts_alone(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A quiet revision records the check but not a new count.
+
+        The check has to be recorded or the poll rotation never advances
+        past it (see TestPollCapFairness); what must not move is the
+        count/seen pair the unread badge is derived from.
+        """
+        conn = review_tracking.init_db('poll-quiet')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 5, seen_message_count = 3,'
+            " last_update_check = '2026-07-01T00:00:00+00:00',"
+            " last_mail_at = '2026-06-30T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        # The refetch finds the same 5 messages.
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(5),
+        )
+        result = review_tracking.update_revision_message_counts(
+            'poll-quiet', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result == {
+            'updated': 0,
+            'new_mail': 0,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 1,
+            'cancelled': 0,
+        }
+        conn = review_tracking.get_db('poll-quiet')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        # The badge is untouched: still 2 unseen, and no fresh activity.
+        assert revs[1]['message_count'] == 5
+        assert revs[1]['seen_message_count'] == 3
+        assert revs[1]['last_mail_at'] == '2026-06-30T00:00:00+00:00'
+        # But the rotation moved on.
+        assert revs[1]['last_update_check'] > '2026-07-01T00:00:00+00:00'
+
+    def test_a_shorter_thread_still_becomes_the_cached_thread(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """thread_blob is "the thread as it last looked", so the fetch wins.
+
+        Threads do shrink, and the blob is what the next sweep diffs
+        against to decide which messages are new -- keeping a fuller older
+        snapshot would re-count the difference as fresh mail for ever.  A
+        range-diff is not what this column answers: that reads
+        ``series_blob``, which :func:`set_revision_thread_blob` leaves
+        alone unless the thread itself changed.
+        """
+        conn = review_tracking.init_db('poll-blobshrink')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 4, seen_message_count = 4,'
+            " thread_blob = 'cafebabe'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(1),
+        )
+        stored: list[int] = []
+        monkeypatch.setattr(
+            review_tracking,
+            'store_revision_thread_blob',
+            lambda conn, topdir, change_id, revision, msgs: stored.append(len(msgs)),
+        )
+        review_tracking.update_revision_message_counts(
+            'poll-blobshrink', [_poller_series('cid', 2, 'v2@x')], topdir='/nonexistent'
+        )
+        conn = review_tracking.get_db('poll-blobshrink')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert (revs[1]['message_count'], revs[1]['seen_message_count']) == (1, 1)
+        assert stored == [1]
+
+    def test_a_changed_thread_drops_the_stitched_series_blob(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A stitch is only as good as the thread it was built from.
+
+        The patch that made a version unstitchable may be exactly what
+        just landed, so a new thread retires the series blob built from
+        the old one and the next range-diff stitches again.
+        """
+        conn = review_tracking.init_db('poll-blobstitch')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 4, seen_message_count = 4,'
+            " thread_blob = 'cafebabe', series_blob = 'deadbeef'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(6),
+        )
+        monkeypatch.setattr(
+            review_tracking, '_write_mbox_blob', lambda topdir, msgs: 'feedface'
+        )
+        review_tracking.update_revision_message_counts(
+            'poll-blobstitch', [_poller_series('cid', 2, 'v2@x')], topdir='/nonexistent'
+        )
+        conn = review_tracking.get_db('poll-blobstitch')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[1]['thread_blob'] == 'feedface'
+        assert revs[1]['series_blob'] is None
+
+    def test_an_unchanged_thread_keeps_the_stitched_series_blob(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Re-storing the same thread must not throw the stitch away.
+
+        The blob is content-addressed, so a thread that has not moved
+        hashes to the SHA already on the row -- and a sweep that retired
+        the series blob on every such write would undo the caching it
+        exists to provide.
+        """
+        conn = review_tracking.init_db('poll-blobkeep')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 4, seen_message_count = 4,'
+            " thread_blob = 'cafebabe', series_blob = 'deadbeef'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        assert (
+            review_tracking.set_revision_thread_blob(
+                review_tracking.get_db('poll-blobkeep'), 'cid', 1, 'cafebabe'
+            )
+            is True
+        )
+        conn = review_tracking.get_db('poll-blobkeep')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[1]['series_blob'] == 'deadbeef'
+
+    def test_a_cancel_between_series_is_reported(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """The outer cancel check must not present a clean, complete sweep."""
+        review_tracking.init_db('poll-cancel-outer').close()
+        result = review_tracking.update_revision_message_counts(
+            'poll-cancel-outer',
+            [_poller_series('cid', 2, 'v2@x')],
+            cancel_cb=lambda: True,
+        )
+        assert result['cancelled'] == 1
+        assert result['polled'] == 0
+
+    def test_a_missing_db_returns_the_documented_contract(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """The early return carries every key the docstring promises."""
+        result = review_tracking.update_revision_message_counts(
+            'poll-no-such-db', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result == {
+            'updated': 0,
+            'new_mail': 0,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 0,
+            'cancelled': 0,
+        }
+
+    def test_first_fetch_is_not_reported_as_new_mail(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Two revisions never counted before, plus one that got mail.
+
+        The sweep summary quotes 'new_mail', so a catalog that has just
+        grown per-revision columns must not read as activity everywhere.
+        """
+        conn = review_tracking.init_db('poll-firstmail')
+        for rev, msgid in ((1, 'v1@x'), (2, 'v2@x'), (3, 'v3@x')):
+            review_tracking.add_revision(conn, 'cid', rev, msgid)
+        conn.execute(
+            'UPDATE revisions SET message_count = 5, seen_message_count = 5,'
+            " last_update_check = '2026-07-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        conn.close()
+        # v1 has never been counted; v2 was at 5 and has grown to 7.
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(
+                7 if int(rev['revision']) == 2 else 2
+            ),
+        )
+        result = review_tracking.update_revision_message_counts(
+            'poll-firstmail', [_poller_series('cid', 3, 'v3@x')]
+        )
+        assert result == {
+            'updated': 2,
+            'new_mail': 1,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 2,
+            'cancelled': 0,
+        }
+
+    def test_new_mail_bumps_count(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-new')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 5, seen_message_count = 5,'
+            " last_update_check = '2026-07-01T00:00:00+00:00',"
+            " last_mail_at = '2026-06-30T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(7),
+        )
+        result = review_tracking.update_revision_message_counts(
+            'poll-new', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result == {
+            'updated': 1,
+            'new_mail': 1,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 1,
+            'cancelled': 0,
+        }
+        conn = review_tracking.get_db('poll-new')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[1]['message_count'] == 7
+        assert revs[1]['seen_message_count'] == 5
+        assert revs[1]['last_mail_at'] > '2026-06-30T00:00:00+00:00'
+        assert revs[1]['last_update_check'] > '2026-07-01T00:00:00+00:00'
+
+    def test_fetch_error_counts_error(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-err')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 5, seen_message_count = 5,'
+            " last_update_check = '2026-07-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: None,
+        )
+        result = review_tracking.update_revision_message_counts(
+            'poll-err', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result == {
+            'updated': 0,
+            'new_mail': 0,
+            'errors': 1,
+            'fresh_errors': 1,
+            'polled': 0,
+            'cancelled': 0,
+        }
+        conn = review_tracking.get_db('poll-err')
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        assert revs[0]['message_count'] == 5
+
+    def test_skip_statuses_not_polled(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-skip')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.close()
+        calls: list[int] = []
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: calls.append(rev['revision']),
+        )
+        for status in ('archived', 'snoozed'):
+            result = review_tracking.update_revision_message_counts(
+                'poll-skip', [_poller_series('cid', 2, 'v2@x', status=status)]
+            )
+            assert result == {
+                'updated': 0,
+                'new_mail': 0,
+                'errors': 0,
+                'fresh_errors': 0,
+                'polled': 0,
+                'cancelled': 0,
+            }
+        assert calls == []
+
+    def test_applied_series_is_still_polled(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A late reply to an old version still counts once a series lands.
+
+        The tracked revision is deliberately polled past 'accepted' so
+        follow-up discussion on an applied series keeps raising a badge;
+        its older versions must not be dropped at the same moment.
+        """
+        conn = review_tracking.init_db('poll-applied')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.close()
+        calls: list[int] = []
+
+        def _fetch(identifier: str, conn: Any, change_id: str, rev: Any) -> Any:
+            calls.append(int(rev['revision']))
+            return _thread_msgs(3)
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _fetch)
+        for status in ('accepted', 'thanked'):
+            calls.clear()
+            # The first pass stamps the check; age it back out so the
+            # second status is not skipped by the minimum-interval gate.
+            conn = review_tracking.get_db('poll-applied')
+            conn.execute('UPDATE revisions SET last_update_check = NULL')
+            conn.commit()
+            conn.close()
+            review_tracking.update_revision_message_counts(
+                'poll-applied', [_poller_series('cid', 2, 'v2@x', status=status)]
+            )
+            assert calls == [1]
+
+    def test_tracked_revision_not_polled(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-tracked')
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.close()
+        calls: list[int] = []
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: calls.append(rev['revision']),
+        )
+        result = review_tracking.update_revision_message_counts(
+            'poll-tracked', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result == {
+            'updated': 0,
+            'new_mail': 0,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 0,
+            'cancelled': 0,
+        }
+        assert calls == []
+
+    def test_tracked_row_backfilled_when_missing(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Seeded from the series table, the authority the dict mirrors."""
+        conn = review_tracking.init_db('poll-backfill')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='test subject',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        # Simulate the manual-link gap: the series row exists, its
+        # revision's catalog row does not.
+        conn.execute('DELETE FROM revisions')
+        conn.commit()
+        conn.close()
+        review_tracking.update_revision_message_counts(
+            'poll-backfill', [_poller_series('cid', 2, 'v2@x')]
+        )
+        conn = review_tracking.get_db('poll-backfill')
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        assert len(revs) == 1
+        assert revs[0]['revision'] == 2
+        assert revs[0]['message_id'] == 'v2@x'
+        assert revs[0]['message_count'] is None
+
+    def test_a_recent_check_is_skipped(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Below the cap the rotation never engages; the age floor must.
+
+        With every candidate under the cap, an uncapped rotation re-fetches
+        each quiet old version's full thread on every sweep just to learn
+        it is still quiet -- thousands of lore round-trips a day on a
+        30-minute cron for a list of any size.
+        """
+        recent = datetime.datetime.now(datetime.timezone.utc).isoformat()
+        conn = review_tracking.init_db('poll-fresh')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 5, seen_message_count = 5,'
+            ' last_update_check = ?',
+            (recent,),
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: pytest.fail(
+                'a freshly checked revision must not be fetched'
+            ),
+        )
+        result = review_tracking.update_revision_message_counts(
+            'poll-fresh', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result['polled'] == 0
+
+    def test_named_revisions_bypass_the_age_floor(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """only_revisions means the caller is asking right now."""
+        recent = datetime.datetime.now(datetime.timezone.utc).isoformat()
+        conn = review_tracking.init_db('poll-named')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 5, seen_message_count = 5,'
+            ' last_update_check = ?',
+            (recent,),
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(5),
+        )
+        result = review_tracking.update_revision_message_counts(
+            'poll-named', [_poller_series('cid', 2, 'v2@x')], only_revisions={1}
+        )
+        assert result['polled'] == 1
+
+    def test_newest_first_with_cap(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-cap')
+        for rev in (1, 2, 3, 4):
+            review_tracking.add_revision(conn, 'cid', rev, f'v{rev}@x')
+        conn.close()
+        polled: list[int] = []
+
+        def _fake_fetch(
+            identifier: str, conn: Any, change_id: str, rev: Dict[str, Any]
+        ) -> list[EmailMessage]:
+            polled.append(int(rev['revision']))
+            return _thread_msgs(2)
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _fake_fetch)
+        result = review_tracking.update_revision_message_counts(
+            'poll-cap',
+            [_poller_series('cid', 4, 'v4@x')],
+            max_revisions_per_series=1,
+        )
+        assert result == {
+            'updated': 1,
+            'new_mail': 0,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 1,
+            'cancelled': 0,
+        }
+        assert polled == [3]
+
+    def test_rethreaded_first_fetch_reassembles(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-rt-first')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x', is_rethreaded=True)
+        _insert_patches(conn, 'cid', 1, ['p1@x', 'p2@x'])
+        conn.close()
+        seen_dicts: list[Dict[str, Any]] = []
+
+        def _fake_retrieve(
+            series: Dict[str, Any], identifier: str
+        ) -> list[EmailMessage]:
+            seen_dicts.append(series)
+            return _thread_msgs(4)
+
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(b4.review, 'retrieve_series_messages', _fake_retrieve)
+        result = review_tracking.update_revision_message_counts(
+            'poll-rt-first', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result == {
+            'updated': 1,
+            'new_mail': 0,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 1,
+            'cancelled': 0,
+        }
+        assert seen_dicts and seen_dicts[0]['is_rethreaded'] is True
+        assert seen_dicts[0]['revision'] == 1
+        conn = review_tracking.get_db('poll-rt-first')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[1]['message_count'] == 4
+
+    def test_rethreaded_recount_reassembles_from_patches(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """An already-counted rethreaded revision recounts the same way.
+
+        Summing per-patch queries counted a reply CC'd into several patch
+        threads once per thread; reassembly dedupes it.
+        """
+        conn = review_tracking.init_db('poll-rt-incr')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x', is_rethreaded=True)
+        _insert_patches(conn, 'cid', 1, ['p1@x', 'p2@x'])
+        conn.execute(
+            'UPDATE revisions SET message_count = 6, seen_message_count = 6,'
+            " last_update_check = '2026-07-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        seen_series: list[Dict[str, Any]] = []
+
+        def _reassemble(series: Dict[str, Any], identifier: str) -> list[EmailMessage]:
+            seen_series.append(series)
+            return _thread_msgs(8)
+
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(b4.review, 'retrieve_series_messages', _reassemble)
+        result = review_tracking.update_revision_message_counts(
+            'poll-rt-incr', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert result == {
+            'updated': 1,
+            'new_mail': 1,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 1,
+            'cancelled': 0,
+        }
+        assert [s['revision'] for s in seen_series] == [1]
+        assert seen_series[0]['is_rethreaded'] is True
+        conn = review_tracking.get_db('poll-rt-incr')
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        assert revs[0]['message_count'] == 8
+        # Seen is untouched, so the two new messages raise a badge.
+        assert revs[0]['seen_message_count'] == 6
+
+    def test_first_fetch_stores_blob_with_topdir(
+        self, gitdir: str, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-blob')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.close()
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(2),
+        )
+        review_tracking.update_revision_message_counts(
+            'poll-blob', [_poller_series('cid', 2, 'v2@x')], topdir=gitdir
+        )
+        conn = review_tracking.get_db('poll-blob')
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        blob_sha = revs[0]['thread_blob']
+        assert blob_sha
+        mbox = review_tracking.get_thread_mbox(gitdir, blob_sha)
+        assert mbox is not None
+        assert b'[email protected]' in mbox
+
+
+class TestRevisionAwareSyncHelpers:
+    """refresh_message_count / sync_seen fall back to the catalog."""
+
+    def _seed(self, identifier: str) -> None:
+        conn = review_tracking.init_db(identifier)
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        conn.execute(
+            'UPDATE revisions SET message_count = 8, seen_message_count = 8'
+            " WHERE change_id = 'cid'"
+        )
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 6, seen_message_count = 6'
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.execute(
+            'UPDATE revisions SET message_count = 3, seen_message_count = 3'
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        conn.close()
+
+    def test_sync_seen_writes_the_named_revisions_row(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """No routing decision left: the revision named is the row written."""
+        self._seed('sync-live')
+        assert review_tracking.sync_seen_from_unseen_count('sync-live', 'cid', 2, 2)
+        conn = review_tracking.get_db('sync-live')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        # v2 holds 3 messages, 2 of them unseen.
+        assert revs[2]['seen_message_count'] == 1
+        # ...and the version beside it is untouched.
+        assert revs[1]['seen_message_count'] == 6
+
+    def test_sync_seen_falls_back_to_catalog(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        self._seed('sync-fall')
+        assert review_tracking.sync_seen_from_unseen_count('sync-fall', 'cid', 1, 4)
+        conn = review_tracking.get_db('sync-fall')
+        rev_seen = conn.execute(
+            'SELECT seen_message_count FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 1"
+        ).fetchone()[0]
+        conn.close()
+        assert rev_seen == 2
+
+    def test_sync_seen_ignores_the_series_status(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """An archived series row used to shadow, then have to be excluded.
+
+        Read state never sat on it, so its status cannot affect a badge and
+        the write needs no guard against it.
+        """
+        self._seed('sync-arch')
+        conn = review_tracking.get_db('sync-arch')
+        review_tracking.update_series_status(conn, 'cid', 'archived')
+        conn.close()
+        assert review_tracking.sync_seen_from_unseen_count('sync-arch', 'cid', 2, 1)
+        conn = review_tracking.get_db('sync-arch')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[2]['seen_message_count'] == 2
+
+    def test_sync_seen_no_rows_returns_false(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        review_tracking.init_db('sync-none').close()
+        assert not review_tracking.sync_seen_from_unseen_count('sync-none', 'cid', 9, 1)
+
+    def test_refresh_count_falls_back_to_catalog(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        conn = review_tracking.init_db('refresh-fall')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.close()
+        assert review_tracking.refresh_message_count('refresh-fall', 'cid', 1, 7)
+        conn = review_tracking.get_db('refresh-fall')
+        revs = review_tracking.get_revisions(conn, 'cid')
+        conn.close()
+        # First fetch initialises both counts equally (no badge).
+        assert revs[0]['message_count'] == 7
+        assert revs[0]['seen_message_count'] == 7
+
+    def test_refresh_count_unchanged_writes_nothing(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A count that has not moved leaves the DB mtime alone."""
+        self._seed('refresh-skip')
+        assert not review_tracking.refresh_message_count('refresh-skip', 'cid', 2, 3)
+
+    def test_mark_all_messages_seen_clears_the_badge(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """One row to clear, and its own total is what the badge showed."""
+        self._seed('mark-rev')
+        conn = review_tracking.get_db('mark-rev')
+        conn.execute(
+            'UPDATE revisions SET seen_message_count = 1'
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        review_tracking.mark_all_messages_seen(conn, 'cid', 2)
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[2]['seen_message_count'] == revs[2]['message_count'] == 3
+        # The other version keeps whatever it had.
+        assert revs[1]['seen_message_count'] == 6
+
+    def test_marking_seen_uses_the_rows_own_total(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """The count on the row is the count that was displayed.
+
+        This used to need a clamp: the badge came from a stitched read, so
+        a catalog row that ran ahead of the series row held messages the
+        list never showed.  With one copy the two cannot diverge.
+        """
+        self._seed('mark-ahead')
+        conn = review_tracking.get_db('mark-ahead')
+        conn.execute(
+            'UPDATE revisions SET message_count = 14, seen_message_count = 10'
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        assert revs[2]['message_count'] == 14
+        review_tracking.mark_all_messages_seen(conn, 'cid', 2)
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[2]['seen_message_count'] == 14
+
+
+class TestRevisionCountsSurviveSeriesMoves:
+    """A series row only holds the tracked revision's counts.
+
+    Re-pointing or retiring one must hand that read state to the catalog,
+    which is where every non-tracked revision keeps it.
+    """
+
+    def _seed(self, identifier: str, revision: int = 2) -> sqlite3.Connection:
+        conn = review_tracking.init_db(identifier)
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=revision,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id=f'v{revision}@x',
+            num_patches=3,
+        )
+        conn.execute(
+            'UPDATE revisions SET message_count = 12, seen_message_count = 9,'
+            " last_update_check = '2026-06-05T00:00:00+00:00',"
+            " last_mail_at = '2026-06-04T00:00:00+00:00'"
+            ' WHERE change_id = ? AND revision = ?',
+            ('cid', revision),
+        )
+        conn.commit()
+        return conn
+
+    def test_upgrade_parks_counts_in_catalog(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        conn = self._seed('carry-upgrade')
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, 'v3@x')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[2]['message_count'] == 12
+        assert revs[2]['seen_message_count'] == 9
+        assert revs[2]['message_id'] == 'v2@x'
+        assert revs[2]['last_mail_at'] == '2026-06-04T00:00:00+00:00'
+
+    def test_upgrade_defers_to_a_newer_catalog_row(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        conn = self._seed('carry-nooverwrite')
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 20, seen_message_count = 20,'
+            " last_update_check = '2026-06-09T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, 'v3@x')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[2]['message_count'] == 20
+
+    def test_an_upgrade_leaves_the_old_revision_alone(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Nothing is copied on an upgrade, so nothing can overwrite.
+
+        The outgoing revision's counts were never on the series row: they
+        are its own, and moving off it does not touch them.
+        """
+        conn = self._seed('carry-overwrite')
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 8, seen_message_count = 8,'
+            " last_update_check = '2026-06-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, 'v3@x')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[2]['message_count'] == 8
+        assert revs[2]['seen_message_count'] == 8
+        assert revs[2]['last_update_check'] == '2026-06-01T00:00:00+00:00'
+
+    def test_an_upgrade_needs_no_staleness_check(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Which copy is newer was only ever a question with two copies."""
+        conn = self._seed('carry-untimed')
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 20, seen_message_count = 20'
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, 'v3@x')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        # No timestamp anywhere, and still unambiguous.
+        assert revs[2]['message_count'] == 20
+
+    def test_absorb_carries_stray_counts(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        conn = review_tracking.init_db('carry-absorb')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='target',
+            revision=3,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v3@x',
+            num_patches=3,
+        )
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='stray',
+            revision=2,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-05-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=3,
+        )
+        conn.execute(
+            'UPDATE revisions SET message_count = 15, seen_message_count = 11'
+            " WHERE change_id = 'stray'"
+        )
+        conn.commit()
+        assert review_tracking.absorb_series_as_revision(conn, 'target', 'stray', 2)
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'target')}
+        conn.close()
+        assert revs[2]['message_count'] == 15
+        assert revs[2]['seen_message_count'] == 11
+
+    def test_absorb_carries_counts_held_only_by_the_catalog(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A stray's counts commonly live in its own catalog row.
+
+        The per-revision read COALESCEs over both tables, so a stray whose
+        series row never carried counts still displays them -- and absorb
+        deletes that catalog row, so reading only the series row drops the
+        state the user was looking at.
+        """
+        conn = review_tracking.init_db('carry-absorb-catalog')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='target',
+            revision=3,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v3@x',
+            num_patches=3,
+        )
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='stray',
+            revision=2,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-05-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=3,
+        )
+        review_tracking.add_revision(conn, 'stray', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 12, seen_message_count = 5'
+            " WHERE change_id = 'stray' AND revision = 2"
+        )
+        conn.commit()
+        assert review_tracking.absorb_series_as_revision(conn, 'target', 'stray', 2)
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'target')}
+        conn.close()
+        assert revs[2]['message_count'] == 12
+        assert revs[2]['seen_message_count'] == 5
+
+    def test_absorb_uses_the_revision_the_caller_matched(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A stray tracked across versions must not contribute the wrong one."""
+        conn = review_tracking.init_db('carry-absorb-multi')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='target',
+            revision=5,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='t5@x',
+            num_patches=3,
+        )
+        for rev, count in ((2, 4), (3, 30)):
+            review_tracking.add_series_to_db(
+                conn,
+                change_id='stray',
+                revision=rev,
+                subject='s',
+                sender_name='n',
+                sender_email='e@x',
+                sent_at='2026-06-01T00:00:00+00:00',
+                message_id=f'stray-v{rev}@x',
+                num_patches=1,
+            )
+            conn.execute(
+                'UPDATE revisions SET message_count = ?, seen_message_count = 0'
+                " WHERE change_id = 'stray' AND revision = ?",
+                (count, rev),
+            )
+        conn.commit()
+        assert review_tracking.absorb_series_as_revision(
+            conn, 'target', 'stray', 2, stray_revision=2
+        )
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'target')}
+        conn.close()
+        # v3's message-id and counts must not arrive labelled as v2.
+        assert revs[2]['message_id'] == 'stray-v2@x'
+        assert revs[2]['message_count'] == 4
+
+    def test_absorb_refuses_a_revision_the_stray_does_not_track(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A named revision is the only candidate, never a hint.
+
+        The catalog can hold a revision the stray never had a series row
+        for, and falling back to another of its versions would file that
+        posting under the message-id the caller matched.
+        """
+        conn = review_tracking.init_db('carry-absorb-missing')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='target',
+            revision=5,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='t5@x',
+            num_patches=3,
+        )
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='stray',
+            revision=3,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='stray-v3@x',
+            num_patches=1,
+        )
+        conn.execute(
+            'UPDATE revisions SET message_count = 30, seen_message_count = 0'
+            " WHERE change_id = 'stray' AND revision = 3"
+        )
+        conn.commit()
+
+        assert (
+            review_tracking.absorb_series_as_revision(
+                conn, 'target', 'stray', 2, stray_revision=2
+            )
+            is False
+        )
+        revs = review_tracking.get_revisions(conn, 'target')
+        stray_rows = conn.execute(
+            "SELECT COUNT(*) FROM series WHERE change_id = 'stray'"
+        ).fetchone()[0]
+        conn.close()
+        # The refused absorb recorded nothing, and the stray is untouched --
+        # v3's message-id must not turn up labelled v2.  The target's own
+        # v5 row is there because tracking a series catalogues the revision
+        # it tracks, which is where that revision's read state lives.
+        assert [r['revision'] for r in revs] == [5]
+        assert stray_rows == 1
+
+    def test_archiving_parks_counts_in_catalog(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Upgrading a checked-out series archives the outgoing row.
+
+        Per-revision reads skip archived rows, so the counts have to
+        reach the catalog before the status flips.
+        """
+        conn = self._seed('carry-archive', revision=1)
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        review_tracking.update_series_status(conn, 'cid', 'archived', revision=1)
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-10T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=3,
+        )
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[1]['message_count'] == 12
+        assert revs[1]['seen_message_count'] == 9
+
+    def test_archiving_backfills_a_missing_catalog_row(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A manually linked series can lack a catalog row entirely."""
+        conn = self._seed('carry-archive-nocatalog', revision=1)
+        review_tracking.update_series_status(conn, 'cid', 'archived')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[1]['message_id'] == 'v1@x'
+        assert revs[1]['message_count'] == 12
+        assert revs[1]['seen_message_count'] == 9
+
+    def test_parking_dates_the_revision_it_retires(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """found_at is when the version was posted, not when it was retired."""
+        conn = self._seed('carry-founddate', revision=2)
+        conn.execute(
+            "UPDATE series SET added_at = '2026-06-02T00:00:00+00:00'"
+            " WHERE change_id = 'cid'"
+        )
+        conn.commit()
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, 'v3@x')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        # Dating it now would sort the older version after the newer one, and
+        # dating it added_at reports when tracking started -- sent_at is the
+        # Date: header the row claims to be showing.
+        assert revs[2]['found_at'] == '2026-06-01T00:00:00+00:00'
+
+    def test_archiving_keeps_the_revisions_watermark(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A NULL watermark sorts to the head of the poll rotation forever.
+
+        Archiving used to park counts, which could spread the incoming
+        revision's cleared watermark onto the one being retired.  It now
+        writes no read state at all.
+        """
+        conn = self._seed('carry-nullmark', revision=2)
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 4, seen_message_count = 4,'
+            " last_update_check = '2026-06-02T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        conn.commit()
+        review_tracking.update_series_status(conn, 'cid', 'archived', revision=2)
+        row = conn.execute(
+            'SELECT last_update_check FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 2"
+        ).fetchone()
+        conn.close()
+        assert row[0] == '2026-06-02T00:00:00+00:00'
+
+    def test_parking_does_not_overwrite_polled_activity(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """series.last_activity_at also stamps maintainer actions.
+
+        The catalog column only ever holds a real Date: header, so a
+        snooze or a status change must not replace one.
+        """
+        conn = self._seed('carry-activity', revision=2)
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 4, seen_message_count = 4,'
+            " last_mail_at = '2026-03-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 2"
+        )
+        # A maintainer action bumps the series stamp to something newer.
+        conn.execute(
+            "UPDATE series SET last_activity_at = '2026-07-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid'"
+        )
+        conn.commit()
+        review_tracking.update_series_status(conn, 'cid', 'archived', revision=2)
+        row = conn.execute(
+            'SELECT last_mail_at FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 2"
+        ).fetchone()
+        conn.close()
+        assert row[0] == '2026-03-01T00:00:00+00:00'
+
+
+class TestPollerFetchDiscipline:
+    """The poller must fetch the same way every other count writer does."""
+
+    def test_fetch_is_uncached_and_strict(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A cached mbox can predate the very messages the rt: poll found.
+
+        Counting it would leave message_count unmoved while
+        last_update_check advanced past those messages, losing them.
+        """
+        calls: list[Dict[str, Any]] = []
+
+        def _fake(msgid: str, **kw: Any) -> list[EmailMessage]:
+            calls.append({'msgid': msgid, **kw})
+            return _thread_msgs(3)
+
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(b4, 'get_pi_thread_by_msgid', _fake)
+        msgs = review_tracking._fetch_thread_msgs('v1@x')
+        assert msgs is not None and len(msgs) == 3
+        assert calls == [{'msgid': 'v1@x', 'nocache': True, 'quiet': True}]
+
+    def test_fetch_propagates_cancellation(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        def _cancelled(msgid: str, **kw: Any) -> list[EmailMessage]:
+            raise liblore.OperationCancelledError('Request cancelled')
+
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(b4, 'get_pi_thread_by_msgid', _cancelled)
+        with pytest.raises(liblore.OperationCancelledError):
+            review_tracking._fetch_thread_msgs('v1@x')
+
+    def test_offline_skips_rethreaded_fetch(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Offline must short-circuit before the per-patch requests."""
+        conn = review_tracking.init_db('poll-offline')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x', is_rethreaded=True)
+        _insert_patches(conn, 'cid', 1, ['p1@x', 'p2@x'])
+        conn.close()
+
+        def _boom(series: Dict[str, Any], identifier: str) -> list[EmailMessage]:
+            raise AssertionError('must not fetch while offline')
+
+        monkeypatch.setattr(b4, 'can_network', False)
+        monkeypatch.setattr(b4.review, 'retrieve_series_messages', _boom)
+        result = review_tracking.update_revision_message_counts(
+            'poll-offline', [_poller_series('cid', 2, 'v2@x')]
+        )
+        # Offline is not a failure: no request was issued, so nothing is
+        # reported unreachable.  Counting it would have _cron_update() mail
+        # 'Could not poll N non-tracked revision(s)' after every sweep run
+        # from a machine that happened to be off the network.
+        assert result == {
+            'updated': 0,
+            'new_mail': 0,
+            'errors': 0,
+            'fresh_errors': 0,
+            'polled': 0,
+            'cancelled': 0,
+        }
+
+    def test_cancel_cb_stops_the_sweep(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('poll-cancel')
+        for rev in (1, 2, 3):
+            review_tracking.add_revision(conn, 'cid', rev, f'v{rev}@x')
+        conn.close()
+        polled: list[int] = []
+
+        def _fake_fetch(
+            identifier: str, conn: Any, change_id: str, rev: Dict[str, Any]
+        ) -> list[EmailMessage]:
+            polled.append(int(rev['revision']))
+            return _thread_msgs(2)
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _fake_fetch)
+        result = review_tracking.update_revision_message_counts(
+            'poll-cancel',
+            [_poller_series('cid', 4, 'v4@x')],
+            cancel_cb=lambda: len(polled) >= 1,
+        )
+        assert polled == [3]
+        assert result['updated'] == 1
+
+    def test_connection_closed_when_a_revision_raises(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """update_all_tracking swallows and continues, so a leak compounds."""
+        conn = review_tracking.init_db('poll-leak')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.close()
+        real_get_db = review_tracking.get_db
+
+        class _ProxyConn:
+            """sqlite3.Connection.close is read-only, so wrap instead."""
+
+            def __init__(self, real: sqlite3.Connection) -> None:
+                self._real = real
+                self.closed = False
+
+            def __getattr__(self, name: str) -> Any:
+                return getattr(self._real, name)
+
+            def close(self) -> None:
+                self.closed = True
+                self._real.close()
+
+        proxies: list[_ProxyConn] = []
+
+        def _tracking_get_db(identifier: str) -> Any:
+            proxy = _ProxyConn(real_get_db(identifier))
+            proxies.append(proxy)
+            return proxy
+
+        def _boom(*a: Any, **kw: Any) -> None:
+            raise sqlite3.OperationalError('database is locked')
+
+        monkeypatch.setattr(review_tracking, 'get_db', _tracking_get_db)
+        monkeypatch.setattr(review_tracking, '_update_one_revision_count', _boom)
+        with pytest.raises(sqlite3.OperationalError):
+            review_tracking.update_revision_message_counts(
+                'poll-leak', [_poller_series('cid', 2, 'v2@x')]
+            )
+        assert proxies and all(p.closed for p in proxies)
+
+    def test_incremental_stamps_per_revision(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A sweep-wide timestamp double-counts mail arriving during it."""
+        conn = review_tracking.init_db('poll-stamp')
+        for rev in (1, 2):
+            review_tracking.add_revision(conn, 'cid', rev, f'v{rev}@x')
+        conn.close()
+        stamps: list[str] = []
+
+        def _fake_fetch(
+            identifier: str, conn: Any, change_id: str, rev: Dict[str, Any]
+        ) -> list[EmailMessage]:
+            return _thread_msgs(2)
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _fake_fetch)
+        review_tracking.update_revision_message_counts(
+            'poll-stamp', [_poller_series('cid', 3, 'v3@x')]
+        )
+        conn = review_tracking.get_db('poll-stamp')
+        stamps = [
+            r['last_update_check']
+            for r in review_tracking.get_revisions(conn, 'cid')
+            # v3 is the tracked revision, so the poller skips it
+            if r['revision'] != 3
+        ]
+        conn.close()
+        assert len(stamps) == 2
+        assert all(s for s in stamps)
+        assert len(set(stamps)) == 2
+
+
+class TestRevisionSwitchClearsStaleState:
+    """update_series_revision() must not leave the old revision behind."""
+
+    def _seed(self, identifier: str) -> None:
+        conn = review_tracking.init_db(identifier)
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='[PATCH v2 0/2] thing',
+            sender_name='S',
+            sender_email='[email protected]',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='[email protected]',
+            num_patches=2,
+        )
+        conn.execute(
+            'UPDATE revisions SET message_count = 10, seen_message_count = 10,'
+            " last_update_check = '2026-05-01T00:00:00+00:00',"
+            " last_mail_at = '2026-04-28T00:00:00+00:00'"
+            " WHERE change_id = 'cid'"
+        )
+        review_tracking.add_revision(conn, 'cid', 2, '[email protected]')
+        review_tracking.add_revision(conn, 'cid', 3, '[email protected]')
+        conn.execute(
+            'UPDATE revisions SET message_count = 7, seen_message_count = 7,'
+            " last_update_check = '2026-06-01T00:00:00+00:00',"
+            " last_mail_at = '2026-05-30T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 3"
+        )
+        conn.commit()
+        conn.close()
+
+    def test_watermark_does_not_survive_the_switch(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """The incoming revision must not inherit the outgoing thread's watermark."""
+        self._seed('switch-watermark')
+        conn = review_tracking.get_db('switch-watermark')
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, '[email protected]')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        # v3's count comes from the catalog, so its watermark must too --
+        # not from the series row, where it still described v2.
+        assert revs[3]['message_count'] == 7
+        assert revs[3]['last_update_check'] == '2026-06-01T00:00:00+00:00'
+
+    def test_activity_is_the_threads_not_the_switch(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A version row reports thread activity, not when the upgrade happened."""
+        self._seed('switch-activity')
+        conn = review_tracking.get_db('switch-activity')
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, '[email protected]')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[3]['last_mail_at'] == '2026-05-30T00:00:00+00:00'
+        assert revs[2]['last_mail_at'] == '2026-04-28T00:00:00+00:00'
+
+    def test_rethread_flag_is_repointed(self, tmp_path: pytest.TempPathFactory) -> None:
+        """The flag describes the tracked revision, so it moves with it."""
+        self._seed('switch-rethread')
+        conn = review_tracking.get_db('switch-rethread')
+        conn.execute("UPDATE series SET is_rethreaded = 1 WHERE change_id = 'cid'")
+        conn.commit()
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, '[email protected]')
+        row = conn.execute(
+            "SELECT is_rethreaded FROM series WHERE change_id = 'cid'"
+        ).fetchone()
+        assert row[0] == 0
+        # ...and parking must not stamp the stale flag onto the catalog,
+        # where add_revision() promotes but never clears it.
+        review_tracking.update_series_status(conn, 'cid', 'archived', revision=3)
+        crow = conn.execute(
+            'SELECT is_rethreaded FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 3"
+        ).fetchone()
+        conn.close()
+        assert crow[0] == 0
+
+    def test_incoming_counts_are_simply_read(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A switch cannot mark the incoming version's unread mail read.
+
+        There is no first-sighting to mistake it for: the row the series
+        moves onto already holds whatever the poller learned about it, and
+        the next count write reads that rather than a blank series row.
+        """
+        self._seed('switch-adopt')
+        conn = review_tracking.get_db('switch-adopt')
+        conn.execute(
+            'UPDATE revisions SET seen_message_count = 4'
+            " WHERE change_id = 'cid' AND revision = 3"
+        )
+        conn.commit()
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, '[email protected]')
+        # The sweep refetches the tracked thread and finds the same 7.
+        changed = review_tracking.update_message_count_from_msgs(
+            conn, 'cid', 3, _thread_msgs(7)
+        )
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert (revs[3]['message_count'], revs[3]['seen_message_count']) == (7, 4)
+        # Nothing moved, and nothing had to be moved for it to be right.
+        assert changed is False
+
+    def test_refresh_count_reads_the_same_row(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Opening the thread viewer must not clear the badge either."""
+        self._seed('switch-adopt-refresh')
+        conn = review_tracking.get_db('switch-adopt-refresh')
+        conn.execute(
+            'UPDATE revisions SET seen_message_count = 4'
+            " WHERE change_id = 'cid' AND revision = 3"
+        )
+        conn.commit()
+        review_tracking.update_series_revision(conn, 'cid', 2, 3, '[email protected]')
+        conn.close()
+        # 7 is what the row already holds, so there is nothing to write.
+        assert not review_tracking.refresh_message_count(
+            'switch-adopt-refresh', 'cid', 3, 7
+        )
+        conn = review_tracking.get_db('switch-adopt-refresh')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert (revs[3]['message_count'], revs[3]['seen_message_count']) == (7, 4)
+
+
+class TestPollerLeavesOtherLiveRowsAlone:
+    """A second live series row's revision is not the poller's to write."""
+
+    @staticmethod
+    def _two_live_rows(identifier: str) -> None:
+        """One change_id, two non-archived series rows, as rescan leaves them."""
+        conn = review_tracking.init_db(identifier)
+        for rev, msgid in ((2, 'v2@x'), (1, 'v1@x')):
+            review_tracking.add_series_to_db(
+                conn,
+                change_id='cid',
+                revision=rev,
+                subject=f'[PATCH v{rev}] thing',
+                sender_name='S',
+                sender_email='[email protected]',
+                sent_at='2026-01-01T00:00:00+00:00',
+                message_id=msgid,
+                num_patches=1,
+            )
+            review_tracking.add_revision(conn, 'cid', rev, msgid)
+        conn.commit()
+        conn.close()
+
+    def test_another_rows_tracked_revision_is_not_polled(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """update_all_tracking() walks the rows one at a time.
+
+        Excluding only the revision of the dict this call was handed leaves
+        the *other* row's actively tracked revision fair game -- and the
+        poller writes the catalog from a first fetch (seen = count), so that
+        row's unread delta is gone before anything can park it.
+        """
+        self._two_live_rows('poll-otherrow')
+        conn = review_tracking.get_db('poll-otherrow')
+        conn.execute(
+            'UPDATE revisions SET message_count = 20, seen_message_count = 17,'
+            " last_update_check = '2026-01-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        polled: list[int] = []
+
+        def _fetch(identifier: str, conn: Any, change_id: str, rev: Any) -> Any:
+            polled.append(int(rev['revision']))
+            return _thread_msgs(20)
+
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _fetch)
+        review_tracking.update_revision_message_counts(
+            'poll-otherrow', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert polled == []
+
+    def test_the_other_rows_unread_survives(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The end-to-end damage this once caused: three unread marked read.
+
+        A change_id with two live series rows had one row's unread state
+        overwritten by the other.  Nothing copies read state between rows
+        any more, so the poller simply has to leave a revision another live
+        row tracks to that row.
+        """
+        self._two_live_rows('poll-otherpark')
+        conn = review_tracking.get_db('poll-otherpark')
+        conn.execute(
+            'UPDATE revisions SET message_count = 20, seen_message_count = 17,'
+            " last_update_check = '2026-01-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(20),
+        )
+        review_tracking.update_revision_message_counts(
+            'poll-otherpark', [_poller_series('cid', 2, 'v2@x')]
+        )
+        conn = review_tracking.get_db('poll-otherpark')
+        review_tracking.update_series_status(conn, 'cid', 'archived', revision=1)
+        row = conn.execute(
+            'SELECT message_count, seen_message_count FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 1"
+        ).fetchone()
+        conn.close()
+        assert (row[0], row[1]) == (20, 17)
+
+
+class TestPollerRoutesOnTheCatalogRow:
+    """The poller reads the row it writes, not the stitched view."""
+
+    def test_counted_but_unwatermarked_keeps_its_badge(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The v11 migration seeds counts with a NULL watermark; don't clobber."""
+        conn = review_tracking.init_db('poll-nowm')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 4, seen_message_count = 1,'
+            " last_mail_at = '2026-02-02T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        # No Date: headers, so the fetch cannot improve on last_activity_at.
+        undated = _thread_msgs(6)
+        for msg in undated:
+            del msg['Date']
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: undated,
+        )
+        review_tracking.update_revision_message_counts(
+            'poll-nowm', [_poller_series('cid', 2, 'v2@x')]
+        )
+        conn = review_tracking.get_db('poll-nowm')
+        row = conn.execute(
+            'SELECT message_count, seen_message_count, last_mail_at'
+            " FROM revisions WHERE change_id = 'cid' AND revision = 1"
+        ).fetchone()
+        conn.close()
+        # 3 unread before, 5 after -- not "all read".
+        assert (row['message_count'], row['seen_message_count']) == (6, 1)
+        assert row['last_mail_at'] == '2026-02-02T00:00:00+00:00'
+
+    def test_single_patch_rethread_uses_the_recorded_thread(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """One recorded patch is not enough to reassemble from."""
+        conn = review_tracking.init_db('poll-rt1')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x', is_rethreaded=True)
+        conn.execute(
+            'INSERT INTO series_patches (change_id, revision, position, message_id)'
+            " VALUES ('cid', 1, 1, 'p1@x')"
+        )
+        conn.commit()
+        conn.close()
+        queried: list[str] = []
+
+        def _thread(msgid: str) -> list[EmailMessage]:
+            queried.append(msgid)
+            return _thread_msgs(3)
+
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(review_tracking, '_fetch_thread_msgs', _thread)
+        monkeypatch.setattr(
+            b4.review,
+            'retrieve_series_messages',
+            lambda series, identifier: pytest.fail('must not reassemble'),
+        )
+        review_tracking.update_revision_message_counts(
+            'poll-rt1', [_poller_series('cid', 2, 'v2@x')]
+        )
+        assert queried == ['v1@x']
+
+
+class TestPollCapFairness:
+    """The cap must not permanently hide the oldest versions."""
+
+    def _seed(self, identifier: str, revs: int) -> None:
+        conn = review_tracking.init_db(identifier)
+        for rev in range(1, revs + 1):
+            review_tracking.add_revision(conn, 'cid', rev, f'v{rev}@x')
+        conn.close()
+
+    def test_never_counted_revisions_are_polled_first(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A newest-first cap left v1/v2 of a v6 series at '-' forever."""
+        self._seed('cap-fair', 5)
+        conn = review_tracking.get_db('cap-fair')
+        # v3..v5 already counted; v1 and v2 never were.
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2,'
+            " last_update_check = '2026-06-01T00:00:00+00:00'"
+            ' WHERE change_id = ? AND revision >= 3',
+            ('cid',),
+        )
+        conn.commit()
+        conn.close()
+        fetched: list[int] = []
+
+        def _full(identifier: str, conn: Any, change_id: str, rev: Any) -> Any:
+            fetched.append(int(rev['revision']))
+            return _thread_msgs(2)
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _full)
+        review_tracking.update_revision_message_counts(
+            'cap-fair',
+            [_poller_series('cid', 6, 'v6@x')],
+            max_revisions_per_series=2,
+        )
+        assert sorted(fetched) == [1, 2]
+
+    def test_a_failed_fetch_does_not_spend_the_budget(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """One unreachable revision must not starve the ones behind it."""
+        self._seed('cap-fail', 3)
+        attempted: list[int] = []
+
+        def _full(identifier: str, conn: Any, change_id: str, rev: Any) -> Any:
+            revision = int(rev['revision'])
+            attempted.append(revision)
+            # v3 is unreachable, the rest are fine.
+            return None if revision == 3 else _thread_msgs(2)
+
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _full)
+        result = review_tracking.update_revision_message_counts(
+            'cap-fail',
+            [_poller_series('cid', 4, 'v4@x')],
+            max_revisions_per_series=2,
+        )
+        assert result['errors'] == 1
+        assert result['updated'] == 2
+        assert attempted == [3, 2, 1]
+
+    def test_two_failures_in_a_row_stop_the_series(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Offline means every revision fails; don't try the whole catalog."""
+        self._seed('cap-offline', 6)
+        attempted: list[int] = []
+
+        def _full(identifier: str, conn: Any, change_id: str, rev: Any) -> Any:
+            attempted.append(int(rev['revision']))
+            return None
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _full)
+        review_tracking.update_revision_message_counts(
+            'cap-offline',
+            [_poller_series('cid', 7, 'v7@x')],
+            max_revisions_per_series=4,
+        )
+        assert len(attempted) == 2
+
+    def test_a_dead_revision_does_not_starve_the_rotation(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Two permanently unreachable revisions used to stop every sweep.
+
+        They stayed uncounted, so they sorted to the front for ever, and
+        two failures in a row abandoned the series before anything else
+        was reached -- including the recent versions late replies land on.
+        """
+        monkeypatch.setattr(b4, 'can_network', True)
+        self._seed('cap-dead', 5)
+        conn = review_tracking.get_db('cap-dead')
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2,'
+            " last_update_check = '2026-06-01T00:00:00+00:00'"
+            ' WHERE change_id = ? AND revision >= 4',
+            ('cid',),
+        )
+        conn.commit()
+        conn.close()
+
+        def _full(identifier: str, conn: Any, change_id: str, rev: Any) -> Any:
+            # v1 and v2 are gone from the archive for good.
+            return None if int(rev['revision']) in (1, 2) else _thread_msgs(3)
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _full)
+        for _ in range(3):
+            review_tracking.update_revision_message_counts(
+                'cap-dead',
+                [_poller_series('cid', 6, 'v6@x')],
+                max_revisions_per_series=2,
+            )
+        conn = review_tracking.get_db('cap-dead')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        # The reachable versions were reached despite the two dead ones.
+        assert revs[4]['message_count'] == 3
+        assert revs[5]['message_count'] == 3
+
+    def test_named_revisions_are_not_abandoned_after_two_failures(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """discover_older_revisions passes only_revisions with no cap.
+
+        It does that precisely so every version it just recorded gets
+        counted; giving up after two dead message-ids -- which is exactly
+        what a backward lore search turns up -- reintroduces the starvation
+        the missing cap was avoiding.
+        """
+        self._seed('cap-named', 4)
+        fetched: list[int] = []
+
+        def _full(identifier: str, conn: Any, change_id: str, rev: Any) -> Any:
+            revision = int(rev['revision'])
+            fetched.append(revision)
+            return None if revision in (3, 4) else _thread_msgs(3)
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _full)
+        review_tracking.update_revision_message_counts(
+            'cap-named',
+            [_poller_series('cid', 5, 'v5@x')],
+            only_revisions={1, 2, 3, 4},
+        )
+        conn = review_tracking.get_db('cap-named')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert fetched == [4, 3, 2, 1]
+        assert revs[1]['message_count'] == 3
+        assert revs[2]['message_count'] == 3
+
+    def test_counted_revisions_come_back_around(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A newest-first cap watched only the newest few, for ever."""
+        self._seed('cap-rotate', 6)
+        conn = review_tracking.get_db('cap-rotate')
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2,'
+            " last_update_check = '2026-06-01T00:00:00+00:00'",
+        )
+        conn.commit()
+        conn.close()
+        attempted: list[int] = []
+
+        def _full(identifier: str, conn: Any, change_id: str, rev: Any) -> Any:
+            attempted.append(int(rev['revision']))
+            return _thread_msgs(2)
+
+        monkeypatch.setattr(review_tracking, '_fetch_revision_thread_msgs', _full)
+        for _ in range(3):
+            review_tracking.update_revision_message_counts(
+                'cap-rotate',
+                [_poller_series('cid', 7, 'v7@x')],
+                max_revisions_per_series=2,
+            )
+        # Six sweeps' worth of budget covered all six versions, not the
+        # same two over and over.
+        assert sorted(attempted) == [1, 2, 3, 4, 5, 6]
+
+
+class TestSeenSyncFallsBackToCatalog:
+    def test_uncounted_series_row_defers_to_the_catalog(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A NULL series count is not "nothing to do".
+
+        The displayed badge came from the catalog, so that is where the
+        sync has to land.
+        """
+        conn = review_tracking.init_db('seen-fallback')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=3,
+            subject='[PATCH v3] thing',
+            sender_name='S',
+            sender_email='[email protected]',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='v3@x',
+            num_patches=1,
+        )
+        review_tracking.add_revision(conn, 'cid', 3, 'v3@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 8, seen_message_count = 8'
+            " WHERE change_id = 'cid' AND revision = 3"
+        )
+        conn.commit()
+        conn.close()
+        assert review_tracking.sync_seen_from_unseen_count('seen-fallback', 'cid', 3, 3)
+        conn = review_tracking.get_db('seen-fallback')
+        row = conn.execute(
+            'SELECT seen_message_count FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 3"
+        ).fetchone()
+        conn.close()
+        assert row[0] == 5
+
+
+class TestRethreadFlagStitching:
+    """`series.is_rethreaded` is never NULL, so it cannot be COALESCEd over."""
+
+    @staticmethod
+    def _seed(identifier: str) -> None:
+        conn = review_tracking.init_db(identifier)
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='[PATCH v2] thing',
+            sender_name='S',
+            sender_email='[email protected]',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=2,
+        )
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x', is_rethreaded=True)
+        _insert_patches(conn, 'cid', 2, ['p1@x', 'p2@x'])
+        conn.commit()
+        conn.close()
+
+    def test_catalog_rethread_survives_a_zeroed_series_row(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """The column is INTEGER DEFAULT 0, so a COALESCE always picks it.
+
+        A series row that lost the flag (the upgrade path used to write the
+        default) would then permanently mask the catalog's 1.
+        """
+        self._seed('rt-stitch')
+        conn = review_tracking.get_db('rt-stitch')
+        row = conn.execute(
+            "SELECT is_rethreaded FROM series WHERE change_id = 'cid'"
+        ).fetchone()
+        conn.close()
+        # Precondition: the series row really does hold a non-NULL 0.
+        assert row[0] == 0
+
+        conn = review_tracking.get_db('rt-stitch')
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        assert revs[2]['is_rethreaded']
+
+    def test_known_revisions_keeps_the_patch_list(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """build_known_revisions() gates the portable patch list on the flag.
+
+        update_series_tracking() rewrites `known-revisions` on every sweep,
+        so a dropped flag actively erases a rethreaded revision from the
+        branch -- and it cannot be re-derived from lore.
+        """
+        self._seed('rt-known')
+        conn = review_tracking.get_db('rt-known')
+        known = review_tracking.build_known_revisions(conn, 'cid')
+        conn.close()
+        entry = next(e for e in known if e['revision'] == 2)
+        assert entry.get('is-rethreaded') is True
+        assert [p['message-id'] for p in entry['patches']] == ['p1@x', 'p2@x']
+
+
+class TestShrinkIsRecorded:
+    def test_a_stale_high_watermark_does_not_eat_the_badge(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """10/10 stored, real thread 8 -> two replies -> the badge shows.
+
+        Threads do shrink (dedup variation, mail removed from the
+        archive), and a writer that refuses any total at or below the
+        stored one turns 10 into a watermark: the corrected 8 and the
+        subsequent genuine 10 are both refused, the badge never lights,
+        and the one repair path runs only when the maintainer opens the
+        thread the missing badge was meant to point at.
+        """
+        conn = review_tracking.init_db('shrink-badge')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 10, seen_message_count = 10,'
+            " last_update_check = '2026-01-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+
+        size = [8]
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(size[0]),
+        )
+        review_tracking.update_revision_message_counts(
+            'shrink-badge', [_poller_series('cid', 2, 'v2@x')]
+        )
+        conn = review_tracking.get_db('shrink-badge')
+        row = conn.execute(
+            'SELECT message_count, seen_message_count FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 1"
+        ).fetchone()
+        # The shrink is recorded and seen capped with it: nothing unread.
+        assert (row[0], row[1]) == (8, 8)
+        # Age the check stamp out of the minimum-interval gate.
+        conn.execute(
+            "UPDATE revisions SET last_update_check = '2026-01-01T00:00:00+00:00'"
+        )
+        conn.commit()
+        conn.close()
+
+        size[0] = 10
+        review_tracking.update_revision_message_counts(
+            'shrink-badge', [_poller_series('cid', 2, 'v2@x')]
+        )
+        conn = review_tracking.get_db('shrink-badge')
+        row = conn.execute(
+            'SELECT message_count, seen_message_count FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 1"
+        ).fetchone()
+        conn.close()
+        # The two genuine replies badge instead of vanishing under the
+        # old high watermark.
+        assert (row[0], row[1]) == (10, 8)
+
+    def test_a_genuine_growth_is_still_taken(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Growth stores the count and leaves seen for the badge."""
+        conn = review_tracking.init_db('short-grow')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 4, seen_message_count = 4'
+            " WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(6),
+        )
+        review_tracking.update_revision_message_counts(
+            'short-grow', [_poller_series('cid', 2, 'v2@x')]
+        )
+        conn = review_tracking.get_db('short-grow')
+        row = conn.execute(
+            'SELECT message_count, seen_message_count FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 1"
+        ).fetchone()
+        conn.close()
+        assert (row[0], row[1]) == (6, 4)
+
+
+class TestTrackedRevisionActivityKeepsMoving:
+    def test_the_catalog_date_follows_the_tracked_thread(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Per-revision reads prefer the catalog, and the poller skips the
+        tracked revision -- so without a mirror a version's date freezes at
+        whatever poll it last got as an older version."""
+        conn = review_tracking.init_db('act-mirror')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=3,
+            subject='[PATCH v3] thing',
+            sender_name='S',
+            sender_email='[email protected]',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='v3@x',
+            num_patches=1,
+        )
+        review_tracking.add_revision(conn, 'cid', 3, 'v3@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2,'
+            " last_mail_at = '2026-02-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 3"
+        )
+        conn.commit()
+        conn.close()
+        # get_db(), not the init_db() handle: update_message_count_from_msgs
+        # indexes rows by name and only get_db() sets the Row factory.
+        conn = review_tracking.get_db('act-mirror')
+        review_tracking.update_message_count_from_msgs(conn, 'cid', 3, _thread_msgs(4))
+        revs = {r['revision']: r for r in review_tracking.get_revisions(conn, 'cid')}
+        conn.close()
+        # _thread_msgs dates run 01..04 Jul 2026, so the newest wins.
+        assert revs[3]['last_mail_at'].startswith('2026-07-04')
+
+    def test_a_maintainer_action_does_not_reach_the_catalog(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Only a real Date: header moves the column."""
+        conn = review_tracking.init_db('act-nomaint')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=3,
+            subject='[PATCH v3] thing',
+            sender_name='S',
+            sender_email='[email protected]',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='v3@x',
+            num_patches=1,
+        )
+        review_tracking.add_revision(conn, 'cid', 3, 'v3@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2,'
+            " last_mail_at = '2026-02-01T00:00:00+00:00'"
+            " WHERE change_id = 'cid' AND revision = 3"
+        )
+        conn.commit()
+        review_tracking.update_series_status(conn, 'cid', 'waiting', revision=3)
+        row = conn.execute(
+            'SELECT last_mail_at FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 3"
+        ).fetchone()
+        conn.close()
+        assert row[0] == '2026-02-01T00:00:00+00:00'
+
+
+class TestPrunedThreadBlobIsReCached:
+    def test_a_gc_d_blob_is_replaced_on_a_quiet_poll(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Thread blobs are unreferenced objects; git gc may take one.
+
+        A settled old version's count never moves again, so the quiet path
+        is its only chance -- and it used to treat the dead SHA still in the
+        row as proof the thread was cached.
+        """
+        conn = review_tracking.init_db('blob-gc')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2,'
+            " thread_blob = 'deadbeef' WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        stored: list[int] = []
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(2),
+        )
+        monkeypatch.setattr(
+            review_tracking, '_thread_blob_exists', lambda topdir, sha: False
+        )
+        monkeypatch.setattr(
+            review_tracking,
+            'store_revision_thread_blob',
+            lambda conn, topdir, change_id, revision, msgs: stored.append(len(msgs)),
+        )
+        review_tracking.update_revision_message_counts(
+            'blob-gc', [_poller_series('cid', 2, 'v2@x')], topdir='/nonexistent'
+        )
+        assert stored == [2]
+
+    def test_a_blob_holding_at_least_as_much_is_left_alone(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        conn = review_tracking.init_db('blob-live')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2,'
+            " thread_blob = 'deadbeef' WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        stored: list[int] = []
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(2),
+        )
+        monkeypatch.setattr(
+            review_tracking, '_thread_blob_exists', lambda topdir, sha: True
+        )
+        monkeypatch.setattr(
+            review_tracking,
+            'store_revision_thread_blob',
+            lambda conn, topdir, change_id, revision, msgs: stored.append(len(msgs)),
+        )
+        review_tracking.update_revision_message_counts(
+            'blob-live', [_poller_series('cid', 2, 'v2@x')], topdir='/nonexistent'
+        )
+        assert stored == []
+
+    def test_the_quiet_path_does_not_read_the_blob_back(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Existence, not content: the thread is the one already stored.
+
+        Every cataloged revision comes through here on every sweep, so
+        reading and re-parsing each one's whole mbox to answer "no change"
+        is a cost the rotation pays for nothing.
+        """
+        conn = review_tracking.init_db('blob-quiet-read')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2,'
+            " thread_blob = 'deadbeef' WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(2),
+        )
+        monkeypatch.setattr(
+            review_tracking, '_thread_blob_exists', lambda topdir, sha: True
+        )
+        monkeypatch.setattr(
+            review_tracking,
+            'get_thread_mbox',
+            lambda topdir, sha: pytest.fail('quiet poll must not read the blob'),
+        )
+        review_tracking.update_revision_message_counts(
+            'blob-quiet-read', [_poller_series('cid', 2, 'v2@x')], topdir='/nonexistent'
+        )
+
+    def test_a_shrink_still_restores_a_pruned_blob(
+        self, tmp_path: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The short-fetch path has the messages in hand; cache them.
+
+        A revision whose thread ends up permanently shorter than the
+        stored watermark otherwise never got its pruned blob back, and
+        every range-diff against it refetched from lore forever.
+        """
+        conn = review_tracking.init_db('blob-shrink-gc')
+        review_tracking.add_revision(conn, 'cid', 1, 'v1@x')
+        conn.execute(
+            'UPDATE revisions SET message_count = 10, seen_message_count = 10,'
+            " thread_blob = 'deadbeef' WHERE change_id = 'cid' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review_tracking,
+            '_fetch_revision_thread_msgs',
+            lambda identifier, conn, change_id, rev: _thread_msgs(8),
+        )
+        stored: list[int] = []
+        monkeypatch.setattr(
+            review_tracking,
+            'store_revision_thread_blob',
+            lambda conn, topdir, change_id, revision, msgs: stored.append(len(msgs)),
+        )
+        review_tracking.update_revision_message_counts(
+            'blob-shrink-gc', [_poller_series('cid', 2, 'v2@x')], topdir='/nonexistent'
+        )
+        assert stored == [8]
+
+
+class TestSeenWritersStayConsistent:
+    @staticmethod
+    def _seed(identifier: str, series_count: Optional[int], cat_count: int) -> None:
+        conn = review_tracking.init_db(identifier)
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='[PATCH v2] thing',
+            sender_name='S',
+            sender_email='[email protected]',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        if series_count is not None:
+            conn.execute(
+                'UPDATE revisions SET message_count = ?, seen_message_count = ?'
+                " WHERE change_id = 'cid' AND revision = 2",
+                (series_count, series_count - 3),
+            )
+        conn.execute(
+            'UPDATE revisions SET message_count = ?, seen_message_count = ?'
+            " WHERE change_id = 'cid' AND revision = 2",
+            (cat_count, cat_count),
+        )
+        conn.commit()
+        conn.close()
+
+    def test_sync_writes_the_single_copy(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """There is no second copy to go stale behind this one."""
+        self._seed('seen-mirror', series_count=10, cat_count=10)
+        assert review_tracking.sync_seen_from_unseen_count('seen-mirror', 'cid', 2, 2)
+        conn = review_tracking.get_db('seen-mirror')
+        row = conn.execute(
+            'SELECT message_count, seen_message_count FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 2"
+        ).fetchone()
+        conn.close()
+        assert (row[0], row[1]) == (10, 8)
+
+    def test_mark_seen_skips_a_row_with_no_count(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """A seen count against a NULL total is a badge with no basis.
+
+        There is no longer a second row for it to shadow, but recording it
+        would still leave seen > total the moment a count did arrive.
+        """
+        conn = review_tracking.init_db('seen-nullcount')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='s',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-06-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        conn.commit()
+        review_tracking.mark_all_messages_seen(conn, 'cid', 2)
+        row = conn.execute(
+            'SELECT message_count, seen_message_count FROM revisions'
+            " WHERE change_id = 'cid' AND revision = 2"
+        ).fetchone()
+        conn.close()
+        assert row[0] is None
+        assert row[1] is None
+
+
+class TestMigrationDeclinesWhatItCannotCarry:
+    """A series table too degenerate to backfill from keeps its columns.
+
+    The read-state move drops the `series` copies only inside the backfill
+    guard: dropping a copy that was never carried across would just lose
+    it.  The branch_sha move sits outside that guard because it needs
+    nothing from `series` but the two columns every version of it has had.
+    """
+
+    @staticmethod
+    def _degenerate_v1_db(identifier: str) -> None:
+        import sqlite3 as _sqlite3
+
+        raw = _sqlite3.connect(review_tracking.get_db_path(identifier))
+        raw.executescript("""
+            CREATE TABLE schema_version (version INTEGER PRIMARY KEY);
+            CREATE TABLE series (
+                track_id INTEGER PRIMARY KEY,
+                change_id TEXT NOT NULL,
+                revision INTEGER NOT NULL,
+                status TEXT DEFAULT 'new',
+                UNIQUE (change_id, revision)
+            );
+        """)
+        raw.execute('INSERT INTO schema_version (version) VALUES (1)')
+        raw.commit()
+        raw.close()
+
+    def test_read_state_survives_a_backfill_it_cannot_run(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        self._degenerate_v1_db('mig-degenerate')
+        conn = review_tracking.get_db('mig-degenerate')
+        series_cols = {row[1] for row in conn.execute('PRAGMA table_info(series)')}
+        rev_cols = {row[1] for row in conn.execute('PRAGMA table_info(revisions)')}
+        version = conn.execute('SELECT version FROM schema_version').fetchone()[0]
+        conn.close()
+        read_state = {'message_count', 'seen_message_count', 'last_update_check'}
+        # The catalog gains them either way ...
+        assert read_state <= rev_cols
+        # ... and `series` keeps its own, because there was nothing to copy:
+        # this table never had the identity columns the backfill selects.
+        assert read_state <= series_cols
+        assert version == review_tracking.SCHEMA_VERSION
+
+    def test_branch_sha_moves_even_so(self, tmp_path: pytest.TempPathFactory) -> None:
+        self._degenerate_v1_db('mig-degenerate-sha')
+        conn = review_tracking.get_db('mig-degenerate-sha')
+        series_cols = {row[1] for row in conn.execute('PRAGMA table_info(series)')}
+        chg_cols = {row[1] for row in conn.execute('PRAGMA table_info(changes)')}
+        conn.close()
+        assert 'branch_sha' not in series_cols
+        assert 'branch_sha' in chg_cols
Signature · 1 line
2.53.0
#12 lore raw

RFC PATCH v2 12/25 review-tui: poll every revision on u/U updates

In reply to Christian Brauner

Hook update_revision_message_counts() into the per-series update loop so every known version of a tracked series gets new-mail detection, not just the tracked revision. Revisions discovered by update_series_tracking() moments earlier are picked up in the same pass, because the poller re-reads the catalog.

A series whose branch is busy is still polled. Only the branch is left alone, and the ref catches up on a later sweep, while the poll writes DB rows and a loose blob and moves no ref. A series under review is normally the checked-out branch, so exempting it would mute exactly the series being worked on. Its tracked revision's counts keep landing too, with the tracking-commit save withheld: the thread snapshot behind seen_bump moves onto the revision's catalog row so it keeps advancing while the ref is frozen, and the skip is reported only for statuses whose branch the sweep would have written.

Quiet old versions are re-polled on a schedule keyed to how recently their thread saw mail. An explicit u/U bypasses that minimum-age skip, since a recently checked version silently withheld reads as the update not working.

---
 src/b4/review/_review.py           | 184 ++++++++++++++++++++++++++++++-------
 src/b4/review/tracking.py          | 154 ++++++++++++++++++++++++++++---
 src/b4/review_tui/_common.py       |   4 +-
 src/b4/review_tui/_modals.py       |   8 ++
 src/b4/review_tui/_review_app.py   |   2 +-
 src/b4/review_tui/_tracking_app.py |  16 +++-
 src/tests/test_review_tracking.py  |  20 ++--
 7 files changed, 331 insertions(+), 57 deletions(-)
src/b4/review/_review.py +152 -32
index f566dbfd..652f21a5 100644
@@ -34,6 +34,10 @@ logger = b4.logger
 REVIEW_MAGIC_MARKER = '--- b4-review-tracking ---'
 REVIEW_BRANCH_PREFIX = 'b4/review/'
 COMMIT_MESSAGE_PATH = ':message'
+# Statuses whose review branch the update sweep rewrites (trailer
+# follow-ups, tracking-commit refreshes); every other status leaves the
+# branch strictly alone.
+BRANCH_UPDATE_STATUSES = ('reviewing', 'replied', 'partial', 'waiting')
 # Synthesized into the cover text when the author sent no cover letter;
 # consumers check for it to detect cover-letter absence.
 NO_COVER_NOTE = 'NOTE: No cover letter provided by the author.'
@@ -1909,7 +1913,7 @@ def _integrate_followup_inline_comments(
     Returns True if any comments were integrated.
     """
     series = tracking['series']
-    blob_sha = series.get('thread-blob', '')
+    blob_sha = b4.review.tracking.resolve_thread_blob(topdir, series)
     if not blob_sha:
         return False
 
@@ -2392,23 +2396,46 @@ def _own_message_entries(
     return entries
 
 
-def _prev_thread_msgids(topdir: str, change_id: str) -> Optional[Set[str]]:
+def _prev_thread_msgids(
+    topdir: str, identifier: str, change_id: str, revision: int
+) -> Optional[Set[str]]:
     """Msgids from the previously stored thread blob, or None if unavailable.
 
     None means "no reliable previous snapshot" — callers must treat that
     as "cannot tell which messages are new" and skip any accounting that
     depends on it.
+
+    The revision's catalog row is the authoritative snapshot: it advances
+    on every counted fetch, including sweeps that must not touch the
+    tracking ref because the branch is checked out.  The tracking commit's
+    blob covers only rows from before the catalog copy existed —
+    preferring it while the ref was frozen re-counted the same messages
+    as new on every sweep.  A recorded catalog blob that no longer reads
+    back (git gc pruned it) is no snapshot at all, not a fallback case.
     """
-    branch = REVIEW_BRANCH_PREFIX + change_id
-    if not b4.git_branch_exists(topdir, branch):
-        return None
+    blob_sha = ''
     try:
-        _, tracking = load_tracking(topdir, branch)
-    except (SystemExit, Exception):
+        conn = b4.review.tracking.get_db(identifier)
+        try:
+            blob_sha = (
+                b4.review.tracking.get_revision_thread_blob(conn, change_id, revision)
+                or ''
+            )
+        finally:
+            conn.close()
+    except Exception:
         return None
-    blob_sha = tracking.get('series', {}).get('thread-blob', '')
     if not blob_sha:
-        return None
+        branch = REVIEW_BRANCH_PREFIX + change_id
+        if not b4.git_branch_exists(topdir, branch):
+            return None
+        try:
+            _, tracking = load_tracking(topdir, branch)
+        except (SystemExit, Exception):
+            return None
+        blob_sha = tracking.get('series', {}).get('thread-blob', '')
+        if not blob_sha:
+            return None
     mbox_bytes = b4.review.tracking.get_thread_mbox(topdir, blob_sha)
     if not mbox_bytes:
         return None
@@ -2548,22 +2575,21 @@ def update_series_tracking(
     # as a side effect of updating.  Do not re-add auto-promotion here.
 
     # Update follow-up trailers if the series has a review branch.  A
-    # branch that is checked out (in any worktree) is left strictly
-    # alone: the maintainer is working on it right there, possibly
-    # mid-rebase, and rewriting its tip under them risks corrupting
-    # their work.  The database updates above have already happened;
-    # the tracking commit catches up on the next sweep after the
-    # branch is no longer checked out.
+    # branch whose worktree has a git operation in flight is left strictly
+    # alone: the maintainer is mid-am or mid-rebase right there, and that
+    # state names the tip this would replace.  The database updates above
+    # have already happened; the tracking commit catches up on the next
+    # sweep that finds the worktree free.
     branch = f'b4/review/{change_id}'
-    update_branch = bool(topdir) and status in (
-        'reviewing',
-        'replied',
-        'partial',
-        'waiting',
-    )
-    if update_branch and topdir and b4.git_branch_checked_out(topdir, branch):
-        logger.debug('%s is checked out, leaving the branch alone', branch)
-        result['checked_out'] = True
+    # Asked only for the statuses whose branch this would write, and only
+    # to *report* the skip -- save_tracking_ref declines on its own, so
+    # nothing below depends on getting this right.  Every other status
+    # short-circuits before the lookup, which is what keeps a sweep from
+    # spending a `git worktree list` per series to learn nothing.
+    update_branch = bool(topdir) and status in BRANCH_UPDATE_STATUSES
+    if update_branch and topdir and b4.git_worktree_busy(topdir, branch):
+        logger.debug('%s is mid-operation, leaving the branch alone', branch)
+        result['branch_busy'] = True
         update_branch = False
     if update_branch and topdir:
         wantver = current_rev
@@ -2665,7 +2691,9 @@ def update_series_tracking(
                 if own_entries:
                     messages.set_flags_bulk(mconn, own_entries, 'Seen')
             if topdir:
-                prev_msgids = _prev_thread_msgids(topdir, change_id)
+                prev_msgids = _prev_thread_msgids(
+                    topdir, identifier, change_id, current_rev
+                )
                 if prev_msgids is not None:
                     new_msgids = []
                     for msg in thread_msgs:
@@ -2725,6 +2753,7 @@ def update_all_tracking(
     series_list: Optional[List[Dict[str, Any]]] = None,
     progress_cb: Optional[Callable[[int, int, str], None]] = None,
     cancel_cb: Optional[Callable[[], bool]] = None,
+    force_revision_poll: bool = False,
 ) -> Dict[str, Any]:
     """Rescan branches, then fetch threads and update all tracked series.
 
@@ -2737,10 +2766,16 @@ def update_all_tracking(
     are updated.  *progress_cb*, when provided, is called as
     ``progress_cb(completed, total, subject)`` around each series.
     *cancel_cb* is polled between series; returning True stops the
-    sweep.
+    sweep.  *force_revision_poll* makes the per-revision poller ignore
+    its minimum-age skip -- set for a user-initiated refresh, where a
+    recently checked version being skipped silently reads as the update
+    not working; scheduled sweeps leave old quiet versions on their
+    schedule.
 
     Returns a summary dict with keys: series_checked, series_updated,
-    errors, gone, followup_updated, error_details, cancelled.
+    errors, gone, followup_updated, revision_counts_updated,
+    revision_errors, revision_fresh_errors, revision_polled,
+    error_details, cancelled.
     """
     result: Dict[str, Any] = {
         'series_checked': 0,
@@ -2748,7 +2783,11 @@ def update_all_tracking(
         'errors': 0,
         'gone': 0,
         'followup_updated': 0,
-        'checked_out_skipped': 0,
+        'revision_counts_updated': 0,
+        'revision_errors': 0,
+        'revision_fresh_errors': 0,
+        'revision_polled': 0,
+        'branch_busy_skipped': 0,
         'error_details': [],
         'cancelled': False,
     }
@@ -2796,14 +2835,73 @@ def update_all_tracking(
                 result['errors'] += 1
                 submitter = series.get('sender_name', 'unknown')
                 result['error_details'].append((submitter, r['error']))
-            if r.get('checked_out'):
-                result['checked_out_skipped'] += 1
             if r.get('counts_updated'):
                 result['followup_updated'] += 1
 
+            if r.get('branch_busy'):
+                # Only the branch was left alone.  The per-revision poll
+                # below writes DB rows and a loose blob, moves no ref, and
+                # a series under review is normally the checked-out branch
+                # -- skipping it here is what stopped late replies to old
+                # versions being noticed at all.
+                result['branch_busy_skipped'] += 1
+
             if progress_cb:
                 progress_cb(i + 1, total, subject)
 
+        # Poll non-tracked revisions for new mail; revisions discovered by
+        # update_series_tracking moments ago are picked up because the
+        # poller re-reads the catalog.  Capped per series: this is one lore
+        # round-trip per revision on top of the per-series fetch, and late
+        # replies land on recent versions.
+        #
+        # One call for the whole list, which is what the signature takes.
+        # Handing it a series at a time reopened the database for every
+        # entry, and scoped its own offline short-circuit to a single
+        # series so a sweep run off the network never stopped early.
+        if not result['cancelled']:
+            # The bar reached N/N when the loop above finished, and the
+            # poll below can be minutes of lore traffic; keep feeding it or
+            # the display reads as hung.  Held at N/N: the series it
+            # counts are all done, and walking the bar backwards through a
+            # second pass over the same list read as a restarted sweep.
+            def _poll_status(subject: str) -> None:
+                if progress_cb:
+                    progress_cb(total, total, f'Polling earlier revisions: {subject}')
+
+            try:
+                rc = b4.review.tracking.update_revision_message_counts(
+                    identifier,
+                    series_list,
+                    topdir=topdir,
+                    max_revisions_per_series=b4.review.tracking.REVISION_POLL_LIMIT,
+                    cancel_cb=cancel_cb,
+                    status_cb=_poll_status if progress_cb else None,
+                    force=force_revision_poll,
+                )
+                result['revision_counts_updated'] += rc.get('new_mail', 0)
+                # Counted separately from result['errors'], which drives
+                # the per-series error report: a revision that will not
+                # fetch is not a series that failed to update.  Without
+                # it a poller that never works (a bad linkmask, 404ing
+                # message-ids) is indistinguishable from a quiet list.
+                result['revision_errors'] += rc.get('errors', 0)
+                result['revision_fresh_errors'] += rc.get('fresh_errors', 0)
+                result['revision_polled'] += rc.get('polled', 0)
+                if rc.get('cancelled'):
+                    result['cancelled'] = True
+            except liblore.OperationCancelledError:
+                result['cancelled'] = True
+            except Exception as ex:
+                # Counted, not just logged.  A poll that raises has failed
+                # exactly as surely as one whose fetch came back empty,
+                # and at debug level the whole feature can break -- a
+                # locked database, a regression in the poll path -- while
+                # every sweep goes on reporting a clean run.
+                result['revision_errors'] += 1
+                result['revision_fresh_errors'] += 1
+                logger.debug('Per-revision count update failed: %s', ex)
+
     return result
 
 
@@ -2892,11 +2990,33 @@ def _cron_update(identifier: str, topdir: Optional[str]) -> None:
         )
     else:
         logger.debug('Checked %s series, no updates', result['series_checked'])
-    if result.get('checked_out_skipped'):
+    if result.get('revision_counts_updated'):
+        logger.info(
+            'New mail on %s non-tracked revision(s)',
+            result['revision_counts_updated'],
+        )
+    if result.get('revision_errors'):
+        # Out of error_details (not a per-series failure).  Warned -- and
+        # thus turned into cron mail -- only when the whole poll came back
+        # empty AND something failed for the first time.  A permanently
+        # dead message-id fails on every pass; once it is known dead
+        # (attempted before, never fetched once) each further failure is
+        # old news, and when it is the only candidate at all, gating on
+        # the others' success alone still mailed the maintainer forever.
+        if result.get('revision_polled') or not result.get('revision_fresh_errors'):
+            logger.debug(
+                'Could not poll %s non-tracked revision(s)', result['revision_errors']
+            )
+        else:
+            logger.warning(
+                'Could not poll %s non-tracked revision(s)', result['revision_errors']
+            )
+    if result.get('branch_busy_skipped'):
         # Normal while the maintainer works on a branch — debug, not
         # cron mail.  The branch catches up on a later sweep.
         logger.debug(
-            '%s branch(es) checked out, left alone', result['checked_out_skipped']
+            '%s branch(es) mid-operation, left alone',
+            result['branch_busy_skipped'],
         )
     for submitter, error in result['error_details']:
         logger.warning('Update error (%s): %s', submitter, error)
src/b4/review/tracking.py +140 -14

242 lines not on this page · raw message

src/b4/review_tui/_common.py +3 -1
index 2d978441..34cd5d28 100644
@@ -461,7 +461,9 @@ class CheckRunnerMixin:
             try:
                 with _quiet_worker():
                     _cover, tracking = b4.review.load_tracking(topdir, review_branch)
-                blob_sha = tracking.get('series', {}).get('thread-blob', '')
+                blob_sha = b4.review.tracking.resolve_thread_blob(
+                    topdir, tracking.get('series', {})
+                )
                 fd, tracking_file = tempfile.mkstemp(
                     prefix='b4-tracking-', suffix='.json'
                 )
src/b4/review_tui/_modals.py +8 -0
index 4acfd0da..23d5f566 100644
@@ -2814,12 +2814,19 @@ class UpdateAllScreen(ModalScreen[Dict[str, Any]]):
         identifier: str,
         linkmask: str,
         topdir: Optional[str] = None,
+        force_revision_poll: bool = False,
     ) -> None:
         super().__init__()
         self._series_list = series_list
         self._identifier = identifier
         self._linkmask = linkmask
         self._topdir = topdir
+        # 'u' on one series: the maintainer is asking about that series
+        # right now, so a recently checked version is polled rather than
+        # silently skipped.  'U' leaves the schedule alone -- forcing it
+        # across a few hundred series turns one keypress into a
+        # REVISION_POLL_LIMIT-sized burst of lore traffic per series.
+        self._force_revision_poll = force_revision_poll
         self._cancelled = False
         self._result: Dict[str, Any] = {
             'series_checked': 0,
@@ -2868,6 +2875,7 @@ class UpdateAllScreen(ModalScreen[Dict[str, Any]]):
                     series_list=self._series_list,
                     progress_cb=_on_progress,
                     cancel_cb=_should_cancel,
+                    force_revision_poll=self._force_revision_poll,
                 )
             except b4.LockHeldError:
                 self._result['busy'] = True
src/b4/review_tui/_review_app.py +1 -1
index 7fe707bb..47d448ed 100644
@@ -2084,7 +2084,7 @@ class ReviewApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[None]):
         self._show_external_comments = True
 
         # ── Try local blob first, fall back to lore in background ────────────
-        blob_sha = self._series.get('thread-blob', '')
+        blob_sha = b4.review.tracking.resolve_thread_blob(self._topdir, self._series)
         self.notify('Loading follow-ups\u2026')
         run_lore_worker(
             self,
src/b4/review_tui/_tracking_app.py +13 -3
index 42f0f46c..31601ded 100644
@@ -2364,7 +2364,11 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
         self._focus_change_id = self._selected_series.get('change_id')
         self.push_screen(
             UpdateAllScreen(
-                [self._selected_series], self._identifier, linkmask, topdir
+                [self._selected_series],
+                self._identifier,
+                linkmask,
+                topdir,
+                force_revision_poll=True,
             ),
             callback=self._on_update_complete,
         )
@@ -2413,9 +2417,15 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
             parts.append(f'{updated} updated')
         if errors:
             parts.append(f'{errors} error(s)')
-        skipped = result.get('checked_out_skipped', 0)
+        rev_counts = result.get('revision_counts_updated', 0)
+        if rev_counts:
+            parts.append(f'{rev_counts} other revision(s) with new mail')
+        rev_errors = result.get('revision_errors', 0)
+        if rev_errors:
+            parts.append(f'{rev_errors} revision(s) unreachable')
+        skipped = result.get('branch_busy_skipped', 0)
         if skipped:
-            parts.append(f'{skipped} checked-out branch(es) left alone')
+            parts.append(f'{skipped} busy branch(es) left alone')
 
         severity: Literal['information', 'warning'] = (
             'warning' if errors else 'information'
src/tests/test_review_tracking.py +14 -6
index c1f20649..df867938 100644
@@ -4962,8 +4962,8 @@ class TestCmdForget:
         assert self._rows_left('forget-checkedout', 'cid-gone')['series'] == 1
 
 
-class TestUpdateSkipsCheckedOutBranch:
-    """update_series_tracking leaves a checked-out review branch alone."""
+class TestUpdateSkipsABusyWorktree:
+    """update_series_tracking leaves a mid-operation worktree alone."""
 
     def _tracking_data(self, change_id: str) -> Dict[str, Any]:
         return {
@@ -5025,20 +5025,28 @@ class TestUpdateSkipsCheckedOutBranch:
                 series_dict, 'co-test', 'https://example.com/%s', topdir=gitdir
             )
 
-    def test_checked_out_branch_left_alone(self, gitdir: str) -> None:
-        """A checked-out branch is skipped: flag set, tip untouched."""
+    def test_busy_worktree_left_alone(self, gitdir: str) -> None:
+        """A worktree mid-operation is skipped: flag set, tip untouched.
+
+        Checked out is not enough on its own -- the amend reuses the
+        branch's own tree, so a quiescent checkout survives it untouched.
+        What it would strand is the `git am` whose sequencer state names
+        the tip being replaced, and that is what this puts in the way.
+        """
         change_id = 'co-checkedout'
         branch = _create_review_branch(
             gitdir, change_id, self._tracking_data(change_id)
         )
         ecode, _ = b4.git_run_command(gitdir, ['checkout', branch])
         assert ecode == 0
+        # What `git am` leaves behind for as long as it is in flight.
+        os.makedirs(os.path.join(gitdir, '.git', 'rebase-apply'), exist_ok=True)
         ecode, tip_before = b4.git_run_command(gitdir, ['rev-parse', branch])
         assert ecode == 0
 
         result = self._run_update(gitdir, change_id)
 
-        assert result.get('checked_out') is True
+        assert result.get('branch_busy') is True
         assert result.get('error') is None
         ecode, tip_after = b4.git_run_command(gitdir, ['rev-parse', branch])
         assert ecode == 0
@@ -5054,7 +5062,7 @@ class TestUpdateSkipsCheckedOutBranch:
 
         result = self._run_update(gitdir, change_id)
 
-        assert result.get('checked_out') is None
+        assert result.get('branch_busy') is None
         assert result.get('error') == 'Could not find series v1 in retrieved messages'
 
 
Signature · 1 line
2.53.0
#13 lore raw

RFC PATCH v2 13/25 review: test the per-revision poll sweep

In reply to Christian Brauner

Cover the sweep wiring around update_revision_message_counts(): a busy branch keeping its poll while the ref is left alone, the thread snapshot moving onto the catalog row so seen_bump stops re-counting read mail, offline not counting as a failed poll, a poll that raises being counted rather than dropped at debug level, and the cron reporting of per-revision results and unreachable revisions.

---
 src/tests/test_review.py          | 688 ++++++++++++++++++++++++++++++++++++++
 src/tests/test_review_tracking.py | 281 ++++++++++++++++
 src/tests/test_tui_tracking.py    |  29 ++
 3 files changed, 998 insertions(+)
src/tests/test_review.py +688 -0
index 4f566898..a7c9cb15 100644
@@ -1,9 +1,11 @@
 import argparse
 import email.message
 import importlib.util
+import io
 import json
 import logging
 import os
+import sqlite3
 from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
 from unittest import mock
 
@@ -11,6 +13,7 @@ import pytest
 
 import b4
 import b4.review.tracking
+import liblore
 from b4 import review, review_tui
 from b4.review import _review
 from b4.review._review import REVIEW_MAGIC_MARKER, check_series_attestation
@@ -4855,3 +4858,688 @@ class TestCreateReviewBranchCleanup:
         assert ecode == 0
         assert head.strip() == tip
         assert not b4.git_branch_exists(gitdir, branch)
+
+
+def test_update_all_tracking_polls_revisions_capped(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The sweep must actually drive the per-revision poller, with a cap.
+
+    Uncapped this is one lore round-trip per known older revision of every
+    tracked series on every 'U' press.
+    """
+    series = [
+        {'change_id': 'a', 'subject': 's-a', 'status': 'new', 'sender_name': 'A'},
+        {'change_id': 'b', 'subject': 's-b', 'status': 'reviewing', 'sender_name': 'B'},
+    ]
+    monkeypatch.setattr(
+        b4.review.tracking, 'get_all_tracked_series', lambda identifier: series
+    )
+    monkeypatch.setattr(
+        review,
+        'update_series_tracking',
+        lambda one, identifier, linkmask, topdir=None: {
+            'new_revisions': 0,
+            'new_trailers': 0,
+            'error': None,
+        },
+    )
+    calls: List[Dict[str, Any]] = []
+
+    def fake_counts(
+        identifier: str,
+        series_list: List[Dict[str, Any]],
+        topdir: Optional[str] = None,
+        max_revisions_per_series: Optional[int] = None,
+        cancel_cb: Optional[Any] = None,
+        status_cb: Optional[Any] = None,
+        force: bool = False,
+    ) -> Dict[str, int]:
+        calls.append(
+            {
+                'change_ids': [s['change_id'] for s in series_list],
+                'cap': max_revisions_per_series,
+                'cancel_cb': cancel_cb,
+                'force': force,
+            }
+        )
+        return {'updated': 5, 'new_mail': 2, 'errors': 0}
+
+    monkeypatch.setattr(
+        b4.review.tracking, 'update_revision_message_counts', fake_counts
+    )
+    result = review.update_all_tracking(
+        'poller',
+        'https://lore.example/r/%s',
+        cancel_cb=lambda: False,
+    )
+    # One call for the whole list: the poller loops internally and applies
+    # the cap per series, so handing it a series at a time only reopened the
+    # database once per entry.
+    assert [c['change_ids'] for c in calls] == [['a', 'b']]
+    assert {c['cap'] for c in calls} == {b4.review.tracking.REVISION_POLL_LIMIT}
+    assert all(c['cancel_cb'] is not None for c in calls)
+    # Nothing asked for a forced poll, so recently checked versions keep
+    # their minimum-age schedule.
+    assert all(c['force'] is False for c in calls)
+    # The summary reports new mail, not every row the poller touched.
+    assert result['revision_counts_updated'] == 2
+    assert result['revision_errors'] == 0
+
+
+def test_update_all_tracking_reports_revision_poll_errors(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A poller that never works must not look like a quiet mailing list.
+
+    Counted apart from result['errors'], which drives the per-series error
+    report: a revision that will not fetch is not a series that failed.
+    """
+    series = [{'change_id': 'a', 'subject': 's-a', 'status': 'new', 'sender_name': 'A'}]
+    monkeypatch.setattr(
+        b4.review.tracking, 'get_all_tracked_series', lambda identifier: series
+    )
+    monkeypatch.setattr(
+        review,
+        'update_series_tracking',
+        lambda one, identifier, linkmask, topdir=None: {
+            'new_revisions': 0,
+            'new_trailers': 0,
+            'error': None,
+        },
+    )
+    monkeypatch.setattr(
+        b4.review.tracking,
+        'update_revision_message_counts',
+        lambda *a, **kw: {'updated': 0, 'new_mail': 0, 'errors': 3, 'polled': 0},
+    )
+    result = review.update_all_tracking('poller-err', 'https://lore.example/r/%s')
+    assert result['revision_errors'] == 3
+    assert result['revision_polled'] == 0
+    assert result['errors'] == 0
+
+
+def test_update_all_tracking_feeds_poll_progress(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The poll phase reports through the same callback as the series loop.
+
+    It runs after the bar has reached N/N and can be minutes of lore
+    traffic; without its own progress the update modal reads as hung.
+    """
+    series = [{'change_id': 'a', 'subject': 's-a', 'status': 'new', 'sender_name': 'A'}]
+    monkeypatch.setattr(
+        b4.review.tracking, 'get_all_tracked_series', lambda identifier: series
+    )
+    monkeypatch.setattr(
+        review,
+        'update_series_tracking',
+        lambda one, identifier, linkmask, topdir=None: {
+            'new_revisions': 0,
+            'new_trailers': 0,
+            'error': None,
+        },
+    )
+
+    def fake_counts(
+        identifier: str,
+        series_list: List[Dict[str, Any]],
+        topdir: Optional[str] = None,
+        max_revisions_per_series: Optional[int] = None,
+        cancel_cb: Optional[Any] = None,
+        status_cb: Optional[Any] = None,
+        force: bool = False,
+    ) -> Dict[str, int]:
+        assert status_cb is not None
+        status_cb(series_list[0]['subject'])
+        return {'updated': 0, 'new_mail': 0, 'errors': 0, 'polled': 1}
+
+    monkeypatch.setattr(
+        b4.review.tracking, 'update_revision_message_counts', fake_counts
+    )
+    seen: List[Any] = []
+    review.update_all_tracking(
+        'poll-progress',
+        'https://lore.example/r/%s',
+        progress_cb=lambda c, t, s: seen.append((c, t, s)),
+    )
+    # Held at N/N: the series loop already drove the bar there, and the
+    # poller hands over a subject and nothing else, so there is no second
+    # count to walk it backwards.  The label carries the poll's progress.
+    polled = [(c, t) for c, t, s in seen if s.startswith('Polling earlier')]
+    assert polled == [(1, 1)]
+
+
[email protected](
+    ('polled', 'fresh', 'level'),
+    [(0, 3, 'WARNING'), (2, 3, 'DEBUG'), (0, 0, 'DEBUG')],
+)
+def test_cron_reports_unreachable_revisions_only_when_nothing_polled(
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+    polled: int,
+    fresh: int,
+    level: str,
+) -> None:
+    """One dead message-id must not mail the maintainer on every sweep.
+
+    Nothing ever retires a revision whose message-id is permanently gone:
+    it keeps its place in the rotation and fails again on every pass.  A
+    sweep that polled something has a working poller and says so quietly.
+    And an empty sweep is only worth cron mail when something failed for
+    the *first* time: a known-dead revision (attempted before, never
+    fetched once) failing again is old news -- gating on the other
+    revisions' success alone still mailed forever whenever the dead one
+    was the only candidate at all.
+    """
+    monkeypatch.setattr(
+        _review,
+        'update_all_tracking',
+        lambda identifier, linkmask, topdir=None, **kw: {
+            'series_checked': 1,
+            'series_updated': 0,
+            'errors': 0,
+            'gone': 0,
+            'followup_updated': 0,
+            'revision_counts_updated': 0,
+            'revision_errors': 3,
+            'revision_fresh_errors': fresh,
+            'revision_polled': polled,
+            'branch_busy_skipped': 0,
+            'error_details': [],
+            'cancelled': False,
+        },
+    )
+    with caplog.at_level(logging.DEBUG, logger=b4.logger.name):
+        _review._cron_update('cron-poller', None)
+    records = [r for r in caplog.records if 'Could not poll' in r.getMessage()]
+    assert [r.levelname for r in records] == [level]
+
+
+def test_update_all_tracking_cancelled_poller_stops_sweep(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Cancellation now reaches the handler -- the fetch helpers used to
+    swallow OperationCancelledError, making that branch unreachable.
+
+    The poll is one batched call after the series loop, so a cancel raised
+    there marks the sweep cancelled without unwinding the per-series work
+    that already finished.  A cancel the *maintainer* asks for still stops
+    the series loop itself: it checks cancel_cb at the top of every pass.
+    """
+    series = [
+        {'change_id': 'a', 'subject': 's-a', 'status': 'new', 'sender_name': 'A'},
+        {'change_id': 'b', 'subject': 's-b', 'status': 'new', 'sender_name': 'B'},
+    ]
+    monkeypatch.setattr(
+        b4.review.tracking, 'get_all_tracked_series', lambda identifier: series
+    )
+    monkeypatch.setattr(
+        review,
+        'update_series_tracking',
+        lambda one, identifier, linkmask, topdir=None: {
+            'new_revisions': 0,
+            'new_trailers': 0,
+            'error': None,
+        },
+    )
+
+    def cancelled(*a: Any, **kw: Any) -> Dict[str, int]:
+        raise liblore.OperationCancelledError('Request cancelled')
+
+    monkeypatch.setattr(b4.review.tracking, 'update_revision_message_counts', cancelled)
+    result = review.update_all_tracking('poller-cancel', 'https://lore.example/r/%s')
+    assert result['cancelled'] is True
+    assert result['series_checked'] == 2
+
+
+def _stub_sweep(monkeypatch: pytest.MonkeyPatch, series: List[Dict[str, Any]]) -> None:
+    """Point update_all_tracking at *series* with a no-op per-series update."""
+    monkeypatch.setattr(
+        b4.review.tracking, 'get_all_tracked_series', lambda identifier: series
+    )
+    monkeypatch.setattr(
+        review,
+        'update_series_tracking',
+        lambda one, identifier, linkmask, topdir=None: {
+            'new_revisions': 0,
+            'new_trailers': 0,
+            'error': None,
+        },
+    )
+
+
+def test_a_busy_branch_still_polls_its_revisions(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Only the branch is left alone, not the per-revision poll.
+
+    The poll writes DB rows and a loose blob and moves no ref, while a
+    series under review is normally the checked-out branch -- so skipping
+    it there is skipping it almost always, and late replies to old
+    versions stop being noticed at all.
+    """
+    series = [
+        {'change_id': 'a', 'subject': 's-a', 'status': 'new', 'sender_name': 'A'},
+        {'change_id': 'b', 'subject': 's-b', 'status': 'new', 'sender_name': 'B'},
+    ]
+    monkeypatch.setattr(
+        b4.review.tracking, 'get_all_tracked_series', lambda identifier: series
+    )
+    monkeypatch.setattr(
+        review,
+        'update_series_tracking',
+        lambda one, identifier, linkmask, topdir=None: {
+            'new_revisions': 0,
+            'new_trailers': 0,
+            'error': None,
+            'branch_busy': one['change_id'] == 'a',
+        },
+    )
+    polled: List[str] = []
+
+    def _record(
+        identifier: str, series_list: List[Dict[str, Any]], **kw: Any
+    ) -> Dict[str, int]:
+        polled.extend(s['change_id'] for s in series_list)
+        return {'updated': 0, 'new_mail': 0, 'errors': 0}
+
+    monkeypatch.setattr(b4.review.tracking, 'update_revision_message_counts', _record)
+    result = review.update_all_tracking('poll-co', 'https://lore.example/r/%s')
+    # 'a' is the checked-out one, and it is still handed to the poller.
+    assert polled == ['a', 'b']
+    assert result['branch_busy_skipped'] == 1
+
+
+def test_update_all_tracking_forwards_the_forced_poll(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A user-initiated sweep polls recently checked versions too.
+
+    The poller's minimum-age skip exists for unattended sweeps; on an
+    explicit u/U it silently withheld exactly the per-version counts the
+    refresh was pressed for.
+    """
+    series = [{'change_id': 'a', 'subject': 's-a', 'status': 'new', 'sender_name': 'A'}]
+    monkeypatch.setattr(
+        b4.review.tracking, 'get_all_tracked_series', lambda identifier: series
+    )
+    monkeypatch.setattr(
+        review,
+        'update_series_tracking',
+        lambda one, identifier, linkmask, topdir=None: {
+            'new_revisions': 0,
+            'new_trailers': 0,
+            'error': None,
+        },
+    )
+    forced: List[bool] = []
+
+    def fake_counts(
+        identifier: str,
+        series_list: List[Dict[str, Any]],
+        force: bool = False,
+        **kw: Any,
+    ) -> Dict[str, int]:
+        forced.append(force)
+        return {'updated': 0, 'new_mail': 0, 'errors': 0}
+
+    monkeypatch.setattr(
+        b4.review.tracking, 'update_revision_message_counts', fake_counts
+    )
+    review.update_all_tracking(
+        'force-poll', 'https://lore.example/r/%s', force_revision_poll=True
+    )
+    assert forced == [True]
+
+
+def test_busy_reported_only_when_an_update_was_forgone(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The busy-branch report follows the statuses whose branch the sweep writes.
+
+    branch_busy guards every ref writer, but an accepted or thanked
+    series' branch was never going to be written -- counting it made the
+    'N checked-out branch(es) left alone' toast report branches the sweep
+    never touches, on every sweep, for as long as they stay checked out.
+    """
+    monkeypatch.setattr(b4, 'git_worktree_busy', lambda topdir, branch: True)
+    monkeypatch.setattr(
+        b4.review.tracking, 'store_revision_thread_blob', lambda *a, **kw: None
+    )
+    monkeypatch.setattr(b4.review.tracking, '_store_thread_blob', lambda *a, **kw: None)
+
+    def _run(status: str) -> Dict[str, Any]:
+        identifier = f'cog-{status}'
+        change_id = f'cog-{status}-cid'
+        conn = b4.review.tracking.init_db(identifier)
+        b4.review.tracking.add_series_to_db(
+            conn,
+            change_id,
+            1,
+            'Subject',
+            'Author',
+            '[email protected]',
+            '2024-01-15T10:00:00+00:00',
+            '[email protected]',
+            2,
+        )
+        b4.review.tracking.update_series_status(conn, change_id, status)
+        conn.close()
+
+        msg = email.message.EmailMessage()
+        msg['Message-Id'] = f'<{change_id}[email protected]>'
+        msg['Date'] = 'Mon, 27 Jul 2026 10:00:00 +0000'
+        mock_lmbx = mock.Mock()
+        mock_lmbx.series = {}
+        mock_lmbx.covers = {}
+        mock_lmbx.get_series.return_value = None
+        series_dict: Dict[str, Any] = {
+            'change_id': change_id,
+            'revision': 1,
+            'status': status,
+            'message_id': '[email protected]',
+        }
+        with (
+            mock.patch(
+                'b4.review._review.retrieve_series_messages', return_value=[msg]
+            ),
+            mock.patch('b4.LoreMailbox', return_value=mock_lmbx),
+        ):
+            return review.update_series_tracking(
+                series_dict, identifier, 'https://example.com/%s', topdir='/nonexistent'
+            )
+
+    assert _run('reviewing').get('branch_busy') is True
+    assert not _run('accepted').get('branch_busy')
+
+
+def _seed_catalog_blob(identifier: str, blob_sha: str) -> None:
+    conn = b4.review.tracking.init_db(identifier)
+    b4.review.tracking.add_revision(conn, 'cid', 1, 'v1@x')
+    conn.execute(
+        "UPDATE revisions SET thread_blob = ? WHERE change_id = 'cid'", (blob_sha,)
+    )
+    conn.commit()
+    conn.close()
+
+
+def test_prev_thread_msgids_reads_the_catalog_snapshot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The catalog row's blob outranks the tracking commit's.
+
+    The catalog copy advances on every counted fetch, including sweeps
+    that leave a checked-out branch's ref alone; the tracking commit's
+    blob is frozen then, and deriving seen bumps from it re-counted the
+    same read messages as new on every sweep.
+    """
+    _seed_catalog_blob('prev-snap', 'c0ffee')
+    msgs = []
+    for i in range(2):
+        msg = email.message.EmailMessage()
+        msg['Message-Id'] = f'<prev-{i}@example.com>'
+        msg['Date'] = 'Mon, 27 Jul 2026 10:00:00 +0000'
+        msg.set_content('body')
+        msgs.append(msg)
+    buf = io.BytesIO()
+    b4.save_mboxrd_mbox(msgs, buf)
+    asked: List[str] = []
+
+    def _mbox(topdir: str, sha: str) -> bytes:
+        asked.append(sha)
+        return buf.getvalue()
+
+    monkeypatch.setattr(b4.review.tracking, 'get_thread_mbox', _mbox)
+
+    def _no_branch(*a: Any, **kw: Any) -> bool:
+        raise AssertionError('tracking commit consulted despite a catalog snapshot')
+
+    monkeypatch.setattr(b4, 'git_branch_exists', _no_branch)
+    got = _review._prev_thread_msgids('/nonexistent', 'prev-snap', 'cid', 1)
+    assert asked == ['c0ffee']
+    assert got == {'[email protected]', '[email protected]'}
+
+
+def test_prev_thread_msgids_pruned_catalog_blob_is_no_snapshot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A recorded blob that no longer reads back yields None, not a fallback.
+
+    The tracking commit's copy is older than the pruned one, and bumps
+    against it were already applied; "cannot tell which messages are
+    new" is the honest answer.
+    """
+    _seed_catalog_blob('prev-gcd', 'deadbeef')
+    monkeypatch.setattr(b4.review.tracking, 'get_thread_mbox', lambda topdir, sha: None)
+
+    def _no_branch(*a: Any, **kw: Any) -> bool:
+        raise AssertionError('tracking commit consulted despite a catalog snapshot')
+
+    monkeypatch.setattr(b4, 'git_branch_exists', _no_branch)
+    assert _review._prev_thread_msgids('/nonexistent', 'prev-gcd', 'cid', 1) is None
+
+
+def test_a_raising_poller_is_counted_not_swallowed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """At debug level the whole feature can break while sweeps look clean."""
+    _stub_sweep(
+        monkeypatch,
+        [{'change_id': 'a', 'subject': 's-a', 'status': 'new', 'sender_name': 'A'}],
+    )
+
+    def _boom(*a: Any, **kw: Any) -> Dict[str, int]:
+        raise sqlite3.OperationalError('database is locked')
+
+    monkeypatch.setattr(b4.review.tracking, 'update_revision_message_counts', _boom)
+    result = review.update_all_tracking('poll-raise', 'https://lore.example/r/%s')
+    assert result['revision_errors'] == 1
+    # Still not a per-series failure: the series itself updated fine.
+    assert result['errors'] == 0
+
+
+def test_a_cancelled_sweep_does_not_start_the_poller(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The poll is minutes of lore traffic; a cancel must land before it."""
+    _stub_sweep(
+        monkeypatch,
+        [{'change_id': 'a', 'subject': 's-a', 'status': 'new', 'sender_name': 'A'}],
+    )
+    called: List[int] = []
+
+    def _record(*a: Any, **kw: Any) -> Dict[str, int]:
+        called.append(1)
+        return {'updated': 0, 'new_mail': 0, 'errors': 0}
+
+    monkeypatch.setattr(b4.review.tracking, 'update_revision_message_counts', _record)
+    review.update_all_tracking(
+        'poll-cancelled', 'https://lore.example/r/%s', cancel_cb=lambda: True
+    )
+    assert called == []
+
+
+class TestCancelledPollKeepsItsTally:
+    """A cancel mid-poll must not discard the work already committed.
+
+    The per-revision poller commits each revision as it goes, so a cancel
+    raised on revision N leaves revisions 1..N-1 counted in the database.
+    Reporting that sweep as `{'revision_polled': 0}` makes those badges
+    appear with nothing having announced them -- and makes a permanently
+    broken poller read exactly like a cancelled one.
+    """
+
+    @staticmethod
+    def _msgs(count: int) -> List[Any]:
+        """A thread of *count* messages, each carrying a Date header."""
+        out: List[Any] = []
+        for i in range(count):
+            msg = email.message.EmailMessage()
+            msg['Message-ID'] = f'<poll-{i}@example.com>'
+            msg['Subject'] = f'Re: [PATCH] thing ({i})'
+            msg['Date'] = 'Tue, 07 Jul 2026 12:00:00 +0000'
+            msg.set_content(f'body {i}')
+            out.append(msg)
+        return out
+
+    def test_partial_poll_tallies_survive_a_cancel(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any
+    ) -> None:
+        identifier = 'poll-cancel-partial'
+        conn = b4.review.tracking.init_db(identifier)
+        # Two older versions, both already counted once: a second fetch that
+        # grows is then real new mail rather than a first count, which the
+        # sweep deliberately does not report as new mail.
+        for rev in (1, 2):
+            b4.review.tracking.add_revision(conn, 'a', rev, f'a-v{rev}@example.com')
+        conn.execute(
+            'UPDATE revisions SET message_count = 2, seen_message_count = 2'
+            " WHERE change_id = 'a'"
+        )
+        conn.commit()
+        conn.close()
+
+        series = [
+            {
+                'change_id': 'a',
+                'revision': 3,
+                'subject': 's-a',
+                'status': 'new',
+                'sender_name': 'A',
+            }
+        ]
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            b4.review.tracking, 'get_all_tracked_series', lambda identifier: series
+        )
+        monkeypatch.setattr(
+            review,
+            'update_series_tracking',
+            lambda one, identifier, linkmask, topdir=None: {
+                'new_revisions': 0,
+                'new_trailers': 0,
+                'error': None,
+            },
+        )
+
+        fetched: List[int] = []
+
+        def fetch(
+            identifier_: str,
+            conn_: Any,
+            change_id: str,
+            rev: Dict[str, Any],
+        ) -> List[Any]:
+            fetched.append(int(rev['revision']))
+            if len(fetched) == 1:
+                # Grew 2 -> 3: one revision's worth of genuine new mail,
+                # committed before the cancel lands.
+                return TestCancelledPollKeepsItsTally._msgs(3)
+            raise liblore.OperationCancelledError('Request cancelled')
+
+        monkeypatch.setattr(b4.review.tracking, '_fetch_revision_thread_msgs', fetch)
+
+        result = review.update_all_tracking(identifier, 'https://lore.example/r/%s')
+
+        # One revision completed, the next raised.
+        assert len(fetched) == 2
+        assert result['cancelled'] is True
+
+        # The completed revision really is committed -- this is the work the
+        # summary below has to account for, not a hypothetical.
+        conn = b4.review.tracking.get_db(identifier)
+        grown = conn.execute(
+            "SELECT COUNT(*) FROM revisions WHERE change_id = 'a' AND message_count = 3"
+        ).fetchone()[0]
+        conn.close()
+        assert grown == 1
+
+        # ...so the sweep must report it rather than returning zeros.
+        assert result['revision_polled'] == 1
+        assert result['revision_counts_updated'] == 1
+
+
+class TestExplicitUpdateReachesASnoozedSeries:
+    """[u] on one row is a question about that row, [U] is a sweep.
+
+    An explicit single-series update already spends the larger network
+    cost on a snoozed series -- update_all_tracking does not filter a
+    caller-supplied series_list, so the tracked revision's thread is
+    fetched and its trailers re-read.  Declining only the cheaper
+    per-revision top-up afterwards is not a network-thrift policy, it is
+    an inconsistency: the maintainer asked about this series and got a
+    partial answer with nothing saying so.  The scheduled sweep keeps
+    skipping snoozed rows, which is what 'snoozed' is for.
+    """
+
+    @staticmethod
+    def _seed(identifier: str) -> List[Dict[str, Any]]:
+        conn = b4.review.tracking.init_db(identifier)
+        for rev in (1, 2):
+            b4.review.tracking.add_revision(conn, 'snz', rev, f'snz-v{rev}@example.com')
+        conn.close()
+        return [
+            {
+                'change_id': 'snz',
+                'revision': 2,
+                'subject': 's-snz',
+                'status': 'snoozed',
+                'sender_name': 'S',
+            }
+        ]
+
+    def _run(
+        self,
+        identifier: str,
+        monkeypatch: pytest.MonkeyPatch,
+        forced: bool,
+    ) -> List[int]:
+        series_list = self._seed(identifier)
+        monkeypatch.setattr(b4, 'can_network', True)
+        monkeypatch.setattr(
+            review,
+            'update_series_tracking',
+            lambda one, ident, linkmask, topdir=None: {
+                'new_revisions': 0,
+                'new_trailers': 0,
+                'error': None,
+            },
+        )
+        fetched: List[int] = []
+
+        def fetch(
+            ident: str, conn: Any, change_id: str, rev: Dict[str, Any]
+        ) -> List[Any]:
+            fetched.append(int(rev['revision']))
+            msg = email.message.EmailMessage()
+            msg['Message-ID'] = '<[email protected]>'
+            msg['Date'] = 'Tue, 07 Jul 2026 12:00:00 +0000'
+            msg.set_content('late reply')
+            return [msg]
+
+        monkeypatch.setattr(b4.review.tracking, '_fetch_revision_thread_msgs', fetch)
+        review.update_all_tracking(
+            identifier,
+            'https://lore.example/r/%s',
+            series_list=series_list,
+            force_revision_poll=forced,
+        )
+        return fetched
+
+    def test_u_polls_the_older_versions_of_a_snoozed_series(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any
+    ) -> None:
+        """[u] is the maintainer asking now -- answer about every version."""
+        assert self._run('snooze-forced', monkeypatch, forced=True) == [1]
+
+    def test_the_scheduled_sweep_still_leaves_a_snoozed_series_alone(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any
+    ) -> None:
+        """...but nothing unattended goes near it.
+
+        Pinned alongside the case above so the fix cannot be "drop
+        skip_statuses", which would put every snoozed series back into
+        the cron sweep's lore budget.
+        """
+        assert self._run('snooze-sweep', monkeypatch, forced=False) == []
src/tests/test_review_tracking.py +281 -0

296 lines not on this page · raw message

src/tests/test_tui_tracking.py +29 -0
index cc80e7b1..2803bf3d 100644
@@ -6001,3 +6001,32 @@ class TestRethreadFlagReachesTheThreadFetch:
             screen._fetch_thread()
         assert seen['is_rethreaded'] is True
         assert seen['revision'] == 2
+
+
+class TestUpdateAllDoesNotForceThePoll:
+    """'u' asks about one series; 'U' must not force the schedule everywhere.
+
+    Both keys push the same UpdateAllScreen, so a single flag on the screen
+    made 'U' bypass the minimum-age skip for every non-snoozed series --
+    REVISION_POLL_LIMIT round-trips apiece where a scheduled sweep would
+    have done almost none.
+    """
+
+    @pytest.mark.asyncio
+    async def test_u_forces_and_capital_u_does_not(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        _seed_db('force-scope', SAMPLE_SERIES)
+        seen = []
+
+        app = TrackingApp('force-scope')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            with patch.object(
+                app, 'push_screen', lambda s, callback=None: seen.append(s)
+            ):
+                app.action_update_one()
+                app.action_update_all()
+        assert len(seen) == 2
+        assert seen[0]._force_revision_poll is True
+        assert seen[1]._force_revision_poll is False
Signature · 1 line
2.53.0
#14 lore raw

RFC PATCH v2 14/25 review-tui: resolve the tracked revision in revision lists

In reply to Christian Brauner

The revisions catalog is not guaranteed a row for the tracked revision, since manually linking a newer version records only that one. Anything reasoning about the versions of a series from the catalog alone can therefore omit the version the maintainer is actually on, and a range-diff then cannot resolve the side it is taken against, on a row whose binding was enabled on exactly that basis.

Add merge_tracked_revisions(), which appends an entry synthesized from the series row when the catalog lacks one, and route both readers through
it: the DB-side resolver get_revisions_with_tracked() and the TUI's row builder. The versions shown and the versions a range-diff can resolve are then always the same set.

It covers every live series row, not just the furthest along. rescan_branches() can leave a change_id with more than one and the tracking list renders each separately, so resolving only one would enable the range-diff on a version row whose message-id cannot then be found.

The synthesized entry carries neither blob nor read state. Both live on the catalog row it stands in for, so a series row that never got one has none to report.

---
 src/b4/review/tracking.py          | 100 +++++++++++++++++++++++++++++++++++++
 src/b4/review_tui/_common.py       |   6 ++-
 src/b4/review_tui/_tracking_app.py |  34 +++++++++++++
 3 files changed, 139 insertions(+), 1 deletion(-)
src/b4/review/tracking.py +100 -0
index 1b26d722..c8d9e7d9 100644
@@ -1649,6 +1649,106 @@ def get_revisions(conn: sqlite3.Connection, change_id: str) -> list[dict[str, An
     return [dict(zip(_REVISION_COLS, row)) for row in cursor.fetchall()]
 
 
+def merge_tracked_revisions(
+    change_id: str,
+    revs: List[dict[str, Any]],
+    series_rows: List[dict[str, Any]],
+) -> List[dict[str, Any]]:
+    """Merge catalog *revs* with the revisions the *series_rows* track.
+
+    A catalog row for a tracked revision is not guaranteed -- manually
+    linking a newer version records only that one -- so anything that
+    reasons about "the versions of this series" from the catalog alone
+    can silently omit the one the maintainer is actually on.  Synthesize
+    an entry from the series row when it is missing.
+
+    Every series row, not just one: rescan_branches can leave a change_id
+    with more than one, and the tracking list renders each of them
+    separately.  Resolving only one would enable the range-diff on a
+    version row whose message-id cannot then be found.  Both the DB
+    resolver (:func:`get_revisions_with_tracked`) and the TUI's row
+    builder go through here, so the versions shown and the versions the
+    range-diff can resolve are always the same set.
+
+    Every write path that points a series row at a revision catalogues it
+    first (:func:`_ensure_catalog_row`), and the v11 backfill did the same
+    for every row that predates that rule, so this is a fallback for a
+    database written before it and not a reconciliation step: nothing here
+    fixes up a value the catalog also holds.
+
+    The synthesized entry carries neither blob nor read state.  Both live
+    on the catalog row this one stands in for, so a series row that never
+    got one has none to report -- the entry exists to supply a message-id
+    and a subject, not a badge.
+
+    *series_rows* entries carry ``revision``, ``message_id``, ``subject``,
+    ``found_at``, ``fingerprint`` and ``is_rethreaded``.
+    """
+    revs = list(revs)
+    known = {int(r['revision']) for r in revs if r.get('revision') is not None}
+    added = False
+    for row in series_rows:
+        if not row.get('message_id'):
+            continue
+        tracked = int(row.get('revision') or 1)
+        if tracked in known:
+            continue
+        known.add(tracked)
+        added = True
+        revs.append(
+            {
+                'change_id': change_id,
+                'revision': tracked,
+                'message_id': row['message_id'],
+                'subject': row.get('subject'),
+                'link': '',
+                'found_at': row.get('found_at') or '',
+                'thread_blob': '',
+                'series_blob': '',
+                'fingerprint': row.get('fingerprint'),
+                'source': 'tracked',
+                'is_rethreaded': bool(row.get('is_rethreaded')),
+                'message_count': None,
+                'seen_message_count': None,
+                'last_update_check': None,
+                'last_mail_at': None,
+            }
+        )
+    if added:
+        revs.sort(key=lambda r: r.get('revision') or 0)
+    return revs
+
+
+def get_revisions_with_tracked(
+    conn: sqlite3.Connection, change_id: str
+) -> list[dict[str, Any]]:
+    """get_revisions(), guaranteed to include the revision being tracked.
+
+    :func:`merge_tracked_revisions` over the catalog and every live series
+    row -- see there for why the merge works the way it does.
+    """
+    # Positional access: callers may hand us a connection without a
+    # sqlite3.Row factory (init_db does not set one).
+    rows = [
+        {
+            'revision': row[0],
+            'message_id': row[1],
+            'subject': row[2],
+            'found_at': row[3],
+            'fingerprint': row[4],
+            'is_rethreaded': row[5],
+        }
+        for row in conn.execute(
+            'SELECT revision, message_id, subject, COALESCE(sent_at, added_at),'
+            ' fingerprint, is_rethreaded FROM series'
+            " WHERE change_id = ? AND COALESCE(status, 'new') != 'archived'"
+            ' ORDER BY revision DESC',
+            (change_id,),
+        )
+    ]
+    return merge_tracked_revisions(change_id, get_revisions(conn, change_id), rows)
+
+
 def find_revision_by_fingerprint(
     conn: sqlite3.Connection, fingerprint: Optional[str]
 ) -> Optional[dict[str, Any]]:
src/b4/review_tui/_common.py +5 -1
index 34cd5d28..2f161c2c 100644
@@ -1237,7 +1237,11 @@ def compute_range_diff(
     """
     try:
         conn = b4.review.tracking.get_db(identifier)
-        revisions = b4.review.tracking.get_revisions(conn, change_id)
+        # Must include the tracked revision even when the catalog has no
+        # row for it, or the side this diff is taken against cannot be
+        # resolved -- and the TUI enables the action on exactly that
+        # basis.
+        revisions = b4.review.tracking.get_revisions_with_tracked(conn, change_id)
         conn.close()
     except Exception as ex:
         logger.critical('Could not load revisions: %s', ex)
src/b4/review_tui/_tracking_app.py +34 -0
index 31601ded..bcad86f3 100644
@@ -1746,6 +1746,40 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
             )
         )
 
+    @staticmethod
+    def _merge_tracked_revision(series: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Known revisions of a series, guaranteed to include the tracked ones.
+
+        tracking.merge_tracked_revisions() over the preloaded catalog rows
+        and every live series row of the change_id (stashed by
+        _load_series), so the version rows shown here and the revisions
+        compute_range_diff can resolve are always the same set.
+
+        Memoized onto the series dict: the answer gates two bindings, so it
+        is recomputed on every refresh_bindings() for every cursor move.
+        _load_series rebuilds these dicts from scratch, which is what keeps
+        the memo from outliving the data it was derived from.
+        """
+        cached: Optional[List[Dict[str, Any]]] = series.get('_versions')
+        if cached is not None:
+            return cached
+        rows = [
+            {
+                'revision': s.get('revision', 1),
+                'message_id': s.get('message_id', ''),
+                'subject': s.get('subject'),
+                'found_at': s.get('sent_at') or s.get('added_at') or '',
+                'fingerprint': s.get('fingerprint'),
+                'is_rethreaded': s.get('is_rethreaded'),
+            }
+            for s in (series.get('_sibling_rows') or [series])
+        ]
+        revs = b4.review.tracking.merge_tracked_revisions(
+            series.get('change_id', ''), series.get('_revisions') or [], rows
+        )
+        series['_versions'] = revs
+        return revs
+
     def _checkout_new_series(self) -> None:
         """Retrieve series, build am-ready mbox, and show base selection."""
         series = self._selected_series
Signature · 1 line
2.53.0
#15 lore raw

RFC PATCH v2 15/25 review-tui: fall back when a cached thread blob has no series

In reply to Christian Brauner

fetch_fake_am_range() trusted revisions.thread_blob unconditionally: any non-empty blob short-circuited the lore fetch, and if the series could not be built from it the function gave up rather than trying the path that would have worked.

That was safe while the column was only ever written from a complete tracked-series thread at upgrade time. It is not now that the revision poller caches whatever thread it counted, which for a version the backward search records as plain despite broken threading is a single patch's thread. Range-diff against such a version then failed permanently, since the bad blob was preferred on every attempt.

Build the series before committing to the blob, and refetch when it does not yield one: the lore path runs the get_extra_series() passes that stitch a broken-threaded version back together. Store what those passes produced as the revision's series_blob, beside the thread rather than over it, since the thread is still what a poll counts and what the next fetch is diffed against. The following range-diff reads it back instead of paying for the stitching again. An incomplete cached thread is kept as a fallback for a refetch that cannot run at all.

---
 src/b4/review_tui/_common.py | 167 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 136 insertions(+), 31 deletions(-)
src/b4/review_tui/_common.py +136 -31
index 2f161c2c..b90d6815 100644
@@ -1158,17 +1158,21 @@ def fetch_fake_am_range(
     topdir: str,
     revisions: List[Dict[str, Any]],
     rev: int,
+    recache: Optional[Callable[[int, List[Any]], None]] = None,
 ) -> Optional[Tuple[str, str]]:
     """Fetch a revision and create a fake-am commit range.
 
-    Tries the cached thread blob from the revisions table first,
-    falling back to a lore fetch if the blob is absent or GC'd.
+    Three sources, cheapest first: the stitched ``series_blob`` recorded by
+    an earlier call, the ``thread_blob`` a poll cached when it holds the
+    whole series, and lore.  Any of them may be absent or GC'd.
+
+    *recache*, when given, is handed the stitched messages behind whatever
+    this ends up using so the caller can record them as the revision's
+    series blob.  It is what keeps the next call off the lore path, for a
+    version whose thread does not carry every patch and never will.
 
     Returns (range_start, range_end) on success, or None on failure.
     """
-    msgs = None
-    msgid = ''
-
     # Locate this revision's record
     rev_record: Dict[str, Any] = {}
     for r in revisions:
@@ -1176,36 +1180,120 @@ def fetch_fake_am_range(
             rev_record = r
             break
 
-    # Try cached thread blob first (may be absent or GC'd — tolerate both)
-    blob_sha = rev_record.get('thread_blob') or ''
-    if blob_sha:
-        mbox_bytes = b4.review.tracking.get_thread_mbox(topdir, blob_sha)
-        if mbox_bytes:
-            logger.info('Using cached thread blob for v%d', rev)
-            msgs = b4.split_and_dedupe_pi_results(mbox_bytes)
+    def _series_from(msgs: List[Any]) -> Optional['b4.LoreSeries']:
+        lmbx = b4.LoreMailbox()
+        for msg in msgs:
+            lmbx.add_message(msg)
+        return lmbx.get_series(rev, sloppytrailers=False, codereview_trailers=False)
 
-    # Fall back to lore fetch
-    if not msgs:
-        msgid = rev_record.get('message_id', '')
-        if not msgid:
-            logger.critical('No message-id recorded for v%d', rev)
+    def _known_patches(lser: Optional['b4.LoreSeries']) -> int:
+        """How many of a series' patches are actually in hand.
+
+        Absent counts as none, so the comparisons below need no companion
+        None test: "did this source do better?" is the only question, and
+        having nothing is the bottom of that order rather than a separate
+        case.
+        """
+        if lser is None:
+            return 0
+        return sum(1 for p in (lser.patches or [])[1:] if p is not None)
+
+    def _cached(blob_sha: str) -> Optional[List[Any]]:
+        if not blob_sha:
+            return None
+        mbox_bytes = b4.review.tracking.get_thread_mbox(topdir, blob_sha)
+        if not mbox_bytes:
             return None
+        return b4.split_and_dedupe_pi_results(mbox_bytes)
+
+    # The fullest reconstruction seen so far, whichever source it came
+    # from.  An incomplete range-diff beats none, so this is what the lore
+    # passes below have to improve on to be worth using.
+    partial: Optional['b4.LoreSeries'] = None
+
+    # A recorded series blob is this revision stitched, and it is dropped
+    # the moment its thread changes -- but only a *complete* one is an
+    # answer.  Returning a short stitch unconditionally pinned every later
+    # range-diff to it: a settled version's thread never changes, so the
+    # blob is never dropped and the passes below never run again.  It is
+    # the same completeness test the thread arm applies, for the same
+    # reason.
+    stitched = _cached(rev_record.get('series_blob') or '')
+    if stitched:
+        lser = _series_from(stitched)
+        if lser is not None and lser.complete:
+            logger.info('Using cached series blob for v%d', rev)
+            return _fake_am_range_from(topdir, lser, rev)
+        partial = lser
+
+    # The thread as last fetched, which for most versions is the whole
+    # series and costs nothing further.
+    cached_msgs = _cached(rev_record.get('thread_blob') or '')
+    if cached_msgs:
+        logger.info('Using cached thread blob for v%d', rev)
+        lser = _series_from(cached_msgs)
+        if lser is not None and lser.complete:
+            return _fake_am_range_from(topdir, lser, rev)
+        # get_series() returns None only when every patch is missing; a
+        # merely short series comes back complete=False.  Either way the
+        # thread does not hold the version, and only the get_extra_series()
+        # passes below can stitch the rest back together.
+        if _known_patches(lser) > _known_patches(partial):
+            partial = lser
+        logger.info('Cached thread for v%d is incomplete, refetching', rev)
+
+    msgid = rev_record.get('message_id', '')
+    if not msgid:
+        logger.critical('No message-id recorded for v%d', rev)
+        return _fake_am_range_from(topdir, partial, rev)
 
-        logger.info('Fetching v%d from lore...', rev)
-        with lore_request():
-            msgs = b4.get_pi_thread_by_msgid(msgid)
-            if not msgs:
-                logger.critical('Could not retrieve thread for v%d', rev)
-                return None
+    logger.info('Fetching v%d from lore...', rev)
+    with lore_request():
+        msgs: List[Any] = b4.get_pi_thread_by_msgid(msgid) or []
+        if not msgs:
+            logger.critical('Could not retrieve thread for v%d', rev)
+            return _fake_am_range_from(topdir, partial, rev)
+
+        msgs = b4.mbox.get_extra_series(msgs, direction=1, wantvers=[rev])
+        msgs = b4.mbox.get_extra_series(msgs, direction=-1, wantvers=[rev])
+    lser = _series_from(msgs)
+    if lser is None or _known_patches(lser) <= _known_patches(partial):
+        # The passes came back no more complete than what is already
+        # cached, so that cache is all there is of this version.  Nothing
+        # was stitched here, so nothing is recorded: writing the cached
+        # bytes back as a `series_blob` would file them under a name
+        # meaning "every patch of this version", which is the one thing
+        # they are not -- and the arm above would then trust them.
+        if partial is not None:
+            if lser is None:
+                logger.info(
+                    'Refetch of v%d failed, using the incomplete cached thread', rev
+                )
+            else:
+                logger.info(
+                    'Refetch of v%d is no better than the cache, keeping it', rev
+                )
+        return _fake_am_range_from(topdir, partial, rev)
+
+    # Record what the stitching produced, so the next press of 'd' takes
+    # the branch above instead of three more lore round-trips -- but only
+    # when it is the whole version.  `series_blob` means "every patch of
+    # this version", and its reader returns it without re-deriving that; a
+    # short stitch stays a fallback, and the thread it improved on is
+    # already cached beside it.
+    if recache is not None and msgs and lser.complete:
+        try:
+            recache(rev, msgs)
+        except Exception as ex:
+            logger.debug('Could not re-cache series for v%d: %s', rev, ex)
 
-            msgs = b4.mbox.get_extra_series(msgs, direction=1, wantvers=[rev])
-            msgs = b4.mbox.get_extra_series(msgs, direction=-1, wantvers=[rev])
+    return _fake_am_range_from(topdir, lser, rev)
 
-    lmbx = b4.LoreMailbox()
-    for msg in msgs:
-        lmbx.add_message(msg)
 
-    lser = lmbx.get_series(rev, sloppytrailers=False, codereview_trailers=False)
+def _fake_am_range_from(
+    topdir: str, lser: Optional['b4.LoreSeries'], rev: int
+) -> Optional[Tuple[str, str]]:
+    """Build the fake-am range for *lser*, or fail loudly if there is none."""
     if lser is None:
         logger.critical('Could not find series v%d in retrieved messages', rev)
         return None
@@ -1247,6 +1335,23 @@ def compute_range_diff(
         logger.critical('Could not load revisions: %s', ex)
         return None
 
+    def _recache(rev: int, msgs: List[Any]) -> None:
+        """Store a stitched series so the next range-diff hits the cache.
+
+        Beside the thread blob rather than over it: a poll caches whatever
+        single thread it counted, which for a version posted with broken
+        threading is one patch's, and that thread is still the right
+        baseline for counting new mail even though it will never satisfy
+        fetch_fake_am_range().
+        """
+        conn = b4.review.tracking.get_db(identifier)
+        try:
+            b4.review.tracking.store_revision_series_blob(
+                conn, topdir, change_id, rev, msgs
+            )
+        finally:
+            conn.close()
+
     # --- Resolve the current revision range ---
     # Use local review branch if available, otherwise fetch from lore
     branch = f'b4/review/{change_id}'
@@ -1267,13 +1372,13 @@ def compute_range_diff(
 
     if not cur_start or not cur_end:
         # No local branch — fetch from lore
-        result = fetch_fake_am_range(topdir, revisions, current_rev)
+        result = fetch_fake_am_range(topdir, revisions, current_rev, recache=_recache)
         if result is None:
             return None
         cur_start, cur_end = result
 
     # --- Fetch the other version (blob SHA comes from the revisions table) ---
-    result = fetch_fake_am_range(topdir, revisions, other_rev)
+    result = fetch_fake_am_range(topdir, revisions, other_rev, recache=_recache)
     if result is None:
         return None
     other_start, other_end = result
Signature · 1 line
2.53.0
#16 lore raw

RFC PATCH v2 16/25 review-tui: test revision resolution and the range-diff fallback

In reply to Christian Brauner

Cover merge_tracked_revisions() and get_revisions_with_tracked(): the synthesized entry, every live series row contributing one, and neither blob nor read state coming across. Cover fetch_fake_am_range()'s three
sources: the stitched series blob, a cached thread that does hold the whole series, and the lore refetch for one that does not, including the incomplete cache kept as a fallback and the stitched result stored back.

---
 src/tests/test_review_tracking.py | 105 +++++++++++++++
 src/tests/test_tui_review.py      | 274 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 378 insertions(+), 1 deletion(-)
src/tests/test_review_tracking.py +105 -0
index e2fcdf85..145fac8f 100644
@@ -8352,3 +8352,108 @@ class TestThreadBlobResolution:
     def test_no_topdir_still_answers(self) -> None:
         assert review_tracking.resolve_thread_blob(None, {'thread-blob': 'x'}) == 'x'
         assert review_tracking.resolve_thread_blob(None, {}) == ''
+
+
+class TestGetRevisionsWithTracked:
+    def test_the_tracked_revision_is_always_present(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """Manually linking a newer version used to record only that one.
+
+        Tracking a series now catalogues the revision it tracks, so the
+        entry is a real row rather than one synthesized on read -- which is
+        also what gives its read state somewhere to live.
+        """
+        conn = review_tracking.init_db('with-tracked')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='[PATCH v2] thing',
+            sender_name='n',
+            sender_email='e@x',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        review_tracking.add_revision(conn, 'cid', 3, 'v3@x')
+        conn.commit()
+        revs = review_tracking.get_revisions_with_tracked(conn, 'cid')
+        conn.close()
+        assert [r['revision'] for r in revs] == [2, 3]
+        tracked = revs[0]
+        assert tracked['message_id'] == 'v2@x'
+
+    def test_two_live_series_rows_both_resolve(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        """rescan_branches can leave a change_id with two live rows.
+
+        The tracking list renders a row per live series row, and every
+        gate that offers the range-diff counts the same way, so both
+        revisions have to be resolvable here -- picking one would enable
+        an action on a version this function cannot find a message-id for.
+        """
+        conn = review_tracking.init_db('tracked-ambiguous')
+        for rev in (2, 5):
+            conn.execute(
+                'INSERT INTO series (change_id, revision, message_id, subject,'
+                " sender_name, sender_email, status) VALUES (?,?,?,?,?,?,'new')",
+                ('cid', rev, f'v{rev}@x', f'subj v{rev}', 'A', 'a@x'),
+            )
+        conn.commit()
+        revs = review_tracking.get_revisions_with_tracked(conn, 'cid')
+        conn.close()
+        assert [r['revision'] for r in revs] == [2, 5]
+        assert [r['message_id'] for r in revs] == ['v2@x', 'v5@x']
+
+    def test_present_tracked_revision_is_left_alone(
+        self, tmp_path: pytest.TempPathFactory
+    ) -> None:
+        conn = review_tracking.init_db('with-tracked-noop')
+        review_tracking.add_series_to_db(
+            conn,
+            change_id='cid',
+            revision=2,
+            subject='[PATCH v2] thing',
+            sender_name='S',
+            sender_email='[email protected]',
+            sent_at='2026-01-01T00:00:00+00:00',
+            message_id='v2@x',
+            num_patches=1,
+        )
+        review_tracking.add_revision(conn, 'cid', 2, 'v2@x')
+        conn.commit()
+        revs = review_tracking.get_revisions_with_tracked(conn, 'cid')
+        conn.close()
+        assert [r['revision'] for r in revs] == [2]
+        assert revs[0]['source'] == 'heuristic'
+
+
+class TestMergeTrackedRevisionsHelper:
+    """One merge rule for the DB resolver and the TUI's version rows."""
+
+    def test_every_series_row_resolves(self) -> None:
+        revs = [
+            {
+                'change_id': 'cid',
+                'revision': 2,
+                'message_id': 'v2@x',
+                'message_count': 4,
+            }
+        ]
+        rows = [
+            {'revision': 3, 'message_id': 'v3@x', 'subject': 's3'},
+            {'revision': 2, 'message_id': 'v2@x', 'subject': 's2'},
+            {'revision': 1, 'message_id': ''},
+        ]
+        merged = review_tracking.merge_tracked_revisions('cid', revs, rows)
+        assert [r['revision'] for r in merged] == [2, 3]
+        # The catalog row wins over a synthesized twin.
+        assert merged[0]['message_count'] == 4
+        synth = merged[1]
+        assert synth['source'] == 'tracked'
+        assert synth['message_id'] == 'v3@x'
+        # No read state: the entry supplies a message-id, not a badge.
+        assert synth['message_count'] is None
+        assert synth['seen_message_count'] is None
src/tests/test_tui_review.py +273 -1

289 lines not on this page · raw message

Signature · 1 line
2.53.0
#17 lore raw

RFC PATCH v2 17/25 review: skip the catalog mirror when nothing moved

In reply to Christian Brauner

sync_revisions_catalog_to_branch() is a no-op in the steady state, and the update sweep lands there every pass for every series, so answering "already current" should cost nothing.

Two things drive that. The sweep only mirrors the catalog as part of a branch save for four statuses, so every other status never mirrored at all, even though those series still hold per-patch message-ids that cannot be re-derived from the list; mirror them here instead of never. Answering then has to stop costing a rev-parse plus a tracking-commit read per series per pass.

changes.catalog_synced remembers "<branch-sha>:<catalog-sha1>" from the last verified mirror. While both halves still match, the branch reads are skipped outright; rescan_branches() refreshes branch_sha at the start of every sweep, and a pulled or rewritten branch changes it. Any catalog write or branch move breaks the pair and falls through to the full compare-and-save.

The pair is a cache key. A mismatch costs one extra tracking-commit read, never a wrong answer.

---
 src/b4/review/_review.py     | 40 +++++++++++++++++-
 src/b4/review/tracking.py    | 97 ++++++++++++++++++++++++++++++++++++--------
 src/tests/test_review.py     | 19 +++++----
 src/tests/test_tui_modals.py |  1 +
 4 files changed, 131 insertions(+), 26 deletions(-)
src/b4/review/_review.py +39 -1
index 652f21a5..68b5a7a0 100644
@@ -2452,9 +2452,18 @@ def update_series_tracking(
     identifier: str,
     linkmask: str,
     topdir: Optional[str] = None,
+    review_branches: Optional[Set[str]] = None,
 ) -> Dict[str, Any]:
     """Fetch thread, discover revisions, update trailers for one series.
 
+    *review_branches*, when given, is every ``b4/review/*`` branch that
+    exists, as :func:`b4.review.tracking.rescan_branches` enumerated it at
+    the top of this sweep.  It answers "has this change_id a branch at
+    all?" without a subprocess, which the catalog mirror below would
+    otherwise ask git once per series and then have answered "no" for
+    every series that has never been checked out.  None means the caller
+    does not know, and the mirror falls back to asking.
+
     Returns {'new_revisions': int, 'new_trailers': int,
              'error': Optional[str]}.
     """
@@ -2581,6 +2590,11 @@ def update_series_tracking(
     # have already happened; the tracking commit catches up on the next
     # sweep that finds the worktree free.
     branch = f'b4/review/{change_id}'
+    # Whether there is a branch to write to at all, from the enumeration the
+    # sweep already did.  Believing a stale "yes" costs one sync that
+    # declines; a stale "no" defers the mirror by one sweep, and nothing
+    # creates a review branch while a sweep is running.
+    has_review_branch = review_branches is None or branch in review_branches
     # Asked only for the statuses whose branch this would write, and only
     # to *report* the skip -- save_tracking_ref declines on its own, so
     # nothing below depends on getting this right.  Every other status
@@ -2671,6 +2685,21 @@ def update_series_tracking(
             result['error'] = 'Error saving tracking data'
             return result
 
+    elif topdir and has_review_branch:
+        # The block above mirrors the catalog as part of its save, but it
+        # only runs for four statuses.  Every other one still holds
+        # per-patch message-ids that cannot be re-derived from the list, so
+        # mirror them here rather than never.  Cheap on the every-sweep
+        # steady state: the sync's catalog_synced watermark answers
+        # "already current" without touching git -- but only for a series
+        # that has a branch.  Without one there is no watermark to match
+        # and nothing to mirror onto, so the sync opens the database and
+        # spends a rev-parse every sweep only to decline.  A 'new' series
+        # is exactly that case, and a tracking list is mostly those.
+        b4.review.tracking.sync_revisions_catalog_to_branch(
+            topdir, identifier, change_id
+        )
+
     # Auto-mark the maintainer's own messages as read.  Two passes:
     # replies sent through b4 were already flagged Seen at send time and
     # match here by message-id; anything whose From exactly matches the
@@ -2795,10 +2824,15 @@ def update_all_tracking(
     with b4.lockfile_nb(_get_update_lock_path(identifier)):
         # Rescan local review branches first so the DB reflects current
         # on-disk state before the network update runs.
+        # The review branches that exist, enumerated once here rather than
+        # asked per series below.  Left None when the rescan could not run,
+        # which is the "do not know" the per-series check falls back on.
+        review_branches: Optional[Set[str]] = None
         if topdir:
             try:
                 rescan = b4.review.tracking.rescan_branches(identifier, topdir)
                 result['gone'] = rescan.get('gone', 0)
+                review_branches = rescan.get('branches')
             except Exception as ex:
                 logger.warning('Pre-update rescan failed: %s', ex)
 
@@ -2823,7 +2857,11 @@ def update_all_tracking(
                 # Called via the package attribute: it is the established
                 # patch seam for tests and TUI callers alike
                 r = b4.review.update_series_tracking(
-                    series, identifier, linkmask, topdir=topdir
+                    series,
+                    identifier,
+                    linkmask,
+                    topdir=topdir,
+                    review_branches=review_branches,
                 )
             except liblore.OperationCancelledError:
                 result['cancelled'] = True
src/b4/review/tracking.py +81 -16

149 lines not on this page · raw message

src/tests/test_review.py +10 -9
index a7c9cb15..f3adcb5a 100644
@@ -4503,6 +4503,7 @@ def test_update_all_tracking_skips_snoozed_and_archived(
         identifier: str,
         linkmask: str,
         topdir: Optional[str] = None,
+        **kw: Any,
     ) -> Dict[str, Any]:
         updated.append(one['change_id'])
         if one['change_id'] == 'd':
@@ -4878,7 +4879,7 @@ def test_update_all_tracking_polls_revisions_capped(
     monkeypatch.setattr(
         review,
         'update_series_tracking',
-        lambda one, identifier, linkmask, topdir=None: {
+        lambda one, identifier, linkmask, topdir=None, **kw: {
             'new_revisions': 0,
             'new_trailers': 0,
             'error': None,
@@ -4942,7 +4943,7 @@ def test_update_all_tracking_reports_revision_poll_errors(
     monkeypatch.setattr(
         review,
         'update_series_tracking',
-        lambda one, identifier, linkmask, topdir=None: {
+        lambda one, identifier, linkmask, topdir=None, **kw: {
             'new_revisions': 0,
             'new_trailers': 0,
             'error': None,
@@ -4974,7 +4975,7 @@ def test_update_all_tracking_feeds_poll_progress(
     monkeypatch.setattr(
         review,
         'update_series_tracking',
-        lambda one, identifier, linkmask, topdir=None: {
+        lambda one, identifier, linkmask, topdir=None, **kw: {
             'new_revisions': 0,
             'new_trailers': 0,
             'error': None,
@@ -5077,7 +5078,7 @@ def test_update_all_tracking_cancelled_poller_stops_sweep(
     monkeypatch.setattr(
         review,
         'update_series_tracking',
-        lambda one, identifier, linkmask, topdir=None: {
+        lambda one, identifier, linkmask, topdir=None, **kw: {
             'new_revisions': 0,
             'new_trailers': 0,
             'error': None,
@@ -5101,7 +5102,7 @@ def _stub_sweep(monkeypatch: pytest.MonkeyPatch, series: List[Dict[str, Any]]) -
     monkeypatch.setattr(
         review,
         'update_series_tracking',
-        lambda one, identifier, linkmask, topdir=None: {
+        lambda one, identifier, linkmask, topdir=None, **kw: {
             'new_revisions': 0,
             'new_trailers': 0,
             'error': None,
@@ -5129,7 +5130,7 @@ def test_a_busy_branch_still_polls_its_revisions(
     monkeypatch.setattr(
         review,
         'update_series_tracking',
-        lambda one, identifier, linkmask, topdir=None: {
+        lambda one, identifier, linkmask, topdir=None, **kw: {
             'new_revisions': 0,
             'new_trailers': 0,
             'error': None,
@@ -5167,7 +5168,7 @@ def test_update_all_tracking_forwards_the_forced_poll(
     monkeypatch.setattr(
         review,
         'update_series_tracking',
-        lambda one, identifier, linkmask, topdir=None: {
+        lambda one, identifier, linkmask, topdir=None, **kw: {
             'new_revisions': 0,
             'new_trailers': 0,
             'error': None,
@@ -5416,7 +5417,7 @@ class TestCancelledPollKeepsItsTally:
         monkeypatch.setattr(
             review,
             'update_series_tracking',
-            lambda one, identifier, linkmask, topdir=None: {
+            lambda one, identifier, linkmask, topdir=None, **kw: {
                 'new_revisions': 0,
                 'new_trailers': 0,
                 'error': None,
@@ -5500,7 +5501,7 @@ class TestExplicitUpdateReachesASnoozedSeries:
         monkeypatch.setattr(
             review,
             'update_series_tracking',
-            lambda one, ident, linkmask, topdir=None: {
+            lambda one, ident, linkmask, topdir=None, **kw: {
                 'new_revisions': 0,
                 'new_trailers': 0,
                 'error': None,
src/tests/test_tui_modals.py +1 -0
index 5a19cdd4..46b4d8b7 100644
@@ -1132,6 +1132,7 @@ class TestUpdateAllScreenCancellation:
             identifier: str,
             linkmask: str,
             topdir: Optional[str] = None,
+            **kw: Any,
         ) -> Dict[str, Any]:
             nonlocal call_count
             call_count += 1
Signature · 1 line
2.53.0
#18 lore raw

RFC PATCH v2 18/25 review: match a stray posting by message-id

In reply to Christian Brauner

Three places ask whether another series already owns a posting: [l]'s confirmation preview, the absorb it then performs, and the conflicts [o] reports. They disagreed, and the preview warned about the safe cases while staying silent on the destructive one.

Give them one rule. find_stray_revision() matches by message-id first and fingerprint second. A fingerprint hashes only the patches present, so a revision recorded from a partial fetch never matches the one computed with the whole series in hand.

Both lookups exclude the target change_id in SQL and walk every remaining row rather than testing one. A posting can sit in the catalog under the link target as well as under the stray, since auto-discovery records it and the maintainer then links it, so taking the first row back would answer with the target itself whenever it sorts first. [l] would then duplicate the series instead of absorbing it.

An all-archived owner is not a match at all. It is invisible in the tracking list, so absorbing it deletes a series the maintainer cannot see and reporting it sends them after one they cannot reach. The same walk keeps such an owner from hiding a live one behind it.

Act on the absorb result rather than assuming it. Absorb still declines a revision with neither a series nor a catalog row, and that revision would otherwise go unrecorded while the TUI reported both a link and an absorbed duplicate.

---
 src/b4/review/tracking.py          | 111 +++++++++++++++++++++++++++++++------
 src/b4/review_tui/_tracking_app.py |  10 +++-
 2 files changed, 102 insertions(+), 19 deletions(-)
src/b4/review/tracking.py +95 -16
index 958b5180..6662cd9e 100644
@@ -1804,6 +1804,32 @@ def get_revisions_with_tracked(
     return merge_tracked_revisions(change_id, get_revisions(conn, change_id), rows)
 
 
+def _find_revisions_by(
+    conn: sqlite3.Connection,
+    column: str,
+    value: Optional[str],
+    exclude_change_id: Optional[str] = None,
+) -> List[dict[str, Any]]:
+    """Every catalog row whose *column* equals *value*, ordered by change_id.
+
+    Plural on purpose: nothing constrains a message-id or a fingerprint to
+    one change_id, so a caller looking for *another* series' copy has to be
+    able to walk past the first row.  Ordered, or the answer is rowid order
+    and flips the first time a row is rewritten.
+
+    *column* is a literal supplied by this module, never caller input.
+    """
+    if not value:
+        return []
+    sql = _REVISION_SELECT + f' WHERE r.{column} = ?'
+    params: List[Any] = [value]
+    if exclude_change_id is not None:
+        sql += ' AND r.change_id != ?'
+        params.append(exclude_change_id)
+    sql += ' ORDER BY r.change_id'
+    return [dict(zip(_REVISION_COLS, row)) for row in conn.execute(sql, params)]
+
+
 def find_revision_by_fingerprint(
     conn: sqlite3.Connection, fingerprint: Optional[str]
 ) -> Optional[dict[str, Any]]:
@@ -1813,15 +1839,43 @@ def find_revision_by_fingerprint(
     under a different change_id) so it can be absorbed rather than duplicated.
     An empty or None fingerprint never matches.
     """
-    if not fingerprint:
-        return None
-    row = conn.execute(
-        _REVISION_SELECT + ' WHERE r.fingerprint = ? ORDER BY r.change_id LIMIT 1',
-        (fingerprint,),
-    ).fetchone()
-    if row is None:
-        return None
-    return dict(zip(_REVISION_COLS, row))
+    rows = _find_revisions_by(conn, 'fingerprint', fingerprint)
+    return rows[0] if rows else None
+
+
+def find_stray_revision(
+    conn: sqlite3.Connection,
+    change_id: str,
+    message_id: Optional[str],
+    fingerprint: Optional[str],
+) -> Optional[dict[str, Any]]:
+    """Return the revision another series already owns this posting under.
+
+    The single rule behind [l]'s confirmation preview, the absorb it then
+    performs, and the conflicts [o] reports -- they disagreed once and the
+    preview warned about the safe cases while staying silent on the
+    destructive one.
+
+    Message-id first, fingerprint second: a fingerprint hashes only the
+    patches present, so a revision recorded from a partial fetch does not
+    match the one computed with the whole series in hand.  An all-archived
+    owner is not a match at all -- it is invisible in the tracking list, so
+    absorbing it deletes a series the maintainer cannot see and reporting
+    it sends them after one they cannot reach.
+
+    Both lookups exclude *change_id* in SQL and walk every remaining row
+    rather than testing one.  A posting can sit in the catalog under the
+    link target as well as under the stray -- auto-discovery records it,
+    then the maintainer links it -- and taking the first row back would
+    answer with the target itself whenever it sorts first, reporting no
+    stray and letting [l] duplicate the series instead of absorbing it.
+    The same walk keeps an archived owner from hiding a live one behind it.
+    """
+    for column, value in (('message_id', message_id), ('fingerprint', fingerprint)):
+        for stray in _find_revisions_by(conn, column, value, change_id):
+            if not _is_archived_only(conn, str(stray['change_id'])):
+                return stray
+    return None
 
 
 def find_existing_change_id(
@@ -2251,8 +2305,10 @@ def record_linked_revision(
       returns ``status='collision'`` without mutating anything, so the caller
       can confirm before overwriting.
     - If the posting is already tracked as its own stray series (matched by
-      fingerprint under a different change_id), that series is absorbed
-      (``absorbed=True``) rather than duplicated.
+      message-id, then fingerprint, under a different change_id), that series
+      is absorbed (``absorbed=True``) rather than duplicated.  A stray whose
+      series rows are all archived is left alone and the revision is simply
+      recorded.
     - Otherwise the revision and its patches are recorded with
       ``source='manual'``.
 
@@ -2283,17 +2339,20 @@ def record_linked_revision(
         return result
 
     fingerprint = lser.fingerprint
-    stray = find_revision_by_fingerprint(conn, fingerprint)
-    if stray is not None and stray['change_id'] != change_id:
-        absorb_series_as_revision(
+    stray = find_stray_revision(conn, change_id, ref_msg.msgid, fingerprint)
+    if stray is not None:
+        # Acted on, not assumed: absorb still declines a revision with
+        # neither a series nor a catalog row, and the revision the
+        # maintainer asked to link would then go unrecorded while the TUI
+        # reported a link and an absorbed duplicate.
+        result['absorbed'] = absorb_series_as_revision(
             conn,
             change_id,
             stray['change_id'],
             revision,
             stray_revision=stray.get('revision'),
         )
-        result['absorbed'] = True
-    else:
+    if not result['absorbed']:
         message_id = ref_msg.msgid
         add_revision(
             conn,
@@ -4162,6 +4221,26 @@ def update_revision_message_counts(
     }
 
 
+def _is_archived_only(conn: sqlite3.Connection, change_id: str) -> bool:
+    """Whether *change_id* has series rows and every one of them is archived.
+
+    The v11 migration gives every series row a catalog entry, archived ones
+    included, so a catalog hit under another change_id no longer proves
+    anything is still tracked there.  A change_id with no series row at all
+    is a different matter -- that is a catalogued posting, and colliding
+    with it still matters -- so only the all-archived case is exempt.
+    """
+    row = conn.execute(
+        'SELECT COUNT(*),'
+        " SUM(COALESCE(status, 'new') != 'archived') FROM series"
+        ' WHERE change_id = ?',
+        (change_id,),
+    ).fetchone()
+    if row is None or not row[0]:
+        return False
+    return not (row[1] or 0)
+
+
 def mark_all_messages_seen(
     conn: sqlite3.Connection, change_id: str, revision: int
 ) -> None:
src/b4/review_tui/_tracking_app.py +7 -3
index bcad86f3..f0ad512a 100644
@@ -4006,8 +4006,12 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
             known = {
                 r['revision'] for r in b4.review.tracking.get_revisions(conn, change_id)
             }
-            stray = b4.review.tracking.find_revision_by_fingerprint(
-                conn, lser.fingerprint
+            ref_msg = b4.review.tracking._series_ref_message(lser)
+            stray = b4.review.tracking.find_stray_revision(
+                conn,
+                change_id,
+                ref_msg.msgid if ref_msg is not None else None,
+                lser.fingerprint,
             )
             conn.close()
         except Exception as ex:
@@ -4019,7 +4023,7 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
         warning = ''
         if collision:
             warning = f'v{revision} is already tracked — linking replaces it.'
-        elif stray is not None and stray['change_id'] != change_id:
+        elif stray is not None:
             warning = 'Already tracked as a separate series — it will be absorbed.'
 
         num_patches = sum(1 for p in lser.patches[1:] if p is not None)
Signature · 1 line
2.53.0
#19 lore raw

RFC PATCH v2 19/25 review: add backward discovery of older series revisions

In reply to Christian Brauner

Auto-discovery only looks forward, so versions posted before a series was tracked never enter the revisions catalog unless they shared the seed thread.

Add discover_older_revisions(). It fetches the tracked thread and runs the same get_extra_series() machinery b4 am/mbox uses to pull other revisions, with an explicit wantvers covering every previous version, since the backward search otherwise fetches only latest-1. Newly recorded revisions are polled immediately so they arrive with counts and cached thread blobs.

The update sweep runs the same backward search once per series, latched in a dedicated back_searched column. Neither the catalog nor revision provenance can record that a search ran and found nothing: the v11 backfill gives every series row a catalog entry, and offline tracking and manual linking both stamp a source with no search behind them.

---
 src/b4/review/_review.py  |  45 +++++---
 src/b4/review/tracking.py | 263 +++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 293 insertions(+), 15 deletions(-)
src/b4/review/_review.py +33 -12
index 68b5a7a0..2ed7c340 100644
@@ -2497,22 +2497,38 @@ def update_series_tracking(
     if b4.can_network:
         try:
             _conn = b4.review.tracking.get_db(identifier)
-            _known = set(
-                r['revision']
-                for r in b4.review.tracking.get_revisions(_conn, change_id)
-            )
-            _conn.close()
+            try:
+                _rows = b4.review.tracking.get_revisions(_conn, change_id)
+                _searched = b4.review.tracking.is_back_searched(_conn, change_id)
+            finally:
+                _conn.close()
         except Exception:
-            _known = set()
+            _rows = []
+            _searched = False
+        _known = {r['revision'] for r in _rows}
 
         msgs = b4.mbox.get_extra_series(msgs, direction=1, nocache=True)
-        # Discount the tracked revision's own entry.  The v11 backfill gives
-        # every series row one, so a plain "is the catalog empty?" test is
-        # never true again and this one-shot search stopped running at all.
-        if current_rev > 1 and not (_known - {current_rev}):
+        # One-shot, latched on changes.back_searched.  The catalog alone
+        # cannot carry the latch: the v11 backfill gives every series row
+        # an entry, so "is the catalog empty?" is never true again, and
+        # discounting just the tracked revision re-ran this uncached
+        # subject+sender search on every sweep, forever, for any series
+        # whose older versions cannot be found.  Revision provenance
+        # cannot carry it either: offline tracking and manual linking
+        # both stamp a source with no search behind it, and a manual
+        # stamp can never be overwritten to record a later real search.
+        if current_rev > 1 and not _searched and not (_known - {current_rev}):
             msgs = b4.mbox.get_extra_series(
                 msgs, direction=-1, wantvers=list(range(1, current_rev)), nocache=True
             )
+            try:
+                _conn = b4.review.tracking.get_db(identifier)
+                try:
+                    b4.review.tracking.set_back_searched(_conn, change_id)
+                finally:
+                    _conn.close()
+            except Exception as ex:
+                logger.debug('Could not latch the backward search: %s', ex)
 
     lmbx = b4.LoreMailbox()
     for msg in msgs:
@@ -2562,7 +2578,13 @@ def update_series_tracking(
     try:
         conn = b4.review.tracking.get_db(identifier)
         new_revs = b4.review.tracking._record_discovered_revisions(
-            conn, change_id, lmbx, str(linkmask)
+            conn,
+            change_id,
+            lmbx,
+            str(linkmask),
+            # Offline the lmbx is just the cached thread with no search
+            # behind it; 'heuristic' keeps that provenance honest.
+            source='discovered' if b4.can_network else 'heuristic',
         )
         result['new_revisions'] = len(new_revs)
         try:
@@ -2684,7 +2706,6 @@ def update_series_tracking(
         if not save_tracking_ref(topdir, branch, cover_text, tracking):
             result['error'] = 'Error saving tracking data'
             return result
-
     elif topdir and has_review_branch:
         # The block above mirrors the catalog as part of its save, but it
         # only runs for four statuses.  Every other one still holds
src/b4/review/tracking.py +260 -3

327 lines not on this page · raw message

Signature · 1 line
2.53.0
#20 lore raw

RFC PATCH v2 20/25 review-tui: add a "Find older revisions" action

In reply to Christian Brauner

Offer discover_older_revisions() from the tracker's action menu, wherever manual revision linking is offered. The search runs in a lore worker; on success the list reloads, deferring to the DB mtime poll when a modal is up.

The documentation also gains the "Link a revision" line the partial block never listed, although that action has been offered for partial series all along.

---
 docs/maintainer/review.rst         |  9 ++++
 src/b4/review_tui/_tracking_app.py | 96 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
docs/maintainer/review.rst +9 -0
index ca063269..5ddd9dd2 100644
@@ -252,6 +252,8 @@ actions depend on the series status:
 * ``[s]`` **Snooze** — defer until a date, duration, or git tag
 * ``[U]`` **Upgrade** — switch to a newer revision (when available)
 * ``[l]`` **Link a revision** — manually associate a revision by message-id
+* ``[o]`` **Find older revisions** — search lore for versions posted before
+  the series was tracked
 * ``[A]`` **Abandon** / ``[x]`` **Archive**
 
 **Partial** (some patches applied, remainder still in review):
@@ -262,6 +264,9 @@ actions depend on the series status:
 * ``[w]`` **Mark as waiting** — waiting on a new revision
 * ``[s]`` **Snooze** — defer until later
 * ``[U]`` **Upgrade** — switch to a newer revision (when available)
+* ``[l]`` **Link a revision** — manually associate a revision by message-id
+* ``[o]`` **Find older revisions** — search lore for versions posted before
+  the series was tracked
 * ``[A]`` **Abandon** / ``[x]`` **Archive**
 
 **New / gone:**
@@ -270,6 +275,8 @@ actions depend on the series status:
 * ``[U]`` **Upgrade** — switch to a newer revision (new only, when available)
 * ``[s]`` **Snooze** — defer until later (new only)
 * ``[l]`` **Link a revision** — manually associate a revision by message-id (new only)
+* ``[o]`` **Find older revisions** — search lore for versions posted before
+  the series was tracked (new only)
 * ``[A]`` **Abandon**
 
 **Waiting:**
@@ -277,6 +284,8 @@ actions depend on the series status:
 * ``[U]`` **Upgrade** — switch to the newer revision (when available)
 * ``[r]`` **Review** — return to reviewing
 * ``[l]`` **Link a revision** — manually associate a revision by message-id
+* ``[o]`` **Find older revisions** — search lore for versions posted before
+  the series was tracked
 * ``[A]`` **Abandon** / ``[x]`` **Archive**
 
 **Snoozed:**
src/b4/review_tui/_tracking_app.py +96 -0

156 lines not on this page · raw message

Signature · 1 line
2.53.0
#21 lore raw

RFC PATCH v2 21/25 review: test the catalog mirror, stray matching and backward discovery

In reply to Christian Brauner

Cover the catalog-sync watermark answering "already current" without touching git, and a catalog write breaking it. Cover stray matching by message-id, a fingerprint that drifted, a catalog-only stray, and an all-archived owner left alone. Cover discover_older_revisions(): every previous version recorded with an explicit wantvers, revisions dated from their own posting, the one-shot latch, offline, the v1 no-op, conflicts reported rather than absorbed, and the budget the follow-up poll runs inside.

Also the branch sha recorded once per change_id, the force flag bypassing the minimum-age skip, and the catalog thread snapshot advancing while the tracking ref is frozen.

---
 src/tests/test_review.py          |  133 +++
 src/tests/test_review_tracking.py | 1612 +++++++++++++++++++++++++++++++++++++
 src/tests/test_tui_tracking.py    |   47 ++
 3 files changed, 1792 insertions(+)
src/tests/test_review.py +133 -0
index f3adcb5a..a40b9af6 100644
@@ -5544,3 +5544,136 @@ class TestExplicitUpdateReachesASnoozedSeries:
         the cron sweep's lore budget.
         """
         assert self._run('snooze-sweep', monkeypatch, forced=False) == []
+
+
+class TestCatalogMirrorSkipsABranchlessSeries:
+    """The sweep enumerates the review branches once; asking again is waste.
+
+    Every status outside BRANCH_UPDATE_STATUSES falls through to the
+    mirror below the branch save, and a series that has never been checked
+    out has nothing to mirror onto -- but the sync only learns that by
+    opening the database and spending a rev-parse, once per series, every
+    sweep.  A tracking list is mostly 'new' series.
+    """
+
+    @staticmethod
+    def _run(
+        monkeypatch: pytest.MonkeyPatch, identifier: str, **kwargs: Any
+    ) -> List[str]:
+        change_id = f'{identifier}-cid'
+        conn = b4.review.tracking.init_db(identifier)
+        b4.review.tracking.add_series_to_db(
+            conn,
+            change_id,
+            1,
+            'Subject',
+            'Author',
+            '[email protected]',
+            '2024-01-15T10:00:00+00:00',
+            '[email protected]',
+            2,
+        )
+        conn.close()
+        synced: List[str] = []
+        monkeypatch.setattr(
+            b4.review.tracking,
+            'sync_revisions_catalog_to_branch',
+            lambda topdir, ident, cid: synced.append(cid),
+        )
+        monkeypatch.setattr(b4, 'git_worktree_busy', lambda topdir, branch: False)
+        monkeypatch.setattr(
+            b4.review.tracking, 'store_revision_thread_blob', lambda *a, **kw: None
+        )
+        monkeypatch.setattr(
+            b4.review.tracking, '_store_thread_blob', lambda *a, **kw: None
+        )
+
+        msg = email.message.EmailMessage()
+        msg['Message-Id'] = f'<{change_id}[email protected]>'
+        msg['Date'] = 'Mon, 27 Jul 2026 10:00:00 +0000'
+        mock_lmbx = mock.Mock()
+        mock_lmbx.series = {}
+        mock_lmbx.covers = {}
+        mock_lmbx.get_series.return_value = None
+        series_dict: Dict[str, Any] = {
+            'change_id': change_id,
+            'revision': 1,
+            'status': 'new',
+            'message_id': '[email protected]',
+        }
+        with (
+            mock.patch(
+                'b4.review._review.retrieve_series_messages', return_value=[msg]
+            ),
+            mock.patch('b4.LoreMailbox', return_value=mock_lmbx),
+        ):
+            review.update_series_tracking(
+                series_dict,
+                identifier,
+                'https://example.com/%s',
+                topdir='/nonexistent',
+                **kwargs,
+            )
+        return synced
+
+    def test_a_branchless_series_is_not_mirrored(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        assert self._run(monkeypatch, 'mirror-none', review_branches=set()) == []
+
+    def test_a_series_with_a_branch_still_is(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        assert self._run(
+            monkeypatch,
+            'mirror-some',
+            review_branches={'b4/review/mirror-some-cid'},
+        ) == ['mirror-some-cid']
+
+    def test_not_knowing_falls_back_to_asking(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A rescan that could not run must not mute the mirror."""
+        assert self._run(monkeypatch, 'mirror-unknown') == ['mirror-unknown-cid']
+
+
+def test_update_all_tracking_forwards_the_branch_set(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """One enumeration at the top of the sweep, not one git call per series."""
+    seen: List[Any] = []
+    monkeypatch.setattr(
+        b4.review.tracking,
+        'rescan_branches',
+        lambda identifier, topdir: {
+            'gone': 0,
+            'changed': 0,
+            'branches': {'b4/review/a'},
+        },
+    )
+    monkeypatch.setattr(
+        b4.review.tracking,
+        'get_all_tracked_series',
+        lambda identifier: [
+            {'change_id': 'a', 'subject': 's', 'status': 'new', 'sender_name': 'A'}
+        ],
+    )
+
+    def _fake(
+        one: Dict[str, Any],
+        identifier: str,
+        linkmask: str,
+        topdir: Optional[str] = None,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        seen.append(kw.get('review_branches'))
+        return {'new_revisions': 0, 'new_trailers': 0, 'error': None}
+
+    monkeypatch.setattr(review, 'update_series_tracking', _fake)
+    monkeypatch.setattr(
+        b4.review.tracking, 'update_revision_message_counts', lambda *a, **kw: {}
+    )
+    review.update_all_tracking(
+        'fwd-branches', 'https://lore.example/r/%s', topdir='/nonexistent'
+    )
+    assert seen == [{'b4/review/a'}]
src/tests/test_review_tracking.py +1612 -0

1,651 lines not on this page · raw message

src/tests/test_tui_tracking.py +47 -0

50 lines not on this page · raw message

Signature · 1 line
2.53.0
#22 lore raw

RFC PATCH v2 22/25 review-tui: extract the Msgs column renderer from TrackedSeriesItem

In reply to Christian Brauner

The tracker list computes the Msgs column, a thread total plus an unseen badge, inline in TrackedSeriesItem.compose(). Per-version child rows need the same column, so pull the computation out into _msgs_fields() and the styled append into _append_msgs().

No functional change.

---
 src/b4/review_tui/_tracking_app.py | 107 +++++++++++++++++++++++--------------
 1 file changed, 66 insertions(+), 41 deletions(-)
src/b4/review_tui/_tracking_app.py +66 -41
index 999513ca..53466498 100644
@@ -726,6 +726,66 @@ def _format_attestation(att: str, app: Any = None) -> Optional[RichText]:
     return text
 
 
+def _unseen_delta(
+    message_count: Optional[int], seen_message_count: Optional[int]
+) -> int:
+    """Unseen messages in a thread, for every renderer of that number.
+
+    An absent seen count means nothing is known to have been read yet --
+    but the counts are written in pairs, so in practice that only happens
+    on rows migrated in from a database predating them.  Treat it as
+    "nothing unseen" rather than "everything unseen": two renderers
+    disagreeing about a missing value is worse than either answer.
+    """
+    if message_count is None or seen_message_count is None:
+        return 0
+    return max(0, message_count - seen_message_count)
+
+
+def _msgs_fields(
+    message_count: Optional[int], seen_message_count: Optional[int]
+) -> Tuple[str, str, bool]:
+    """Render the Msgs column for a (total, seen) message count pair.
+
+    Returns (base, badge, base_accent): "1" (all seen), "6" accented (all
+    new), "6" + "(3)" (mixed).  A never-fetched thread has no count and
+    renders as "-".  The badge is accented whenever it is non-empty.
+    """
+    if message_count is None:
+        return '-', '', False
+    if message_count == 0:
+        return '0', '', False
+    delta = _unseen_delta(message_count, seen_message_count)
+    if delta == message_count:
+        # All follow-ups are new
+        return str(message_count), '', True
+    if delta > 0:
+        # Mixed: total + (unseen)
+        return str(message_count), f'({delta})', False
+    # All seen
+    return str(message_count), '', False
+
+
+def _append_msgs(
+    label: RichText,
+    app: Any,
+    message_count: Optional[int],
+    seen_message_count: Optional[int],
+) -> None:
+    """Append the Msgs column (total + unseen badge) to *label*."""
+    base, badge, base_accent = _msgs_fields(message_count, seen_message_count)
+    base_style = ''
+    badge_style = ''
+    if base_accent or badge:
+        accent = f'bold {resolve_styles(app)["warning"]}'
+        if base_accent:
+            base_style = accent
+        if badge:
+            badge_style = accent
+    label.append(f'  {base.rjust(3)}', style=base_style)
+    label.append(f'{badge:<3s}', style=badge_style)
+
+
 class TrackedSeriesItem(ListItem):
     """A single tracked series entry in the listing."""
 
@@ -770,36 +830,6 @@ class TrackedSeriesItem(ListItem):
             art_str = f'{a}·{r}·{t}'
         else:
             art_str = '-'
-        fc = self.series.get('message_count')
-        sc = self.series.get('seen_message_count')
-        if fc is not None:
-            delta = (fc - sc) if (sc is not None and fc > sc) else 0
-        else:
-            delta = 0
-        # Msgs display: "1" (all seen), "6" accent (all new), "6(3)" mixed
-        if fc is None:
-            fu_base = '-'
-            fu_badge = ''
-            base_accent = False
-        elif fc == 0:
-            fu_base = '0'
-            fu_badge = ''
-            base_accent = False
-        elif delta == fc:
-            # All follow-ups are new
-            fu_base = str(fc)
-            fu_badge = ''
-            base_accent = True
-        elif delta > 0:
-            # Mixed: total + (unseen)
-            fu_base = str(fc)
-            fu_badge = f'({delta})'
-            base_accent = False
-        else:
-            # All seen
-            fu_base = str(fc)
-            fu_badge = ''
-            base_accent = False
         # Build compact prefix using LoreSubject to extract subsystem/modifier tokens
         ls = b4.LoreSubject(subject)
         extras = ls.get_extra_prefixes(exclude=['patch'])
@@ -822,17 +852,12 @@ class TrackedSeriesItem(ListItem):
             label.append(' ')
         label.append(' ')
         label.append(art_str.rjust(7))
-        base_style = ''
-        badge_style = ''
-        if base_accent or fu_badge:
-            ts = resolve_styles(self.app)
-            accent = f'bold {ts["warning"]}'
-            if base_accent:
-                base_style = accent
-            if fu_badge:
-                badge_style = accent
-        label.append(f'  {fu_base.rjust(3)}', style=base_style)
-        label.append(f'{fu_badge:<3s}', style=badge_style)
+        _append_msgs(
+            label,
+            self.app,
+            self.series.get('message_count'),
+            self.series.get('seen_message_count'),
+        )
         label.append(f'  {symbol}{flag}  {subject_display}')
         yield Label(label, markup=False)
 
Signature · 1 line
2.53.0
#23 lore raw

RFC PATCH v2 23/25 review-tui: give the unseen badge a column of its own

In reply to Christian Brauner

The Msgs column packs the thread total and the unseen badge into adjacent fields, so a two-digit total and a badge render as "15(3)" and read as a single number.

Put a separator between them and widen the badge to four columns, so a two-digit unseen count still fits, and move the header label over the field it now describes.

Assisted-by claude-opus-5
---
 src/b4/review_tui/_tracking_app.py | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)
src/b4/review_tui/_tracking_app.py +10 -3
index 53466498..37377758 100644
@@ -772,7 +772,13 @@ def _append_msgs(
     message_count: Optional[int],
     seen_message_count: Optional[int],
 ) -> None:
-    """Append the Msgs column (total + unseen badge) to *label*."""
+    """Append the Msgs column (total + unseen badge) to *label*.
+
+    Ten columns: two of lead-in, three for the total, a separator, four for
+    the badge.  The separator is what keeps a two-digit total and a badge
+    from reading as one number, and the badge is four wide so a two-digit
+    unseen count still fits inside the field.
+    """
     base, badge, base_accent = _msgs_fields(message_count, seen_message_count)
     base_style = ''
     badge_style = ''
@@ -783,7 +789,8 @@ def _append_msgs(
         if badge:
             badge_style = accent
     label.append(f'  {base.rjust(3)}', style=base_style)
-    label.append(f'{badge:<3s}', style=badge_style)
+    label.append(' ')
+    label.append(f'{badge:<4s}', style=badge_style)
 
 
 class TrackedSeriesItem(ListItem):
@@ -1432,7 +1439,7 @@ class TrackingApp(LoreNodeShutdownMixin, CheckRunnerMixin, App[Optional[str]]):
                 await self.mount(empty, before=self.query_one(Footer))
                 return
 
-            header_text = f'{"Submitter":<20s}{"A":>1s} {"A·R·T":>7s}  {"Msgs":>6s}  {"S":<4s}{"Subject"}'
+            header_text = f'{"Submitter":<20s}{"A":>1s} {"A·R·T":>7s}  {"Msgs":<8s}{"S":<6s}{"Subject"}'
             header = Static(header_text, id='tracking-header')
 
             list_items: List[ListItem] = [TrackedSeriesItem(s) for s in display_series]
Signature · 1 line
2.53.0
#24 lore raw

RFC PATCH v2 24/25 review-tui: expand tracked series into per-version rows

In reply to Christian Brauner

Series with more than one known version become expandable. 'x' unfolds indented child rows, one per catalog revision with the tracked one starred, showing per-version unread badges and activity dates; 'X' toggles every series at once. Enter or 'e' on a child opens that revision's thread with revision-correct seen syncing, 'd' range-diffs it against the tracked revision directly, and every other action keeps operating on the parent series. Expansion state and the (change_id, revision) cursor position survive the periodic DB-mtime reloads and limit filtering.

Focusing a series for the next rebuild goes through a helper that also clears the stashed version. The stash outlives a screen that closed without rebuilding the list, so a plain _focus_change_id assignment would drop the cursor onto a child row nobody selected, and it is that row the thread and range-diff actions read.

has_multiple_revisions loses its last reader here. It counts raw catalog rows, which miss a tracked revision the catalog never recorded. The bulk revision-count query goes with it: the remaining caller needs the grouped rows anyway, so counting them is a dict lookup rather than a second pass over the table.

---
 docs/maintainer/review.rst         |  40 ++
 src/b4/review/tracking.py          |   8 -
 src/b4/review_tui/_modals.py       |   7 +
 src/b4/review_tui/_tracking_app.py | 743 +++++++++++++++++++++++++++++++------
 src/tests/test_review_tracking.py  |  11 -
 src/tests/test_tui_tracking.py     |  27 +-
 6 files changed, 707 insertions(+), 129 deletions(-)
docs/maintainer/review.rst +40 -0
index 5ddd9dd2..8c04e7c1 100644
@@ -188,12 +188,17 @@ Key           Action
 ``e``         Thread — open the lite thread viewer (see below)
 ``a``         Action menu — context-sensitive actions (see below)
 ``d``         Range-diff between revisions
+``x``         Expand or collapse the per-version rows of a series marked
+              with ``▸`` (see :ref:`version_rows`)
 ``u``         Update — fetch latest trailers and check for newer
               revisions for the selected series; press ``Escape`` or
               ``q`` to cancel
 ``U``         Update all — same as ``u`` but for all tracked series
               (skipping snoozed); press ``Escape`` or ``q`` to cancel
               mid-run — series already updated are saved
+``X``         Expand or collapse the version rows of every multi-version
+              series in the current list at once (so a ``l`` limit scopes
+              it, in both directions)
 ``l``         Limit — filter the list of displayed series. Plain text
               matches subjects and submitters; ``s:<status>`` filters
               by status, ``t:<target-branch>`` by target branch, and
@@ -328,6 +333,41 @@ the tracking database and displayed without re-checking on subsequent
 views. The attestation check honours the :term:`b4.attestation-policy`
 and :term:`b4.attestation-staleness-days` configuration options.
 
+.. _version_rows:
+
+Version rows
+~~~~~~~~~~~~
+
+A series whose catalog holds more than one known version is marked with
+a ``▸`` before its subject. Press ``x`` to expand it into one child row
+per version (``X`` expands or collapses every such series at once). An
+asterisk marks the version the series currently tracks:
+
+.. code-block:: none
+
+   ▾ [PATCH v3,00/12] introduce the frobnicator
+     ├─ v1   12 Mar    4      introduce the frobnicator
+     ├─ v2   02 Apr    9 (3)  introduce the frobnicator
+     └─ v3*  28 Apr   15      introduce the frobnicator
+
+Each row carries that version's own message count and unread badge, so
+follow-up mail arriving on an older version's thread is still visible.
+On a version row, ``Enter`` or ``e`` opens that version's thread and
+``d`` range-diffs it against the tracked revision, skipping the revision
+picker. Every other key still acts on the parent series, except the four
+actions that drive the review branch: ``r`` (review), and **Take**,
+**Rebase** and **Upgrade** in the ``a`` action menu. That branch always
+holds the revision the series tracks, so on any other version's row ``r``
+is greyed out and the three menu entries are not offered.
+
+Update sweeps poll a few non-tracked versions of each series for new
+mail, least-recently-checked first, so a series with many versions
+fills in over successive sweeps and then keeps cycling through them —
+a late reply to an old version is noticed however many versions there
+are. Every version is browsable on demand regardless.
+
+.. versionadded:: v0.17
+
 Lite thread viewer
 ~~~~~~~~~~~~~~~~~~
 Pressing ``e`` on any series opens a mutt-style thread viewer that
src/b4/review/tracking.py +0 -8
index 843808c4..7f08258e 100644
@@ -2551,14 +2551,6 @@ def get_all_newest_revisions(conn: sqlite3.Connection) -> dict[str, int]:
     return {row[0]: int(row[1]) for row in cursor.fetchall()}
 
 
-def get_all_revision_counts(conn: sqlite3.Connection) -> dict[str, int]:
-    """Return {change_id: revision_count} for all change_ids."""
-    cursor = conn.execute(
-        'SELECT change_id, COUNT(*) FROM revisions GROUP BY change_id'
-    )
-    return {row[0]: int(row[1]) for row in cursor.fetchall()}
-
-
 def get_all_revisions_grouped(
     conn: sqlite3.Connection,
 ) -> dict[str, list[dict[str, Any]]]:
src/b4/review_tui/_modals.py +7 -0
index 23d5f566..8be61319 100644
@@ -328,9 +328,16 @@ TRACKING_HELP_LINES = [
     '  [bold]d[/bold]         Range-diff between revisions\n',
     '  [bold]a[/bold]         Open action menu (take, rebase, etc.)\n',
     '  [bold]u[/bold]         Update selected series\n',
+    '  [bold]x[/bold]         Expand/collapse the version rows of a ▸ series\n',
+    '\n',
+    '[bold]Version rows[/bold]\n',
+    '  v2*           Asterisk marks the revision the series tracks\n',
+    '  [bold]Enter[/bold] / [bold]e[/bold] View the thread of that version\n',
+    '  [bold]d[/bold]         Range-diff that version against the tracked one\n',
     '\n',
     '[bold]App[/bold]\n',
     '  [bold]U[/bold]         Update all tracked series\n',
+    '  [bold]X[/bold]         Expand/collapse all multi-version series\n',
     '  [bold]l[/bold]         Filter series by pattern\n',
     '  [bold]s[/bold]         Suspend to shell\n',
     '  [bold]p[/bold]         Switch to Patchwork TUI\n',
src/b4/review_tui/_tracking_app.py +639 -104

1,117 lines not on this page · raw message

src/tests/test_review_tracking.py +0 -11
index 532c65c9..03aa3407 100644
@@ -1068,17 +1068,6 @@ class TestRevisions:
         assert review_tracking.get_all_newest_revisions(conn) == {}
         conn.close()
 
-    def test_get_all_revision_counts(self, tmp_path: pytest.TempPathFactory) -> None:
-        """Verify bulk revision-count query returns correct counts."""
-        conn = review_tracking.init_db('rev-bulk-count-test')
-        review_tracking.add_revision(conn, 'change-a', 1, '[email protected]')
-        review_tracking.add_revision(conn, 'change-a', 2, '[email protected]')
-        review_tracking.add_revision(conn, 'change-a', 3, '[email protected]')
-        review_tracking.add_revision(conn, 'change-b', 1, '[email protected]')
-        result = review_tracking.get_all_revision_counts(conn)
-        assert result == {'change-a': 3, 'change-b': 1}
-        conn.close()
-
     def test_get_all_revisions_grouped(self, tmp_path: pytest.TempPathFactory) -> None:
         """Verify bulk grouped revisions returns correct per-change-id lists."""
         conn = review_tracking.init_db('rev-bulk-grouped-test')
src/tests/test_tui_tracking.py +21 -6
index d6233afe..7ba2443e 100644
@@ -4663,7 +4663,7 @@ class TestLoadSeriesCaching:
             await pilot.pause()
             assert app._cached_branch_tips is not None
             assert app._cached_newest_revisions is not None
-            assert app._cached_revision_counts is not None
+            assert app._cached_revisions is not None
 
     @pytest.mark.asyncio
     async def test_caches_survive_db_poll_no_change(
@@ -4697,14 +4697,26 @@ class TestLoadSeriesCaching:
             # https://github.com/python/mypy/issues/9457:
             # app._cached_branch_tips is stale-narrowed across a method call.
             assert app._cached_newest_revisions is None  # type: ignore[unreachable]
-            assert app._cached_revision_counts is None
+            assert app._cached_revisions is None
             assert app._cached_art_counts is None
 
     @pytest.mark.asyncio
     async def test_selective_invalidation_keeps_other_caches(
         self, tmp_path: pathlib.Path
     ) -> None:
-        """_invalidate_caches(change_id) only evicts that ART entry."""
+        """_invalidate_caches(change_id) evicts one ART entry and the revisions.
+
+        The revision caches have to go: _load_series only refills them when
+        _cached_newest_revisions is None, so keeping them pins the version
+        rows and both revision-count gates to pre-action data.
+
+        What the targeted form protects is the *other* series' ART entries,
+        each of which costs a `git cat-file` to rebuild.  The branch tips
+        are one `git for-each-ref` for all of them, and _load_series already
+        refills a None dict with it -- resolving them here instead only put
+        that subprocess on the message pump, in a handler that may never
+        reload at all.
+        """
         _seed_db('cache-sel-inv', SAMPLE_SERIES)
 
         app = TrackingApp('cache-sel-inv')
@@ -4719,9 +4731,12 @@ class TestLoadSeriesCaching:
             # Alpha evicted, bravo still there
             assert 'b4/review/test-change-alpha' not in app._cached_art_counts
             assert 'b4/review/test-change-bravo' in app._cached_art_counts
-            # Other caches untouched
-            assert app._cached_branch_tips is not None
-            assert app._cached_newest_revisions is not None
+            # Branch tips are dropped, not re-resolved inline: one
+            # for-each-ref refills them, and _load_series already runs it.
+            assert app._cached_branch_tips is None
+            # Revision data is dropped so the next load re-reads it
+            assert app._cached_newest_revisions is None
+            assert app._cached_revisions is None
 
     @pytest.mark.asyncio
     async def test_revisions_stashed_in_series(self, tmp_path: pathlib.Path) -> None:
Signature · 1 line
2.53.0
#25 lore raw

RFC PATCH v2 25/25 review-tui: test per-version tracker rows

In reply to Christian Brauner

Cover the expansion affordance and toggling, tracked-revision marking, child-row selection state, survival of expansion and cursor position across DB reloads and limit filtering, child-row thread opening with the right revision, direct child range-diff, expand-all, the details-panel version row, and NULL-count rendering.

---
 src/tests/test_tui_tracking.py | 1629 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 1626 insertions(+), 3 deletions(-)
src/tests/test_tui_tracking.py +1626 -3
index 7ba2443e..17cdf41a 100644
@@ -11,11 +11,14 @@ core user workflows: series listing, navigation, filtering,
 status transitions, and modal interactions.
 """
 
+import contextlib
 import datetime
 import email.message
 import os
 import pathlib
+import re
 import sqlite3
+import time
 from typing import Any, Callable, Dict, List, Optional, Tuple
 from unittest.mock import patch
 
@@ -23,7 +26,7 @@ import pytest
 
 pytest.importorskip('textual')
 
-from textual.widgets import Input, ListView, Static
+from textual.widgets import Input, Label, ListView, Static
 
 import b4
 import b4.review
@@ -36,6 +39,7 @@ from b4 import (
     _worktree_inprogress_op,
     _worktree_merge_in_progress,
 )
+from b4.review_tui._lite_app import LiteThreadScreen
 from b4.review_tui._modals import (
     ActionItem,
     ActionScreen,
@@ -45,17 +49,21 @@ from b4.review_tui._modals import (
     HelpScreen,
     LimitScreen,
     LinkRevisionScreen,
+    RangeDiffScreen,
     RebaseScreen,
     SnoozeScreen,
     TakeConfirmScreen,
     TargetBranchScreen,
 )
 from b4.review_tui._tracking_app import (
+    TrackedRevisionItem,
     TrackedSeriesItem,
     TrackingApp,
     _build_base_suggestions,
     _detect_initial_base,
     _effective_tier,
+    _format_version,
+    _msgs_fields,
     _resolve_worktree_take_conflict,
     _shazam_merge_flags,
     _take_worktree,
@@ -5995,8 +6003,6 @@ class TestRethreadFlagReachesTheThreadFetch:
         self, tmp_path: pathlib.Path
     ) -> None:
         """The viewer's series dict is what selects the reassembly path."""
-        from b4.review_tui._lite_app import LiteThreadScreen
-
         seen: Dict[str, Any] = {}
 
         def _capture(series: Dict[str, Any], identifier: str) -> List[Any]:
@@ -6017,6 +6023,27 @@ class TestRethreadFlagReachesTheThreadFetch:
         assert seen['is_rethreaded'] is True
         assert seen['revision'] == 2
 
+    @pytest.mark.asyncio
+    async def test_a_plain_version_row_reports_its_own_flag(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """v1 is not rethreaded, so its row must not inherit v2's flag."""
+        self._seed_rethreaded('rt-child')
+
+        app = TrackingApp('rt-child')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.pause()
+            with patch.object(app, 'push_screen') as mock_push:
+                await pilot.press('e')
+                await pilot.pause()
+            screen = mock_push.call_args[0][0]
+            assert screen._tracking_info['revision'] == 1
+            assert screen._tracking_info['is_rethreaded'] is False
+
 
 class TestUpdateAllDoesNotForceThePoll:
     """'u' asks about one series; 'U' must not force the schedule everywhere.
@@ -6064,6 +6091,45 @@ class TestDiscoverOlderAction:
             keys = [key for key, _label in getattr(app.screen, '_actions')]
             assert 'discover' in keys
 
+    @pytest.mark.asyncio
+    async def test_conflicts_suppress_the_nothing_found_notice(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """A run that skipped every version it found reports 0 found.
+
+        Saying "No older revisions found" and then listing four of them is
+        two notifications contradicting each other in the same toast stack.
+        """
+        _seed_db(
+            'test-discover-both',
+            [{'change_id': 'cid-d', 'revision': 5, 'status': 'new'}],
+        )
+        notices: List[str] = []
+
+        app = TrackingApp('test-discover-both')
+        with patch.object(
+            tracking,
+            'discover_older_revisions',
+            lambda *a, **kw: {
+                'found': 0,
+                'revisions': [],
+                'conflicts': [1, 2],
+                'error': None,
+            },
+        ):
+            async with app.run_test(size=(120, 30)) as pilot:
+                await pilot.pause()
+                with patch.object(
+                    TrackingApp,
+                    'notify',
+                    lambda self, msg, **kw: notices.append(str(msg)),
+                ):
+                    app.action_discover_older()
+                    await app.workers.wait_for_complete()
+                    await pilot.pause()
+        assert not any('No older revisions found' in n for n in notices), notices
+        assert any('v1, v2' in n for n in notices), notices
+
     @pytest.mark.asyncio
     async def test_action_runs_discovery(self, tmp_path: pathlib.Path) -> None:
         _seed_db(
@@ -6092,3 +6158,1560 @@ class TestDiscoverOlderAction:
                 await app.workers.wait_for_complete()
                 await pilot.pause()
         assert calls == [('test-discover-run', 'cid-d')]
+
+
+def _seed_multiver(
+    identifier: str,
+    change_id: str = 'multi-1',
+    tracked: int = 2,
+    revisions: Optional[List[int]] = None,
+) -> None:
+    """Seed a series tracking v*tracked* with *revisions* in the catalog.
+
+    The tracked revision has message counts (5 total, 2 unseen); the
+    other revisions were never fetched, so their counts stay NULL.
+    """
+    conn = tracking.init_db(identifier)
+    tracking.add_series_to_db(
+        conn,
+        change_id=change_id,
+        revision=tracked,
+        subject=f'[PATCH v{tracked} 0/2] multi: test series',
+        sender_name='Vera Version',
+        sender_email='[email protected]',
+        sent_at='2026-03-10T10:00:00+00:00',
+        message_id=f'{change_id}-v{tracked}@example.com',
+        num_patches=2,
+    )
+    conn.execute(
+        'UPDATE revisions SET message_count = 5, seen_message_count = 3'
+        ' WHERE change_id = ? AND revision = ?',
+        (change_id, tracked),
+    )
+    conn.commit()
+    for rev in [1, 2, 3] if revisions is None else revisions:
+        tracking.add_revision(
+            conn,
+            change_id,
+            rev,
+            f'{change_id}-v{rev}@example.com',
+            subject=f'[PATCH v{rev} 0/2] multi: test series',
+        )
+    conn.close()
+
+
+def _selected_rev(app: TrackingApp) -> Optional[Any]:
+    """Read _selected_revision without narrowing it for the rest of the test."""
+    return app._selected_revision
+
+
+def _version_row_shown(app: TrackingApp) -> bool:
+    """Whether the details panel's Version: row is currently displayed."""
+    return bool(app.query_one('#detail-version-row').display)
+
+
+def _list_items(app: TrackingApp) -> List[Any]:
+    """Every row currently in the tracking list, parents and children."""
+    return list(app.query_one('#tracking-list', ListView).children)
+
+
+def _row_text(item: Any) -> str:
+    """The rendered text of a single tracking list row."""
+    return _static_text(item.query_one(Label))
+
+
+def _msgs_column(text: str) -> str:
+    """The Msgs column of a rendered row (total + unseen badge).
+
+    Fixed offset: 20 (submitter) + 1 (attestation) + 1 + 7 (A·R·T) = 29,
+    then 5 for the total, a separator and 4 for the badge.  Slicing it
+    asserts that parent and child rows agree on the column layout.
+    """
+    return text[29:39].strip()
+
+
+class TestVersionExpansion:
+    """Tests for expanding a series into per-version child rows."""
+
+    @pytest.mark.asyncio
+    async def test_affordance_only_with_multiple_versions(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Only a series with more than one known version gets the marker."""
+        _seed_multiver('expand-affordance')
+        conn = tracking.get_db('expand-affordance')
+        tracking.add_series_to_db(
+            conn,
+            change_id='single-1',
+            revision=1,
+            subject='[PATCH] single: just one version',
+            sender_name='Sam Single',
+            sender_email='[email protected]',
+            sent_at='2026-03-11T10:00:00+00:00',
+            message_id='[email protected]',
+            num_patches=1,
+        )
+        tracking.add_revision(conn, 'single-1', 1, '[email protected]')
+        conn.close()
+
+        app = TrackingApp('expand-affordance')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            rows = {i.series['change_id']: _row_text(i) for i in _list_items(app)}
+            assert '▸' in rows['multi-1']
+            assert '▸' not in rows['single-1']
+
+    @pytest.mark.asyncio
+    async def test_x_expands_into_child_rows(self, tmp_path: pathlib.Path) -> None:
+        """x adds one child row per known version, oldest first."""
+        _seed_multiver('expand-toggle')
+
+        app = TrackingApp('expand-toggle')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert len(_list_items(app)) == 1
+
+            await pilot.press('x')
+            await pilot.pause()
+            items = _list_items(app)
+            assert len(items) == 4
+            assert isinstance(items[0], TrackedSeriesItem)
+            assert items[0].expanded
+            assert '▾' in _row_text(items[0])
+            children = items[1:]
+            assert all(isinstance(c, TrackedRevisionItem) for c in children)
+            assert [c.rev['revision'] for c in children] == [1, 2, 3]
+
+    @pytest.mark.asyncio
+    async def test_x_collapses_again(self, tmp_path: pathlib.Path) -> None:
+        """A second x hides the child rows and restores the parent cursor."""
+        _seed_multiver('expand-collapse')
+
+        app = TrackingApp('expand-collapse')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            # Collapse from a child row — focus must return to the parent
+            await pilot.press('j')
+            await pilot.pause()
+            assert app._selected_revision is not None
+
+            await pilot.press('x')
+            await pilot.pause()
+            items = _list_items(app)
+            assert len(items) == 1
+            assert '▸' in _row_text(items[0])
+            assert _selected_rev(app) is None
+            assert app.query_one('#tracking-list', ListView).index == 0
+
+    @pytest.mark.asyncio
+    async def test_tracked_version_is_marked(self, tmp_path: pathlib.Path) -> None:
+        """The child row for the tracked revision carries an asterisk."""
+        _seed_multiver('expand-marker')
+
+        app = TrackingApp('expand-marker')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            children = _list_items(app)[1:]
+            marked = [c for c in children if c.is_tracked]
+            assert len(marked) == 1
+            assert marked[0].rev['revision'] == 2
+            assert 'v2*' in _row_text(marked[0])
+            assert 'v1*' not in _row_text(children[0])
+            assert 'v3*' not in _row_text(children[2])
+
+    @pytest.mark.asyncio
+    async def test_highlighting_child_keeps_parent_series(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """A child row selects its version, but the series stays the parent."""
+        _seed_multiver('expand-select')
+
+        app = TrackingApp('expand-select')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+
+            await pilot.press('j')
+            await pilot.pause()
+            sel_rev = _selected_rev(app)
+            assert sel_rev is not None
+            assert sel_rev['revision'] == 1
+            assert app._selected_series is not None
+            assert app._selected_series['change_id'] == 'multi-1'
+
+            # Back on the parent row the version selection is cleared
+            await pilot.press('k')
+            await pilot.pause()
+            assert _selected_rev(app) is None
+            assert app._selected_series is not None
+            assert app._selected_series['change_id'] == 'multi-1'
+
+    @pytest.mark.asyncio
+    async def test_expansion_and_cursor_survive_db_reload(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """An external DB change rebuilds the list without losing the child."""
+        _seed_multiver('expand-reload')
+
+        app = TrackingApp('expand-reload')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.press('j')
+            await pilot.pause()
+            assert app._selected_revision is not None
+            assert app._selected_revision['revision'] == 2
+
+            # Bump the mtime the way another b4 process writing the DB would
+            db_path = tracking.get_db_path('expand-reload')
+            stamp = os.path.getmtime(db_path) + 10
+            os.utime(db_path, (stamp, stamp))
+            app._check_db_changed()
+            await pilot.pause()
+
+            items = _list_items(app)
+            assert len(items) == 4
+            assert isinstance(items[2], TrackedRevisionItem)
+            assert app.query_one('#tracking-list', ListView).index == 2
+            assert app._selected_revision is not None
+            assert app._selected_revision['revision'] == 2
+
+    @pytest.mark.asyncio
+    async def test_x_is_noop_on_single_version_series(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """A series with only the tracked version has nothing to expand."""
+        _seed_db('expand-single', [SAMPLE_SERIES[1]])
+
+        app = TrackingApp('expand-single')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            assert len(_list_items(app)) == 1
+            assert not app._expanded_rows
+
+    @pytest.mark.asyncio
+    async def test_expansion_survives_limit_filter(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Setting and clearing a limit keeps the series expanded."""
+        _seed_multiver('expand-limit')
+
+        app = TrackingApp('expand-limit')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            assert len(_list_items(app)) == 4
+
+            await pilot.press('l')
+            await pilot.pause()
+            app.screen.query_one('#limit-input', Input).value = 'multi'
+            await pilot.press('enter')
+            await pilot.pause()
+            assert len(_list_items(app)) == 4
+
+            await pilot.press('l')
+            await pilot.pause()
+            app.screen.query_one('#limit-input', Input).value = ''
+            await pilot.press('enter')
+            await pilot.pause()
+            assert len(_list_items(app)) == 4
+
+    @pytest.mark.asyncio
+    async def test_filtering_everything_away_drops_the_selection(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """An empty list must not leave a version row selected.
+
+        The empty-list branch returns above the block that re-derives the
+        selection from the cursor, so the stale pair kept every series
+        action enabled -- and on a version row 'd' skips the picker and
+        range-diffs a series the list is no longer showing.
+        """
+        _seed_multiver('expand-empty')
+
+        app = TrackingApp('expand-empty')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.pause()
+            # Bound to a local: asserting on the attribute narrows it for
+            # the rest of the function, and mypy then calls the checks
+            # below unreachable.
+            on_child = app._selected_revision
+            assert on_child is not None
+
+            await pilot.press('l')
+            await pilot.pause()
+            app.screen.query_one('#limit-input', Input).value = 'nomatch-xyzzy'
+            await pilot.press('enter')
+            await pilot.pause()
+            assert len(app.query('#tracking-list')) == 0
+            assert app.query_one('#tracking-empty', Static)
+            assert app._selected_revision is None
+            assert app._selected_series is None
+            assert app.check_action('range_diff', ()) is False
+            # 'thread' is ungated and self-guards instead; with nothing
+            # selected it must open no screen.
+            depth = len(app.screen_stack)
+            app.action_thread()
+            await pilot.pause()
+            assert len(app.screen_stack) == depth
+
+    @pytest.mark.asyncio
+    async def test_expand_all_toggles_every_series(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """X expands all multi-version series, then collapses them."""
+        _seed_multiver('expand-all', change_id='multi-a')
+        _seed_multiver('expand-all', change_id='multi-b')
+
+        app = TrackingApp('expand-all')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert len(_list_items(app)) == 2
+
+            await pilot.press('X')
+            await pilot.pause()
+            assert len(_list_items(app)) == 8  # 2 parents + 3 versions each
+            assert app._expanded_rows == {('multi-a', 2), ('multi-b', 2)}
+
+            await pilot.press('X')
+            await pilot.pause()
+            assert len(_list_items(app)) == 2
+            assert not app._expanded_rows
+
+            # A partially expanded list expands the rest before collapsing
+            await pilot.press('x')
+            await pilot.pause()
+            assert len(_list_items(app)) == 5
+            await pilot.press('X')
+            await pilot.pause()
+            assert len(_list_items(app)) == 8
+
+    @pytest.mark.asyncio
+    async def test_child_msgs_column(self, tmp_path: pathlib.Path) -> None:
+        """Child counts render like the parent, with '-' when never fetched."""
+        _seed_multiver('expand-msgs')
+
+        app = TrackingApp('expand-msgs')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            items = _list_items(app)
+            # v1 was never fetched, v2 is tracked (5 messages, 2 unseen)
+            assert items[1].rev['message_count'] is None
+            assert _msgs_column(_row_text(items[1])) == '-'
+            assert _msgs_column(_row_text(items[2])) == '5 (2)'
+            assert _msgs_column(_row_text(items[0])) == '5 (2)'
+
+    def test_missing_seen_count_reads_the_same_both_ways(self) -> None:
+        """A pre-v11 row can arrive with a total but no seen count.
+
+        The Msgs column and the details panel one line below it must not
+        answer that differently.
+        """
+        assert _msgs_fields(5, None) == ('5', '', False)
+        assert '5 msgs (0 unseen)' in _format_version(
+            {'revision': 2, 'message_count': 5, 'seen_message_count': None},
+            {'revision': 3},
+        )
+
+    @pytest.mark.asyncio
+    async def test_child_rows_show_subjects(self, tmp_path: pathlib.Path) -> None:
+        """Every version row carries its own prefix-stripped title."""
+        _seed_multiver('expand-subject', revisions=[1, 2])
+        conn = tracking.get_db('expand-subject')
+        tracking.add_revision(
+            conn,
+            'multi-1',
+            3,
+            '[email protected]',
+            subject='[PATCH v3 0/2] multi: renamed after review',
+        )
+        conn.close()
+
+        app = TrackingApp('expand-subject')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            items = _list_items(app)
+            # Versions keeping the series title still show it -- an empty
+            # subject cell reads as missing data.
+            assert 'multi: test series' in _row_text(items[1])
+            assert 'multi: test series' in _row_text(items[2])
+            # A retitled version shows its own title, prefix-stripped.
+            assert 'multi: renamed after review' in _row_text(items[3])
+            assert '[PATCH v3' not in _row_text(items[3])
+
+    @pytest.mark.asyncio
+    async def test_details_panel_version_row(self, tmp_path: pathlib.Path) -> None:
+        """The Version row describes the highlighted child, and hides for parents."""
+        _seed_multiver('expand-details')
+
+        app = TrackingApp('expand-details')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert not _version_row_shown(app)
+
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.press('j')
+            await pilot.pause()
+            assert _version_row_shown(app)
+            text = _static_text(app.query_one('#detail-version', Static))
+            assert text.startswith('v2 (tracked)')
+            assert '5 msgs (2 unseen)' in text
+            assert ', posted ' in text
+
+            # A version that was never fetched has no counts to show
+            await pilot.press('k')
+            await pilot.pause()
+            text = _static_text(app.query_one('#detail-version', Static))
+            assert text.startswith('v1')
+            assert '(tracked)' not in text
+            assert '- msgs (- unseen)' in text
+
+            # The catalog knows no patch count or send date per revision, so
+            # neither is filled in from the tracked revision.
+            subj = _static_text(app.query_one('#detail-subject', Static))
+            assert subj.startswith('[v1] ')
+            assert _static_text(app.query_one('#detail-sent', Static)) == 'Unknown'
+
+            # Back on the parent row the version detail disappears
+            await pilot.press('k')
+            await pilot.pause()
+            assert not _version_row_shown(app)
+
+
+class TestChildRowActions:
+    """Tests for actions taken while a version row is highlighted."""
+
+    @pytest.mark.asyncio
+    async def test_e_opens_that_version_thread(self, tmp_path: pathlib.Path) -> None:
+        """e on a child views the child's thread, not the tracked one."""
+        _seed_multiver('child-thread')
+
+        app = TrackingApp('child-thread')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.pause()
+
+            with patch.object(app, 'push_screen') as mock_push:
+                await pilot.press('e')
+                await pilot.pause()
+
+            assert mock_push.call_count == 1
+            screen = mock_push.call_args[0][0]
+            assert isinstance(screen, LiteThreadScreen)
+            assert screen._message_id == '[email protected]'
+            assert screen._tracking_info is not None
+            assert screen._tracking_info['change_id'] == 'multi-1'
+            assert screen._tracking_info['revision'] == 1
+
+    @pytest.mark.asyncio
+    async def test_enter_opens_that_version_thread(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Enter on a child opens the thread instead of the action menu."""
+        _seed_multiver('child-enter')
+
+        app = TrackingApp('child-enter')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            for _ in range(3):
+                await pilot.press('j')
+            await pilot.pause()
+
+            with patch.object(app, 'push_screen') as mock_push:
+                await pilot.press('enter')
+                await pilot.pause()
+
+            assert mock_push.call_count == 1
+            screen = mock_push.call_args[0][0]
+            assert isinstance(screen, LiteThreadScreen)
+            assert screen._message_id == '[email protected]'
+            assert screen._tracking_info is not None
+            assert screen._tracking_info['revision'] == 3
+
+    @pytest.mark.asyncio
+    async def test_e_on_parent_still_opens_tracked_thread(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """With no child highlighted, e views the tracked revision's thread."""
+        _seed_multiver('child-parent-thread')
+
+        app = TrackingApp('child-parent-thread')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+
+            with patch.object(app, 'push_screen') as mock_push:
+                await pilot.press('e')
+                await pilot.pause()
+
+            screen = mock_push.call_args[0][0]
+            assert screen._message_id == '[email protected]'
+            assert screen._tracking_info['revision'] == 2
+
+    @pytest.mark.asyncio
+    async def test_d_range_diffs_child_against_tracked(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """d on a child diffs it against the tracked revision, no picker."""
+        _seed_multiver('child-rangediff')
+
+        app = TrackingApp('child-rangediff')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            for _ in range(3):
+                await pilot.press('j')
+            await pilot.pause()
+            assert app._selected_revision is not None
+            assert app._selected_revision['revision'] == 3
+
+            with (
+                patch.object(app, '_do_range_diff') as mock_diff,
+                patch.object(app, 'suspend', return_value=contextlib.nullcontext()),
+            ):
+                await pilot.press('d')
+                await pilot.pause()
+
+            mock_diff.assert_called_once_with('multi-1', 2, 3)
+            assert not isinstance(app.screen, RangeDiffScreen)
+
+    @pytest.mark.asyncio
+    async def test_d_enabled_when_only_synthesized_row_makes_two(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Both gates count the tracked revision the same way.
+
+        Gating d on a raw catalog count once left an expanded version row
+        with d disabled.  Tracking a series now catalogues the revision it
+        tracks, so the two counts agree by construction rather than by the
+        merge helper patching one of them up.
+        """
+        _seed_multiver('child-rangediff-gate', tracked=2, revisions=[3])
+
+        app = TrackingApp('child-rangediff-gate')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            sel = app._selected_series
+            assert sel is not None
+            assert len(sel.get('_revisions') or []) == 2
+            assert len(app._merge_tracked_revision(sel)) == 2
+            assert app.check_action('toggle_expand', ()) is True
+            assert app.check_action('range_diff', ()) is True
+
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.press('j')
+            await pilot.pause()
+            assert app._selected_revision is not None
+            assert app._selected_revision['revision'] == 3
+
+            with (
+                patch.object(app, '_do_range_diff') as mock_diff,
+                patch.object(app, 'suspend', return_value=contextlib.nullcontext()),
+            ):
+                await pilot.press('d')
+                await pilot.pause()
+            mock_diff.assert_called_once_with('multi-1', 2, 3)
+
+    @pytest.mark.asyncio
+    async def test_d_on_tracked_child_shows_picker(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """The tracked version has no implied other side — pick one."""
+        _seed_multiver('child-rangediff-self')
+
+        app = TrackingApp('child-rangediff-self')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.press('j')
+            await pilot.pause()
+            assert app._selected_revision is not None
+            assert app._selected_revision['revision'] == 2
+
+            with patch.object(app, '_do_range_diff') as mock_diff:
+                await pilot.press('d')
+                await pilot.pause()
+                assert isinstance(app.screen, RangeDiffScreen)
+                await pilot.press('escape')
+                await pilot.pause()
+
+            mock_diff.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_series_actions_use_parent_from_child_row(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """The action menu on a child row acts on the parent series."""
+        _seed_multiver('child-action')
+
+        app = TrackingApp('child-action')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.pause()
+
+            await pilot.press('a')
+            await pilot.pause()
+            assert isinstance(app.screen, ActionScreen)
+            lv = app.screen.query_one('#action-list', ListView)
+            actions = [c.key for c in lv.children if isinstance(c, ActionItem)]
+            assert 'abandon' in actions
+            # 'r' is greyed out on another version's row because it checks out
+            # the *tracked* revision; the menu has to refuse it too, or the
+            # checkout the guard declines is one extra keystroke away.
+            assert 'review' not in actions
+            await pilot.press('escape')
+            await pilot.pause()
+            assert app._selected_series is not None
+            assert app._selected_series['change_id'] == 'multi-1'
+
+
+class TestUnseenVersionSignal:
+    """The collapsed row has to show that a non-tracked version has mail."""
+
+    @staticmethod
+    def _set_counts(identifier: str, rev: int, total: int, seen: int) -> None:
+        conn = tracking.get_db(identifier)
+        conn.execute(
+            'UPDATE revisions SET message_count = ?, seen_message_count = ?'
+            ' WHERE change_id = ? AND revision = ?',
+            (total, seen, 'multi-1', rev),
+        )
+        conn.commit()
+        conn.close()
+
+    @pytest.mark.asyncio
+    async def test_marker_flags_unread_on_an_older_version(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        _seed_multiver('unseen-child')
+        # v1 has 3 unread; the tracked v2 has none of its own.
+        self._set_counts('unseen-child', 1, 7, 4)
+
+        app = TrackingApp('unseen-child')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            item = _list_items(app)[0]
+            assert isinstance(item, TrackedSeriesItem)
+            assert item.has_unseen_versions
+            assert '▸' in _row_text(item)
+
+    @pytest.mark.asyncio
+    async def test_tracked_revisions_own_unread_does_not_flag_it(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """The Msgs column already carries the tracked revision's badge."""
+        _seed_multiver('unseen-tracked-only')
+        # Only the tracked v2 has an unread delta (5 total, 3 seen).
+        for rev in (1, 3):
+            self._set_counts('unseen-tracked-only', rev, 4, 4)
+
+        app = TrackingApp('unseen-tracked-only')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            item = _list_items(app)[0]
+            assert isinstance(item, TrackedSeriesItem)
+            assert not item.has_unseen_versions
+
+    @pytest.mark.asyncio
+    async def test_never_counted_versions_do_not_flag_it(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """A NULL count is "unknown", not "all unread"."""
+        _seed_multiver('unseen-null')
+
+        app = TrackingApp('unseen-null')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            item = _list_items(app)[0]
+            assert isinstance(item, TrackedSeriesItem)
+            assert not item.has_unseen_versions
+
+
+class TestVersionRowDetails:
+    @pytest.mark.asyncio
+    async def test_attestation_is_not_shown_for_another_version(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Attestation is stored per series row, so it describes v2 only."""
+        _seed_multiver('att-version')
+        conn = tracking.get_db('att-version')
+        conn.execute(
+            "UPDATE series SET attestation = 'signed:dkim/example.com'"
+            " WHERE change_id = 'multi-1'"
+        )
+        conn.commit()
+        conn.close()
+
+        app = TrackingApp('att-version')
+
+        def att_shown() -> bool:
+            return bool(app.query_one('#detail-attestation-row').display)
+
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert att_shown()
+
+            # Move onto a child row for a different version.
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.pause()
+            sel = _selected_rev(app)
+            assert sel is not None and sel['revision'] == 1
+            assert not att_shown()
+
+            # ...and back on the tracked version's own row it returns.
+            await pilot.press('k')
+            await pilot.pause()
+            assert att_shown()
+
+
+class TestNeedsUpdateHintSurvivesTheMergedList:
+    @pytest.mark.asyncio
+    async def test_hint_is_shown_when_the_catalog_is_empty(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """The row's '*' flag and the panel have to agree.
+
+        The merged version list always carries the tracked revision, so the
+        panel started rendering 'Revisions: v1' for a series with no catalog
+        data at all -- contradicting the '*' the same row was flying, and
+        leaving the documented "tracking data needs a refresh" hint
+        unreachable.
+        """
+        _seed_db(
+            'needs-update-hint',
+            [
+                {
+                    'change_id': 'no-cat',
+                    'revision': 1,
+                    'subject': '[PATCH] thing: do it',
+                    # Not one of the branch-backed states, or the startup
+                    # rescan marks it gone and the flag is suppressed.
+                    'status': 'accepted',
+                }
+            ],
+        )
+
+        app = TrackingApp('needs-update-hint')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert app._all_series[0].get('needs_update')
+            row = app.query_one('#detail-revisions-row')
+            assert row.display
+            assert 'run [u]pdate' in _static_text(
+                app.query_one('#detail-revisions', Static)
+            )
+
+    @pytest.mark.asyncio
+    async def test_hint_survives_the_v11_catalog_backfill(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """A migrated database must not lose the hint on the way in.
+
+        Schema v11 backfills a catalog row for every series row, so a
+        never-swept series stopped looking any different from one that was
+        swept and found nothing: counting catalog rows put the '*' flag and
+        the panel hint permanently out of reach for every upgrading user.
+        """
+        _seed_db(
+            'needs-update-migrated',
+            [
+                {
+                    'change_id': 'migrated',
+                    'revision': 2,
+                    'subject': '[PATCH v2] thing: do it',
+                    'status': 'accepted',
+                }
+            ],
+        )
+        conn = tracking.get_db('needs-update-migrated')
+        # Exactly what the migration leaves behind: an entry mirroring the
+        # tracked revision, and no watermark, because no sweep has run.
+        tracking.add_revision(conn, 'migrated', 2, '[email protected]')
+        conn.execute('UPDATE revisions SET last_update_check = NULL')
+        conn.commit()
+        conn.close()
+
+        app = TrackingApp('needs-update-migrated')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert app._all_series[0].get('needs_update')
+            assert 'run [u]pdate' in _static_text(
+                app.query_one('#detail-revisions', Static)
+            )
+
+    @pytest.mark.asyncio
+    async def test_no_hint_once_a_sweep_has_run(self, tmp_path: pathlib.Path) -> None:
+        """A v1 series has no other version to find, and must not nag."""
+        _seed_db(
+            'needs-update-swept',
+            [
+                {
+                    'change_id': 'swept',
+                    'revision': 1,
+                    'subject': '[PATCH] thing: do it',
+                    'status': 'accepted',
+                }
+            ],
+        )
+        conn = tracking.get_db('needs-update-swept')
+        tracking.add_revision(conn, 'swept', 1, '[email protected]')
+        conn.execute(
+            "UPDATE revisions SET last_update_check = '2026-03-10T10:00:00+00:00'"
+        )
+        conn.commit()
+        conn.close()
+
+        app = TrackingApp('needs-update-swept')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert not app._all_series[0].get('needs_update')
+
+
+class TestVersionRowDates:
+    def test_panel_dates_are_local_not_a_utc_slice(self) -> None:
+        """The details panel and the version row must not disagree by a day.
+
+        The row converts to local time on purpose; the panel used to slice
+        the stored ISO string, so within the local offset of midnight the
+        two rendered different dates for the same revision.
+        """
+        old_tz = os.environ.get('TZ')
+        os.environ['TZ'] = 'Australia/Sydney'
+        time.tzset()
+        try:
+            stamp = '2026-03-12T23:30:00+00:00'
+            out = _tracking_app._format_version(
+                {
+                    'revision': 1,
+                    'message_count': 4,
+                    'seen_message_count': 4,
+                    'found_at': stamp,
+                    'last_mail_at': stamp,
+                },
+                {'revision': 2},
+            )
+            # 23:30 UTC is already the 13th in Sydney; the ISO slice says 12th.
+            assert ', posted 2026-03-13' in out
+            assert ', last activity 2026-03-13' in out
+            assert _tracking_app._local_stamp(stamp, '%d %b') == '13 Mar'
+        finally:
+            if old_tz is None:
+                os.environ.pop('TZ', None)
+            else:
+                os.environ['TZ'] = old_tz
+            time.tzset()
+
+    def test_unparseable_stamp_renders_empty(self) -> None:
+        assert _tracking_app._local_stamp('not a date', '%d %b') == ''
+        assert _tracking_app._local_stamp(None, '%d %b') == ''
+
+
+class TestDuplicateChangeIdRows:
+    """rescan_branches can leave one change_id with two live series rows."""
+
+    @staticmethod
+    def _seed(identifier: str) -> None:
+        conn = tracking.init_db(identifier)
+        for rev, added in ((2, '2026-03-01T00:00:00+00:00'), (5, '2026-03-02')):
+            conn.execute(
+                'INSERT INTO series (change_id, revision, message_id, subject,'
+                ' sender_name, sender_email, sent_at, added_at, status,'
+                " num_patches) VALUES ('dup',?,?,?,'Dee','[email protected]',"
+                "?,?,'new',2)",
+                (
+                    rev,
+                    f'dup-v{rev}@example.com',
+                    f'[PATCH v{rev} 0/2] dup: a series',
+                    added,
+                    added,
+                ),
+            )
+        for rev in (1, 2, 5):
+            tracking.add_revision(conn, 'dup', rev, f'dup-v{rev}@example.com')
+        conn.commit()
+        conn.close()
+
+    @pytest.mark.asyncio
+    async def test_expanding_one_row_leaves_its_twin_collapsed(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Expansion is per row, not per change_id.
+
+        Both rows are rendered separately and carry different tracked
+        revisions, so keying the expansion on the change_id alone unfolded
+        the pair together and gave each an identical set of child rows.
+        """
+        self._seed('dup-expand')
+
+        app = TrackingApp('dup-expand')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            items = _list_items(app)
+            assert len(items) == 2
+            first_rev = items[0].series['revision']
+
+            await pilot.press('x')
+            await pilot.pause()
+            items = _list_items(app)
+            # One parent grew three children; the other is untouched.
+            assert len(items) == 5
+            assert app._expanded_rows == {('dup', first_rev)}
+            parents = [i for i in items if isinstance(i, TrackedSeriesItem)]
+            assert [p.expanded for p in parents] == [True, False]
+
+    @pytest.mark.asyncio
+    async def test_unread_on_a_twins_revision_is_not_this_rows_badge(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Another live row's revision is that row's business, not this one's.
+
+        Its counts are badged in its own Msgs column; accenting this row's
+        expander for them reports "an older version of this series has new
+        mail" about a version this series never tracked.
+        """
+        self._seed('dup-badge')
+        conn = tracking.get_db('dup-badge')
+        # Unread mail on v5 -- which the other live row tracks.
+        conn.execute(
+            'UPDATE revisions SET message_count = 9, seen_message_count = 4'
+            " WHERE change_id = 'dup' AND revision = 5"
+        )
+        conn.commit()
+        conn.close()
+
+        app = TrackingApp('dup-badge')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            by_rev = {
+                i.series['revision']: i
+                for i in _list_items(app)
+                if isinstance(i, TrackedSeriesItem)
+            }
+            # v5 is the other row's own tracked revision...
+            assert by_rev[2].has_unseen_versions is False
+            # ...and v5's row does not badge itself for it either.
+            assert by_rev[5].has_unseen_versions is False
+
+
+class TestLimitCursorRestore:
+    @pytest.mark.asyncio
+    async def test_cursor_returns_after_a_limit_matched_nothing(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """Clearing the selection must not also drop the restore hint.
+
+        The empty branch has to forget what is selected, or every action
+        stays enabled against a row the list no longer shows -- but the
+        stashed focus is only a hint, and dropping it lands the cursor at
+        the top once the filter is cleared again.
+        """
+        _seed_db('limit-empty', [SAMPLE_SERIES[0], SAMPLE_SERIES[1]])
+
+        app = TrackingApp('limit-empty')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.pause()
+            selected = app._selected_series
+            assert selected is not None
+            target = selected['change_id']
+
+            app._limit_pattern = 'nothing-matches-this'
+            app._stash_focus()
+            await app._refresh_list()
+            await pilot.pause()
+            while_empty = app._selected_series
+            assert while_empty is None
+
+            app._limit_pattern = ''
+            await app._refresh_list()
+            await pilot.pause()
+            restored = app._selected_series
+            assert restored is not None
+            assert restored['change_id'] == target
+
+
+class TestExpandAllScope:
+    @pytest.mark.asyncio
+    async def test_expand_all_ignores_filtered_out_series(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """[X] judged "already expanded?" against rows the filter hides."""
+        _seed_multiver('expand-scope', change_id='multi-1')
+        conn = tracking.get_db('expand-scope')
+        tracking.add_series_to_db(
+            conn,
+            change_id='other-1',
+            revision=2,
+            subject='[PATCH v2 0/2] other: hidden series',
+            sender_name='Hidden Hank',
+            sender_email='[email protected]',
+            sent_at='2026-03-11T10:00:00+00:00',
+            message_id='[email protected]',
+            num_patches=2,
+        )
+        for rev in (1, 2):
+            tracking.add_revision(conn, 'other-1', rev, f'other-1-v{rev}@example.com')
+        conn.close()
+
+        app = TrackingApp('expand-scope')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            # Hide 'other-1' behind the limit filter.
+            app._limit_pattern = 'multi'
+            await app._refresh_list()
+            await pilot.pause()
+            assert len(_list_items(app)) == 1
+
+            app.action_expand_all()
+            await pilot.pause()
+            # The visible series expanded, and the hidden one was not
+            # counted when deciding expand-vs-collapse.
+            assert app._expanded_rows == {('multi-1', 2)}
+            assert len(_list_items(app)) == 4
+
+    @pytest.mark.asyncio
+    async def test_expand_all_collapse_leaves_hidden_series_alone(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """[X] collapsing must not fold up what the filter is hiding."""
+        _seed_multiver('collapse-scope', change_id='multi-1')
+        conn = tracking.get_db('collapse-scope')
+        tracking.add_series_to_db(
+            conn,
+            change_id='other-1',
+            revision=2,
+            subject='[PATCH v2 0/2] other: hidden series',
+            sender_name='Hidden Hank',
+            sender_email='[email protected]',
+            sent_at='2026-03-11T10:00:00+00:00',
+            message_id='[email protected]',
+            num_patches=2,
+        )
+        for rev in (1, 2):
+            tracking.add_revision(conn, 'other-1', rev, f'other-1-v{rev}@example.com')
+        conn.close()
+
+        app = TrackingApp('collapse-scope')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            # Expand both, then hide one behind the limit filter.
+            app.action_expand_all()
+            await pilot.pause()
+            assert app._expanded_rows == {('multi-1', 2), ('other-1', 2)}
+            app._limit_pattern = 'multi'
+            await app._refresh_list()
+            await pilot.pause()
+
+            app.action_expand_all()
+            await pilot.pause()
+            # Only the displayed series collapsed.
+            assert app._expanded_rows == {('other-1', 2)}
+
+
+class TestUnseenVersionMarkerRendering:
+    """The computed flag has to reach the glyph, not just the attribute."""
+
+    @pytest.mark.asyncio
+    async def test_the_marker_is_accented_when_an_older_version_has_mail(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        _seed_multiver('unseen-style')
+        conn = tracking.get_db('unseen-style')
+        conn.execute(
+            'UPDATE revisions SET message_count = 7, seen_message_count = 4'
+            " WHERE change_id = 'multi-1' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+
+        app = TrackingApp('unseen-style')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            label = _list_items(app)[0].query_one(Label)
+            marker_spans = [
+                span
+                for span in label.content.spans
+                if label.content.plain[span.start : span.end] == '▸'
+            ]
+            assert marker_spans, 'the ▸ marker carries no style'
+            assert 'bold' in str(marker_spans[0].style)
+
+    @pytest.mark.asyncio
+    async def test_the_marker_is_plain_when_nothing_is_unread(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        _seed_multiver('unseen-style-none')
+
+        app = TrackingApp('unseen-style-none')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            label = _list_items(app)[0].query_one(Label)
+            marker_spans = [
+                span
+                for span in label.content.spans
+                if label.content.plain[span.start : span.end] == '▸'
+            ]
+            assert marker_spans == []
+
+
+class TestStatusActionsKeepTheVersionRow:
+    @pytest.mark.asyncio
+    async def test_waiting_from_a_version_row_stays_there(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """A status change says nothing about which versions the series has.
+
+        Setting a target branch already left the cursor alone; snooze,
+        unsnooze, waiting and thank bounced it up to the parent, so two
+        status-only actions taken from the same row disagreed about where
+        the cursor belonged afterwards.
+        """
+        _seed_multiver('status-keeps-row')
+        app = TrackingApp('status-keeps-row')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')  # onto the first version row
+            await pilot.pause()
+            before = app.query_one('#tracking-list', ListView).index
+            assert isinstance(_list_items(app)[before], TrackedRevisionItem)
+            picked = _list_items(app)[before].rev['revision']
+
+            app.action_waiting()
+            await pilot.pause()
+            await pilot.pause()
+
+            item = _list_items(app)[
+                app.query_one('#tracking-list', ListView).index or 0
+            ]
+            assert isinstance(item, TrackedRevisionItem)
+            assert item.rev['revision'] == picked
+            assert app._selected_revision is not None
+            assert app._selected_revision['revision'] == picked
+
+
+class TestVersionRowDateIsLocal:
+    @pytest.mark.asyncio
+    async def test_the_date_is_rendered_in_local_time(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """The column stores UTC; showing it raw puts a row a day out.
+
+        23:00 UTC is the next day in any eastward zone, which is exactly
+        when a maintainer notices the version row and the thread viewer
+        disagreeing about the same message.
+
+        Plain environ save/restore, not monkeypatch.setenv: the fixture
+        undoes its env change after this method's finally block, so the
+        last tzset() here would run with TZ unset and leave libc's cached
+        zone disagreeing with os.environ for the rest of the process.
+        """
+        old_tz = os.environ.get('TZ')
+        os.environ['TZ'] = 'Australia/Sydney'
+        time.tzset()
+        try:
+            _seed_multiver('rowdate-local')
+            conn = tracking.get_db('rowdate-local')
+            conn.execute(
+                "UPDATE revisions SET last_mail_at = '2026-03-11T23:30:00+00:00'"
+                " WHERE change_id = 'multi-1' AND revision = 1"
+            )
+            conn.commit()
+            conn.close()
+
+            app = TrackingApp('rowdate-local')
+            async with app.run_test(size=(120, 30)) as pilot:
+                await pilot.pause()
+                await pilot.press('x')
+                await pilot.pause()
+                child = _list_items(app)[1]
+                assert isinstance(child, TrackedRevisionItem)
+                assert '12 Mar' in _row_text(child)
+        finally:
+            if old_tz is None:
+                os.environ.pop('TZ', None)
+            else:
+                os.environ['TZ'] = old_tz
+            time.tzset()
+
+    @pytest.mark.asyncio
+    async def test_the_date_touches_neither_neighbour(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """The date shares the submitter field with the version label.
+
+        Both are variable width, so the check is that blanks separate the
+        date from the version beside it and from the counts after it, and
+        that Subject still starts on the same column as the parent row's --
+        which is the column the header describes.
+        """
+        _seed_multiver('rowdate-gap')
+        conn = tracking.get_db('rowdate-gap')
+        conn.execute(
+            "UPDATE revisions SET last_mail_at = '2026-03-11T10:00:00+00:00'"
+            " WHERE change_id = 'multi-1' AND revision = 1"
+        )
+        conn.commit()
+        conn.close()
+
+        app = TrackingApp('rowdate-gap')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            items = _list_items(app)
+            child = items[1]
+            assert isinstance(child, TrackedRevisionItem)
+            text = _row_text(child)
+            assert 'multi: test series' in text
+            # Blank on both sides of the date, whatever it renders as.
+            assert re.search(r'v1 +11 Mar +', text)
+            # Subject starts where the parent's does, and the header says so.
+            assert text.index('multi: test series') == _row_text(items[0]).index('[v2,')
+
+
+class TestConflictNoticeKeepsItsKeyHint:
+    def test_the_link_key_survives_markup_rendering(self) -> None:
+        """notify() renders Rich markup, so a bare [l] is eaten as a tag."""
+        from textual.content import Content
+
+        from b4.review_tui._tracking_app import _conflicts_notice
+
+        notice = _conflicts_notice([2, 3])
+        rendered = Content.from_markup(notice).plain
+        assert 'v2, v3' in rendered
+        assert '[l]' in rendered
+        # ...and nothing was mistaken for a style along the way.
+        assert Content.from_markup(notice).spans == []
+
+
+class TestDiscoveryErrorSurvivesMarkupRendering:
+    """A lore exception is arbitrary text, and notify() parses markup."""
+
+    def test_a_bracketed_subject_is_not_swallowed(self) -> None:
+        """Lowercase-initial brackets parse as a style tag and vanish."""
+        from textual.content import Content
+
+        from b4.review_tui._tracking_app import _discovery_error_notice
+
+        notice = _discovery_error_notice('no match for [patch v2 1/3] foo: fix')
+        rendered = Content.from_markup(notice).plain
+        assert '[patch v2 1/3] foo: fix' in rendered
+        assert Content.from_markup(notice).spans == []
+
+    def test_a_closing_tag_does_not_raise(self) -> None:
+        """An unbalanced '[/...]' raises MarkupError inside the toast."""
+        from textual.content import Content
+
+        from b4.review_tui._tracking_app import _discovery_error_notice
+
+        notice = _discovery_error_notice('cannot read [/var/tmp/x] while fetching')
+        rendered = Content.from_markup(notice).plain
+        assert '[/var/tmp/x]' in rendered
+
+
+class TestVersionRowActionGating:
+    @pytest.mark.asyncio
+    async def test_range_diff_is_offered_on_a_thanked_series(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """[x] expands in every state, and the docs promise 'd' on a child."""
+        _seed_multiver('gate-thanked')
+        conn = tracking.get_db('gate-thanked')
+        tracking.update_series_status(conn, 'multi-1', 'thanked', revision=2)
+        conn.close()
+
+        app = TrackingApp('gate-thanked')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert app.check_action('toggle_expand', ()) is True
+            assert app.check_action('range_diff', ()) is True
+
+    @pytest.mark.asyncio
+    async def test_review_is_disabled_on_another_version(
+        self, tmp_path: pathlib.Path
+    ) -> None:
+        """'r' checks out the tracked revision, not the highlighted one."""
+        _seed_multiver('gate-review')
+        app = TrackingApp('gate-review')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert app.check_action('review', ()) is True
+            await pilot.press('x')
+            await pilot.pause()
+            # Cursor onto v1 -- not the tracked v2.
+            await pilot.press('j')
+            await pilot.pause()
+            assert _selected_rev(app) is not None
+            assert app.check_action('review', ()) is False
+            # ...and on the tracked revision's own row it is fine again.
+            await pilot.press('j')
+            await pilot.pause()
+            assert _selected_rev(app) is not None
+            assert app.check_action('review', ()) is True
+
+    @pytest.mark.asyncio
+    async def test_take_and_rebase_are_disabled_on_another_version(
+        self, gitdir: str
+    ) -> None:
+        """Both act on the review branch, which holds the tracked revision.
+
+        'r' was greyed out for that reason from the start; these two build
+        and move the very same branch, so offering them on a v1 row runs
+        them against v2 while every label on screen says v1.
+        """
+        # A real branch, or the startup rescan turns 'reviewing' into 'gone'
+        # and neither action is offered in any case.
+        _create_review_branch(gitdir, 'multi-1', identifier='gate-take', revision=2)
+        _seed_multiver('gate-take')
+        conn = tracking.get_db('gate-take')
+        tracking.update_series_status(conn, 'multi-1', 'reviewing', revision=2)
+        conn.close()
+
+        app = TrackingApp('gate-take')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert app.check_action('take', ()) is True
+            assert app.check_action('rebase', ()) is True
+            await pilot.press('x')
+            await pilot.pause()
+            # Cursor onto v1 -- not the tracked v2.
+            await pilot.press('j')
+            await pilot.pause()
+            assert _selected_rev(app) is not None
+            assert app.check_action('take', ()) is False
+            assert app.check_action('rebase', ()) is False
+            # ...and the action menu drops them for the same row.
+            await pilot.press('a')
+            await pilot.pause()
+            assert isinstance(app.screen, ActionScreen)
+            lv = app.screen.query_one('#action-list', ListView)
+            from b4.review_tui._modals import ActionItem
+
+            offered = [c.key for c in lv.children if isinstance(c, ActionItem)]
+            assert 'take' not in offered
+            assert 'rebase' not in offered
+            # An action that does not touch the branch is still there.
+            assert 'snooze' in offered
+            await pilot.press('escape')
+
+
+class TestThreadViewLeavesNoStaleFocus:
+    """Viewing a version's thread must not capture a later reload.
+
+    _stash_focus() is a hint for the *next* _refresh_list(), and every
+    other caller reloads immediately.  action_thread() instead pushes a
+    screen and returns, so the hint outlives the action -- and re-reading
+    an already-read thread writes nothing, leaving the DB mtime alone and
+    _check_db_changed() asleep, so nothing consumes it either.  The next
+    reload from an unrelated action then parks the cursor on the version
+    row the maintainer looked at, arming _selected_revision behind their
+    back.
+    """
+
+    @pytest.mark.asyncio
+    async def test_a_viewed_version_does_not_capture_a_later_reload(
+        self, tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from textual.screen import ModalScreen
+
+        class _StubThreadScreen(ModalScreen[None]):
+            """Stands in for LiteThreadScreen: pushes and pops, no fetch."""
+
+            def __init__(self, *args: Any, **kwargs: Any) -> None:
+                super().__init__()
+
+        monkeypatch.setattr(
+            'b4.review_tui._lite_app.LiteThreadScreen', _StubThreadScreen
+        )
+        # Re-reading a thread whose counts have not moved writes nothing, so
+        # in the real flow the mtime poller stays asleep and never reloads.
+        # The startup rescan does touch the DB here, so pin the poller off
+        # rather than race its one-second timer.
+        monkeypatch.setattr(TrackingApp, '_check_db_changed', lambda self: None)
+
+        # Seeded oldest-first: the list sorts newest-tracked first, so
+        # 'multi-b' heads the list and 'multi-a' follows it.
+        _seed_multiver('thread-focus', change_id='multi-a')
+        _seed_multiver('thread-focus', change_id='multi-b')
+
+        app = TrackingApp('thread-focus')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            items = _list_items(app)
+            assert [i.series['change_id'] for i in items] == ['multi-b', 'multi-a']
+
+            # Expand 'multi-a' and put the cursor on its v1 row.
+            await pilot.press('j')
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.pause()
+            on_child = app._selected_revision
+            assert on_child is not None
+            assert on_child['revision'] == 1
+
+            # View that version's thread and come back.  Nothing about the
+            # thread changed, so no reload happens on the way out.
+            depth = len(app.screen_stack)
+            app.action_thread()
+            await pilot.pause()
+            assert len(app.screen_stack) == depth + 1
+            app.pop_screen()
+            await pilot.pause()
+
+            # The hint must not outlive the action that set it.
+            assert app._focus_change_id is None
+            assert app._focus_revision is None
+
+            # Navigate back up to 'multi-b' and abandon it -- a reload that
+            # deliberately does not stash a focus of its own.
+            await pilot.press('k')
+            await pilot.press('k')
+            await pilot.pause()
+            selected = app._selected_series
+            assert selected is not None
+            assert selected['change_id'] == 'multi-b'
+
+            app._on_abandon_confirmed(True, 'multi-b', 'b4/review/multi-b', False)
+            await pilot.pause()
+
+            # The cursor lands on a series row, not on the version row that
+            # was looked at three actions ago.
+            lv = app.query_one('#tracking-list', ListView)
+            landed = lv.highlighted_child
+            assert isinstance(landed, TrackedSeriesItem)
+            assert app._selected_revision is None
+
+
+class TestExpandAllWithoutASelection:
+    """[X] needs no selection, so it must not restore by row index.
+
+    _stash_focus() records a hint only when something is selected, and
+    expanding is precisely the operation that inserts rows above the
+    cursor -- so the index fallback lands somewhere unrelated.
+    """
+
+    @pytest.mark.asyncio
+    async def test_expand_all_keeps_the_highlighted_series(
+        self, tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # The mtime poller re-stashes and reloads on its own timer; pin it
+        # off so this exercises [X]'s restore and not a race with it.
+        monkeypatch.setattr(TrackingApp, '_check_db_changed', lambda self: None)
+
+        # Display order is newest-tracked first: multi-c, multi-b, multi-a.
+        for change_id in ('multi-a', 'multi-b', 'multi-c'):
+            _seed_multiver('expand-nosel', change_id=change_id)
+
+        app = TrackingApp('expand-nosel')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            assert [i.series['change_id'] for i in _list_items(app)] == [
+                'multi-c',
+                'multi-b',
+                'multi-a',
+            ]
+
+            # Put the cursor on the last row, away from index 0.
+            await pilot.press('j')
+            await pilot.press('j')
+            await pilot.pause()
+            selected = app._selected_series
+            assert selected is not None
+            target = selected['change_id']
+            assert target == 'multi-a'
+
+            # Close the details panel: the selection goes, the cursor stays.
+            await pilot.press('escape')
+            await pilot.pause()
+            assert app._selected_series is None
+
+            await pilot.press('X')
+            await pilot.pause()
+            assert len(_list_items(app)) == 12  # 3 parents + 3 versions each
+
+            # Still the same series, and still its parent row.
+            lv = app.query_one('#tracking-list', ListView)
+            landed = lv.highlighted_child
+            assert isinstance(landed, TrackedSeriesItem)
+            assert landed.series['change_id'] == target
+            assert app._selected_revision is None
+
+
+class TestTargetBranchKeepsTheVersionRow:
+    """Setting a target branch must not repaint the panel for another row.
+
+    [t] acts on the series whichever row the cursor is on, which is fine
+    -- but its callback refreshes the details panel without saying which
+    version the cursor is sitting on, so the panel silently reverts to
+    the tracked revision while the cursor visibly stays on the child row.
+    """
+
+    @pytest.mark.asyncio
+    async def test_setting_a_target_keeps_the_panel_on_the_version_row(
+        self, tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # The mtime poller would reload and repaint on its own timer; pin
+        # it off so this pins the callback's own behaviour.
+        monkeypatch.setattr(TrackingApp, '_check_db_changed', lambda self: None)
+        _seed_multiver('target-version-row')
+
+        app = TrackingApp('target-version-row')
+        async with app.run_test(size=(120, 30)) as pilot:
+            await pilot.pause()
+            await pilot.press('x')
+            await pilot.pause()
+            await pilot.press('j')
+            await pilot.pause()
+            on_child = app._selected_revision
+            assert on_child is not None
+            assert on_child['revision'] == 1
+            assert _version_row_shown(app)
+
+            app._on_target_branch_set('sound/for-next')
+            await pilot.pause()
+
+            # The cursor never moved, so the panel must still describe the
+            # version it is on.
+            still_on = app._selected_revision
+            assert still_on is not None
+            assert still_on['revision'] == 1
+            assert _version_row_shown(app)
Signature · 1 line
2.53.0