From 8f2c3bb378b1cce8cf739a538f88bdd5b1d8312c Mon Sep 17 00:00:00 2001
From: dank <dank@dankclaw.local>
Date: Wed, 4 Nov 2026 12:24:56 -0800
Subject: [PATCH] docs(scripts): --after names the trigger's epoch, never a
 file mtime

Both drivers' help text recommended `--after "$(stat -c %Y <journal>)"`. Measured
2026-11-04 that epoch is answered by whatever scan finished before the question was
asked: on Jellyfin it reads an earlier task's EndTimeUtc, and the Plex door cannot be
a waiter at all, since PMS stamps section_locations.scanned_at when it accepts the
request. The laws are on the vault pages (main 146c28d); this puts the warning at
point of use, in the text an agent reads before calling the door.
---
 scripts/media-refresh-jellyfin.py | 7 ++++---
 scripts/media-refresh-plex.sh     | 5 ++++-
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/scripts/media-refresh-jellyfin.py b/scripts/media-refresh-jellyfin.py
index 0f17280..e5906ba 100755
--- a/scripts/media-refresh-jellyfin.py
+++ b/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")
diff --git a/scripts/media-refresh-plex.sh b/scripts/media-refresh-plex.sh
index d797500..bba4e30 100755
--- a/scripts/media-refresh-plex.sh
+++ b/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.