docs(plex): --after takes the trigger's epoch; a file mtime reports a false settle

The page's own example passed the journal mtime. Measured 2026-11-04: a chain
using it fell straight through its wait loop, because status only asks whether
the section has scanned since that epoch and the section had been walked earlier
the same day. The verify that followed read a database that had not yet processed
that day's renames — a false success, which is the direction that gets believed.
This commit is contained in:
dank committed 2026-11-04 12:17:20 -08:00
1 parent 0161ab2aa8
commit b82655d30a
1 file changed
+12 -1
+12 -1
View File
@@ -111,8 +111,9 @@ driver from the host shell; the section keys are `1` Movies, `3` TV Shows,
`5` Audiobooks, `6` Music, `11` VODs & Live Events:
```bash
after="$(date +%s)" # the TRIGGER's epoch — never a file mtime
scripts/media-refresh-plex.sh trigger --library 1
scripts/media-refresh-plex.sh status --library 1 --after "$(stat -c %Y <journal>)"
scripts/media-refresh-plex.sh status --library 1 --after "$after"
```
Exactly ONE section: a refresh costs a full walk of that tree, and refreshing all
@@ -124,6 +125,16 @@ the library database carries the same epoch `GET /library/sections` prints as
`scannedAt` (verified 2026-11-04), and that is what `status` compares `--after`
against.
**The epoch `--after` receives must be the trigger's, not a file's.** `status` answers
one question — has this section scanned since that epoch — so any journal or plan whose
mtime predates the most recent scan makes it report settled the instant you ask.
Measured 2026-11-04: a chain that passed `stat -c %Y <journal>` fell straight through
its wait loop and the verify after it read a database that had not yet processed that
day's renames. The failure mode is a false *success*, never a false alarm, which is
what makes it worth two lines of warning. A purge gate survives it —
`scripts/media-verify.py` asks whether any row still points at a path with no file, and
a scan can clear rows but cannot invent one — but a "the scan is done" claim does not.
The driver ships its runner into the container with `podman cp` rather than
quoting a command through `podman exec sh -c`, because PMS's HTTPD closes without
a single byte on a request that arrives from another netns — the host address and