feat(plex): Phase B — Siftlode→Plex watch-state push

Mirror watched/unwatched/resume from Siftlode to a linked (owner) Plex account.

- PlexClient: scrobble / unscrobble / set_timeline (/:/scrobble, /:/unscrobble, /:/timeline).
- watch_sync: link_for_push() gates on owner + sync_enabled + initial_import_done; best-effort
  push_state_to_plex() runs as a background task with its own session, never raises (Plex being
  down must not break the user's action), and flips synced_to_plex on success so Phase C's pull
  won't bounce it back.
- item_state / item_progress schedule the push: watched/unwatched immediately, resume only on a
  "final" checkpoint (pause / pagehide / unmount) — not every 10s tick — so one watch doesn't spray
  /:/timeline at the server. `hidden` is Siftlode-only and never touches Plex.
- Frontend: plexProgress / plexProgressBeacon carry a `final` flag; the periodic checkpoint is
  non-final, pause/pagehide/leaving the player are final.

Verified live against the real Plex server (scrobble/unscrobble/timeline round-trip + restore;
link gating; synced_to_plex flip).

backend/app/routes/plex.py

@@ -16,7 +16,7 @@ from pathlib import Path
 from urllib.parse import quote
 
 import httpx
-from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query, Request, Response
 from fastapi.responses import FileResponse
 from sqlalchemy import and_, func, or_, text
 from sqlalchemy.orm import Session, aliased
@@ -1486,22 +1486,49 @@ def item_detail(
     }
 
 
+def _push_watch(
+    background: BackgroundTasks,
+    db: Session,
+    user_id: int,
+    item_id: int,
+    rating_key: str,
+    action: str,
+    time_ms: int = 0,
+    duration_ms: int = 0,
+) -> None:
+    """Schedule a best-effort Siftlode→Plex watch push, but only for a user whose owner link has
+    push enabled — non-owner users never touch Plex. Guarding here (with the request session) avoids
+    spinning up a throwaway background session on every state change for the common no-link case."""
+    if plex_watch.link_for_push(db, user_id) is None:
+        return
+    background.add_task(
+        plex_watch.push_state_to_plex, user_id, item_id, rating_key, action, time_ms, duration_ms
+    )
+
+
 @router.post("/item/{rating_key}/progress")
 def item_progress(
     rating_key: str,
     payload: dict,
+    background: BackgroundTasks,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Checkpoint the resume position while playing (near the end → mark watched + clear it)."""
+    """Checkpoint the resume position while playing (near the end → mark watched + clear it).
+
+    `final` (sent on the pause/pagehide/unmount flush, not the periodic 10s checkpoint) is what
+    debounces the Plex resume push: we mirror the settled position to Plex only on a final flush, so
+    a single watch doesn't spray `/:/timeline` calls at the server every 10 seconds."""
     it = _item_or_404(db, rating_key)
     try:
         position = max(0, int(payload.get("position_seconds") or 0))
         duration = int(payload.get("duration_seconds") or 0)
     except (TypeError, ValueError):
         raise HTTPException(status_code=400, detail="position_seconds must be an integer")
+    final = bool(payload.get("final"))
     now = datetime.now(timezone.utc)
     st = db.query(PlexState).filter_by(user_id=user.id, item_id=it.id).first()
+    was_watched = st is not None and st.status == "watched"
 
     near_end = duration > 0 and position > duration - _FINISH_MARGIN_S
     if near_end:
@@ -1512,7 +1539,12 @@ def item_progress(
         st.watched_at = now
         st.position_seconds = 0
         st.progress_updated_at = now
+        st.synced_to_plex = False
         db.commit()
+        # Immediate on the watched transition; skip a repeat scrobble if it was already watched
+        # (a later checkpoint of the same finished item would otherwise bump Plex's viewCount again).
+        if not was_watched:
+            _push_watch(background, db, user.id, it.id, rating_key, "watched")
         return {"status": "watched", "position_seconds": 0}
 
     if position < _PROGRESS_MIN_S:
@@ -1529,7 +1561,13 @@ def item_progress(
         db.add(st)
     st.position_seconds = position
     st.progress_updated_at = now
+    if final:
+        st.synced_to_plex = False
     db.commit()
+    if final:
+        _push_watch(
+            background, db, user.id, it.id, rating_key, "resume", position * 1000, duration * 1000
+        )
     return {"position_seconds": position}
 
 
@@ -1537,19 +1575,25 @@ def item_progress(
 def item_state(
     rating_key: str,
     payload: dict,
+    background: BackgroundTasks,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Set the per-user watch status (new|watched|hidden)."""
+    """Set the per-user watch status (new|watched|hidden). watched→scrobble / →new→unscrobble push
+    to a linked Plex account immediately; `hidden` is a Siftlode-only concept with no Plex analogue,
+    so it never touches Plex."""
     it = _item_or_404(db, rating_key)
     status = payload.get("status")
     if status not in ("new", "watched", "hidden"):
         raise HTTPException(status_code=400, detail="Invalid status")
     st = db.query(PlexState).filter_by(user_id=user.id, item_id=it.id).first()
+    prev_status = st.status if st is not None else "new"
     if status == "new":
         if st is not None:
             db.delete(st)
             db.commit()
+        if prev_status != "new":  # something → unwatched: mirror the un-mark to Plex
+            _push_watch(background, db, user.id, it.id, rating_key, "unwatched")
         return {"status": "new"}
     if st is None:
         st = PlexState(user_id=user.id, item_id=it.id)
@@ -1558,7 +1602,10 @@ def item_state(
     if status == "watched":
         st.watched_at = datetime.now(timezone.utc)
         st.position_seconds = 0
+    st.synced_to_plex = False
     db.commit()
+    if status == "watched" and prev_status != "watched":
+        _push_watch(background, db, user.id, it.id, rating_key, "watched")
     return {"status": status}