scripts/media-refresh-jellyfin.py

@@ -7,7 +7,8 @@
 
 `status` answers {"scan": true, "taskState": "Running", "recentMedia": 17}: the
 Scan Media Library row plus the rows the database has taken in recently; with
-`--after` (a journal mtime) it also answers `scannedAfter` and exits non-zero
+`--after` (the trigger's epoch — a file mtime is already passed by an earlier scan) it
+also answers `scannedAfter` and exits non-zero
 while the last finished scan predates it. `wait` calls the library settled only
 on the page's law: a sighting of the task Running — or a run that finished while
 it watched, or a `--after` the task already passes — and THEN `--require-quiet`
@@ -140,8 +141,8 @@ def main() -> None:
     ap.add_argument("--require-quiet", type=int, default=3,
                     help="wait: consecutive quiet reads before the library counts as settled")
     ap.add_argument("--after", type=float, default=None,
-                    help="status/wait: an epoch (a journal mtime) the scan must have "
-                         "finished after; status exits non-zero while it has not")
+                    help="status/wait: an epoch the scan must have finished after — pass "
+                         "the trigger's, not a file mtime an earlier scan already passes")
     ap.add_argument("--start-window", type=float, default=120.0,
                     help="wait: seconds to allow the scan to start before reporting "
                          "that the 204 queued nothing")

scripts/media-refresh-plex.sh

@@ -23,7 +23,10 @@
 # Progress needs no token and no container: `section_locations.scanned_at` in
 # the library database is the same epoch the API prints as `scannedAt`
 # (verified 2026-11-04), so `status` reads the database and compares it against
-# --after. `trigger` answering 000 means PMS is still warming — retry, never
+# --after — which makes it a census of the last RECORDED scan, never a waiter: PMS
+# stamps that epoch when it accepts the request, so the door answers `settled` in the
+# same second its own `trigger` ran (measured 2026-11-04; no epoch survives it).
+# `trigger` answering 000 means PMS is still warming — retry, never
 # restart the service over it. Proof that a rename actually landed is
 # scripts/media-verify.py replaying the journal; this script only moves the
 # scanner along.