feat(review): re-read an open Needs review page when its queue changes

An open Needs review page now follows the queue without polling. A new
server-sent event stream, GET /prompt_manager/review/events, sends
"ready" when it opens and "change" after every committed queue change:
an item the scan or the monitor recorded, a spelling refresh, a decision
from any tab, and a restore. database/review_changes.py notifies after
the commit from whichever thread wrote it. The page re-reads its first
page on each event, keeps the open item, its choice and an unanswered
decision, and re-reads the SAVED VIEWS count with it. When the open item
left the queue, the next one opens with a note. A keepalive comment
every 25 s lets the server drop a closed tab; shutdown ends every stream.

Leaving the page mid-decision now releases that decision's capture.

D-NEW-F1 is renumbered D119 in markers and TESTING.md.

database/review.py

@@ -31,6 +31,7 @@ from .annotation_schema import (
 )
 from .annotations import _new_id, _validate_locator, _validate_target
 from .models import normalize_image_path, utc_now_iso
+from .review_changes import notify_review_change
 from .review_schema import (
     ITEMS_TABLE,
     MAX_CANDIDATES,
@@ -286,7 +287,9 @@ class ReviewOperations:
             refreshed = _refresh_spelling(conn, locator, spelled_path)
             if inserted or refreshed:
                 conn.execute(_BUMP_REVIEW_INDEX)
-            return inserted
+        if inserted or refreshed:
+            notify_review_change(self.model.db_path)
+        return inserted
 
     def refresh_review_spelling(self, locator: str, spelled_path: str) -> bool:
         """Record ``spelled_path`` as the spelling of every item at ``locator``.
@@ -303,7 +306,9 @@ class ReviewOperations:
             refreshed = _refresh_spelling(conn, locator, spelled_path)
             if refreshed:
                 conn.execute(_BUMP_REVIEW_INDEX)
-            return refreshed
+        if refreshed:
+            notify_review_change(self.model.db_path)
+        return refreshed
 
     def review_index_revision(self) -> int:
         """The queue's revision (moved by every queue change)."""

database/review_changes.py

@@ -0,0 +1,64 @@
+"""Needs review queue change notices (#249 PR F2).
+
+Every committed change to the pending queue (an item recorded by the scan or
+the monitor, a spelling refresh, a decision) calls ``notify_review_change``
+after its transaction, from whichever thread wrote it. The review event
+stream (``py/api/review_events.py``) subscribes, so an open Needs review page
+re-reads its queue when it changes instead of polling. Observers are keyed by
+the database file, like ``subscribe_history_restore``; an observer that fails
+is logged and never fails the write.
+"""
+
+import os
+import threading
+from typing import Callable
+
+try:
+    from ..utils.logging_config import get_logger
+except ImportError:
+    from utils.logging_config import get_logger
+
+_logger = get_logger("prompt_manager.database.review_changes")
+_lock = threading.Lock()
+_observers: dict[str, dict[object, Callable[[], None]]] = {}
+
+
+def _identity(db_path: str) -> str:
+    return os.path.normcase(os.path.realpath(db_path))
+
+
+def subscribe_review_changes(
+    db_path: str, callback: Callable[[], None]
+) -> Callable[[], None]:
+    """Call ``callback()`` after each committed queue change; return the unsubscribe."""
+    identity = _identity(db_path)
+    token = object()
+    with _lock:
+        _observers.setdefault(identity, {})[token] = callback
+
+    def unsubscribe() -> None:
+        with _lock:
+            observers = _observers.get(identity)
+            if observers is not None:
+                observers.pop(token, None)
+                if not observers:
+                    _observers.pop(identity, None)
+
+    return unsubscribe
+
+
+def observer_count(db_path: str) -> int:
+    """How many observers watch ``db_path`` (tests and diagnostics)."""
+    with _lock:
+        return len(_observers.get(_identity(db_path), {}))
+
+
+def notify_review_change(db_path: str) -> None:
+    """Tell every observer of ``db_path``; call it after the commit."""
+    with _lock:
+        callbacks = tuple(_observers.get(_identity(db_path), {}).values())
+    for callback in callbacks:
+        try:
+            callback()
+        except Exception:
+            _logger.warning("Needs review change observer failed", exc_info=True)

database/review_decisions.py

@@ -29,6 +29,7 @@ from .review import (
     dependent_images,
     same_name_rows,
 )
+from .review_changes import notify_review_change
 from .review_schema import DECISIONS_TABLE, ITEMS_TABLE, canonical_evidence
 
 DECISION_KIND = "user-selection"
@@ -119,7 +120,7 @@ class ReviewDecisionOperations:
             raise ValueError("A selected decision needs a candidate and a file")
         try:
             with self._pair_transaction() as conn:
-                return self._decide_in(
+                decided = self._decide_in(
                     conn,
                     item_id=item_id,
                     expected_epoch=expected_epoch,
@@ -135,6 +136,9 @@ class ReviewDecisionOperations:
                 )
         except _Rollback as rollback:
             raise rollback.error from None
+        # After the commit: open Needs review pages re-read their queue.
+        notify_review_change(self.model.db_path)
+        return decided
 
     def _decide_in(self, conn: sqlite3.Connection, **command) -> dict:
         epoch = self._library_epoch(conn, command["expected_epoch"])