release: 0.92.0 (improvement/debt-burn)

Round 2 of the deep review:
- A click on, or a key typed into, the focus keeper's stand-in fires no focusin, so a restore still
  polling for its list could take the focus from under the reader. A pointerdown or keydown now
  makes it the reader's own focus.
- The Jump-to pill hid its "Ctrl K" from its name (the voice command "click Ctrl K" still matched
  nothing); the key cap's tooltip now equals its name, so it is not read twice as a description.
- listNav's comment still cited DataTable's two layouts as the reason for its visibility filter.

CHANGELOG.md

@@ -7,6 +7,97 @@ edit the release notes and re-run the generator.
 
 Upgrading, pinning a version and rolling back: [docs/self-hosting.md](docs/self-hosting.md#upgrading).
 
+## 0.92.0 — 2026-09-19
+
+A debt burn: every item the roadmap had deferred is done or dropped — Plex playback per viewer, refusals said in your language, controls that keep the keyboard focus, and a screen reader that hears Hungarian.
+
+### Features
+
+- The command palette has a visible way in: a Ctrl K key cap in the header's search field, and a “Jump to…” pill on pages without one.
+- The Playlists rail says, under “Missing a list? Why?”, which lists YouTube's API does not hand out (Watch later, History, lists saved from other channels).
+- The last native drop-downs are the app's own controls: the live search's result count, rows per page, a download format's content, audio format and quality, and the download dialog's format.
+- Plex plays one session per viewer, so two accounts can watch the same film at once; an administrator sets the ceiling on concurrent sessions (Configuration → Plex).
+
+### Fixes
+
+- A YouTube action YouTube refuses says what to do — wait for tomorrow's quota, reconnect the account, or try again later — instead of a server error; a passing Google hiccup no longer asks you to reconnect.
+- Every refusal the server gives is said in your language, and every label a screen reader or tooltip reads is translated.
+- Dragging to reorder a list is announced in your language and with the right position, and a Plex playlist keeps a drag within the list it started in.
+- A button that turns itself off, or a row that removes itself, leaves the keyboard focus where it was; Back from a Plex title returns the focus to the tile you opened, even after using a button there.
+- With Plex turned off, the Home shelf shows your YouTube pins only, and reordering it leaves the hidden Plex pins in their places; two reorders at once can no longer put two pins on one slot.
+- The Home hero from a pinned show offers to unpin the show, and “Surprise me” from the command palette really asks for a surprise.
+- A finished Plex title scrobbles once and gets no resume point pushed after it; a subtitle pass that stalled resumes instead of starting over.
+- Tables keep their j/k keys after the window is resized across the phone breakpoint, and boxes grow with the text-size setting.
+- Whitelisting an address and activating its account happen in one step, and the audit log names the entry.
+
+### Internal
+
+- Every mutation answers `ok`, and route helpers leave the commit to the request — both held by tests; a request that leaves a write uncommitted now fails its test.
+- New lint rules and contracts: no native select, no hover that ignores aria-disabled, no untranslated accessible text, no unused translation key.
+- Two adversarial review rounds at the epic's end: 23 findings, all fixed, each regression test proven to fail with its own fix removed.
+
+## 0.91.0 — 2026-09-19
+
+What a test run on the live instance turned up, fixed: new videos keep arriving while YouTube's feeds are down, an open tab survives a release, and Back returns to what you left.
+
+### Features
+
+- A card's menu (right-click or long press) now offers the card's own actions — watched, save, hide, reset — beside the comfort-shelf pin.
+- Settings → Account shows your role and your last sign-in. 0.88 announced the last sign-in in your account panel; it is actually there now.
+
+### Fixes
+
+- When YouTube's feed for a channel stays dark for hours, as it did for 393 of 396 channels on 18–19 September, the channel's newest uploads are read through the YouTube API instead, at most once every 2 hours per channel (adjustable by an administrator, 0 turns it off).
+- A tab left open across a release no longer falls to the crash screen when it opens something it had not loaded yet: it reloads onto the new version once.
+- Back from a request's lines in the Server log returns to the view the pivot was made from, search text included, as 0.90 promised.
+- Back to Home keeps the question you asked (the time budget and the hero you rerolled to), and the keyboard lands on the card you opened, even when the rail's cards moved or several share a name.
+- Browser tabs are named after the page again: signed out, and on the privacy and terms pages.
+- On a phone, the feed and Plex toolbars wrap instead of running past the edge, and so do notifications.
+- The countdown of a raised diagnostics level counts from the moment it was raised, not from when the page was opened.
+- The download box's placeholder names every site it takes, Facebook included.
+
+### Internal
+
+- The screens' own polling reads (the unread badges, the download list, the scheduler) are logged at debug level in the server's log and in the browser's copy of it, where they made up about 95% of the lines.
+- An account with no YouTube channel no longer writes a warning every six hours, and a scheduler job that fails carries an event code.
+- Two adversarial review rounds: 15 findings raised, 11 survived, all fixed, and every regression test was proven to fail with its own fix removed.
+
+## 0.90.0 — 2026-09-19
+
+The server's log gets a screen of its own: an admin can now read what the API, the downloader and the browsers wrote down, filter it, and follow one request or job from start to end.
+
+### Features
+
+- Admin → Server log: the stored log, newest first, with a search, level chips, and source, account, event and period filters. A line opens in place to its full record; its request id or job id narrows the list to everything that request or job wrote.
+- Filters live in the address bar, so a filtered view is a link, and Back brings the previous view back.
+- Live follows the newest lines every few seconds; Copy puts the loaded lines on the clipboard, oldest first. A failed read says so instead of quietly freezing the list.
+- Both log viewers (Server log and My log) can be walked with j/k and a line opened with Enter.
+
+### Fixes
+
+- New videos no longer arrive late from channels whose YouTube feed answers 404 or 500 now and then: a feed is tried again before the channel counts as failed.
+- A % or _ typed into a search is searched for as itself, not as a wildcard.
+
+### Internal
+
+- The console's own reads are logged at debug level, so watching the log does not fill it.
+- Two adversarial review rounds: 19 findings raised, 12 survived, all fixed, and every regression test was proven to fail with its own fix removed.
+
+## 0.89.0 — 2026-09-19
+
+A release for the log rather than for the screen: what the server writes down when something fails is now complete, said once, and free of what you downloaded or searched for.
+
+### Fixes
+
+- A download that failed because the server lost its database for a moment no longer shows the video's title and file path inside the database's own error message.
+
+### Internal
+
+- No log line carries what a person typed, watched or downloaded: search terms, titles, channel names, file paths, links and video ids are taken out — also from yt-dlp's and ffmpeg's own text, from error stacks, and from database errors. The one exception is Full diagnostics, and only under the user's own consent.
+- Every one of the backend's 114 swallowed exceptions was ruled on: 44 now leave a line with an event code, the other 70 say in the code why they need none — and a test keeps it that way. A failure is logged once, with its stack when it is our own bug, and a stalled or killed download no longer fails without a line.
+- yt-dlp's own explanations (“Requested format is not available”, a sign-in wall) reach the log instead of a stdout nobody read, and a burst of identical lines is summarised instead of flooding the stored log.
+- Three adversarial review rounds: 49 findings raised, 42 survived three independent attempts to refute them, all fixed, and every regression test was proven to fail with its own fix removed.
+
 ## 0.88.0 — 2026-09-18
 
 When something goes wrong, you can now turn on detailed logging for yourself for 24 hours — and read your own log on the spot, before any of it is sent anywhere. Siftlode also has a privacy policy and terms at last, in both languages, saying exactly what is recorded and for how long.

CLAUDE.md

@@ -82,8 +82,8 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 | Admin gate import       | `app.auth`                                                   | the `app.routes.admin` re-export                       |
 | Upstream failure status | `422` with JSON detail                                       | `502` (reserve 502 for raw byte-proxies)               |
 | User-facing error       | structured `detail` (`{code, reason}`)                       | a bare English string under a bilingual UI             |
-| Mutation response       | `{"ok": true, …}` (`{"deleted": id}`)                        | ad-hoc `{"unsubscribed"}`/`{"cleared": n}`/echo        |
-| Transaction commit      | the handler/job-wrapper commits; helpers `flush`             | helpers that commit (only `quota` owns its session)    |
+| Mutation response       | `{"ok": true, …}` (`{"deleted": id}`), test-held             | a bare `{"unsubscribed"}`/`{"cleared": n}`, no `ok`    |
+| Transaction commit      | the handler commits; helpers `flush` (test-held list)        | helpers that commit (only `quota` owns its session)    |
 | Admin knob storage      | `sysconfig` (values)                                         | env / `app_state` / `scheduler_settings` scatter       |
 | Job status word         | the `downloads/status.py` StrEnum                            | loose `"canceled"`/`"cancelled"` literals              |
 | Current time            | inline `datetime.now(timezone.utc)`                          | new `now_utc`/`_now` helpers                           |
@@ -92,7 +92,7 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 | FE keyboard shortcut    | a row in `lib/keymap.ts` + `dispatch()`                      | a private `keydown` listener with its own key literals |
 | FE list/grid keys       | `NavGrid`/`keyboardNav` + `navItemAttrs` + `data-nav-open`   | a private arrow-key / roving-tabindex handler          |
 | FE view push (history)  | `rememberNavPosition()` right before `history.pushState`     | a push that forgets: Back strands focus on `<body>`    |
-| FE control              | the chip/segmented primitives (`Select` only for >6 options) | a native `<select>`                                    |
+| FE control              | `SegmentedToggle`; a long or user's list: `FilterSelect`     | a native `<select>` (lint-enforced)                    |
 | FE loading/empty/error  | `QueryState` / `StateMessage`                                | ad-hoc conditionals                                    |
 | FE failed write         | `meta.failTitle`, else `notifyActionError(err, title)`       | a bare `catch {}` or `notify()` with no error attached |
 | FE network call         | `req`/`uploadReq`/`beacon`, or `lib/http.ts` `send` (public pages) | a bare `fetch`/`XMLHttpRequest`/`WebSocket` (lint-enforced) |

VERSION

@@ -1 +1 @@
-0.88.0
+0.92.0

backend/alembic/versions/0088_channels_feed_fallback_at.py

@@ -0,0 +1,30 @@
+"""add channels.feed_fallback_at — when a channel's uploads were last read through the API because
+its RSS feed would not answer
+
+Revision ID: 0088_channels_feed_fallback_at
+Revises: 0087_users_diagnostics_level
+Create Date: 2026-09-19
+
+YouTube's RSS feeds go dark for hours at a time, per channel (2026-09-18/19: 393 of 396 answered 404
+for four hours; the same channel answers 404 to every retry). The RSS poll then reads the newest
+uploads through the Data API instead, at a quota cost, and at most once per `rss_fallback_hours` per
+channel: this column is that clock. NULL = never needed it.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0088_channels_feed_fallback_at"
+down_revision: str | None = "0087_users_diagnostics_level"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "channels", sa.Column("feed_fallback_at", sa.DateTime(timezone=True), nullable=True)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("channels", "feed_fallback_at")

backend/app/auth.py

@@ -1,5 +1,3 @@
-import logging
-
 import httpx
 from fastapi import BackgroundTasks, Depends, HTTPException, Request
 from sqlalchemy import delete, func, select
@@ -16,6 +14,7 @@ from app.db import get_db
 from app.models import Invite, LogEvent, User
 from app.security import decrypt_optional
 from app.utils import canonical_email
+from app.refusal import refused
 
 PASSWORD_MIN_LEN = 10
 
@@ -39,7 +38,7 @@ READ_SCOPES = f"{BASE_SCOPES} {READ_SCOPE}"
 WRITE_SCOPES = f"{BASE_SCOPES} {READ_SCOPE} {WRITE_SCOPE}"
 _YOUTUBE_SCOPES = frozenset({READ_SCOPE, WRITE_SCOPE})
 
-log = logging.getLogger("siftlode.auth")
+log = logs.get_logger(__name__)
 
 
 def google_enabled(db: Session) -> bool:
@@ -222,7 +221,7 @@ def revoke_google_token(token: str | None) -> None:
             timeout=10,
         )
         log.info("Google token revoke: status=%s", resp.status_code)
-    except Exception:
+    except Exception:  # noqa: BLE001 — a revoke we cannot make must not fail the sign-out
         log.warning("Google token revoke failed", exc_info=True)
 
 
@@ -305,6 +304,13 @@ def resolved_user_id(conn: HTTPConnection, *, strict: bool = True) -> tuple[int
         try:
             hid = int(hdr)
         except ValueError:
+            # Under `strict` this becomes a 401 and the tab authenticates as nobody, which reads
+            # in the browser exactly like a session that expired. The value itself stays out —
+            # it came from a request, and `wallet` says which accounts were actually on offer.
+            log.debug(
+                "the active-account header could not be read as an id",
+                extra=logs.event("auth.account_header.invalid", accounts=len(wallet)),
+            )
             hid = None
         if hid is not None and hid in wallet:
             return hid, hid == default_id
@@ -336,19 +342,19 @@ def current_user(request: Request, db: Session = Depends(get_db)) -> User:
 
 def _session_user(request: Request, db: Session, user_id: int | None, is_default: bool) -> User:
     if not user_id:
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        raise refused(401, "not_authenticated")
     user = db.get(User, user_id)
     if user is None or not user.is_active or user.is_suspended:
         # Suspended/deactivated mid-session → end it so the block takes effect at once.
         _end_account_session(request, user_id, is_default)
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        raise refused(401, "not_authenticated")
     # SA4: reject a cookie whose recorded epoch is behind the account's current one (revoked by a
     # password reset/change or "log out everywhere"). A cookie with no recorded epoch (pre-SA4, or an
     # account signed in before this shipped) is treated as epoch 0 — so the FIRST bump revokes it too.
     epochs = request.session.get("epochs") or {}
     if int(epochs.get(str(user_id), 0)) != (user.session_epoch or 0):
         _end_account_session(request, user_id, is_default)
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        raise refused(401, "not_authenticated")
     # Always keep the session default in the switchable list — covers sessions created before
     # multi-session existed (their account_ids was never seeded), so the switcher isn't empty.
     default_id = request.session.get("user_id")
@@ -376,12 +382,20 @@ def optional_current_user(request: Request, db: Session = Depends(get_db)) -> Us
     user_id, is_default = resolved_user_id(request, strict=False)
     try:
         return _session_user(request, db, user_id, is_default)
+    # silent-ok: this is the anonymous case as much as the refused one — every landing page hit
+    # comes through here. The second attempt below is the handling, and it reports.
     except HTTPException:
         if is_default:
             return None
     try:
         return _session_user(request, db, *resolved_user_id(request, strict=False))
     except HTTPException:
+        # Both the pinned account AND the default one were refused, so the tab is signed out
+        # without being told why — and it got here from a session that named a real account.
+        log.info(
+            "a session was resolved to nobody: neither the named nor the default account held",
+            extra=logs.event("auth.session.probe_rejected", user_id=user_id),
+        )
         return None
 
 
@@ -405,10 +419,7 @@ def require_write_scope(user: User = Depends(require_human)) -> User:
     checks that had drifted into three different 403 messages across channels/playlists. Layers on
     `require_human` because writing to YouTube needs a real, non-demo identity."""
     if not has_write_scope(user):
-        raise HTTPException(
-            status_code=403,
-            detail="Enable YouTube editing in Settings first.",
-        )
+        raise refused(403, "youtube_editing_off")
     return user
 
 
@@ -416,7 +427,7 @@ def admin_user(user: User = Depends(current_user)) -> User:
     """Dependency: require the signed-in user to be an admin. Single source of truth for the
     admin gate — every admin route/action depends on this rather than re-checking the role."""
     if user.role != "admin":
-        raise HTTPException(status_code=403, detail="Admin only")
+        raise refused(403, "admin_only")
     return user
 
 

backend/app/config.py

@@ -16,6 +16,8 @@ def _version_from_file() -> str:
             v = p.read_text(encoding="utf-8").strip()
             if v:
                 return v
+        # silent-ok: this runs at import, and `app.logs` imports THIS module — a log call here
+        # would be a circular import. The loop tries the other location, then falls back to "dev".
         except OSError:
             continue
     return "dev"
@@ -117,6 +119,9 @@ class Settings(BaseSettings):
     # Recent-first backfill: how far back to fetch on the first pass per channel.
     backfill_recent_max_videos: int = 100
     backfill_recent_max_days: int = 365
+    # A channel whose RSS feed has not answered for this many hours gets its newest uploads read
+    # through the Data API instead (1 unit), at most once per this many hours. 0 = never.
+    rss_fallback_hours: int = 2
 
     # Shorts are confirmed by probing youtube.com/shorts/<id>. Only videos at or below
     # this duration (and not livestreams) are probed; longer videos are never Shorts.
@@ -310,6 +315,10 @@ class Settings(BaseSettings):
     # re-encode is CPU-heavy (the VAAPI hardware path is far cheaper and could sustain more); direct-serve
     # and remux (stream-copy) are not capped by this.
     plex_max_transcodes: int = 4
+    # Max concurrent playback sessions of ANY kind — remux (stream-copy) included. Cheap on the CPU but
+    # each one is a whole segmented copy of the film on the scratch volume, written faster than
+    # realtime. One account holds at most two regardless (plex/stream.py `_MAX_SESSIONS_PER_USER`).
+    plex_max_sessions: int = 8
     # --- Transcode (playable="transcode") re-encode tuning (E6 S1) ---
     # Hardware-encoder policy: "auto" = VAAPI (h264_vaapi) when the iGPU render node is present AND the
     # source codec is hardware-decodable, else libx264 software; "on" = force VAAPI wherever the render

backend/app/db.py

@@ -20,6 +20,10 @@ engine = create_engine(
     max_overflow=30,
     pool_timeout=30,
     future=True,
+    # A database error renders its bound parameters into its message — a title, an uploader, a
+    # file path, a URL — and that message is logged and stored as a job's error text. The SQL
+    # stays; the values are data, and the ids an operator needs are on the line already.
+    hide_parameters=True,
 )
 SessionLocal = sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)
 

backend/app/discover/hero.py

@@ -81,7 +81,11 @@ def pick(
         return None
 
     def _comfort() -> dict | None:
-        for card in pins.playables(pins.shelf(db, user) if shelf is None else shelf):
+        if shelf is None:
+            own = pins.shelf(db, user, include_plex=rails.plex_available(db))
+        else:
+            own = shelf
+        for card in pins.playables(own):
             if cards.key(card) not in skip and fits(card["remaining_seconds"], budget):
                 return card
         return None

backend/app/discover/pins.py

@@ -8,14 +8,16 @@ second one.
 
 Every shelf card carries a resolved `next`: the thing that actually plays when you click the tile —
 a show's in-progress-or-next episode, a channel's newest unwatched video, a playlist's first
-unwatched item. It costs a query per non-leaf pin, which is affordable precisely because this shelf is
-short and hand-curated, and it buys the property the whole surface exists for: one click, no
-intermediate page, no second decision.
+unwatched item. That buys the property the whole surface exists for: one click, no intermediate page,
+no second decision. Channels and playlists are resolved for the whole shelf at once (`_Batch`), so the
+cost does not grow a query or two per pin.
 
 Domain module, so nothing here raises HTTP. `resolve_ref` returns None for "no such thing, or not
 yours" and the route turns that into its 404 — core never imports routes.
 """
 
+from dataclasses import dataclass, field
+
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
@@ -62,6 +64,8 @@ def resolve_ref(db: Session, user: User, kind: str, ref: str) -> tuple[str, obje
         return (col, sh.id) if sh is not None else None
     try:
         pid = int(ref)
+    # silent-ok: validating a reference the client supplied. "Not an integer" is answered as "no
+    # such pin target", which is the same answer this function gives for one that does not exist.
     except ValueError:
         return None
     pl = db.get(Playlist, pid)
@@ -71,6 +75,44 @@ def resolve_ref(db: Session, user: User, kind: str, ref: str) -> tuple[str, obje
     return (col, pl.id) if pl is not None and pl.user_id == user.id else None
 
 
+def reorder(db: Session, user: User, ids: list[int]) -> None:
+    """Put the listed pins in the listed order, WITHIN the slots they already hold.
+
+    The client sends the order it can SEE, which is not always the whole shelf: with Plex off the Home
+    rail hides the Plex pins, and a stale tab may not know a pin added elsewhere. Numbering only the
+    listed ids 0..n-1 collided with every pin left out — two tiles on one position, and the hidden
+    ones jumped about when they came back. So the pins left out keep their slots, and the listed ones
+    are dealt into the slots the listed set occupies. Ids that are not this user's, or repeated, are
+    ignored rather than failing a stale replay wholesale. Flushes; the route commits."""
+    # Locked: the rows it leaves alone are part of the answer too. Two overlapping reorders each
+    # skipped the rows that already matched in their own snapshot and interleaved into two pins on
+    # one slot; the second now waits and deals from the first one's result. Locked in id order and
+    # sorted HERE: with `ORDER BY position … FOR UPDATE` Postgres sorts before it locks, so the one
+    # that waited got the fresh rows in its stale order and dealt the pins it left out back to their
+    # old slots — and one global lock order means two reorders cannot deadlock.
+    locked = db.execute(
+        select(ComfortPin)
+        .where(ComfortPin.user_id == user.id)
+        .order_by(ComfortPin.id)
+        .with_for_update()
+        .execution_options(populate_existing=True)
+    ).scalars()
+    current = sorted(locked, key=lambda p: (p.position, p.id))
+    owned = {p.id for p in current}
+    listed: list[int] = []
+    for i in ids:
+        if i in owned and i not in listed:
+            listed.append(i)
+    chosen = set(listed)
+    queue = iter(listed)
+    order = [next(queue) if p.id in chosen else p.id for p in current]
+    by_id = {p.id: p for p in current}
+    for position, pin_id in enumerate(order):
+        if by_id[pin_id].position != position:
+            by_id[pin_id].position = position
+    db.flush()
+
+
 def list_pins(db: Session, user: User) -> list[ComfortPin]:
     return list(
         db.execute(
@@ -101,7 +143,34 @@ def next_position(db: Session, user: User) -> int:
     )
 
 
-def _shelf_card(db: Session, user: User, pin: ComfortPin) -> dict | None:
+@dataclass
+class _Batch:
+    """What the shelf resolves for every pinned channel and playlist in one go."""
+
+    channels: dict[str, Channel] = field(default_factory=dict)
+    channel_summary: dict[str, tuple[int, dict | None]] = field(default_factory=dict)
+    playlists: dict[int, Playlist] = field(default_factory=dict)
+    playlist_summary: dict[int, tuple[int, dict | None]] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, db: Session, user: User, pins: list[ComfortPin]) -> "_Batch":
+        ch_ids = [p.channel_id for p in pins if p.channel_id is not None]
+        pl_ids = [p.playlist_id for p in pins if p.playlist_id is not None]
+        b = cls()
+        if ch_ids:
+            b.channels = {
+                c.id: c for c in db.scalars(select(Channel).where(Channel.id.in_(ch_ids)))
+            }
+            b.channel_summary = queries.channels_summary(db, user, ch_ids)
+        if pl_ids:
+            b.playlists = {
+                p.id: p for p in db.scalars(select(Playlist).where(Playlist.id.in_(pl_ids)))
+            }
+            b.playlist_summary = queries.playlists_summary(db, user, pl_ids)
+        return b
+
+
+def _shelf_card(db: Session, user: User, pin: ComfortPin, batch: _Batch) -> dict | None:
     """One pin as a unified card with its resolved `next`. None when the pinned row has gone (the FK
     cascade removes the pin itself, so this is only the window between a delete and a refetch)."""
     card: dict | None = None
@@ -115,11 +184,11 @@ def _shelf_card(db: Session, user: User, pin: ComfortPin) -> dict | None:
         nxt = dict(card)  # a video plays itself
 
     elif pin.channel_id is not None:
-        ch = db.get(Channel, pin.channel_id)
+        ch = batch.channels.get(pin.channel_id)
         if ch is None:
             return None
-        card = cards.from_channel(ch, queries.channel_unwatched_count(db, user, ch.id))
-        row = queries.channel_next_video(db, user, ch.id)
+        count, row = batch.channel_summary.get(ch.id, (0, None))
+        card = cards.from_channel(ch, count)
         nxt = cards.from_video(row) if row else None
 
     elif pin.plex_item_id is not None:
@@ -140,10 +209,10 @@ def _shelf_card(db: Session, user: User, pin: ComfortPin) -> dict | None:
         nxt = cards.from_plex(ep) if ep else None
 
     elif pin.playlist_id is not None:
-        pl = db.get(Playlist, pin.playlist_id)
+        pl = batch.playlists.get(pin.playlist_id)
         if pl is None:
             return None
-        count, row = queries.playlist_summary(db, user, pl.id)
+        count, row = batch.playlist_summary.get(pl.id, (0, None))
         card = cards.from_playlist(pl, count, row.get("thumbnail_url") if row else None)
         nxt = cards.from_video(row) if row else None
 
@@ -157,11 +226,24 @@ def _shelf_card(db: Session, user: User, pin: ComfortPin) -> dict | None:
     return card
 
 
-def shelf(db: Session, user: User) -> list[dict]:
-    """The whole shelf, in the user's own order."""
+_PLEX_COLUMNS = ("plex_item_id", "plex_show_id")
+
+
+def shelf(db: Session, user: User, *, include_plex: bool = True) -> list[dict]:
+    """The whole shelf, in the user's own order.
+
+    `include_plex=False` is the Home surface with the deployment's Plex toggle off (the owner's call,
+    2026-09-19): the rails beside it go YouTube-only, and a Plex tile there would offer a Play that
+    lands on a gated module. The pins themselves are kept — the pin menus still read the full shelf
+    (`GET /pins`), and switching Plex back on brings the tiles back in their old slots
+    (`reorder` keeps a hidden pin's place)."""
     out = []
-    for pin in list_pins(db, user):
-        card = _shelf_card(db, user, pin)
+    pins = list_pins(db, user)
+    if not include_plex:
+        pins = [p for p in pins if all(getattr(p, c) is None for c in _PLEX_COLUMNS)]
+    batch = _Batch.load(db, user, pins)
+    for pin in pins:
+        card = _shelf_card(db, user, pin, batch)
         if card is not None:
             out.append(card)
     return out
@@ -169,5 +251,17 @@ def shelf(db: Session, user: User) -> list[dict]:
 
 def playables(shelf_cards: list[dict]) -> list[dict]:
     """The `next` of every shelf entry that has one — what the hero may draw from. A pinned channel
-    with nothing unwatched left, or an empty playlist, simply is not an answer right now."""
-    return [c["next"] for c in shelf_cards if c.get("next")]
+    with nothing unwatched left, or an empty playlist, simply is not an answer right now.
+
+    Each carries `pinned_from`: the pin it was resolved from. A show's next EPISODE is not itself
+    pinned, so without it the hero's menu looked the episode up, missed, and offered "Pin" under a
+    kicker that says "From your shelf" — and taking it inserted a second pin. With it, the hero's
+    pin row acts on the shelf entry the card came from (the owner's call, 2026-09-19: "Unpin")."""
+    return [
+        {
+            **c["next"],
+            "pinned_from": {k: c[k] for k in ("source", "kind", "id", "title")},
+        }
+        for c in shelf_cards
+        if c.get("next")
+    ]

backend/app/discover/queries.py

@@ -43,8 +43,9 @@ from app.plex import rollup
 from app.plex.cards import leaf_card, movie_card, show_card
 from app.plex.query import apply_show_state_filter, content_libs
 
-# How many rows a single rail may carry. Matches `routes/plex/discover.py`'s RAIL_LIMIT on purpose —
-# the two surfaces should feel like the same app, and a rail is a rail.
+# How many rows a single rail may carry — Home's rails and the Plex module's Discover rails alike
+# (`routes/plex/discover.py` imports it): the two surfaces should feel like the same app, and a rail
+# is a rail. One definition, because a comment was all that held two copies in step.
 RAIL_LIMIT = 20
 
 # The feed parameters a Home rail runs with. Spelled out rather than borrowed from the route's
@@ -129,18 +130,6 @@ def yt_surprise(db: Session, user: User, budget: str, seed: int, limit: int) ->
     return [r for r in out if not r["position_seconds"]][:limit]
 
 
-def channel_next_video(db: Session, user: User, channel_id: str) -> dict | None:
-    """The newest unwatched video of a pinned channel — what "put on that channel" resolves to."""
-    # `library_source="all"`: a pinned channel means the whole channel, including videos that only
-    # ever arrived through a search. The feed's "organic" default is a feed-scoping choice, not a
-    # statement about what belongs to a channel.
-    params = dict(_FEED_BASE, channel_ids=[channel_id], scope="all", library_source="all")
-    query, rank_expr = filtered_query(db, user, **params)
-    keys = sort_keys("newest", 0, rank_expr)
-    row = db.execute(query.order_by(*order_by(keys)).limit(1)).first()
-    return serialize(row) if row is not None else None
-
-
 def yt_video_row(db: Session, user: User, video_id: str) -> dict | None:
     """One video as a feed row, with this user's watch state.
 
@@ -158,31 +147,55 @@ def yt_video_row(db: Session, user: User, video_id: str) -> dict | None:
     return serialize(row) if row is not None else None
 
 
-def channel_unwatched_count(db: Session, user: User, channel_id: str) -> int:
-    """How many unwatched videos a pinned channel is holding — the tile's only honest promise, since a
-    channel has no runtime of its own."""
-    params = dict(_FEED_BASE, channel_ids=[channel_id], scope="all", library_source="all")
-    query, _ = filtered_query(db, user, **params)
-    return int(db.execute(select(func.count()).select_from(query.subquery())).scalar() or 0)
+def channels_summary(
+    db: Session, user: User, channel_ids: list[str]
+) -> dict[str, tuple[int, dict | None]]:
+    """For each pinned channel: (unwatched count, its newest unwatched video) — the tile's only honest
+    promise, since a channel has no runtime of its own, and what "put on that channel" resolves to.
+
+    ONE query for the whole shelf, not two per channel: the count and the first row per channel are
+    window functions over the same filtered set. `library_source="all"`: a pinned channel means the
+    whole channel, including videos that only ever arrived through a search — the feed's "organic"
+    default is a feed-scoping choice, not a statement about what belongs to a channel."""
+    if not channel_ids:
+        return {}
+    params = dict(_FEED_BASE, channel_ids=list(channel_ids), scope="all", library_source="all")
+    query, rank_expr = filtered_query(db, user, **params)
+    newest = order_by(sort_keys("newest", 0, rank_expr))
+    per_channel = {"partition_by": Video.channel_id}
+    sub = query.add_columns(
+        func.row_number().over(**per_channel, order_by=newest).label("_rn"),
+        func.count().over(**per_channel).label("_total"),
+    ).subquery()
+    rows = db.execute(select(sub).where(sub.c._rn == 1)).all()
+    return {r.channel_id: (int(r._total), serialize(r)) for r in rows}
 
 
-def playlist_summary(db: Session, user: User, playlist_id: int) -> tuple[int, dict | None]:
-    """(item count, the row to play next) for a pinned playlist — its first not-yet-watched item, or
-    its first item once the whole list is watched. The same row doubles as the tile's artwork, so a
-    shelf of playlists is scannable instead of a row of blank boxes."""
+def playlists_summary(
+    db: Session, user: User, playlist_ids: list[int]
+) -> dict[int, tuple[int, dict | None]]:
+    """For each pinned playlist: (item count, the row to play next) — its first not-yet-watched item,
+    or its first item once the whole list is watched. The same row doubles as the tile's artwork, so
+    a shelf of playlists is scannable instead of a row of blank boxes. One query for the whole shelf."""
+    if not playlist_ids:
+        return {}
     st = aliased(VideoState)
     rows = db.execute(
-        select(*feed_columns(user, st), PlaylistItem.position)
+        select(*feed_columns(user, st), PlaylistItem.playlist_id.label("_playlist"))
         .join(PlaylistItem, PlaylistItem.video_id == Video.id)
         .join(Channel, Channel.id == Video.channel_id)
         .outerjoin(st, and_(st.video_id == Video.id, st.user_id == user.id))
-        .where(PlaylistItem.playlist_id == playlist_id)
-        .order_by(PlaylistItem.position.asc())
+        .where(PlaylistItem.playlist_id.in_(playlist_ids))
+        .order_by(PlaylistItem.playlist_id, PlaylistItem.position.asc())
     ).all()
-    if not rows:
-        return 0, None
-    nxt = next((r for r in rows if (r.status or "new") not in ("watched", "hidden")), rows[0])
-    return len(rows), serialize(nxt)
+    grouped: dict[int, list] = {}
+    for r in rows:
+        grouped.setdefault(r._playlist, []).append(r)
+    out: dict[int, tuple[int, dict | None]] = {}
+    for pid, items in grouped.items():
+        nxt = next((r for r in items if (r.status or "new") not in ("watched", "hidden")), items[0])
+        out[pid] = (len(items), serialize(nxt))
+    return out
 
 
 # ── Plex ──────────────────────────────────────────────────────────────────────────────────────────

backend/app/downloads/adapters.py

@@ -18,6 +18,7 @@ import yt_dlp
 from yt_dlp.networking.impersonate import ImpersonateTarget
 
 from app.config import settings
+from app.downloads.stated import StatedFailure
 
 # Facebook's "Cannot parse data": the page yt-dlp got was a wall, not the content. Both the Chrome retry
 # below and the failure catalog (errors.py) decide on it, so the wording exists once.
@@ -178,11 +179,11 @@ class FacebookAdapter(SourceAdapter):
         # Measured (E11.5 review): a refused or expired cookie gets the login page (~450 KB, a login
         # form, no post id at all), which is not a post without a video — the user's cookie is the cause.
         if _quoted(post_id) not in page:
-            raise RuntimeError(POST_NOT_SHOWN_MESSAGE)
+            raise StatedFailure(POST_NOT_SHOWN_MESSAGE)
         video_id = facebook_post_video_id(page, post_id)
         if video_id is None:
             # Never fall back to the post link: that is exactly where the wrong video comes from.
-            raise RuntimeError(POST_WITHOUT_VIDEO_MESSAGE)
+            raise StatedFailure(POST_WITHOUT_VIDEO_MESSAGE)
         return f"https://www.facebook.com/watch/?v={video_id}"
 
     def client_sets(self, authed: bool = False) -> list:

backend/app/downloads/backfill.py

@@ -11,11 +11,12 @@ Run once per environment:
     docker exec siftlode-worker-1 python -c "from app.downloads import backfill; print(backfill.run())"
 """
 
-import logging
+from urllib.parse import urlsplit
 
 import yt_dlp
 from sqlalchemy import select
 
+from app import logs
 from app.config import settings
 from app.db import SessionLocal
 from app.downloads import adapters
@@ -23,12 +24,17 @@ from app.downloads import edit as editmod
 from app.downloads import formats, service
 from app.models import MediaAsset
 
-log = logging.getLogger("siftlode.backfill")
+log = logs.get_logger(__name__)
 
 
-def _extract_meta(url: str, adapter: adapters.SourceAdapter) -> dict | None:
+def _extract_meta(url: str, adapter: adapters.SourceAdapter, asset_id: int) -> dict | None:
     """Metadata-only yt-dlp extraction, using the source adapter's client sets + options (YouTube
     needs the POT/player-client strategy even just to extract)."""
+    with formats.hiding(url):
+        return _extract_meta_scoped(url, adapter, asset_id)
+
+
+def _extract_meta_scoped(url: str, adapter: adapters.SourceAdapter, asset_id: int) -> dict | None:
     for clients in adapter.client_sets():
         opts = formats.build_ydl_opts(
             {}, "%(id)s.%(ext)s", lambda d: None, extra=adapter.ydl_opts_extra(clients)
@@ -40,7 +46,19 @@ def _extract_meta(url: str, adapter: adapters.SourceAdapter) -> dict | None:
             if info:
                 return info
         except Exception as exc:  # noqa: BLE001 — best-effort backfill, keep going
-            log.info("meta extract failed for %s (%s): %s", url, clients, str(exc)[:100])
+            # The asset id, not the URL. A source URL is a row of this user's download
+            # history, and `redact_text` only takes credential params out of it — the rest
+            # of it goes in whole. The id names the same asset to anyone holding the
+            # database and nothing at all to anyone who is not; the host is kept because it
+            # is what decides which client set was tried. yt-dlp's message goes through
+            # `log_safe` for the same reason: it opens with the URL or the video id.
+            log.info(
+                "meta extract failed for asset %s on %s (%s): %s",
+                asset_id,
+                urlsplit(url).hostname or "?",  # log-pii-ok: the host, never the path or query
+                clients,
+                formats.log_safe(exc)[:100],
+            )
     return None
 
 
@@ -60,12 +78,14 @@ def run() -> dict:
             adapter = adapters.resolve_adapter(a.source_kind, a.source_ref)
             if a.uploader_url is None and adapter.wants_metadata_backfill():
                 url = a.source_webpage_url or service.source_url(a.source_kind, a.source_ref)
-                info = _extract_meta(url, adapter)
+                info = _extract_meta(url, adapter, a.id)
                 uu = adapter.uploader_url(info) if info else None
                 if uu:
                     a.uploader_url = uu
                     filled_url += 1
-                    log.info("asset %s uploader_url <- %s", a.id, uu)
+                    log.info(
+                        "asset %s uploader_url filled", a.id
+                    )  # the URL names what they downloaded
             if a.poster_path is None:
                 # Record a self-hosted poster for every download (the reliable og:image source):
                 # ensure_poster returns the existing <base>.jpg thumbnail sidecar, or cuts a frame.
@@ -73,7 +93,7 @@ def run() -> dict:
                 if rel:
                     a.poster_path = rel
                     filled_poster += 1
-                    log.info("asset %s poster <- %s", a.id, rel)
+                    log.info("asset %s poster filled", a.id)  # the path carries the title
             db.commit()
     result = {
         "assets": len(assets),

backend/app/downloads/credentials.py

@@ -23,19 +23,19 @@ Security controls enforced here:
     logged, or written to a job's error/snapshot.
 """
 
-import logging
 import os
 from pathlib import Path
 
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.downloads import formats
 from app.downloads.adapters import _host_is
 from app.models import DownloadCredential, MediaAsset
 from app.security import decrypt_optional, encrypt
 
-log = logging.getLogger("siftlode.downloads.credentials")
+log = logs.get_logger(__name__)
 
 
 class HostSpec:

backend/app/downloads/edit.py

@@ -23,7 +23,6 @@ for a player hover-preview later.
 
 import hashlib
 import json
-import logging
 import math
 import os
 import queue
@@ -33,9 +32,11 @@ import threading
 import time
 from pathlib import Path
 
+from app import logs
 from app.config import settings
+from app.downloads.stated import StatedFailure
 
-log = logging.getLogger("siftlode.edit")
+log = logs.get_logger(__name__)
 
 
 def encode_thread_cap() -> int:
@@ -71,7 +72,13 @@ def normalize_edit_spec(spec: dict | None) -> dict:
     if crop:
         try:
             c = {k: int(round(float(crop[k]))) for k in ("x", "y", "w", "h")}
-        except (KeyError, TypeError, ValueError):
+        except (KeyError, TypeError, ValueError) as exc:
+            # The clip still renders — uncropped. The user asked for a crop, got a whole frame,
+            # and nothing anywhere called it a failure; this line is the only trace there is.
+            log.warning(
+                "the crop in an edit spec could not be read and was dropped",
+                extra=logs.event("edit.spec.crop_dropped", reason=type(exc).__name__),
+            )
             c = None
         if c and c["w"] > 0 and c["h"] > 0 and c["x"] >= 0 and c["y"] >= 0:
             out["crop"] = c
@@ -80,6 +87,7 @@ def normalize_edit_spec(spec: dict | None) -> dict:
     segs = spec.get("segments")
     if isinstance(segs, list) and segs:
         norm: list[dict] = []
+        unreadable = 0
         for s in segs:
             try:
                 st = max(0.0, float((s or {}).get("start_s") or 0.0))
@@ -88,9 +96,18 @@ def normalize_edit_spec(spec: dict | None) -> dict:
                     continue
                 en = float(end_raw)
             except (TypeError, ValueError):
+                # silent-ok: counted, not logged here — one cut-list can drop several, and the
+                # join that comes out is simply shorter than the one the user built. Reported
+                # once after the loop.
+                unreadable += 1
                 continue
             if en > st:
                 norm.append({"start_s": round(st, 3), "end_s": round(en, 3)})
+        if unreadable:
+            log.warning(
+                "some segments of a cut list could not be read and were dropped",
+                extra=logs.event("edit.spec.segments_dropped", dropped=unreadable, kept=len(norm)),
+            )
         norm.sort(key=lambda x: x["start_s"])
         # SEC-13: an accurate join builds one ffmpeg `filter_complex` with two filters per segment,
         # so an unbounded list becomes an unbounded command line and an ffmpeg that never finishes.
@@ -114,7 +131,13 @@ def normalize_edit_spec(spec: dict | None) -> dict:
             start = max(0.0, float(trim.get("start_s") or 0.0))
             end_raw = trim.get("end_s")
             end = float(end_raw) if end_raw is not None else None
-        except (TypeError, ValueError):
+        except (TypeError, ValueError) as exc:
+            # Either a 400 the user cannot act on, or — beside a crop — a full-length clip where
+            # they asked for a cut. Both are worth one line saying the spec was the problem.
+            log.warning(
+                "the trim in an edit spec could not be read and was dropped",
+                extra=logs.event("edit.spec.trim_dropped", reason=type(exc).__name__),
+            )
             start, end = 0.0, None
         t: dict = {"start_s": round(start, 3)}
         if end is not None and end > start:
@@ -306,11 +329,14 @@ def _parse_out_time(line: str) -> float | None:
     if line.startswith("out_time_us="):
         try:
             return int(line.split("=", 1)[1]) / 1_000_000
+        # silent-ok: one line of ffmpeg's `-progress` stream, several per second. None means "this
+        # line carried no usable time", which the caller already treats as "no progress yet".
         except ValueError:
             return None
     if line.startswith("out_time_ms="):  # (some builds mislabel this as microseconds)
         try:
             return int(line.split("=", 1)[1]) / 1_000_000
+        # silent-ok: as above, the other spelling of the same line.
         except ValueError:
             return None
     return None
@@ -329,7 +355,9 @@ def _pump(stream, sink: "queue.Queue[str | None]") -> None:
     try:
         for line in stream:
             sink.put(line)
-    except (ValueError, OSError):  # pipe closed under us by the kill path
+    # silent-ok: the pipe was closed under us by our OWN kill path — the expected end of a
+    # cancelled or timed-out run, and the code that did the killing is the code that reports it.
+    except (ValueError, OSError):
         pass
     finally:
         sink.put(None)
@@ -347,6 +375,8 @@ def _drain_tail(stream, sink: list[str]) -> None:
             sink.append(line)
             if len(sink) > 200:
                 del sink[:100]
+    # silent-ok: same closed pipe as `_pump` above, and the tail collected so far is still handed
+    # to whoever reports the failure.
     except (ValueError, OSError):
         pass
 
@@ -362,13 +392,17 @@ def escalate_kill(proc: subprocess.Popen, terminate, kill, grace_s: float, label
     try:
         proc.wait(timeout=grace_s)
         return
+    # silent-ok: the escalation below IS the handling of this timeout, and surviving THAT is what
+    # the line under the second wait reports.
     except subprocess.TimeoutExpired:
         pass
     kill()
     try:
         proc.wait(timeout=grace_s)
     except subprocess.TimeoutExpired:
-        log.error("%s pid %s survived SIGKILL", label, proc.pid)
+        # noqa TRY400: the exception IS the message here. A TimeoutExpired's traceback is this
+        # `wait` call and nothing else — it would add three frames and no fact the line lacks.
+        log.error("%s pid %s survived SIGKILL", label, proc.pid)  # noqa: TRY400
 
 
 def _stop(proc: subprocess.Popen) -> None:
@@ -404,6 +438,8 @@ def run_ffmpeg(
         while True:
             try:
                 line = lines.get(timeout=1.0)
+            # silent-ok: not a failure — the one-second timeout is how this loop gets a turn to
+            # poll for cancellation while ffmpeg is quiet.
             except queue.Empty:
                 line = ""
             if line is None:  # stdout hit EOF — ffmpeg is done (or dying)
@@ -416,11 +452,11 @@ def run_ffmpeg(
             if should_cancel():
                 raise EditAborted
             if time.monotonic() - last_output > stall_timeout_s:
-                raise RuntimeError(f"ffmpeg stalled: no progress for {int(stall_timeout_s)}s")
+                raise StatedFailure(f"ffmpeg stalled: no progress for {int(stall_timeout_s)}s")
         try:
             ret = proc.wait(timeout=_FFMPEG_EXIT_GRACE_S)
         except subprocess.TimeoutExpired:  # pipes closed but the process lingers
-            raise RuntimeError("ffmpeg did not exit after closing its output")
+            raise StatedFailure("ffmpeg did not exit after closing its output")
     except BaseException:
         # ONE exit path stops the process, so the invariant is unconditional: nothing leaves this
         # function with ffmpeg still running. Not just our own EditAborted/stall — `on_progress`
@@ -435,7 +471,7 @@ def run_ffmpeg(
             if pipe:
                 pipe.close()
     if ret != 0:
-        raise RuntimeError(f"ffmpeg failed ({ret}): {''.join(err_tail)[-300:]}")
+        raise StatedFailure(f"ffmpeg failed ({ret}): {''.join(err_tail)[-300:]}")
 
 
 # --- ffmpeg: universal browser playability --------------------------------------------------
@@ -471,7 +507,13 @@ def run_ffprobe_json(
     try:
         out = subprocess.run(args, capture_output=True, text=True, timeout=30, check=True).stdout
         return json.loads(out)
-    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError):
+    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError) as exc:
+        # None makes every field it would have filled read as absent, and a file with no streams
+        # and no duration is indistinguishable here from one that is not media at all.
+        log.warning(
+            "ffprobe could not read a file",
+            extra=logs.event("media.ffprobe_failed", reason=type(exc).__name__),
+        )
         return None
 
 
@@ -525,7 +567,13 @@ def probe_duration(path: Path) -> int:
             check=True,
         ).stdout.strip()
         return int(float(out)) if out else 0
-    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError):
+    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError) as exc:
+        # Zero is the denominator of the re-encode progress bar, so a failed probe leaves the user
+        # watching a bar that never moves rather than a job that says it went wrong.
+        log.info(
+            "the duration probe failed; progress for this job has no total",
+            extra=logs.event("media.duration_probe_failed", reason=type(exc).__name__),
+        )
         return 0
 
 
@@ -670,15 +718,28 @@ def _run_ffmpeg_best_effort(cmd: list[str], timeout_s: int) -> Exception | None:
     try:
         subprocess.run(cmd, capture_output=True, timeout=timeout_s, check=True)
         return None
+    # silent-ok: the exception is the RETURN VALUE. This helper exists so the three callers share
+    # one run/timeout policy, and each logs the failure with the context only it has.
     except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError) as exc:
         return exc
 
 
+def _step_failure(err: BaseException) -> str:
+    """What a best-effort image step's failure line says: the kind and, for ffmpeg, its exit
+    status. Never `str(err)`: a CalledProcessError or TimeoutExpired quotes ffmpeg's argv, and an
+    OSError its file name — the source path either way, which is built from the channel and the
+    title."""
+    code = getattr(err, "returncode", None)
+    return f"{type(err).__name__} {code}" if code is not None else type(err).__name__
+
+
 def _is_jpeg(path: Path) -> bool:
     """True if the file starts with the JPEG SOI marker (FF D8 FF)."""
     try:
         with path.open("rb") as f:
             return f.read(3) == b"\xff\xd8\xff"
+    # silent-ok: False only means "do not copy this straight through" — the caller then goes the
+    # ffmpeg route, which opens the same file and reports it properly if it really is unreadable.
     except OSError:
         return False
 
@@ -699,13 +760,15 @@ def thumbnail_to_jpg(src: Path | None, dest: Path, timeout_s: int = 30) -> Path
             shutil.copyfile(src, dest)
             return dest
         except OSError as exc:
-            log.info("thumbnail copy failed (%s); poster falls back to a cut frame", str(exc)[:120])
+            log.info(
+                "thumbnail copy failed (%s); poster falls back to a cut frame", _step_failure(exc)
+            )
             return None
     err = _run_ffmpeg_best_effort(build_thumbnail_jpg_cmd(src, dest), timeout_s)
     if err is not None:
         log.info(
             "thumbnail->jpg conversion failed (%s); poster falls back to a cut frame",
-            str(err)[:120],
+            _step_failure(err),
         )
         return None
     return dest if dest.exists() else None
@@ -730,7 +793,7 @@ def ensure_poster(asset, download_root: str, timeout_s: int = 30) -> str | None:
     at = min(3.0, (asset.duration_s or 10) * 0.1)
     err = _run_ffmpeg_best_effort(build_poster_cmd(src, dest, at), timeout_s)
     if err is not None:
-        log.info("poster gen skipped for asset %s: %s", asset.id, str(err)[:120])
+        log.info("poster gen skipped for asset %s: %s", asset.id, _step_failure(err))
         return None
     return rel if dest.exists() else None
 
@@ -761,7 +824,7 @@ def ensure_storyboard(asset, download_root: str, timeout_s: int = 90) -> dict |
     cmd = build_storyboard_cmd(src, dest, asset.duration_s, geom)
     err = _run_ffmpeg_best_effort(cmd, timeout_s)
     if err is not None:
-        log.info("storyboard gen skipped for asset %s: %s", asset.id, str(err)[:120])
+        log.info("storyboard gen skipped for asset %s: %s", asset.id, _step_failure(err))
         return None
     if not dest.exists():
         return None

backend/app/downloads/formats.py

@@ -17,8 +17,134 @@ spec shape (all keys optional; defaults + browser-playability clamp applied by `
 `container`/`vcodec` keys survive only so an old stored profile deserializes without error.
 """
 
+import contextlib
+import contextvars
 import hashlib
 import json
+import logging
+import os
+import re
+import urllib.parse
+from collections.abc import Iterator
+
+from app import logs
+
+log = logs.get_logger(__name__)
+
+# yt-dlp names what it is working on in these shapes, and each one is a row of someone's download
+# history: the source URL, the `[extractor] <id>:` prefix on nearly every warning and error, the
+# file path it writes to (`storage.rel_path` builds it from the channel and the title), a
+# playlist's title, and an id quoted mid-sentence. The job id is already on every line
+# (`logs.set_job` in the download child), so none of them adds anything an operator needs. What
+# stays: the host (it says which extractor is failing) and the extractor tag. Every pattern below
+# is a shape measured in yt-dlp's own source (2026.07.04), pinned in test_ytdlp_logging.py.
+_URL_RE = re.compile(r"https?://([^/\s]+)\S*")
+# `Destination:` is yt-dlp's own word in `[download] Destination: <path>`, not an id — the path
+# after it is what `_PATH_RE` takes out.
+_ID_PREFIX_RE = re.compile(r"(\[[\w:.-]+\] )(?!Destination:)[^\s:\[\]]+:")
+# The generic extractor's "id" is the URL's basename, percent-DECODED: `My%20Holiday.mp4` is
+# `My Holiday` — spaces, brackets, colons and all, which no pattern can bound (`Our Trip: Day 1`
+# ends at which `: `?). The job knows its own URL, so the exact name is taken out as a literal
+# (`hiding`). This pattern is the fallback for a line logged outside that scope: up to the first
+# `: `. Only this extractor: every other one names a site id, and letting the prefix run to `: `
+# everywhere would take the words out of lines like `[VideoConvertor] Converting …; Destination:`.
+_GENERIC_ID_RE = re.compile(r"(\[generic\] )(?!Destination:)[^\[\]\n]+?:(?= |$)", re.M)
+# `[youtube:tab] Playlist <title>: Downloading 5 items` — the title is not an id, and has spaces.
+_PLAYLIST_TITLE_RE = re.compile(r"(\] Playlist ).+?(?=: Downloading )")
+# `[download] Finished downloading playlist: <title>`, `[download] Downloading playlist: <title>`,
+# `… Skipping already downloaded playlist: <title>` — the title runs to the end of the line.
+_TITLE_TAIL_RE = re.compile(r"(playlist: |\[download\] Downloading \w+: ).*", re.I)
+# An id quoted mid-sentence, not as a prefix: `… not available for <id>`, and `--no-playlist`'s
+# `Downloading just the video <id>` (`_yes_playlist`) / `Downloading just video <id>` (multifeed).
+_BARE_ID_RE = re.compile(
+    r"((?:subtitles not available for|Downloading just (?:the )?\w+) )[^\s,;]+"
+)
+# Two segments or more, and not glued to a word: `www.youtube.com/…` is what the URL pattern
+# leaves behind, and it must survive this one.
+_PATH_RE = re.compile(r"(?<![\w.…])/(?:[^/\s\"']+/)+[^/\s\"']*")
+
+
+_HIDDEN: contextvars.ContextVar[tuple[str, ...]] = contextvars.ContextVar(
+    "formats_hidden", default=()
+)
+
+
+def generic_id(url: str) -> str:
+    """The name yt-dlp's generic extractor gives a URL: its basename, extension off, percent-
+    decoded — `InfoExtractor._generic_id` (2026.07.04), pinned against it in the tests."""
+    return urllib.parse.unquote(os.path.splitext(url.rstrip("/").split("/")[-1])[0])
+
+
+@contextlib.contextmanager
+def hiding(url: str | None) -> Iterator[None]:
+    """For the work on one URL: `log_safe` also takes out the name yt-dlp's generic extractor
+    gives it, exactly, where yt-dlp puts it (`[generic] <name>:`). A context variable, so it
+    holds for yt-dlp's logger calls too — they run on the same thread as the extraction."""
+    name = generic_id(url) if url else ""
+    token = _HIDDEN.set((*_HIDDEN.get(), name) if name else _HIDDEN.get())
+    try:
+        yield
+    finally:
+        _HIDDEN.reset(token)
+
+
+def log_safe(text: object) -> str:
+    """yt-dlp's text (its own lines, or a DownloadError's message) with the parts that name a
+    person's download taken out. Every log line that carries yt-dlp's words goes through here,
+    not just the adapter's: yt-dlp raises the same text it has just logged, so a line that skipped
+    it would put back one line later exactly what the adapter took out."""
+    text = str(text)
+    for name in _HIDDEN.get():
+        text = text.replace(f"[generic] {name}:", "[generic] …:")
+    text = _URL_RE.sub(lambda m: f"{m.group(1)}/…", text)
+    text = _ID_PREFIX_RE.sub(r"\1…:", text)
+    text = _GENERIC_ID_RE.sub(r"\1…:", text)
+    text = _PLAYLIST_TITLE_RE.sub(r"\1…", text)
+    text = _TITLE_TAIL_RE.sub(r"\1…", text)
+    text = _BARE_ID_RE.sub(r"\1…", text)
+    return _PATH_RE.sub("…", text)
+
+
+class _YdlLog:
+    """yt-dlp's logger protocol, pointed at ours.
+
+    Without it yt-dlp explains itself to nobody: `quiet` sends its output to a stdout we do not
+    read, so "Requested format is not available", a signature-extraction failure or a POT refusal
+    reached us only as whatever text ended up in the raised exception. Measured against yt-dlp
+    2026.07.04: with `logger` set it calls `debug` for extraction and progress lines and
+    `warning`/`error` for the rest, and `quiet`/`no_warnings` do NOT gate those calls.
+
+    `debug` goes to TRACE: it is several lines per second during a download, so it shows only
+    when the whole process runs at TRACE. (Not under a user's own Teljes consent — that lives in
+    the API process's request scope, and the download child that runs yt-dlp has none.)
+
+    `error` goes to WARNING, not ERROR. yt-dlp calls it from `trouble()` just before it raises,
+    on EVERY failed attempt — including the ones the pipeline then recovers from with its fallback
+    client set. Whether the job failed is the pipeline's verdict (`download.job.failed`), and that
+    is the one line whose level should say so."""
+
+    def _emit(self, level: int, msg: str) -> None:
+        # The line goes as an ARGUMENT, not as the format string. yt-dlp writes progress as
+        # `[download]  53.2% of 12.00MiB`, and while stdlib logging only applies `%` formatting to
+        # a record that has args, this way the question never arises — and it is the shape ruff's
+        # `G` rules ask for. (The sink's flood limiter groups a bare `%s` by the text itself, so
+        # distinct yt-dlp warnings do not share one bucket — `logsink._template`.)
+        log.log(level, "%s", log_safe(msg), extra=logs.event("download.ytdlp"))
+
+    def debug(self, msg):
+        self._emit(logs.TRACE, msg)
+
+    def info(self, msg):
+        self._emit(logging.DEBUG, msg)
+
+    def warning(self, msg):
+        self._emit(logging.WARNING, msg)
+
+    def error(self, msg):
+        self._emit(logging.WARNING, msg)
+
+
+_YDL_LOG = _YdlLog()
 
 # Fields that affect the produced file — and therefore the cache identity.
 _SIG_KEYS = (
@@ -78,7 +204,13 @@ def normalize(spec: dict) -> dict:
         # rather than raising an unhandled 500 at enqueue.
         try:
             s["max_height"] = int(s["max_height"])
-        except (TypeError, ValueError):
+        except (TypeError, ValueError) as exc:
+            # "best" is the opposite of what a height cap asks for: the user set a ceiling to save
+            # bandwidth or disk, and the download quietly takes the largest rendition there is.
+            log.warning(
+                "the height cap on a download could not be read and was dropped",
+                extra=logs.event("download.format.max_height_dropped", reason=type(exc).__name__),
+            )
             s["max_height"] = None
     for b in ("embed_subs", "embed_chapters", "embed_thumbnail", "sponsorblock"):
         s[b] = bool(s[b])
@@ -181,6 +313,12 @@ def build_ydl_opts(
     if extra:
         opts.update(extra)
 
+    # With a logger attached, `quiet` and `no_warnings` stop deciding whether yt-dlp explains itself
+    # and only decide where — so both stay on above and the explanation comes here instead of to a
+    # stdout nothing reads. AFTER the adapter merge, like `cookiefile` and the size cap: an adapter
+    # must not be able to silence the one account of what went wrong that a failed job leaves.
+    opts["logger"] = _YDL_LOG
+
     # SEC-13: hard ceiling on a single download. AFTER the adapter merge, for the same reason
     # `cookiefile` is — a source adapter must not be able to raise a limit the quota layer set.
     #

backend/app/downloads/gc.py

@@ -16,7 +16,6 @@ Five passes each run:
 Runs in the API process (which mounts DOWNLOAD_ROOT). Pure disk/DB work — no YouTube quota.
 """
 
-import logging
 import time
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
@@ -24,14 +23,13 @@ from pathlib import Path
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
 from app.downloads import storage
 from app.models import DownloadJob, MediaAsset
 from app.notifications import create_notification
 
-log = logging.getLogger("siftlode.downloads.gc")
-
+log = logs.get_logger(__name__)
 # Dot-prefixed top-level trees that are NOT part of the Plex/flat asset layout — the orphan sweep
 # never touches them (user clips, Plex HLS/img caches, in-progress staging, editor storyboards).
 _SYSTEM_TREE = {".edits", ".plex-hls", ".plex-img-cache", ".staging", ".storyboards"}
@@ -99,6 +97,7 @@ def _sweep_orphan_files(db: Session, download_root: str) -> int:
         if pause_s and touched % batch == 0:
             time.sleep(pause_s)
 
+    unreclaimed = 0
     for entry in root.iterdir():
         if entry.name.startswith("."):  # .edits / .plex-* / .staging / .storyboards + any dotfile
             continue
@@ -111,7 +110,9 @@ def _sweep_orphan_files(db: Session, download_root: str) -> int:
                 f.unlink()
                 removed += 1
             except OSError:
-                pass
+                # silent-ok: counted, not logged per file — a broken mount would put one line
+                # under every orphan. The total is reported once at the end of the sweep.
+                unreclaimed += 1
         if entry.is_dir():  # prune emptied dirs (deepest first), then the channel dir itself
             for d in sorted(
                 (p for p in entry.rglob("*") if p.is_dir()),
@@ -120,12 +121,20 @@ def _sweep_orphan_files(db: Session, download_root: str) -> int:
             ):
                 try:
                     d.rmdir()
+                # silent-ok: `rmdir` refusing means the directory still holds files, which is
+                # the ordinary answer here — this prune only takes the ones that emptied.
                 except OSError:
                     pass
             try:
                 entry.rmdir()
+            # silent-ok: the same prune one level up, at the channel directory.
             except OSError:
                 pass
+    if unreclaimed:
+        log.warning(
+            "some orphaned download files could not be reclaimed",
+            extra=logs.event("download.gc.unreclaimed", files=unreclaimed, removed=removed),
+        )
     return removed
 
 

backend/app/downloads/links.py

@@ -49,6 +49,8 @@ def check_grant(token: str, grant: str | None, password_version: int) -> bool:
     exp_s, sig = grant.split(".", 1)
     try:
         exp = int(exp_s)
+    # silent-ok: an untrusted grant that does not parse is simply not a valid grant, and the
+    # honest answer to it — a password prompt — is the same as for one that expired.
     except ValueError:
         return False
     if exp < datetime.now(timezone.utc).timestamp():

backend/app/downloads/og.py

@@ -66,6 +66,8 @@ def _jpeg_size(path: Path) -> tuple[int, int] | None:
                     width = (data[3] << 8) + data[4]
                     return width, height
                 f.seek(length - 2, 1)  # skip this segment's payload
+    # silent-ok: None omits width/height from the unfurl card, which is what the card does for
+    # every poster whose dimensions were never asked for. Nothing is claimed that is not true.
     except OSError:
         return None
 

backend/app/downloads/pipeline.py

@@ -1,6 +1,5 @@
 """Child-side download/edit pipeline — the yt-dlp download + ffmpeg edit that runs in the spawned subprocess."""
 
-import logging
 import re
 import shutil
 import time
@@ -9,7 +8,7 @@ from pathlib import Path
 
 import yt_dlp
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
 from app.db import SessionLocal
 from app.downloads import edit as editmod
@@ -24,12 +23,13 @@ from app.downloads.jobdb import (
     _staging_dir,
     _touch_job,
 )
+from app.downloads.stated import StatedFailure
 from app.downloads.status import JobStatus
 from app.models import DownloadJob, MediaAsset
 from app.notifications import create_notification
 from app.titles import normalize_title
 
-log = logging.getLogger("siftlode.worker")
+log = logs.get_logger(__name__)
 
 
 class _Aborted(Exception):
@@ -98,6 +98,8 @@ def _parse_upload_date(raw) -> date | None:
         return None
     try:
         return datetime.strptime(str(raw), "%Y%m%d").date()
+    # silent-ok: a date we cannot read becomes a date the card does not show, which is what the
+    # card shows for every source that never supplies one. Absent is the honest rendering.
     except ValueError:
         return None
 
@@ -138,7 +140,14 @@ def _make_progress_hook(job_id: int, asset_id: int):
             try:
                 _fill_asset_meta_early(asset_id, d["info_dict"])
             except Exception:  # noqa: BLE001 — metadata is best-effort, never fail a download
-                pass
+                # Best-effort is about the DOWNLOAD, not about knowing. What this swallows is
+                # anything from a shape change in yt-dlp's info dict to the database being down,
+                # and all the user sees is a card with an id on it until the job finishes.
+                log.info(
+                    "early metadata could not be filled in for this download",
+                    extra=logs.event("download.meta.early_fill_failed", asset_id=asset_id),
+                    exc_info=True,
+                )
         if d.get("status") != "downloading":
             return
         if not allow_write():
@@ -299,7 +308,7 @@ def _produced_file(info: dict, staging: Path) -> Path:
         and not _YTDLP_TEMP_RE.search(p.name)
     ]
     if not cands:
-        raise RuntimeError("yt-dlp produced no output file")
+        raise StatedFailure("yt-dlp produced no output file")
     return max(cands, key=lambda p: p.stat().st_size)
 
 
@@ -375,13 +384,22 @@ def _extract_with_fallback(
                     "job %s: clients %s failed (%s); retrying with fallback",
                     job_id,
                     clients,
-                    str(exc)[:70],
+                    formats.log_safe(exc)[:70],
                 )
                 for p in list(staging.iterdir()):  # drop partials before the retry
                     try:
                         p.unlink()
-                    except OSError:
-                        pass
+                    except OSError as exc:
+                        # A partial left behind is not inert: the next client set resumes into it,
+                        # so the retry this loop exists to make clean starts dirty instead.
+                        log.info(
+                            "a partial file could not be removed before the retry",
+                            extra=logs.event(
+                                "download.retry.partial_unlink_failed",
+                                job_id=job_id,
+                                reason=type(exc).__name__,
+                            ),
+                        )
                 _set_job(job_id, progress=0, phase="downloading")
                 continue
             raise
@@ -464,7 +482,7 @@ def _download(
             try:
                 urlguard.check_url(url)
             except urlguard.BlockedUrl as e:
-                raise RuntimeError(f"Refusing to download from this address ({e.reason}).") from e
+                raise StatedFailure(f"Refusing to download from this address ({e.reason}).") from e
         # S6: attach the acting user's per-host cookie ONLY when it's host-scoped to this URL AND
         # this asset is that user's private, salted identity (the double gate lives in credentials).
         remaining_bytes: int | None = None
@@ -586,13 +604,23 @@ def _download(
             db.commit()
             if finalized:
                 _notify_download_done(db, owner_id, meta.title, job_id, kind="download")
-                log.info("job %s done: %s", job_id, rel)
+                # The asset id, not `rel`: the path is built from the channel and the title.
+                log.info(
+                    "job %s done: asset %s",
+                    job_id,
+                    asset_id,
+                    extra=logs.event("download.job.done", job_id=job_id, asset_id=asset_id),
+                )
 
     except (_Aborted, editmod.EditAborted):
         # Paused/canceled mid-download or mid-transcode: free the asset for a later retry; keep the
         # job's status (the route set it to paused/canceled). ref_count is adjusted by the route.
         _reset_asset_pending(asset_id)
-        log.info("job %s aborted (pause/cancel)", job_id)
+        log.info(
+            "job %s aborted (pause/cancel)",
+            job_id,
+            extra=logs.event("download.job.aborted", job_id=job_id),
+        )
     except _OwnerRefused as exc:
         # Fail this job only. The asset is never marked `error`; it goes back to `pending` (below),
         # so another user's job for the same video is claimed and downloaded normally instead of
@@ -613,7 +641,12 @@ def _download(
         # it, and this one must already be out of the way. (The staging tree is still torn down in
         # `finally` below — the same narrow window the pause/cancel path above has always had.)
         _reset_asset_pending(asset_id)
-        log.info("job %s refused for its owner: %s", job_id, msg)
+        log.info(
+            "job %s refused for its owner: %s",
+            job_id,
+            formats.log_safe(msg),
+            extra=logs.event("download.job.refused", job_id=job_id),
+        )
     except Exception as exc:  # noqa: BLE001 — surface any failure to the user, keep worker alive
         msg = str(exc)[:500]
         # The catalog needs the link and whether the user's cookie went with it: the same yt-dlp
@@ -626,8 +659,9 @@ def _download(
             if asset:
                 asset.status = "error"
                 asset.error = msg
-            # Atomic fail: only while still running, so a route-set cancel/pause is never overwritten
-            # with `error` (error also holds the asset → would re-open the double-release class).
+            # Atomic fail: only while still running, so a route-set cancel/pause is never
+            # overwritten with `error` (error also holds the asset → would re-open the
+            # double-release class).
             service.finalize_if_running(
                 db,
                 job_id,
@@ -638,7 +672,10 @@ def _download(
                 phase=None,
             )
             db.commit()
-        log.warning("job %s failed: %s", job_id, msg)
+        # After the write: a job the write could not fail is not a failed job. When it raises,
+        # the runner reports this failure with it (`runner._run`) and the worker fails the job.
+        # silent-ok: not silent — `_log_download_failed` is the report.
+        _log_download_failed(job_id, msg, diagnosis.code, exc)
     finally:
         # Unlink the decrypted cookie file explicitly (the rmtree below removes the whole staging
         # tree too, but never leave a plaintext session cookie on disk a moment longer than needed).
@@ -647,7 +684,50 @@ def _download(
         shutil.rmtree(staging, ignore_errors=True)
 
 
-def _fail_edit(job_id: int, asset_id: int, msg: str) -> None:
+def _failure_stack(exc: BaseException) -> dict[str, str]:
+    """The `extra=` fragment that puts a failure's traceback on its line — or nothing.
+
+    Nothing for yt-dlp's DownloadError and for our own `StatedFailure` (`ffmpeg failed (1): …`):
+    their message is the whole story, and their stack is only the `except` that caught them.
+    Everything else keeps it — a TypeError on an odd info dict, a plain RuntimeError, an OSError,
+    a database error: that is our code or our platform failing, and the stack is the lead.
+
+    Scrubbed, link by link (`logs.scrubbed_stack`): a stack's messages are data — an OSError names
+    its file, and a database error raised inside `except DownloadError` carries yt-dlp's
+    unscrubbed text as its context."""
+    if isinstance(exc, (yt_dlp.utils.DownloadError, StatedFailure)):
+        return {}
+    return logs.scrubbed_stack(exc, formats.log_safe)
+
+
+def _log_download_failed(job_id: int, msg: str, code: str | None, exc: BaseException) -> None:
+    """The child's `download.job.failed` line. `msg` is the user's copy and keeps their URL; the
+    log's copy goes through `log_safe`, or it would put back one line later the URL and id the
+    yt-dlp adapter took out of the line before it. The stack only when the classifier could not
+    place the failure: a recognised one is fully described by its code."""
+    unplaced = code in (None, "", "unknown")
+    log.warning(
+        "job %s failed: %s",
+        job_id,
+        formats.log_safe(msg),
+        extra={
+            **logs.event(
+                "download.job.failed",
+                job_id=job_id,
+                error_code=code,
+                error_type=type(exc).__name__,
+            ),
+            **(_failure_stack(exc) if unplaced else {}),
+        },
+    )
+
+
+def _fail_edit(job_id: int, asset_id: int, msg: str, exc: BaseException | None = None) -> None:
+    """Fail an edit job, and say so ONCE — every way an edit fails comes through here, so this is
+    where its line and its event code live. `exc` is the exception when there was one.
+
+    Its traceback goes with the line unless the message already tells it all (`_failure_stack`).
+    Logged after the write, as on the download error path."""
     with SessionLocal() as db:
         asset = db.get(MediaAsset, asset_id)
         if asset:
@@ -663,7 +743,22 @@ def _fail_edit(job_id: int, asset_id: int, msg: str) -> None:
             phase=None,
         )
         db.commit()
-    log.warning("edit job %s failed: %s", job_id, msg)
+    # `msg` is the user's copy; ffmpeg's stderr tail in it can name the source file, whose path is
+    # built from the channel and the title.
+    log.warning(
+        "edit job %s failed: %s",
+        job_id,
+        formats.log_safe(msg),
+        extra={
+            **logs.event(
+                "edit.job.failed",
+                job_id=job_id,
+                asset_id=asset_id,
+                **({"error_type": type(exc).__name__} if exc is not None else {}),
+            ),
+            **(_failure_stack(exc) if exc is not None else {}),
+        },
+    )
 
 
 def _process_edit(job_id: int, asset_id: int) -> None:
@@ -715,7 +810,7 @@ def _process_edit(job_id: int, asset_id: int) -> None:
             should_cancel=_cancel_poll(job_id),
         )
         if not dest_staging.exists():
-            raise RuntimeError("ffmpeg produced no output file")
+            raise StatedFailure("ffmpeg produced no output file")
 
         rel = storage.edit_rel_path(user_id, asset_id, out_ext)
         storage.place_file(dest_staging, settings.download_root, rel)
@@ -751,13 +846,24 @@ def _process_edit(job_id: int, asset_id: int) -> None:
             db.commit()
             if finalized:
                 _notify_download_done(db, owner_id, dl_title, job_id, kind="edit")
-                log.info("edit job %s done: %s", job_id, rel)
+                # The asset id, not `rel`: the path is built from the channel and the title.
+                log.info(
+                    "edit job %s done: asset %s",
+                    job_id,
+                    asset_id,
+                    extra=logs.event("edit.job.done", job_id=job_id, asset_id=asset_id),
+                )
 
     except editmod.EditAborted:
         # Paused/canceled mid-encode: free the asset for a later retry (ref_count is the route's job).
         _reset_asset_pending(asset_id)
-        log.info("edit job %s aborted (pause/cancel)", job_id)
+        log.info(
+            "edit job %s aborted (pause/cancel)",
+            job_id,
+            extra=logs.event("edit.job.aborted", job_id=job_id),
+        )
     except Exception as exc:  # noqa: BLE001 — surface the failure, keep the worker alive
-        _fail_edit(job_id, asset_id, str(exc)[:500])
+        # silent-ok: not silent — `_fail_edit` is the report, and it takes `exc` for its stack.
+        _fail_edit(job_id, asset_id, str(exc)[:500], exc)
     finally:
         shutil.rmtree(staging, ignore_errors=True)

backend/app/downloads/probe.py

@@ -64,6 +64,8 @@ def _facts_from_probe(
         raw = fmt.get("duration")
         if raw is not None:
             duration = int(float(raw))
+    # silent-ok: an unusable duration is stored as no duration, which the UI renders as unknown
+    # rather than as zero — the honest state, and the one a re-probe can still fill in.
     except (TypeError, ValueError):
         duration = None
     return vcodec, acodec, width, height, duration

backend/app/downloads/runner.py

@@ -11,7 +11,6 @@ writes the terminal job/asset state itself (done / error, or a cooperative pause
 progress hook), then exits 0. An unexpected crash exits non-zero and the parent fails the job.
 """
 
-import logging
 import os
 import shutil
 import subprocess
@@ -22,9 +21,10 @@ from app import logsink
 from app.config import settings
 from app.db import SessionLocal
 from app.downloads import edit as editmod
+from app.downloads import formats
 from app.models import DownloadJob
 
-log = logging.getLogger("siftlode.worker.runner")
+log = logs.get_logger(__name__)
 
 
 def _deprioritize() -> None:
@@ -57,7 +57,12 @@ def main() -> None:
     logs.configure_logging("runner")
     _deprioritize()
     if len(sys.argv) != 2:
-        print("usage: python -m app.downloads.runner <job_id>", file=sys.stderr)
+        # noqa T201: a usage line is for the person who typed the command. Logging is already
+        # configured here, and in a deployment it writes JSON records — the one reader of this
+        # line wants the bare sentence, not a record with a request id they do not have.
+        print(  # noqa: T201
+            "usage: python -m app.downloads.runner <job_id>", file=sys.stderr
+        )
         raise SystemExit(2)
     job_id = int(sys.argv[1])
     # This whole process exists to run ONE job — tag every line it prints with it, so the child's
@@ -77,14 +82,40 @@ def main() -> None:
     if asset_id is None:
         return
 
+    _run(job_id, asset_id, job_kind, source_kind, source_ref, spec, user_id)
+
+
+def _run(job_id, asset_id, job_kind, source_kind, source_ref, spec, user_id) -> None:
+    """Run the job, and be the last stop before Python's own exception hook.
+
+    What gets past the pipeline is a failure it could not even record (the database refused the
+    write that fails the job). Python's hook would print it to stderr raw — and its context is the
+    download's own failure, whose text is the URL or ffmpeg's stderr naming the file. Here it is
+    one line with the whole chain scrubbed; the non-zero exit then has the worker fail the job
+    (`cause=child_exit`)."""
     # Imported here (not at module top) so the child pays the yt-dlp import cost only when it has
     # real work, and to keep the import graph obvious: runner is a thin entry over the pipeline.
     from app.downloads.pipeline import _download, _process_edit
 
-    if job_kind == "edit":
-        _process_edit(job_id, asset_id)
-    else:
-        _download(job_id, asset_id, source_kind, source_ref, spec, user_id)
+    with formats.hiding(source_ref):
+        try:
+            if job_kind == "edit":
+                _process_edit(job_id, asset_id)
+            else:
+                _download(job_id, asset_id, source_kind, source_ref, spec, user_id)
+        except Exception as exc:  # noqa: BLE001 — whatever it is, it is reported here or raw
+            # noqa TRY400: the stack goes with it scrubbed (`scrubbed_stack`); `exc_info` is raw.
+            log.error(  # noqa: TRY400
+                "the download child for job %s failed",
+                job_id,
+                extra={
+                    **logs.event(
+                        "download.child.failed", job_id=job_id, error_type=type(exc).__name__
+                    ),
+                    **logs.scrubbed_stack(exc, formats.log_safe),
+                },
+            )
+            raise SystemExit(1) from None
 
 
 if __name__ == "__main__":

backend/app/downloads/service.py

@@ -87,6 +87,8 @@ def get_or_create_asset(
         with db.begin_nested():
             db.add(asset)
             db.flush()
+    # silent-ok: the expected outcome of the race this savepoint exists for — two jobs wanting the
+    # same asset. Losing it means the other insert won, and re-selecting is the whole handling.
     except IntegrityError:
         asset = db.execute(stmt).scalar_one()
     return asset

backend/app/downloads/stated.py

@@ -0,0 +1,13 @@
+"""The failures the download pipeline raises itself, with the whole story in the message.
+
+`ffmpeg failed (1): …`, `yt-dlp produced no output file`, a post that shows no video: the message
+says what happened, and the stack is only the `except` that caught it. A failure line leaves that
+stack off (`pipeline._failure_stack`) — but ONLY for these. A plain `RuntimeError` is also what
+Python raises for a bug of ours (a dict changed size during iteration, a generator's
+StopIteration, `RecursionError`, `NotImplementedError`), and that one's stack is the only lead.
+"""
+
+
+class StatedFailure(RuntimeError):
+    """A failure we raised on purpose, whose message is its full explanation. A `RuntimeError` so
+    every `except RuntimeError` that caught these before still does."""

backend/app/downloads/storage.py

@@ -19,8 +19,11 @@ from datetime import date
 from pathlib import Path
 from xml.sax.saxutils import escape
 
+from app import logs
 from app.downloads import mediakind
 
+log = logs.get_logger(__name__)
+
 # Reserve room for the "_id.ext" suffix + parent dirs within the 255-char component limit.
 _MAX_TITLE = 120
 # User-facing (Content-Disposition) names can be longer than an on-disk component.
@@ -294,7 +297,13 @@ def write_sidecars(download_root: str, rel: str, meta: MediaMeta, thumb_src: Pat
         if thumb_src and thumb_src.exists():
             shutil.copyfile(str(thumb_src), str(_sidecar(media, ".jpg")))
         return True
-    except OSError:
+    except OSError as exc:
+        # The download itself still completes, so the job reads as done while the library it was
+        # downloaded FOR has no .nfo to read and no poster to show.
+        log.warning(
+            "the sidecars beside a download could not be written",
+            extra=logs.event("download.sidecars.write_failed", reason=type(exc).__name__),
+        )
         return False
 
 
@@ -304,14 +313,23 @@ def delete_asset_files(download_root: str, rel: str) -> None:
     for p in (media, _sidecar(media, ".nfo"), _sidecar(media, ".jpg")):
         try:
             p.unlink()
-        except OSError:
-            pass
+        except FileNotFoundError:
+            pass  # silent-ok: already gone is the outcome this function wanted
+        except OSError as exc:
+            # The row goes and the bytes stay. Nothing else ever revisits this path, so the disk
+            # quietly keeps a file no account has any way to see, let alone delete.
+            log.info(
+                "a deleted download left a file behind",
+                extra=logs.event("download.asset.file_unlink_failed", reason=type(exc).__name__),
+            )
     # Prune empty Season/Channel dirs up to (but not including) the root.
     root = Path(download_root).resolve()
     parent = media.parent
     while parent != root and root in parent.parents:
         try:
             parent.rmdir()  # only succeeds if empty
+        # silent-ok: this `rmdir` failing is the loop's stop condition — the parent still
+        # holds another download's files, so the prune has gone as far up as it may.
         except OSError:
             break
         parent = parent.parent

backend/app/email.py

@@ -11,7 +11,6 @@ to be a person telling them nothing arrived.
 """
 
 import html
-import logging
 import re
 import smtplib
 import ssl
@@ -21,15 +20,14 @@ from email.utils import formatdate
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app import mailtext, sysconfig
+from app import logs, mailtext, sysconfig
 from app.config import settings
 from app.db import SessionLocal
 from app.models import User
 from app.notifications import create_notification
 from app.ratelimit import RateLimiter
 
-log = logging.getLogger("siftlode.email")
-
+log = logs.get_logger(__name__)
 # One admin notice an hour per reason. A relay that is down fails every send, and the inbox must
 # stay readable; the log keeps the full record either way.
 _alert_throttle = RateLimiter(max_events=1, window_seconds=3600)
@@ -155,7 +153,15 @@ def _send(to: list[str], subject: str, body: str, reply_to: str | None = None) -
         return False
     c = _smtp()
     if not (c["host"] and c["user"] and c["password"]):
-        log.info("SMTP not configured; skipping email %r to %s", subject, recipients)
+        # The count, not the addresses: `redact_text` rewrites every one of them to `[email]`
+        # before either sink sees the line, so the list only ever printed as noise. The subject
+        # stays — the templates are static, and the one that interpolates (`admin_new_request`)
+        # interpolates an address, which the same redactor covers.
+        log.info(
+            "SMTP not configured; skipping email %r to %d recipient(s)",
+            subject,
+            len(recipients),  # log-pii-ok: how many, not who
+        )
         _alert_admins("not_configured", subject, recipients)
         return False
     msg = EmailMessage()
@@ -176,10 +182,12 @@ def _send(to: list[str], subject: str, body: str, reply_to: str | None = None) -
             s.starttls(context=ssl.create_default_context())
             s.login(c["user"], c["password"])
             s.send_message(msg)
-        log.info("Sent email %r to %s", subject, recipients)
+        # log-pii-ok: how many, not who
+        log.info("Sent email %r to %d recipient(s)", subject, len(recipients))
         return True
     except Exception:
-        log.exception("SMTP send failed (%r to %s)", subject, recipients)
+        # log-pii-ok: how many, not who
+        log.exception("SMTP send failed (%r to %d recipient(s))", subject, len(recipients))
         _alert_admins("send_failed", subject, recipients)
         return False
 

backend/app/feedquery.py

@@ -30,7 +30,7 @@ from app.models import (
     Video,
     VideoState,
 )
-from app.utils import iso, to_tsquery_str
+from app.utils import iso, like_escape, to_tsquery_str
 
 
 def _channel_url(channel_id: str, handle: str | None) -> str:
@@ -272,8 +272,9 @@ def filtered_query(
         # `unaccent(channels.title) ILIKE '%q%'` straight into the per-video predicate defeated the
         # search_vector GIN — the planner detoasted every non-matching tsvector to test the `@@`
         # (~2.6s/search on the prod-sized set); channel_id.in_(...) keeps the GIN as a BitmapOr branch
-        # (PERF-12). Empty match -> false() so the OR collapses to the text match alone.
-        like = func.unaccent(f"%{q}%")
+        # (PERF-12). Empty match -> false() so the OR collapses to the text match alone. The query
+        # is a literal inside the pattern: `_` in `my_channel` is not a wildcard.
+        like = func.unaccent(f"%{like_escape(q)}%")
         matching_channel_ids = (
             db.execute(select(Channel.id).where(func.unaccent(Channel.title).ilike(like)))
             .scalars()

backend/app/logs.py

@@ -15,7 +15,7 @@ issue attachment will carry, so it is deliberately flat and stable.
 
 Call sites stay ordinary stdlib logging:
 
-    log = logging.getLogger("siftlode.downloads")
+    log = logs.get_logger(__name__)  # app/downloads/pipeline.py -> siftlode.downloads.pipeline
     log.info("job finished", extra=logs.event("download.job.done", job_id=7, bytes=n))
 
 `event()` is optional — a bare `log.info("…")` still comes out well-formed — but the dotted code is
@@ -37,7 +37,9 @@ import re
 import sys
 import threading
 import time
+import traceback
 import uuid
+from collections.abc import Callable
 from datetime import datetime, timezone
 from typing import Any
 from urllib.parse import parse_qsl
@@ -152,11 +154,15 @@ def bind(**fields: Any):
             _CONTEXT_VARS[key].reset(token)
 
 
-def event(code: str, **attrs: Any) -> dict[str, Any]:
+def event(code: str, /, **attrs: Any) -> dict[str, Any]:
     """`extra=` payload for a log call: a stable dotted event code plus structured attributes.
 
     Returns a plain dict so it composes with stdlib logging and costs nothing when the level is off
-    (the dict is built either way; keep the attrs cheap — no DB reads inside the call)."""
+    (the dict is built either way; keep the attrs cheap — no DB reads inside the call).
+
+    `code` is positional-only so that no attribute name is reserved: `event("x", code=...)` means
+    the attribute, not this parameter. Without the `/` it was a TypeError, and `code` is exactly
+    the word a caller reaches for when the thing that failed has one of its own."""
     return {"event": code, "attrs": attrs}
 
 
@@ -259,11 +265,53 @@ def redact(value: Any, *, key: str = "") -> Any:
 
 
 # --- formatters ----------------------------------------------------------------------------
+_SCRUBBED_STACK = "scrubbed_stack"
+
+
+def scrubbed_stack(exc: BaseException, scrub: Callable[[BaseException], str]) -> dict[str, str]:
+    """`extra=` fragment: `exc`'s traceback, rendered where an `exc_info` stack goes, with the
+    message of every exception in it put through `scrub`.
+
+    For a failure whose message can name someone's data (a download's URL, a file path, a video
+    id). The frames name code and are kept whole; the text at the foot of each link is the data.
+    A plain `exc_info` renders the chain too — the `__cause__`/`__context__` a DB error raised
+    inside `except DownloadError` carries — so scrubbing only the line's own message is not
+    enough. Merge it into the call's `extra`: `{**event(...), **scrubbed_stack(...)}`."""
+    links: list[BaseException] = []
+    link: BaseException | None = exc
+    while link is not None and all(link is not seen for seen in links):
+        links.append(link)
+        link = link.__cause__ or (None if link.__suppress_context__ else link.__context__)
+    parts: list[str] = []
+    for i in range(len(links) - 1, -1, -1):  # the oldest first, as Python prints a chain
+        link = links[i]
+        kind = type(link)
+        name = kind.__qualname__
+        if kind.__module__ not in ("builtins", "__main__"):
+            name = f"{kind.__module__}.{name}"
+        try:
+            message = scrub(link)
+        # silent-ok: the message is what could not be rendered, and the placeholder says so — the
+        # caller is in the middle of reporting one failure and must not get a second from here.
+        except Exception:  # noqa: BLE001 — a `__str__` that raises, of any shape
+            message = "<unprintable>"
+        frames = "".join(traceback.format_tb(link.__traceback__))
+        head = f"Traceback (most recent call last):\n{frames}" if frames else ""
+        parts.append(f"{head}{name}: {message}" if message else f"{head}{name}")
+        if i:
+            parts.append(
+                "\nThe above exception was the direct cause of the following exception:\n"
+                if links[i - 1].__cause__ is link
+                else "\nDuring handling of the above exception, another exception occurred:\n"
+            )
+    return {_SCRUBBED_STACK: "\n".join(parts)}
+
+
 # Attributes every LogRecord carries; anything else a caller passed via `extra=` is a structured
 # attribute and is merged into `attrs` (so `extra={"job_id": 7}` works as well as `event(...)`).
 _RECORD_STANDARD = frozenset(
     vars(logging.LogRecord("", 0, "", 0, "", None, None)).keys()
-    | {"message", "asctime", "taskName", "event", "attrs", PERSIST, "elevated"}
+    | {"message", "asctime", "taskName", "event", "attrs", PERSIST, "elevated", _SCRUBBED_STACK}
 )
 
 
@@ -314,6 +362,8 @@ def _safe_message(record: logging.LogRecord) -> str:
     must not take down the caller, so the failure is reported IN the line instead."""
     try:
         return record.getMessage()
+    # silent-ok: the failure is reported IN the returned line. Logging it would re-enter this same
+    # formatter with a record built out of the one that just failed.
     except Exception as exc:  # noqa: BLE001 — any formatting error, reported not raised
         return f"{record.msg!r} (log formatting failed: {exc})"
 
@@ -342,6 +392,8 @@ def record_fields(record: logging.LogRecord) -> dict[str, Any]:
         fields["attrs"] = redact(attrs)
     if record.exc_info:
         fields["exc"] = redact_text(logging.Formatter().formatException(record.exc_info))
+    elif getattr(record, _SCRUBBED_STACK, None):
+        fields["exc"] = redact_text(getattr(record, _SCRUBBED_STACK))
     elif record.exc_text:
         # A QueueHandler-style hand-off formats the traceback into exc_text and drops exc_info.
         fields["exc"] = redact_text(record.exc_text)
@@ -375,6 +427,8 @@ class TextFormatter(logging.Formatter):
             line += f" {json.dumps(redact(attrs), ensure_ascii=False, default=str)}"
         if record.exc_info:
             line += "\n" + redact_text(self.formatException(record.exc_info))
+        elif getattr(record, _SCRUBBED_STACK, None):
+            line += "\n" + redact_text(getattr(record, _SCRUBBED_STACK))
         return line
 
 
@@ -401,6 +455,28 @@ _THIRD_PARTY_LEVELS = {
 }
 
 
+def get_logger(name: str) -> logging.Logger:
+    """The logger for one module: `logs.get_logger(__name__)` in `app/plex/sync.py` is
+    `siftlode.plex.sync`.
+
+    The names were literals before, and 25 of them covered 34 modules — six different Plex modules
+    all called themselves `siftlode.plex`, so neither a level pinned per logger nor E22.6's console
+    filter could tell a sync line from a stream line. Derived from `__name__` there is exactly one
+    name per module, it cannot drift from the file it sits in, and `test_logger_names.py` fails if a
+    module hand-rolls one again.
+
+    `__main__` is resolved to the module it really is. The worker runs as `python -m app.worker`
+    and spawns `python -m app.downloads.runner`, so in the two long-running processes `__name__`
+    is `__main__` — taken at its word, both would log as the bare root. `-m` records the real name
+    on the module's spec; a plain script has none and stays the root."""
+    if name == "__main__":
+        spec = getattr(sys.modules.get("__main__"), "__spec__", None)
+        name = getattr(spec, "name", None) or name
+    stem = name.removeprefix("app.") if name.startswith("app.") else ""
+    # logger-name-ok: this call IS the derivation
+    return logging.getLogger(f"siftlode.{stem}" if stem else "siftlode")
+
+
 def resolve_level(name: str) -> int:
     """Level name → number. Both ways in (the `LOG_LEVEL` env and the `log_level` admin knob) are
     already held to the `LogLevel` choices, so an unknown name here is a programming error."""
@@ -562,11 +638,37 @@ def current_source() -> str:
 _REQUEST_ID_RE = re.compile(r"^[A-Za-z0-9._-]{8,64}$")
 
 # Paths whose success is logged at DEBUG rather than INFO: the container healthcheck runs every 15s
-# (5.7k lines/day saying nothing) and hashed static assets are served by the hundred per page load.
-# A FAILURE on either still logs at WARNING/ERROR — this lowers the floor, it does not hide.
-_QUIET_PREFIXES = ("/healthz", "/assets/", "/static/")
+# (5.7k lines/day saying nothing), hashed static assets are served by the hundred per page load, and
+# the admin log console reads the stored log — its live tail every few seconds, so at INFO the log
+# would fill with the console watching itself. A FAILURE on any of them still logs at WARNING/ERROR
+# — this lowers the floor, it does not hide.
+_QUIET_PREFIXES = ("/healthz", "/assets/", "/static/", "/api/admin/logs")
 
-_request_log = logging.getLogger("siftlode.http")
+# The reads the frontend POLLS (a `useLiveQuery`, the `me` heartbeat, the sync status, the subtitle
+# progress), by route template, GET only — logged at DEBUG like the prefixes above. One open tab asked
+# for the two unread counts, `/api/me` and the download index every 30 s, and at INFO those were ~95%
+# of the stored log (measured on prod 2026-09-19): 11k lines a day per tab burying every line someone
+# caused. The same route answered with a failure still logs at WARNING/ERROR.
+_POLLED_ROUTES = frozenset(
+    {
+        "/api/me",
+        "/api/me/notifications/unread_count",
+        "/api/messages/unread_count",
+        "/api/downloads",
+        "/api/downloads/index",
+        "/api/downloads/usage",
+        "/api/sync/my-status",
+        "/api/admin/scheduler",
+        "/api/admin/downloads",
+        "/api/admin/downloads/storage",
+        "/api/plex/subtitle/{rating_key}/{sub_ord}/status",
+    }
+)
+
+# Not `siftlode.logs`: this is the replacement for uvicorn's ACCESS log, and `siftlode.http` is
+# what an operator pins a level on when they want request lines and nothing else. The module it
+# happens to live in is not what the name is about.
+_request_log = logging.getLogger("siftlode.http")  # logger-name-ok: named for the traffic
 
 
 async def log_requests(request, call_next):
@@ -608,7 +710,9 @@ async def log_requests(request, call_next):
         raise
     duration_ms = round((time.perf_counter() - started) * 1000, 1)
     status = response.status_code
-    quiet = request.url.path.startswith(_QUIET_PREFIXES)
+    quiet = request.url.path.startswith(_QUIET_PREFIXES) or (
+        request.method == "GET" and _route_template(request) in _POLLED_ROUTES
+    )
     if status >= 500:
         level = logging.ERROR
     elif status >= 400:
@@ -634,6 +738,10 @@ async def log_requests(request, call_next):
         extra={**event("http.request", **attrs), **_request_owner(request, level)},
     )
     response.headers["X-Request-Id"] = rid
+    # The browser logs its own copy of this line (frontend lib/http.ts) and must pick the same level:
+    # it learns "this one is quiet" here instead of keeping a second copy of the polled-route list.
+    if level == logging.DEBUG:
+        response.headers["X-Log-Quiet"] = "1"
     # The template, so the browser's copy of this line groups the same way (frontend lib/http.ts).
     # Only a MATCHED route's: a template never carries a path parameter's value (a share token stays
     # `{token}`), while the raw-path fallback of an unmatched request could — the browser then
@@ -646,6 +754,16 @@ async def log_requests(request, call_next):
     return response
 
 
+def consented_trace() -> bool:
+    """Whether the current request's OWN user turned Teljes (TRACE) on — the gate for a line that
+    carries what they typed or what was quoted back to them. The level alone is not enough: an
+    admin running the whole process at TRACE would pass it for every user, and a scheduler thread,
+    which has no request, for none of them in particular. Guard such a line with this, then log it
+    at TRACE."""
+    scope = _scope.get()
+    return scope is not None and _traced(scope)
+
+
 def _traced(scope: _RequestScope) -> bool:
     """Whether this request's query string is logged: only under its OWN user's Teljes consent. An
     admin setting the whole process to TRACE gets more detail, not every user's search terms — the

backend/app/logsink.py

@@ -29,6 +29,7 @@ import atexit
 import json
 import logging
 import queue
+import re
 import sys
 import threading
 import time
@@ -66,7 +67,7 @@ _LIMITS = {
     "exc": 32_000,
 }
 
-_log = logging.getLogger("siftlode.logsink")
+_log = logs.get_logger(__name__)
 
 
 def should_store(record: logging.LogRecord) -> bool:
@@ -137,6 +138,21 @@ def _notice(code: str, msg: str, **attrs: Any) -> dict[str, Any]:
     )
 
 
+_DIGITS = re.compile(r"\d+")
+
+
+def _template(record: logging.LogRecord) -> str:
+    """The flood limiter's grouping key: the message template. Except when the template is a bare
+    `%s` — a pass-through for someone else's text (yt-dlp's lines, `formats._YdlLog`), where the
+    template says nothing and every distinct line would share one bucket. Then the text itself
+    groups, with its numbers folded, so `Retrying fragment 5 (1/10)` and `(2/10)` are still one
+    repeat and a different warning is not crowded out by them."""
+    msg = str(record.msg)
+    if msg != "%s" or not record.args:
+        return msg
+    return _DIGITS.sub("#", record.getMessage())[:200]
+
+
 class _Repeats:
     """Per-template admission for one minute at a time. Used by the writer thread only (unlocked)."""
 
@@ -155,9 +171,11 @@ class _Repeats:
         self.seen[key] = (count or 0) + 1
         return self.seen[key] <= self.per_window
 
-    def roll(self, now: float) -> list[dict[str, Any]]:
-        """Close the window if it is over: one notice per template that went past the limit."""
-        if now - self.started < self.window:
+    def roll(self, now: float, *, final: bool = False) -> list[dict[str, Any]]:
+        """Close the window if it is over — or, `final`, because the process is: one notice per
+        template that went past the limit. Without `final` a process that lives under a minute
+        (every download child) would drop its repeats and never say so."""
+        if not final and now - self.started < self.window:
             return []
         notices = [
             _notice(
@@ -202,6 +220,8 @@ class LogSink(logging.Handler):
             return
         try:
             row = to_row(logs.record_fields(record))
+        # silent-ok: `handleError` is the report — logging's own out-of-band channel to stderr.
+        # A log call here would be handed to this handler, which is the one that just failed.
         except Exception:  # noqa: BLE001 — a record we cannot turn into a row is reported, not raised
             self.handleError(record)
             return
@@ -209,21 +229,25 @@ class LogSink(logging.Handler):
         key = (
             None
             if row["event"] == "http.request"
-            else (record.name, str(record.msg), record.levelno)
+            else (record.name, _template(record), record.levelno)
         )
         try:
             self._queue.put_nowait((key, row))
+        # silent-ok: counted, not logged — the count goes out as the `log.sink.dropped` notice row
+        # the writer emits, which is the one report that does not feed this queue again.
         except queue.Full:
             with self._dropped_lock:
                 self._dropped += 1
 
     # --- writer side ---------------------------------------------------------------------------
-    def write_pending(self, wait: float = 0.0) -> int:
+    def write_pending(self, wait: float = 0.0, *, final: bool = False) -> int:
         """Write one batch: whatever is queued (up to BATCH_MAX), waiting up to `wait` seconds for the
-        first item. Returns the number of rows written, notices included."""
+        first item. Returns the number of rows written, notices included. `final` closes the
+        repeat window early — the last batch before the process exits."""
         rows: list[dict[str, Any]] = []
         try:
             item = self._queue.get(timeout=wait) if wait > 0 else self._queue.get_nowait()
+        # silent-ok: an idle sink. Nothing failed; there was simply nothing waiting.
         except queue.Empty:
             item = None
         while item is not None:
@@ -234,9 +258,10 @@ class LogSink(logging.Handler):
                 break
             try:
                 item = self._queue.get_nowait()
+            # silent-ok: the batch ends here because the queue ran dry, which is the normal end.
             except queue.Empty:
                 item = None
-        rows.extend(self._repeats.roll(time.monotonic()))
+        rows.extend(self._repeats.roll(time.monotonic(), final=final))
         with self._dropped_lock:
             dropped, self._dropped = self._dropped, 0
         if dropped:
@@ -254,8 +279,12 @@ class LogSink(logging.Handler):
             with self._bind.connect() as conn, logs.erasure_guard(), conn.begin():
                 conn.execute(insert(LogEvent), without_erased(rows))
         except Exception as exc:  # noqa: BLE001 — the database is down or refused the batch
-            print(
-                f"log sink: could not store {len(rows)} log events: {logs.redact_text(str(exc))[:300]}",
+            # silent-ok / noqa T201: the sink's OWN failure. A log call here would be handed to
+            # this sink, which is the thing that just failed — straight into a loop. stderr is
+            # the one way out that does not re-enter.
+            print(  # noqa: T201
+                f"log sink: could not store {len(rows)} log events: "
+                f"{logs.redact_text(str(exc))[:300]}",
                 file=sys.stderr,
             )
             return 0
@@ -266,6 +295,7 @@ class LogSink(logging.Handler):
             self.write_pending(wait=FLUSH_SECONDS)
         while self.write_pending():  # drain what arrived before the stop
             pass
+        self.write_pending(final=True)  # and the repeat notices of a window cut short
 
     def start(self) -> None:
         self._writer = threading.Thread(target=self._run, name="log-sink", daemon=True)

backend/app/main.py

@@ -1,5 +1,4 @@
 import asyncio
-import logging
 import math
 from contextlib import asynccontextmanager, suppress
 from pathlib import Path
@@ -12,11 +11,12 @@ from fastapi.exceptions import RequestValidationError
 # import time is already covered. ONE format for the api, the worker, the download child and alembic
 # alike (app/logs.py) — this replaces the old uvicorn --log-config + the hand-rolled fallback that
 # used to live here, and uvicorn's access log is replaced by the `http.request` middleware below.
+from app import logs
 from app.logs import configure_logging, current_level, log_requests, set_level
 
 configure_logging("api")
 
-log = logging.getLogger("siftlode.app")
+log = logs.get_logger(__name__)
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
@@ -32,6 +32,7 @@ from app.plex import stream as plex_stream
 from app.plex import subtitles as plex_subtitles
 from app.routes import (
     admin,
+    admin_logs as admin_logs_routes,
     audit as audit_routes,
     auth as auth_routes,
     channels,
@@ -73,17 +74,17 @@ async def lifespan(app: FastAPI):
         # booting — an unreachable or not-yet-migrated database has to start into the env level.
         try:
             set_level(sysconfig.get_str(db, "log_level"))
-        except Exception as exc:  # noqa: BLE001 — any DB/config failure keeps the bootstrap level
-            log.warning(
-                "could not read the stored log level (%s); staying at %s", exc, current_level()
-            )
+        except Exception:  # noqa: BLE001 — any DB/config failure keeps the bootstrap level
+            # With the traceback: this catch spans a connection, a query and a coercion at boot,
+            # and `%s` of the exception does not say which of them raised.
+            log.exception("could not read the stored log level; staying at %s", current_level())
         if not state.is_configured(db):
             token = state.rotate_setup_token(db)
             url = f"{settings.app_base}/setup?token={token}"
             log.warning(
                 "FIRST-RUN SETUP REQUIRED — this instance isn't configured yet.\n"
                 "    Open the install wizard (internal access only):\n    %s",
-                url,
+                url,  # log-pii-ok: this instance's OWN setup URL, and `?token=` is redacted
             )
     # No HLS session survives a restart (they live in this process), so anything still on disk is
     # a crashed run's segments — sweep them or they accumulate forever. FIRE AND FORGET, not
@@ -285,6 +286,7 @@ app.include_router(admin.router)
 app.include_router(config_routes.router)
 app.include_router(scheduler_routes.router)
 app.include_router(audit_routes.router)
+app.include_router(admin_logs_routes.router)
 app.include_router(quota.router)
 app.include_router(version.router)
 app.include_router(setup_routes.router)

backend/app/models.py

@@ -241,6 +241,9 @@ class Channel(Base, TimestampMixin):
     details_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     recent_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     last_rss_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    # When the newest uploads were last read through the Data API because the RSS feed would not
+    # answer (`sync/runner.py` `run_feed_fallback`): the once-per-`rss_fallback_hours` clock.
+    feed_fallback_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     backfill_cursor: Mapped[str | None] = mapped_column(String(128))
     backfill_done: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
     # True when this channel only entered the catalog because a live YouTube search

backend/app/plex/client.py

@@ -6,16 +6,15 @@ metadata, image proxying, and (P5) optional watch-state write-back. Requests JSO
 ``Accept: application/json`` header (Plex serves XML by default).
 """
 
-import logging
 from urllib.parse import quote
 
 import httpx
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
 
-log = logging.getLogger("siftlode.plex")
+log = logs.get_logger(__name__)
 
 
 class PlexError(Exception):
@@ -106,7 +105,18 @@ class PlexClient:
         Best-effort (needs the library's related data) — returns [] if Plex has none."""
         try:
             mc = self._get(f"/library/metadata/{rating_key}/related")
-        except PlexError:
+        except PlexError as exc:
+            # An empty list is also the answer for an item that genuinely has no related titles,
+            # so the caller cannot tell the two apart — and it deliberately declines to CACHE an
+            # empty one for exactly that reason. This line is what says which it was.
+            log.debug(
+                "the related items for a Plex item could not be read",
+                extra=logs.event(
+                    "plex.client.related_unavailable",
+                    rating_key=rating_key,
+                    reason=type(exc).__name__,
+                ),
+            )
             return []
         out: list[dict] = []
         for hub in mc.get("Hub", []) or []:
@@ -139,6 +149,8 @@ class PlexClient:
             raise PlexError(str(e)) from e
         try:
             return (r.json() or {}).get("MediaContainer", {}) or {} if r.content else {}
+        # silent-ok: the HTTP call already succeeded — this is a write endpoint, and Plex answers
+        # those with an empty or non-JSON body as a matter of course.
         except ValueError:
             return {}
 

backend/app/plex/detail.py

@@ -22,6 +22,8 @@ def rich_detail(meta: dict) -> dict:
         if str(r.get("image") or "").startswith("imdb://"):
             try:
                 imdb_rating = round(float(r.get("value")), 1)
+            # silent-ok: no IMDb score, which is the common and legitimate case — the UI has a
+            # separate audience score to fall back on and shows nothing if neither exists.
             except (TypeError, ValueError):
                 pass
             break

backend/app/plex/imgcache.py

@@ -11,10 +11,13 @@ The cache directory (``cache.CACHE_DIR``) is shared with the subtitle cache (see
 from fastapi import Response
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.models import PlexCollection, PlexItem, PlexSeason, PlexShow
 from app.plex.cache import CACHE_DIR
 from app.plex.lookups import by_rating_key
 
+log = logs.get_logger(__name__)
+
 _EXT_CT = [("jpg", "image/jpeg"), ("png", "image/png"), ("webp", "image/webp")]
 _CT_EXT = {ct: ext for ext, ct in _EXT_CT}
 # Target box per variant — Plex resizes to these server-side. Posters fill ≤176px cells (grid/info/
@@ -46,6 +49,8 @@ def read(key: str) -> tuple[bytes, str] | None:
         try:
             if p.exists() and p.stat().st_size > 0:
                 return p.read_bytes(), ct
+        # silent-ok: a miss. The caller fetches from Plex and writes the file again, and the write
+        # path below is the one that reports a cache that cannot be used.
         except OSError:
             pass
     return None
@@ -58,8 +63,14 @@ def write(key: str, data: bytes, ct: str) -> None:
         tmp = CACHE_DIR / f"{key}.{ext}.tmp"
         tmp.write_bytes(data)
         tmp.replace(CACHE_DIR / f"{key}.{ext}")  # atomic publish
-    except OSError:
-        pass  # cache is best-effort
+    except OSError as exc:
+        # Best-effort, and silently so: with an unwritable cache every poster on every grid goes
+        # to Plex live, for as long as nobody notices. Debug, because a grid is ~100 images and
+        # the point is the condition, not the count.
+        log.debug(
+            "the Plex image cache could not be written",
+            extra=logs.event("plex.imgcache.write_failed", reason=type(exc).__name__),
+        )
 
 
 def response(data: bytes, ct: str) -> Response:

backend/app/plex/paths.py

@@ -12,7 +12,9 @@ from pathlib import Path
 
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
+
+log = logs.get_logger(__name__)
 
 
 def parse_map(raw: str) -> list[tuple[str, str]]:
@@ -47,6 +49,13 @@ def local_media_path(db: Session, plex_path: str | None) -> Path | None:
         return None
     try:
         p = Path(map_path(db, plex_path)).resolve()
-    except OSError:
+    except OSError as exc:
+        # None is answered as a 404 "no local file", which is also the answer for a title the
+        # server does not hold — so a dead mount or a wrong path map reads as missing media for
+        # the whole library at once. The path itself stays out: it carries the title.
+        log.warning(
+            "a Plex media path could not be resolved locally",
+            extra=logs.event("plex.paths.resolve_failed", reason=type(exc).__name__),
+        )
         return None
     return p if p.is_file() else None

backend/app/plex/query.py

@@ -298,10 +298,6 @@ class LibraryFilters:
         }
 
 
-def like_escape(s: str) -> str:
-    return s.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
-
-
 # --- Watch-state scope (shared by the /library grid AND the /facets aggregation) ---------------
 #
 # The `show` scope (all | watched | in_progress | unwatched) filters the browse result by per-user

backend/app/plex/rollup.py

@@ -43,7 +43,9 @@ def rollup(cards: list[dict]) -> dict:
     ]
     resume = None
     if inprog:
-        resume = inprog[-1]  # continue the latest-started episode
+        # The LAST in-progress episode in broadcast order — no timestamp is consulted. Home's
+        # `discover.queries.next_episode` picks the same one, so both Resume buttons agree.
+        resume = inprog[-1]
     else:
         resume = next((c for c in cards if c.get("status") != "watched"), None)
     return {

backend/app/plex/stream.py

@@ -18,7 +18,6 @@ segments. The remux is CPU-light (video copy + a tiny audio transcode), so it ru
 CPU-only prod host; only P3's full transcode is CPU-heavy.
 """
 
-import logging
 import os
 import re
 import secrets
@@ -31,15 +30,14 @@ from pathlib import Path
 
 from sqlalchemy.orm import Session as DbSession
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
 from app.downloads.edit import encode_thread_cap
 from app.models import PlexItem
 from app.plex import paths
 from app.plex.sync import HW_DECODABLE_CODECS
 
-log = logging.getLogger("siftlode.plex")
-
+log = logs.get_logger(__name__)
 _HLS_ROOT = (
     Path(settings.plex_hls_dir)
     if settings.plex_hls_dir
@@ -62,8 +60,10 @@ _WARMUP_SEG_TIMEOUT_S = 8.0
 # its index for that one. See `segment_name` for why this is a constant and not a comment.
 _VIDEO_VARIANT = "0"
 _SESSION_IDLE_S = 600  # reap a session with no access for this long
-# A session directory is named `{rating_key}_{int(start_s)}_{tag}_{aoff:+.2f}` (see start_session);
-# before multi-audio it was just `{rating_key}_{int(start_s)}`. `sweep_orphans` deletes ONLY names
+# A session directory is named `{rating_key}_u{user_id}_{int(start_s)}_{tag}_{aoff:+.2f}` (see
+# start_session); before per-viewer sessions it was `{rating_key}_{int(start_s)}_{tag}_{aoff:+.2f}`,
+# and before multi-audio just `{rating_key}_{int(start_s)}` — the older shapes stay sweepable, since a
+# restart leaves them behind like any other. `sweep_orphans` deletes ONLY names
 # matching one of those two shapes: `_HLS_ROOT` is admin-configurable (PLEX_HLS_DIR), so it may
 # legitimately point at a shared scratch path we do not own, and a blanket "delete every directory
 # under the root" would take the neighbours with it.
@@ -74,7 +74,9 @@ _SESSION_IDLE_S = 600  # reap a session with no access for this long
 # non-numeric rating_key would merely leave its directory unswept, which is the safe direction to
 # fail. Covered by test_plex_stream.py — this regex is the only thing standing between the sweep
 # and someone else's data.
-_SESSION_DIR_RE = re.compile(r"^\d+_\d+(_[^_]+_[+-]\d+\.\d{2})?$")
+_SESSION_DIR_RE = re.compile(
+    r"^\d+_\d+(_[^_]+_[+-]\d+\.\d{2})?$|^\d+_u\d+_\d+_[^_]+_[+-]\d+\.\d{2}$"
+)
 # When this process started. `sweep_orphans` only deletes directories older than this: everything
 # newer belongs to a session THIS run created, and since `start_session` reuses a directory path
 # for the same (rating_key, offset, tag), "stale name" is not the same as "stale directory".
@@ -90,7 +92,16 @@ _PROCESS_START = time.time()
 _MTIME_GRACE_S = 2.0
 
 _lock = threading.Lock()
-_sessions: dict[str, "HlsSession"] = {}
+# Keyed by VIEWER and item, (user_id, rating_key). Keyed by the item alone, a second account opening
+# the same film `_kill`ed the first one's session: the displaced viewer got a 404, reclaimed at its
+# playhead, and so evicted the other in turn — two people could not watch one film at once. (One
+# account on two devices still shares a session; that case ends in the player's bounded reclaim.)
+_sessions: dict[tuple[int, str], "HlsSession"] = {}
+# How many live sessions one account may hold at once (two devices, or a next item starting while the
+# last one winds down). A new one past it replaces that account's least recently used — whose waiting
+# session request then returns at once, since `wait_for` watches the killed ffmpeg — so one account
+# can neither pile up film-sized scratch copies nor park more than this many request workers.
+_MAX_SESSIONS_PER_USER = 2
 
 
 class HlsSession:
@@ -104,16 +115,17 @@ class HlsSession:
         transcode: bool = False,
         hw: bool = False,
         tonemap: bool = False,
+        user_id: int = 0,
     ):
-        # Unguessable per-session id, carried in the URLs the client is handed. Sessions are keyed
-        # by rating_key alone, so a seek-restart or a SECOND viewer of the same item replaces the
-        # registered one — and the old viewer's next request for `seg_12.ts`, resolved by rating_key,
-        # was answered 200 with the NEW session's twelfth segment, produced from a different offset
+        # Unguessable per-session id, carried in the URLs the client is handed. A seek-restart
+        # replaces the viewer's registered session for the item — and the old player's next request
+        # for `seg_12.ts`, resolved by (viewer, rating_key) alone, was answered 200 with the NEW session's twelfth segment, produced from a different offset
         # under `-copyts`. Wrong bytes, not an error, so the client's reclaim never fired on it
         # (deep-review round 5). A request naming a session that is no longer registered is a 404,
         # which the player recovers from by restarting at the playhead.
         self.id = secrets.token_urlsafe(9)
-        self.key = key
+        self.key = key  # the item's rating_key (what the logs name)
+        self.user_id = user_id  # whose session it is: the registry key is (user_id, key)
         self.dir = directory
         self.proc = proc
         self.transcode = transcode  # video re-encoded (non-h264 source), not stream-copied
@@ -135,6 +147,8 @@ class HlsSession:
         # single index. Derived, not passed, so it cannot disagree with the argv.
         self.entry = _MASTER_PL if self.variants else _INDEX_PL
         self.last_access = time.time()
+        # `artifact_may_arrive` reports a refusing session directory once, not per segment.
+        self.probe_failure_reported = False
 
 
 def _seek_opts(start_s: float) -> list[str]:
@@ -232,7 +246,15 @@ def _probe_video_kind(src: Path) -> str:
             text=True,
             timeout=10,
         )
-    except (subprocess.SubprocessError, OSError):
+    except (subprocess.SubprocessError, OSError) as exc:
+        # The safe kind is a real answer, but it is the answer for an 8-bit SDR source — a blind
+        # ffprobe sends every HDR file down it, so playback quietly degrades to a software
+        # transcode with nothing anywhere saying why. The path stays out of the line: it is the
+        # title of whatever is playing.
+        log.info(
+            "video-kind probe failed; assuming the HW-safe pipeline",
+            extra=logs.event("plex.stream.probe_kind_failed", reason=type(exc).__name__),
+        )
         return _VK_HWSAFE
     pix_fmt = bits = transfer = ""
     for line in out.stdout.splitlines():
@@ -261,7 +283,14 @@ def _opencl_present() -> bool:
     software libx264. Its own function so it's monkeypatchable in tests, mirroring _render_node_present."""
     try:
         return any(_OPENCL_ICD_DIR.glob("*.icd"))
-    except OSError:
+    except OSError as exc:
+        # A MISSING directory does not come through here — `glob` simply yields nothing for one.
+        # This is a directory we cannot read, and the answer it forces (no OpenCL) costs every HDR
+        # source the hardware tonemap path.
+        log.info(
+            "the OpenCL ICD directory could not be read; treating OpenCL as absent",
+            extra=logs.event("plex.stream.opencl_probe_failed", reason=type(exc).__name__),
+        )
         return False
 
 
@@ -447,6 +476,8 @@ def _sw_child_preexec() -> None:
     playback."""
     try:
         os.nice(_SW_TRANSCODE_NICE)
+    # silent-ok: this runs in the forked child, between fork and exec. Logging there can deadlock
+    # on a lock some other thread held at fork time, and the child is about to become ffmpeg.
     except OSError:
         pass
 
@@ -473,7 +504,14 @@ def _probe_audio_langs(src: Path) -> list[str]:
             timeout=10,
         )
         return [ln.strip() for ln in out.stdout.splitlines()]
-    except (subprocess.SubprocessError, OSError):
+    except (subprocess.SubprocessError, OSError) as exc:
+        # An empty list IS the single-audio path, so a failed probe silently collapses a file with
+        # several audio tracks down to one — and the viewer gets a player with no language picker
+        # rather than an error.
+        log.warning(
+            "audio-track probe failed; falling back to a single-audio session",
+            extra=logs.event("plex.stream.probe_audio_failed", reason=type(exc).__name__),
+        )
         return []
 
 
@@ -582,8 +620,14 @@ def _probe_first_pts(seg: Path) -> float | None:
             tok = line.strip().strip(",")
             if tok:
                 return float(tok)
-    except (subprocess.SubprocessError, ValueError, OSError):
-        pass
+    except (subprocess.SubprocessError, ValueError, OSError) as exc:
+        # None means "keep the offset the client asked for", and the whole point of this probe is
+        # that the two differ: without it the subtitle track is shifted by whatever the container
+        # started its timestamps at. Seconds of drift, and nothing on screen calls it a failure.
+        log.warning(
+            "first-PTS probe failed; the requested offset is used as-is",
+            extra=logs.event("plex.stream.first_pts_probe_failed", reason=type(exc).__name__),
+        )
     return None
 
 
@@ -592,29 +636,62 @@ def _kill(s: HlsSession) -> None:
         s.proc.terminate()
         try:
             s.proc.wait(timeout=3)
+        # silent-ok: the escalation IS the handling. A transcode that ignores TERM for three
+        # seconds gets KILL, which is exactly what this branch does.
         except subprocess.TimeoutExpired:
             s.proc.kill()
-    except Exception:
-        pass
+    except Exception as exc:  # noqa: BLE001 — teardown finishes whatever the process does
+        # Not nothing: what survives this is an ffmpeg nobody owns any more, holding a VAAPI
+        # handle and a core, and the transcode cap that is supposed to bound them counts rows in
+        # `_sessions` rather than processes. One line is the only way that ever surfaces.
+        log.info(
+            "could not stop the transcode process",
+            extra=logs.event("plex.stream.kill_failed", key=s.key, reason=type(exc).__name__),
+        )
     shutil.rmtree(s.dir, ignore_errors=True)
 
 
-def _enforce_cap(cap: int) -> None:
-    # Caller holds _lock. Only TRANSCODE sessions count toward plex_max_transcodes — remux
-    # (stream-copy) and direct-serve are cheap and deliberately uncapped (see config.py:
-    # plex_max_transcodes, and the user-facing config hint). Drop the least-recently-accessed
-    # transcode sessions over the cap, leaving any concurrent remux streams untouched.
-    tx = [(key, s) for key, s in _sessions.items() if s.transcode]
-    if len(tx) <= cap:
-        return
-    for key, s in sorted(tx, key=lambda kv: kv[1].last_access)[: len(tx) - cap]:
-        _kill(s)
-        _sessions.pop(key, None)
+def _enforce_caps(user_id: int, max_transcodes: int, max_sessions: int) -> None:
+    """Caller holds _lock. Three bounds, applied after a session is registered, each dropping the
+    least recently accessed sessions over it:
+
+    * this account's own sessions (`_MAX_SESSIONS_PER_USER`) — first, so a single account filling the
+      box evicts itself before anyone else;
+    * TRANSCODE sessions (plex_max_transcodes): the CPU/GPU-heavy ones;
+    * EVERY session (plex_max_sessions). A remux is cheap on the CPU but not on the disk: each one is a
+      whole segmented copy of the film under `_HLS_ROOT`, written faster than realtime. Counted only
+      by the transcode cap, N distinct items were N ffmpegs and N film-sized scratch directories.
+
+    Somebody's playback stops at each drop. The route turns the missing session into a retryable 404
+    and the player restarts at the playhead, so from the server nothing failed — and "my film keeps
+    rebuffering" has no other explanation anywhere, hence the line."""
+
+    def cull(pool: list[tuple[tuple[int, str], HlsSession]], cap: int, bound: str) -> None:
+        if len(pool) <= cap:
+            return
+        for reg, sess in sorted(pool, key=lambda kv: kv[1].last_access)[: len(pool) - cap]:
+            log.info(
+                "a session was dropped to stay under a cap",
+                extra=logs.event(
+                    "plex.stream.session_culled",
+                    key=sess.key,
+                    bound=bound,
+                    cap=cap,
+                    sessions=len(pool),
+                ),
+            )
+            _kill(sess)
+            _sessions.pop(reg, None)
+
+    cull([kv for kv in _sessions.items() if kv[0][0] == user_id], _MAX_SESSIONS_PER_USER, "user")
+    cull([kv for kv in _sessions.items() if kv[1].transcode], max_transcodes, "transcode")
+    cull(list(_sessions.items()), max_sessions, "total")
 
 
 def start_session(
     db: DbSession,
     item: PlexItem,
+    user_id: int,
     start_s: float,
     audio_ord: int | None = None,
     aoff: float = 0.0,
@@ -634,6 +711,7 @@ def start_session(
     # session respawn (the HW->SW fallback) must not pick up a mid-playback config change.
     loudnorm = sysconfig.get_bool(db, "plex_audio_loudnorm")
     key = item.rating_key
+    reg = (user_id, key)  # the registry key: one session per viewer per item
     start_s = max(0.0, float(start_s))
     audio_langs = _probe_audio_langs(src) if multi else []
     is_multi = len(audio_langs) > 1  # only worth a master playlist when there really are ≥2 tracks
@@ -646,7 +724,7 @@ def start_session(
     # the tag with a DASH — `_SESSION_DIR_RE` treats the tag as one underscore-free field, and that
     # regex is the only thing keeping the orphan sweep off a shared scratch path (see its comment).
     tag = ("multi" if is_multi else str(audio_ord)) + ("-ln" if loudnorm else "")
-    directory = _HLS_ROOT / f"{key}_{int(start_s)}_{tag}_{aoff:+.2f}"
+    directory = _HLS_ROOT / f"{key}_u{user_id}_{int(start_s)}_{tag}_{aoff:+.2f}"
 
     def _seg(i: int) -> Path:
         return directory / segment_name(i, _VIDEO_VARIANT if variants else None)
@@ -672,9 +750,9 @@ def start_session(
         # platform without fork (the API always runs in a Linux container in prod) it's simply omitted.
         preexec = _sw_child_preexec if (transcode and not hw and os.name == "posix") else None
         with _lock:
-            if replace_only is not None and _sessions.get(key) is not replace_only:
+            if replace_only is not None and _sessions.get(reg) is not replace_only:
                 return None  # superseded/culled while we waited out of lock — don't clobber the newer one
-            old = _sessions.pop(key, None)
+            old = _sessions.pop(reg, None)
             if old is not None:
                 _kill(old)
             shutil.rmtree(directory, ignore_errors=True)
@@ -708,11 +786,31 @@ def start_session(
                 transcode=transcode,
                 hw=hw,
                 tonemap=tonemap,
+                user_id=user_id,
+            )
+            _sessions[reg] = s
+            # The one line that says which pipeline a session actually got. Everything downstream
+            # — the cap, the HW→SW fallback, the subtitle offset — is about this choice, and until
+            # now it was only inferable from the ffmpeg command nobody keeps.
+            log.info(
+                "an HLS session started",
+                extra=logs.event(
+                    "plex.stream.session_started",
+                    key=key,
+                    transcode=transcode,
+                    hw=hw,
+                    tonemap=tonemap,
+                    variants=len(variants or ()),
+                    start_s=round(start_s, 1),
+                ),
+            )
+            # Admin-configurable caps (Configuration → Plex); at least 1 each so playback can't be
+            # capped to zero.
+            _enforce_caps(
+                user_id,
+                max(1, sysconfig.get_int(db, "plex_max_transcodes")),
+                max(1, sysconfig.get_int(db, "plex_max_sessions")),
             )
-            _sessions[key] = s
-            # Admin-configurable concurrency cap (Configuration → Plex → Max concurrent transcodes);
-            # at least 1 so playback can't be capped to zero.
-            _enforce_cap(max(1, sysconfig.get_int(db, "plex_max_transcodes")))
         return s
 
     s = _spawn(*_select_encode(db, item, transcode, src))
@@ -728,7 +826,8 @@ def start_session(
         # ONE lock in _spawn, so we can never tear down the newer session. s.hw is now False, so the route
         # honestly reports "CPU" and the player's Preparing-stream state stays correct.
         log.warning(
-            "plex transcode: HW session produced no segments — falling back to software key=%s", key
+            "the hardware transcode produced no segments; falling back to software",
+            extra=logs.event("plex.stream.hw_fallback", key=key),
         )
         respawned = _spawn(False, False, replace_only=s)
         if respawned is None:
@@ -737,7 +836,7 @@ def start_session(
             # turns a None return into a "Media file not found on disk" 404 — dishonest for a file that
             # exists. A (dead) session instead degrades to a retryable 404 ("No active playback session" /
             # "Not available yet") the client re-requests.
-            return current_session(key) or s
+            return current_session(user_id, key) or s
         s = respawned
         ready = wait_for(_seg(0), timeout=25.0, proc=s.proc)
     if ready:
@@ -768,9 +867,9 @@ def start_session(
     return s
 
 
-def current_session(key: str) -> HlsSession | None:
+def current_session(user_id: int, key: str) -> HlsSession | None:
     with _lock:
-        s = _sessions.get(key)
+        s = _sessions.get((user_id, key))
         if s is not None:
             s.last_access = time.time()
         return s
@@ -867,7 +966,23 @@ def artifact_may_arrive(s: "HlsSession", filename: str) -> bool:
         return True
     try:
         return (s.dir / segment_name(seq - 1, variant)).exists()
-    except OSError:
+    except OSError as exc:
+        # `exists()` answers False for a missing file without raising, so this is the session
+        # directory itself refusing — a full or unmounted disk. Every segment then 404s, which the
+        # player shows as a stall. Once per session: this runs for every segment request and
+        # every hls.js retry of one, and the sink's limiter still stores 30 a minute of a
+        # template — stdout would get them all.
+        if not s.probe_failure_reported:
+            s.probe_failure_reported = True
+            log.warning(
+                "a session segment could not be checked",
+                extra=logs.event(
+                    "plex.stream.segment_probe_failed",
+                    key=s.key,
+                    seq=seq,
+                    reason=type(exc).__name__,
+                ),
+            )
         return False
 
 
@@ -884,12 +999,16 @@ def wait_for(path: Path, timeout: float = 20.0, proc: subprocess.Popen | None =
         try:
             if path.exists() and path.stat().st_size > 0:
                 return True
+        # silent-ok: this is a 150 ms poll — a line here is a line every 150 ms for the whole
+        # timeout. The final check below decides, and the 404 the caller then returns is honest.
         except OSError:
             pass
         if proc is not None and proc.poll() is not None:
             # the producer exited — no more segments are coming; one last check then give up.
             try:
                 return path.exists() and path.stat().st_size > 0
+            # silent-ok: one last look after the producer exited. False here becomes a 404 the
+            # player recovers from, which is the honest answer either way.
             except OSError:
                 return False
         time.sleep(0.15)
@@ -922,7 +1041,16 @@ def sweep_orphans(older_than: float | None = None) -> int:
     dropped = 0
     try:
         entries = list(_HLS_ROOT.iterdir())
-    except OSError:  # the root doesn't exist yet — nothing to sweep
+    # silent-ok: nothing has been transcoded yet, so there is nothing to sweep.
+    except FileNotFoundError:
+        return 0
+    except OSError as exc:
+        # Any OTHER reason the root will not list is not "nothing to sweep": the sweep reports 0
+        # like a clean run while every crashed session's segments stay on disk forever.
+        log.warning(
+            "the HLS root could not be listed; no orphans were swept",
+            extra=logs.event("plex.stream.sweep_root_unreadable", reason=type(exc).__name__),
+        )
         return 0
     for p in entries:
         if not _SESSION_DIR_RE.match(p.name):
@@ -932,7 +1060,9 @@ def sweep_orphans(older_than: float | None = None) -> int:
         try:
             if p.stat().st_mtime >= cutoff:
                 continue  # this run made (or reused) it — never ours to delete
-        except OSError:  # vanished under us (a concurrent restart of that session)
+        # silent-ok: vanished under us — a concurrent restart of that session removed it, which
+        # is the outcome this sweep wanted anyway.
+        except OSError:
             continue
         with _lock:
             if any(s.dir == p for s in _sessions.values()):
@@ -968,21 +1098,21 @@ def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
     now = time.time()
     dropped = 0
     with _lock:
-        for key, s in list(_sessions.items()):
+        for reg, s in list(_sessions.items()):
             done = s.proc.poll() is not None
             idle = now - s.last_access
             if idle > _SESSION_IDLE_S or (done and idle > finished_idle_s):
                 _kill(s)
-                _sessions.pop(key, None)
+                _sessions.pop(reg, None)
                 dropped += 1
     return dropped
 
 
-def touch_session(key: str) -> None:
-    """Say a viewer is still there for `key`, without fetching anything. `last_access` used to move
+def touch_session(user_id: int, key: str) -> None:
+    """Say this viewer is still there for `key`, without fetching anything. `last_access` used to move
     only on an HLS file fetch, which a paused player does not do — so the only way to keep a paused
     viewer's session alive was to keep EVERY abandoned one just as long."""
     with _lock:
-        s = _sessions.get(key)
+        s = _sessions.get((user_id, key))
         if s is not None:
             s.last_access = time.time()

backend/app/plex/subtitles.py

@@ -33,17 +33,18 @@ zero-based clock and shifted back to absolute time here with `shift_vtt`.
 """
 
 import json
-import logging
 import re
 import subprocess
 import tempfile
 import threading
 import time
+import logging
 from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.db import SessionLocal
 from app.models import PlexItem
 from app.plex import paths as plex_paths
@@ -51,8 +52,7 @@ from app.plex.cache import CACHE_DIR
 from app.plex.client import PlexClient, PlexError
 from app.plex.lookups import by_rating_key
 
-log = logging.getLogger("siftlode.plex")
-
+log = logs.get_logger(__name__)
 # Image-based subtitle codecs (Blu-ray/DVD) — can't be turned into text WebVTT (would need burn-in).
 BITMAP_SUBS = {
     "pgs",
@@ -104,6 +104,7 @@ def shift_vtt(vtt: str, offset: float) -> str:
     straddling 0 is clamped to start at 0."""
     if not offset:
         return vtt
+    unshifted = 0
     out_blocks: list[str] = []
     for block in re.split(r"\n[ \t]*\n", vtt):
         if "-->" not in block:
@@ -121,7 +122,12 @@ def shift_vtt(vtt: str, offset: float) -> str:
                 st = _vtt_ts_to_s(left.strip()) - offset
                 en = _vtt_ts_to_s(rparts[0]) - offset
             except (ValueError, IndexError):
-                break  # unparseable timing → leave the block as-is
+                # silent-ok: left as-is means left UNSHIFTED — the viewer sees that one cue at
+                # the wrong moment. Counted rather than logged here: this is per cue, and the file
+                # being parsed is one ffmpeg wrote for us a moment ago, so a broken timestamp is
+                # a fact about the extraction, reported once below.
+                unshifted += 1
+                break
             if en <= 0:
                 keep = False  # whole cue is before the session start → drop the block
             else:
@@ -131,6 +137,11 @@ def shift_vtt(vtt: str, offset: float) -> str:
             break
         if keep:
             out_blocks.append("\n".join(lines))
+    if unshifted:
+        log.info(
+            "some cues could not be shifted and stay at their original time",
+            extra=logs.event("plex.subtitles.cues_unshifted", cues=unshifted, offset_s=offset),
+        )
     return "\n\n".join(out_blocks)
 
 
@@ -162,7 +173,15 @@ def cache_read(key: str) -> str | None:
     try:
         p = CACHE_DIR / f"{key}.vtt"
         return p.read_text(encoding="utf-8") if p.exists() else None
-    except OSError:
+    except OSError as exc:
+        # None is the same answer as "never cached", so a cache we cannot read looks exactly like
+        # a cold one — and every request re-extracts instead of saying the disk is the problem.
+        log.warning(
+            "the cached subtitle could not be read",
+            extra=logs.event(
+                "plex.subtitles.cache_read_failed", key=key, reason=type(exc).__name__
+            ),
+        )
         return None
 
 
@@ -175,7 +194,16 @@ def cache_write(key: str, vtt: str) -> bool:
         tmp.write_text(vtt, encoding="utf-8")
         tmp.replace(CACHE_DIR / f"{key}.vtt")  # atomic publish
         return True
-    except OSError:
+    except OSError as exc:
+        # `publish` turns False into "the region was not claimed" and moves on, so the track just
+        # never appears. Which errno it was — full disk, read-only mount, permissions — is the
+        # whole diagnosis, and it exists only here.
+        log.warning(
+            "the subtitle cache could not be written",
+            extra=logs.event(
+                "plex.subtitles.cache_write_failed", key=key, reason=type(exc).__name__
+            ),
+        )
         return False
 
 
@@ -206,7 +234,17 @@ def read_meta(key: str) -> tuple[list[list[float]], bool]:
     try:
         raw = json.loads(_meta_path(key).read_text(encoding="utf-8"))
         return [[float(a), float(b)] for a, b in raw.get("ranges", [])], bool(raw.get("complete"))
-    except (OSError, ValueError, TypeError):
+    # silent-ok: no sidecar at all is the documented older-build case the fallback exists for.
+    except FileNotFoundError:
+        return ([[0.0, _FULL_END_S]], True) if _exists(_vtt_path(key)) else ([], False)
+    except (OSError, ValueError, TypeError) as exc:
+        # A sidecar that EXISTS and will not parse is different, and the fallback is the dangerous
+        # answer to it: beside a cached VTT it reports the track as complete, so a partial track is
+        # never extended again and the viewer loses every cue past the window that was cached.
+        log.warning(
+            "the subtitle sidecar could not be read; the cached track is taken as complete",
+            extra=logs.event("plex.subtitles.meta_unreadable", key=key, reason=type(exc).__name__),
+        )
         return ([[0.0, _FULL_END_S]], True) if _exists(_vtt_path(key)) else ([], False)
 
 
@@ -216,6 +254,8 @@ def _exists(p: Path) -> bool:
     escaped as a 500 from the status route."""
     try:
         return p.exists()
+    # silent-ok: this function's whole job is to answer False for a path the OS refuses. The
+    # refusal IS the return value; a caller that needs to report one reports it itself.
     except (OSError, ValueError):
         return False
 
@@ -226,8 +266,18 @@ def _write_meta(key: str, ranges: list[list[float]], complete: bool) -> None:
         tmp = CACHE_DIR / f"{key}.json.tmp"
         tmp.write_text(json.dumps({"ranges": ranges, "complete": complete}), encoding="utf-8")
         tmp.replace(_meta_path(key))
-    except OSError:
-        pass
+    except OSError as exc:
+        # Without the sidecar beside it, a cached window reads back as a COMPLETE track (see
+        # `read_meta`) — so one failed write here permanently costs the rest of that subtitle.
+        log.warning(
+            "the subtitle sidecar could not be written",
+            extra=logs.event(
+                "plex.subtitles.meta_write_failed",
+                key=key,
+                complete=complete,
+                reason=type(exc).__name__,
+            ),
+        )
 
 
 def generation(key: str) -> int:
@@ -235,7 +285,9 @@ def generation(key: str) -> int:
     window is superseded by a wider one the browser refetches instead of keeping the short VTT."""
     try:
         return _vtt_path(key).stat().st_mtime_ns
-    except (OSError, ValueError):  # ValueError: a NUL in the key — `stat` refuses the path outright
+    # silent-ok: 0 for a track that is not cached yet, which is the ordinary case on every first
+    # request. (ValueError: a NUL in the key — `stat` refuses the path outright.)
+    except (OSError, ValueError):
         return 0
 
 
@@ -267,16 +319,27 @@ def merge_vtt(*sources: str) -> str:
     happen to share a time (two speakers, a sign over dialogue) are both kept."""
     seen: set[str] = set()
     cues: list[tuple[float, str]] = []
+    dropped = 0
     for src in sources:
         for block in re.split(r"\n[ \t]*\n", src or ""):
-            canon = _canonical_cue(block.strip())
+            stripped = block.strip()
+            canon = _canonical_cue(stripped)
             if canon is None:
+                # A block WITH a timing line that still would not parse is a cue we are throwing
+                # away, not a header — and the merged track would simply be missing those lines.
+                if "-->" in stripped:
+                    dropped += 1
                 continue  # header / NOTE / STYLE — the merged file gets its own single header
             start, key, text = canon
             if key in seen:
                 continue
             seen.add(key)
             cues.append((start, text))
+    if dropped:
+        log.info(
+            "some cues were dropped from the merged subtitle: their timing would not parse",
+            extra=logs.event("plex.subtitles.cues_dropped", cues=dropped, kept=len(cues)),
+        )
     cues.sort(key=lambda c: c[0])
     return "WEBVTT\n\n" + "\n\n".join(b for _, b in cues) + "\n"
 
@@ -295,6 +358,8 @@ def _canonical_cue(block: str) -> tuple[float, str, str] | None:
         try:
             st = _vtt_ts_to_s(left.strip())
             en = _vtt_ts_to_s(rparts[0])
+        # silent-ok: None here means "not a cue", and the caller tells a header apart from a
+        # broken timing line by whether the block had a `-->` at all — see `merge_vtt`.
         except (ValueError, IndexError):
             return None
         lines[i] = f"{_vtt_s_to_ts(st)} --> {_vtt_s_to_ts(en)}{settings}"
@@ -310,6 +375,8 @@ def _last_cue_end(vtt: str) -> float:
             continue
         try:
             end = max(end, _vtt_ts_to_s(ln.partition("-->")[2].strip().split(None, 1)[0]))
+        # silent-ok: this is a floor — "how far the pass provably got". Skipping a line it cannot
+        # read makes the answer smaller, never larger, so the error is always on the safe side.
         except (ValueError, IndexError):
             continue
     return end
@@ -394,11 +461,18 @@ _FULL_POOL = ThreadPoolExecutor(max_workers=2, thread_name_prefix="plex-subs-ful
 # which time something has finished.
 _MAX_WINDOWS_INFLIGHT = 8
 _MAX_FULL_INFLIGHT = 6
+# …of which one account may hold this many. The full-pass slots are minutes each, and a hostile (or
+# merely curious) account opening subtitles on film after film could otherwise hold all of them while
+# everyone else's tracks never completed. A viewer over their share still gets windows — the part
+# that makes a track watchable now — just not another whole-file read until one of theirs ends.
+_MAX_FULL_PER_USER = 3
 _MAX_TRACK_WINDOWS = 2
 
 _LOCK = threading.Lock()
 # Queued or running jobs → the absolute span a window job reads (None for a full pass).
 _INFLIGHT: dict[tuple, tuple[float, float] | None] = {}
+# rating_key → the account whose poll queued that item's full pass (see _MAX_FULL_PER_USER).
+_FULL_OWNERS: dict[str, int] = {}
 # Track-level failures: a track that cannot be served at all (no item, a bitmap track, Plex down…).
 _FAILURES: dict[str, tuple[str, float]] = {}
 # rating_key → when its full pass last failed (see FULL_RETRY_S).
@@ -448,6 +522,7 @@ def reset_state() -> None:
     global _STOPPING
     with _LOCK:
         _INFLIGHT.clear()
+        _FULL_OWNERS.clear()
         _FAILURES.clear()
         _FULL_FAILED.clear()
         _WIN_FAILED.clear()
@@ -531,7 +606,7 @@ def _window_failed(key: str, at: float) -> bool:
         return any(a <= at <= b for a, b, _ in _live_window_failures(key))
 
 
-def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
+def ensure(rating_key: str, sub_ord: int, at: float = 0.0, viewer: int = 0) -> dict:
     """State of one subtitle track, scheduling whatever extraction is still missing. NEVER blocks.
 
     ``ready`` = fully extracted · ``partial`` = usable, covers ``at``, still growing · ``preparing``
@@ -574,8 +649,23 @@ def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
             if edge - at <= LOOKAHEAD_S and edge < _FULL_END_S:
                 probe = edge + 1.0
                 want_window = not _window_failed(key, probe)
-        _schedule(rating_key, sub_ord, probe, want_window=want_window, want_full=not full_failed)
-    return {"state": "partial" if covered else "preparing", "code": None, "gen": gen}
+        _schedule(
+            rating_key,
+            sub_ord,
+            probe,
+            want_window=want_window,
+            want_full=not full_failed,
+            viewer=viewer,
+        )
+    # `growing`: whether the track will fill in on its own. False once the full pass has failed and
+    # is backed off — a partial track then stays partial until a window is asked for, so the player
+    # may poll slowly (only to read ahead of an edge) instead of every two seconds for the whole film.
+    return {
+        "state": "partial" if covered else "preparing",
+        "code": None,
+        "gen": gen,
+        "growing": not full_failed,
+    }
 
 
 def cached_track(rating_key: str, sub_ord: int) -> tuple[str | None, str | None]:
@@ -592,7 +682,12 @@ def cached_track(rating_key: str, sub_ord: int) -> tuple[str | None, str | None]
 
 
 def _schedule(
-    rating_key: str, sub_ord: int, at: float, want_window: bool, want_full: bool = True
+    rating_key: str,
+    sub_ord: int,
+    at: float,
+    want_window: bool,
+    want_full: bool = True,
+    viewer: int = 0,
 ) -> None:
     """Kick off the jobs this track still needs: the window that makes it watchable now, and the one
     full pass that makes it complete. A 1 s status poll (or a second viewer) joins a job already
@@ -625,8 +720,15 @@ def _schedule(
                 ident = ("win", rating_key, sub_ord, w_start)
                 _INFLIGHT[ident] = (w_start, w_start + WINDOW_PRE_S + WINDOW_LEN_S)
                 jobs.append((ident, w_start))
-        if want_full and n_full < _MAX_FULL_INFLIGHT and ("full", rating_key) not in _INFLIGHT:
+        mine = sum(1 for owner in _FULL_OWNERS.values() if owner == viewer)
+        if (
+            want_full
+            and n_full < _MAX_FULL_INFLIGHT
+            and ("full", rating_key) not in _INFLIGHT
+            and mine < _MAX_FULL_PER_USER
+        ):
             _INFLIGHT[("full", rating_key)] = None
+            _FULL_OWNERS[rating_key] = viewer
             jobs.append((("full", rating_key), None))
     for ident, window_start in jobs:
         pool = _FULL_POOL if window_start is None else _WIN_POOL
@@ -652,12 +754,35 @@ def _run(
             return
         _extract_and_publish(rating_key, sub_ord, window_start)
     except SubtitleUnavailable as e:
+        # The player's own state was the only place this ever showed. `_pass_failed` backs the item
+        # off for an hour and `_fail` records a code, but neither leaves a line, so "my subtitles
+        # never appear" had nothing on the server to read.
+        # A final code is a fact about the file (no such track, a bitmap subtitle); anything else
+        # is this instance failing at something it could do.
+        log.log(
+            logging.INFO if e.code in FINAL_CODES else logging.WARNING,
+            "subtitle extraction gave up",
+            extra=logs.event(
+                "plex.subtitles.pass_failed",
+                rating_key=rating_key,
+                sub_ord=sub_ord,
+                code=e.code,
+                windowed=window_start is not None,
+            ),
+        )
         if e.code == "extract_failed":
             _pass_failed(rating_key, [key], window_start)
         else:
             _fail(key, e.code)
     except PlexError as e:
-        log.warning("subtitle extraction failed for %s/%s: %s", rating_key, sub_ord, e)
+        # No traceback on purpose: a PlexError carries httpx's own message, which names the method,
+        # the URL and the status — the stack under it is this `except` and the client call, and
+        # says nothing the message does not. (The URL holds no token; it travels as a header.)
+        log.warning(
+            "subtitle extraction failed talking to Plex: %s",
+            e,
+            extra=logs.event("plex.subtitles.plex_error", rating_key=rating_key, sub_ord=sub_ord),
+        )
         _fail(key, "plex_error")
     except (
         Exception
@@ -667,6 +792,8 @@ def _run(
     finally:
         with _LOCK:
             _INFLIGHT.pop(ident, None)
+            if ident[0] == "full":
+                _FULL_OWNERS.pop(rating_key, None)
 
 
 def _pass_failed(
@@ -732,10 +859,13 @@ def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | No
             for i, s in enumerate(subs)
             if s.get("index") is not None and not _is_bitmap(s)
         }
-    start = window_start or 0.0
+    # A full pass starts where every track's leading coverage ends: a pass that ran out of time
+    # (`EXTRACT_TIMEOUT_S`) kept what it reached, and restarting from 0 each `FULL_RETRY_S` meant a file
+    # too big to read in one go never completed. Windows handle an offset start already; so does this.
+    start = window_start if window_start is not None else _full_pass_start(rating_key, targets)
     length = (WINDOW_LEN_S + WINDOW_PRE_S) if window_start is not None else None
     end = _FULL_END_S if length is None else start + length
-    texts, clean = _ffmpeg_extract(str(src), sorted(targets), window_start, length)
+    texts, clean = _ffmpeg_extract(str(src), sorted(targets), start or None, length)
     for emb_ord, vtt in texts.items():
         key = cache_key(rating_key, targets[emb_ord])
         # A pass that exited non-zero holds only what ffmpeg reached before it died. Claim no more
@@ -756,6 +886,24 @@ def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | No
             _pass_failed(rating_key, [key], window_start, (covered_end, end))
 
 
+def _full_pass_start(rating_key: str, targets: dict[int, int]) -> float:
+    """Where the full pass may begin: the end of the span from 0 that EVERY target track already has
+    (one read feeds them all, so the least-covered track decides), backed off by `WINDOW_PRE_S` so a
+    cue running across the join is read whole — `merge_vtt` folds the overlap. 0 when any track has
+    nothing from the start."""
+    ends = []
+    for ord_ in targets.values():
+        key = cache_key(rating_key, ord_)
+        ranges, _ = read_meta(key) if _exists(_vtt_path(key)) else ([], False)
+        lead = [b for a, b in ranges if a <= 0.0]
+        if not lead:
+            return 0.0
+        ends.append(max(lead))
+    if not ends:
+        return 0.0
+    return max(0.0, float(f"{min(ends) - WINDOW_PRE_S:.3f}"))
+
+
 def _sidecar_vtt(db: Session, stream: dict) -> str:
     """An external subtitle file, fetched through Plex and converted to WebVTT."""
     with PlexClient(db) as plex:
@@ -794,9 +942,10 @@ def _ffmpeg_extract(
             cmd += ["-map", f"0:s:{emb_ord}"]
             if length is not None:
                 cmd += ["-t", f"{length:.3f}"]
+            if start:
                 # The input seek lands on the keyframe at or BEFORE `start`, so a cue already running
                 # at `start` comes out at a negative time — and by default the muxer then shifts the
-                # WHOLE output so that cue sits at 0: every cue of the window late by the distance to
+                # WHOLE output so that cue sits at 0: every cue of the read late by the distance to
                 # that keyframe (1–5 s measured on a real library file, a whole GOP on a synthetic
                 # one), and doubled for good once the full pass merged in beside it. Kept negative, the
                 # times are exact on the zero-based clock (`_vtt_ts_to_s` reads the sign).
@@ -829,6 +978,16 @@ def _ffmpeg_extract(
                 try:
                     _, err = proc.communicate(timeout=_TERM_GRACE_S)
                 except subprocess.TimeoutExpired:
+                    # TERM is what makes a timed-out pass worth keeping: ffmpeg closes its outputs
+                    # on it. An ffmpeg that ignores TERM leaves only whole blocks already flushed,
+                    # so the partial track is short for a reason the later line cannot tell apart.
+                    log.info(
+                        "the subtitle extraction ignored TERM and was killed",
+                        extra=logs.event(
+                            "plex.subtitles.extract_killed_after_term",
+                            windowed=start is not None,
+                        ),
+                    )
                     proc.kill()
                     _, err = proc.communicate()
         finally:

backend/app/plex/sync.py

@@ -15,20 +15,18 @@ dead `enabled` column) is a separate follow-up. Cast + intro/credit markers are
 item-detail/player path (P2), not here.
 """
 
-import logging
 from datetime import datetime, timezone
 
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.models import PlexCollection, PlexItem, PlexLibrary, PlexSeason, PlexShow
 from app.plex import detail, people
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
 
-log = logging.getLogger("siftlode.plex")
-
+log = logs.get_logger(__name__)
 # Codecs/containers a browser can play in a native <video> without any transcoding.
 _BROWSER_VIDEO = {"h264"}
 _BROWSER_AUDIO = {"aac", "mp3", "opus", "vorbis"}
@@ -102,6 +100,9 @@ def _video_stream_props(meta: dict) -> tuple[int | None, bool]:
                 bd = s.get("bitDepth")
                 try:
                     depth = int(bd) if bd else None
+                # silent-ok: unknown bit depth, which is also what most listings report. The
+                # playback class then falls back to the codec alone, and per-stream noise over a
+                # whole library would drown the sync's own lines.
                 except (TypeError, ValueError):
                     depth = None
                 hdr = str(s.get("colorTrc") or "").lower() in _HDR_TRANSFERS
@@ -112,6 +113,8 @@ def _video_stream_props(meta: dict) -> tuple[int | None, bool]:
 def _epoch(v) -> datetime | None:
     try:
         return datetime.fromtimestamp(int(v), tz=timezone.utc) if v else None
+    # silent-ok: a field Plex leaves out of most listing rows. None is a legitimate stored value,
+    # and every caller treats it as "not known" rather than as an error.
     except (TypeError, ValueError, OSError):
         return None
 
@@ -120,6 +123,7 @@ def _date(v):
     """Parse a Plex 'YYYY-MM-DD' string (originallyAvailableAt) → date, or None."""
     try:
         return datetime.strptime(v, "%Y-%m-%d").date() if v else None
+    # silent-ok: as `_epoch` above — an absent or unparsable air date is stored as no air date.
     except (TypeError, ValueError):
         return None
 
@@ -135,6 +139,7 @@ def _tags(meta: dict, key: str, limit: int | None = None) -> list | None:
 def _rating(meta: dict) -> float | None:
     try:
         return float(meta.get("audienceRating") or meta.get("rating"))
+    # silent-ok: TypeError on `float(None)` is the ordinary path — most items carry no rating.
     except (TypeError, ValueError):
         return None
 
@@ -266,15 +271,19 @@ def sync(db: Session) -> dict:
             # becomes filterable over successive runs (the cheap listing above only stored the top ~3).
             try:
                 stats["people_enriched"] = _enrich_people_batch(db, plex)
-            except Exception as e:  # best-effort — never fail the sync over the backfill
-                log.warning("Plex people enrich batch failed: %s", e)
+            except Exception:  # noqa: BLE001 — best-effort; never fail the sync over a backfill
+                # With the traceback: a blind catch over a batch that fetches AND writes can be
+                # a Plex shape change, a DB error or our own bug, and `%s` told them apart badly.
+                log.exception("the Plex people-enrich batch failed")
             # Probe a bounded batch of HW-decodable transcode items for bit-depth/HDR, so the
             # playback-class filter's HW/SW split is precise (a 10-bit/HDR HEVC → software) over
             # successive runs. Only HW-decodable-codec transcodes are probed — the rest are SW by codec.
             try:
                 stats["media_probed"] = _probe_media_batch(db, plex)
-            except Exception as e:  # best-effort — never fail the sync over the backfill
-                log.warning("Plex media probe batch failed: %s", e)
+            except Exception:  # noqa: BLE001 — best-effort; never fail the sync over a backfill
+                log.exception("the Plex media-probe batch failed")
+    # silent-ok: the return value IS the report. `{"skipped": …}` goes to the scheduler, which
+    # logs the job result, and to the admin route, which answers it to the caller.
     except PlexNotConfigured as e:
         return {"skipped": str(e)}
     except PlexError as e:
@@ -285,8 +294,8 @@ def sync(db: Session) -> dict:
     # appear in ANY item's cast/directors — drop those rows, mirroring how Plex drops orphaned metadata.
     try:
         stats["people_pruned"] = people.prune_orphan_people(db)
-    except Exception as e:  # best-effort housekeeping — never fail the sync over it
-        log.warning("Plex people prune failed: %s", e)
+    except Exception:  # noqa: BLE001 — best-effort housekeeping; never fail the sync over it
+        log.exception("the Plex people prune failed")
     log.info("Plex sync done: %s", stats)
     return stats
 
@@ -325,7 +334,9 @@ def _probe_media_batch(db: Session, plex: PlexClient, limit: int = _PROBE_BATCH)
     for row in rows:
         try:
             meta = plex.metadata(row.rating_key) or {}
-        except Exception as e:  # transient — leave media_probed_at NULL so it retries next run
+        # No traceback and only debug: this is per item over a whole library, and the stack is
+        # the same `plex.metadata` call every time. The retry next run is the handling.
+        except Exception as e:  # noqa: BLE001 — transient; leave media_probed_at NULL to retry
             log.debug("Plex media probe fetch failed for %s: %s", row.rating_key, e)
             continue
         bit_depth, hdr = _video_stream_props(meta)
@@ -372,7 +383,8 @@ def _enrich_people_batch(db: Session, plex: PlexClient, limit: int = _ENRICH_BAT
     for row in [*movies, *shows]:
         try:
             meta = plex.metadata(row.rating_key) or {}
-        except Exception as e:
+        # As in `_probe_media_batch` above: per item, so the message without the stack.
+        except Exception as e:  # noqa: BLE001 — transient; leave people_enriched_at NULL
             log.debug("Plex people enrich fetch failed for %s: %s", row.rating_key, e)
             continue  # leave people_enriched_at NULL so it's retried on a later run
         people.enrich_row_people(db, row, people.cast_from_meta(meta))

backend/app/plex/tmdb.py

@@ -10,7 +10,6 @@ One-parser rule (mirrors app/plex/detail.py): `parse_tmdb` is the pure parser, `
 the row. The enrich batch + scheduler entry live here too so the whole TMDB integration is one module.
 """
 
-import logging
 import time
 from datetime import datetime, timezone
 
@@ -19,12 +18,11 @@ from sqlalchemy import func, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.config import settings
 from app.models import PlexItem, PlexPerson, PlexShow
 
-log = logging.getLogger("siftlode.tmdb")
-
+log = logs.get_logger(__name__)
 # Politeness throttle: TMDB tolerates ~50 req/s; ~33/s leaves comfortable headroom for a shared host.
 _MIN_INTERVAL = 0.03
 
@@ -142,6 +140,12 @@ def guid_to_tmdb_id(guid: str | None, media_type: str, tmdb: TmdbClient) -> int
         try:
             return int(ext)
         except ValueError:
+            # The caller stamps the watermark on a None, so this title is never looked at again:
+            # one unreadable guid costs it its artwork and its cast permanently.
+            log.info(
+                "a Plex guid named TMDB but did not carry a numeric id",
+                extra=logs.event("plex.tmdb.guid_unparsable", provider=provider),
+            )
             return None
     source = {"imdb": "imdb_id", "tvdb": "tvdb_id"}.get(provider)
     if not source:
@@ -499,7 +503,17 @@ def enrich_person(db: Session, person: PlexPerson) -> bool:
         # doesn't tie up a threadpool worker for the default 30s.
         with TmdbClient(db, timeout=8.0) as tmdb:
             payload = tmdb.fetch_person(person.tmdb_person_id)
-    except TmdbError:
+    except TmdbError as exc:
+        # False leaves the person un-enriched and unstamped, so it is retried — but the page in
+        # front of the user right now shows an empty biography with nothing to say why.
+        log.warning(
+            "the TMDB person lookup failed",
+            extra=logs.event(
+                "plex.tmdb.person_enrich_failed",
+                person_id=person.id,
+                reason=type(exc).__name__,
+            ),
+        )
         return False
     if payload is None:
         person.tmdb_enriched_at = datetime.now(timezone.utc)

backend/app/plex/watch_sync.py

@@ -17,14 +17,17 @@ and the incremental pull resolves a genuine divergence to Plex's state (see `_pu
 running a last-write-wins comparison.
 """
 
-import logging
+# On the PlexError lines in this module: none of them carries a traceback, deliberately. A
+# PlexError is httpx's own message — the method, the URL and the status of one call — and the stack
+# beneath it is always this `except` plus `PlexClient._get`. The attrs beside the line say which
+# user and which phase, which is the part the message cannot know.
 from datetime import datetime, timezone
 
 from sqlalchemy import func, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.db import SessionLocal
 from app.models import PlexItem, PlexLink, PlexState
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
@@ -36,8 +39,7 @@ from app.plex.sync import (
     _paginate,
 )
 
-log = logging.getLogger("siftlode.plex.watch")
-
+log = logs.get_logger(__name__)
 # A resume position below this many seconds isn't worth mirroring — matches the player's own
 # _PROGRESS_MIN_S (a stray few-second seek is not "in progress").
 _PROGRESS_MIN_S = 5
@@ -148,6 +150,8 @@ def import_owner_watch_state(db: Session, link: PlexLink) -> dict:
             link.initial_import_done = True
             link.last_watch_sync_at = datetime.now(timezone.utc)
             db.commit()
+    # silent-ok: the `{"skipped": …}` return is the report — the admin route answers it and the
+    # scheduler logs it on the job line.
     except PlexNotConfigured as e:
         return {"skipped": str(e)}
     except PlexError as e:
@@ -326,8 +330,18 @@ def _resolve_account_id(db: Session, plex: PlexClient, link: PlexLink) -> int:
             if int(a.get("id") or -1) == 1:
                 username = a.get("name")
                 break
-    except PlexError:
-        pass
+    except PlexError as exc:
+        # The fallback account id 1 is right for the admin-token setup, so sync keeps working —
+        # but the username is never stored, and the UI then has no name to show for the link,
+        # exactly as if the server had not offered one.
+        log.info(
+            "the Plex account list could not be read; the link keeps the default account",
+            extra=logs.event(
+                "plex.watch.accounts_probe_failed",
+                user_id=link.user_id,
+                reason=type(exc).__name__,
+            ),
+        )
     link.plex_account_id = acct_id
     if username:
         link.plex_username = username
@@ -566,6 +580,7 @@ def run_plex_watch_sync(db: Session) -> dict:
                 total["repushed"] += _repush_dirty(db, plex, link)
                 link.last_watch_sync_at = now
                 db.commit()
+        # silent-ok: the `{"skipped": …}` return is the report, as above.
         except PlexNotConfigured as e:
             return {"skipped": str(e)}
         except PlexError as e:
@@ -617,6 +632,7 @@ def run_plex_watch_reconcile(db: Session) -> dict:
                 total["repushed"] += _repush_dirty(db, plex, link)
                 link.last_watch_sync_at = datetime.now(timezone.utc)
                 db.commit()
+        # silent-ok: the `{"skipped": …}` return is the report, as above.
         except PlexNotConfigured as e:
             return {"skipped": str(e)}
         except PlexError as e:

backend/app/quota.py

@@ -37,6 +37,7 @@ class QuotaAction:
     PLAYLISTS_DELETE = "playlists_delete"
     VIDEOS_BACKFILL_RECENT = "videos_backfill_recent"
     VIDEOS_BACKFILL_FULL = "videos_backfill_full"
+    VIDEOS_FEED_FALLBACK = "videos_feed_fallback"
     VIDEOS_ENRICH = "videos_enrich"
     VIDEOS_LOOKUP = "videos_lookup"
     VIDEOS_SEARCH = "videos_search"

backend/app/ratelimit.py

@@ -73,6 +73,8 @@ def _norm_ip(s: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
     plain-IPv4 allowlist still matches a peer that surfaces in mapped form. None for a non-IP string."""
     try:
         ip = ipaddress.ip_address(s.strip())
+    # silent-ok: parsing an untrusted header value, where "not an IP" is a documented answer this
+    # function returns — and a line per request is what an attacker would aim for.
     except ValueError:
         return None
     return ip.ipv4_mapped if getattr(ip, "ipv4_mapped", None) else ip

backend/app/realtime.py

@@ -13,12 +13,12 @@ mutated from a single thread.
 """
 
 import asyncio
-import logging
 from collections import defaultdict
 
 from starlette.websockets import WebSocket
+from app import logs
 
-log = logging.getLogger("siftlode.realtime")
+log = logs.get_logger(__name__)
 
 
 class ConnectionManager:
@@ -42,9 +42,16 @@ class ConnectionManager:
         for ws in list(self._conns.get(user_id, ())):
             try:
                 await ws.send_json(payload)
-            except Exception:
-                # Stale socket; it'll be cleaned up by its own disconnect handler.
-                pass
+            except Exception as exc:  # noqa: BLE001 — one dead socket must not stop the others
+                # Stale socket; it'll be cleaned up by its own disconnect handler. But this is
+                # also where a live update goes missing: the UI simply never changes, and there
+                # is no request behind it whose failure anyone could look up.
+                log.debug(
+                    "a live update could not be pushed to a socket",
+                    extra=logs.event(
+                        "realtime.push_failed", user_id=user_id, reason=type(exc).__name__
+                    ),
+                )
 
     def push(self, user_id: int, payload: dict) -> None:
         """Schedule a push onto the WebSocket event loop. Safe to call from a sync route
@@ -54,7 +61,7 @@ class ConnectionManager:
             return
         try:
             asyncio.run_coroutine_threadsafe(self._push(user_id, payload), loop)
-        except Exception:
+        except Exception:  # noqa: BLE001 — a closed loop or socket must not fail the caller
             log.debug("ws push failed", exc_info=True)
 
 

backend/app/refusal.py

@@ -0,0 +1,37 @@
+"""A request the app refuses, said in a way the UI can put in the reader's language.
+
+Every refusal the API answers carries a structured `detail` — `{code, reason, …params}` — and the client
+translates it (`lib/api/core.ts` `localizeDetail`). A bare English string reached the Hungarian UI
+verbatim: the blocking error dialog, and every inline surface that printed `HttpError.detail`, showed
+whatever sentence the route happened to hand-write. `refused` is the generic family
+(`errors.refused.<reason>`, the params interpolated into the sentence); the older specific codes
+(`not_found`, `youtube`, `playlist`, the admin refusals, …) stay, since each is already translated.
+
+A test (`test_http_details.py`) reads every `HTTPException` in the app and fails on a string detail,
+and the frontend's contract test requires every `refused(…, "<reason>")` to be named in both
+languages — so the rule is enforced, not described.
+"""
+
+from fastapi import HTTPException
+
+
+def refused(status: int, reason: str, **params: object) -> HTTPException:
+    """The refusal to raise: `raise refused(409, "view_name_taken", name=name)`. `params` travel in
+    the detail for the sentence to interpolate (`{{name}}`); keep them to values the reader may see."""
+    return HTTPException(status_code=status, detail={"code": "refused", "reason": reason, **params})
+
+
+# `sysconfig.InvalidSetting.reason` → the refusal it answers as. A dict of literals, so the frontend's
+# contract test can read every reason this can produce.
+_SETTING_REASONS = {
+    "not_a_number": "setting_not_a_number",
+    "too_low": "setting_too_low",
+    "too_high": "setting_too_high",
+    "not_a_choice": "setting_not_a_choice",
+    "no_encryption_key": "no_encryption_key",
+}
+
+
+def setting_refused(exc) -> HTTPException:
+    """A value the admin entered that `sysconfig.set_value` refused (`exc`: its `InvalidSetting`)."""
+    return refused(400, _SETTING_REASONS[exc.reason], key=exc.key, **exc.params)

backend/app/routes/_common.py

@@ -13,6 +13,7 @@ from sqlalchemy.orm import Session
 
 from app.db import Base
 from app.models import User
+from app.youtube.client import YouTubeError, refusal_reason
 
 M = TypeVar("M", bound=Base)
 
@@ -45,9 +46,20 @@ def owned_or_404(
 ) -> M:
     """Fetch a row by primary key that `user` owns, or raise 404. A row owned by someone
     else 404s (NOT 403) on purpose — a 403 would confirm the id exists to a stranger.
-    Generalizes the near-identical per-route ownership helpers (e.g. plex's
-    `_own_playlist_or_404`, the saved-views owner check)."""
+    It replaced the near-identical per-route ownership helpers, and is called directly — a thin
+    `_own_x` wrapper around it is the ad-hoc shape CLAUDE.md's patterns table rules out."""
     obj = get_or_404(db, model, id_, what=what)
     if getattr(obj, owner_attr) != user.id:
         raise not_found(what)
     return obj
+
+
+def youtube_refusal(exc: Exception) -> HTTPException:
+    """The answer to an action YouTube refused: a 422 whose reason the UI translates
+    (`errors.youtube.<reason>`). One definition, because the routes had grown three shapes of it —
+    a bare English string quoting the upstream message, a playlist-scoped reason, and nothing at
+    all (a raw 500 from the manual syncs). The upstream failure is already logged where it
+    happened (`youtube.api.error`). A failure that is not the Data API's (the search scraper's) is
+    YouTube being unavailable to us — the retryable answer."""
+    reason = refusal_reason(exc) if isinstance(exc, YouTubeError) else "unavailable"
+    return HTTPException(status_code=422, detail={"code": "youtube", "reason": reason})

backend/app/routes/admin.py

@@ -39,6 +39,7 @@ from app.routes.auth import (
     send_verification_link,
 )
 from app.utils import canonical_email, iso, valid_email
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/admin", tags=["admin"])
 
@@ -169,7 +170,7 @@ def _activate_user_by_email(db: Session, email: str) -> None:
     user = next((u for u in candidates if u.email == email), None) or next(iter(candidates), None)
     if user is not None and not user.is_active:
         user.is_active = True
-        db.commit()
+        db.flush()  # the handler commits (CLAUDE.md: helpers flush)
 
 
 def _decide(db: Session, invite_id: int, admin: User, approved: bool) -> Invite:
@@ -179,7 +180,7 @@ def _decide(db: Session, invite_id: int, admin: User, approved: bool) -> Invite:
     # sending a duplicate decision mail, even flipping an already-approved invite to "denied" and
     # mailing a rejection to an already-active account.
     if inv.status != "pending":
-        raise HTTPException(status_code=409, detail="Invite already decided")
+        raise refused(409, "invite_decided")
     inv.status = "approved" if approved else "denied"
     inv.decided_at = datetime.now(timezone.utc)
     inv.decided_by = admin.email
@@ -191,7 +192,7 @@ def _decide(db: Session, invite_id: int, admin: User, approved: bool) -> Invite:
         target_id=inv.id,
         summary=inv.email,
     )
-    db.commit()
+    db.flush()  # the handler commits, with the activation that goes with it
     return inv
 
 
@@ -210,6 +211,9 @@ def approve_invite(
     link, has_account, hours = _welcome_mail_parts(db, inv.email)
     lang = mailtext.lang_for_email(db, inv.email)
     background.add_task(email_mod.send_access_approved, inv.email, lang, link, has_account, hours)
+    # Before the response, so the mail (a background task, after it) never describes a decision
+    # the database does not hold yet.
+    db.commit()
     return _serialize(inv, has_account=bool(_accounts_for(db, [inv.email])))
 
 
@@ -226,6 +230,7 @@ def deny_invite(
     background.add_task(
         email_mod.send_access_denied, inv.email, mailtext.lang_for_email(db, inv.email)
     )
+    db.commit()
     return _serialize(inv, has_account=bool(_accounts_for(db, [inv.email])))
 
 
@@ -242,7 +247,7 @@ def add_invite(
     """Manually whitelist an email (approved straight away). Convenience for the admin."""
     email = body.email.strip().lower()
     if not valid_email(email):
-        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+        raise refused(400, "invalid_email")
     # Reuse a canonically-equal row instead of adding a second one for the same mailbox. Prod carries
     # exactly that pair for one person from 2026-06-16 (hartmann.peter1986@ / hartmannpeter1986@),
     # which is how an admin ends up approving the same human twice and still seeing them bounce.
@@ -259,11 +264,13 @@ def add_invite(
     inv.status = "approved"
     inv.decided_at = datetime.now(timezone.utc)
     inv.decided_by = admin.email
+    db.flush()  # a new invite's id, for the audit row — before it, the row named no target
     audit.record(
         db, admin.id, AuditAction.INVITE_ADD, target_type="invite", target_id=inv.id, summary=email
     )
-    db.commit()
+    # One transaction: the whitelisting and the activation it implies land together or not at all.
     _activate_user_by_email(db, email)
+    db.commit()
     return _serialize(inv, has_account=bool(_accounts_for(db, [email])))
 
 
@@ -366,10 +373,7 @@ def delete_invite(
     promoted to admin on its next Google sign-in). The admin has to hear that, not guess it."""
     inv = get_or_404(db, Invite, invite_id, what="invite")
     if _accounts_for(db, [inv.email]):
-        raise HTTPException(
-            status_code=409,
-            detail="That address already has an account — delete the account instead.",
-        )
+        raise refused(409, "address_has_account")
     still_allowed_by_env = _env_allowed(inv.email)
     audit.record(
         db,
@@ -435,19 +439,19 @@ def set_user_role(
     account, and can't remove the last remaining admin. Emails the user when it actually changes."""
     role = body.role
     if role not in ("user", "admin"):
-        raise HTTPException(status_code=400, detail="role must be 'user' or 'admin'")
+        raise refused(400, "invalid_role")
     target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
-        raise HTTPException(status_code=400, detail="The demo account's role can't be changed.")
+        raise refused(400, "demo_role")
     if target.id == admin.id:
-        raise HTTPException(status_code=400, detail="You can't change your own role.")
+        raise refused(400, "own_role")
     if (
         target.role == "admin"
         and role == "user"
         and not target.is_suspended
         and count_admins(db, active_only=True) <= 1
     ):
-        raise HTTPException(status_code=400, detail="Can't remove the last admin.")
+        raise refused(400, "last_admin")
     changed = target.role != role
     if changed:
         audit.record(
@@ -493,16 +497,16 @@ def set_user_suspended(
     suspended = body.suspended
     target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
-        raise HTTPException(status_code=400, detail="The demo account can't be suspended.")
+        raise refused(400, "demo_suspend")
     if target.id == admin.id:
-        raise HTTPException(status_code=400, detail="You can't suspend your own account.")
+        raise refused(400, "own_suspend")
     if (
         suspended
         and target.role == "admin"
         and not target.is_suspended
         and count_admins(db, active_only=True) <= 1
     ):
-        raise HTTPException(status_code=400, detail="Can't suspend the last active admin.")
+        raise refused(400, "last_active_admin")
     was_suspended = target.is_suspended
     if was_suspended != suspended:
         audit.record(
@@ -537,17 +541,15 @@ def admin_delete_user(
     not the demo account, not yourself (use Settings → Account), and not the last admin."""
     target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
-        raise HTTPException(status_code=400, detail="The demo account can't be deleted.")
+        raise refused(400, "demo_delete")
     if target.id == admin.id:
-        raise HTTPException(
-            status_code=400, detail="Delete your own account from Settings → Account."
-        )
+        raise refused(400, "own_delete")
     if (
         target.role == "admin"
         and not target.is_suspended
         and count_admins(db, active_only=True) <= 1
     ):
-        raise HTTPException(status_code=400, detail="Can't delete the last admin.")
+        raise refused(400, "last_admin")
     # Record BEFORE the purge — the target row (and its email) is gone afterwards.
     audit.record(
         db,
@@ -691,7 +693,7 @@ def activate_user(
     `_activate_user_by_email`). What was missing was any way to know they had to."""
     target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
-        raise HTTPException(status_code=400, detail="The demo account can't be activated.")
+        raise refused(400, "demo_activate")
     if target.is_active:
         return _serialize_user(target)  # idempotent: a double click is not an error
     if not is_allowed(db, target.email):
@@ -788,7 +790,7 @@ def add_demo_whitelist(
     sign-in). Idempotent — re-adding an existing email just returns it."""
     email = body.email.strip().lower()
     if not valid_email(email):
-        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+        raise refused(400, "invalid_email")
     row = db.execute(select(DemoWhitelist).where(DemoWhitelist.email == email)).scalar_one_or_none()
     if row is None:
         row = DemoWhitelist(
@@ -835,7 +837,7 @@ def reset_demo(admin: User = Depends(admin_user), db: Session = Depends(get_db))
         db, admin.id, AuditAction.DEMO_RESET, summary=f"{seeded} sample playlists re-seeded"
     )
     db.commit()
-    return {"reset": True, "playlists_seeded": seeded}
+    return {"ok": True, "reset": True, "playlists_seeded": seeded}
 
 
 @router.post("/purge-discovery")
@@ -854,4 +856,4 @@ def purge_discovery(admin: User = Depends(admin_user), db: Session = Depends(get
         after=result,
     )
     db.commit()
-    return result
+    return {"ok": True, **result}

backend/app/routes/admin_logs.py

@@ -0,0 +1,234 @@
+"""The admin diagnostics console's read side (E22.6): query `log_events`, the server's stored log.
+
+Admin-only and read-only — rows leave the table through the retention job (`log_retention_days`),
+never through here. Reading is not audited: it changes nothing, and the console's live tail polls,
+so a row per read would bury the audit log's real entries.
+
+What a row holds was redacted when it was written (`logs.record_fields`, and the ingest route for a
+browser's rows), so this serves the columns as they are; a value the redactor took out reads as
+`[redacted]` / `[email]`, which is the point — the console shows that something was there.
+
+Paging is a keyset over `(ts desc, id desc)`: a browser row's `ts` is clamped into its consent
+window, so `ts` alone is not unique, and an offset would skip or repeat rows while the writer adds
+new ones at the top. The live tail re-reads the first page rather than asking for "ids after N":
+several processes write this table, and a batch's ids are taken when it inserts, not when it
+commits, so a slower batch can land below an id the tail already passed — and would never show.
+"""
+
+import base64
+import binascii
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import Text, and_, cast, func, or_, select
+from sqlalchemy.orm import Session
+
+from app.auth import admin_user
+from app.db import get_db
+from app.models import LogEvent, User
+from app.utils import iso, like_escape
+
+router = APIRouter(prefix="/api/admin/logs", tags=["admin"])
+
+PAGE_MAX = 200
+# A facet list is a chip row, not a report: past this many distinct events the rest are reachable
+# through the free-text search, and the response stays small whatever a self-host logs.
+FACET_EVENTS_MAX = 100
+
+Level = Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+# The filters a facet can leave out of its own count (`LogFilters.conditions`).
+Facet = Literal["levels", "sources", "user", "event"]
+# `none` selects the rows that have no account / no event code (a scheduler line, an anonymous
+# request) — a real value to filter on, not the absence of a filter.
+NONE = "none"
+
+
+def _utc(value: datetime | None) -> datetime | None:
+    """A bound without a zone is UTC — the column is `timestamptz`, and a naive value would be read
+    in the database session's zone instead."""
+    if value is None or value.tzinfo is not None:
+        return value
+    return value.replace(tzinfo=timezone.utc)
+
+
+def _encode_cursor(row: LogEvent) -> str:
+    return base64.urlsafe_b64encode(json.dumps([row.ts.isoformat(), row.id]).encode()).decode()
+
+
+def _decode_cursor(cursor: str) -> tuple[datetime, int]:
+    try:
+        ts, row_id = json.loads(base64.urlsafe_b64decode(cursor.encode()))
+        return _utc(datetime.fromisoformat(ts)), int(row_id)
+    except (binascii.Error, json.JSONDecodeError, ValueError, TypeError) as exc:
+        raise HTTPException(status_code=400, detail={"code": "bad_cursor"}) from exc
+
+
+def _serialize(row: LogEvent) -> dict:
+    return {
+        "id": row.id,
+        "ts": iso(row.ts),
+        "level": row.level,
+        "source": row.source,
+        "logger": row.logger,
+        "event": row.event,
+        "msg": row.msg,
+        "attrs": row.attrs,
+        "exc": row.exc,
+        "request_id": row.request_id,
+        "user_id": row.user_id,
+        "job_id": row.job_id,
+        "debug_session_id": row.debug_session_id,
+        "version": row.version,
+    }
+
+
+def _accounts(db: Session, user_ids: set[int]) -> dict[str, str]:
+    """The accounts a page names, by id → address. An id with no account left (erased after the
+    line was written) is simply absent, and the client shows the bare id."""
+    if not user_ids:
+        return {}
+    rows = db.execute(select(User.id, User.email).where(User.id.in_(user_ids))).all()
+    return {str(uid): email for uid, email in rows}
+
+
+@dataclass(frozen=True)
+class LogFilters:
+    """The console's filters, shared by the page and its facet counts."""
+
+    levels: list[str]
+    sources: list[str]
+    user: str | None
+    event: str | None
+    request_id: str | None
+    job_id: int | None
+    q: str | None
+    since: datetime | None
+    until: datetime | None
+
+    def conditions(self, skip: Facet | None = None) -> list:
+        """The WHERE conditions, ANDed by the caller. `skip` leaves one filter out: a facet counts
+        its own values under every OTHER filter, so picking a level does not zero the other
+        levels' counts (the way back), while a request pivot does narrow them (honest counts)."""
+        out = []
+        if self.levels and skip != "levels":
+            out.append(LogEvent.level.in_(self.levels))
+        if self.sources and skip != "sources":
+            out.append(LogEvent.source.in_(self.sources))
+        if self.user is not None and skip != "user":
+            out.append(
+                LogEvent.user_id.is_(None)
+                if self.user == NONE
+                else LogEvent.user_id == int(self.user)
+            )
+        if self.event is not None and skip != "event":
+            out.append(
+                LogEvent.event.is_(None) if self.event == NONE else LogEvent.event == self.event
+            )
+        if self.request_id is not None:
+            out.append(LogEvent.request_id == self.request_id)
+        if self.job_id is not None:
+            out.append(LogEvent.job_id == self.job_id)
+        if self.since is not None:
+            out.append(LogEvent.ts >= _utc(self.since))
+        if self.until is not None:
+            out.append(LogEvent.ts < _utc(self.until))
+        if self.q and self.q.strip():
+            like = f"%{like_escape(self.q.strip())}%"
+            out.append(
+                or_(
+                    LogEvent.msg.ilike(like),
+                    LogEvent.event.ilike(like),
+                    LogEvent.request_id.ilike(like),
+                    LogEvent.exc.ilike(like),
+                    cast(LogEvent.attrs, Text).ilike(like),
+                )
+            )
+        return out
+
+
+def log_filters(
+    levels: list[Level] = Query(default=[]),
+    sources: list[str] = Query(default=[], max_length=8),
+    user: str | None = Query(default=None, pattern=r"^(none|[0-9]{1,10})$"),
+    event: str | None = Query(
+        default=None, max_length=64, pattern=r"^(none|[a-z][a-z0-9_]*(\.[a-z0-9_]+)*)$"
+    ),
+    request_id: str | None = Query(default=None, pattern=r"^[A-Za-z0-9._-]{8,64}$"),
+    job_id: int | None = Query(default=None, ge=1),
+    q: str | None = Query(default=None, max_length=200),
+    since: datetime | None = None,
+    until: datetime | None = None,
+) -> LogFilters:
+    return LogFilters(list(levels), list(sources), user, event, request_id, job_id, q, since, until)
+
+
+@router.get("")
+def list_logs(
+    filters: LogFilters = Depends(log_filters),
+    before: str | None = Query(default=None, max_length=200),
+    limit: int = Query(default=100, ge=1, le=PAGE_MAX),
+    _: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """One page of rows, newest first, matching every filter given (they AND together); `before`
+    continues from a previous page's `next_cursor`."""
+    query = select(LogEvent).where(*filters.conditions())
+    if before is not None:
+        ts, row_id = _decode_cursor(before)
+        # The `ts <=` conjunct is implied by the OR; it is there so the planner can bound the
+        # `ts` index scan instead of filtering every newer row first.
+        query = query.where(
+            and_(
+                LogEvent.ts <= ts,
+                or_(LogEvent.ts < ts, and_(LogEvent.ts == ts, LogEvent.id < row_id)),
+            )
+        )
+
+    # One more than asked, to know whether there is a next page without a second count query.
+    rows = (
+        db.execute(query.order_by(LogEvent.ts.desc(), LogEvent.id.desc()).limit(limit + 1))
+        .scalars()
+        .all()
+    )
+    more = len(rows) > limit
+    rows = rows[:limit]
+    return {
+        "items": [_serialize(r) for r in rows],
+        "accounts": _accounts(db, {r.user_id for r in rows if r.user_id is not None}),
+        "next_cursor": _encode_cursor(rows[-1]) if more else None,
+    }
+
+
+@router.get("/facets")
+def log_facets(
+    filters: LogFilters = Depends(log_filters),
+    _: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """What the filter chips offer, with counts: the levels, sources and accounts present, and the
+    most frequent events — each counted under every filter but its own (`LogFilters.conditions`).
+    `total` is the "all levels" count: every filter but the level one."""
+
+    def counts(col, skip: Facet, cap: int | None = None) -> list[dict]:
+        n = func.count().label("n")
+        stmt = select(col, n).where(*filters.conditions(skip)).group_by(col).order_by(n.desc(), col)
+        if cap is not None:
+            stmt = stmt.limit(cap)
+        return [
+            {"value": NONE if value is None else value, "count": count}
+            for value, count in db.execute(stmt).all()
+        ]
+
+    users = counts(LogEvent.user_id, "user")
+    total = select(func.count()).select_from(LogEvent).where(*filters.conditions("levels"))
+    return {
+        "levels": counts(LogEvent.level, "levels"),
+        "sources": counts(LogEvent.source, "sources"),
+        "events": counts(LogEvent.event, "event", FACET_EVENTS_MAX),
+        "users": [{**u, "value": str(u["value"])} for u in users],
+        "accounts": _accounts(db, {u["value"] for u in users if u["value"] != NONE}),
+        "total": db.scalar(total) or 0,
+    }

backend/app/routes/audit.py

@@ -68,4 +68,4 @@ def clear_audit(admin: User = Depends(admin_user), db: Session = Depends(get_db)
     n = db.execute(delete(AuditLog)).rowcount or 0
     audit.record(db, admin.id, AuditAction.AUDIT_CLEAR, summary=f"Cleared {n} audit entries")
     db.commit()
-    return {"cleared": n}
+    return {"ok": True, "cleared": n}

backend/app/routes/auth.py

@@ -17,6 +17,7 @@ from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app import email as email_mod
+from app import logs
 from app import mailtext
 from app import sysconfig
 from app.auth import (
@@ -42,6 +43,7 @@ from app.models import AuthToken, DemoWhitelist, Invite, OAuthToken, User
 from app.ratelimit import RateLimiter, client_key
 from app.security import encrypt, hash_password, hash_token, verify_password
 from app.utils import canonical_email, valid_email
+from app.refusal import refused
 
 VERIFY_TTL = timedelta(hours=24)
 # A confirmation link that rides an APPROVAL or an invitation lives longer than one the person is
@@ -377,7 +379,7 @@ async def callback(
 
     userinfo = token.get("userinfo")
     if not userinfo or not userinfo.get("sub"):
-        raise HTTPException(status_code=400, detail="No user info returned by Google")
+        raise refused(400, "google_no_userinfo")
 
     sub = userinfo["sub"]
     email = (userinfo.get("email") or "").lower()
@@ -386,7 +388,15 @@ async def callback(
         return _complete_link(request, db, link_uid, link_explicit, sub, userinfo, token)
 
     if not is_allowed(db, email):
-        log.warning("Login denied (not approved): %s", email or "<no email>")
+        # No uid to name — having no account here is the branch. And the address is left out on
+        # purpose: `redact_text` turns it into `[email]` before either sink sees it, so a line
+        # whose only variable is always `[email]` says nothing. WHO asked is in the pending
+        # invite recorded just below, which is where an admin looks anyway.
+        log.warning(
+            "Google sign-in denied: address not approved",
+            # log-pii-ok: whether an address came back, not what it was
+            extra=logs.event("auth.login.denied", reason="not_approved", has_email=bool(email)),
+        )
         # A denied Google login doubles as an access request: record it for the admin and
         # land the user on a friendly "request received" screen instead of a raw 403.
         if email:
@@ -419,15 +429,20 @@ async def callback(
             if existing.google_sub is not None and existing.google_sub != sub:
                 # A different Google identity is already bound to this email — refuse rather than
                 # hijack it. (Near-impossible with real Google accounts: email↔sub is stable.)
-                log.warning("Google login email collision (different sub): %s", email)
+                log.warning(
+                    "Google sign-in refused: a different Google identity holds this address",
+                    extra=logs.event("auth.login.denied", reason="sub_collision", uid=existing.id),
+                )
                 return RedirectResponse(url=_access_notice_url("denied"))
             if not userinfo.get("email_verified", False):
                 # Adopting (and activating) a pre-existing password account requires Google to
                 # actually attest the address — otherwise an unverified Google email that merely
                 # collides with a pending registration could seize that account. Defense-in-depth.
                 log.warning(
-                    "Google login: unverified email, refusing to adopt account: %s",
-                    email,
+                    "Google sign-in refused: unverified address, not adopting the account",
+                    extra=logs.event(
+                        "auth.login.denied", reason="email_unverified", uid=existing.id
+                    ),
                 )
                 return RedirectResponse(url=_access_notice_url("denied"))
             user = existing
@@ -445,7 +460,10 @@ async def callback(
     # A suspended account can't sign in by any method. Block before establishing the session and
     # tell the (verified) owner why — a successful Google auth proves they control this account.
     if user.is_suspended:
-        log.info("Suspended account blocked at Google login: %s", email)
+        log.info(
+            "Google sign-in blocked: the account is suspended",
+            extra=logs.event("auth.login.denied", reason="suspended", uid=user.id),
+        )
         _notify_suspended(background, user)
         return RedirectResponse(url="/?login=suspended")
     # Record what Google actually answers with, beside the address the user registered with. The two
@@ -481,7 +499,10 @@ async def callback(
     _store_token(db, user, token)
     _establish_session(request, user)
     db.commit()
-    log.info("Login: %s (id=%s, role=%s)", email, user.id, user.role)
+    log.info(
+        "signed in",
+        extra=logs.event("auth.login.ok", method="google", uid=user.id, role=user.role),
+    )
     return RedirectResponse(url="/")
 
 
@@ -633,15 +654,15 @@ async def request_access(
     endpoint can't be probed for throttling either."""
     email = (body.email or "").strip().lower()
     if not valid_email(email):
-        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+        raise refused(400, "invalid_email")
     if not _request_access_limiter.allow(client_key(request)):
-        return {"status": "pending"}
+        return {"ok": True, "status": "pending"}
     if is_allowed(db, email):
-        return {"status": "pending"}  # already allowed — don't reveal it
+        return {"ok": True, "status": "pending"}  # already allowed — don't reveal it
     req = upsert_pending_invite(db, email, body.lang)
     if req.is_new:
         notify_admins_of_request(db, background, email)
-    return {"status": "pending"}
+    return {"ok": True, "status": "pending"}
 
 
 @router.post("/demo")
@@ -652,7 +673,7 @@ def demo_login(body: EmailIn, request: Request, db: Session = Depends(get_db)) -
     exactly like a non-match (authenticated=false) so the field can't be hammered as an
     enumeration oracle. On a match it sets the session and the client reloads into the app."""
     if not _demo_limiter.allow(client_key(request)):
-        return {"authenticated": False}
+        return {"ok": True, "authenticated": False}
     email = (body.email or "").strip().lower()
     if valid_email(email) and is_demo_allowed(db, email):
         demo = get_or_create_demo_user(db)
@@ -661,9 +682,10 @@ def demo_login(body: EmailIn, request: Request, db: Session = Depends(get_db)) -
         request.session.clear()
         request.session["user_id"] = demo.id
         _remember_epoch(request, demo)
-        log.info("Demo login (key=%s, demo_id=%s)", email, demo.id)
-        return {"authenticated": True}
-    return {"authenticated": False}
+        # The demo key IS an address, so it is not in the line — see the denied branch above.
+        log.info("signed in", extra=logs.event("auth.login.ok", method="demo", uid=demo.id))
+        return {"ok": True, "authenticated": True}
+    return {"ok": True, "authenticated": False}
 
 
 def _establish_session(request: Request, user: User) -> None:
@@ -794,23 +816,20 @@ def register(
     password = body.password or ""
     # Input validation is safe to reveal (independent of whether the email exists).
     if not valid_email(email):
-        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+        raise refused(400, "invalid_email")
     if len(password) < PASSWORD_MIN_LEN:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Password must be at least {PASSWORD_MIN_LEN} characters.",
-        )
+        raise refused(400, "weak_password", min=PASSWORD_MIN_LEN)
     if not sysconfig.get_bool(db, "allow_registration"):
-        raise HTTPException(status_code=403, detail="Registration is currently closed.")
+        raise refused(403, "registration_closed")
     if not _register_limiter.allow(client_key(request)):
-        return {"status": "ok"}  # silently throttle; uniform response
+        return {"ok": True, "status": "ok"}  # silently throttle; uniform response
 
     # Do the existence check + account creation OFF the response path (a background task with its own
     # session). The create path hashes the password + writes several rows + schedules emails; doing it
     # inline would make a NEW email respond measurably slower than an already-registered one (which
     # skips all that) — a timing oracle for enumeration. Off-path, any valid email responds the same.
     background.add_task(_register_account, email, password, body.lang)
-    return {"status": "ok"}
+    return {"ok": True, "status": "ok"}
 
 
 def _register_account(email: str, password: str, lang: str | None = None) -> None:
@@ -880,7 +899,12 @@ def _register_account(email: str, password: str, lang: str | None = None) -> Non
         except IntegrityError:
             # A concurrent registration for the same new email won the race between the pre-check
             # above and this flush (the unique-email constraint fires). Same already-registered
-            # no-op as the pre-check hit — roll back and stop.
+            # no-op as the pre-check hit — roll back and stop. The line carries nothing: the
+            # answer to the caller is deliberately identical either way, and so is this.
+            log.info(
+                "a registration lost the race for its address",
+                extra=logs.event("auth.register.race_lost"),
+            )
             db.rollback()
             return
         upsert_pending_invite(db, email)  # admin-approval gate
@@ -971,11 +995,11 @@ def verify_email_resend(
     mail had no way back. Uniform response + timing regardless of whether the email has a pending
     account (the lookup runs off the response path), so it can't probe for registered emails."""
     if not _verify_resend_limiter.allow(client_key(request)):
-        return {"status": "ok"}  # silently throttle; uniform response
+        return {"ok": True, "status": "ok"}  # silently throttle; uniform response
     email = (body.email or "").strip().lower()
     if valid_email(email):
         background.add_task(_resend_verify_if_eligible, email)
-    return {"status": "ok"}
+    return {"ok": True, "status": "ok"}
 
 
 def _resend_verify_if_eligible(email: str) -> None:
@@ -1049,7 +1073,10 @@ def password_login(
         raise _login_refused(403, "pending_approval", user)
     _establish_session(request, user)
     db.commit()
-    log.info("Password login: %s (id=%s, role=%s)", email, user.id, user.role)
+    log.info(
+        "signed in",
+        extra=logs.event("auth.login.ok", method="password", uid=user.id, role=user.role),
+    )
     return {"ok": True}
 
 
@@ -1062,14 +1089,14 @@ def password_reset_request(
     """Request a password-reset link. Uniform response + timing regardless of whether the email has a
     password account (the lookup runs off the response path), so it can't probe for registered emails."""
     if not _reset_limiter.allow(client_key(request)):
-        return {"status": "ok"}
+        return {"ok": True, "status": "ok"}
     email = (body.email or "").strip().lower()
     # Do the account lookup + token issue + email OFF the response path (a background task with its
     # own session), so the endpoint takes the same time for any valid email whether or not it has a
     # password account — no timing-based enumeration. Any valid email schedules the same task.
     if valid_email(email):
         background.add_task(_send_reset_if_eligible, email)
-    return {"status": "ok"}
+    return {"ok": True, "status": "ok"}
 
 
 def _send_reset_if_eligible(email: str) -> None:
@@ -1264,13 +1291,10 @@ def set_password(
         raise HTTPException(status_code=403, detail={"code": "demo"})
     new_password = body.password or ""
     if len(new_password) < PASSWORD_MIN_LEN:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Password must be at least {PASSWORD_MIN_LEN} characters.",
-        )
+        raise refused(400, "weak_password", min=PASSWORD_MIN_LEN)
     if user.password_hash:
         if not verify_password(body.current_password or "", user.password_hash):
-            raise HTTPException(status_code=403, detail="Current password is incorrect.")
+            raise refused(403, "wrong_password")
     user.password_hash = hash_password(new_password)
     user.password_revoked_at = None  # same as the reset path: a password exists again
     # SA4: a password change logs out every OTHER session; re-stamp this cookie at the new epoch so

backend/app/routes/channels.py

@@ -2,15 +2,14 @@
 hidden, tags) and per-channel sync state. Local reads/writes plus YouTube-side writes
 (subscribe / unsubscribe) that require the optional write scope."""
 
-import logging
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from fastapi import APIRouter, BackgroundTasks, Depends
 from pydantic import BaseModel
 from sqlalchemy import func, select, update
 from sqlalchemy.orm import Session
 
-from app import quota
+from app import logs, quota
 from app.auth import admin_user, current_user, require_human, require_write_scope
 from app.db import get_db
 from app.models import (
@@ -26,16 +25,17 @@ from app.models import (
     User,
     Video,
 )
-from app.routes._common import get_or_404, not_found, owned_or_404
+from app.routes._common import get_or_404, not_found, owned_or_404, youtube_refusal
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import backfill_channel_now, run_recent_backfill
 from app.sync.subscriptions import apply_channel_details
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/channels", tags=["channels"])
 
-log = logging.getLogger("siftlode.api")
+log = logs.get_logger(__name__)
 
 
 @router.get("")
@@ -166,7 +166,15 @@ def discover_channels(
                 user.yt_channel_id = own
                 db.commit()
         except YouTubeError as exc:
-            log.warning("discovery: own-channel resolve failed (user %s): %s", user.id, exc)
+            # No traceback anywhere in this file's YouTube handlers: for an upstream answer
+            # `_upstream_failure` already logged the structured `youtube.api.error`, and the
+            # message names the call, its status and its reason (or, with no answer at all, the
+            # transport failure). The stack under it is this `except` and the client call.
+            log.warning(
+                "discovery: own-channel resolve failed: %s",
+                exc,
+                extra=logs.event("channels.discovery.own_channel_failed", reason=exc.reason),
+            )
 
     rows = _discovery_rows(db, user)
 
@@ -190,7 +198,11 @@ def discover_channels(
                 rows, key=lambda r: (-int(r[1]), r[0].title is None, (r[0].title or "").lower())
             )
         except YouTubeError as exc:
-            log.warning("discovery: channel enrich failed (user %s): %s", user.id, exc)
+            log.warning(
+                "discovery: channel enrich failed: %s",
+                exc,
+                extra=logs.event("channels.discovery.enrich_failed", reason=exc.reason),
+            )
             db.rollback()
 
     return [
@@ -298,7 +310,13 @@ def channel_detail(
             db.commit()
             channel = db.get(Channel, channel_id)
         except YouTubeError as exc:
-            log.warning("channel detail enrich failed (%s): %s", channel_id, exc)
+            log.warning(
+                "channel detail enrich failed: %s",
+                exc,
+                extra=logs.event(
+                    "channels.detail.enrich_failed", channel_id=channel_id, reason=exc.reason
+                ),
+            )
             db.rollback()
     sub = db.execute(
         select(Subscription).where(
@@ -366,12 +384,9 @@ def explore_channel(
     backfill quota reserve; blocked for the demo account (it spends shared quota)."""
     channel = get_or_404(db, Channel, channel_id, what="channel")
     if _is_blocked(db, user, channel_id):
-        raise HTTPException(status_code=403, detail="You've blocked this channel.")
+        raise refused(403, "channel_blocked")
     if quota.backfill_reserve_reached():
-        raise HTTPException(
-            status_code=429,
-            detail="The shared daily quota reserve is reached — try exploring later.",
-        )
+        raise refused(429, "quota_reserve")
 
     # Record/refresh the exploration (DB only) before ingesting, so the explorer can see the
     # videos as soon as they land. Flag the channel ephemeral unless it's organically followed.
@@ -407,8 +422,9 @@ def explore_channel(
                 channel = db.get(Channel, channel_id)
             result = explore_ingest_page(db, yt, channel, page_token)
     except YouTubeError as exc:
-        raise HTTPException(status_code=422, detail=f"YouTube couldn't load this channel: {exc}")
+        raise youtube_refusal(exc)
     return {
+        "ok": True,
         "channel_id": channel_id,
         "ingested": result["ingested"],
         "next_page_token": result["next_page_token"],
@@ -490,6 +506,7 @@ def update_channel(
         background.add_task(backfill_channel_now, channel_id, user.id)
 
     return {
+        "ok": True,
         "id": channel_id,
         "priority": sub.priority,
         "hidden": sub.hidden,
@@ -524,7 +541,7 @@ def reset_backfill(
     db.commit()
     with quota.attribute(user.id, quota.QuotaAction.VIDEOS_BACKFILL_RECENT):
         run_recent_backfill(db, [channel], max_channels=1)
-    return {"id": channel_id, "reset": True}
+    return {"ok": True, "id": channel_id, "reset": True}
 
 
 @router.post("/{channel_id}/subscribe")
@@ -545,7 +562,7 @@ def subscribe(
         )
     ).scalar_one_or_none()
     if existing is not None:
-        raise HTTPException(status_code=409, detail="Already subscribed to this channel.")
+        raise refused(409, "already_subscribed")
     with (
         quota.attribute(user.id, quota.QuotaAction.CHANNELS_SUBSCRIBE),
         YouTubeClient(db, user) as yt,
@@ -559,13 +576,14 @@ def subscribe(
             # subscription resync fills in the resource id. Any other YouTube error is a real
             # problem — surface it with a clear message (422, not a 502 that the client would
             # mistake for a transient "connection lost").
-            msg = str(exc).lower()
-            if "already exists" in msg or "duplicate" in msg:
+            # On the reason code, never on the prose: the error no longer carries the body (it is
+            # the request quoted back), and a message YouTube rewords would silently turn "already
+            # following" back into a 422 the user cannot act on. `reason` is comma-joined when the
+            # body listed several.
+            if "subscriptionDuplicate" in exc.reason.split(","):
                 yt_sub_id = ""
             else:
-                raise HTTPException(
-                    status_code=422, detail=f"YouTube couldn't subscribe you: {exc}"
-                )
+                raise youtube_refusal(exc)
         # Enrich a stub channel (title/thumbnail/subscriber count) so it shows up properly right
         # away, on BOTH the normal and the desync path — a resurfaced stub still needs metadata to
         # render. Keep the client open (we're still inside the `with`); a metadata failure here
@@ -574,7 +592,15 @@ def subscribe(
             try:
                 apply_channel_details(db, yt.get_channels([channel_id]))
             except YouTubeError as exc:
-                log.warning("subscribe: stub enrich failed (%s): %s", channel_id, exc)
+                log.warning(
+                    "subscribe: stub enrich failed: %s",
+                    exc,
+                    extra=logs.event(
+                        "channels.subscribe.enrich_failed",
+                        channel_id=channel_id,
+                        reason=exc.reason,
+                    ),
+                )
     db.add(
         Subscription(
             user_id=user.id,
@@ -594,7 +620,7 @@ def subscribe(
             .values(via_explore=False)
         )
     db.commit()
-    return {"subscribed": channel_id}
+    return {"ok": True, "subscribed": channel_id}
 
 
 @router.delete("/{channel_id}/subscription")
@@ -608,10 +634,7 @@ def unsubscribe(
     should Hide instead."""
     sub = _user_subscription(db, user, channel_id)
     if not sub.yt_subscription_id:
-        raise HTTPException(
-            status_code=400,
-            detail="No YouTube subscription id on record — sync subscriptions first.",
-        )
+        raise refused(400, "no_subscription_id")
     try:
         with (
             quota.attribute(user.id, quota.QuotaAction.CHANNELS_UNSUBSCRIBE),
@@ -621,10 +644,10 @@ def unsubscribe(
     except YouTubeError as exc:
         # 422 (a real, explainable error → speaking modal), not 502 which the client treats as
         # a transient "connection lost" gateway blip.
-        raise HTTPException(status_code=422, detail=f"YouTube couldn't unsubscribe you: {exc}")
+        raise youtube_refusal(exc)
     db.delete(sub)
     db.commit()
-    return {"unsubscribed": channel_id}
+    return {"ok": True, "unsubscribed": channel_id}
 
 
 @router.get("/blocked/list")
@@ -665,7 +688,7 @@ def block_channel(
             )
         )
         db.commit()
-    return {"blocked": channel_id}
+    return {"ok": True, "blocked": channel_id}
 
 
 @router.delete("/{channel_id}/block")
@@ -680,7 +703,7 @@ def unblock_channel(
         )
     )
     db.commit()
-    return {"unblocked": channel_id}
+    return {"ok": True, "unblocked": channel_id}
 
 
 class AttachTagIn(BaseModel):
@@ -715,7 +738,7 @@ def attach_tag(
             )
         )
         db.commit()
-    return {"channel_id": channel_id, "tag_id": body.tag_id}
+    return {"ok": True, "channel_id": channel_id, "tag_id": body.tag_id}
 
 
 @router.delete("/{channel_id}/tags/{tag_id}")
@@ -735,4 +758,4 @@ def detach_tag(
     if row is not None:
         db.delete(row)
         db.commit()
-    return {"channel_id": channel_id, "tag_id": tag_id}
+    return {"ok": True, "channel_id": channel_id, "tag_id": tag_id}

backend/app/routes/config.py

@@ -4,7 +4,7 @@ app.sysconfig. Secret values (e.g. SMTP password) are write-only — never retur
 import re
 from typing import Any
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
@@ -17,6 +17,9 @@ from app.audit import AuditAction
 from app.auth import admin_user
 from app.db import get_db
 from app.models import User
+from app.refusal import refused
+from app.routes._common import not_found
+from app.refusal import setting_refused
 
 router = APIRouter(prefix="/api/admin/config", tags=["admin"])
 
@@ -59,19 +62,16 @@ def set_config(
 ) -> dict:
     s = sysconfig.spec(key)
     if s is None:
-        raise HTTPException(status_code=404, detail="Unknown config key")
+        raise not_found("config_key")
     if "value" not in body.model_fields_set:
-        raise HTTPException(status_code=400, detail="Missing 'value'")
+        raise refused(400, "value_missing")
     if s.secret and not sysconfig.secrets_manageable():
-        raise HTTPException(
-            status_code=400,
-            detail="Set TOKEN_ENCRYPTION_KEY to store secrets in the database.",
-        )
+        raise refused(400, "no_encryption_key")
     old = None if s.secret else sysconfig.get(db, key)
     try:
         sysconfig.set_value(db, key, body.value)
-    except (TypeError, ValueError) as exc:
-        raise HTTPException(status_code=400, detail=str(exc) or "Invalid value")
+    except sysconfig.InvalidSetting as exc:
+        raise setting_refused(exc) from None
     # Never log a secret's value — only that it was changed, by whom. Non-secret values are logged
     # but with URL credentials redacted (a proxy/URL setting can embed user:pass). Skip the row when
     # a non-secret value didn't actually change (a no-op re-save shouldn't add trail noise); secrets
@@ -101,7 +101,7 @@ def reset_config(
 ) -> dict:
     s = sysconfig.spec(key)
     if s is None:
-        raise HTTPException(status_code=404, detail="Unknown config key")
+        raise not_found("config_key")
     old = None if s.secret else sysconfig.get(db, key)
     sysconfig.reset(db, key)
     audit.record(
@@ -126,8 +126,8 @@ def send_test_email(
     """Send a test email to the requesting admin using the current (DB or env) SMTP config —
     lets the admin verify the settings actually work."""
     if not email_mod.email_enabled():
-        raise HTTPException(status_code=400, detail="SMTP is not configured.")
+        raise refused(400, "smtp_off")
     sent = email_mod.send_test(user.email, mailtext.lang_for_user(user))
     if not sent:
-        raise HTTPException(status_code=422, detail="SMTP send failed — check the settings.")
-    return {"sent": True, "to": user.email}
+        raise refused(422, "smtp_failed")
+    return {"ok": True, "sent": True, "to": user.email}

backend/app/routes/discover.py

@@ -11,9 +11,9 @@ thing it exists to remove.
 
 from typing import Literal
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
-from sqlalchemy import select, update
+from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
@@ -23,7 +23,7 @@ from app.discover import hero as hero_mod
 from app.discover import pins, rails
 from app.discover.budget import Budget, DEFAULT_BUDGET
 from app.models import ComfortPin, User
-from app.routes._common import owned_or_404
+from app.routes._common import owned_or_404, not_found
 
 router = APIRouter(prefix="/api/discover", tags=["discover"])
 
@@ -53,7 +53,9 @@ def get_discover(
     `resume` and `shelf` are built once and handed to the hero, so the two rails the hero draws from
     are not queried twice for a single page load."""
     resume = rails.continue_watching(db, user)
-    shelf = pins.shelf(db, user)
+    # Plex off → the shelf rail (and so the hero's comfort tier) goes YouTube-only like the rails
+    # beside it; the pins are kept and `GET /pins` still lists them (`pins.shelf`).
+    shelf = pins.shelf(db, user, include_plex=rails.plex_available(db))
     return {
         "budget": budget,
         "hero": hero_mod.pick(db, user, budget, seed, resume=resume, shelf=shelf),
@@ -125,7 +127,7 @@ def add_pin(
     constraint is the mechanism, not the message."""
     resolved = pins.resolve_ref(db, user, body.kind, body.ref)
     if resolved is None:
-        raise HTTPException(status_code=404, detail="Unknown item")
+        raise not_found("item")
     column, value = resolved
 
     existing = db.execute(
@@ -157,7 +159,7 @@ def add_pin(
             # between `resolve_ref` confirming it and this INSERT (a Plex sync dropping a removed
             # item), which trips the FK. Semantically that is the same "no such thing" the pre-check
             # returns above — re-raising handed the user a 500 they could do nothing with.
-            raise HTTPException(status_code=404, detail="Unknown item")
+            raise not_found("item")
         return {"ok": True, "id": winner.id, "created": False}
     return {"ok": True, "id": pin.id, "created": True}
 
@@ -180,18 +182,11 @@ def reorder_pins(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Rewrite the shelf order from a full list of pin ids.
+    """Rewrite the shelf order from the list of pin ids the client shows.
 
     Whole-list rather than a move-one delta: the shelf is short, and a full rewrite cannot leave two
-    tiles claiming the same slot the way an interrupted sequence of single moves can. Ids that are not
-    this user's are ignored rather than 404'd — a stale tab replaying an order that includes a pin
-    deleted meanwhile should reorder what still exists, not fail wholesale."""
-    owned = {p.id for p in pins.list_pins(db, user)}
-    for position, pin_id in enumerate(i for i in body.ids if i in owned):
-        db.execute(
-            update(ComfortPin)
-            .where(ComfortPin.id == pin_id, ComfortPin.user_id == user.id)
-            .values(position=position)
-        )
+    tiles claiming the same slot the way an interrupted sequence of single moves can. The list may be
+    PARTIAL (hidden Plex pins, a stale tab) — `pins.reorder` keeps what it leaves out in place."""
+    pins.reorder(db, user, body.ids)
     db.commit()
     return {"ok": True}

backend/app/routes/downloads.py

@@ -38,10 +38,11 @@ from app.models import (
     MediaAsset,
     User,
 )
-from app.routes._common import get_or_404, not_found
+from app.routes._common import get_or_404, not_found, owned_or_404
 from app.security import hash_password
 from app.userscope import is_messageable_user, messageable_clauses
 from app.utils import iso
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/downloads", tags=["downloads"])
 admin_router = APIRouter(prefix="/api/admin/downloads", tags=["admin-downloads"])
@@ -63,7 +64,7 @@ def resolve_source(raw: str) -> tuple[str, str]:
     as a raw URL for yt-dlp's generic extractor."""
     raw = (raw or "").strip()
     if not raw:
-        raise HTTPException(status_code=400, detail="A video link or id is required.")
+        raise refused(400, "link_required")
     if _VIDEO_ID.match(raw):
         return "youtube", raw
     if raw.startswith(("http://", "https://")):
@@ -93,7 +94,7 @@ def resolve_source(raw: str) -> tuple[str, str]:
             if _VIDEO_ID.match(vid):
                 return "youtube", vid
         return "url", raw
-    raise HTTPException(status_code=400, detail="That doesn't look like a valid video link.")
+    raise refused(400, "invalid_link")
 
 
 def _serialize(job: DownloadJob, asset: MediaAsset | None) -> dict:
@@ -166,15 +167,8 @@ def _serialize_job(db: Session, job: DownloadJob) -> dict:
     return _serialize(job, asset)
 
 
-def _own_job(db: Session, user: User, job_id: int) -> DownloadJob:
-    job = db.get(DownloadJob, job_id)
-    if job is None or job.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown download")
-    return job
-
-
 def _own_job_for_update(db: Session, user: User, job_id: int) -> DownloadJob:
-    """`_own_job` for a transition that moves its asset's ref count (resume, cancel, delete, redownload)
+    """The ownership check (`owned_or_404`) for a transition that moves its asset's ref count (resume, cancel, delete, redownload)
     or writes the status those decide on (pause). The job is re-read under a row lock, so two
     overlapping requests for one job run one after the other and the second decides on the first's
     committed result — never both releasing the same hold, and never a pause turning a job a cancel
@@ -183,7 +177,7 @@ def _own_job_for_update(db: Session, user: User, job_id: int) -> DownloadJob:
     The asset is locked BEFORE the job: the order a finishing worker child takes them in
     (`service.finalize_if_running`), so the two can never deadlock."""
     while True:
-        asset_id = _own_job(db, user, job_id).asset_id
+        asset_id = owned_or_404(db, DownloadJob, job_id, user, what="download").asset_id
         if asset_id is not None:
             db.execute(select(MediaAsset.id).where(MediaAsset.id == asset_id).with_for_update())
         job = db.execute(
@@ -193,7 +187,7 @@ def _own_job_for_update(db: Session, user: User, job_id: int) -> DownloadJob:
             .execution_options(populate_existing=True)
         ).scalar_one_or_none()
         if job is None:
-            raise HTTPException(status_code=404, detail="Unknown download")
+            raise not_found("download")
         if job.asset_id == asset_id:
             return job
         db.rollback()  # another request moved the job to another asset meanwhile: lock that one
@@ -240,7 +234,7 @@ def create_profile(
     name = body.name.strip()
     spec = body.spec
     if not name:
-        raise HTTPException(status_code=400, detail="A profile name is required.")
+        raise refused(400, "profile_name_required")
     maxpos = db.execute(
         select(func.coalesce(func.max(DownloadProfile.sort_order), 100)).where(
             DownloadProfile.user_id == user.id
@@ -268,16 +262,16 @@ def update_profile(
 ) -> dict:
     p = db.get(DownloadProfile, profile_id)
     if p is None or p.is_builtin or p.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown profile")
+        raise not_found("profile")
     sent = body.model_fields_set
     if "name" in sent:
         name = (body.name or "").strip()
         if not name:
-            raise HTTPException(status_code=400, detail="A profile name is required.")
+            raise refused(400, "profile_name_required")
         p.name = name[:80]
     if "spec" in sent:
         if body.spec is None:
-            raise HTTPException(status_code=400, detail="spec must be an object")
+            raise refused(400, "spec_not_object")
         p.spec = body.spec
     db.commit()
     return _serialize_profile(p)
@@ -289,7 +283,7 @@ def delete_profile(
 ) -> dict:
     p = db.get(DownloadProfile, profile_id)
     if p is None or p.is_builtin or p.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown profile")
+        raise not_found("profile")
     db.delete(p)
     db.commit()
     return {"deleted": profile_id}
@@ -319,7 +313,7 @@ def set_credential(
     """Store (encrypted) this user's cookies.txt for one supported host. Write-only: the value is
     never echoed back, logged, or audited — only the fact that it changed."""
     if not dlcreds.is_supported_host(host_key):
-        raise HTTPException(status_code=404, detail="Unknown host")
+        raise not_found("host")
     try:
         cleaned = dlcreds.validate_cookies(body.cookies)
     except dlcreds.InvalidCookies as e:
@@ -341,7 +335,7 @@ def delete_credential(
     host_key: str, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
     if not dlcreds.is_supported_host(host_key):
-        raise HTTPException(status_code=404, detail="Unknown host")
+        raise not_found("host")
     if dlcreds.delete_credential(db, user.id, host_key):
         audit.record(
             db,
@@ -362,7 +356,7 @@ def _resolve_spec(
     if profile_id is not None:
         p = db.get(DownloadProfile, profile_id)
         if p is None or (not p.is_builtin and p.user_id != user.id):
-            raise HTTPException(status_code=404, detail="Unknown profile")
+            raise not_found("profile")
         return p.spec, p.id
     if spec is not None:
         return spec, None
@@ -373,7 +367,7 @@ def _resolve_spec(
         .limit(1)
     ).scalar_one_or_none()
     if fallback is None:
-        raise HTTPException(status_code=400, detail="No download profile available.")
+        raise refused(400, "no_profile")
     return fallback.spec, fallback.id
 
 
@@ -484,7 +478,7 @@ def enqueue_edit(
     source file is only read, never modified, so editing a shared video is safe."""
     source_job = _accessible_job(db, user, body.source_job_id)
     if source_job.status != "done" or source_job.asset_id is None:
-        raise HTTPException(status_code=409, detail="You can only edit a finished download.")
+        raise refused(409, "edit_unfinished")
     spec = body.edit_spec
     display_name = (body.display_name or "").strip() or None
     try:
@@ -587,6 +581,8 @@ def _clean_url(raw) -> str | None:
     # authority. This one already has a "not a plausible URL" answer, so the typo belongs in it.
     try:
         parsed = urlparse(url)
+    # silent-ok: a typo in a link someone pasted. None is this function's "not a plausible URL"
+    # answer, the caller already has one, and any line here would carry the URL itself.
     except ValueError:
         return None
     if not parsed.netloc:
@@ -612,7 +608,7 @@ def update_download_meta(
 ) -> dict:
     """Update a download's display metadata: title, channel name + link, and extra reference URLs.
     All are display-only overrides — the on-disk file keeps its system-decided, id-bound name."""
-    job = _own_job(db, user, job_id)
+    job = owned_or_404(db, DownloadJob, job_id, user, what="download")
     sent = body.model_fields_set
     if "display_name" in sent:
         job.display_name = ((body.display_name or "").strip())[:255] or None
@@ -666,9 +662,9 @@ def redownload_download(
     if job.job_kind in ("edit", "upload"):
         # Neither has a re-fetchable source: an editor clip is derived locally, an upload IS the
         # source. Re-running yt-dlp against source_kind='upload'/'edit' would just fail.
-        raise HTTPException(status_code=409, detail="This item can't be re-downloaded.")
+        raise refused(409, "not_redownloadable")
     if job.status in ("queued", "running", "paused"):
-        raise HTTPException(status_code=409, detail="This download is still in progress.")
+        raise refused(409, "still_downloading")
     service.redownload(db, job)
     return _serialize_job(db, job)
 
@@ -697,7 +693,7 @@ def delete_download(
 def _accessible_job(db: Session, user: User, job_id: int) -> DownloadJob:
     job = db.get(DownloadJob, job_id)
     if job is None:
-        raise HTTPException(status_code=404, detail="Unknown download")
+        raise not_found("download")
     if job.user_id == user.id:
         return job
     shared = db.execute(
@@ -706,7 +702,7 @@ def _accessible_job(db: Session, user: User, job_id: int) -> DownloadJob:
         )
     ).first()
     if shared is None:
-        raise HTTPException(status_code=404, detail="Unknown download")
+        raise not_found("download")
     return job
 
 
@@ -720,10 +716,10 @@ def download_file(
     job = _accessible_job(db, user, job_id)
     asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
     if asset is None or asset.status != "ready" or not asset.rel_path:
-        raise HTTPException(status_code=409, detail="This download isn't ready.")
+        raise refused(409, "download_not_ready")
     path = storage.safe_abs_path(settings.download_root, asset.rel_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="File is no longer available.")
+        raise not_found("file")
 
     filename = storage.download_filename(
         job.display_name or asset.title or asset.source_ref, asset.container, path
@@ -762,7 +758,7 @@ def storyboard_meta(
     job = _accessible_job(db, user, job_id)
     asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
     if asset is None or asset.status != "ready" or not asset.rel_path:
-        raise HTTPException(status_code=409, detail="This download isn't ready.")
+        raise refused(409, "download_not_ready")
     meta = editmod.ensure_storyboard(asset, settings.download_root)
     if meta is None:
         return {"available": False}
@@ -783,10 +779,10 @@ def poster_image(job_id: int, user: User = Depends(require_human), db: Session =
     job = _accessible_job(db, user, job_id)
     asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
     if asset is None or not asset.poster_path:
-        raise HTTPException(status_code=404, detail="No poster.")
+        raise not_found("poster")
     path = storage.safe_abs_path(settings.download_root, asset.poster_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="No poster.")
+        raise not_found("poster")
     return FileResponse(path, media_type="image/jpeg")
 
 
@@ -797,10 +793,10 @@ def storyboard_image(
     job = _accessible_job(db, user, job_id)
     asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
     if asset is None or not asset.storyboard_path:
-        raise HTTPException(status_code=404, detail="No filmstrip.")
+        raise not_found("filmstrip")
     path = storage.safe_abs_path(settings.download_root, asset.storyboard_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="No filmstrip.")
+        raise not_found("filmstrip")
     return FileResponse(path, media_type="image/jpeg")
 
 
@@ -818,12 +814,12 @@ def share_download(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    job = _own_job(db, user, job_id)
+    job = owned_or_404(db, DownloadJob, job_id, user, what="download")
     if job.status != "done" or job.asset_id is None:
-        raise HTTPException(status_code=409, detail="Only a finished download can be shared.")
+        raise refused(409, "share_unfinished")
     target = body.email.strip().lower()
     if not target:
-        raise HTTPException(status_code=400, detail="A recipient email is required.")
+        raise refused(400, "recipient_required")
     recipient = db.execute(
         select(User).where(func.lower(User.email) == target)
     ).scalar_one_or_none()
@@ -832,7 +828,7 @@ def share_download(
     if not is_messageable_user(recipient):
         raise not_found("recipient")
     if recipient.id == user.id:
-        raise HTTPException(status_code=400, detail="That's already your download.")
+        raise refused(400, "share_own")
     exists = db.execute(
         select(DownloadShare.id).where(
             DownloadShare.job_id == job_id, DownloadShare.to_user_id == recipient.id
@@ -851,7 +847,7 @@ def share_download(
             commit=False,
         )
         db.commit()
-    return {"shared_with": recipient.email}
+    return {"ok": True, "shared_with": recipient.email}
 
 
 @router.delete("/{job_id}/share/{email}")
@@ -861,7 +857,9 @@ def unshare_download(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    _own_job(db, user, job_id)  # ownership guard (404s if not the caller's job)
+    owned_or_404(
+        db, DownloadJob, job_id, user, what="download"
+    )  # ownership guard (404s if not the caller's job)
     recipient = db.execute(
         select(User).where(func.lower(User.email) == email.strip().lower())
     ).scalar_one_or_none()
@@ -893,7 +891,7 @@ def remove_shared_with_me(
     if row is not None:
         db.delete(row)
         db.commit()
-    return {"removed": job_id}
+    return {"ok": True, "removed": job_id}
 
 
 # --- recipients (for the internal "share with a user" picker) ------------------------------
@@ -923,10 +921,10 @@ def share_recipients(
 def _own_link(db: Session, user: User, link_id: int) -> DownloadLink:
     link = db.get(DownloadLink, link_id)
     if link is None:
-        raise HTTPException(status_code=404, detail="Unknown link")
+        raise not_found("link")
     job = db.get(DownloadJob, link.job_id)
     if job is None or job.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown link")
+        raise not_found("link")
     return link
 
 
@@ -942,7 +940,7 @@ def _link_expiry(days: int | None) -> datetime | None:
 def list_links(
     job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> list[dict]:
-    _own_job(db, user, job_id)
+    owned_or_404(db, DownloadJob, job_id, user, what="download")
     rows = (
         db.execute(
             select(DownloadLink)
@@ -973,9 +971,9 @@ def create_link(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    job = _own_job(db, user, job_id)
+    job = owned_or_404(db, DownloadJob, job_id, user, what="download")
     if job.status != "done" or job.asset_id is None:
-        raise HTTPException(status_code=409, detail="Only a finished download can be shared.")
+        raise refused(409, "share_unfinished")
     pw = body.password.strip()
     link = DownloadLink(
         job_id=job_id,

backend/app/routes/feed.py

@@ -1,6 +1,6 @@
 from datetime import date, datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, Query
 from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
@@ -29,10 +29,11 @@ from app.models import (
     Video,
     VideoState,
 )
-from app.routes._common import get_or_404
+from app.routes._common import get_or_404, youtube_refusal, not_found
 from app.sync.videos import parse_iso8601_duration
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
+from app.refusal import refused
 
 router = APIRouter(prefix="/api", tags=["feed"])
 
@@ -120,7 +121,7 @@ def get_feed(
             vals, cursor_id = decode_cursor(keys, cursor)
         except ValueError:
             # `from None`: the ValueError is an expected bad-input signal, not an error to chain.
-            raise HTTPException(status_code=400, detail="Invalid feed cursor") from None
+            raise refused(400, "invalid_cursor") from None
         for k, v in zip(keys, vals):
             k["value"] = v
         query = query.where(keyset_predicate(keys, cursor_id))
@@ -235,7 +236,7 @@ def set_video_state(
 ) -> dict:
     status = body.status
     if status not in VALID_STATES:
-        raise HTTPException(status_code=400, detail=f"status must be one of {VALID_STATES}")
+        raise refused(400, "invalid_status")
     get_or_404(db, Video, video_id, what="video")
 
     now = datetime.now(timezone.utc)
@@ -256,9 +257,11 @@ def set_video_state(
                 db.delete(row)
             try:
                 db.commit()
+            # silent-ok: the documented lost race — a concurrent player checkpoint already removed
+            # or moved this row. The state the caller asked for is the state that holds either way.
             except StaleDataError:
                 db.rollback()
-        return {"video_id": video_id, "status": "new"}
+        return {"ok": True, "video_id": video_id, "status": "new"}
 
     # watched / hidden: atomic upsert. The player marks "watched" at end-of-playback at
     # the same instant a progress checkpoint may DELETE the in-progress row; a plain
@@ -279,7 +282,7 @@ def set_video_state(
     )
     db.execute(stmt)
     db.commit()
-    return {"video_id": video_id, "status": status}
+    return {"ok": True, "video_id": video_id, "status": status}
 
 
 @router.delete("/videos/{video_id}/state")
@@ -298,9 +301,10 @@ def clear_video_state(
         db.delete(row)
         try:
             db.commit()
+        # silent-ok: the row went under the delete, which is the outcome the delete wanted.
         except StaleDataError:
             db.rollback()
-    return {"video_id": video_id, "status": "new", "position_seconds": 0}
+    return {"ok": True, "video_id": video_id, "status": "new", "position_seconds": 0}
 
 
 class VideoProgressIn(BaseModel):
@@ -355,9 +359,10 @@ def set_video_progress(
             # have removed/updated this row already — tolerate the lost race.
             try:
                 db.commit()
+            # silent-ok: exactly the race the comment above describes; the response stays true.
             except StaleDataError:
                 db.rollback()
-        return {"video_id": video_id, "position_seconds": 0}
+        return {"ok": True, "video_id": video_id, "position_seconds": 0}
 
     if row is None:
         row = VideoState(user_id=user.id, video_id=video_id)
@@ -365,7 +370,7 @@ def set_video_progress(
     row.position_seconds = position
     row.progress_updated_at = datetime.now(timezone.utc)
     db.commit()
-    return {"video_id": video_id, "position_seconds": position}
+    return {"ok": True, "video_id": video_id, "position_seconds": position}
 
 
 @router.get("/videos/{video_id}")
@@ -398,7 +403,7 @@ def get_video_detail(
     # The DB path above is free; the off-catalog YouTube lookup below spends a quota unit, so the
     # demo account can't reach it — it just sees "unknown" for a video we don't already store.
     if user.is_demo:
-        raise HTTPException(status_code=404, detail="Unknown video")
+        raise not_found("video")
 
     try:
         with (
@@ -407,9 +412,9 @@ def get_video_detail(
         ):
             items = yt.get_videos([video_id])
     except YouTubeError as exc:
-        raise HTTPException(status_code=422, detail=f"YouTube lookup failed: {exc}")
+        raise youtube_refusal(exc)
     if not items:
-        raise HTTPException(status_code=404, detail="Unknown video")
+        raise not_found("video")
 
     snippet = items[0].get("snippet", {})
     stats = items[0].get("statistics", {})

backend/app/routes/me.py

@@ -23,6 +23,9 @@ from app import logs
 from app import sysconfig
 from app.db import get_db
 from app.models import Invite, User
+from app.utils import iso
+from app.refusal import refused
+from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/me", tags=["me"])
 
@@ -69,7 +72,7 @@ def switch_account(
     here) are allowed, and access is re-checked in case the invite was revoked since."""
     target = body.user_id
     if target not in (request.session.get("account_ids") or []):
-        raise HTTPException(status_code=403, detail="Not an account you've signed into here.")
+        raise refused(403, "not_your_account")
     # An account `_session_user` would refuse — gone, deactivated, suspended, or its session revoked — is
     # refused here too, and dropped from the switch list the way `_session_user` drops it. Made the session
     # default instead, the next request's current_user would refuse it as the DEFAULT and clear the whole
@@ -77,22 +80,20 @@ def switch_account(
     u = db.get(User, target)
     if u is None:
         drop_from_wallet(request.session, target)
-        raise HTTPException(status_code=404, detail="That account no longer exists.")
+        raise not_found("account")
     if not is_allowed(db, u.email):
-        raise HTTPException(status_code=403, detail="That account no longer has access.")
+        raise refused(403, "account_no_access")
     if not u.is_active:
         drop_from_wallet(request.session, target)
-        raise HTTPException(status_code=403, detail="That account no longer has access.")
+        raise refused(403, "account_no_access")
     if u.is_suspended:
         drop_from_wallet(request.session, target)
-        raise HTTPException(status_code=403, detail="That account is suspended.")
+        raise refused(403, "account_suspended")
     # Revoked: a password reset/change or "log out everywhere" bumped the account's epoch.
     epochs = request.session.get("epochs") or {}
     if int(epochs.get(str(target), 0)) != (u.session_epoch or 0):
         drop_from_wallet(request.session, target)
-        raise HTTPException(
-            status_code=403, detail="That account was signed out elsewhere — sign in again."
-        )
+        raise refused(403, "account_signed_out")
     request.session["user_id"] = target
     return {"ok": True, "user_id": target}
 
@@ -138,6 +139,9 @@ def get_me(
             user.google_email if user.google_email and user.google_email != user.email else None
         ),
         "has_password": user.password_hash is not None,
+        # The account's latest sign-in on any device — shown in Settings → Account, so a sign-in the
+        # user does not recognise is something they can see (null: none since 0.88, or the demo).
+        "last_login_at": iso(user.last_login_at),
         # Instance-wide: whether Google sign-in / YouTube connect is available at all (the UI hides
         # YouTube-access affordances and the onboarding nudge when it isn't configured).
         "google_enabled": google_enabled(db),
@@ -177,10 +181,7 @@ def delete_my_account(
     if user.is_demo:
         raise HTTPException(status_code=403, detail={"code": "demo", "reason": "delete_account"})
     if user.role == "admin" and count_admins(db) <= 1:
-        raise HTTPException(
-            status_code=400,
-            detail="You're the only admin — promote another admin before deleting your account.",
-        )
+        raise refused(400, "only_admin_delete")
     user_id = user.id
     # Full erasure (cascades) + access-request cleanup + Google-grant revocation; shared with the
     # admin delete path. Capture the id first — `user` is detached once purge_user deletes the row.
@@ -213,7 +214,7 @@ def update_preferences(
     user.preferences = merged
     db.add(user)
     db.commit()
-    return {"preferences": merged}
+    return {"ok": True, "preferences": merged}
 
 
 class DiagnosticsIn(BaseModel):

backend/app/routes/messages.py

@@ -16,7 +16,7 @@ routing and unread counts.
 
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi import APIRouter, Depends, WebSocket, WebSocketDisconnect
 from pydantic import BaseModel
 from sqlalchemy import and_, case, delete, func, or_, select
 from sqlalchemy.orm import Session
@@ -29,6 +29,8 @@ from app.realtime import manager
 from app.security import verify_password
 from app.userscope import is_messageable_user, messageable_clauses
 from app.utils import iso
+from app.refusal import refused
+from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/messages", tags=["messages"])
 
@@ -152,7 +154,7 @@ def setup_keys(
     """Store this user's public key + passphrase-wrapped private key. Set-once: changing the
     key would orphan every existing conversation key, so re-setup is rejected here."""
     if db.get(MessageKey, user.id) is not None:
-        raise HTTPException(status_code=409, detail="Secure messaging is already set up.")
+        raise refused(409, "messaging_set_up")
     db.add(
         MessageKey(
             user_id=user.id,
@@ -164,7 +166,7 @@ def setup_keys(
         )
     )
     db.commit()
-    return {"configured": True}
+    return {"ok": True, "configured": True}
 
 
 @router.post("/keys/reset")
@@ -185,11 +187,11 @@ def reset_keys(
     less (Google-only) account has nothing to re-verify, so it relies on its live session plus the
     client-side danger confirmation."""
     if not _reset_key_limiter.allow(str(user.id)):
-        raise HTTPException(status_code=429, detail="Too many attempts. Try again shortly.")
+        raise refused(429, "too_many_attempts")
     if user.password_hash and not verify_password(
         payload.current_password or "", user.password_hash
     ):
-        raise HTTPException(status_code=403, detail="Current password is incorrect.")
+        raise refused(403, "wrong_password")
     # Delete the now-dead ciphertext first (both directions), then the wrapped keypair itself so a
     # fresh setup is allowed. Order doesn't matter (no FK between them), but do it in one commit.
     db.execute(
@@ -202,7 +204,7 @@ def reset_keys(
     if key is not None:
         db.delete(key)
     db.commit()
-    return {"configured": False}
+    return {"ok": True, "configured": False}
 
 
 @router.get("/keys/{user_id}")
@@ -223,10 +225,10 @@ def public_key(
     p = db.get(User, user_id)
     has_history = db.scalar(select(Message.id).where(cond).limit(1))
     if p is None or (not is_messageable_user(p) and not has_history):
-        raise HTTPException(status_code=404, detail="User not found")
+        raise not_found("user")
     k = db.get(MessageKey, user_id)
     if k is None:
-        raise HTTPException(status_code=404, detail="That member hasn't set up messaging yet.")
+        raise refused(404, "no_messaging")
     return {"user_id": user_id, "public_key": k.public_key}
 
 
@@ -344,7 +346,7 @@ def get_thread(
         # still opens). Otherwise the same 404 as a non-existent id → no enumeration oracle.
         has_history = db.scalar(select(Message.id).where(cond).limit(1))
         if p is None or (not is_messageable_user(p) and not has_history):
-            raise HTTPException(status_code=404, detail="User not found")
+            raise not_found("user")
         partner = _serialize_user(p)
     msgs = (
         db.execute(select(Message).where(cond).order_by(Message.created_at.asc())).scalars().all()
@@ -374,20 +376,20 @@ def send_message(
     """Send an end-to-end-encrypted message. The server stores only the ciphertext the client
     produced, then pushes it live to the recipient (and the sender's other devices)."""
     if not _send_limiter.allow(f"msg:{user.id}"):
-        raise HTTPException(status_code=429, detail="Too many messages — slow down a moment.")
+        raise refused(429, "message_rate")
     ct = (payload.ciphertext or "").strip()
     iv = (payload.iv or "").strip()
     if not ct or not iv:
-        raise HTTPException(status_code=400, detail="Message is empty.")
+        raise refused(400, "message_empty")
     if len(ct) > MAX_CIPHERTEXT:
-        raise HTTPException(status_code=400, detail="Message is too long.")
+        raise refused(400, "message_too_long")
     if payload.recipient_id == user.id:
-        raise HTTPException(status_code=400, detail="You can't message yourself.")
+        raise refused(400, "message_self")
     recipient = db.get(User, payload.recipient_id)
     if not is_messageable_user(recipient):
-        raise HTTPException(status_code=404, detail="Recipient not available.")
+        raise not_found("recipient")
     if db.get(MessageKey, recipient.id) is None:
-        raise HTTPException(status_code=404, detail="That member hasn't set up messaging yet.")
+        raise refused(404, "no_messaging")
     m = Message(kind="user", sender_id=user.id, recipient_id=recipient.id, ciphertext=ct, iv=iv)
     db.add(m)
     db.commit()
@@ -449,6 +451,8 @@ async def messages_ws(ws: WebSocket) -> None:
     try:
         while True:
             await ws.receive_text()
+    # silent-ok: the ordinary way a chat socket ends — a closed tab. The `finally` below is the
+    # whole handling, and nothing failed.
     except WebSocketDisconnect:
         pass
     finally:

backend/app/routes/notifications.py

@@ -5,7 +5,7 @@ All endpoints use `current_user` (not `require_human`): notifications and their
 state are personal UI state with no quota or YouTube involvement, so the shared demo account
 manages its own inbox normally."""
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, Query
 from sqlalchemy import func, select, update
 from sqlalchemy.orm import Session
 
@@ -14,6 +14,7 @@ from app.db import get_db
 from app.models import Notification, User
 from app.notifications import trim_read
 from app.utils import iso
+from app.routes._common import owned_or_404
 
 router = APIRouter(prefix="/api/me/notifications", tags=["notifications"])
 
@@ -72,20 +73,13 @@ def unread_count(user: User = Depends(current_user), db: Session = Depends(get_d
     return {"count": count or 0}
 
 
-def _owned(db: Session, notification_id: int, user: User) -> Notification:
-    n = db.get(Notification, notification_id)
-    if n is None or n.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Notification not found")
-    return n
-
-
 @router.post("/{notification_id}/read")
 def mark_read(
     notification_id: int,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    n = _owned(db, notification_id, user)
+    n = owned_or_404(db, Notification, notification_id, user, what="notification")
     n.read = True
     db.commit()
     trim_read(db, user.id)
@@ -110,7 +104,7 @@ def dismiss(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    n = _owned(db, notification_id, user)
+    n = owned_or_404(db, Notification, notification_id, user, what="notification")
     # Dismiss implies read (it no longer counts toward the unread badge).
     n.dismissed = True
     n.read = True

backend/app/routes/playlists.py

@@ -3,11 +3,10 @@ CRUD (create / rename / delete, add / remove / reorder items) plus YouTube two-w
 mirror the user's own YouTube playlists in (`/sync-youtube`) and push/revert local edits back
 out (`/{id}/push-plan`, `/{id}/revert-youtube`), behind the optional write scope."""
 
-from datetime import datetime, timezone
-
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
 from sqlalchemy import func, select, and_
+from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session, aliased
 
 from app import quota
@@ -23,7 +22,7 @@ from app.sync.playlists import (
     sync_user_playlists,
 )
 from app.ratelimit import RateLimiter
-from app.routes._common import get_or_404, owned_or_404
+from app.routes._common import get_or_404, owned_or_404, youtube_refusal
 from app.youtube.client import YouTubeClient, YouTubeError
 
 router = APIRouter(prefix="/api/playlists", tags=["playlists"])
@@ -48,10 +47,6 @@ def _check_pull_cooldown(user: User) -> None:
         raise HTTPException(status_code=429, detail={"code": "sync_cooldown"})
 
 
-def _own_playlist(db: Session, user: User, playlist_id: int) -> Playlist:
-    return owned_or_404(db, Playlist, playlist_id, user, what="playlist")
-
-
 def _refused(status: int, reason: str) -> HTTPException:
     """A playlist action the server refuses, as a reason the UI translates
     (`playlists.errors.<reason>`) — a bare English detail reached the Hungarian UI verbatim."""
@@ -64,8 +59,11 @@ def _touch(pl: Playlist) -> None:
     `UpdatedAtMixin`'s `onupdate` fires on an UPDATE of the PLAYLIST row, and add / remove /
     reorder / move write the item rows instead — so without this the rail's "recently changed"
     sort would only ever see renames. The assignment is what makes the column mean "last time
-    this list changed", which is what the rail promises the reader."""
-    pl.updated_at = datetime.now(timezone.utc)
+    this list changed", which is what the rail promises the reader.
+
+    The DATABASE's clock, like the mixin's own `onupdate`: one sort key written from two clocks
+    (this process's and Postgres's) could order a rename and an item edit the wrong way round."""
+    pl.updated_at = func.now()
 
 
 def _next_playlist_position(db: Session, user_id: int) -> int:
@@ -108,7 +106,7 @@ def _add_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) ->
     if mark_dirty:
         recompute_dirty(db, pl)
     _touch(pl)
-    db.commit()
+    db.flush()  # the handler commits (CLAUDE.md: helpers flush)
     return True
 
 
@@ -126,7 +124,7 @@ def _remove_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool)
     if mark_dirty:
         recompute_dirty(db, pl)
     _touch(pl)
-    db.commit()
+    db.flush()  # the handler commits (CLAUDE.md: helpers flush)
     return True
 
 
@@ -280,7 +278,7 @@ def _watch_later(db: Session, user: User) -> Playlist:
             position=_next_playlist_position(db, user.id),
         )
         db.add(pl)
-        db.commit()
+        db.flush()  # the id, for the item the caller adds next; the handler commits
     return pl
 
 
@@ -295,7 +293,8 @@ def add_watch_later(
     get_or_404(db, Video, video_id, what="video")
     pl = _watch_later(db, user)
     _add_item(db, pl, video_id, mark_dirty=False)
-    return {"saved": True, "playlist_id": pl.id}
+    db.commit()
+    return {"ok": True, "saved": True, "playlist_id": pl.id}
 
 
 @router.delete("/watch-later/{video_id}")
@@ -309,7 +308,8 @@ def remove_watch_later(
     )
     if pl is not None:
         _remove_item(db, pl, video_id, mark_dirty=False)
-    return {"saved": False}
+        db.commit()
+    return {"ok": True, "saved": False}
 
 
 @router.post("/sync-youtube")
@@ -322,8 +322,12 @@ def sync_youtube(
     if not has_read_scope(user):
         raise _refused(403, "youtube_read_scope")
     _check_pull_cooldown(user)
-    with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
-        return sync_user_playlists(db, user)
+    try:
+        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
+            return {"ok": True, **sync_user_playlists(db, user)}
+    except YouTubeError as exc:
+        db.rollback()
+        raise youtube_refusal(exc)
 
 
 @router.post("/{playlist_id}/revert-youtube")
@@ -335,7 +339,7 @@ def revert_youtube(
     """Reset one YouTube-linked playlist to its current YouTube state, discarding local
     edits (and clearing the dirty flag). The user-facing 'undo all my changes' for a list
     once the in-session undo history is gone."""
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     if not pl.yt_playlist_id:
         raise _refused(400, "not_on_youtube")
     if not has_read_scope(user):
@@ -343,16 +347,16 @@ def revert_youtube(
     _check_pull_cooldown(user)
     try:
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
-            return repull_playlist(db, user, pl)
-    except YouTubeError:
+            return {"ok": True, **repull_playlist(db, user, pl)}
+    except YouTubeError as exc:
         db.rollback()
-        raise _refused(422, "youtube_failed")
+        raise youtube_refusal(exc)
 
 
 def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
     """A local playlist the user may push to YouTube (create or update). The built-in
     Watch later and read-only YouTube mirrors are never pushable."""
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     if pl.kind == "watch_later":
         raise _refused(400, "watch_later_not_pushable")
     return pl
@@ -371,8 +375,8 @@ def push_plan(
     try:
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
             plan = plan_merge(db, user, pl)
-    except YouTubeError:
-        raise _refused(422, "youtube_failed")
+    except YouTubeError as exc:
+        raise youtube_refusal(exc)
     plan["remaining_today"] = quota.remaining_today(db)
     plan["affordable"] = plan["units_estimate"] <= plan["remaining_today"]
     return plan
@@ -403,10 +407,10 @@ def push(
             plan = plan_merge(db, user, pl, live=live)
             if plan["units_estimate"] > quota.remaining_today(db):
                 raise _refused(429, "quota_exceeded")
-            return merge_playlist(db, user, pl, live=live)
-    except YouTubeError:
+            return {"ok": True, **merge_playlist(db, user, pl, live=live)}
+    except YouTubeError as exc:
         db.rollback()
-        raise _refused(422, "youtube_failed")
+        raise youtube_refusal(exc)
 
 
 @router.get("/{playlist_id}")
@@ -415,7 +419,7 @@ def get_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     state = aliased(VideoState)
     rows = db.execute(
         select(*feed_columns(user, state))
@@ -447,7 +451,7 @@ def rename_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     if "name" in body.model_fields_set:
         name = (body.name or "").strip()
         if not name:
@@ -484,7 +488,7 @@ def delete_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     if pl.kind == "watch_later":
         raise _refused(400, "watch_later_undeletable")
     if on_youtube:
@@ -496,8 +500,8 @@ def delete_playlist(
             with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_DELETE):
                 with YouTubeClient(db, user) as yt:
                     yt.delete_playlist(pl.yt_playlist_id)
-        except YouTubeError:
-            raise _refused(422, "youtube_failed")
+        except YouTubeError as exc:
+            raise youtube_refusal(exc)
     db.delete(pl)  # items cascade
     db.commit()
     return {"deleted": playlist_id}
@@ -510,11 +514,12 @@ def add_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     video_id = body.video_id
     get_or_404(db, Video, video_id, what="video")
     _add_item(db, pl, video_id, mark_dirty=True)
-    return {"playlist_id": pl.id, "video_id": video_id}
+    db.commit()
+    return {"ok": True, "playlist_id": pl.id, "video_id": video_id}
 
 
 @router.delete("/{playlist_id}/items/{video_id}")
@@ -524,9 +529,10 @@ def remove_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     _remove_item(db, pl, video_id, mark_dirty=True)
-    return {"playlist_id": pl.id, "video_id": video_id}
+    db.commit()
+    return {"ok": True, "playlist_id": pl.id, "video_id": video_id}
 
 
 class MoveItemIn(BaseModel):
@@ -548,7 +554,7 @@ def move_item(
     exactly the kind of half-applied state this codebase treats as a bug rather than an edge
     case. Idempotent: if the video is already in the target, the source row is simply dropped
     (moving into a list that already has it is a removal, not a duplicate)."""
-    src = _own_playlist(db, user, playlist_id)
+    src = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     # Its own reason: "this playlist doesn't exist any more" about a TARGET that is gone was read as
     # the list on screen — which is still there.
     dst = owned_or_404(db, Playlist, body.target_playlist_id, user, what="move_target")
@@ -571,19 +577,33 @@ def move_item(
             PlaylistItem.playlist_id == dst.id, PlaylistItem.video_id == video_id
         )
     )
-    if already is not None:
-        db.delete(item)  # the uq_playlist_video constraint would reject a second row anyway
-    else:
+    dst_changed = False
+    if already is None:
         # Re-parent the existing row rather than delete+insert: `added_at` ("when I saved this")
-        # survives the move, and there is no window where the video belongs to neither list.
-        item.playlist_id = dst.id
-        item.position = _next_item_position(db, dst.id)
-    # Both sides changed, so both get the dirty recompute and the timestamp — the asymmetric
-    # version of this (touching only the source) is the recurring smell CLAUDE.md warns about.
+        # survives the move, and there is no window where the video belongs to neither list. The
+        # check above is not a lock: a second tab's add or the scheduler's YouTube merge can insert
+        # the same (playlist, video) in between, and uq_playlist_video then refuses the re-parent.
+        # That is the already-present outcome arriving late, not a failure — answer it the same way
+        # instead of a raw 500.
+        try:
+            with db.begin_nested():
+                item.playlist_id = dst.id
+                item.position = _next_item_position(db, dst.id)
+                db.flush()
+            dst_changed = True
+        # silent-ok: the conflict IS the answer — the target already holds the video, which is the
+        # idempotent outcome; the savepoint put the row back in the source list, dropped below.
+        except IntegrityError:
+            pass
+    if not dst_changed:
+        db.delete(item)
+    # The source always changed; the target only when the row landed in it. `_touch` on a target
+    # that already had the video promoted an untouched list in the rail's "recently changed" sort.
     recompute_dirty(db, src)
-    recompute_dirty(db, dst)
     _touch(src)
-    _touch(dst)
+    if dst_changed:
+        recompute_dirty(db, dst)
+        _touch(dst)
     db.commit()
     return {"ok": True, "from_playlist_id": src.id, "to_playlist_id": dst.id, "video_id": video_id}
 
@@ -599,7 +619,7 @@ def reorder_items(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     order = body.video_ids
     items = {
         it.video_id: it
@@ -625,4 +645,4 @@ def reorder_items(
     recompute_dirty(db, pl)
     _touch(pl)
     db.commit()
-    return {"playlist_id": pl.id, "count": pos}
+    return {"ok": True, "playlist_id": pl.id, "count": pos}

backend/app/routes/plex/_shared.py

@@ -1,20 +1,19 @@
 """Shared helpers, serializers and constants for the plex route package."""
 
-import logging
-
-from fastapi import HTTPException
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.models import PlexItem
 from app.plex.lookups import by_rating_key
+from app.routes._common import not_found
 
-log = logging.getLogger("siftlode.plex")
+log = logs.get_logger(__name__)
 
 
 def item_or_404(db: Session, rating_key: str) -> PlexItem:
     it = by_rating_key(db, PlexItem, rating_key)
     if it is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex item")
+        raise not_found("plex_item")
     return it
 
 

backend/app/routes/plex/admin.py

@@ -2,12 +2,12 @@
 
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.auth import admin_user, current_user
 from app.db import get_db
 from app.models import (
@@ -20,6 +20,9 @@ from app.plex import sync as plex_sync
 from app.plex import watch_sync as plex_watch
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.utils import iso
+from app.refusal import refused
+
+log = logs.get_logger(__name__)
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
@@ -35,10 +38,15 @@ def test_connection(_: User = Depends(admin_user), db: Session = Depends(get_db)
             info = plex.server_info()
             sections = plex.sections()
             media_check = _media_check(db, plex, sections)
-    except PlexNotConfigured as e:
-        raise HTTPException(status_code=400, detail=str(e))
+    except PlexNotConfigured:
+        raise refused(400, "plex_not_configured") from None
     except PlexError as e:
-        raise HTTPException(status_code=422, detail=f"Plex connection failed: {e}")
+        # What the upstream said is for the log, not the toast: it can quote the server URL back.
+        log.warning(
+            "the Plex connection test failed",
+            extra=logs.event("plex.admin.connection_failed", reason=type(e).__name__, error=str(e)),
+        )
+        raise refused(422, "plex_unreachable") from None
     return {
         "ok": True,
         "server_name": info.get("friendlyName") or info.get("title1") or "Plex",
@@ -95,7 +103,7 @@ def _media_check(db: Session, plex: PlexClient, sections: list[dict]) -> dict:
 def trigger_sync(_: User = Depends(admin_user), db: Session = Depends(get_db)) -> dict:
     """Admin: mirror the enabled Plex sections into the local catalog. Synchronous (can take a
     while on a large library); a background/scheduled sync also runs periodically."""
-    return plex_sync.sync(db)
+    return {"ok": True, **plex_sync.sync(db)}
 
 
 def _link_dict(link: PlexLink | None) -> dict:
@@ -129,7 +137,7 @@ def watch_link_set(
     admin token, so no separate Plex login. Enabling it for the first time runs the one-time
     "Plex is master" import immediately so the owner's existing Plex history shows up in Siftlode."""
     if not sysconfig.get_bool(db, "plex_enabled"):
-        raise HTTPException(status_code=409, detail="The Plex module is disabled.")
+        raise refused(409, "plex_disabled")
     enabled = body.enabled
     link = db.execute(select(PlexLink).where(PlexLink.user_id == user.id)).scalars().first()
     if link is None:
@@ -141,7 +149,7 @@ def watch_link_set(
     result: dict = {}
     if enabled and not link.initial_import_done:
         result = plex_watch.import_owner_watch_state(db, link)
-    return {**_link_dict(link), "import": result or None}
+    return {"ok": True, **_link_dict(link), "import": result or None}
 
 
 @router.post("/watch/import")
@@ -150,6 +158,6 @@ def watch_import_now(user: User = Depends(admin_user), db: Session = Depends(get
     intersection; Siftlode-only states are preserved. Idempotent."""
     link = db.execute(select(PlexLink).where(PlexLink.user_id == user.id)).scalars().first()
     if link is None or not link.sync_enabled:
-        raise HTTPException(status_code=409, detail="Enable Plex watch-sync first.")
+        raise refused(409, "watch_sync_off")
     result = plex_watch.import_owner_watch_state(db, link)
-    return {**_link_dict(link), "import": result}
+    return {"ok": True, **_link_dict(link), "import": result}

backend/app/routes/plex/collections.py

@@ -9,6 +9,7 @@ from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.auth import admin_user, current_user
 from app.db import get_db
 from app.models import (
@@ -24,7 +25,12 @@ from app.plex import sync as plex_sync
 from app.plex.cards import movie_card, show_card
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
-from app.plex.query import content_libs, like_escape, runtime_by_key, top_art_keys
+from app.plex.query import content_libs, runtime_by_key, top_art_keys
+from app.utils import like_escape
+from app.refusal import refused
+from app.routes._common import not_found
+
+log = logs.get_logger(__name__)
 
 # The most-restrictive → least ordering used to pick a collection's effective content rating from its
 # members (Plex shows one cert on the collection; we don't store it, so derive it).
@@ -233,7 +239,7 @@ def collection_detail(
     endpoints below."""
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     movies = (
         db.execute(
             select(PlexItem)
@@ -324,9 +330,9 @@ def collection_detail(
 def _editable_collection_or_403(db: Session, rating_key: str) -> PlexCollection:
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     if not _collection_editable(col):
-        raise HTTPException(status_code=403, detail="This collection is read-only")
+        raise refused(403, "collection_read_only")
     return col
 
 
@@ -361,14 +367,13 @@ def _write_or_pending_error(wrote: bool, e: Exception) -> HTTPException:
     Both use 422, NOT a 5xx: the frontend treats 502/503/504 as "gateway unreachable" and raises a
     sticky offline banner (see api/core.ts RETRIABLE_GATEWAY). A 422 surfaces the detail as an ordinary
     action-error toast, which is what both of these are — the app answered, it didn't go unreachable."""
-    if wrote:
-        detail = (
-            "Collection updated in Plex, but refreshing the local copy failed; "
-            f"it will reconcile on the next sync ({e})"
-        )
-    else:
-        detail = f"Plex write failed: {e}"
-    return HTTPException(status_code=422, detail=detail)
+    log.warning(
+        "a Plex collection write did not settle",
+        extra=logs.event(
+            "plex.collections.write_failed", wrote=wrote, reason=type(e).__name__, error=str(e)
+        ),
+    )
+    return refused(422, "collection_pending_sync") if wrote else refused(422, "plex_write_failed")
 
 
 class CreateCollectionIn(BaseModel):
@@ -388,7 +393,7 @@ def create_collection(
     title = body.title.strip()
     seed = body.item_rating_key
     if not title or not seed:
-        raise HTTPException(status_code=400, detail="title and item_rating_key are required")
+        raise refused(400, "collection_fields_required")
     if library:
         lib = (
             db.execute(select(PlexLibrary).where(PlexLibrary.plex_key == library)).scalars().first()
@@ -398,7 +403,7 @@ def create_collection(
         seed_item = by_rating_key(db, PlexItem, seed) or by_rating_key(db, PlexShow, seed)
         lib = db.get(PlexLibrary, seed_item.library_id) if seed_item else None
     if lib is None:
-        raise HTTPException(status_code=404, detail="Unknown library")
+        raise not_found("library")
     _reject_duplicate_name(db, lib.id, title)
     wrote = False
     try:
@@ -472,7 +477,7 @@ def collection_rename(
     col = _editable_collection_or_403(db, rating_key)
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     _reject_duplicate_name(db, col.library_id, title, exclude_rk=rating_key)
     lib = db.get(PlexLibrary, col.library_id)
     wrote = False
@@ -501,7 +506,7 @@ def collection_delete(
         db.commit()
     except (PlexError, PlexNotConfigured) as e:
         db.rollback()
-        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
+        raise _write_or_pending_error(False, e) from None
     return {"deleted": rating_key}
 
 
@@ -520,13 +525,10 @@ def collection_set_editable(
     (IMDb/TMDb/…) can never be made editable — they're regenerated outside Plex."""
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     want = body.editable
     if want and (col.smart or _collection_source(col) != "collection"):
-        raise HTTPException(
-            status_code=400,
-            detail="Smart / auto-list collections can't be made editable",
-        )
+        raise refused(400, "collection_smart")
     col.editable = want
     db.commit()
     return _collection_card(col)

backend/app/routes/plex/detail.py

@@ -5,10 +5,11 @@ import time
 from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.auth import current_user
 from app.db import get_db
 from app.models import (
@@ -29,6 +30,9 @@ from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
 from app.routes.plex._shared import _norm_lang, item_or_404
 from app.routes.plex.collections import _collection_source
+from app.routes._common import not_found
+
+log = logs.get_logger(__name__)
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
@@ -65,7 +69,21 @@ def _show_enrichment(db: Session, rating_key: str) -> tuple[dict, list]:
                 related_f = ex.submit(plex.related, rating_key)  # swallows its own errors → []
                 meta = meta_f.result() or {}
                 related_raw = related_f.result()
-    except (PlexError, PlexNotConfigured):
+    except PlexNotConfigured:
+        # silent-ok: not a failure but a state — this instance has no Plex server, and the page
+        # is meant to render from the local rows alone.
+        return {}, []
+    except PlexError as exc:
+        # The detail page still renders, from the rows the sync left behind: no cast, no related
+        # strip, no rich detail. Indistinguishable on screen from a show that simply has none.
+        log.warning(
+            "live Plex enrichment failed for a show",
+            extra=logs.event(
+                "plex.detail.show_enrich_failed",
+                rating_key=rating_key,
+                reason=type(exc).__name__,
+            ),
+        )
         return {}, []
     # Don't cache an EMPTY related list: plex.related() swallows a transient failure as [] (same as a
     # genuinely no-related show), so caching it would serve an empty "related" section for the whole TTL
@@ -92,7 +110,7 @@ def show_detail(
     hu = _norm_lang(lang) == "hu"
     sh = by_rating_key(db, PlexShow, rating_key)
     if sh is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex show")
+        raise not_found("show")
     seasons = (
         db.execute(
             select(PlexSeason)
@@ -145,12 +163,26 @@ def show_detail(
             sh.people_enriched_at = datetime.now(timezone.utc)
             try:
                 db.commit()
-            except Exception:
+            except Exception:  # noqa: BLE001 — a failed enrich must not fail the page
+                # The rollback un-does the enrichment AND the `people_enriched_at` stamp, so the
+                # next view tries again — but if the commit keeps failing nobody ever hears, and
+                # the cast section stays empty for good.
+                log.warning(
+                    "the show enrichment could not be committed",
+                    extra=logs.event(
+                        "plex.detail.enrich_commit_failed", rating_key=sh.rating_key, kind="show"
+                    ),
+                )
                 db.rollback()
-    except Exception:
+    except Exception:  # noqa: BLE001 — the local episode list must render whatever Plex does
         # Best-effort only — the local episode list is already assembled, so any live-Plex failure
-        # (not configured, HTTP/JSON shape) must degrade, not 500.
-        pass
+        # (not configured, HTTP/JSON shape) must degrade, not 500. With the traceback, because what
+        # is left in here after the Plex errors above are handled is our own shape bugs.
+        log.warning(
+            "the live part of a show page could not be built",
+            extra=logs.event("plex.detail.show_extras_failed", rating_key=sh.rating_key),
+            exc_info=True,
+        )
 
     imdb_id = sh.imdb_id
     return {
@@ -295,6 +327,14 @@ def _episode_nav(db: Session, it: PlexItem) -> tuple[str | None, str | None]:
     try:
         i = keys.index(it.rating_key)
     except ValueError:
+        # An episode missing from its own show's ordered list — the two came out of the same sync,
+        # so this is a gap in it. The page loses its previous/next arrows and says nothing.
+        log.info(
+            "an episode is not in its show's episode list; no previous/next",
+            extra=logs.event(
+                "plex.detail.episode_nav_missing", rating_key=it.rating_key, show_id=it.show_id
+            ),
+        )
         return None, None
     return (keys[i - 1] if i > 0 else None), (keys[i + 1] if i < len(keys) - 1 else None)
 
@@ -366,8 +406,32 @@ def item_detail(
                         "text": codec not in subtitles.BITMAP_SUBS,
                     }
                 )
-    except Exception:
-        pass  # live extras (markers/streams) are best-effort; any live-Plex failure must degrade, not 500 — playback works without them
+    # Best-effort, but not free: what either branch drops is the subtitle stream list and the intro
+    # markers, so the player offers no subtitles and no skip button — and looks like a file that has
+    # neither.
+    except PlexNotConfigured:
+        # silent-ok: not a failure but a state — no Plex server, and nothing to play from anyway.
+        pass
+    except PlexError as exc:
+        log.warning(
+            "the live extras for an item could not be fetched",
+            extra=logs.event(
+                "plex.detail.extras_failed",
+                rating_key=it.rating_key,
+                kind=it.kind,
+                reason=type(exc).__name__,
+            ),
+        )
+    except Exception:  # noqa: BLE001 — playback works without the extras; never 500 here
+        # Plex answered and WE could not read it — a shape our parsing does not expect. The same
+        # split `show_detail` makes: the stack is the only thing that says where.
+        log.warning(
+            "the live extras for an item could not be read",
+            extra=logs.event(
+                "plex.detail.extras_unreadable", rating_key=it.rating_key, kind=it.kind
+            ),
+            exc_info=True,
+        )
 
     # Lazy enrichment (movies only): the live fetch above carries the FULL cast + rich detail (the sync
     # only stored the listing's top ~3), so fill a not-yet-enriched movie — its cast becomes filterable
@@ -380,7 +444,15 @@ def item_detail(
         it.people_enriched_at = datetime.now(timezone.utc)
         try:
             db.commit()
-        except Exception:
+        except Exception:  # noqa: BLE001 — a failed enrich must not fail the page
+            # Same as the show path above: the info page then serves the three names the listing
+            # sync stored, and the full cast it just fetched is thrown away unreported.
+            log.warning(
+                "the movie enrichment could not be committed",
+                extra=logs.event(
+                    "plex.detail.enrich_commit_failed", rating_key=it.rating_key, kind="movie"
+                ),
+            )
             db.rollback()
 
     hu = lang == "hu"

backend/app/routes/plex/discover.py

@@ -32,12 +32,12 @@ from app.plex.query import (
     meta_filter_conds,
     top_art_keys,
 )
+from app.discover.queries import RAIL_LIMIT
 from app.plex.tmdb import resolve_recs
 from app.routes.plex._shared import _norm_lang
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
-RAIL_LIMIT = 20
 GENRE_TILES = 12
 SURPRISE_PER_KIND = 3  # Surprise-me: at most this many movies + this many shows (6 total)
 

backend/app/routes/plex/people.py

@@ -1,6 +1,5 @@
 """Plex people: cast/crew filter-chip cards + a single person's filmography page."""
 
-import logging
 import threading
 import time
 
@@ -8,6 +7,7 @@ from fastapi import APIRouter, BackgroundTasks, Depends
 from sqlalchemy import func, or_, select
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.auth import current_user
 from app.db import SessionLocal, get_db
 from app.models import (
@@ -22,7 +22,7 @@ from app.plex.cards import movie_card, show_card
 from app.plex.query import content_libs, split_csv
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
-log = logging.getLogger("siftlode.plex")
+log = logs.get_logger(__name__)
 
 
 def _resolve_known_for(

backend/app/routes/plex/playback.py

@@ -17,7 +17,8 @@ from fastapi import (
 )
 from fastapi.responses import FileResponse
 from pydantic import BaseModel, ConfigDict, Field
-from sqlalchemy import select
+from sqlalchemy import select, update
+from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
 from app.auth import current_user, resolved_user_id
@@ -38,6 +39,8 @@ from app.plex import stream as plex_stream
 from app.plex import watch_sync as plex_watch
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.routes.plex._shared import item_or_404
+from app.refusal import refused
+from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
@@ -48,7 +51,7 @@ def _require_session(request: Request) -> int:
     low-sensitivity; a valid session is enough."""
     uid, _ = resolved_user_id(request)
     if not uid:
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        raise refused(401, "not_authenticated")
     return uid
 
 
@@ -77,15 +80,17 @@ def image(rating_key: str, request: Request, variant: str = "thumb") -> Response
         with SessionLocal() as db:
             key = imgcache.key_for(db, str(rating_key), v)
             if not key:
-                raise HTTPException(status_code=404, detail="No image")
+                raise not_found("image")
             plex = PlexClient(db)  # reads base URL + token now; the fetch below needs no DB
-    except PlexNotConfigured as e:
-        raise HTTPException(status_code=400, detail=str(e))
+    except PlexNotConfigured:
+        raise refused(400, "plex_not_configured") from None
     try:
         with plex:
             data, ct = plex.image_bytes(key, w, h)
-    except PlexError as e:
-        raise HTTPException(status_code=502, detail=f"Plex image fetch failed: {e}")
+    # silent-ok: a byte proxy for an <img>; the browser shows the placeholder and no reader sees the
+    # detail — the 502 is the whole answer, as for the person-image proxy below.
+    except PlexError:
+        raise refused(502, "image_fetch_failed") from None
     imgcache.write(cache_key, data, ct)
     return imgcache.response(data, ct)
 
@@ -120,7 +125,7 @@ def subtitle_status(
 
     `at` is the viewer's absolute position: the extractor windows around it, so what gets read first
     is the part actually about to be watched."""
-    return subtitles.ensure(rating_key, sub_ord, at)
+    return subtitles.ensure(rating_key, sub_ord, at, viewer=user.id)
 
 
 @router.get("/subtitle/{rating_key}/{sub_ord}")
@@ -213,7 +218,7 @@ def person_image(u: str, request: Request) -> Response:
     Signed-session auth (no DB) so it, like /image, never holds a pool connection during the fetch."""
     _require_session(request)
     if not u.startswith(plex_people.PERSON_IMG_HOST):
-        raise HTTPException(status_code=400, detail="Unsupported image host")
+        raise refused(400, "image_host")
     cache_key = "person_" + hashlib.sha1(u.encode()).hexdigest()
     hit = imgcache.read(cache_key)
     if hit:
@@ -223,7 +228,7 @@ def person_image(u: str, request: Request) -> Response:
             r = c.get(u)
             r.raise_for_status()
     except httpx.HTTPError:
-        raise HTTPException(status_code=502, detail="Image fetch failed")
+        raise refused(502, "image_fetch_failed")
     ct = r.headers.get("content-type", "image/jpeg")
     imgcache.write(cache_key, r.content, ct)
     return imgcache.response(r.content, ct)
@@ -295,6 +300,37 @@ def _push_watch(
     )
 
 
+def _mark_finished(db: Session, user_id: int, item_id: int, now: datetime) -> bool:
+    """Mark the item watched (position cleared) and say whether THIS call made it so. Two near-end
+    checkpoints arrive together routinely (the 10 s tick and the debounced `seeked` flush), and a
+    read-then-write let both see "not watched" and both scrobble. The transition is decided by the
+    write itself: an insert that did not conflict, or an update conditional on the old status —
+    under READ COMMITTED the second writer re-reads the committed row and matches nothing."""
+    values = {
+        "status": "watched",
+        "watched_at": now,
+        "position_seconds": 0,
+        "progress_updated_at": now,
+        "synced_to_plex": False,
+    }
+    inserted = db.execute(
+        pg_insert(PlexState)
+        .values(user_id=user_id, item_id=item_id, **values)
+        .on_conflict_do_nothing(constraint="uq_plex_user_item")
+        .returning(PlexState.id)
+    ).first()
+    if inserted is not None:
+        return True
+    mine = (PlexState.user_id == user_id) & (PlexState.item_id == item_id)
+    if db.execute(
+        update(PlexState).where(mine, PlexState.status != "watched").values(values)
+    ).rowcount:
+        return True
+    # Already watched: a re-finish still restamps the row, as it always did — just no scrobble.
+    db.execute(update(PlexState).where(mine).values(values))
+    return False
+
+
 class ItemProgressIn(BaseModel):
     # Finite only: JSON parsing here accepts `Infinity`/`NaN`, and the handler's `int()` turned
     # one into a 500.
@@ -330,11 +366,27 @@ def item_progress(
     # finish latch is up, or before the first position is known. Those are the states in which
     # reaping is the right answer anyway, and a viewer who scrubs back into a reaped session gets
     # the same 404 → reclaim the player already handles.
-    plex_stream.touch_session(str(rating_key))
+    plex_stream.touch_session(user.id, str(rating_key))
     position = max(0, int(body.position_seconds))
     duration = int(body.duration_seconds)
     final = body.final
     now = datetime.now(timezone.utc)
+    near_end = duration > 0 and position > duration - _FINISH_MARGIN_S
+    if near_end:
+        flipped = _mark_finished(db, user.id, it.id, now)
+        # The finish supersedes every resume push still in flight for this item: stamping it as the
+        # latest push makes `_resume_push_superseded` drop them. Popping the entry instead (to keep
+        # the map small) removed the very guard, and an older resume push could then land at Plex
+        # AFTER the scrobble and revive a resume point on a watched item. Eviction bounds the map.
+        with _push_throttle_lock:
+            _last_push_at[(user.id, it.id)] = now
+        db.commit()
+        # Only the checkpoint that flipped the row scrobbles: a later checkpoint of the same finished
+        # item — or a second one racing this one — would otherwise bump Plex's viewCount again.
+        if flipped:
+            _push_watch(background, db, user.id, it.id, rating_key, "watched")
+        return {"ok": True, "status": "watched", "position_seconds": 0}
+
     st = (
         db.execute(
             select(PlexState).where(PlexState.user_id == user.id, PlexState.item_id == it.id)
@@ -342,28 +394,6 @@ def item_progress(
         .scalars()
         .first()
     )
-    was_watched = st is not None and st.status == "watched"
-
-    near_end = duration > 0 and position > duration - _FINISH_MARGIN_S
-    if near_end:
-        if st is None:
-            st = PlexState(user_id=user.id, item_id=it.id)
-            db.add(st)
-        st.status = "watched"
-        st.watched_at = now
-        st.position_seconds = 0
-        st.progress_updated_at = now
-        st.synced_to_plex = False
-        # Terminal state for resume write-back: drop the throttle/ordering entry so the map doesn't
-        # retain a dead key for every finished item.
-        with _push_throttle_lock:
-            _last_push_at.pop((user.id, it.id), None)
-        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:
         if st is not None and st.status == "new":
@@ -372,7 +402,7 @@ def item_progress(
             st.position_seconds = 0
             st.progress_updated_at = now
         db.commit()
-        return {"position_seconds": 0}
+        return {"ok": True, "position_seconds": 0}
 
     if st is None:
         st = PlexState(user_id=user.id, item_id=it.id)
@@ -397,7 +427,7 @@ def item_progress(
             duration * 1000,
             intent=now,
         )
-    return {"position_seconds": position}
+    return {"ok": True, "position_seconds": position}
 
 
 class ItemStateIn(BaseModel):
@@ -418,7 +448,7 @@ def item_state(
     it = item_or_404(db, rating_key)
     status = body.status
     if status not in ("new", "watched", "hidden"):
-        raise HTTPException(status_code=400, detail="Invalid status")
+        raise refused(400, "invalid_status")
     st = (
         db.execute(
             select(PlexState).where(PlexState.user_id == user.id, PlexState.item_id == it.id)
@@ -443,7 +473,7 @@ def item_state(
             db.commit()
         if mirrored_on_plex:
             _push_watch(background, db, user.id, it.id, rating_key, "unwatched")
-        return {"status": "new"}
+        return {"ok": True, "status": "new"}
     if st is None:
         st = PlexState(user_id=user.id, item_id=it.id)
         db.add(st)
@@ -455,7 +485,7 @@ def item_state(
     db.commit()
     if status == "watched" and prev_status != "watched":
         _push_watch(background, db, user.id, it.id, rating_key, "watched")
-    return {"status": status}
+    return {"ok": True, "status": status}
 
 
 def _bulk_state(
@@ -497,7 +527,9 @@ def _bulk_state(
                 db.delete(st)
                 if prev != "new":
                     to_push.append((e.id, e.rating_key, "unwatched"))
-    db.commit()
+    # Flush, not commit: the handler commits, and it does so before the response — which is when
+    # the background push below runs, so the push always reads the committed marks.
+    db.flush()
     if pushable and to_push:
         # One coalesced background task for the whole batch (reuses a single session + Plex client),
         # not one task per episode — a 200-ep show mark is 1 task, not 200.
@@ -520,7 +552,7 @@ def show_state(
     """Mark a whole show watched/unwatched (all its episodes) for the current user + push to Plex."""
     sh = by_rating_key(db, PlexShow, rating_key)
     if sh is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex show")
+        raise not_found("show")
     watched = body.watched
     eps = (
         db.execute(select(PlexItem).where(PlexItem.show_id == sh.id, PlexItem.kind == "episode"))
@@ -528,7 +560,8 @@ def show_state(
         .all()
     )
     changed = _bulk_state(background, db, user.id, eps, watched)
-    return {"changed": changed, "watched": watched}
+    db.commit()
+    return {"ok": True, "changed": changed, "watched": watched}
 
 
 @router.post("/season/{rating_key}/state")
@@ -542,7 +575,7 @@ def season_state(
     """Mark a whole season watched/unwatched (all its episodes) for the current user + push to Plex."""
     se = by_rating_key(db, PlexSeason, rating_key)
     if se is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex season")
+        raise not_found("season")
     watched = body.watched
     eps = (
         db.execute(select(PlexItem).where(PlexItem.season_id == se.id, PlexItem.kind == "episode"))
@@ -550,7 +583,8 @@ def season_state(
         .all()
     )
     changed = _bulk_state(background, db, user.id, eps, watched)
-    return {"changed": changed, "watched": watched}
+    db.commit()
+    return {"ok": True, "changed": changed, "watched": watched}
 
 
 @router.post("/stream/{rating_key}/session")
@@ -575,21 +609,23 @@ def stream_session(
     # the client can switch audio without a restart — even for otherwise direct-playable files.
     if it.playable == "direct" and audio is None and not aoff and not multi:
         return {
+            "ok": True,
             "mode": "direct",
             "url": f"/api/plex/stream/{it.rating_key}/file",
             "start_s": 0.0,
         }
     if plex_paths.local_media_path(db, it.file_path) is None:
-        raise HTTPException(status_code=404, detail="Media file not found on disk")
-    s = plex_stream.start_session(db, it, start, audio, aoff, multi, transcode=transcode)
+        raise refused(404, "media_missing")
+    s = plex_stream.start_session(db, it, user.id, start, audio, aoff, multi, transcode=transcode)
     if s is None:
-        raise HTTPException(status_code=404, detail="Media file not found on disk")
+        raise refused(404, "media_missing")
     # Report the REAL media start (the keyframe ffmpeg landed on, which hls.js zero-bases to), not the
     # requested offset — the client's absolute clock and the subtitle cue-shift both key off this.
     # `transcode`/`hw`/`tonemap` let the player show an honest cold-start ("Preparing stream…") and
     # surface the active mode + encoder in the stats overlay (`tonemap` = the HW HDR→SDR path); both
     # segment streams are otherwise identical.
     return {
+        "ok": True,
         "mode": "hls",
         "start_s": s.media_start_s,
         # The session id is part of the path (not a query param) so the playlist's RELATIVE segment
@@ -614,7 +650,7 @@ def stream_file(
     it = item_or_404(db, rating_key)
     src = plex_paths.local_media_path(db, it.file_path)
     if src is None:
-        raise HTTPException(status_code=404, detail="Media file not found on disk")
+        raise refused(404, "media_missing")
     if download:
         # A clean, safe download name from the title + the real file extension.
         ext = src.suffix or (f".{it.container}" if it.container else "")
@@ -651,9 +687,9 @@ def stream_hls_file(
     references its segments/subtitles by relative name, all resolving back here.
 
     The session id in the path is what makes "back here" mean the same session. Sessions are keyed by
-    rating_key alone and a seek-restart or a second viewer of the same item replaces the registered
-    one, while the DIRECTORY is per (key, offset, tag) — so resolving by rating_key handed the old
-    viewer the new session's `seg_12.ts`, produced from a different offset under `-copyts`: wrong
+    (viewer, rating_key) and a seek-restart replaces the viewer's registered one, while the DIRECTORY
+    is per (key, viewer, offset, tag) — so resolving by the key alone handed the old player the new
+    session's `seg_12.ts`, produced from a different offset under `-copyts`: wrong
     bytes with a 200, which the player has no way to notice (deep-review round 5). A request for a
     session that is no longer the registered one is a 404, and the player reclaims at the playhead.
 
@@ -668,10 +704,10 @@ def stream_hls_file(
         or "\\" in filename
         or ".." in filename
     ):
-        raise HTTPException(status_code=404, detail="Not found")
-    s = plex_stream.current_session(str(rating_key))
+        raise not_found("file")
+    s = plex_stream.current_session(user.id, str(rating_key))
     if s is None or s.id != session_id:
-        raise HTTPException(status_code=404, detail="No active playback session")
+        raise refused(404, "session_gone")
     path = s.dir / filename
     # Only a name THIS session can actually produce is worth waiting for: its own playlists, and a
     # segment of one of its own renditions whose predecessor is already on disk (ffmpeg writes them
@@ -681,14 +717,14 @@ def stream_hls_file(
     # past the produced region — or a deliberate flood of hopeless names — from parking threadpool
     # workers and their DB connections (see `artifact_may_arrive`).
     if not plex_stream.artifact_may_arrive(s, filename):
-        raise HTTPException(status_code=404, detail="Not available yet")
+        raise refused(404, "not_ready")
     timeout = 30 if ext == ".m3u8" else 20
     # `proc` so a session whose ffmpeg has already exited answers at once instead of polling out the
     # whole timeout: this is a SYNC route on the ~40-slot threadpool, holding a pooled DB connection
     # with it, so every such wait is a worker (and a connection) parked for 20 s — an ordinary seek
     # past the produced region was enough to do it (round 5).
     if not plex_stream.wait_for(path, timeout, proc=s.proc):
-        raise HTTPException(status_code=404, detail="Not available yet")
+        raise refused(404, "not_ready")
     try:
         content = path.read_bytes()
     except OSError:
@@ -699,7 +735,7 @@ def stream_hls_file(
         # restarting at the playhead. Ordinary trigger: `loadSession` awaits the new session — which
         # kills and rmtrees the old one — before destroying the old hls instance, so the outgoing
         # instance's in-flight segment request races the rmtree on every seek-restart.
-        raise HTTPException(status_code=404, detail="No active playback session") from None
+        raise refused(404, "session_gone") from None
     return Response(
         content=content,
         media_type=_HLS_CT[ext],

backend/app/routes/plex/playlists.py

@@ -2,7 +2,7 @@
 
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import delete, func, select, update
 from sqlalchemy.orm import Session
@@ -19,15 +19,12 @@ from app.models import (
 )
 from app.plex.cards import leaf_card
 from app.plex.lookups import by_rating_key
-from app.routes._common import owned_or_404
+from app.routes._common import owned_or_404, not_found
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
 
-def _own_playlist_or_404(db: Session, pid: int, user: User) -> PlexPlaylist:
-    return owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
-
-
 def _playlist_card(pl: PlexPlaylist, count: int, thumb_rk: str | None) -> dict:
     return {
         "id": pl.id,
@@ -120,7 +117,7 @@ def create_playlist(
 ) -> dict:
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     pl = PlexPlaylist(user_id=user.id, title=title)
     db.add(pl)
     db.flush()
@@ -140,7 +137,7 @@ def create_playlist(
 def playlist_detail(
     pid: int, user: User = Depends(current_user), db: Session = Depends(get_db)
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     rows = db.execute(_playlist_item_query(pid)).all()
     items = [it for (_pi, it) in rows]
     states = {
@@ -183,10 +180,10 @@ def rename_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     pl.title = title
     db.commit()
     count = (
@@ -203,7 +200,7 @@ def rename_playlist(
 def delete_playlist(
     pid: int, user: User = Depends(current_user), db: Session = Depends(get_db)
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     db.delete(pl)
     db.commit()
     return {"deleted": pid}
@@ -220,10 +217,10 @@ def playlist_add_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     it = by_rating_key(db, PlexItem, body.item_rating_key)
     if it is None:
-        raise HTTPException(status_code=404, detail="Unknown item")
+        raise not_found("item")
     exists = (
         db.execute(
             select(PlexPlaylistItem).where(
@@ -252,7 +249,7 @@ def playlist_remove_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     it = by_rating_key(db, PlexItem, item_rating_key)
     if it is not None:
         db.execute(
@@ -297,7 +294,7 @@ def playlist_add_bulk(
 ) -> dict:
     """Append many items at once (a whole season/show). Already-present items are skipped; the input
     order is preserved for the newly-added ones. Returns how many were added + the new total."""
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     items = _items_by_rks(db, body.item_rating_keys)
     existing = set(
         db.execute(
@@ -328,7 +325,7 @@ def playlist_add_bulk(
         )
         or 0
     )
-    return {"added": added, "item_count": total}
+    return {"ok": True, "added": added, "item_count": total}
 
 
 @router.post("/playlists/{pid}/items/remove-bulk")
@@ -340,7 +337,7 @@ def playlist_remove_bulk(
 ) -> dict:
     """Remove many items at once (a whole season/show, or a multi-select). Returns how many were
     removed + the new total."""
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     ids = [it.id for it in _items_by_rks(db, body.item_rating_keys)]
     removed = 0
     if ids:
@@ -359,7 +356,7 @@ def playlist_remove_bulk(
         )
         or 0
     )
-    return {"removed": removed, "item_count": total}
+    return {"ok": True, "removed": removed, "item_count": total}
 
 
 @router.put("/playlists/{pid}/order")
@@ -370,7 +367,7 @@ def reorder_playlist(
     db: Session = Depends(get_db),
 ) -> dict:
     """Set the playlist order from an explicit list of item rating_keys (0-based positions)."""
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     order = body.item_rating_keys
     id_by_rk = {
         it.rating_key: it.id

backend/app/routes/public.py

@@ -6,7 +6,7 @@ the app or any account data. Password-protected links exchange the password once
 a short-lived signed grant that the media URL carries (a `<video src>` can't send a header).
 """
 
-from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi import APIRouter, Depends, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel
 from sqlalchemy import select
@@ -19,6 +19,8 @@ from app.downloads import storage
 from app.models import DownloadJob, DownloadLink, MediaAsset
 from app.ratelimit import RateLimiter, client_key
 from app.security import verify_password
+from app.refusal import refused
+from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/public", tags=["public"])
 
@@ -37,7 +39,7 @@ _unlock_failures = RateLimiter(max_events=50, window_seconds=300)
 def _link_or_404(db: Session, token: str) -> DownloadLink:
     link = db.execute(select(DownloadLink).where(DownloadLink.token == token)).scalar_one_or_none()
     if link is None or linksmod.is_expired(link):
-        raise HTTPException(status_code=404, detail="This link is no longer available.")
+        raise refused(404, "link_gone")
     return link
 
 
@@ -45,12 +47,12 @@ def _ready_target(db: Session, link: DownloadLink) -> tuple[DownloadJob, MediaAs
     job = db.get(DownloadJob, link.job_id)
     asset = db.get(MediaAsset, job.asset_id) if job and job.asset_id else None
     if job is None or asset is None or asset.status != "ready" or not asset.rel_path:
-        raise HTTPException(status_code=404, detail="This video is no longer available.")
+        raise refused(404, "video_gone")
     # Verify the file is actually on disk here (not just flagged ready), so the watch page never
     # loads a player for a missing file — meta and file agree.
     path = storage.safe_abs_path(settings.download_root, asset.rel_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="This video is no longer available.")
+        raise refused(404, "video_gone")
     return job, asset
 
 
@@ -100,22 +102,24 @@ def watch_unlock(
     link = _link_or_404(db, token)
     viewer = f"{token}|{client_key(request)}"
     if _unlock_failures.exhausted(token) or not _unlock_limit.allow(viewer):
-        raise HTTPException(status_code=429, detail="Too many attempts. Try again later.")
+        raise refused(429, "too_many_attempts")
     if not link.password_hash:
         # Not a password link — nothing to unlock; just hand back the plain meta.
         job, asset = _ready_target(db, link)
         return {
+            "ok": True,
             "needs_password": False,
             **linksmod.public_meta(link, job, asset, _file_url(token), _poster_url(token, asset)),
         }
     if not verify_password(body.password, link.password_hash):
         _unlock_failures.allow(token)
-        raise HTTPException(status_code=403, detail="Wrong password.")
+        raise refused(403, "wrong_share_password")
     job, asset = _ready_target(db, link)
     link.view_count += 1
     db.commit()
     grant = linksmod.make_grant(token, link.password_version)
     return {
+        "ok": True,
         "needs_password": False,
         **linksmod.public_meta(
             link, job, asset, _file_url(token, grant), _poster_url(token, asset, grant)
@@ -129,11 +133,11 @@ def watch_file(token: str, g: str | None = None, db: Session = Depends(get_db)):
     `allow_download` link serves it as an attachment. Password links require a valid grant."""
     link = _link_or_404(db, token)
     if link.password_hash and not linksmod.check_grant(token, g, link.password_version):
-        raise HTTPException(status_code=403, detail="This link needs a password.")
+        raise refused(403, "share_password_required")
     asset = _ready_asset(db, link)
     path = storage.safe_abs_path(settings.download_root, asset.rel_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="This video is no longer available.")
+        raise refused(404, "video_gone")
 
     filename = storage.download_filename(asset.title or "video", asset.container, path)
     # The served Content-Type comes from the asset's ffprobe-verified media_kind + a container
@@ -163,11 +167,11 @@ def watch_poster(token: str, g: str | None = None, db: Session = Depends(get_db)
     and the link-preview image). Password links require a valid grant, like the file."""
     link = _link_or_404(db, token)
     if link.password_hash and not linksmod.check_grant(token, g, link.password_version):
-        raise HTTPException(status_code=403, detail="This link needs a password.")
+        raise refused(403, "share_password_required")
     job, asset = _ready_target(db, link)
     if not asset.poster_path:
-        raise HTTPException(status_code=404, detail="No poster.")
+        raise not_found("poster")
     path = storage.safe_abs_path(settings.download_root, asset.poster_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="No poster.")
+        raise not_found("poster")
     return FileResponse(path, media_type="image/jpeg")

backend/app/routes/saved_views.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import func, select, update
 from sqlalchemy.exc import IntegrityError
@@ -8,6 +8,7 @@ from app.auth import require_human
 from app.db import get_db
 from app.models import SavedView, User
 from app.routes._common import owned_or_404
+from app.refusal import refused
 
 # Saved "smart views": per-user named snapshots of a module's filters (feed or plex, keyed by
 # `source`). Gated behind require_human so the shared demo account can't pollute a communal list
@@ -66,7 +67,7 @@ def create_view(
 ) -> dict:
     name = body.name.strip()
     if not name:
-        raise HTTPException(status_code=400, detail="name is required")
+        raise refused(400, "name_required")
     source = _norm_source(body.source)
     # Position is per (user, source), so each module's views number 0..N independently.
     maxpos = db.execute(
@@ -86,14 +87,10 @@ def create_view(
         db.commit()
     except IntegrityError:
         db.rollback()
-        raise HTTPException(status_code=409, detail=f"You already have a view named “{name}”.")
+        raise refused(409, "view_name_taken", name=name)
     return _serialize(view)
 
 
-def _own_view(db: Session, user: User, view_id: int) -> SavedView:
-    return owned_or_404(db, SavedView, view_id, user, what="view")
-
-
 class UpdateViewIn(BaseModel):
     # PATCH: presence decides what's touched (read via model_fields_set). filters, when sent,
     # must be a real object — an explicit null is rejected (a view can't have null filters).
@@ -109,16 +106,16 @@ def update_view(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    view = _own_view(db, user, view_id)
+    view = owned_or_404(db, SavedView, view_id, user, what="view")
     sent = body.model_fields_set
     if "name" in sent:
         name = (body.name or "").strip()
         if not name:
-            raise HTTPException(status_code=400, detail="name cannot be empty")
+            raise refused(400, "name_required")
         view.name = name[:80]
     if "filters" in sent:
         if body.filters is None:
-            raise HTTPException(status_code=400, detail="filters must be an object")
+            raise refused(400, "filters_not_object")
         view.filters = body.filters
     if "is_default" in sent:
         make_default = bool(body.is_default)
@@ -138,7 +135,7 @@ def update_view(
         db.commit()
     except IntegrityError:
         db.rollback()
-        raise HTTPException(status_code=409, detail=f"You already have a view named “{view.name}”.")
+        raise refused(409, "view_name_taken", name=view.name)
     return _serialize(view)
 
 
@@ -148,7 +145,7 @@ def delete_view(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    view = _own_view(db, user, view_id)
+    view = owned_or_404(db, SavedView, view_id, user, what="view")
     db.delete(view)
     db.commit()
     return {"deleted": view_id}

backend/app/routes/scheduler.py

@@ -2,7 +2,7 @@
 per-job run activity (from the in-process scheduler), the work still queued (DB-derived),
 and the shared quota picture."""
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.orm import Session
@@ -25,6 +25,8 @@ from app.scheduler import (
 from app.sync.explore import followed_channel
 from app.sync.runner import estimate_deep_backfill
 from app.routes._common import not_found
+from app.refusal import refused
+from app.refusal import setting_refused
 
 router = APIRouter(prefix="/api/admin/scheduler", tags=["admin"])
 
@@ -46,10 +48,7 @@ def set_job_interval(
         raise not_found("job")
     minutes = body.interval_minutes
     if not (MIN_INTERVAL <= minutes <= MAX_INTERVAL):
-        raise HTTPException(
-            status_code=400,
-            detail=f"interval must be between {MIN_INTERVAL} and {MAX_INTERVAL} minutes",
-        )
+        raise refused(400, "invalid_interval", min=MIN_INTERVAL, max=MAX_INTERVAL)
     applied = apply_interval(db, job_id, minutes)
     audit.record(
         db,
@@ -61,7 +60,7 @@ def set_job_interval(
         after={"interval_minutes": applied},
     )
     db.commit()
-    return {"id": job_id, "interval_minutes": applied}
+    return {"ok": True, "id": job_id, "interval_minutes": applied}
 
 
 @router.post("/jobs/{job_id}/run")
@@ -77,14 +76,14 @@ def run_job_now(
     except KeyError:
         raise not_found("job")
     if result == "already_running":
-        raise HTTPException(status_code=409, detail="Job is already running")
-    return {"id": job_id, "started": True}
+        raise refused(409, "job_running")
+    return {"ok": True, "id": job_id, "started": True}
 
 
 @router.post("/run-all")
 def run_all_now(user: User = Depends(admin_user)) -> dict:
     """Trigger every job that isn't already running. Returns the ids actually started."""
-    return {"started": trigger_all(actor_id=user.id)}
+    return {"ok": True, "started": trigger_all(actor_id=user.id)}
 
 
 class MaintenanceSettingsIn(BaseModel):
@@ -102,8 +101,8 @@ def set_maintenance_settings(
     # set_value validates against the spec's min/max (one source of bounds), mirroring the config PATCH.
     try:
         sysconfig.set_value(db, "maintenance_revalidate_batch", body.revalidate_batch)
-    except (TypeError, ValueError) as exc:
-        raise HTTPException(status_code=400, detail=str(exc) or "Invalid value")
+    except sysconfig.InvalidSetting as exc:
+        raise setting_refused(exc) from None
     new = sysconfig.get_int(db, "maintenance_revalidate_batch")
     audit.record(
         db,
@@ -113,7 +112,7 @@ def set_maintenance_settings(
         after={"revalidate_batch": new},
     )
     db.commit()
-    return {"revalidate_batch": new}
+    return {"ok": True, "revalidate_batch": new}
 
 
 @router.get("")

backend/app/routes/search.py

@@ -13,17 +13,16 @@ this search-discovered "noise" by default. Shorts and currently-live/upcoming vi
 ingested this way (Shorts are confirmed by the youtube.com/shorts probe; live/upcoming are
 dropped from the search response up front)."""
 
-import logging
 from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import and_, delete, func, or_, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session, aliased
 
-from app import quota, sysconfig
+from app import logs, quota, sysconfig
 from app.auth import require_human
 from app.db import get_db
 from app.models import (
@@ -39,14 +38,16 @@ from app.models import (
     VideoState,
 )
 from app.feedquery import feed_columns, serialize
+from app.utils import like_escape
 from app.sync.subscriptions import apply_channel_details
 from app.sync.videos import insert_stubs, apply_video_details, parse_dt
 from app.youtube import search_scrape
 from app.youtube.client import YouTubeClient, YouTubeError
 from app.youtube.shorts import make_client, probe_is_short
+from app.refusal import refused
+from app.routes._common import youtube_refusal
 
-log = logging.getLogger("siftlode.search")
-
+log = logs.get_logger(__name__)
 router = APIRouter(prefix="/api/search", tags=["search"])
 
 # search.list costs this many quota units per page.
@@ -132,6 +133,13 @@ def _ingest_candidates(
             apply_channel_details(db, details)
             db.commit()
         except YouTubeError:
+            # The stubs remain and the details can be backfilled later — but until they are, those
+            # channels sit in the results with no thumbnail and no subscriber count, looking like
+            # channels that have neither.
+            log.warning(
+                "the channels found by a search could not be enriched",
+                extra=logs.event("search.channel_enrich_failed", channels=len(new_channel_ids)),
+            )
             db.rollback()  # details can be backfilled later; the stubs remain
 
     # 2) Video stubs, flagged via_search. Existing rows keep their flags (ON CONFLICT DO
@@ -161,6 +169,12 @@ def _ingest_candidates(
         with quota.attribute(user.id, quota.QuotaAction.VIDEOS_ENRICH):
             detail_by_id = {it["id"]: it for it in yt.get_videos(ids)}
     except YouTubeError:
+        # Every candidate then stays unenriched, and an unenriched video cannot be judged live or
+        # Short — so it is dropped. A working search returns nothing and reads as "no results".
+        log.warning(
+            "the videos found by a search could not be enriched",
+            extra=logs.event("search.video_enrich_failed", candidates=len(ids)),
+        )
         detail_by_id = {}
     enriched_at = datetime.now(
         timezone.utc
@@ -213,6 +227,25 @@ def _new_first(db: Session, user: User, ids: list[str]) -> list[str]:
     return [i for i in ids if i not in have] + [i for i in ids if i in have]
 
 
+def _fold_term(db: Session, video_ids: list[str], term: str) -> None:
+    """Append `term` to each video's space-joined `search_terms`, unless it is already one of them.
+
+    "Already one of them" is a whole-term match, as a literal: a substring test skipped `cat` on a
+    video already found for `category`, and an unescaped one read the `_` in `my_channel` as a
+    wildcard — either way the term was never folded in, and local search lost that relevance."""
+    padded = func.concat(" ", func.coalesce(Video.search_terms, ""), " ")
+    db.execute(
+        update(Video)
+        .where(Video.id.in_(video_ids))
+        .where(padded.notilike(f"% {like_escape(term)} %"))
+        .values(
+            search_terms=func.trim(
+                func.coalesce(Video.search_terms, "").op("||")(" ").op("||")(term)
+            )
+        )
+    )
+
+
 @router.get("/youtube")
 def search_youtube(
     q: str | None = None,
@@ -227,7 +260,7 @@ def search_youtube(
     page, so it returns a single page (≤50) regardless. `cursor` lets the caller fetch further."""
     term = (q or "").strip()
     if not term:
-        raise HTTPException(status_code=400, detail="A search term is required.")
+        raise refused(400, "search_term_required")
     limit = max(1, min(limit, 100))
 
     # Source: "scrape" (InnerTube, no API quota) or "api" (search.list, 100 units/page).
@@ -238,16 +271,20 @@ def search_youtube(
     daily_limit = sysconfig.get_int(db, "search_daily_limit_per_user")
     used = quota.actions_today(db, user.id, quota.QuotaAction.VIDEOS_SEARCH)
     if used >= daily_limit:
-        raise HTTPException(
-            status_code=429,
-            detail=f"You've reached today's YouTube search limit ({daily_limit}). Try again tomorrow.",
+        # The 429 is in the request line either way; which of the two caps produced it is not, and
+        # they are answered by different things — this one by tomorrow, the other by the admin.
+        log.info(
+            "a live search was refused: the per-user daily cap is spent",
+            extra=logs.event("search.refused", reason="daily_cap", limit=daily_limit),
         )
+        raise refused(429, "search_daily_limit", limit=daily_limit)
     # The 100-unit budget pre-check only applies to the API source.
     if source == "api" and not quota.can_spend(db, SEARCH_COST):
-        raise HTTPException(
-            status_code=429,
-            detail="The shared YouTube quota for today is used up. Try again tomorrow.",
+        log.info(
+            "a live search was refused: the shared YouTube budget is spent",
+            extra=logs.event("search.refused", reason="shared_quota", cost=SEARCH_COST),
         )
+        raise refused(429, "quota_spent")
 
     # Channels this user has blocked are dropped before ingestion — never shown, never stored.
     blocked = set(
@@ -272,9 +309,14 @@ def search_youtube(
                 # dropout (auto-retry + "connection lost" banner — lib/api/core RETRIABLE_GATEWAY),
                 # which hides the real message and burns a second quota-costed search. Upstream failure
                 # on a JSON endpoint = 422 + message; reserve 5xx for the raw byte-proxies. (B-core-1)
-                raise HTTPException(
-                    status_code=422, detail=f"YouTube search failed: {exc}"
-                ) from exc
+                # A Data API failure is logged where it happened; the scraper's is not, and its text
+                # no longer rides the answer — so it is said here.
+                if isinstance(exc, search_scrape.ScrapeError):
+                    log.warning(
+                        "the YouTube search scrape failed",
+                        extra=logs.event("search.scrape_failed", error=str(exc)),
+                    )
+                raise youtube_refusal(exc) from exc
 
             # Drop currently-live/upcoming, channel-less, and blocked-channel results.
             candidates = [
@@ -291,12 +333,32 @@ def search_youtube(
                 collected.extend(_ingest_candidates(db, yt, user, candidates))
             except Exception as exc:  # noqa: BLE001 — any ingest failure, not just YouTubeError
                 db.rollback()
-                log.exception("live search ingest failed for %r", term)
+                # The term is NOT in this line. A search string is exactly what the privacy
+                # policy keeps out of the log unless the user turned Teljes/TRACE on for
+                # themselves, and `redact_text` does not cover it — it scrubs addresses and
+                # credential params, not what someone typed into the search box. What the
+                # ERROR line carries instead is the shape of the failure, which is what tells
+                # an ingest bug from an upstream one; the term follows at TRACE, and only
+                # under this user's own consent — not whenever the process runs at TRACE.
+                log.exception(
+                    "live search ingest failed",
+                    extra=logs.event(
+                        "search.live.ingest_failed",
+                        source=source,
+                        candidates=len(candidates),
+                        collected=len(collected),
+                    ),
+                )
+                if logs.consented_trace():
+                    log.log(
+                        logs.TRACE,
+                        "the term the ingest failed on",
+                        # log-pii-ok: only under this user's own Teljes consent
+                        extra=logs.event("search.live.term", term=term),
+                    )
                 if collected:
                     break  # keep what earlier pages already gathered
-                raise HTTPException(
-                    status_code=422, detail=f"YouTube search failed: {exc}"
-                ) from exc
+                raise youtube_refusal(exc) from exc
             next_cursor = page["next_page_token"]
             # The API source pages cost 100 units each — never auto-page; one page per request.
             if source == "api" or len(collected) >= limit or not next_cursor:
@@ -321,16 +383,7 @@ def search_youtube(
             .values([{"user_id": user.id, "video_id": vid} for vid in ordered])
             .on_conflict_do_nothing(index_elements=["user_id", "video_id"])
         )
-        db.execute(
-            update(Video)
-            .where(Video.id.in_(ordered))
-            .where(func.coalesce(Video.search_terms, "").notilike(f"%{term}%"))
-            .values(
-                search_terms=func.trim(
-                    func.coalesce(Video.search_terms, "").op("||")(" ").op("||")(term)
-                )
-            )
-        )
+        _fold_term(db, ordered, term)
         db.commit()
 
     ordered = _new_first(db, user, ordered)
@@ -358,7 +411,7 @@ def clear_search(
     find. Kept videos and organically-owned ones are left untouched."""
     ids = body.video_ids
     if not ids:
-        return {"removed": 0}
+        return {"ok": True, "removed": 0}
     db.execute(
         delete(SearchFind).where(SearchFind.user_id == user.id, SearchFind.video_id.in_(ids))
     )
@@ -378,4 +431,4 @@ def clear_search(
         )
     ).rowcount
     db.commit()
-    return {"removed": removed}
+    return {"ok": True, "removed": removed}

backend/app/routes/setup.py

@@ -8,7 +8,7 @@ X-Setup-Token header).
 
 from typing import Any
 
-from fastapi import APIRouter, Depends, Header, HTTPException
+from fastapi import APIRouter, Depends, Header
 from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.orm import Session
@@ -21,6 +21,8 @@ from app.auth import PASSWORD_MIN_LEN
 from app.db import get_db
 from app.models import User
 from app.security import hash_password
+from app.refusal import refused
+from app.refusal import setting_refused
 
 router = APIRouter(prefix="/api/setup", tags=["setup"])
 
@@ -31,9 +33,9 @@ def require_setup(
 ) -> Session:
     """Gate for setup steps. Returns the db session for the handler to reuse."""
     if state.is_configured(db):
-        raise HTTPException(status_code=409, detail="This instance is already set up.")
+        raise refused(409, "already_set_up")
     if not state.check_setup_token(db, x_setup_token):
-        raise HTTPException(status_code=403, detail="Invalid or missing setup token.")
+        raise refused(403, "setup_token")
     return db
 
 
@@ -66,11 +68,9 @@ def setup_admin(body: SetupAdminIn, db: Session = Depends(require_setup)) -> dic
     email = body.email.strip().lower()
     password = body.password
     if "@" not in email:
-        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+        raise refused(400, "invalid_email")
     if len(password) < PASSWORD_MIN_LEN:
-        raise HTTPException(
-            status_code=400, detail=f"Password must be at least {PASSWORD_MIN_LEN} characters."
-        )
+        raise refused(400, "weak_password", min=PASSWORD_MIN_LEN)
     # Resolve canonically, not by the literal string (DX-17). The wizard can be re-run, and E9.5's
     # whole point is that two spellings of one Gmail mailbox are one person — matching literally here
     # would let a second run under the other spelling create the DUPLICATE admin row the epic exists
@@ -97,16 +97,16 @@ def setup_config(settings_map: dict[str, Any], db: Session = Depends(require_set
     saved: list[str] = []
     for key, value in settings_map.items():
         if sysconfig.spec(key) is None:
-            raise HTTPException(status_code=400, detail=f"Unknown setting: {key}")
+            raise refused(400, "unknown_setting", key=key)
         if value is None or value == "":
             continue
         try:
             sysconfig.set_value(db, key, value)
-        except (ValueError, RuntimeError) as exc:
-            raise HTTPException(status_code=400, detail=str(exc))
+        except sysconfig.InvalidSetting as exc:
+            raise setting_refused(exc) from None
         saved.append(key)
     db.commit()  # sysconfig.set_value only flushes now — persist the wizard's config in one commit
-    return {"saved": saved}
+    return {"ok": True, "saved": saved}
 
 
 class SetupTestEmailIn(BaseModel):
@@ -121,9 +121,9 @@ def setup_test_email(body: SetupTestEmailIn, db: Session = Depends(require_setup
     """Send a test email to confirm the SMTP settings the wizard just saved."""
     to = body.to.strip()
     if "@" not in to:
-        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+        raise refused(400, "invalid_email")
     if not email_mod.send_test(to, mailtext.normalize(body.lang)):
-        raise HTTPException(status_code=400, detail="Couldn't send — check the SMTP settings.")
+        raise refused(400, "smtp_failed")
     return {"ok": True}
 
 
@@ -133,6 +133,6 @@ def setup_finish(db: Session = Depends(require_setup)) -> dict:
     invalidates the setup token and disables the wizard)."""
     has_admin = db.execute(select(User).where(User.role == "admin")).first() is not None
     if not has_admin:
-        raise HTTPException(status_code=400, detail="Create the admin account first.")
+        raise refused(400, "admin_first")
     state.mark_configured(db)
     return {"ok": True}

backend/app/routes/sync.py

@@ -7,10 +7,13 @@ from app.audit import AuditAction
 from app.auth import admin_user, current_user, has_read_scope, require_human
 from app.db import get_db
 from app.models import Channel, Subscription, User, Video
+from app.routes._common import youtube_refusal
 from app.ratelimit import RateLimiter
 from app.sync.runner import estimate_deep_backfill
 from app.sync.subscriptions import import_subscriptions
 from app.scheduler import running_job_ids
+from app.youtube.client import YouTubeError
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/sync", tags=["sync"])
 
@@ -26,17 +29,20 @@ _sync_limiter = RateLimiter(max_events=3, window_seconds=600)
 def sync_subscriptions(user: User = Depends(require_human), db: Session = Depends(get_db)) -> dict:
     if not has_read_scope(user):
         # No YouTube read grant yet — the onboarding wizard hasn't been completed.
-        raise HTTPException(
-            status_code=403,
-            detail="Connect your YouTube account (read access) to import subscriptions.",
-        )
+        raise refused(403, "youtube_read_scope")
     if not _sync_limiter.allow(str(user.id)):
         raise HTTPException(status_code=429, detail={"code": "sync_cooldown"})
-    with quota.measured(db, user.id, quota.QuotaAction.SUBSCRIPTIONS_PULL) as m:
-        result = import_subscriptions(db, user)
+    try:
+        with quota.measured(db, user.id, quota.QuotaAction.SUBSCRIPTIONS_PULL) as m:
+            result = import_subscriptions(db, user)
+    except YouTubeError as exc:
+        # The onboarding wizard's first call: an unguarded failure here was a raw 500 and the
+        # blocking "Server error" dialog, with nothing the user could act on (E9 F1).
+        db.rollback()
+        raise youtube_refusal(exc)
     result["quota_used_estimate"] = m.used
     result["quota_remaining_today"] = m.remaining
-    return result
+    return {"ok": True, **result}
 
 
 @router.get("/status")
@@ -137,7 +143,7 @@ def deep_all(
         update(Subscription).where(Subscription.user_id == user.id).values(deep_requested=on)
     )
     db.commit()
-    return {"updated": result.rowcount, "deep_requested": on}
+    return {"ok": True, "updated": result.rowcount, "deep_requested": on}
 
 
 @router.post("/pause")
@@ -145,7 +151,7 @@ def pause_sync(admin: User = Depends(admin_user), db: Session = Depends(get_db))
     state.set_sync_paused(db, True)
     audit.record(db, admin.id, AuditAction.SYNC_PAUSE, summary="Background sync paused")
     db.commit()
-    return {"paused": True}
+    return {"ok": True, "paused": True}
 
 
 @router.post("/resume")
@@ -153,4 +159,4 @@ def resume_sync(admin: User = Depends(admin_user), db: Session = Depends(get_db)
     state.set_sync_paused(db, False)
     audit.record(db, admin.id, AuditAction.SYNC_RESUME, summary="Background sync resumed")
     db.commit()
-    return {"paused": False}
+    return {"ok": True, "paused": False}

backend/app/routes/tags.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import func, or_, select
 from sqlalchemy.exc import IntegrityError
@@ -9,6 +9,7 @@ from app.db import get_db
 from app.models import ChannelTag, Tag, User
 from app.routes._common import owned_or_404
 from app.sync.tagsuggest import compute_tag_suggestions
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/tags", tags=["tags"])
 
@@ -60,7 +61,7 @@ def create_tag(
 ) -> dict:
     name = body.name.strip()
     if not name:
-        raise HTTPException(status_code=400, detail="name is required")
+        raise refused(400, "name_required")
     # An unknown category silently falls back to "other" (unchanged behaviour) rather than 422.
     category = body.category if body.category in ("language", "topic", "other") else "other"
     tag = Tag(
@@ -74,13 +75,14 @@ def create_tag(
         db.commit()
     except IntegrityError:
         db.rollback()
-        raise HTTPException(status_code=409, detail=f"You already have a tag named “{name}”.")
-    return {"id": tag.id, "name": tag.name, "color": tag.color, "category": tag.category}
-
-
-def _own_tag(db: Session, user: User, tag_id: int) -> Tag:
-    # System tags (user_id NULL) are not user-editable → owned_or_404 404s them too.
-    return owned_or_404(db, Tag, tag_id, user, what="tag")
+        raise refused(409, "tag_name_taken", name=name)
+    return {
+        "ok": True,
+        "id": tag.id,
+        "name": tag.name,
+        "color": tag.color,
+        "category": tag.category,
+    }
 
 
 class TagUpdateIn(BaseModel):
@@ -97,12 +99,13 @@ def update_tag(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    tag = _own_tag(db, user, tag_id)
+    # System tags (user_id NULL) are not user-editable: owned_or_404 404s them too.
+    tag = owned_or_404(db, Tag, tag_id, user, what="tag")
     sent = body.model_fields_set
     if "name" in sent:
         name = (body.name or "").strip()
         if not name:
-            raise HTTPException(status_code=400, detail="name cannot be empty")
+            raise refused(400, "name_required")
         tag.name = name
     if "color" in sent:
         tag.color = body.color
@@ -110,8 +113,14 @@ def update_tag(
         db.commit()
     except IntegrityError:
         db.rollback()
-        raise HTTPException(status_code=409, detail=f"You already have a tag named “{tag.name}”.")
-    return {"id": tag.id, "name": tag.name, "color": tag.color, "category": tag.category}
+        raise refused(409, "tag_name_taken", name=tag.name)
+    return {
+        "ok": True,
+        "id": tag.id,
+        "name": tag.name,
+        "color": tag.color,
+        "category": tag.category,
+    }
 
 
 @router.delete("/{tag_id}")
@@ -120,7 +129,8 @@ def delete_tag(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    tag = _own_tag(db, user, tag_id)
+    # System tags (user_id NULL) are not user-editable: owned_or_404 404s them too.
+    tag = owned_or_404(db, Tag, tag_id, user, what="tag")
     db.delete(tag)  # ChannelTag rows cascade on tag delete.
     db.commit()
     return {"deleted": tag_id}

backend/app/scheduler.py

@@ -2,7 +2,6 @@
 recent-first / deep backfill. Runs inside the API process (single worker)."""
 
 import contextvars
-import logging
 import threading
 from datetime import datetime, timezone
 from typing import Callable
@@ -10,7 +9,7 @@ from typing import Callable
 from apscheduler.schedulers.background import BackgroundScheduler
 from sqlalchemy import select
 
-from app import audit, logsink, progress, quota
+from app import audit, logs, logsink, progress, quota
 from app.audit import AuditAction
 from app.config import settings
 from app.db import SessionLocal
@@ -35,8 +34,7 @@ from app.sync.runner import (
     run_subscription_resync,
 )
 
-logger = logging.getLogger("siftlode.scheduler")
-
+log = logs.get_logger(__name__)
 _scheduler: BackgroundScheduler | None = None
 
 # Per-job run activity, kept in-memory for the admin Scheduler dashboard to read (the
@@ -104,7 +102,7 @@ def apply_interval(db, job_id: str, minutes: int) -> int:
     db.commit()
     if _scheduler is not None and _scheduler.get_job(job_id) is not None:
         _scheduler.reschedule_job(job_id, trigger="interval", minutes=minutes)
-        logger.info("rescheduled job %s to every %s min", job_id, minutes)
+        log.info("rescheduled job %s to every %s min", job_id, minutes)
     return minutes
 
 
@@ -131,7 +129,7 @@ def _notify_done(db, actor_id: int, job_id: str, status: str, summary: str | Non
         )
     except Exception:
         db.rollback()
-        logger.exception("failed to write completion notification for job %s", job_id)
+        log.exception("failed to write completion notification for job %s", job_id)
 
 
 def _run_changed(result) -> bool:
@@ -167,7 +165,7 @@ def _audit_run(db, actor_id, job_id, status, summary, result) -> None:
         db.commit()
     except Exception:
         db.rollback()
-        logger.exception("failed to write audit row for job %s", job_id)
+        log.exception("failed to write audit row for job %s", job_id)
 
 
 def _job(name: str, fn) -> None:
@@ -175,7 +173,7 @@ def _job(name: str, fn) -> None:
     # HERE, atomically: whichever reaches this first wins, the other skips. This is the real
     # single-run guard — trigger_job's pre-check is only a fast best-effort answer for the UI.
     if not _claim_running(name):
-        logger.info("job %s already running — skipping this trigger", name)
+        log.info("job %s already running — skipping this trigger", name)
         return
     db = SessionLocal()
     actor_id = _manual_actor.get()  # set only for a manual "run now" trigger
@@ -188,7 +186,7 @@ def _job(name: str, fn) -> None:
 
     try:
         if is_sync_paused(db):
-            logger.info("job %s skipped (sync paused)", name)
+            log.info("job %s skipped (sync paused)", name)
             _record(
                 name,
                 status="skipped",
@@ -203,14 +201,14 @@ def _job(name: str, fn) -> None:
         with progress.bind(sink):
             result = fn(db)
         summary = _summarize(result)
-        logger.info("job %s -> %s", name, result)
+        log.info("job %s -> %s", name, result)
         _record(name, status="ok", last_finished=_now_iso(), last_result=summary, progress=None)
         if actor_id is not None:
             _notify_done(db, actor_id, name, "ok", summary)
         _audit_run(db, actor_id, name, "ok", summary, result)
     except Exception as exc:
         db.rollback()
-        logger.exception("job %s failed", name)
+        log.exception("job %s failed", name, extra=logs.event("scheduler.job.failed", job=name))
         err = str(exc) or exc.__class__.__name__
         _record(name, status="error", last_finished=_now_iso(), last_error=err, progress=None)
         if actor_id is not None:
@@ -493,7 +491,7 @@ def start_scheduler() -> None:
         scheduler.add_job(fn, "interval", minutes=iv[job_id], id=job_id)
     scheduler.start()
     _scheduler = scheduler
-    logger.info("scheduler started")
+    log.info("scheduler started")
 
 
 def shutdown_scheduler() -> None:

backend/app/security.py

@@ -1,10 +1,14 @@
 import hashlib
 
 from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
 from cryptography.fernet import Fernet
 
+from app import logs
 from app.config import settings
 
+log = logs.get_logger(__name__)
+
 # argon2id with the library defaults (sensible memory/time cost). One shared hasher instance.
 _ph = PasswordHasher()
 
@@ -24,8 +28,16 @@ def verify_password(password: str, hashed: str | None) -> bool:
         return False
     try:
         return _ph.verify(hashed, password)
-    except Exception:
-        # Any failure (mismatch, malformed hash) is a non-match — never raise to the caller.
+    except VerifyMismatchError:
+        return False  # silent-ok: a wrong password. The commonest path through this function.
+    except Exception as exc:  # noqa: BLE001 — never raise to the caller, whatever went wrong
+        # Everything else is a hash this process cannot USE — truncated in the column, written by
+        # a different argon2 build. It is answered as "wrong password", so the owner of that
+        # account is locked out by a bug and told they mistyped.
+        log.warning(
+            "a stored password hash could not be verified",
+            extra=logs.event("auth.password.hash_unusable", reason=type(exc).__name__),
+        )
         return False
 
 
@@ -60,5 +72,13 @@ def decrypt_optional(value: str | None) -> str | None:
         return None
     try:
         return _require_fernet().decrypt(value.encode()).decode()
-    except Exception:
+    except Exception as exc:  # noqa: BLE001 — callers fall back to a refresh, never to an error
+        # Info rather than warning because the docstring's legacy-plaintext case comes through
+        # here too and is harmless. What is NOT harmless looks identical: a rotated
+        # TOKEN_ENCRYPTION_KEY turns every stored token unreadable at once, and every account
+        # then reads as "not connected" with nothing saying the key is the reason.
+        log.info(
+            "a stored ciphertext could not be decrypted",
+            extra=logs.event("security.decrypt.failed", reason=type(exc).__name__),
+        )
         return None

backend/app/state.py

@@ -1,15 +1,14 @@
 """Global admin-controlled app state (e.g. pausing background sync, first-run setup)."""
 
-import logging
 import secrets
 
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.models import AppState
 from app.security import hash_token
 
-log = logging.getLogger("siftlode.state")
-
+log = logs.get_logger(__name__)
 # Once configuration completes in this process it never reverts, so cache it to skip the per-request
 # DB hit in the setup-mode gate (see main.setup_gate). Starts False; refreshed from the DB.
 _configured_cache = False

backend/app/sync/autotag.py

@@ -6,17 +6,16 @@ topicDetails categories and the channel's dominant video category. System tags a
 regenerated freely; user tags are never touched here.
 """
 
-import logging
 import re
 
 from sqlalchemy import and_, exists, func, select
 from sqlalchemy.orm import Session
 
-log = logging.getLogger("siftlode.autotag")
-
-from app import progress, sysconfig
+from app import logs, progress, sysconfig
 from app.models import Channel, ChannelTag, Tag, Video
 
+log = logs.get_logger(__name__)
+
 # --- language id (offline, deterministic, small) ---
 try:
     from py3langid.langid import MODEL_FILE, LanguageIdentifier
@@ -29,7 +28,13 @@ try:
     def _restrict(codes: list[str]) -> None:
         _identifier.set_languages(codes)
 
-except Exception:  # pragma: no cover - fallback to module-level API
+except Exception:  # noqa: BLE001 — pragma: no cover, fallback to the module-level API
+    # The fallback classifies without the normalisation the identifier applies, so language tags
+    # come out subtly different — and nothing else in the app would ever hint at which path ran.
+    log.info(
+        "the langid model could not be loaded; using the module-level classifier",
+        extra=logs.event("autotag.langid.fallback"),
+    )
     import py3langid as _langid
 
     def _classify(text: str):

backend/app/sync/explore.py

@@ -8,13 +8,12 @@ stay private to users who explored (or subscribe to) the channel — the feed qu
 otherwise the cleanup job hard-deletes the channel and its untouched ephemeral videos after a
 grace period (mirrors the maintenance job's grace-then-delete safety)."""
 
-import logging
 from datetime import timedelta
 
 from sqlalchemy import delete, or_, select
 from sqlalchemy.orm import Session
 
-from app import sysconfig
+from app import logs, sysconfig
 from app.models import (
     Channel,
     ExploredChannel,
@@ -28,7 +27,7 @@ from app.sync.videos import insert_stubs, stub_from_playlist_item, apply_video_d
 from app.utils import now_utc as _now
 from app.youtube.client import YouTubeClient
 
-log = logging.getLogger("siftlode.explore")
+log = logs.get_logger(__name__)
 
 
 def followed_channel():

backend/app/sync/maintenance.py

@@ -20,13 +20,12 @@ Quota: phase 1 costs ~(flagged / 50) units, phase 2 ~(batch / 50). Both respect
 backfill reserve as the other jobs so interactive syncs never starve.
 """
 
-import logging
 from datetime import timedelta
 
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app import progress, quota, sysconfig
+from app import logs, progress, quota, sysconfig
 from app.config import settings
 from app.models import Playlist, PlaylistItem, Video
 from app.notifications import create_notification
@@ -35,8 +34,7 @@ from app.sync.videos import apply_video_details, parse_dt
 from app.utils import now_utc as _now
 from app.youtube.client import YouTubeClient
 
-log = logging.getLogger("siftlode.maintenance")
-
+log = logs.get_logger(__name__)
 # Reasons recorded on Video.unavailable_reason. "removed" = absent from videos.list
 # (deleted or made private); "abandoned" = an upcoming premiere that never went live.
 GRACE_DAYS_BY_REASON = {

backend/app/sync/playlists.py

@@ -8,7 +8,6 @@ ingested (with a stub channel) so the mirror is faithful."""
 
 import hashlib
 import json
-import logging
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -17,15 +16,14 @@ from typing import TypeVar
 from sqlalchemy import delete, select
 from sqlalchemy.orm import Session
 
-from app import progress, quota
+from app import logs, progress, quota
 from app.auth import has_read_scope
 from app.models import Channel, Playlist, PlaylistItem, User, Video
 from app.sync.runner import token_users
 from app.sync.videos import apply_video_details, parse_dt
 from app.youtube.client import YouTubeClient, YouTubeError
 
-log = logging.getLogger("siftlode.sync")
-
+log = logs.get_logger(__name__)
 # Cost of a single YouTube write op (playlists/playlistItems insert/update/delete).
 WRITE_UNIT_COST = 50
 
@@ -59,7 +57,17 @@ def _load_baseline(pl: Playlist) -> tuple[list[str] | None, set[str]]:
         return None, set()
     try:
         val = json.loads(pl.synced_video_ids)
-    except (ValueError, TypeError):
+    except (ValueError, TypeError) as exc:
+        # No baseline means the three-way merge has no "what we last agreed on" to subtract, so
+        # it degrades to a union: nothing is lost, but a delete made on either side comes back.
+        log.warning(
+            "the sync baseline for a playlist could not be read; merging as a union",
+            extra=logs.event(
+                "sync.playlist.baseline_unreadable",
+                playlist_id=pl.id,
+                reason=type(exc).__name__,
+            ),
+        )
         return None, set()
     if isinstance(val, list):
         return [str(v) for v in val], set()
@@ -410,8 +418,11 @@ class _Breaker:
     write site can't accidentally implement two thirds of the protocol (forgetting to record a
     failure would silently disable the breaker for that operation)."""
 
-    def __init__(self, limit: int = _MAX_CONSECUTIVE_FAILURES) -> None:
+    def __init__(
+        self, limit: int = _MAX_CONSECUTIVE_FAILURES, playlist_id: int | None = None
+    ) -> None:
         self.limit = limit
+        self.playlist_id = playlist_id  # for the failure line only
         self.streak = 0
         self.tripped = False
 
@@ -432,7 +443,9 @@ class _Breaker:
                 self.limit,
             )
 
-    def run(self, op: Callable[[], T], on_fail: Callable[[], None]) -> T | _Failed:
+    def run(
+        self, op: Callable[[], T], on_fail: Callable[[], None], action: str = "write"
+    ) -> T | _Failed:
         """Attempt one YouTube write. Returns the op's result, or `FAILED` when the breaker is
         already tripped (op not called) or the op raised YouTubeError. `on_fail` records the item
         in the caller's failure list either way."""
@@ -441,7 +454,19 @@ class _Breaker:
             return FAILED
         try:
             out = op()
-        except YouTubeError:
+        except YouTubeError as exc:
+            # The client logged the call, but not which playlist it was for or what kind of write
+            # — and the caller's failure list only ever reaches the user as a count. Not the video:
+            # what is in someone's playlist is a row of their history, the same as a download.
+            log.debug(
+                "a playlist write to YouTube failed",
+                extra=logs.event(
+                    "sync.playlist.item_push_failed",
+                    playlist_id=self.playlist_id,
+                    action=action,
+                    reason=exc.reason,
+                ),
+            )
             on_fail()
             self.hit(False)
             return FAILED
@@ -460,7 +485,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
     local = _local_video_ids(db, pl)
     inserted = deleted = reordered = created = pulled = removed_local = 0
     failures: list[str] = []
-    breaker = _Breaker()
+    breaker = _Breaker(playlist_id=pl.id)
     with YouTubeClient(db, user) as yt:
         if not pl.yt_playlist_id:
             pl.yt_playlist_id = yt.create_playlist(pl.name)
@@ -471,6 +496,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
                 added = breaker.run(
                     lambda v=vid: yt.add_playlist_item(pl.yt_playlist_id, v),
                     lambda v=vid: failures.append(v),
+                    "add",
                 )
                 if not isinstance(added, _Failed):
                     inserted += 1
@@ -533,7 +559,17 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
         if snippet is not None and (snippet.get("title") or "") != pl.name:
             try:
                 yt.update_playlist_title(pl.yt_playlist_id, pl.name)
-            except YouTubeError:
+            except YouTubeError as exc:
+                # All the caller passes on is the word "title", which says the rename did not
+                # happen but not that YouTube refused it, or why.
+                log.debug(
+                    "a playlist rename did not reach YouTube",
+                    extra=logs.event(
+                        "sync.playlist.title_push_failed",
+                        playlist_id=pl.id,
+                        reason=exc.reason,
+                    ),
+                )
                 failures.append("title")
         # Propagate genuine local deletes.
         for vid in mp.remove_from_yt:
@@ -543,6 +579,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
             dropped = breaker.run(
                 lambda i=item_id: yt.delete_playlist_item(i),
                 lambda v=vid: failures.append(v),
+                "delete",
             )
             if not isinstance(dropped, _Failed):
                 deleted += 1
@@ -552,6 +589,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
             item_id = breaker.run(
                 lambda v=vid: yt.add_playlist_item(pl.yt_playlist_id, v),
                 lambda v=vid: failures.append(v),
+                "add",
             )
             if not isinstance(item_id, _Failed):
                 item_id_by_vid[vid] = item_id
@@ -571,6 +609,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
                     item_id_by_vid[w], pl.yt_playlist_id, w, pos
                 ),
                 lambda w=want: failures.append(w),
+                "move",
             )
             if isinstance(moved, _Failed):
                 continue
@@ -631,11 +670,19 @@ def sync_all_playlists(db: Session) -> dict:
         try:
             with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
                 total += sync_user_playlists(db, user).get("synced", 0)
-        except YouTubeError:
+        except YouTubeError as exc:
             db.rollback()
-            log.warning("Playlist sync failed for user %s", user.id)
+            log.warning(
+                "Playlist sync failed for user %s",
+                user.id,
+                extra=logs.event("sync.playlists.failed", user_id=user.id, reason=exc.reason),
+            )
         except Exception:
             db.rollback()
-            log.exception("Playlist sync crashed for user %s", user.id)
+            log.exception(
+                "Playlist sync crashed for user %s",
+                user.id,
+                extra=logs.event("sync.playlists.crashed", user_id=user.id),
+            )
         progress.report(i, len(users), "playlist_sync")
     return {"users": len(users), "playlists_synced": total}

backend/app/sync/runner.py

@@ -9,13 +9,14 @@ import logging
 import threading
 from collections import Counter
 from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timedelta, timezone
 
-from sqlalchemy import select
+from sqlalchemy import func, or_, select, update
 from sqlalchemy.orm import Session
 
 from app import logs, progress, quota, sysconfig
 
-log = logging.getLogger("siftlode.sync")
+log = logs.get_logger(__name__)
 from app.db import SessionLocal
 from app.models import Channel, OAuthToken, Subscription, User
 from app.sync.explore import followed_channel
@@ -25,11 +26,13 @@ from app.sync.videos import (
     backfill_channel_deep,
     backfill_channel_recent,
     enrich_pending,
+    insert_stubs,
     reconcile_full_history,
     refresh_live,
     run_shorts_classification,
+    stub_from_playlist_item,
 )
-from app.youtube.client import YouTubeClient
+from app.youtube.client import YouTubeClient, YouTubeError, is_quota_refusal
 from app.youtube.rss import RssError, fetch_channel_feed
 
 # RSS feeds are free and network-bound, so fetch many at once; DB writes stay single-threaded.
@@ -85,6 +88,9 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
     # of 2026-09-16 into 11k warnings in four hours; each channel's own line is DEBUG now.
     reasons: Counter[str] = Counter()
     examples: list[str] = []
+    # Channels whose FEED would not answer (not those whose rows failed to apply: the API would
+    # hand the same rows to the same broken write) — the feed fallback's candidates.
+    unread: list[str] = []
 
     def fail(reason: str, detail: str, *, unexpected: str | None = None) -> None:
         """Count a channel that did not get polled. `unexpected` is the message for a failure that
@@ -120,14 +126,19 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
             except RssError as exc:
                 log.debug("RSS poll skipped for channel %s: %s", channel.id, exc)
                 fail(exc.reason, f"{channel.id}: {exc}")
-            except Exception as exc:
+                unread.append(channel.id)
+            # silent-ok: `fail(unexpected=…)` is the report — it logs at ERROR with the
+            # traceback, once per reason per poll, which is the flood control this loop needs.
+            except Exception as exc:  # noqa: BLE001 — one channel must not stop the poll
                 fail(
                     "error", f"{channel.id}: {exc}", unexpected=f"RSS fetch failed for {channel.id}"
                 )
             else:
                 try:
                     new += apply_rss_feed(db, channel, entries)
-                except Exception as exc:
+                # silent-ok: `fail(unexpected=…)` below is the report — ERROR with the traceback,
+                # once per reason per poll.
+                except Exception as exc:  # noqa: BLE001 — one channel must not stop the poll
                     # A write failure (read-only DB, failover) leaves the channel just as un-polled
                     # as an unreachable feed — count it, or a wholly broken run reports "failed=0".
                     db.rollback()
@@ -139,17 +150,24 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
             # One place that advances the counter, whatever happened above.
             done += 1
             progress.report(done, total, "rss_poll")
+    fallback = run_feed_fallback(db, unread)
     if failed:
+        # The fallback's count rides on this line because this is the one the stored log keeps (an
+        # INFO line outside a request never reaches `log_events`): the console should show whether
+        # the uploads came in another way.
         log.warning(
-            "RSS poll: %d/%d channels could not be polled",
+            "RSS poll: %d/%d channels could not be polled; %d read through the API instead",
             failed,
             total,
+            fallback["read"],
             extra=logs.event(
                 "sync.rss.failed",
                 failed=failed,
                 total=total,
                 reasons=dict(reasons),
                 examples=examples,
+                fallback_read=fallback["read"],
+                fallback_new=fallback["new"],
             ),
         )
     if total and failed == total:
@@ -160,8 +178,115 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
         # subscriptions "all channels failed" is also what ONE dead feed id looks like, and a red
         # card the user can't act on is its own kind of dishonest. `channel: HTTP 404` says
         # "fix this subscription"; `Connection refused` says "the egress is down".
-        raise RuntimeError(f"RSS poll failed for all {total} channels — first: {first_error}")
-    return {"new": new, "failed": failed}
+        # The fallback's count rides along: a red card during an RSS outage should still say
+        # whether the uploads are arriving another way.
+        raise RuntimeError(
+            f"RSS poll failed for all {total} channels — first: {first_error}"
+            f" (read through the API instead: {fallback['read']})"
+        )
+    return {"new": new + fallback["new"], "failed": failed, "fallback": fallback["read"]}
+
+
+def run_feed_fallback(db: Session, channel_ids: list[str]) -> dict[str, int]:
+    """Read the newest uploads through the Data API for the channels among `channel_ids` whose feed
+    has not answered for `rss_fallback_hours` — and that were not read this way within as long.
+
+    YouTube's RSS goes dark per channel for hours at a time (2026-09-18/19: 393 of 396 feeds answered
+    404 for four hours, and a retry of the same channel gets the same 404), and nothing else reads a
+    followed channel's new uploads: recent backfill runs once per channel, ever. One page of the
+    uploads playlist is 1 unit, so a whole day of total outage costs 12 units per channel at the
+    default 2 hours; it yields to the backfill reserve like every other background read. The clock is
+    `last_rss_at` or `feed_fallback_at`, whichever is later, so a channel is read at most once per
+    window whether its feed came back in between or not. A read the API REFUSED stamps the clock
+    too: a terminated channel's uploads playlist answers 404 for good, and without the stamp it
+    would be charged again on every 20-minute poll instead of once per window. A failure that is not
+    about the channel (no connection, no token, the quota spent) stamps nothing and ends the round."""
+    hours = sysconfig.get_int(db, "rss_fallback_hours")
+    if hours <= 0 or not channel_ids:
+        return {"read": 0, "new": 0, "failed": 0}
+    now = datetime.now(timezone.utc)
+    last_read = func.greatest(Channel.last_rss_at, Channel.feed_fallback_at)
+    due = (
+        db.execute(
+            select(Channel)
+            .where(
+                Channel.id.in_(channel_ids),
+                Channel.uploads_playlist_id.is_not(None),
+                or_(last_read.is_(None), last_read < now - timedelta(hours=hours)),
+            )
+            .order_by(Channel.id)
+        )
+        .scalars()
+        .all()
+    )
+    user = get_service_user(db) if due else None
+    if user is None:
+        return {"read": 0, "new": 0, "failed": 0}
+    read = new = failed = 0
+    with (
+        quota.attribute(None, quota.QuotaAction.VIDEOS_FEED_FALLBACK),
+        YouTubeClient(db, user) as yt,
+    ):
+        for channel in due:
+            if quota.backfill_reserve_reached():
+                break
+            try:
+                data = yt.get_playlist_items(channel.uploads_playlist_id, None)
+            # silent-ok: counted, and the one summary line below names the count — the client
+            # already logged the call's own failure (`youtube.api.error`).
+            except YouTubeError as exc:
+                failed += 1
+                # Not an answer about THIS channel — no connection, no token, no quota: every
+                # further channel would fail the same way, and none of them has used its window.
+                if exc.path != "playlistItems" or is_quota_refusal(exc):
+                    break
+                _stamp_fallback_attempt(db, channel.id)
+                continue
+            rows = [
+                s
+                for s in (stub_from_playlist_item(it, channel.id) for it in data.get("items", []))
+                if s is not None
+            ]
+            try:
+                new += insert_stubs(db, rows)
+                channel.feed_fallback_at = datetime.now(timezone.utc)
+                db.add(channel)
+                db.commit()
+            except Exception:  # noqa: BLE001 — one channel must not stop the rest
+                db.rollback()
+                log.exception(
+                    "Feed fallback could not store channel %s",
+                    channel.id,
+                    extra=logs.event("sync.rss.fallback_failed"),
+                )
+                failed += 1
+                _stamp_fallback_attempt(db, channel.id)
+                continue
+            read += 1
+    log.info(
+        "Feed fallback: read %d of %d channels through the API, %d new videos",
+        read,
+        len(due),
+        new,
+        extra=logs.event("sync.rss.fallback", read=read, due=len(due), new=new, failed=failed),
+    )
+    return {"read": read, "new": new, "failed": failed}
+
+
+def _stamp_fallback_attempt(db: Session, channel_id: str) -> None:
+    """Start a channel's fallback window after a read that did not land, so it waits the window out
+    like a read that did. Its own commit: the failure already rolled the channel's work back."""
+    try:
+        db.execute(
+            update(Channel)
+            .where(Channel.id == channel_id)
+            .values(feed_fallback_at=datetime.now(timezone.utc))
+        )
+        db.commit()
+    # silent-ok: the failure that brought us here was already logged and counted; an unstamped
+    # channel is only read again at the next poll.
+    except Exception:  # noqa: BLE001
+        db.rollback()
 
 
 def run_enrich(db: Session, max_batches: int = 200, floor: int = 200) -> int:

backend/app/sync/subscriptions.py

@@ -1,21 +1,23 @@
 """Import the authenticated user's YouTube subscriptions and channel metadata."""
 
-import logging
 from datetime import datetime, timezone
 
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
+from app import logs
 from app.models import Channel, Subscription, User
 from app.utils import normalize_description
 from app.youtube.client import YouTubeClient, best_thumbnail
 
-log = logging.getLogger("siftlode.sync")
+log = logs.get_logger(__name__)
 
 
 def _to_int(value) -> int | None:
     try:
         return int(value) if value is not None else None
+    # silent-ok: an upstream count we cannot read is stored as no count, which the card renders as
+    # absent rather than as zero. Per-channel over a whole subscription list, so it must stay quiet.
     except (TypeError, ValueError):
         return None
 
@@ -25,6 +27,8 @@ def _parse_dt(value: str | None) -> datetime | None:
         return None
     try:
         return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    # silent-ok: as `_to_int` above — an unreadable upstream date becomes NULL, and every caller
+    # already treats a missing date as unknown.
     except ValueError:
         return None
 

backend/app/sync/videos.py

@@ -39,6 +39,8 @@ def parse_dt(value: str | None) -> datetime | None:
         return None
     try:
         return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    # silent-ok: a pure parser with no video to name — the only thing it could put in a line is
+    # the upstream string itself. None is stored, and absent is how the UI renders it.
     except ValueError:
         return None
 

backend/app/sysconfig.py

@@ -8,20 +8,22 @@ stored Fernet-encrypted at rest (requires TOKEN_ENCRYPTION_KEY; without it, secr
 stored in the DB and stay env-only).
 """
 
-import logging
 from dataclasses import dataclass
 
 from sqlalchemy.orm import Session
 
-from app import security
+from app import logs, security
 from app.config import Settings, canonical_choice, choices_of, settings
 from app.models import SystemConfig
 
-log = logging.getLogger("siftlode.config")
-
+log = logs.get_logger(__name__)
 # Config keys whose stored ciphertext failed to decrypt — tracked so the warning is logged once per
 # key, not once per request (bounded by the number of secret config keys).
 _decrypt_warned: set[str] = set()
+# The same for a stored value that no longer coerces (a choice list that shrank in a release): it
+# fails on EVERY read of a hot knob until someone saves it again. Keyed with the value, so saving a
+# different bad value is reported afresh (bounded by the keys times the values ever saved).
+_coerce_warned: set[tuple[str, str]] = set()
 
 
 @dataclass(frozen=True)
@@ -89,6 +91,7 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec(
         "backfill_recent_max_days", "int", "backfill", "backfill_recent_max_days", min=1, max=36_500
     ),
+    ConfigSpec("rss_fallback_hours", "int", "backfill", "rss_fallback_hours", min=0, max=168),
     # --- Shorts probe ---
     ConfigSpec(
         "shorts_probe_max_seconds", "int", "shorts", "shorts_probe_max_seconds", min=1, max=3_600
@@ -173,6 +176,7 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec("plex_overlay_map", "str", "plex", "plex_overlay_map"),
     # (plex_sync_interval_min is tuned from the Scheduler dashboard, not here — it's a scheduler job.)
     ConfigSpec("plex_max_transcodes", "int", "plex", "plex_max_transcodes", min=0, max=16),
+    ConfigSpec("plex_max_sessions", "int", "plex", "plex_max_sessions", min=1, max=64),
     # Transcode re-encode tuning (E6 S1). The libx264 knobs apply only to the software fallback.
     # crf 0–51 (x264 range); max_height 0 = source.
     ConfigSpec("plex_transcode_hw", "choice", "plex", "plex_transcode_hw"),
@@ -208,11 +212,23 @@ def _default(s: ConfigSpec):
     return getattr(settings, s.default_attr)
 
 
+class InvalidSetting(ValueError):
+    """A value `set_value` refuses, as a reason the UI translates (`errors.refused.setting_<reason>`)
+    plus what the sentence needs — the English message is for logs only. A ValueError still, so a
+    caller that only needs "refused or not" keeps working."""
+
+    def __init__(self, key: str, reason: str, **params: object):
+        super().__init__(f"{key}: {reason} {params}")
+        self.key = key
+        self.reason = reason
+        self.params = params
+
+
 def _choice(s: ConfigSpec, raw: object) -> str:
-    """The canonical spelling of `raw` among the key's choices (any letter case), or ValueError."""
+    """The canonical spelling of `raw` among the key's choices (any letter case), or InvalidSetting."""
     option = canonical_choice(s.choices, raw)
     if option is None:
-        raise ValueError(f"{s.key} must be one of: {', '.join(s.choices)}")
+        raise InvalidSetting(s.key, "not_a_choice", choices=", ".join(s.choices))
     return option
 
 
@@ -269,7 +285,17 @@ def get(db: Session, key: str):
         return _default(s)
     try:
         return _coerce(s, raw)
-    except (TypeError, ValueError):
+    except (TypeError, ValueError) as exc:
+        # The admin set this in the UI and it is quietly not in force: the app runs on the env
+        # default while the settings page goes on showing the value that was saved.
+        if (s.key, raw) not in _coerce_warned:
+            _coerce_warned.add((s.key, raw))
+            log.warning(
+                "a stored setting could not be coerced; the default is used instead",
+                extra=logs.event(
+                    "sysconfig.override_uncoercible", key=s.key, reason=type(exc).__name__
+                ),
+            )
         return _default(s)
 
 
@@ -292,11 +318,14 @@ def set_value(db: Session, key: str, value) -> None:
     (B-core-10). The staged value is visible to a same-session `get()` before the commit."""
     s = _BY_KEY[key]
     if s.type == "int":
-        v = int(value)
+        try:
+            v = int(value)
+        except (TypeError, ValueError):
+            raise InvalidSetting(key, "not_a_number") from None
         if s.min is not None and v < s.min:
-            raise ValueError(f"{key} must be >= {s.min}")
+            raise InvalidSetting(key, "too_low", min=s.min)
         if s.max is not None and v > s.max:
-            raise ValueError(f"{key} must be <= {s.max}")
+            raise InvalidSetting(key, "too_high", max=s.max)
         raw = str(v)
     elif s.type == "bool":
         raw = "true" if value else "false"
@@ -308,7 +337,7 @@ def set_value(db: Session, key: str, value) -> None:
     stored, encrypted = raw, False
     if s.secret:
         if not secrets_manageable():
-            raise RuntimeError("TOKEN_ENCRYPTION_KEY is not configured")
+            raise InvalidSetting(key, "no_encryption_key")
         stored, encrypted = security.encrypt(raw) or "", True
 
     row = db.get(SystemConfig, key)

backend/app/utils.py

@@ -73,6 +73,14 @@ def to_tsquery_str(q: str) -> str | None:
     return " & ".join(tokens)
 
 
+def like_escape(s: str) -> str:
+    """`s` as a LITERAL inside a LIKE/ILIKE pattern: `%` and `_` are wildcards there, and `\\` is
+    Postgres's default escape character, so all three are escaped. Every pattern built from text a
+    person typed goes through this — unescaped, a search for `100%` or `my_channel` matches rows it
+    should not."""
+    return s.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+
 def normalize_description(text: str | None) -> str | None:
     """Strip whitespace-only lines from a CHANNEL description before storing. YouTube channel
     descriptions pad their contact/link blocks with runs of blank lines; keeping them wastes storage,

backend/app/worker.py

@@ -16,7 +16,6 @@ Design:
   * Crash-safe: on startup, orphaned `running` jobs are requeued and `downloading` assets reset.
 """
 
-import logging
 import os
 import shutil
 import signal
@@ -24,6 +23,7 @@ import subprocess
 import sys
 import threading
 import time
+from collections.abc import Callable
 from datetime import datetime, timezone
 
 from sqlalchemy import text
@@ -45,8 +45,7 @@ from app.downloads.jobdb import (
 from app.downloads.status import STOPPED_BY_ROUTE, JobStatus
 from app.models import DownloadJob, MediaAsset
 
-log = logging.getLogger("siftlode.worker")
-
+log = logs.get_logger(__name__)
 _stop = threading.Event()
 
 
@@ -73,13 +72,14 @@ def _wait_for_schema(timeout: float = 300.0) -> bool:
             with SessionLocal() as db:
                 db.execute(text("SELECT 1 FROM download_jobs LIMIT 1"))
             return True
-        except Exception as exc:  # noqa: BLE001 — table not migrated yet / DB not up yet
+        except Exception:  # noqa: BLE001 — table not migrated yet / DB not up yet
             if time.monotonic() > deadline:
-                log.error(
-                    "download schema still absent after %ss — the API's migrations have not landed; "
-                    "exiting so the container restarts: %s",
+                # The traceback, not `str(exc)[:120]`: this is the last thing the worker says
+                # before it exits, and which driver call failed is the whole question.
+                log.exception(
+                    "download schema still absent after %ss — the API's migrations have not "
+                    "landed; exiting so the container restarts",
                     timeout,
-                    str(exc)[:120],
                 )
                 return False
             log.info("waiting for the database schema (API migrations)…")
@@ -219,8 +219,17 @@ def _signal_group(proc: subprocess.Popen, pgid: int | None, sig: int) -> None:
             os.killpg(pgid, sig)
         else:
             proc.send_signal(sig)
-    except (ProcessLookupError, OSError):
-        pass
+    except ProcessLookupError:
+        pass  # silent-ok: the child already exited — the race this function is written around
+    except OSError as exc:
+        # Any OTHER refusal means the signal did not land and the child is still running, which
+        # is how a "cancelled" download keeps writing to a staging tree nobody is watching.
+        log.info(
+            "a download child could not be signalled",
+            extra=logs.event(
+                "download.child.signal_failed", signal=int(sig), reason=type(exc).__name__
+            ),
+        )
 
 
 def _stop_child(proc: subprocess.Popen, grace_s: float) -> None:
@@ -230,6 +239,8 @@ def _stop_child(proc: subprocess.Popen, grace_s: float) -> None:
     child already exited, and `getpgid` yields None for a reaped pid, so no separate poll guard."""
     try:
         pgid: int | None = os.getpgid(proc.pid)
+    # silent-ok: `getpgid` refuses for a reaped pid, which the docstring above already treats as
+    # the ordinary case — the escalation then signals the child alone and no-ops if it is gone.
     except OSError:
         pgid = None
     editmod.escalate_kill(
@@ -250,23 +261,42 @@ def _stop_and_free(job_id: int, asset_id: int, proc: subprocess.Popen, grace_s:
 
 
 def _fail_after_kill(
-    job_id: int, asset_id: int, proc: subprocess.Popen, grace_s: float, error: str, error_code: str
-) -> None:
+    job_id: int,
+    asset_id: int,
+    proc: subprocess.Popen,
+    grace_s: float,
+    error: str,
+    error_code: str,
+    cause: str | None = None,
+) -> bool:
     """`_stop_and_free` + mark the job errored — for the watchdog's stall/timeout kills and the
-    supervisor-error fallback."""
+    supervisor-error fallback. Returns whether the job failed here (`_fail_running`)."""
     _stop_and_free(job_id, asset_id, proc, grace_s)
-    _fail_running(job_id, error=error, error_code=error_code)
+    return _fail_running(job_id, error=error, error_code=error_code, cause=cause)
 
 
 def _fail_running(
-    job_id: int, *, error: str, error_code: str | None, error_detail: str | None = None
-) -> None:
+    job_id: int,
+    *,
+    error: str,
+    error_code: str | None,
+    error_detail: str | None = None,
+    cause: str | None = None,
+    exit_code: int | None = None,
+) -> bool:
     """Fail a claimed job — only while it is still `running` (`service.finalize_if_running`), so a
     cancel/pause a route landed first is never turned back into `error`, which holds the asset the
     route already released. `error_detail` is written every time: a failure never shows an earlier
-    failure's explanation."""
+    failure's explanation.
+
+    `cause` is the worker's half of `download.job.failed`: the failures the child never got to
+    report because it was killed, never ran or died — a stall, the wall-clock cap, a non-zero exit
+    (with its `exit_code`). Without it those left no line at all. A caller that logs its own line
+    (a worker error, with its stack — `_report_worker_error`) passes none and uses the returned
+    verdict. Logged only when the job actually failed here: a route's cancel that landed first is
+    not a failure. Returns whether it failed here."""
     with SessionLocal() as db:
-        service.finalize_if_running(
+        failed = service.finalize_if_running(
             db,
             job_id,
             status=JobStatus.ERROR,
@@ -276,6 +306,49 @@ def _fail_running(
             phase=None,
         )
         db.commit()
+    if cause is not None and failed:
+        log.warning(
+            "job %s failed in the worker: %s",
+            job_id,
+            cause,
+            extra=logs.event(
+                "download.job.failed",
+                job_id=job_id,
+                error_code=error_code,
+                cause=cause,
+                **({"exit_code": exit_code} if exit_code is not None else {}),
+            ),
+        )
+    return failed
+
+
+def _report_worker_error(job_id: int, exc: Exception, cause: str, fail: Callable[[], bool]) -> None:
+    """A worker error on a job (the supervisor loop, or processing the job, raised): fail the job,
+    then ONE line with the stack. Its event says what the error did to the job —
+    `download.job.failed` when the job failed with it, `download.worker.error` when a route had
+    already stopped it (a cancel that landed first is not a failure, `_fail_running`).
+
+    The line goes out even when failing the job raises (the database is down): as
+    `download.worker.error`, since the job was not failed, and the raise goes on to the caller —
+    without `exc` as its context, which this line has already carried with its stack."""
+    failed = False
+    try:
+        failed = fail()
+    except BaseException as write_error:
+        write_error.__suppress_context__ = True
+        raise
+    finally:
+        log.error(
+            "job %s: worker error (%s)",
+            job_id,
+            cause,
+            exc_info=exc,
+            extra=logs.event(
+                "download.job.failed" if failed else "download.worker.error",
+                job_id=job_id,
+                cause=cause,
+            ),
+        )
 
 
 def _run_supervised(job_id: int, asset_id: int) -> None:
@@ -306,6 +379,8 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
             try:
                 proc.wait(timeout=poll_s)
                 break  # child finished on its own
+            # silent-ok: the timeout is the loop's clock, not a failure — it is what gives this
+            # thread a turn to check whether a route cancelled the job.
             except subprocess.TimeoutExpired:
                 pass
             status, stale = _job_liveness(job_id)
@@ -328,15 +403,20 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
             # else: a terminal status under the cap (done/error, or a re-queued contended asset) means
             # the child is exiting on its own — keep polling; NEVER kill a finishing child (that could
             # drop its completion notice).
-    except Exception:  # noqa: BLE001 — a watchdog error must NEVER leave the child running unsupervised
-        log.exception("supervisor loop failed for job %s; stopping the child", job_id)
-        _fail_after_kill(
+    except Exception as exc:  # noqa: BLE001 — a watchdog error must NEVER leave the child running unsupervised
+        # silent-ok: not silent — `_report_worker_error` is the report.
+        _report_worker_error(
             job_id,
-            asset_id,
-            proc,
-            grace_s,
-            "The download was stopped after a worker error.",
-            "unknown",
+            exc,
+            "supervisor_error",
+            lambda: _fail_after_kill(
+                job_id,
+                asset_id,
+                proc,
+                grace_s,
+                "The download was stopped after a worker error.",
+                "unknown",
+            ),
         )
         return
 
@@ -355,9 +435,8 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
                         job_id,
                         error=f"The download process exited unexpectedly (code {proc.returncode}).",
                         error_code="unknown",
-                    )
-                    log.warning(
-                        "job %s: child exited %s without finishing", job_id, proc.returncode
+                        cause="child_exit",
+                        exit_code=proc.returncode,
                     )
         except Exception:  # noqa: BLE001 — boot recovery is the backstop for a stuck 'running' job
             log.exception("post-exit reconciliation failed for job %s", job_id)
@@ -371,6 +450,7 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
             grace_s,
             f"The download stalled (no progress for {int(stall_s)}s) and was stopped.",
             "network",
+            cause="stalled",
         )
         return
     if reason == "timeout":
@@ -381,6 +461,7 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
             grace_s,
             f"The download exceeded the {int(wall_s)}s time limit and was stopped.",
             "network",
+            cause="timeout",
         )
         return
     # cancelled / abandon / shutdown: stop + free the asset, but leave the job's own DB status.
@@ -389,10 +470,19 @@ def _run_supervised(job_id: int, asset_id: int) -> None:
         _requeue_if_running(job_id, None)  # resume on the next boot
     elif reason == "abandon":
         log.warning(
-            "job %s: killed a child wedged past the wall-clock; DB status left intact", job_id
+            "job %s: killed a child wedged past the wall-clock; DB status left intact",
+            job_id,
+            extra=logs.event("download.child.abandoned", job_id=job_id),
         )
     else:  # cancelled
-        log.info("job %s: child stopped (route pause/cancel)", job_id)
+        # Not `download.job.aborted`: that is the child's line, logged when it notices the pause
+        # itself — and it often has, and is only tearing down when this poll comes round. This one
+        # says the worker had to stop it.
+        log.info(
+            "job %s: child stopped (route pause/cancel)",
+            job_id,
+            extra=logs.event("download.child.stopped", job_id=job_id),
+        )
 
 
 def _cleanup_staging(asset_id: int) -> None:
@@ -432,7 +522,7 @@ def _process_job(job_id: int) -> None:
             del cookie  # only whether there is one matters here
 
     if asset is None:
-        _fail_running(job_id, error="No media asset", error_code=None)
+        _fail_running(job_id, error="No media asset", error_code=None, cause="no_asset")
         return
 
     if asset_status == "ready":
@@ -444,6 +534,7 @@ def _process_job(job_id: int) -> None:
             error=asset_error or "Download failed",
             error_code=diagnosis.code,
             error_detail=diagnosis.detail,
+            cause="asset_failed",
         )
         return
     if asset_status == "downloading":
@@ -500,9 +591,23 @@ def _worker_loop(idx: int) -> None:
         with logs.bind(job_id=job_id):
             try:
                 _process_job(job_id)
-            except Exception:  # noqa: BLE001
-                log.exception("processing job %s crashed", job_id)
-                _fail_running(job_id, error="Worker error", error_code=None)
+            except Exception as exc:  # noqa: BLE001
+                try:
+                    _report_worker_error(
+                        job_id,
+                        exc,
+                        "crash",
+                        lambda: _fail_running(job_id, error="Worker error", error_code=None),
+                    )
+                # silent-ok: not silent — `_report_worker_error` logged the crash before this
+                # re-raise. Failing the job hit the database, and letting that out would end this
+                # worker thread for good; boot recovery settles a job left `running`.
+                except Exception:  # noqa: BLE001
+                    log.exception(
+                        "could not fail job %s after its crash",
+                        job_id,
+                        extra=logs.event("download.worker.fail_write_failed", job_id=job_id),
+                    )
 
 
 def main() -> None:

backend/app/youtube/client.py

@@ -9,21 +9,128 @@ uses OAuth.
 import logging
 from collections.abc import Iterator
 from datetime import datetime, timedelta, timezone
+from typing import Literal
 
 import httpx
 
-from app import quota, sysconfig
+from app import logs, quota, sysconfig
 from app.models import User
 from app.security import decrypt, decrypt_optional, encrypt
 
-log = logging.getLogger("siftlode.youtube")
-
+log = logs.get_logger(__name__)
 GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"
 API_BASE = "https://www.googleapis.com/youtube/v3"
 
 
 class YouTubeError(Exception):
-    pass
+    """An upstream YouTube Data API failure.
+
+    `reason` is the API's own error reason code (`quotaExceeded`, `subscriptionDuplicate`,
+    `videoNotFound`, …) when the body carried one. Branch on THAT, never on the message: the
+    message is prose, it changes under us, and it is deliberately the poorer of the two here.
+
+    `path` is the API endpoint that ANSWERED with the failure (`playlistItems`); empty when no
+    endpoint did — the request never got through (`transport`) or the token step refused first."""
+
+    def __init__(self, message: str, *, reason: str = "", path: str = ""):
+        super().__init__(message)
+        self.reason = reason
+        self.path = path
+
+
+def _error_reason(resp: httpx.Response) -> str:
+    """The `reason` YouTube puts on an API error. That is the whole diagnostic value of an error
+    body; the `message` beside it is prose, and upstream prose can quote the request back — a
+    search term, a playlist title."""
+    try:
+        error = resp.json().get("error")
+        # The OAuth token endpoint's shape: `{"error": "invalid_grant", "error_description": …}`.
+        if isinstance(error, str):
+            return error or "<none>"
+        errors = (error or {}).get("errors") or []
+        reasons = ",".join(e.get("reason", "") for e in errors if e.get("reason"))
+    # silent-ok: the sentinel it returns goes straight into the caller's warning line, which
+    # is the report. (Any non-JSON body — an HTML error page from a proxy.)
+    except Exception:  # noqa: BLE001
+        return "<unparseable>"
+    return reasons or "<none>"
+
+
+def _upstream_failure(
+    method: str, path: str, resp: httpx.Response, expected: frozenset[str] = frozenset()
+) -> YouTubeError:
+    """Report one upstream failure and build the error to raise. Every YouTube response that is
+    not a success goes through here — the Data API's reads, writes and deletes and the OAuth
+    token refresh — so what may appear in a log line cannot drift apart between them, and the
+    error a caller raises carries the reason code rather than the body, because callers put it in
+    a log line (`routes/channels.py`) and in a 422 answered to the user. (A request that got no
+    response at all is `_send`'s, with the reason `transport`.) The body is logged only under
+    the requesting user's own Teljes consent: it is the request quoted back."""
+    reason = _error_reason(resp)
+    # A reason the caller named as an answer rather than a failure (`channelNotFound` on a `mine`
+    # read: the account simply has no channel) is still raised, but it is not a warning — it came
+    # back every six hours for an account that will never have one.
+    log.log(
+        logging.DEBUG if reason in expected else logging.WARNING,
+        "YouTube %s %s -> %s (%s)",
+        method,
+        path,
+        resp.status_code,
+        reason,
+        extra=logs.event(
+            "youtube.api.error",
+            method=method,
+            path=path,
+            status=resp.status_code,
+            reason=reason,
+        ),
+    )
+    if logs.consented_trace():
+        log.log(
+            logs.TRACE,
+            "the upstream body behind it",
+            # log-pii-ok: only under this user's own Teljes consent, which is what it is for
+            extra=logs.event("youtube.api.body", body=resp.text[:500]),
+        )
+    return YouTubeError(
+        f"{method} {path} -> {resp.status_code}: {reason}", reason=reason, path=path
+    )
+
+
+# The `mine` reads' answer for a Google account that has no YouTube channel.
+_NO_CHANNEL = frozenset({"channelNotFound"})
+
+# The reasons that mean the project's quota is spent: every further call today gets the same answer.
+_QUOTA_REASONS = frozenset({"quotaExceeded", "dailyLimitExceeded"})
+
+
+def is_quota_refusal(exc: YouTubeError) -> bool:
+    """Whether the API refused for want of quota. `reason` can list several codes, comma-joined."""
+    return any(r in _QUOTA_REASONS for r in exc.reason.split(","))
+
+
+# The token endpoint's answer for a revoked or expired grant — the one refusal a reconnect fixes.
+_DEAD_GRANT = "invalid_grant"
+
+# What a refused YouTube action means to the person who asked for it — the three things they can
+# act on differently: wait for tomorrow's budget, reconnect the account, or try again later.
+YouTubeRefusal = Literal["quota", "reconnect", "unavailable"]
+
+
+def refusal_reason(exc: YouTubeError) -> YouTubeRefusal:
+    """Sort a failure by what the user can do about it. A dead grant (Google refused the refresh
+    with `invalid_grant`, which also drops the grant — see `_drop_dead_grant`) or no usable token at
+    all (raised before any endpoint answered, so with no path and no transport reason) means the
+    account must be reconnected; retrying cannot help. Any other token-endpoint failure — a 5xx, a
+    429, a misconfigured client — leaves the grant as it was: reconnecting would not fix it, and
+    the account would still read as connected, with no connect button to press."""
+    if is_quota_refusal(exc):
+        return "quota"
+    if exc.path == "oauth2/token":
+        return "reconnect" if exc.reason == _DEAD_GRANT else "unavailable"
+    if not exc.path and exc.reason != "transport":
+        return "reconnect"
+    return "unavailable"
 
 
 def _chunks(items: list, size: int) -> Iterator[list]:
@@ -62,13 +169,13 @@ class YouTubeClient:
         YouTubeError — degrade gracefully, log, and move on — so wrapping here keeps a
         transient network fault (e.g. the fixed-IP egress proxy being unreachable) from
         escaping as a raw httpx error and turning into an uncaught 500. HTTP status errors
-        are NOT touched here (we don't use raise_for_status): callers inspect resp.status_code
-        themselves and raise their own YouTubeError with the response body."""
+        are NOT touched here (we don't use raise_for_status): each call site inspects
+        resp.status_code itself and hands the response to `_upstream_failure`."""
         try:
             return self._http.request(method, url, **kwargs)
         except httpx.HTTPError as exc:
             raise YouTubeError(
-                f"YouTube API unreachable ({exc.__class__.__name__}: {exc})"
+                f"YouTube API unreachable ({exc.__class__.__name__}: {exc})", reason="transport"
             ) from exc
 
     # --- auth ---
@@ -99,7 +206,10 @@ class YouTubeClient:
             },
         )
         if resp.status_code != 200:
-            raise YouTubeError(f"Token refresh failed: {resp.status_code} {resp.text[:200]}")
+            exc = _upstream_failure("POST", "oauth2/token", resp)
+            if exc.reason == _DEAD_GRANT:
+                self._drop_dead_grant(tok)
+            raise exc
         data = resp.json()
         access = data["access_token"]
         tok.access_token = encrypt(access)
@@ -109,8 +219,34 @@ class YouTubeClient:
         log.info("Refreshed access token for user %s", self.user.id)
         return access
 
+    def _drop_dead_grant(self, tok) -> None:
+        """Google answered the refresh with `invalid_grant`: the grant was revoked or expired, and no
+        retry will revive it. Forget it, so the account reads as NOT connected — Settings and the
+        onboarding wizard then offer the connect button again (a fresh consent issues a new refresh
+        token). Kept as "granted", the UI showed a live connection with no way to renew it while
+        every call failed. Committed like the refresh above: the caller rolls back on the error."""
+        tok.scopes = None
+        tok.access_token = None
+        tok.refresh_token_enc = None
+        tok.expiry = None
+        self.db.add(tok)
+        self.db.commit()
+        # INFO: the refusal itself is already the warning (`youtube.api.error`, invalid_grant).
+        log.info(
+            "cleared the dead YouTube grant of user %s",
+            self.user.id,
+            extra=logs.event("youtube.grant.cleared"),
+        )
+
     # --- core request ---
-    def _get(self, path: str, params: dict, cost: int = 1, allow_key: bool = True) -> dict:
+    def _get(
+        self,
+        path: str,
+        params: dict,
+        cost: int = 1,
+        allow_key: bool = True,
+        expected: frozenset[str] = frozenset(),
+    ) -> dict:
         p = dict(params)
         headers = {}
         api_key = sysconfig.get_str(self.db, "youtube_api_key")
@@ -121,8 +257,7 @@ class YouTubeClient:
         resp = self._send("GET", f"{API_BASE}/{path}", params=p, headers=headers)
         quota.record_usage(cost)
         if resp.status_code != 200:
-            log.warning("YouTube API %s -> %s: %s", path, resp.status_code, resp.text[:200])
-            raise YouTubeError(f"GET {path} -> {resp.status_code}: {resp.text[:300]}")
+            raise _upstream_failure("GET", path, resp, expected)
         return resp.json()
 
     # --- endpoints ---
@@ -162,7 +297,14 @@ class YouTubeClient:
             params = {"part": "snippet,contentDetails", "mine": "true", "maxResults": 50}
             if page_token:
                 params["pageToken"] = page_token
-            data = self._get("playlists", params, cost=1, allow_key=False)
+            try:
+                data = self._get("playlists", params, cost=1, allow_key=False, expected=_NO_CHANNEL)
+            except YouTubeError as exc:
+                # A Google account without a YouTube channel has no playlists, and YouTube says
+                # so as a 404. That is an empty list, not a failed sync.
+                if exc.reason in _NO_CHANNEL:
+                    return
+                raise
             for item in data.get("items", []):
                 sn = item.get("snippet", {})
                 yield {
@@ -247,12 +389,7 @@ class YouTubeClient:
         )
         quota.record_usage(50)
         if resp.status_code not in (200, 204):
-            log.warning(
-                "YouTube subscriptions.delete -> %s: %s",
-                resp.status_code,
-                resp.text[:200],
-            )
-            raise YouTubeError(f"DELETE subscriptions -> {resp.status_code}: {resp.text[:300]}")
+            raise _upstream_failure("DELETE", "subscriptions", resp)
 
     def insert_subscription(self, channel_id: str) -> str:
         """Subscribe to a channel on YouTube. Requires the write scope and the user's
@@ -282,8 +419,7 @@ class YouTubeClient:
         resp = self._send(method, f"{API_BASE}/{path}", params=params, json=json, headers=headers)
         quota.record_usage(50)
         if resp.status_code not in (200, 204):
-            log.warning("YouTube %s %s -> %s: %s", method, path, resp.status_code, resp.text[:200])
-            raise YouTubeError(f"{method} {path} -> {resp.status_code}: {resp.text[:300]}")
+            raise _upstream_failure(method, path, resp)
         return resp.json() if resp.content else {}
 
     def get_playlist_snippet(self, playlist_id: str) -> dict | None:

backend/app/youtube/rss.py

@@ -1,6 +1,7 @@
 """Free per-channel RSS feed reader (no API quota). Returns the channel's most recent
 ~15 uploads as lightweight stubs for fast fresh-video detection."""
 
+import time
 from datetime import datetime, timezone
 
 import feedparser
@@ -8,6 +9,18 @@ import httpx
 
 RSS_URL = "https://www.youtube.com/feeds/videos.xml?channel_id={channel_id}"
 
+# The waits before a second and a third try. YouTube's feed endpoint answers the SAME channel with
+# 404, 500 and 200 in turn (measured 2026-09-19: 15 of 24 channels failed a first request, 16 of them
+# had succeeded by the fifth, one second apart), so one failure is not an answer. A feed that is
+# really gone costs two more requests per poll. A TIMEOUT is not tried again: the flaky endpoint
+# answers fast, and a request that hung for `TIMEOUT` says the way out is hanging — three of them
+# per channel would stretch a poll over a dead egress to three times its interval.
+RETRY_DELAYS = (1.0, 2.0)
+TIMEOUT = 20.0
+# A 404 is in the set because that is how the flaky endpoint fails most often; a 403/410 is not,
+# and neither is anything else that says the request itself is wrong.
+_RETRYABLE_STATUS = frozenset({404, 429, 500, 502, 503, 504})
+
 
 class RssError(Exception):
     """The feed could not be read (transport failure or a non-200 answer).
@@ -24,21 +37,36 @@ class RssError(Exception):
         self.reason = reason
 
 
-def fetch_channel_feed(channel_id: str) -> list[dict]:
-    """The channel's recent uploads as stubs. `[]` means the feed really is empty; a failure
-    raises RssError so the caller can leave the channel un-stamped and log it."""
+def _get_feed(channel_id: str) -> bytes:
+    """The feed's body, after up to `1 + len(RETRY_DELAYS)` tries; the LAST failure is raised."""
     url = RSS_URL.format(channel_id=channel_id)
-    try:
-        resp = httpx.get(url, timeout=20.0, headers={"User-Agent": "Siftlode/1.0"})
-    except httpx.HTTPError as exc:
-        raise RssError(f"RSS fetch failed for {channel_id}: {exc}", "transport") from exc
-    if resp.status_code != 200:
-        raise RssError(
+    for attempt in range(len(RETRY_DELAYS) + 1):
+        if attempt:
+            time.sleep(RETRY_DELAYS[attempt - 1])
+        try:
+            resp = httpx.get(url, timeout=TIMEOUT, headers={"User-Agent": "Siftlode/1.0"})
+        # silent-ok: not silent — the last failure is raised after the final try.
+        except httpx.HTTPError as exc:
+            error = RssError(f"RSS fetch failed for {channel_id}: {exc}", "transport")
+            error.__cause__ = exc
+            if isinstance(exc, httpx.TimeoutException):
+                break
+            continue
+        if resp.status_code == 200:
+            return resp.content
+        error = RssError(
             f"RSS fetch for {channel_id} returned HTTP {resp.status_code}",
             f"http_{resp.status_code}",
         )
+        if resp.status_code not in _RETRYABLE_STATUS:
+            break
+    raise error
 
-    parsed = feedparser.parse(resp.content)
+
+def fetch_channel_feed(channel_id: str) -> list[dict]:
+    """The channel's recent uploads as stubs. `[]` means the feed really is empty; a failure
+    (after the retries) raises RssError so the caller can leave the channel un-stamped and log it."""
+    parsed = feedparser.parse(_get_feed(channel_id))
     out: list[dict] = []
     for entry in parsed.entries:
         video_id = entry.get("yt_videoid")

backend/app/youtube/search_scrape.py

@@ -21,6 +21,10 @@ import re
 
 import httpx
 
+from app import logs
+
+log = logs.get_logger(__name__)
+
 _SEARCH_URL = "https://www.youtube.com/youtubei/v1/search"
 _RESULTS_URL = "https://www.youtube.com/results"
 # Public WEB InnerTube key + a recent client version. These are also embedded in every results
@@ -74,7 +78,14 @@ def _get_config(client: httpx.Client) -> tuple[str, str]:
             key.group(1) if key else _FALLBACK_KEY,
             ver.group(1) if ver else _FALLBACK_CLIENT_VERSION,
         )
-    except httpx.HTTPError:
+    except httpx.HTTPError as exc:
+        # The fallback pair is CACHED in `_config` for the life of the process, so one failed
+        # fetch at the wrong moment pins every later search to a hard-coded key and version —
+        # and when those go stale, search returns nothing at all, with no error anywhere.
+        log.warning(
+            "the InnerTube config could not be fetched; falling back to the pinned key",
+            extra=logs.event("youtube.scrape.config_fallback", reason=type(exc).__name__),
+        )
         _config = (_FALLBACK_KEY, _FALLBACK_CLIENT_VERSION)
     return _config
 

backend/app/youtube/shorts.py

@@ -18,6 +18,8 @@ def probe_is_short(client: httpx.Client, video_id: str) -> bool | None:
     """True if a Short, False if a regular video, None if undetermined (retry later)."""
     try:
         resp = client.get(SHORTS_URL.format(video_id=video_id), follow_redirects=False)
+    # silent-ok: None is the documented third state — "undetermined, ask again later" — and the
+    # scheduler retries it. It is not the same answer as False, so nothing is being hidden.
     except httpx.HTTPError:
         return None
     if resp.status_code == 200:

backend/ruff.toml

@@ -9,4 +9,21 @@
 line-length = 100
 
 [lint]
+# Beyond the default set, the rules that hold a LOG LINE to what E22.5 makes of it:
+#   LOG     — stdlib logging misuse (`.warn()`, a logger built by hand, `exc_info` on `.exception`)
+#   G       — the call's shape: %-style args, never an f-string the level filter cannot skip, and
+#             never `str(exc)` where `exc_info` would carry the traceback
+#   T20     — `print` instead of a log line. Two deliberate ones remain, each with its `# noqa`
+#             and a why: `downloads/runner.py`'s usage line is for whoever typed it, and
+#             `logsink.py` reports the SINK's own failure, which cannot be logged into the sink.
+#   TRY400  — `.error()` in an `except` where `.exception()` would keep the traceback
+#   TRY401  — the exception spelled into the message AND passed as `exc_info` (it is in both)
+#   S112    — `except: continue`, the silent swallow inside a loop
+#   S110    — `except: pass`, the same thing outside one
+#   BLE001  — a blind `except Exception`. Every one that remains carries `# noqa: BLE001 — <why>`,
+#             which is the point: catching everything is sometimes right (a worker thread with
+#             nobody to raise to, a best-effort backfill inside a sync) and always worth a sentence.
+# The wider rule these two enforce lives in tests/test_swallowed_exceptions.py: a handler that
+# neither logs nor re-raises says `# silent-ok: <why>`. Ruff sees only the two narrow shapes.
+extend-select = ["LOG", "G", "T20", "TRY400", "TRY401", "S110", "S112", "BLE001"]
 ignore = ["E402"]

backend/tests/conftest.py

@@ -21,7 +21,8 @@ from alembic import command
 from alembic.config import Config
 from fastapi import HTTPException, Request
 from fastapi.testclient import TestClient
-from sqlalchemy import create_engine, text
+from sqlalchemy import create_engine, event, text
+from starlette.requests import HTTPConnection
 
 import app.models  # noqa: F401 — register every model on Base.metadata
 import app.state as app_state
@@ -49,7 +50,9 @@ def _db_reachable() -> bool:
         with probe.connect() as conn:
             conn.execute(text("SELECT 1"))
         return True
-    except Exception:
+    # silent-ok / noqa BLE001: the question is literally "can anything reach it", so every
+    # failure is the same answer — and this runs at import, before logging is configured.
+    except Exception:  # noqa: BLE001
         return False
     finally:
         probe.dispose()
@@ -98,17 +101,61 @@ def pytest_configure(config):
         )
 
 
+def _request_dep(db, unfinished: list[str]):
+    """`get_db` for a test request: the test's own session, plus the check a shared session hides.
+
+    A route helper flushes and its HANDLER commits (CLAUDE.md). Production's `get_db` closes the
+    session after the request, which rolls back anything flushed but not committed — yet here every
+    request shares the test's session, so a follow-up GET or an assertion reads the flushed write
+    and the suite stays green over a handler that forgot to commit (deep review, debt burn). So a
+    request that ends normally with a write it did not commit — flushed, or still only staged — is
+    recorded, and the test fails on it at teardown. Only the ROOT transaction's end clears it: a
+    savepoint released inside the handler commits nothing. The test's own staged rows are flushed before the request starts — they are the
+    test's business, not the handler's. A request that raises is exempt: its writes are meant to
+    roll back."""
+
+    def dep(conn: HTTPConnection):
+        db.flush()
+        state = {"dirty": False}
+
+        def flushed(session, ctx):
+            state["dirty"] = True
+
+        def ended(session, transaction):
+            if transaction.parent is None:
+                state["dirty"] = False
+
+        hooks = (("after_flush", flushed), ("after_transaction_end", ended))
+        for name, fn in hooks:
+            event.listen(db, name, fn)
+        try:
+            yield db
+            staged = db.new or db.deleted or any(db.is_modified(o) for o in db.dirty)
+            if state["dirty"] or staged:
+                unfinished.append(f"{conn.scope.get('method', 'WS')} {conn.url.path}")
+        finally:
+            for name, fn in hooks:
+                event.remove(db, name, fn)
+
+    return dep
+
+
 @pytest.fixture
 def db(_schema):
     """A real session against the test Postgres, on a clean (empty) database. The code under test
-    may commit freely."""
+    may commit freely. `db.info["request"]` is the `get_db` override for a request against it — the
+    one every test client uses — and a handler that left a write uncommitted fails the test here."""
     _truncate_all()
     session = SessionLocal()
+    unfinished: list[str] = []
+    session.info["request"] = _request_dep(session, unfinished)
+    session.info["unfinished"] = unfinished  # the requests recorded so far (the check's own test)
     try:
         yield session
     finally:
         session.rollback()
         session.close()
+    assert unfinished == [], "a handler left a write uncommitted"
 
 
 @pytest.fixture
@@ -166,7 +213,7 @@ def client(db, override_dep, _configured):
     `current_user` override — so login, the wallet gate and epoch revoke are exercised end to end.
     Starlette's SessionMiddleware round-trips the signed cookie, so a login in one call authenticates
     the next on this same instance. No lifespan (the scheduler / HLS sweep stay off)."""
-    override_dep(get_db, lambda: db)
+    override_dep(get_db, db.info["request"])
     return TestClient(app)
 
 
@@ -185,7 +232,7 @@ def as_user(db, override_dep, _configured):
             raise HTTPException(status_code=401, detail="Not authenticated")
         return registry[uid]
 
-    override_dep(get_db, lambda: db)
+    override_dep(get_db, db.info["request"])
     override_dep(current_user, _resolver)
 
     def _as(user: User) -> TestClient:

backend/tests/test_admin_invites.py

@@ -168,3 +168,15 @@ def test_deleting_the_user_also_clears_the_way_to_re_invite(db, make_user, as_us
     assert (
         db.execute(select(Invite).where(Invite.email == member.email)).scalar_one_or_none() is None
     )
+
+
+def test_whitelisting_a_new_address_audits_it_by_id(db, make_user, as_user):
+    """The audit row was written before the new invite had an id, so it named no target."""
+    from app.models import AuditLog
+
+    admin = make_user(role="admin")
+    r = as_user(admin).post("/api/admin/invites", json={"email": "fresh-e27@example.com"})
+    assert r.status_code == 200
+    inv = db.scalar(select(Invite).where(Invite.email == "fresh-e27@example.com"))
+    row = db.scalar(select(AuditLog).where(AuditLog.target_type == "invite"))
+    assert row is not None and row.target_id == str(inv.id)

backend/tests/test_admin_logs.py

@@ -0,0 +1,191 @@
+"""The admin diagnostics console's query API (E22.6 S1), DB-lane."""
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from sqlalchemy import insert
+
+from app.models import LogEvent
+
+T0 = datetime(2026, 9, 19, 12, 0, tzinfo=timezone.utc)
+
+
+def _row(**kw) -> dict:
+    row = {
+        "ts": T0,
+        "level": "INFO",
+        "sev": 9,
+        "source": "api",
+        "logger": "siftlode.http",
+        "event": "http.request",
+        "msg": "GET /api/feed 200",
+        "attrs": None,
+        "exc": None,
+        "request_id": None,
+        "user_id": None,
+        "job_id": None,
+        "version": "0.90.0",
+    }
+    row.update(kw)
+    return row
+
+
+def _add(db, *rows: dict) -> None:
+    db.execute(insert(LogEvent), list(rows))
+    db.commit()
+
+
+@pytest.fixture
+def admin(db, make_user, as_user):
+    return as_user(make_user(email="admin@example.com", role="admin"))
+
+
+def _msgs(resp) -> list[str]:
+    assert resp.status_code == 200, resp.text
+    return [it["msg"] for it in resp.json()["items"]]
+
+
+def test_only_an_admin_reads_the_log(db, make_user, as_user, client):
+    _add(db, _row())
+    assert as_user(make_user()).get("/api/admin/logs").status_code == 403
+    assert as_user(make_user()).get("/api/admin/logs/facets").status_code == 403
+    assert client.get("/api/admin/logs").status_code == 401
+
+
+def test_newest_first_and_every_row_once_across_pages_even_on_equal_timestamps(db, admin):
+    # A browser row's `ts` is clamped, so several rows share one: the id breaks the tie.
+    _add(db, *[_row(msg=f"same {i}") for i in range(5)], _row(ts=T0 - timedelta(1), msg="older"))
+
+    seen, cursor = [], None
+    while True:
+        resp = admin.get(
+            "/api/admin/logs", params={"limit": 2, "before": cursor} if cursor else {"limit": 2}
+        )
+        seen += _msgs(resp)
+        cursor = resp.json()["next_cursor"]
+        if cursor is None:
+            break
+
+    assert seen == ["same 4", "same 3", "same 2", "same 1", "same 0", "older"]
+
+
+@pytest.mark.parametrize(
+    ("params", "expected"),
+    [
+        ({"levels": ["ERROR", "WARNING"]}, {"err", "warn"}),
+        ({"sources": ["worker"]}, {"err"}),
+        ({"user": "1"}, {"mine"}),
+        ({"user": "none"}, {"err", "warn", "plain"}),
+        ({"event": "download.job.failed"}, {"err"}),
+        ({"event": "none"}, {"warn"}),
+        ({"request_id": "req-abcdef12"}, {"mine"}),
+        ({"job_id": 42}, {"err"}),
+        ({"q": "FORBIDDEN"}, {"err"}),  # in attrs, any case
+        ({"q": "KeyError"}, {"warn"}),  # in the stack
+        ({"q": "100%"}, {"plain"}),  # a literal, not a wildcard
+        ({"since": (T0 - timedelta(hours=1)).isoformat()}, {"mine", "err", "warn"}),
+        ({"until": (T0 - timedelta(hours=1)).isoformat()}, {"plain", "decoy"}),
+        ({"levels": ["INFO"], "user": "none"}, {"plain"}),
+    ],
+)
+def test_each_filter_selects_exactly_its_rows(db, admin, make_user, params, expected):
+    # user 1 is the admin the fixture made
+    _add(
+        db,
+        _row(msg="mine", user_id=1, request_id="req-abcdef12"),
+        _row(
+            msg="err",
+            level="ERROR",
+            sev=17,
+            source="worker",
+            event="download.job.failed",
+            job_id=42,
+            attrs={"code": "forbidden"},
+        ),
+        _row(msg="warn", level="WARNING", sev=13, event=None, exc="Traceback …\nKeyError: 'x'"),
+        _row(msg="plain", ts=T0 - timedelta(hours=2), attrs={"note": "100% done"}),
+        # Matched by no filter above but `until`: another account, and `100%` read as a pattern.
+        _row(msg="decoy", ts=T0 - timedelta(hours=3), attrs={"note": "1000 done"}, user_id=99),
+    )
+    assert set(_msgs(admin.get("/api/admin/logs", params=params))) == expected
+
+
+def test_a_page_names_its_accounts_and_leaves_an_erased_one_bare(db, admin):
+    _add(db, _row(user_id=1), _row(user_id=77))
+
+    assert admin.get("/api/admin/logs").json()["accounts"] == {"1": "admin@example.com"}
+
+
+@pytest.mark.parametrize(
+    "params",
+    [
+        {"before": "not-a-cursor"},
+        {"before": "WyJ4IiwgMV0="},  # ["x", 1]: decodes, not a timestamp
+    ],
+)
+def test_a_bad_cursor_is_a_400_with_a_code(db, admin, params):
+    resp = admin.get("/api/admin/logs", params=params)
+    assert resp.status_code == 400
+    assert resp.json()["detail"]["code"] == "bad_cursor"
+
+
+def test_facets_count_the_window_and_name_the_rows_without_a_value(db, admin):
+    _add(
+        db,
+        _row(user_id=1),
+        _row(user_id=1, level="ERROR", sev=17, event="sync.rss.failed"),
+        _row(event=None),
+        _row(ts=T0 - timedelta(days=2), source="worker"),
+    )
+
+    body = admin.get(
+        "/api/admin/logs/facets", params={"since": (T0 - timedelta(days=1)).isoformat()}
+    ).json()
+
+    assert body["total"] == 3
+    assert body["levels"] == [{"value": "INFO", "count": 2}, {"value": "ERROR", "count": 1}]
+    assert body["sources"] == [{"value": "api", "count": 3}]
+    assert body["events"] == [
+        {"value": "http.request", "count": 1},
+        {"value": "sync.rss.failed", "count": 1},
+        {"value": "none", "count": 1},
+    ]
+    assert body["users"] == [{"value": "1", "count": 2}, {"value": "none", "count": 1}]
+    assert body["accounts"] == {"1": "admin@example.com"}
+
+
+def test_a_facet_counts_under_every_other_filter_but_not_its_own(db, admin):
+    _add(
+        db,
+        _row(request_id="req-aaaaaaaa"),
+        _row(request_id="req-aaaaaaaa", level="ERROR", sev=17, source="worker"),
+        _row(request_id="req-bbbbbbbb", level="ERROR", sev=17),
+        _row(request_id="req-bbbbbbbb"),
+    )
+
+    body = admin.get(
+        "/api/admin/logs/facets", params={"request_id": "req-aaaaaaaa", "levels": ["ERROR"]}
+    ).json()
+
+    # The pivot narrows every count; the picked level does not zero its sibling (the way back).
+    assert body["levels"] == [{"value": "ERROR", "count": 1}, {"value": "INFO", "count": 1}]
+    assert body["total"] == 2
+    # Every other facet counts under the level filter too.
+    assert body["sources"] == [{"value": "worker", "count": 1}]
+
+
+@pytest.mark.parametrize(
+    ("params", "facet", "expected"),
+    [
+        ({"sources": ["worker"]}, "sources", {"api", "worker"}),
+        ({"user": "1"}, "users", {"1", "none"}),
+        ({"event": "sync.rss.failed"}, "events", {"http.request", "sync.rss.failed"}),
+    ],
+)
+def test_every_facet_keeps_its_siblings_under_its_own_filter(db, admin, params, facet, expected):
+    # The way back from a pick: the picked facet still offers the values it was picked from.
+    _add(db, _row(user_id=1), _row(source="worker", event="sync.rss.failed"))
+
+    body = admin.get("/api/admin/logs/facets", params=params).json()
+
+    assert {f["value"] for f in body[facet]} == expected

backend/tests/test_auth_session.py

@@ -447,7 +447,7 @@ def test_register_route_creates_the_account_end_to_end(client, db, monkeypatch):
 
     r = client.post("/auth/register", json={"email": "newbie@example.com", "password": _PW})
 
-    assert r.status_code == 200 and r.json() == {"status": "ok"}
+    assert r.status_code == 200 and r.json() == {"ok": True, "status": "ok"}
     db.expire_all()
     user = db.execute(_select(User).where(User.email == "newbie@example.com")).scalar_one_or_none()
     assert user is not None, "POST /auth/register answered ok but created nothing"

backend/tests/test_channel_backfill.py

@@ -18,7 +18,7 @@ from app.sync import runner, videos
 _PUB = datetime(2020, 1, 1, tzinfo=timezone.utc)
 
 
-def test_channel_detail_returns_normal_shorts_live_counts(db, monkeypatch):
+def test_channel_detail_returns_normal_shorts_live_counts(db, monkeypatch, override_dep):
     # published_at set so channel_detail skips the YouTube-enrich path (no quota / network in tests).
     ch = Channel(id="UC_nsl", title="N/S/L Channel", published_at=_PUB)
     db.add(ch)
@@ -40,12 +40,9 @@ def test_channel_detail_returns_normal_shorts_live_counts(db, monkeypatch):
 
     # The request gate 503s an unconfigured instance; flip the process-level flag (auto-restored).
     monkeypatch.setattr(state, "_configured_cache", True)
-    app.dependency_overrides[get_db] = lambda: db
-    app.dependency_overrides[current_user] = lambda: me
-    try:
-        resp = TestClient(app).get(f"/api/channels/{ch.id}")
-    finally:
-        app.dependency_overrides.clear()
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: me)
+    resp = TestClient(app).get(f"/api/channels/{ch.id}")
 
     assert resp.status_code == 200, resp.text
     body = resp.json()
@@ -56,7 +53,7 @@ def test_channel_detail_returns_normal_shorts_live_counts(db, monkeypatch):
 
 
 @pytest.mark.parametrize("hidden", [True, False])
-def test_channel_detail_surfaces_subscription_hidden_flag(db, monkeypatch, hidden):
+def test_channel_detail_surfaces_subscription_hidden_flag(db, monkeypatch, hidden, override_dep):
     # S6: the detail GET must expose the per-subscription `hidden` flag so the channel page can offer
     # the same Unhide toggle the manager has (the flag was previously omitted from the detail dict).
     ch = Channel(id="UC_hid", title="Hidden?", published_at=_PUB)
@@ -68,18 +65,15 @@ def test_channel_detail_surfaces_subscription_hidden_flag(db, monkeypatch, hidde
     db.commit()
 
     monkeypatch.setattr(state, "_configured_cache", True)
-    app.dependency_overrides[get_db] = lambda: db
-    app.dependency_overrides[current_user] = lambda: me
-    try:
-        resp = TestClient(app).get(f"/api/channels/{ch.id}")
-    finally:
-        app.dependency_overrides.clear()
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: me)
+    resp = TestClient(app).get(f"/api/channels/{ch.id}")
 
     assert resp.status_code == 200, resp.text
     assert resp.json()["hidden"] is hidden
 
 
-def test_channel_detail_hidden_defaults_false_when_not_subscribed(db, monkeypatch):
+def test_channel_detail_hidden_defaults_false_when_not_subscribed(db, monkeypatch, override_dep):
     # No subscription row → the flag can't be True; it must serialize as False, not raise.
     ch = Channel(id="UC_hid_ns", title="Unsub", published_at=_PUB)
     me = User(email="hidns@example.com")
@@ -87,12 +81,9 @@ def test_channel_detail_hidden_defaults_false_when_not_subscribed(db, monkeypatc
     db.commit()
 
     monkeypatch.setattr(state, "_configured_cache", True)
-    app.dependency_overrides[get_db] = lambda: db
-    app.dependency_overrides[current_user] = lambda: me
-    try:
-        resp = TestClient(app).get(f"/api/channels/{ch.id}")
-    finally:
-        app.dependency_overrides.clear()
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: me)
+    resp = TestClient(app).get(f"/api/channels/{ch.id}")
 
     assert resp.status_code == 200, resp.text
     assert resp.json()["hidden"] is False
@@ -115,33 +106,30 @@ def _setup_channel_and_sub(db, *, email, is_demo=False):
     return ch, user
 
 
-def _patch_deep_requested(db, monkeypatch, user):
+def _patch_deep_requested(db, monkeypatch, override_dep, user):
     calls: list[tuple] = []
     # background.add_task runs after the response in TestClient; record what would be scheduled.
     monkeypatch.setattr(channels_route, "backfill_channel_now", lambda *a, **k: calls.append(a))
     monkeypatch.setattr(state, "_configured_cache", True)
-    app.dependency_overrides[get_db] = lambda: db
-    app.dependency_overrides[current_user] = lambda: user
-    try:
-        resp = TestClient(app).patch("/api/channels/UC_wire", json={"deep_requested": True})
-    finally:
-        app.dependency_overrides.clear()
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: user)
+    resp = TestClient(app).patch("/api/channels/UC_wire", json={"deep_requested": True})
     return resp, calls
 
 
-def test_deep_request_schedules_immediate_backfill_for_non_demo(db, monkeypatch):
+def test_deep_request_schedules_immediate_backfill_for_non_demo(db, monkeypatch, override_dep):
     ch, me = _setup_channel_and_sub(db, email="wire@example.com")
-    resp, calls = _patch_deep_requested(db, monkeypatch, me)
+    resp, calls = _patch_deep_requested(db, monkeypatch, override_dep, me)
     assert resp.status_code == 200, resp.text
     assert resp.json()["deep_requested"] is True
     # scheduled exactly once, with (channel_id, user_id) — the args backfill_channel_now needs.
     assert calls == [(ch.id, me.id)]
 
 
-def test_deep_request_does_not_schedule_immediate_backfill_for_demo(db, monkeypatch):
+def test_deep_request_does_not_schedule_immediate_backfill_for_demo(db, monkeypatch, override_dep):
     # The SHARED demo account must not be able to kick immediate full backfills (budget drain).
     _ch, demo = _setup_channel_and_sub(db, email="demo@example.com", is_demo=True)
-    resp, calls = _patch_deep_requested(db, monkeypatch, demo)
+    resp, calls = _patch_deep_requested(db, monkeypatch, override_dep, demo)
     assert resp.status_code == 200, resp.text
     assert calls == [], "demo must not schedule an immediate backfill"
     # …and deep_requested is not persisted on the shared demo subscription either.

backend/tests/test_channel_subscribe_upstream.py

@@ -0,0 +1,69 @@
+"""Subscribing when YouTube says no — and when "no" means "you already are".
+
+The error no longer carries YouTube's body (it is the request quoted back, and it went into a log
+line and a 422), so "already following" is recognised by the reason code and nothing else.
+DB lane.
+"""
+
+import pytest
+from fastapi import HTTPException
+from sqlalchemy import select
+
+from app.models import Channel, Subscription
+from app.routes import channels
+from app.youtube.client import YouTubeError
+
+
+def _youtube_refusing(reason: str):
+    class _Client:
+        def __init__(self, db, user):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *exc):
+            return False
+
+        def insert_subscription(self, channel_id):
+            raise YouTubeError(f"POST subscriptions -> 400: {reason}", reason=reason)
+
+        def get_channels(self, ids):
+            return []
+
+    return _Client
+
+
+@pytest.fixture
+def stub_channel(db):
+    db.add(Channel(id="UCdup", title="Already followed"))
+    db.commit()
+    return "UCdup"
+
+
+@pytest.mark.parametrize("reason", ["subscriptionDuplicate", "quotaExceeded,subscriptionDuplicate"])
+def test_already_following_on_youtube_is_recorded_not_refused(
+    db, make_user, monkeypatch, stub_channel, reason
+):
+    user = make_user()
+    monkeypatch.setattr(channels, "YouTubeClient", _youtube_refusing(reason))
+
+    channels.subscribe(stub_channel, user=user, db=db)
+
+    sub = db.execute(
+        select(Subscription).where(
+            Subscription.user_id == user.id, Subscription.channel_id == stub_channel
+        )
+    ).scalar_one()
+    assert sub is not None
+
+
+@pytest.mark.parametrize("reason", ["quotaExceeded", "<none>", "<unparseable>"])
+def test_any_other_refusal_is_answered_with_a_422(db, make_user, monkeypatch, stub_channel, reason):
+    user = make_user()
+    monkeypatch.setattr(channels, "YouTubeClient", _youtube_refusing(reason))
+
+    with pytest.raises(HTTPException) as caught:
+        channels.subscribe(stub_channel, user=user, db=db)
+
+    assert caught.value.status_code == 422

backend/tests/test_channel_tags.py

@@ -17,7 +17,7 @@ from app.main import app
 from app.models import Channel, ChannelTag, Tag, User
 
 
-def test_channel_detail_returns_only_this_users_tag_ids(db, monkeypatch):
+def test_channel_detail_returns_only_this_users_tag_ids(db, monkeypatch, override_dep):
     # published_at set so channel_detail skips the YouTube-enrich path (no quota / network in tests).
     ch = Channel(
         id="UC_tags_test",
@@ -43,13 +43,10 @@ def test_channel_detail_returns_only_this_users_tag_ids(db, monkeypatch):
 
     # The request gate 503s an unconfigured instance; flip the process-level flag (auto-restored).
     monkeypatch.setattr(state, "_configured_cache", True)
-    app.dependency_overrides[get_db] = lambda: db
-    app.dependency_overrides[current_user] = lambda: me
-    try:
-        client = TestClient(app)  # no context-manager: skip lifespan (scheduler/HLS sweep)
-        resp = client.get(f"/api/channels/{ch.id}")
-    finally:
-        app.dependency_overrides.clear()
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: me)
+    client = TestClient(app)  # no context-manager: skip lifespan (scheduler/HLS sweep)
+    resp = client.get(f"/api/channels/{ch.id}")
 
     assert resp.status_code == 200, resp.text
     assert resp.json()["tag_ids"] == [mine.id]

backend/tests/test_discover.py

@@ -544,6 +544,73 @@ def test_shelf_resolves_a_playlist_to_its_first_unwatched_item(db):
     assert card["next"]["id"] == "vmed"
 
 
+def _count_statements(db, fn) -> int:
+    """How many SQL statements `fn` sends through the session's connection."""
+    from sqlalchemy import event
+
+    seen: list[str] = []
+    engine = db.get_bind()
+    listener = lambda *a, **k: seen.append(a[2])  # noqa: E731 — (conn, cursor, statement, …)
+    event.listen(engine, "before_cursor_execute", listener)
+    try:
+        fn()
+    finally:
+        event.remove(engine, "before_cursor_execute", listener)
+    return len(seen)
+
+
+def test_the_shelf_resolves_each_channel_and_playlist_on_its_own_terms(db):
+    """Batched, the per-channel count and newest video come from one windowed query: each channel
+    must still get ITS count and ITS newest, not the shelf's overall first row."""
+    user, ch = _seed_yt(db)
+    other = Channel(id="UCother", title="Other")
+    db.add(other)
+    db.flush()
+    db.add(Video(id="vother", channel_id=other.id, title="x", published_at=NOW - timedelta(days=9)))
+    pl = Playlist(user_id=user.id, name="Két elem")
+    empty = Playlist(user_id=user.id, name="Üres")
+    db.add_all([pl, empty])
+    db.flush()
+    db.add(PlaylistItem(playlist_id=pl.id, video_id="vlong", position=0))
+    for i, target in enumerate(
+        [
+            {"channel_id": ch.id},
+            {"channel_id": other.id},
+            {"playlist_id": pl.id},
+            {"playlist_id": empty.id},
+        ]
+    ):
+        db.add(ComfortPin(user_id=user.id, position=i, **target))
+    db.commit()
+
+    got = [
+        (c.get("unwatched_count", c.get("item_count")), (c["next"] or {}).get("id"))
+        for c in pins.shelf(db, user)
+    ]
+    assert got == [(3, "vshort"), (1, "vother"), (1, "vlong"), (0, None)]
+
+
+def test_the_shelf_costs_the_same_queries_for_one_pin_or_many(db):
+    """A channel pin used to cost three queries and a playlist pin two, each; the shelf now
+    resolves every channel and every playlist together."""
+    user, ch = _seed_yt(db)
+    extra = [Channel(id=f"UCx{i}", title=f"x{i}") for i in range(3)]
+    lists = [Playlist(user_id=user.id, name=f"p{i}") for i in range(4)]
+    db.add_all(extra + lists)
+    db.flush()
+    db.add(ComfortPin(user_id=user.id, channel_id=ch.id, position=0))
+    db.add(ComfortPin(user_id=user.id, playlist_id=lists[0].id, position=1))
+    db.commit()
+    few = _count_statements(db, lambda: pins.shelf(db, user))
+
+    for i, c in enumerate(extra):
+        db.add(ComfortPin(user_id=user.id, channel_id=c.id, position=10 + i))
+    for i, p in enumerate(lists[1:]):
+        db.add(ComfortPin(user_id=user.id, playlist_id=p.id, position=20 + i))
+    db.commit()
+    assert _count_statements(db, lambda: pins.shelf(db, user)) == few
+
+
 def test_a_pinned_video_survives_leaving_the_feed_scope(db):
     """The shelf is the fallback surface. An entry silently vanishing because the user unsubscribed
     from the channel is exactly the failure it must not have."""
@@ -940,3 +1007,115 @@ def test_deleting_a_pin_reports_what_went(db, as_user):
     r = c.delete(f"/api/discover/pins/{pin_id}")
     assert r.status_code == 200 and r.json() == {"deleted": pin_id}
     assert c.get("/api/discover/pins").json()["items"] == []
+
+
+def test_with_plex_off_the_home_shelf_hides_plex_pins_but_keeps_them(db, as_user):
+    """The owner's call (2026-09-19): with the deployment's Plex toggle off, the Home shelf goes
+    YouTube-only like the rails beside it — a Plex tile there offered a Play that landed on a gated
+    module. The hero's comfort tier draws from the same filtered shelf, and the pin menus' own
+    listing still sees every pin, so nothing the user curated is lost."""
+    user, _ = _seed_yt(db)
+    _seed_plex(db, user)
+    db.add_all(
+        [
+            ComfortPin(
+                user_id=user.id,
+                plex_item_id=db.scalar(select(PlexItem.id).where(PlexItem.rating_key == "pm1")),
+                position=0,
+            ),
+            ComfortPin(user_id=user.id, video_id="vlong", position=1),
+        ]
+    )
+    db.commit()
+    c = as_user(user)
+    assert [t["id"] for t in c.get("/api/discover").json()["comfort"]] == ["vlong"]
+    assert c.get("/api/discover/pick?start=1").json()["hero"]["card"]["id"] == "vlong"
+    assert {t["id"] for t in c.get("/api/discover/pins").json()["items"]} == {"pm1", "vlong"}
+    _enable_plex(db)
+    assert [t["id"] for t in c.get("/api/discover").json()["comfort"]] == ["pm1", "vlong"]
+
+
+def test_a_reorder_of_the_visible_pins_keeps_the_hidden_ones_in_place(db, as_user):
+    """The client sends the order it SHOWS. With Plex off that leaves the Plex pins out, and
+    numbering only the listed ids 0..n-1 put two pins on one position and moved the hidden one about
+    when Plex came back. The listed pins trade the slots they hold; the rest stay put."""
+    user, ch = _seed_yt(db)
+    _seed_plex(db, user)
+    c = as_user(user)
+    _enable_plex(db)
+    a = c.post("/api/discover/pins", json={"kind": "video", "ref": "vmed"}).json()["id"]
+    hidden = c.post("/api/discover/pins", json={"kind": "plex_item", "ref": "pm1"}).json()["id"]
+    b = c.post("/api/discover/pins", json={"kind": "channel", "ref": ch.id}).json()["id"]
+    assert c.post("/api/discover/pins/reorder", json={"ids": [b, b, a]}).status_code == 200
+    assert [p["pin_id"] for p in c.get("/api/discover/pins").json()["items"]] == [b, hidden, a]
+    positions = db.scalars(select(ComfortPin.position).where(ComfortPin.user_id == user.id)).all()
+    assert sorted(positions) == [0, 1, 2]
+
+
+def test_a_hero_from_a_show_pin_names_the_pin_it_came_from(db, as_user):
+    """A show's next EPISODE is not itself pinned, so the hero's menu used to look the episode up,
+    miss, and offer "Pin" under "From your shelf" — creating a second pin. The card now carries
+    the pin it was resolved from, which the menu acts on (owner's call: "Unpin")."""
+    user, _ = _seed_yt(db)
+    _seed_plex(db, user)
+    _enable_plex(db)
+    c = as_user(user)
+    assert c.post("/api/discover/pins", json={"kind": "plex_show", "ref": "ps1"}).status_code == 200
+    got = c.get("/api/discover/pick?start=1").json()["hero"]
+    assert got["tier"] == "comfort" and got["card"]["id"] == "ps1e1"
+    assert got["card"]["pinned_from"] == {
+        "source": "plex",
+        "kind": "show",
+        "id": "ps1",
+        "title": "A Show",
+    }
+
+
+def test_two_overlapping_reorders_never_share_a_slot(db, as_user):
+    """`reorder` writes only the rows that change. Unlocked, two tabs reordering from the same
+    snapshot each skipped the rows that already matched in THEIR snapshot and interleaved row by
+    row — two pins on one slot (deep review, debt burn). Locked, the second waits for the first and
+    deals from its result: here a partial list (a tab with Plex off, one pin hidden), whose left-out
+    pin must stay where the FIRST reorder put it — a lock taken in position order handed the waiter
+    fresh rows in its stale order, and it dealt that pin back to its old slot (round 2)."""
+    import threading
+
+    from app.db import SessionLocal
+
+    user, ch = _seed_yt(db)
+    c = as_user(user)
+    p1 = c.post("/api/discover/pins", json={"kind": "video", "ref": "vmed"}).json()["id"]
+    p2 = c.post("/api/discover/pins", json={"kind": "channel", "ref": ch.id}).json()["id"]
+    p3 = c.post("/api/discover/pins", json={"kind": "video", "ref": "vlong"}).json()["id"]
+    uid = user.id
+
+    with SessionLocal() as tab_a, SessionLocal() as tab_b, SessionLocal() as probe:
+        pins.reorder(tab_a, tab_a.get(User, uid), [p2, p3, p1])  # written, not yet committed
+        errors: list[BaseException] = []
+
+        def second_tab():
+            try:
+                pins.reorder(tab_b, tab_b.get(User, uid), [p3, p2])
+                tab_b.commit()
+            except BaseException as exc:  # noqa: BLE001 — re-raised in the test thread below
+                errors.append(exc)
+
+        worker = threading.Thread(target=second_tab)
+        worker.start()
+        # Commit A only once B is blocked on a row lock, so B's read is the stale snapshot.
+        waiting = 0
+        for _ in range(200):
+            waiting = probe.scalar(text("SELECT count(*) FROM pg_locks WHERE NOT granted"))
+            probe.rollback()
+            if waiting:
+                break
+            worker.join(0.05)
+        assert waiting, "tab B never blocked — the race was not exercised"
+        tab_a.commit()
+        worker.join(10)
+        assert not worker.is_alive() and errors == []
+
+    db.expire_all()
+    positions = db.scalars(select(ComfortPin.position).where(ComfortPin.user_id == uid)).all()
+    assert sorted(positions) == [0, 1, 2]
+    assert [p["pin_id"] for p in c.get("/api/discover/pins").json()["items"]] == [p3, p2, p1]