release: 0.103.0 (bug/yt-fullscreen-button)

Rows that just mounted join the menu's navigation list a render after the status effect ran: a row
focused that early was unknown to it, and the arrows did nothing from it (seen live after a keyboard
Retry). The retry test now arrows on from the row it lands on.

.dockerignore

@@ -4,6 +4,7 @@
 *.env.local
 **/__pycache__/
 **/*.pyc
+**/.coverage
 .venv/
 venv/
 # Docker patterns are anchored at the context root with NO implicit `**/` (unlike .gitignore, where

.env.example

@@ -28,6 +28,14 @@ ALLOWED_EMAILS=
 # Admin emails (subset of the above) get the admin role.
 ADMIN_EMAILS=
 
+# Logging. LOG_LEVEL is the BOOTSTRAP level — the level a process starts at and the only one
+# the worker/download child read; the API's running level is the admin Configuration page's
+# `log_level` knob, which takes effect without a restart. TRACE | DEBUG | INFO | WARNING | ERROR, in
+# any letter case; any other value stops the boot with an error. LOG_FORMAT is "json" (one object per
+# line — what a log collector ingests) or "text" (a readable line for a local terminal).
+LOG_LEVEL=INFO
+LOG_FORMAT=json
+
 # Optional: origin of a separately-served frontend dev server (enables CORS). Leave empty in production.
 FRONTEND_ORIGIN=
 

.git-blame-ignore-revs

@@ -2,8 +2,11 @@
 # whole-repo reformatting does not bury the real authorship of each line.
 # Configure once per clone:  git config blame.ignoreRevsFile .git-blame-ignore-revs
 #
-# Prettier one-time repo-wide format pass (R2 S1b, 2026-07-21)
+# Prettier one-time repo-wide format pass (2026-07-21)
 51c36c2071728d2cd7ae580b7bfdf21f6867a347
 
 # ruff format one-time backend + scripts pass (line-length 100, 2026-08-23)
 b1832afd180866b922521148603db447020c57a4
+
+# Plan-code purge from comments, one-time (2026-10-04)
+4aaaaa786017278460e0b4f94cc0d3374e0e37e2

.gitea/workflows/check.yml

@@ -1,71 +0,0 @@
-# Server-side mirror of the local `siftlode check` gate (E1 S3 / DX-1), so `main` is always green
-# independent of any one machine. Two parallel jobs match the two local lanes:
-#   frontend — tsc (3 projects) + eslint + prettier --check + knip + vitest
-#   backend  — ruff + the full pytest suite (pure-logic + the DB-backed lane) against a real Postgres
-#
-# Runner: the lab act_runner (LXC 115) mounts the Docker socket, so service containers work. The backend
-# runs pytest NATIVELY against a `postgres` service (not the local docker-compose.test.yml, whose
-# bind-mount is unreliable under a mounted-socket runner); fidelity is kept by installing the SAME pinned
-# requirements, Postgres 16, and ffmpeg, and by setting SIFTLODE_TEST_REQUIRE_DB=1 so a DB/ffmpeg that
-# failed to come up is a hard error, never a silent skip. node 22 matches the prod build image
-# (Dockerfile `node:22-alpine`).
-name: gate
-
-on: [push, pull_request]
-
-jobs:
-  frontend:
-    runs-on: ubuntu-latest
-    container: node:22-bookworm
-    defaults:
-      run:
-        working-directory: frontend
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm ci
-      - run: npm run typecheck
-      - run: npm run lint
-      - run: npm run format:check
-      - run: npm run knip
-      - run: npm run test
-
-  backend:
-    runs-on: ubuntu-latest
-    # A combined python+node image: python 3.12 (matches the prod Dockerfile) for the tests, and node
-    # so the JS actions (checkout) run. actions/setup-python is NOT usable here — the runner can't reach
-    # GitHub's python-versions download, so it must be baked into the image.
-    container: nikolaik/python-nodejs:python3.12-nodejs20
-    services:
-      postgres:
-        image: postgres:16-alpine
-        env:
-          POSTGRES_USER: siftlode
-          POSTGRES_PASSWORD: siftlode
-          POSTGRES_DB: siftlode_test
-        options: >-
-          --health-cmd "pg_isready -U siftlode -d siftlode_test"
-          --health-interval 2s
-          --health-timeout 3s
-          --health-retries 30
-    env:
-      DATABASE_URL: postgresql+psycopg://siftlode:siftlode@postgres:5432/siftlode_test
-      SIFTLODE_TEST_REQUIRE_DB: "1"
-    steps:
-      - uses: actions/checkout@v4
-      # ffmpeg for the poster/thumbnail tests; postgresql-client for the readiness wait below.
-      - run: apt-get update && apt-get install -y --no-install-recommends ffmpeg postgresql-client
-      - name: Wait for Postgres
-        run: until pg_isready -h postgres -U siftlode -d siftlode_test; do sleep 1; done
-      - run: pip install --no-cache-dir -r backend/requirements.lock -r backend/requirements-dev.txt
-      - name: ruff
-        run: python -m ruff check --config backend/ruff.toml backend scripts
-      - name: ruff format --check
-        run: python -m ruff format --check --config backend/ruff.toml backend scripts
-      - name: pytest
-        run: python -m pytest
-        working-directory: backend
-      # Dependency CVE audit over the pinned lock. Non-blocking for now (informational) — a real CVE
-      # shows up in the run without failing the gate; tighten to a hard fail once the noise is known.
-      - name: pip-audit (advisory)
-        run: pip install --no-cache-dir pip-audit && pip-audit -r backend/requirements.lock
-        continue-on-error: true

.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 venv/
 .mypy_cache/
 .pytest_cache/
+.coverage
 .ruff_cache/
 
 # Node / frontend
@@ -37,3 +38,8 @@ backups/
 Thumbs.db
 .idea/
 .vscode/
+
+# TypeScript incremental build artifacts — machine-local, absolute-path-bearing, and no gate lane
+# reads or regenerates them, so a committed one is stale from the commit that adds it.
+*.tsbuildinfo
+frontend/e2e/.speed/

.nvmrc

@@ -0,0 +1 @@
+24

.python-version

@@ -0,0 +1 @@
+3.12

.trivyignore.yaml

@@ -0,0 +1,15 @@
+# The CVE gate's allowlist. The publish gate scans the built image and the committed tree with
+# Trivy and fails on any HIGH or CRITICAL finding that has a fix available. A finding that cannot be
+# fixed yet is let through ONLY by an entry here, and every entry carries both:
+#   statement   — why it is acceptable for now (what is exposed, what is not)
+#   expired_at  — the date it stops being accepted; after it, the gate fails again on its own
+# A contract test (frontend/src/lib/gates.contract.test.ts) refuses an entry without either, and
+# docs/gates.md lists them.
+#
+# Example:
+#   vulnerabilities:
+#     - id: CVE-2026-00000
+#       statement: in libfoo's XML path, which nothing in the image calls; no fixed Debian build yet
+#       expired_at: 2026-12-31
+vulnerabilities: []
+secrets: []

CLAUDE.md

@@ -7,17 +7,21 @@ worse than no rule — if you change how the code works, change this file in the
 
 Siftlode is a self-hosted YouTube reader (+ a local Plex browser/player and a download center). It is a
 **modular monolith**: one Postgres, one FastAPI process (uvicorn + APScheduler), one worker process
-(yt-dlp/ffmpeg), one PO-token sidecar. React 18 + react-query frontend with a router-free navigation
-provider.
+(yt-dlp/ffmpeg), one PO-token sidecar. React 19 (with the React Compiler) + react-query frontend, with a
+router-free navigation provider.
 
 ## The gate — never merge or ship red
 
-The local gate is **ruff (`check` + `format --check`) + typecheck (3 tsc projects) + eslint + prettier
---check + knip + vitest + pytest**. It runs on every `publish`, which **refuses to build on failure — there is deliberately no
-`--skip` flag.** Run it and get it green **before** any merge, release, or handing work to review.
+The local gate is **ruff (`check` + `format --check`) + basedpyright (backend) + the lock check + typecheck (3 tsc projects) +
+eslint + prettier --check + knip + vitest + vite build + pytest + pip-audit + npm audit**. It runs
+before every `release` merges and on every `publish`, which **refuses to build on failure — there is deliberately no `--skip`
+flag**; a release also requires the Playwright suite, and the image must pass a Trivy scan before it is pushed. Run it and get it
+green **before** any merge, release, or handing work to review.
 
-- Full gate (agents with the private ops dispatcher): `siftlode check`.
-- Directly, without the dispatcher: `cd frontend && npm run typecheck && npm run lint && npm run knip && npm run test`, plus backend `ruff check backend` + `ruff format --check backend` and `pytest` (the DB-lane needs Postgres).
+- Full gate: `bash scripts/check.sh` (`lint` for the static lanes only); the private ops dispatcher's `siftlode check` runs the same script. Single lanes: [`docs/development.md`](docs/development.md) § The gate.
+- **There is no CI** (owner, 2026-10-04): this gate, run here, is the only one — green before every hand-over, and `release` refuses to merge without it.
+- **A gate with any real hit is never switched off or narrowed** — not a lint rule, a compiler flag, a lane or a release step. Fix the sites, or suppress each one inline naming its invariant (`-- why`, lint-enforced). What stays narrowed is in [`docs/gates.md`](docs/gates.md), and a contract test fails when a narrowing is missing from it. The effective ESLint config of every scope and the gate/lane lines are pinned in `frontend/src/lib/gates.snapshot.json`: any gate change fails until you regenerate it (`GATE_SNAPSHOT=update`, see gates.md) — then read that diff as a gate change. A comment saying "X is enforced by Y" is checked by running Y (E32: one such comment hid 95 functions the React Compiler skipped).
+- **The backend type lane runs in the test image, not on the host** — `requirements.lock` cannot be installed on Windows (uvloop), and a type checker without the real packages reports nonsense. It fails on NEW errors only; the pre-existing ones sit in `backend/.basedpyright/baseline.json` (no burn-down mandate, but none was ever triaged: a `reportOptional*` entry in code you touch may be a real bug). A run that fixed some rewrites it — commit that.
 - New DB-backed test? It must actually run, not silently skip — assume `SIFTLODE_TEST_REQUIRE_DB=1`.
 
 ## Workflow
@@ -45,21 +49,24 @@ how it gets built. Concretely:
   behind each option and the weight of the decision. These decision points are where the product owner
   engages with the build and learns from it, so make them understandable — a reasoned menu, not a bare one.
 - **Mockups for design/UX decisions.** For any visual or interaction choice, show mockup options to
-  choose from before building.
+  choose from before building. How the UI looks and behaves is decided in
+  [`docs/DESIGN.md`](docs/DESIGN.md) (its variants render in the dev-only `/design-lab`): build to it,
+  and change it only through its decision log.
 - **Challenge unsound requests.** If a request is technically ill-advised and you can back it with real
   arguments, push back or propose an alternative — don't comply blindly.
 - **Verify UI in the browser before calling it done.** tsc/unit/DOM tests miss visual and interaction
-  bugs; do a real visual check of any UI change.
+  bugs; do a real visual check of any UI change, and run DESIGN.md's four-step Conformance check.
 - **Be terse everywhere else.** Outside those decision points, lead with the answer or decision. During
   implementation and debugging especially: no restating the same point reworded, no filler.
 
 ## Architecture shape (don't fight it)
 
 `routes/*` (HTTP only: validation, auth-dependency, serialization) → domain packages `sync/`, `plex/`,
-`downloads/`, `youtube/` (shared by routes + scheduler + worker) → flat core (`auth`, `quota`,
-`sysconfig`, `state`, `audit`, `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`,
-`security`) → `models/db/config`. **Dependency direction is one-way: core never imports routes.**
-Frontend: `main.tsx` provider tree → `App.tsx` shell → `moduleRegistry` route-chunks → module
+`downloads/`, `youtube/`, `issues/` (shared by routes + scheduler + worker) → flat core (`auth`, `quota`,
+`sysconfig`, `state`, `audit`, `notifications`, `userscope`, `ratelimit`, `bodylimit`, `progress`, `collation`,
+`security`, `logs`, `logsink`, `diagnostics`, `debugsession`) → `models/db/config`. **Dependency direction is one-way: core never imports routes.**
+Frontend: `main.tsx` provider tree → `App.tsx` shell (a shared `/watch` link boots from its own
+entry, `watch.html` → `watchMain.tsx`, held app-free by a contract test) → `moduleRegistry` route-chunks → module
 components → the **platform layer `components/ui/`** (domain-free primitives: the popover engine and
 its menus, `Modal`/`Overlay`, `Button`/`form`, `DataTable`/`VirtualGrid`, `QueryState`, …). That
 boundary is one-way and **lint-enforced**, not just described: a platform component may not import a
@@ -74,27 +81,40 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 
 ## Canonical patterns — when you have a choice, pick THIS
 
-| Area                    | Use                                                          | Not                                                    |
-| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------ |
-| ORM                     | SQLAlchemy 2.0 `select()`                                    | `db.query(...)`                                        |
-| Request body            | a Pydantic model                                             | `payload: dict`                                        |
-| Ownership check         | `owned_or_404` / `get_or_404`                                | ad-hoc `_own_playlist`/`_owned`/`_own_job`             |
-| 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)    |
-| 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                           |
-| FE per-account state    | `usePref`                                                    | raw `readAccount`/`writeAccount` or bespoke hooks      |
-| FE action button        | `ui/Button` — pick a `SIZES` rung                            | a hand-rolled `<button className="px-3 py-2 …">`       |
-| 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 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 |
+| Area                                 | Use                                                                                                                                                                                               | Not                                                                                                                                                     |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ORM                                  | SQLAlchemy 2.0 `select()`                                                                                                                                                                         | `db.query(...)`                                                                                                                                         |
+| Request body                         | a Pydantic model                                                                                                                                                                                  | `payload: dict`                                                                                                                                         |
+| Request SIZE                         | nothing — `bodylimit` caps every route (SEC-20); need more? add a ceiling to `ROUTE_MAX_BODY_BYTES`                                                                                               | `capped_body` on a route that does not read raw bytes itself                                                                                            |
+| Ownership check                      | `owned_or_404` / `get_or_404`                                                                                                                                                                     | ad-hoc `_own_playlist`/`_owned`/`_own_job`                                                                                                              |
+| 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}`), 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                                                                                                                            |
+| FE per-account state                 | `usePref`                                                                                                                                                                                         | raw `readAccount`/`writeAccount` or bespoke hooks                                                                                                       |
+| 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 static label / button-like link   | `Badge` (flat, no edge) · `LinkButton` / `IconLink`                                                                                                                                               | a glass pill that reads as a chip; an `<a>` hand-painted like a button                                                                                  |
+| 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 player on a native media element  | `lib/mediaSession` (`useMediaSession`) + `lib/mediaKeys` + `lib/resume` (`useResume`), the element held as STATE                                                                                  | a private `navigator.mediaSession` / `keydown` / position-saving effect per player                                                                      |
+| FE diagnostics                       | `lib/log.ts` (`log.info("event.code", msg, attrs)`); a filter change → `lib/filterLog.ts`, a player → `lib/mediaLog.ts`                                                                           | `console.*` (lint-enforced); a value only a higher level may carry, logged unguarded                                                                    |
+| FE state that MIRRORS a prop/query   | derive it, or hold a draft (`draft ?? server`)                                                                                                                                                    | a copy an effect re-syncs — that paints the stale value first                                                                                           |
+| FE state reset on a key change       | adjust it DURING render against a remembered key                                                                                                                                                  | `useEffect(() => setX(init), [key])`                                                                                                                    |
+| FE effect that must not re-subscribe | `useEffectEvent` (React 19.2+); a handler or timer: `useLatest` / `useStableCallback`                                                                                                             | a render-phase `ref.current = x` — the React Compiler skips the component                                                                               |
+| FE hook suppression                  | an inline `eslint-disable-next-line` NAMING the invariant                                                                                                                                         | `eslint-suppressions.json` (deliberately absent — E27 S2)                                                                                               |
+| FE popover / scroll-fade ref         | destructure it: `const { setReference } = pop.refs`, then `ref={setReference}`                                                                                                                    | `ref={pop.refs.setReference}` / `ref={fade.ref}` — the compiler then treats the whole object as a ref and skips                                         |
+| FE async handler with cleanup        | `try { … } catch { … }`, then the cleanup after it (steps that `return` early go in their own function); a conditional, loop or `?.` the `try` needs goes before it or into a module-level helper | `try/finally`, or a `?:` / `??` / loop / `?.` inside `try` — the React Compiler skips the whole component (and `react-hooks/todo` misses most of these) |
+
+Not repeated here, because a lint rule refuses the wrong one and its message names the right one:
+buttons (`ui/Button`, `IconButton`, `Pressable`, `Chip`, `DragHandle`), text fields and native
+controls (`ui/Input`, `Checkbox`, `Slider`, …), glass surfaces (`SURFACE.*`), a native `<select>`
+(`SegmentedToggle` / `FilterSelect`), and network calls (`req` / `uploadReq` / `beacon`, `lib/http.ts`).
 
 ## House rules that bite (learned from real bugs)
 
@@ -107,7 +127,8 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
   "no results". Reads degrade honestly; writes are conditional (`UPDATE … WHERE status='running'`).
 - **i18n parity.** HU/EN, zero key drift. Every user-facing string is translated.
 - **Comment the "why", keep it current.** This codebase uses comments as its architecture doc; a stale
-  "why" is a liability, so update it when the behavior changes.
+  "why" is a liability, so update it when the behavior changes. Say the why itself, never the plan
+  step that produced it: no epic, sprint or review-round ids in the code (`planCodes.contract.test.ts`).
 
 ---
 

Dockerfile

@@ -10,7 +10,9 @@ ARG GIT_SHA=unknown
 ARG BUILD_DATE=
 
 # Stage 1: build the frontend SPA
-FROM node:22-alpine AS frontend
+# The major is pinned to `.nvmrc` and held there by frontend/src/lib/nodeEngine.contract.test.ts:
+# this image and the dev machine the gate runs on must be ONE engine (see that test for why).
+FROM node:24-alpine AS frontend
 WORKDIR /fe
 # Deps first, keyed on the lockfile, so editing app source never re-resolves node_modules.
 COPY frontend/package.json frontend/package-lock.json ./
@@ -45,14 +47,17 @@ RUN adduser --disabled-password --gecos "" appuser \
     && mkdir -p /downloads \
     && chown appuser /app /downloads
 
-# ffmpeg: merge separate video+audio streams + postprocessing, and the Plex VAAPI transcode (E6 S1).
+# ffmpeg: merge separate video+audio streams + postprocessing, and the Plex VAAPI transcode.
 # intel-media-va-driver (iHD): the VA driver ffmpeg's h264_vaapi needs — libva2 ships in the base but
 # no driver, so without this `vainfo`/`h264_vaapi` fail and transcode silently falls back to libx264.
 # Harmless on hosts with no /dev/dri (the driver just goes unused). Deno: the JavaScript runtime yt-dlp
 # uses to solve YouTube's "n" signature challenge for the web player clients (required alongside the PO
 # token, else only storyboards are offered). yt-dlp auto-detects deno on PATH.
+# `apt-get upgrade`: the base image is a snapshot, and the Debian security fixes released since it
+# was cut are only in the archive — the first Trivy scan found one (pcre2) fixed upstream but not in it.
 ARG DENO_VERSION=v2.9.1
 RUN apt-get update \
+    && apt-get upgrade -y --no-install-recommends \
     && apt-get install -y --no-install-recommends ffmpeg intel-media-va-driver unzip curl ca-certificates \
     && curl -fsSL "https://github.com/denoland/deno/releases/download/${DENO_VERSION}/deno-x86_64-unknown-linux-gnu.zip" -o /tmp/deno.zip \
     && unzip -o /tmp/deno.zip -d /usr/local/bin \
@@ -74,11 +79,14 @@ RUN printf 'Types: deb\nURIs: http://deb.debian.org/debian\nSuites: bookworm\nCo
     && rm -rf /var/lib/apt/lists/*
 
 # Install from the PINNED lock (requirements.lock, generated from requirements.txt) so the image is
-# byte-reproducible and the exact versions are the ones pip-audit scanned in CI — not whatever floats
-# up from the floor ranges on build day. Regenerate the lock when requirements.txt changes (see its header).
+# byte-reproducible and the exact versions are the ones the gate's pip-audit scanned — not whatever
+# floats up from the floor ranges on build day. Regenerate the lock when requirements.txt changes (see its header).
+# pip itself is removed once it has installed the lock: nothing runs it at runtime, and it carries
+# its own VENDORED copies of urllib3, msgpack and setuptools, which Trivy reports as the image's own —
+# an attack surface and a CVE stream for a tool the running app never calls.
 COPY backend/requirements.lock .
 RUN --mount=type=cache,target=/root/.cache/pip \
-    pip install --upgrade pip && pip install -r requirements.lock
+    pip install --upgrade pip && pip install -r requirements.lock && pip uninstall -y pip
 
 COPY --chown=appuser backend/ .
 # Read at runtime by config.py as the app_version (a committed single source of truth).

README.md

@@ -23,8 +23,9 @@ blocker and SponsorBlock keep working.
 - **Playlists with two-way YouTube sync** — build them locally, keep them in sync in both directions.
 - **In-app player** with resume, plus keyboard/scroll controls.
 - **Download Center** — save videos to the server with yt-dlp in a Plex-friendly layout (format
-  presets, per-user storage quota), trim / crop / split & join them in a built-in editor, then save
-  to your device, share with another user, or hand out a public watch link.
+  presets, per-user storage quota), trim / crop / split & join them in a built-in editor, play them
+  where you left off, then save to your device, share with another user, or hand out a public watch
+  link.
 - **Plex library** *(optional)* — point Siftlode at your own Plex server to browse and play its
   movies and shows alongside your feed, with watch state kept in sync.
 - **Multi-user** with per-user private state, a shared catalog, and a fair daily API-quota guard.

VERSION

@@ -1 +1 @@
-0.85.0
+0.103.0

backend/Dockerfile

@@ -1,19 +0,0 @@
-FROM python:3.12-slim
-
-ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1 \
-    PIP_NO_CACHE_DIR=1 \
-    PIP_DISABLE_PIP_VERSION_CHECK=1
-
-WORKDIR /app
-
-COPY requirements.txt .
-RUN pip install -r requirements.txt
-
-COPY . .
-
-RUN adduser --disabled-password --gecos "" appuser && chown -R appuser /app
-USER appuser
-
-EXPOSE 8000
-CMD ["sh", "entrypoint.sh"]

backend/alembic.ini

@@ -1,6 +1,8 @@
 [alembic]
 script_location = alembic
 prepend_sys_path = .
+# Split the path list the way the OS does (alembic's legacy space/comma/colon split is deprecated).
+path_separator = os
 
 [loggers]
 keys = root,sqlalchemy,alembic

backend/alembic/env.py

@@ -1,17 +1,17 @@
-from logging.config import fileConfig
-
 from alembic import context
 from sqlalchemy import engine_from_config, pool
 
 from app.config import settings
 from app.db import Base
+from app.logs import configure_logging
 import app.models  # noqa: F401  (import so models register on Base.metadata)
 
 config = context.config
 config.set_main_option("sqlalchemy.url", settings.database_url)
 
-if config.config_file_name is not None:
-    fileConfig(config.config_file_name)
+# Migrations run at container start (entrypoint.sh), so their output is part of the API's log
+# stream — one format with everything else, not alembic.ini's own fileConfig shape.
+configure_logging("alembic")
 
 target_metadata = Base.metadata
 

backend/alembic/versions/0084_dl_job_error_detail.py

@@ -0,0 +1,41 @@
+"""add download_jobs.error_detail — the domain-specific entry of the failure catalog (E11.5 S1)
+
+Revision ID: 0084_dl_job_error_detail
+Revises: 0083_comfort_pins
+Create Date: 2026-09-13
+
+`error_code` is the generic category (it decides whether a Retry is offered). `error_detail` names
+the host-specific catalog entry `downloads.errors.classify` matched on top of it — `facebook.login_wall`
+and its siblings — so the UI can say what went wrong ON THAT SITE and what to do about it, instead of
+the category's generic sentence. Nullable: most failures have no host-specific entry.
+
+Backfill: a job's code is written once, at failure time, so a new rule never reaches the rows that
+failed before it. The one shape measured on prod (2026-09-13, jobs 9/66/75/145/156/157/182/256/257) is
+yt-dlp's `[facebook] <id>: Cannot parse data`, stored as `unknown`. Without a cookie that is Facebook's
+login wall. Whether a cookie was attached at the time is not recorded anywhere, so every old row gets
+the no-cookie entry — on prod no account had a Facebook cookie, so that is what they all were.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0084_dl_job_error_detail"
+down_revision: str | None = "0083_comfort_pins"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column("download_jobs", sa.Column("error_detail", sa.String(length=48), nullable=True))
+    op.execute(
+        sa.text(
+            "UPDATE download_jobs SET error_code = 'login_required', "
+            "error_detail = 'facebook.login_wall' "
+            "WHERE (error_code IS NULL OR error_code = 'unknown') "
+            "AND error ILIKE '%[facebook]%cannot parse data%'"
+        )
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("download_jobs", "error_detail")

backend/alembic/versions/0085_users_last_login_at.py

@@ -0,0 +1,26 @@
+"""add users.last_login_at — when the account last signed in (E22 S1)
+
+Revision ID: 0085_users_last_login_at
+Revises: 0084_dl_job_error_detail
+Create Date: 2026-09-16
+
+Stamped by the one sign-in path (`routes/auth._establish_session`), which the Google callback and
+password login share. No backfill is possible: the signal exists only at sign-in, so existing rows
+read NULL until each account signs in again, and the admin UI says so rather than inventing a date.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0085_users_last_login_at"
+down_revision: str | None = "0084_dl_job_error_detail"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("last_login_at", sa.DateTime(timezone=True), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("users", "last_login_at")

backend/alembic/versions/0086_log_events.py

@@ -0,0 +1,48 @@
+"""add log_events — stored log events for diagnostics (E22 S3)
+
+Revision ID: 0086_log_events
+Revises: 0085_users_last_login_at
+Create Date: 2026-09-17
+
+Written by app/logsink.py's background writer (WARNING and above, request lines), pruned by the log_gc
+job after `log_retention_days`. Sized against prod on 2026-09-16: ~2k rows on a normal day, ~14k on a
+YouTube-RSS-outage day before flood control — a few MB over the 7-day window. `user_id` carries no
+foreign key on purpose (see models.LogEvent).
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0086_log_events"
+down_revision: str | None = "0085_users_last_login_at"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "log_events",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column("ts", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("level", sa.String(10), nullable=False),
+        sa.Column("sev", sa.SmallInteger(), nullable=False),
+        sa.Column("source", sa.String(16), nullable=False),
+        sa.Column("logger", sa.String(128), nullable=False),
+        sa.Column("event", sa.String(64), nullable=True),
+        sa.Column("msg", sa.Text(), nullable=False),
+        sa.Column("attrs", postgresql.JSONB(), nullable=True),
+        sa.Column("exc", sa.Text(), nullable=True),
+        sa.Column("request_id", sa.String(64), nullable=True),
+        sa.Column("user_id", sa.Integer(), nullable=True),
+        sa.Column("debug_session_id", sa.String(64), nullable=True),
+        sa.Column("job_id", sa.Integer(), nullable=True),
+        sa.Column("version", sa.String(64), nullable=True),
+    )
+    op.create_index("ix_log_events_ts", "log_events", ["ts"])
+    op.create_index("ix_log_events_request_id", "log_events", ["request_id"])
+    op.create_index("ix_log_events_user_ts", "log_events", ["user_id", "ts"])
+
+
+def downgrade() -> None:
+    op.drop_table("log_events")

backend/alembic/versions/0087_users_diagnostics_level.py

@@ -0,0 +1,31 @@
+"""add users.diagnostics_level + diagnostics_until — a user's consented diagnostics level (E22 S5)
+
+Revision ID: 0087_users_diagnostics_level
+Revises: 0086_log_events
+Create Date: 2026-09-17
+
+Both NULL = the base level (Alap). A raised level is ALWAYS paired with its expiry, computed by the
+server at consent time (`app/diagnostics.py`), so no client can ask for a level that never ends.
+Columns rather than `users.preferences`: that JSON is written wholesale by the client, and a consent
+with a lifetime must not be something a client can write.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0087_users_diagnostics_level"
+down_revision: str | None = "0086_log_events"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("diagnostics_level", sa.String(8), nullable=True))
+    op.add_column(
+        "users", sa.Column("diagnostics_until", sa.DateTime(timezone=True), nullable=True)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("users", "diagnostics_until")
+    op.drop_column("users", "diagnostics_level")

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/alembic/versions/0089_debug_sessions.py

@@ -0,0 +1,81 @@
+"""add debug_sessions + debug_screenshots, and index log_events.debug_session_id (E16)
+
+Revision ID: 0089_debug_sessions
+Revises: 0088_channels_feed_fallback_at
+Create Date: 2026-09-19
+
+A debug session is one recording: Start → reproduce → Stop (app/debugsession.py). Every log line
+of that user's requests while it runs carries its id in `log_events.debug_session_id` — the column
+E22 created and left NULL — and the issue it ends in is built from exactly those rows, so the column
+gets its index now. Partial: nearly every row has no session, and an index of NULLs would be most
+of the table for nothing.
+
+At most one OPEN session per user, held by a partial unique index rather than by the start handler
+alone: two tabs pressing Start at once would otherwise both pass a "none open" check.
+
+Screenshots are rows, not files: bounded (size and count per session, app/debugsession.py), gone
+with their session by cascade, and a self-host has no file volume to configure for them.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0089_debug_sessions"
+down_revision: str | None = "0088_channels_feed_fallback_at"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "debug_sessions",
+        sa.Column("id", sa.String(16), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer,
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+            index=True,
+        ),
+        sa.Column("level", sa.String(8), nullable=False),
+        sa.Column("started_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("until", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("ended_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("ended_reason", sa.String(16), nullable=True),
+        sa.Column("issue_url", sa.String(512), nullable=True),
+    )
+    op.create_index(
+        "uq_debug_sessions_open_per_user",
+        "debug_sessions",
+        ["user_id"],
+        unique=True,
+        postgresql_where=sa.text("ended_at IS NULL"),
+    )
+    op.create_table(
+        "debug_screenshots",
+        sa.Column("id", sa.Integer, primary_key=True),
+        sa.Column(
+            "session_id",
+            sa.String(16),
+            sa.ForeignKey("debug_sessions.id", ondelete="CASCADE"),
+            nullable=False,
+            index=True,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("mime", sa.String(16), nullable=False),
+        sa.Column("size", sa.Integer, nullable=False),
+        sa.Column("data", sa.LargeBinary, nullable=False),
+    )
+    op.create_index(
+        "ix_log_events_debug_session",
+        "log_events",
+        ["debug_session_id"],
+        postgresql_where=sa.text("debug_session_id IS NOT NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_log_events_debug_session", table_name="log_events")
+    op.drop_table("debug_screenshots")
+    op.drop_index("uq_debug_sessions_open_per_user", table_name="debug_sessions")
+    op.drop_table("debug_sessions")

backend/alembic/versions/0090_debug_session_draft.py

@@ -0,0 +1,27 @@
+"""add debug_sessions.draft — the issue being written from a session (E16 S3)
+
+Revision ID: 0090_debug_session_draft
+Revises: 0089_debug_sessions
+Create Date: 2026-09-19
+
+The composer saves as it goes: the title, the rendered markdown body that an export or an issue
+carries, the log rows the user took out, and the form's own fields so reopening it later (Settings →
+Diagnosztika lists past sessions) shows what was written. NULL until the composer first saves.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision: str = "0090_debug_session_draft"
+down_revision: str | None = "0089_debug_sessions"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column("debug_sessions", sa.Column("draft", JSONB, nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("debug_sessions", "draft")

backend/alembic/versions/0091_plex_tagline_hu.py

@@ -0,0 +1,27 @@
+"""add tagline_hu to plex_items + plex_shows — the HU overlay's tagline (E30 S1)
+
+Revision ID: 0091_plex_tagline_hu
+Revises: 0090_debug_session_draft
+Create Date: 2026-09-29
+
+The Hungarian overlay section lists a tagline beside the title and summary; the info page showed the
+English one to a Hungarian reader. NULL until the next overlay sync fills it (serving falls back to EN).
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0091_plex_tagline_hu"
+down_revision: str | None = "0090_debug_session_draft"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column("plex_items", sa.Column("tagline_hu", sa.Text(), nullable=True))
+    op.add_column("plex_shows", sa.Column("tagline_hu", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("plex_shows", "tagline_hu")
+    op.drop_column("plex_items", "tagline_hu")

backend/alembic/versions/0092_plex_person_biography_hu.py

@@ -0,0 +1,31 @@
+"""add biography_hu to plex_people — TMDB's Hungarian biography (E30 S4)
+
+Revision ID: 0092_plex_person_biography_hu
+Revises: 0091_plex_tagline_hu
+Create Date: 2026-09-29
+
+The person page showed a Hungarian reader the English biography although TMDB has a Hungarian one for
+most people. The person fetch now appends `translations` and keeps the Hungarian biography beside the
+English one. Already-enriched people are un-stamped, so their next page open refetches them once (the
+same lazy path as a first open) and fills it; until then the English biography stands in.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0092_plex_person_biography_hu"
+down_revision: str | None = "0091_plex_tagline_hu"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column("plex_people", sa.Column("biography_hu", sa.Text(), nullable=True))
+    op.execute(
+        "UPDATE plex_people SET tmdb_enriched_at = NULL "
+        "WHERE tmdb_person_id IS NOT NULL AND tmdb_enriched_at IS NOT NULL"
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("plex_people", "biography_hu")

backend/alembic/versions/0093_plex_person_known_for_votes.py

@@ -0,0 +1,29 @@
+"""re-fetch linked people — "Known for" ranked by votes, without guest visits (E30 S6)
+
+Revision ID: 0093_plex_person_known_for_votes
+Revises: 0092_plex_person_biography_hu
+Create Date: 2026-09-30
+
+A person's "Known for" pool was their credits ranked by TMDB popularity, so talk-show visits as
+themselves crowded out the films (Tom Cruise: 14 of 15 were talk shows, none in the library). The pool is
+now ranked by vote count, without guest visits, with directed works, and deeper. Already-enriched people
+are un-stamped so the people_enrich job fetches them again; their biography stays on the row meanwhile.
+"""
+
+from alembic import op
+
+revision: str = "0093_plex_person_known_for_votes"
+down_revision: str | None = "0092_plex_person_biography_hu"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        "UPDATE plex_people SET tmdb_enriched_at = NULL "
+        "WHERE tmdb_person_id IS NOT NULL AND tmdb_enriched_at IS NOT NULL"
+    )
+
+
+def downgrade() -> None:
+    pass  # the watermark only says "fetched"; a refetch under the old ranking is not worth undoing to

backend/alembic/versions/0094_plex_genres_hu_everywhere.py

@@ -0,0 +1,45 @@
+"""Hungarian genres on every Plex row, not only on overlaid ones (E30 review)
+
+Revision ID: 0094_plex_genres_hu_everywhere
+Revises: 0093_plex_person_known_for_votes
+Create Date: 2026-09-30
+
+The HU genre facets and filter read `genres_hu`, which only the overlay pass wrote — so a library with
+no HU twin, or a guid-less row, offered English genres a Hungarian filter could never match. The sync
+now writes `genres_hu` for every row (plex/sync.py `_apply_facet_fields`); this fills the rows it has
+not reached yet, from their own English list through the same map.
+"""
+
+import json
+
+import sqlalchemy as sa
+from alembic import op
+
+from app.plex.genres import hu_genres
+
+revision: str = "0094_plex_genres_hu_everywhere"
+down_revision: str | None = "0093_plex_person_known_for_votes"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for table in ("plex_items", "plex_shows"):
+        rows = conn.execute(
+            sa.text(
+                f"SELECT id, genres FROM {table} "
+                "WHERE genres_hu IS NULL AND jsonb_typeof(genres) = 'array'"
+            )
+        ).fetchall()
+        updates = [
+            {"id": rid, "g": json.dumps(hu)} for rid, genres in rows if (hu := hu_genres(genres))
+        ]
+        if updates:
+            conn.execute(
+                sa.text(f"UPDATE {table} SET genres_hu = CAST(:g AS jsonb) WHERE id = :id"), updates
+            )
+
+
+def downgrade() -> None:
+    pass  # derived from `genres`; the sync writes the same values again

backend/alembic/versions/0095_videos_channel_cover_index.py

@@ -0,0 +1,83 @@
+"""videos: the per-channel index covers what the channel manager and the feed sidebar read (E31 S4d)
+
+The channel manager (`GET /api/channels`) sums each subscribed channel's videos: count, last upload, total
+duration. The feed sidebar (`/feed/summary`, `/feed/years`) counts the reader's videos per channel and per
+year under the default filters: available, not via explore, not a short, not live. Every one of them found
+its rows through `ix_videos_channel_pub_desc` (channel_id, published_at DESC NULLS LAST, id) and then read
+each video's heap page for the rest: ~270k rows at ~2.5 KB each, 681 MB on prod. That stays in cache only
+while nothing else needs the memory. Measured on prod (2026-10-02): `/api/channels` 51–61 ms warm, but
+2.25 s and 1.96 s on a first open in the browser and 6.4 s under EXPLAIN with 30k blocks read from disk;
+`/feed/summary` and `/feed/years` ~140 ms warm, ~800 ms cold.
+
+The same key with those columns INCLUDEd makes them Index Only Scans. On a prod-copy localdev, after a
+VACUUM, the manager's sums read 0 heap pages and the summary reads the 25 MB index instead of the heap.
+The visibility map is what lets them skip the heap; prod's autovacuum kept it complete (relallvisible ==
+relpages). The key columns are unchanged, so every reader of the old index (the per-channel feed, the FK
+cascade, the sync upsert, channel detail) rides this one. The old index is dropped.
+tests/test_channel_list_index_only.py holds the queries and this column list together.
+
+CONCURRENTLY (autocommit_block) builds it without blocking a live prod. IF (NOT) EXISTS keeps the drift
+test's downgrade → re-upgrade round trip idempotent. A re-run after a build that failed part-way rebuilds
+the INVALID leftover, and the old index is dropped only once the new one is valid: a re-run that kept the
+leftover and dropped the old one left `videos` with no usable channel_id index (E31 S5 review).
+"""
+
+from alembic import op
+from sqlalchemy import text
+
+revision: str = "0095_videos_channel_cover_index"
+down_revision: str | None = "0094_plex_genres_hu_everywhere"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def _valid(name: str) -> bool | None:
+    """The index's `indisvalid`, or None when there is no index of that name."""
+    row = (
+        op.get_bind()
+        .execute(
+            text(
+                "SELECT i.indisvalid FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid "
+                "WHERE c.relname = :name"
+            ),
+            {"name": name},
+        )
+        .first()
+    )
+    return None if row is None else bool(row[0])
+
+
+def _build(name: str, ddl: str) -> None:
+    """CREATE INDEX CONCURRENTLY `name` (`ddl` is what follows the name), re-runnable. A build that
+    failed part-way leaves an INVALID index under the name, and `IF NOT EXISTS` would keep it: the
+    planner never uses it, and nothing says so (E31 S5 review). Such a leftover is dropped and built
+    again."""
+    if _valid(name) is False:
+        op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {name}")
+    op.execute(f"CREATE INDEX CONCURRENTLY IF NOT EXISTS {name} {ddl}")
+
+
+def _swap(build: str, ddl: str, drop: str) -> None:
+    _build(build, ddl)
+    if not _valid(build):
+        raise RuntimeError(f"{build} did not build valid; {drop} is kept")
+    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {drop}")
+
+
+def upgrade() -> None:
+    with op.get_context().autocommit_block():
+        _swap(
+            "ix_videos_channel_pub_cover",
+            "ON videos (channel_id, published_at DESC NULLS LAST, id) "
+            "INCLUDE (duration_seconds, unavailable_since, via_explore, is_short, live_status)",
+            "ix_videos_channel_pub_desc",
+        )
+
+
+def downgrade() -> None:
+    with op.get_context().autocommit_block():
+        _swap(
+            "ix_videos_channel_pub_desc",
+            "ON videos (channel_id, published_at DESC NULLS LAST, id ASC)",
+            "ix_videos_channel_pub_cover",
+        )

backend/alembic/versions/0096_videos_sort_indexes.py

@@ -0,0 +1,86 @@
+"""videos: an index per feed sort, so a sorted page stops after its rows (E31 S4e)
+
+The feed's views, duration and title sorts had no index. Every page (the first and each next cursor)
+read the whole videos heap, filtered it and kept a top-N: on prod ~350 ms a page for views/duration,
+550–780 ms for title (the ICU comparison on every row), 2.3 s for page 2 when the copies of one request
+queued. With an index in the exact ORDER BY (`feedquery.order_by`: the key, NULLS LAST, then id) the
+planner walks it and stops after the page. On a prod-copy localdev every plain sort fell from 180–310 ms
+to ~1 ms, deep pages (20) to 3–5 ms, and narrow filters (a tag, a channel, a year, nothing found) stayed
+at 0.3–25 ms.
+
+One index per direction: a backward scan of `DESC NULLS LAST` gives `ASC NULLS FIRST`, not the
+`ASC NULLS LAST` the asc sorts ask for. The title pair is per reader language (`app.collation.ICU`):
+an index only serves an ORDER BY in its own collation.
+
+Cost: ~130 MB (localdev: 10 + 10 + 8 + 8 + 4 × 23). Writes stay cheap: view_count and duration are
+written by the enrich, which rewrites indexed columns already (the revalidation job only touches
+last_checked_at), so no HOT update is lost. A search combined with one of these sorts can now walk the
+index too: a term matching ~2 % of the videos took 130–200 ms instead of 7 (still under the plain sort it
+replaces); rarer and broader terms stay fast. Fencing the index off under a search made broad terms
+(`m`, `the`) take 2 s, so it is left to the planner.
+
+The title indexes are the schema's first ones on an ICU collation: an ICU upgrade in the Postgres image
+reorders them, and `app.collation.heal_drift` rebuilds them at startup when it sees one.
+tests/test_feed_sort_indexes.py holds each sort and its index together.
+
+CONCURRENTLY (autocommit_block) builds them without blocking a live prod; IF (NOT) EXISTS keeps the drift
+test's downgrade → re-upgrade round trip idempotent.
+"""
+
+from alembic import op
+from sqlalchemy import text
+
+revision: str = "0096_videos_sort_indexes"
+down_revision: str | None = "0095_videos_channel_cover_index"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+# name → the indexed ORDER BY (feedquery.sort_keys + order_by: key NULLS LAST, then id).
+INDEXES = {
+    "ix_videos_views_desc": "view_count DESC NULLS LAST, id",
+    "ix_videos_views_asc": "view_count ASC NULLS LAST, id",
+    "ix_videos_duration_desc": "duration_seconds DESC NULLS LAST, id",
+    "ix_videos_duration_asc": "duration_seconds ASC NULLS LAST, id",
+    "ix_videos_title_en": '(lower(title) COLLATE "en-x-icu") ASC NULLS LAST, id',
+    "ix_videos_title_en_desc": '(lower(title) COLLATE "en-x-icu") DESC NULLS LAST, id',
+    "ix_videos_title_hu": '(lower(title) COLLATE "hu-x-icu") ASC NULLS LAST, id',
+    "ix_videos_title_hu_desc": '(lower(title) COLLATE "hu-x-icu") DESC NULLS LAST, id',
+}
+
+
+def _valid(name: str) -> bool | None:
+    """The index's `indisvalid`, or None when there is no index of that name."""
+    row = (
+        op.get_bind()
+        .execute(
+            text(
+                "SELECT i.indisvalid FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid "
+                "WHERE c.relname = :name"
+            ),
+            {"name": name},
+        )
+        .first()
+    )
+    return None if row is None else bool(row[0])
+
+
+def _build(name: str, ddl: str) -> None:
+    """CREATE INDEX CONCURRENTLY `name` (`ddl` is what follows the name), re-runnable. A build that
+    failed part-way leaves an INVALID index under the name, and `IF NOT EXISTS` would keep it: the
+    planner never uses it, and nothing says so (E31 S5 review). Such a leftover is dropped and built
+    again."""
+    if _valid(name) is False:
+        op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {name}")
+    op.execute(f"CREATE INDEX CONCURRENTLY IF NOT EXISTS {name} {ddl}")
+
+
+def upgrade() -> None:
+    with op.get_context().autocommit_block():
+        for name, columns in INDEXES.items():
+            _build(name, f"ON videos ({columns})")
+
+
+def downgrade() -> None:
+    with op.get_context().autocommit_block():
+        for name in INDEXES:
+            op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {name}")

backend/alembic/versions/0097_drop_messages.py

@@ -0,0 +1,69 @@
+"""messages: drop direct messaging (the owner's decision, 2026-10-04)
+
+Chat — end-to-end encrypted direct messages plus the server's welcome note — was never used: prod held
+two welcome notes, no message between people, and one key. Its tables go with its code. The rows are
+not migrated anywhere; the nightly backup holds them.
+
+The downgrade restores the schema as it stood (0026 + 0027), empty: a message can't be brought back
+from a migration, and the E2EE key blobs were only ever readable by their owner's browser anyway.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0097_drop_messages"
+down_revision: str | None = "0096_videos_sort_indexes"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.drop_table("message_keys")
+    op.drop_index("ix_messages_created_at", table_name="messages")
+    op.drop_index("ix_messages_recipient_id", table_name="messages")
+    op.drop_index("ix_messages_sender_id", table_name="messages")
+    op.drop_table("messages")
+
+
+def downgrade() -> None:
+    op.create_table(
+        "messages",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "sender_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=True
+        ),
+        sa.Column(
+            "recipient_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("body", sa.Text(), nullable=True),
+        sa.Column("read_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False
+        ),
+        sa.Column("kind", sa.String(length=16), nullable=False, server_default="user"),
+        sa.Column("ciphertext", sa.Text(), nullable=True),
+        sa.Column("iv", sa.String(length=32), nullable=True),
+    )
+    op.create_index("ix_messages_sender_id", "messages", ["sender_id"])
+    op.create_index("ix_messages_recipient_id", "messages", ["recipient_id"])
+    op.create_index("ix_messages_created_at", "messages", ["created_at"])
+    op.create_table(
+        "message_keys",
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column("public_key", sa.Text(), nullable=False),
+        sa.Column("wrapped_private_key", sa.Text(), nullable=False),
+        sa.Column("salt", sa.String(length=64), nullable=False),
+        sa.Column("wrap_iv", sa.String(length=32), nullable=False),
+        sa.Column("key_check", sa.Text(), nullable=False),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False
+        ),
+    )

backend/alembic/versions/0098_drop_demo_account.py

@@ -0,0 +1,55 @@
+"""demo: drop the shared demo account (the owner's decision, 2026-10-04)
+
+The demo account — one shared user that whitelisted emails entered from the login page, reset on a
+schedule — goes with its code. Prod held the demo user and 10 whitelist rows.
+
+The upgrade deletes the demo user first (its playlists, states and subscriptions cascade; audit and
+quota rows keep their history with the actor nulled, as for any deleted account), then the traces
+that only the demo code could render: its audit rows (whitelist edits, manual resets, and every row
+about the reset job — its runs and its interval changes), the reset job's interval override and its
+completion notices. Nothing is migrated anywhere; the nightly backup holds the rows.
+
+The downgrade restores the schema as it stood (0014), empty: the demo user is created lazily on its
+first sign-in, so an empty `demo_whitelist` is the whole of its state.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0098_drop_demo_account"
+down_revision: str | None = "0097_drop_messages"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.execute("DELETE FROM users WHERE is_demo")
+    op.execute(
+        "DELETE FROM audit_log WHERE action IN ('demo_add', 'demo_remove', 'demo_reset')"
+        " OR (target_type = 'job' AND target_id = 'demo_reset')"
+    )
+    op.execute("DELETE FROM scheduler_settings WHERE job_id = 'demo_reset'")
+    op.execute("DELETE FROM notifications WHERE data->>'job_id' = 'demo_reset'")
+    op.drop_index("ix_demo_whitelist_email", table_name="demo_whitelist")
+    op.drop_table("demo_whitelist")
+    op.drop_index("ix_users_is_demo", table_name="users")
+    op.drop_column("users", "is_demo")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column("is_demo", sa.Boolean(), nullable=False, server_default=sa.false()),
+    )
+    op.create_index("ix_users_is_demo", "users", ["is_demo"])
+    op.create_table(
+        "demo_whitelist",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("email", sa.String(length=320), nullable=False),
+        sa.Column("note", sa.Text(), nullable=True),
+        sa.Column("added_by", sa.String(length=320), nullable=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False
+        ),
+    )
+    op.create_index("ix_demo_whitelist_email", "demo_whitelist", ["email"], unique=True)

backend/alembic/versions/0099_library_states.py

@@ -0,0 +1,42 @@
+"""library: a resume point per user and library item
+
+The library player opened every item at 0:00. `library_states` keeps where a user stopped, per job
+(their own download, or one shared with them) — the same shape as `video_states`' position, without a
+status: the library has no "watched". It starts empty; the downgrade drops it.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0099_library_states"
+down_revision: str | None = "0098_drop_demo_account"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "library_states",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "job_id",
+            sa.Integer(),
+            sa.ForeignKey("download_jobs.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("position_seconds", sa.Integer(), nullable=False),
+        sa.Column("progress_updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.UniqueConstraint("user_id", "job_id", name="uq_library_user_job"),
+    )
+    op.create_index("ix_library_states_job_id", "library_states", ["job_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_library_states_job_id", table_name="library_states")
+    op.drop_table("library_states")

backend/alembic/versions/0100_drop_plex_item_markers.py

@@ -0,0 +1,22 @@
+"""plex_items: drop `markers`, a column nothing writes or reads
+
+Intro/credits markers are read live from Plex for the item the player opens (with Plex's `final` flag
+on the block that ends it); this cached copy was never filled — every row is NULL. The downgrade
+restores the empty column.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0100_drop_plex_item_markers"
+down_revision: str | None = "0099_library_states"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.drop_column("plex_items", "markers")
+
+
+def downgrade() -> None:
+    op.add_column("plex_items", sa.Column("markers", sa.JSON(), nullable=True))

backend/app/README.md

@@ -1,7 +1,7 @@
 # Backend conventions
 
 The rules below are already followed across `backend/app` — they lived only in a few module
-docstrings (`demo.py`, `userscope.py`, `routes/_common.py`) until this file collected them (E3 S3,
+docstrings (`userscope.py`, `routes/_common.py`) until this file collected them (E3 S3,
 B-core-20). When you add code, match these so the next reader doesn't have to guess "which pattern do
 I copy".
 
@@ -13,16 +13,19 @@ Three layers, by *who* runs the code — not by feature:
    response models, status-code mapping, serialization. It owns logic that runs *only* on a request.
    Business logic that a request happens to trigger does **not** live here if anything else runs it too.
 
-2. **`plex/`, `downloads/`, `sync/` — domain logic shared by more than one caller.** Anything the
+2. **`plex/`, `downloads/`, `sync/`, `issues/` — domain logic shared by more than one caller.** Anything the
    **scheduler or the worker** runs (not just a request) lives in one of these domain packages, so the
    route, the worker, and the scheduler share one definition. Examples from this codebase:
    `downloads/service.py` owns enqueue + the job state transitions (routes call it); `plex/sync.py` is
-   run by both the admin route and the scheduler; `downloads/pipeline.py` is the worker's child pipeline.
+   run by both the admin route and the scheduler; `downloads/pipeline.py` is the worker's child pipeline;
+   `issues/bundle.py` is the one definition of a bug report's files, for the zip export and the tracker.
 
 3. **Flat `app/*.py` core modules — cross-cutting primitives.** `auth`, `sysconfig`, `quota`, `audit`,
-   `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`, … are single-file primitives many
-   layers import. They depend on nothing above them (a core module must never import a `routes/…`
-   module).
+   `notifications`, `userscope`, `ratelimit`, `progress`, `logs` (the one logging
+   configuration), `logsink` (its `log_events` table), `diagnostics` (a user's consented log
+   level), `debugsession` (a recording that tags its user's lines, E16) and `collation` (A→Z in the
+   reader's alphabet, E30), … are single-file primitives many layers import. They depend on nothing above them (a core
+   module must never import a `routes/…` module).
 
 **Extraction trigger: the SECOND consumer.** Keep new logic inline in its first caller. The moment a
 *second* caller needs it (a worker as well as a route; a scheduler as well as a route), extract it down
@@ -69,7 +72,9 @@ mutation it records, so an audit entry can never exist without its change (or vi
 ## The gate
 
 Everything below must be green before a change is done (run via `siftlode check`):
-`ruff` (backend) · `tsc` ×3 + `eslint` + `prettier` + `knip` (frontend) · `vitest` · `pytest`. The
-pytest lane runs in `backend/docker-compose.test.yml` — an ephemeral Postgres + the backend tree
-bind-mounted — so the DB-backed integration tests (the `db` fixture) actually run; `SIFTLODE_TEST_
-REQUIRE_DB=1` there turns a would-be silent skip into a hard failure. See `docs/development.md`.
+`ruff` + `basedpyright` (backend) · the lock check + `tsc` ×3 + `eslint` + `prettier` + `knip` +
+`vite build` (frontend) · `vitest` · `pytest`. The pytest lane runs in `backend/docker-compose.test.yml`
+— an ephemeral Postgres + the backend tree bind-mounted — so the DB-backed integration tests (the `db`
+fixture) actually run; a missing database is a hard failure, not a silent skip, unless a hand run asks
+for pure-logic only with `SIFTLODE_TEST_REQUIRE_DB=0`. See `docs/development.md`, and `docs/gates.md`
+for what each gate deliberately leaves out.

backend/app/audit.py

@@ -27,7 +27,7 @@ class AuditAction:
     USER_SUSPEND = "user_suspend"
     USER_UNSUSPEND = "user_unsuspend"
     USER_DELETE = "user_delete"
-    # E9.5 S5: an admin let a stuck registrant in, or re-sent their confirmation link. Both are
+    # An admin let a stuck registrant in, or re-sent their confirmation link. Both are
     # recorded because both are the admin acting ON someone's access, not merely reading a list.
     USER_ACTIVATE = "user_activate"
     USER_VERIFY_RESEND = "user_verify_resend"
@@ -36,12 +36,9 @@ class AuditAction:
     INVITE_DENY = "invite_deny"
     INVITE_ADD = "invite_add"
     INVITE_DELETE = "invite_delete"
-    # E9.5 S6: the admin chose to tell someone their address is whitelisted. Adding the address is
+    # The admin chose to tell someone their address is whitelisted. Adding the address is
     # silent, so this is the act that actually reaches a person — and the one worth a record.
     INVITE_SEND = "invite_send"
-    DEMO_ADD = "demo_add"
-    DEMO_REMOVE = "demo_remove"
-    DEMO_RESET = "demo_reset"
     DISCOVERY_PURGE = "discovery_purge"
     # Config
     CONFIG_SET = "config_set"
@@ -58,6 +55,9 @@ class AuditAction:
     DOWNLOAD_CREDENTIAL_DELETE = "download_credential_delete"
     # The log itself was cleared (a single row survives the clear as tamper-evidence)
     AUDIT_CLEAR = "audit_clear"
+    # A user sent a debug session's issue to the tracker — the one act that takes their log
+    # off this instance, so it is recorded (target = the session, summary = the issue's URL).
+    ISSUE_CREATE = "issue_create"
 
 
 def record(

backend/app/auth.py

@@ -1,19 +1,20 @@
-import logging
-
 import httpx
 from fastapi import BackgroundTasks, Depends, HTTPException, Request
 from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 from starlette.requests import HTTPConnection
 
+from app import debugsession
 from app import email as email_mod
+from app import logs
 from app import mailtext
 from app import sysconfig
 from app.config import settings
 from app.db import get_db
-from app.models import Invite, User
+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
 
@@ -23,8 +24,6 @@ def operator_contact() -> str | None:
     return next(iter(sorted(settings.admin_email_set)), None)
 
 
-DEMO_GOOGLE_SUB = "__demo__"
-DEMO_EMAIL = "demo@siftlode.local"
 MAX_SESSION_ACCOUNTS = 6
 
 # OAuth scope vocabulary — the atoms + the request bundles, kept together as core. has_*_scope check
@@ -37,7 +36,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:
@@ -68,7 +67,7 @@ def has_write_scope(user: User) -> bool:
 def env_allowed_canonicals() -> set[str]:
     """The env bootstrap allow-list, in CANONICAL form — the only shape it may be compared in.
 
-    S3 canonicalised the Invite branch of `is_allowed` and left this one matching the literal string,
+    Canonicalising only the Invite branch of `is_allowed` left this one matching the literal string,
     which is the 2026-09-03 lockout with a different source of truth: an operator who writes
     `first.last@gmail.com` into ALLOWED_EMAILS is refused when Google answers with the undotted
     primary, and a `+tag`ged entry can never match at all, because a Google account cannot contain a
@@ -128,7 +127,7 @@ def can_activate(db: Session, user: User) -> bool:
     Lives in core so the admin surface and the /api/me badge count answer from ONE definition; a
     button that appears and a number that counts must never disagree about who is stuck.
     """
-    if user.is_demo or user.is_suspended or user.is_active:
+    if user.is_suspended or user.is_active:
         return False
     return is_allowed(db, user.email)
 
@@ -146,7 +145,6 @@ def count_pending_activations(db: Session) -> int:
     rows = (
         db.execute(
             select(User).where(
-                User.is_demo.is_(False),
                 User.is_suspended.is_(False),
                 User.is_active.is_(False),
             )
@@ -187,24 +185,6 @@ def find_user_by_email(db: Session, email: str) -> User | None:
     return candidates[0] if len(candidates) == 1 else None
 
 
-def get_or_create_demo_user(db: Session) -> User:
-    """The one shared demo user, created on first use. No OAuth token / YouTube scope, so
-    has_read_scope/has_write_scope are False and every YouTube-touching path is closed to it."""
-    user = db.query(User).filter(User.is_demo.is_(True)).one_or_none()
-    if user is None:
-        user = User(
-            google_sub=DEMO_GOOGLE_SUB,
-            email=DEMO_EMAIL,
-            display_name="Demo",
-            role="user",
-            is_demo=True,
-            preferences={"language": "en"},
-        )
-        db.add(user)
-        db.commit()
-    return user
-
-
 def revoke_google_token(token: str | None) -> None:
     """Best-effort revocation of a Google OAuth grant at Google's endpoint. Revoking the refresh
     token tears down the whole grant, so a later sign-in starts from a clean consent (no scopes
@@ -220,7 +200,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)
 
 
@@ -245,6 +225,12 @@ def purge_user(db: Session, user: User, background: BackgroundTasks) -> None:
     )
     # Raw delete so Postgres applies ON DELETE CASCADE / SET NULL on every dependent table.
     db.execute(delete(User).where(User.id == user_id))
+    # Stored log events name the account by id with no foreign key to cascade from (models.LogEvent),
+    # so they go explicitly — they are request history, i.e. personal data. Forgotten FIRST: this very
+    # request's access line, a queued row, a later background task would otherwise put rows back
+    # under the id after this DELETE (logs.forget_user).
+    logs.forget_user(user_id)
+    db.execute(delete(LogEvent).where(LogEvent.user_id == user_id))
     # Every canonically-equal invite goes, not just the literal spelling: is_allowed matches on the
     # canonical form, so leaving a sibling row behind would keep granting access to a mailbox whose
     # account was just erased — and prod really does carry approved pairs for one mailbox.
@@ -269,52 +255,84 @@ def purge_user(db: Session, user: User, background: BackgroundTasks) -> None:
 ACTIVE_ACCOUNT_HEADER = "x-siftlode-account"
 
 
-def resolved_user_id(conn: HTTPConnection) -> tuple[int | None, bool]:
+def resolved_user_id(conn: HTTPConnection, *, strict: bool = True) -> tuple[int | None, bool]:
     """Which account this connection acts as, and whether that's the session's default account.
-    Takes any HTTPConnection — an HTTP Request OR a WebSocket — so the WS push channel shares this
-    exact per-tab resolution instead of re-implementing it.
+    Takes an HTTPConnection rather than a Request: it reads only the session and the headers.
 
     The signed cookie holds the *wallet* (`account_ids`, every account signed into this browser)
-    plus a default `user_id`. A caller may override the default with the X-Siftlode-Account header,
-    but ONLY for an account already in the wallet — so a tab can't impersonate an account that never
-    authenticated here. Everything else (WebSocket, plain navigations) keeps using the cookie default.
+    plus a default `user_id`. A caller may name its account with the X-Siftlode-Account header (or
+    `?account=`), but ONLY an account in the wallet — so a tab can't impersonate an account that
+    never authenticated here. A connection that names no account acts as the cookie default.
+
+    A connection naming an account NOT in the wallet acts as nobody (`None`) — typically a tab still
+    pinned to an account that was signed out in another tab. It must not fall back to the default:
+    that tab would go on acting as an account it never showed, its player checkpoints and pref saves
+    landing there and its Sign out signing THAT account out. Only the bootstrap /api/me probe passes
+    `strict=False` and gets the default, which is how such a tab learns who it now is (the frontend
+    re-pins it and reloads). An account whose session ended while it stayed in the wallet (deleted,
+    suspended, revoked) leaves the wallet when it is refused (`_session_user`), so a tab pinned to it
+    takes the same way back.
     """
     default_id = conn.session.get("user_id")
     wallet = conn.session.get("account_ids") or []
-    # Header for normal XHR; ?account= for contexts that can't set headers (WebSocket, and a
-    # plain <a> file download). Both are wallet-gated below, so neither can impersonate an
-    # account that never signed into this browser.
+    # Header for normal XHR; ?account= for a context that can't set headers (a plain <a> file
+    # download). Both are wallet-gated below.
     hdr = conn.headers.get(ACTIVE_ACCOUNT_HEADER) or conn.query_params.get("account")
     if hdr:
         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
+        if strict:
+            return None, False
     return default_id, True
 
 
+def drop_from_wallet(session: dict, user_id: int) -> None:
+    """Take one account out of this browser's wallet (`account_ids`); the session default is untouched."""
+    session["account_ids"] = [a for a in (session.get("account_ids") or []) if a != user_id]
+
+
+def _end_account_session(request: Request, user_id: int, is_default: bool) -> None:
+    """An account whose session here is no longer valid. Only nuke the whole session when it is the
+    SESSION DEFAULT; a per-tab account just leaves the wallet (other tabs' default may still be valid).
+    Leaving is what lets a tab pinned to it recover: its next /api/me names an account no longer signed
+    in here and gets the default. Left in, it answered "signed out" — the landing page, with the default
+    still signed in, and no way off it but closing the tab."""
+    if is_default:
+        request.session.clear()
+    else:
+        drop_from_wallet(request.session, user_id)
+
+
 def current_user(request: Request, db: Session = Depends(get_db)) -> User:
-    user_id, is_default = resolved_user_id(request)
+    return _session_user(request, db, *resolved_user_id(request))
+
+
+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 → drop the session so the block takes effect at once.
-        # But only nuke the whole session when the SESSION DEFAULT identity is gone; a stale
-        # per-tab header account just 401s that one tab (other tabs' default may still be valid).
-        if is_default:
-            request.session.clear()
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        # Suspended/deactivated mid-session → end it so the block takes effect at once.
+        _end_account_session(request, user_id, is_default)
+        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):
-        if is_default:
-            request.session.clear()
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        _end_account_session(request, user_id, is_default)
+        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")
@@ -322,43 +340,53 @@ def current_user(request: Request, db: Session = Depends(get_db)) -> User:
     if default_id and default_id not in accounts:
         accounts.append(default_id)
         request.session["account_ids"] = accounts[-MAX_SESSION_ACCOUNTS:]
+    # Attribute this request's log lines to the account. Here, not in the request middleware:
+    # this is the one place a session becomes an account, and the middleware runs outside both the
+    # session middleware and this task's context. `request.state` is shared across middleware layers
+    # (it lives on the ASGI scope), so the access-log line can read it back. The user's consented
+    # diagnostics level rides along: their requests are logged — and stored — in that detail.
+    # So does a debug session the request names: only the caller's own open one counts, and a
+    # header naming anything else is ignored rather than refused — a stale tab must keep working.
+    session = debugsession.from_header(db, user, request.headers.get(debugsession.HEADER))
+    level, until = debugsession.level_for(user, session)
+    logs.set_user(user.id, level, until, session.id if session else None)
+    request.state.user_id = user.id
     return user
 
 
 def optional_current_user(request: Request, db: Session = Depends(get_db)) -> User | None:
     """Like `current_user` but returns None instead of raising 401 when there's no valid session.
     Used by the bootstrap /api/me probe so the logged-out landing doesn't log a failed request to
-    the browser console (a non-2xx fetch is a console error no matter how the app handles it)."""
+    the browser console (a non-2xx fetch is a console error no matter how the app handles it).
+    The one lenient resolution (`strict=False`): a tab naming an account no longer signed in here gets
+    the default account, which is how it learns who it now is — see `resolved_user_id`. That includes an
+    account refused right here, which `_session_user` has just taken out of the wallet."""
+    user_id, is_default = resolved_user_id(request, strict=False)
     try:
-        return current_user(request, db)
+        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
 
 
-def require_human(user: User = Depends(current_user)) -> User:
-    """Reject the shared demo account from actions that need a real Google/YouTube identity
-    or spend the shared quota. Most YouTube paths are already closed to it implicitly (it has
-    no token, so has_read_scope/has_write_scope are False); this makes the boundary explicit
-    where there's no scope check to lean on."""
-    if user.is_demo:
-        # Structured, because `req` leaves 403 to the caller and `notifyActionError` only shows a
-        # STRUCTURED detail — a plain string here reached the demo user as their caller's generic
-        # "couldn't do that", with no hint that the demo account is the reason (round 6). Affordances
-        # this gate sits behind are not all UI-gated on `is_demo` (the comfort shelf is not).
-        raise HTTPException(status_code=403, detail={"code": "demo"})
-    return user
-
-
-def require_write_scope(user: User = Depends(require_human)) -> User:
+def require_write_scope(user: User = Depends(current_user)) -> User:
     """Dependency: require the YouTube write scope (subscribe/unsubscribe, playlist export/edit).
     Single source of truth for the write gate — replaces the inline `if not has_write_scope(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."""
+    checks that had drifted into three different 403 messages across channels/playlists."""
     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
 
 
@@ -366,7 +394,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/bodylimit.py

@@ -0,0 +1,231 @@
+"""The global request-body cap (SEC-20).
+
+**The hole.** FastAPI reads a declared body IN FULL before auth or any other dependency runs — the
+body parameter has to be parsed to be passed in. So `POST /auth/password-login` drains a 32 MiB
+upload from an anonymous caller and only then answers 401. 70 of the 72 body-declaring routes behave
+the same way: one unauthenticated client can spend the process's memory and time at will.
+
+**Why a middleware and not `capped_body` on every route.** `routes/_common.py:capped_body` is the
+right tool where a route genuinely takes bulk bytes, and the two routes that use it use it
+correctly. But putting it on all 70 others would (a) fight the canonical "Request body → a Pydantic
+model" row, since capping means taking the body as raw bytes and parsing it by hand, and (b) leave
+the NEXT route added uncovered, because nothing would remind its author. A default that has to be
+opted into is not a default. This module inverts it: the cap applies to everything, and the few
+routes that need more opt OUT, in one list, next to the code that reads it.
+
+**Why raw ASGI and not `@app.middleware("http")`.** Starlette's BaseHTTPMiddleware cannot wrap
+`receive`, so it can only read `Content-Length` — which a client may omit entirely (chunked) or
+simply understate. The bytes have to be counted as they arrive, which is the same rule `capped_body`
+already applies per-route, and counting needs the receive channel.
+
+**Why the refusal is byte-identical to `capped_body`'s.** Two shapes for one fact is how the
+`cancelled`/`canceled` bug happened. The 413 body here is built through the same `JSONResponse`
+FastAPI renders `HTTPException(413, {"code": "too_large"})` with — not a hand-rolled `json.dumps`,
+whose default separators differ by two bytes — and `tests/test_body_limit.py` compares the RAW BYTES
+of the two against each other rather than against a literal, so they cannot drift apart. The same
+reasoning decides where the middleware is registered (`main.py`): just inside CORS, so this 413
+carries the same headers `capped_body`'s does.
+
+**No admin knob, deliberately.** The ceiling is a constant, not a `sysconfig` value: an attacker-
+facing limit that an admin can raise from the UI is a limit that can be raised by whoever gets the
+admin session, and nobody has asked to tune it. If a self-hoster ever needs a different ceiling it
+belongs in `config.py` (env, set before the process starts), not in the database.
+"""
+
+import re
+
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from app import debugsession
+from app.config import settings
+
+# 1 MiB. The largest body any route on the default ceiling legitimately takes is 512 KiB (the client
+# log sink, `routes/diagnostics.py:BODY_MAX_BYTES`), so this leaves 2x headroom — a ceiling that
+# refuses a legitimate request would be a worse bug than the one this module fixes. That ratio is
+# the load-bearing fact, so `test_body_limit.py` holds it rather than the figure above.
+DEFAULT_MAX_BODY_BYTES = 1024 * 1024
+
+# The routes that need MORE than the default, as (method, path TEMPLATE) → their own ceiling. The
+# template, not a concrete path, so the list reads like the route decorators it mirrors and
+# `test_body_limit.py` can assert that each one still resolves to a real route: a renamed route
+# fails the gate instead of silently losing its allowance in prod.
+#
+# These are RAISED CEILINGS, NOT EXEMPTIONS, and the difference is the whole point. An exemption
+# would mean "this route is counted by something else" — which is only true when the route's own
+# limit applies to the bytes as they ARRIVE. That, in turn, is only true of a route with NO DECLARED
+# BODY PARAMETER: FastAPI parses and spools a declared body BEFORE the first dependency runs, so a
+# route that declares one has already stored the bytes by the time its own cap — or its auth — gets
+# a say.
+#
+# Both listed routes now satisfy that. The screenshot route always did (`capped_body` streams it,
+# and the owner check resolves first). The upload route did NOT at first: it declared
+# `file: UploadFile = File(...)`, so an anonymous caller could make the process write the whole
+# per-file allowance to temp before the auth dependency refused them — this middleware bounded that
+# number but could not stop the writing. It now reads its own body from a dependency declared after
+# the auth one, so its in-handler cap measures bytes as they arrive, like everything else here.
+#
+# That rule is no longer only written here: `test_body_limit.py` parses the routes and fails the
+# gate if any route in this dict declares a body parameter. A comment could not have stopped the
+# defect it describes; the test can.
+#
+# A route belongs here ONLY IF ITS OWN CAP IS LARGER THAN THE DEFAULT. That is why
+# `POST /api/diagnostics/events` is absent: its `capped_body` limit is 512 KiB, already below the
+# default, so listing it could only widen what it accepts.
+ROUTE_MAX_BODY_BYTES: dict[tuple[str, str], int] = {
+    # Ingesting a local file. The body IS the file now — no multipart envelope to allow for —
+    # so this ceiling and the route's own cap count exactly the same bytes. `sysconfig`'s
+    # `download_upload_max_bytes` is bounded by this same constant (see sysconfig.SPECS), so an
+    # admin can only ever LOWER the route's cap below the edge, never raise it past one.
+    #
+    # WHICH LAYER ANSWERS, measured rather than assumed:
+    #   * knob LOWERED (an override below the default) — the route's cap is the smaller number, so
+    #     `capped_stream_to` trips first and answers 422 `upload_too_large` carrying the admin's own
+    #     figure, after draining the rest of the body so the client can read it.
+    #   * knob at the DEFAULT — the two numbers are EQUAL, and the edge always wins: a declared
+    #     Content-Length over the cap is refused here before a byte is read, and an undeclared body
+    #     trips this counter on the same chunk the route would have tripped on. The route's 422 is
+    #     unreachable in that configuration, and no amount of headroom would change it — the
+    #     declared-length check fires first for any body big enough to matter, and the route's drain
+    #     pushes the count past the edge for the rest.
+    #
+    # So this 413 is a refusal a real user meets on a default install, not a theoretical edge, and
+    # it has to be as readable as the route's own: the client localizes `too_large` (`errors.tooLarge`)
+    # exactly as it does `upload_too_large`, and the upload dialog refuses an over-cap file before
+    # sending it at all, off the `upload_max_bytes` that `GET /api/downloads/usage` reports.
+    ("POST", "/api/downloads/upload"): settings.download_upload_max_bytes,
+    ("POST", "/api/debug-sessions/{sid}/screenshots"): debugsession.SCREENSHOT_MAX_BYTES,
+}
+
+# The refusal, byte-for-byte what `capped_body`'s `HTTPException(413, {"code": "too_large"})` renders
+# as — built through the same JSONResponse so the separators match too, and asserted against a real
+# route's raw bytes in `test_body_limit.py` rather than against a literal here.
+TOO_LARGE_BODY = JSONResponse({"detail": {"code": "too_large"}}, status_code=413).body
+
+_PATH_PARAM = re.compile(r"\{[^/{}]+\}")
+
+
+def template_to_regex(template: str) -> re.Pattern[str]:
+    """`/api/debug-sessions/{sid}/screenshots` → a regex matching one concrete path.
+
+    A path parameter matches `[^/]+` — one segment, never across a `/`, so `{sid}` cannot swallow a
+    deeper path and hand an exemption to a route that was never granted one.
+    """
+    literals = [re.escape(part) for part in _PATH_PARAM.split(template)]
+    return re.compile("^" + "[^/]+".join(literals) + "$")
+
+
+def _declared_length(scope: Scope) -> int | None:
+    """The `Content-Length` header as an int, or None when absent or unparseable (a chunked body has
+    none, and a malformed one is not a number we may trust — both fall through to counting)."""
+    for name, value in scope.get("headers", ()):
+        if name == b"content-length":
+            try:
+                return int(value)
+            except ValueError:
+                # silent-ok: a malformed Content-Length is the caller's doing, not a fault of ours,
+                # and it is about to be answered anyway — returning None drops the request into the
+                # counting path, which refuses on the real bytes. Logging it would hand an anonymous
+                # client a free line in our log for every request it cares to malform.
+                return None
+    return None
+
+
+async def _send_too_large(send: Send) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 413,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"content-length", str(len(TOO_LARGE_BODY)).encode()),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": TOO_LARGE_BODY})
+
+
+class BodyLimitMiddleware:
+    """Refuses any request body over its route's ceiling, before the application sees it.
+
+    Registered just inside CORS in `main.py` — so the 413 is decorated like every other response
+    and a browser can actually read it — but outside the session, the setup gate and every auth
+    dependency, none of which run for a request that is already too large.
+
+    Every request gets a finite ceiling: `ROUTE_MAX_BODY_BYTES` raises it for the two routes that
+    genuinely take bulk bytes, and there is no path that skips counting altogether.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        limit: int = DEFAULT_MAX_BODY_BYTES,
+        routes: dict[tuple[str, str], int] | None = None,
+    ) -> None:
+        self.app = app
+        self.limit = limit
+        self._routes = tuple(
+            (method, template_to_regex(path), cap)
+            for (method, path), cap in (ROUTE_MAX_BODY_BYTES if routes is None else routes).items()
+        )
+
+    def limit_for(self, method: str, path: str) -> int:
+        """This request's ceiling: the route's own if it has one, else the global default. Every
+        request gets a finite number — there is no path through here that is simply not counted."""
+        for m, rx, cap in self._routes:
+            if m == method and rx.match(path):
+                return cap
+        return self.limit
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        limit = self.limit_for(scope.get("method", ""), scope.get("path", ""))
+
+        declared = _declared_length(scope)
+        if declared is not None and declared > limit:
+            # Refused on the declaration alone: nothing downstream is called, and not one byte of
+            # the body is read.
+            await _send_too_large(send)
+            return
+
+        seen = 0
+        refused = False
+        started = False
+
+        async def counting_receive() -> Message:
+            nonlocal seen, refused
+            message = await receive()
+            if message["type"] != "http.request":
+                return message
+            seen += len(message.get("body", b""))
+            if seen > limit:
+                # The app is blocked on this receive, so it has not answered yet. Telling it the
+                # client went away is the only in-band way to stop it reading: `request.stream()`
+                # turns an `http.disconnect` into ClientDisconnect, which unwinds the handler. Our
+                # own 413 goes out below, once the app has finished unwinding.
+                refused = True
+                return {"type": "http.disconnect"}
+            return message
+
+        async def guarded_send(message: Message) -> None:
+            nonlocal started
+            if refused and not started:
+                return  # discard the app's answer to the disconnect; the 413 below is the response
+            started = True
+            await send(message)
+
+        try:
+            await self.app(scope, counting_receive, guarded_send)
+        except Exception:  # only swallowed when WE caused it, see below
+            # ClientDisconnect (or whatever a handler raises on a truncated read) is the expected
+            # consequence of the disconnect we just faked, and the caller must get the 413 rather
+            # than a 500. Anything raised when we did NOT refuse is a real failure and is re-raised
+            # untouched.
+            if not refused:
+                raise
+
+        if refused and not started:
+            await _send_too_large(send)

backend/app/collation.py

@@ -0,0 +1,83 @@
+"""Alphabetical order in the reader's language.
+
+Why not the database default: the Postgres image is Alpine, and musl's `en_US.utf8` collation is BYTE
+order — every accented initial sorted after "Z" ("Zorró < Életrajzi < Ötödik"), in every A→Z list the
+server orders. Postgres ships the ICU collations on the same image (dev, test, prod alike), so a text
+sort names one: Hungarian puts "Ö" after "O" and "Cs" after "Cu", English folds the accents in.
+
+`collated` wraps an ORDER BY expression — and because a keyset cursor compares with the SAME expression
+(`feedquery.sort_keys`), the cursor pages in the same order it sorted in. `sorted_words` orders a Python
+list the same way through the database, so a list built in Python matches one built in SQL exactly.
+
+The feed's title sorts ride indexes built in these collations (migration 0096), and an index keeps the
+order of the ICU that built it. `postgres:16-alpine` is a floating tag: an image update can bring a newer
+ICU, after which those indexes disagree with the comparisons a query makes (a keyset page skips or
+repeats a title). `heal_drift` rebuilds them at startup once Postgres reports the version moved."""
+
+from typing import Any
+
+from sqlalchemy import Engine, SQLColumnExpression, column, func, select, text, values
+from sqlalchemy.orm import Session
+from sqlalchemy.sql.elements import ColumnElement
+from sqlalchemy.types import String
+
+from app import logs
+from app.mailtext import normalize
+
+log = logs.get_logger(__name__)
+
+ICU: dict[str, str] = {"en": "en-x-icu", "hu": "hu-x-icu"}
+
+
+def collation(lang: str | None) -> str:
+    """The ICU collation for a UI language; anything unknown sorts as English."""
+    return ICU[normalize(lang)]
+
+
+def collated(expr: SQLColumnExpression[Any], lang: str | None) -> ColumnElement[Any]:
+    """`expr` compared in the reader's alphabet. Case-folded, so "apple" and "Apple" sit together."""
+    return func.lower(expr).collate(collation(lang))
+
+
+def sorted_words(db: Session, words: list[str], lang: str | None) -> list[str]:
+    """`words` in the reader's alphabetical order, by the same ICU collation as `collated`."""
+    if not words:
+        return []
+    w = values(column("w", String), name="words").data([(x,) for x in words])
+    return list(db.scalars(select(w.c.w).order_by(collated(w.c.w, lang), w.c.w)))
+
+
+def heal_drift(engine: Engine) -> list[str]:
+    """Rebuild every index on an ICU collation whose library version moved, then record the new version.
+    Returns the rebuilt indexes. CONCURRENTLY: the feed keeps reading while it runs."""
+    with engine.connect().execution_options(isolation_level="AUTOCOMMIT") as conn:
+        drifted = conn.execute(
+            text(
+                "SELECT oid, collname FROM pg_collation WHERE collname = ANY(:names) "
+                "AND collversion IS DISTINCT FROM pg_collation_actual_version(oid)"
+            ),
+            {"names": list(ICU.values())},
+        ).all()
+        if not drifted:
+            return []
+        indexes = list(
+            conn.execute(
+                text(
+                    "SELECT DISTINCT d.objid::regclass::text FROM pg_depend d "
+                    "JOIN pg_class c ON c.oid = d.objid AND c.relkind = 'i' "
+                    "WHERE d.classid = 'pg_class'::regclass "
+                    "AND d.refclassid = 'pg_collation'::regclass AND d.refobjid = ANY(:oids)"
+                ),
+                {"oids": [row.oid for row in drifted]},
+            ).scalars()
+        )
+        log.warning(
+            "ICU collation version changed (%s): rebuilding %d indexes",
+            ", ".join(row.collname for row in drifted),
+            len(indexes),
+        )
+        for name in indexes:
+            conn.execute(text(f"REINDEX INDEX CONCURRENTLY {name}"))
+        for row in drifted:
+            conn.execute(text(f'ALTER COLLATION "{row.collname}" REFRESH VERSION'))
+        return indexes

backend/app/config.py

@@ -1,6 +1,7 @@
 from pathlib import Path
+from typing import Literal, get_args, get_origin
 
-from pydantic import model_validator
+from pydantic import Field, ValidationInfo, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 # Shipped placeholder; production must override it. Used by the startup guard below.
@@ -15,11 +16,40 @@ 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"
 
 
+# Closed value sets. A setting typed with one of these is a CHOICE: pydantic rejects anything else at
+# boot, and sysconfig derives the admin picker's options from the same Literal — so the list lives in
+# exactly one place and a consumer never has to guess what a typo should fall back to.
+SearchSource = Literal["scrape", "api"]
+DownloadLayout = Literal["plex", "flat"]
+LogLevel = Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"]
+LogFormat = Literal["json", "text"]
+TranscodeHw = Literal["auto", "on", "off"]
+# libx264's presets, fastest first (`placebo` left out on purpose: no measurable gain for its cost).
+TranscodePreset = Literal[
+    "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow"
+]
+
+
+def choices_of(annotation: object) -> tuple[str, ...]:
+    """The allowed values of a choice-typed setting, or () for any other type."""
+    return tuple(get_args(annotation)) if get_origin(annotation) is Literal else ()
+
+
+def canonical_choice(options: tuple[str, ...], raw: object) -> str | None:
+    """The option `raw` names, in its canonical spelling (any letter case, surrounding space
+    ignored), or None. The ONE matching rule for a choice value from the env and from the admin
+    API, so a spelling one accepts the other cannot refuse."""
+    folded = str(raw).strip().casefold()
+    return next((option for option in options if option.casefold() == folded), None)
+
+
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(env_file=".env", extra="ignore")
 
@@ -57,7 +87,7 @@ class Settings(BaseSettings):
     # VPS Caddy front door. A request from any other peer (someone hitting the app port directly)
     # is NOT trusted and its raw socket IP is used, so it can't spoof its rate-limit identity via
     # XFF. Empty = trust no proxy (use the direct peer) — correct for a directly-exposed / local-dev
-    # deploy. Comma-separated. See routes.auth._client_ip + the deploy docs.
+    # deploy. Comma-separated. See ratelimit.client_key + the deploy docs.
     trusted_proxy_ips: str = ""
 
     # --- Outbound email (onboarding: access-request + approval notices) ---
@@ -85,10 +115,13 @@ class Settings(BaseSettings):
     search_daily_limit_per_user: int = 70
     # Source for live YouTube search: "scrape" (InnerTube, no API quota) or "api" (search.list,
     # 100 units/page). Scrape is the default; flip to "api" if scraping is blocked/breaks.
-    search_source: str = "scrape"
+    search_source: SearchSource = "scrape"
     # 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.
@@ -113,8 +146,6 @@ class Settings(BaseSettings):
     autotag_interval_minutes: int = 30
     subscriptions_resync_minutes: int = 360
     playlist_sync_minutes: int = 360
-    # How often the shared demo account is auto-reset to a clean baseline (communal sandbox).
-    demo_reset_minutes: int = 720
     # --- Maintenance / validation job ---
     # Runs once a day by default (admin-tunable via the Scheduler dashboard). Grace periods
     # are in days because that's the granularity that matters; the rolling re-validation
@@ -155,6 +186,9 @@ class Settings(BaseSettings):
     # per-client responses are flaky, and android_vr can get bot-flagged under heavy load) the
     # worker retries with the FALLBACK set — the POT-capable web clients (web needs the token +
     # Deno) plus android for audio. Both admin-tunable when YouTube shifts what works.
+    # A SIGNED-IN download (the user added YouTube cookies) keeps only the cookie-capable clients
+    # of these two sets — yt-dlp drops the rest, so android_vr / android / ios never run there.
+    # See adapters.YouTubeAdapter._COOKIE_CAPABLE.
     download_player_clients: str = "android_vr"
     download_player_clients_fallback: str = "web_safari,web,android"
 
@@ -208,10 +242,14 @@ class Settings(BaseSettings):
     download_default_max_bytes: int = 5_368_709_120  # 5 GiB
     download_default_max_concurrent: int = 2
     download_default_max_jobs: int = 50
-    # Per-file cap for local uploads (E7). Unlike a download (whose size is unknown until the worker
+    # Per-file cap for local uploads. Unlike a download (whose size is unknown until the worker
     # finishes), an upload's size is known at ingest, so this bounds a single file directly; the
     # user's overall byte footprint is still governed by download_default_max_bytes.
-    download_upload_max_bytes: int = 524_288_000  # 500 MiB
+    # ge=1: this number is also the EDGE ceiling (`bodylimit.ROUTE_MAX_BODY_BYTES`), where 0 is a
+    # real limit of zero rather than the route's "no per-file cap" sentinel — an instance set to 0
+    # would refuse every upload, including the admin page's own way back. To lift the cap in
+    # practice, set a large number.
+    download_upload_max_bytes: int = Field(default=524_288_000, ge=1)  # 500 MiB
     # Retention: an asset expires this many days after its last access; the GC job then
     # deletes it (once no job references it) after an additional grace window.
     download_retention_days: int = 30
@@ -220,11 +258,31 @@ class Settings(BaseSettings):
     # Admin audit log: how long to keep rows (days; 0 = keep forever) + how often the GC runs.
     audit_retention_days: int = 180
     audit_gc_minutes: int = 1440
+    # YouTube quota history (quota_events): days kept (0 = forever). A year, so the admin usage view's
+    # longest window (365 days) stays whole; the same daily cleanup job prunes it.
+    quota_retention_days: int = 365
     # On-disk layout: "plex" (Channel/Season YYYY/… [id].ext + .nfo/poster) or "flat".
-    download_layout: str = "plex"
+    download_layout: DownloadLayout = "plex"
     # Default SponsorBlock (skip sponsor segments) for new custom profiles.
     sponsorblock_default: bool = False
 
+    # --- Diagnostics / logging ---
+    # BOOTSTRAP level only: the running level is the `log_level` admin knob (sysconfig), applied at
+    # startup and on change without a restart. This is what a process logs at before it can reach
+    # the database — and the only knob the worker/runner children read, since they are short-lived.
+    # TRACE (below DEBUG) is the "Teljes" diagnostics level; see app/logs.py.
+    log_level: LogLevel = "INFO"
+    # "json" (one object per line — what Loki and the log_events sink ingest) or "text" (a readable
+    # line for a local terminal). Redaction applies to both.
+    log_format: LogFormat = "json"
+    # Also write events to the `log_events` table (app/logsink.py): WARNING and above, the request
+    # lines, and — once they exist — client batches. Off only where no table is wanted (the tests).
+    log_db_sink: bool = True
+    # Days a `log_events` row is kept (the privacy policy promises this), and how often the log_gc job
+    # enforces it — hourly, so a row never outlives the promise by more than an hour.
+    log_retention_days: int = 7
+    log_gc_minutes: int = 60
+
     # --- Plex integration (optional) ---
     # The Plex module plays the LOCAL physical media file directly (our own ffmpeg/direct-serve);
     # Plex is used only for metadata + optional watch-state sync. Requires the Plex server to be
@@ -241,7 +299,7 @@ class Settings(BaseSettings):
     plex_path_map: str = ""
     # Which Plex library section keys are exposed (comma-separated). Empty = all enabled sections.
     plex_libraries: str = ""
-    # HU-overlay mapping (E5 S5): comma-separated `huSectionKey:enSectionKey` pairs. Each named HU
+    # HU-overlay mapping: comma-separated `huSectionKey:enSectionKey` pairs. Each named HU
     # section is synced as a non-browsable overlay whose Hungarian metadata is written onto the EN
     # twin section's rows (matched by guid). Empty = no overlays. E.g. "3:4,5:1".
     plex_overlay_map: str = ""
@@ -251,7 +309,7 @@ class Settings(BaseSettings):
     plex_sync_interval_min: int = 360
     # How often the incremental Plex→Siftlode watch-state reconcile runs, in minutes (Phase C):
     # a cheap history + on-deck pull plus a re-push of any states that failed their immediate push.
-    # 15 min (S2): with Plex now the source of truth (prompt write-back on the ~10s checkpoint +
+    # 15 min: with Plex now the source of truth (prompt write-back on the ~10s checkpoint +
     # Plex-authoritative pull), a faster incremental pull keeps Siftlode close to Plex-side changes.
     plex_watch_sync_interval_min: int = 15
     # How often the FULL watch-state reconcile runs, in minutes (Phase C). A whole-section rescan
@@ -262,11 +320,15 @@ 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
-    # --- Transcode (playable="transcode") re-encode tuning (E6 S1) ---
+    # 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 ---
     # 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
     # node exists (skip the decodability gate); "off" = always software. See plex/stream.py `_select_encode`.
-    plex_transcode_hw: str = "auto"
+    plex_transcode_hw: TranscodeHw = "auto"
     # Software-fallback libx264 tuning (IGNORED on the VAAPI path). `preset` trades CPU for size; `crf`
     # trades quality for size (lower = better + bigger). `max_height` caps the SOFTWARE transcode's output
     # height (0 = keep source) so a CPU re-encode of a tall source stays affordable — the GPU path always
@@ -276,7 +338,7 @@ class Settings(BaseSettings):
     # call, not a fix. Only affects files that go through remux/transcode — a direct-played file is
     # served untouched, but those are browser-native stereo anyway, not the 5.1 mixes this is for.
     plex_audio_loudnorm: bool = False
-    plex_transcode_preset: str = "veryfast"
+    plex_transcode_preset: TranscodePreset = "veryfast"
     plex_transcode_crf: int = 20
     plex_transcode_max_height: int = 1080
     # Where on-the-fly HLS remux segments are written (transient, reaped). Empty → a `.plex-hls`
@@ -285,7 +347,7 @@ class Settings(BaseSettings):
     # local disk, so the default is fine there.
     plex_hls_dir: str = ""
 
-    # --- TMDB enrichment (E5 S2; optional — enriches the Plex catalog from TMDB) ---
+    # --- TMDB enrichment (optional — enriches the Plex catalog from TMDB) ---
     # TMDB API key (v3 api_key, 32 hex chars). Server-side only; stored encrypted when set via the
     # admin Config page. Empty → the TMDB enrichment job no-ops. Feeds keywords / crew / budget /
     # revenue / TMDb score / recommendations / backdrops onto the mirrored Plex rows, matched by the
@@ -294,10 +356,22 @@ class Settings(BaseSettings):
     tmdb_api_base: str = "https://api.themoviedb.org/3"
     # Metadata language for TMDB fetches (keyword/overview locale). Stored EN by default.
     tmdb_language: str = "en-US"
+
+    # --- Bug reports: where a debug session's issue goes. All three empty = no tracker; the
+    # composer still exports a zip. The repository must be PRIVATE — an issue carries the reporter's
+    # log — and app/issues/gitea.py refuses a public one. Runtime knobs (sysconfig, admin UI). ---
+    issues_gitea_url: str = ""
+    issues_gitea_repo: str = ""
+    issues_gitea_token: str = ""
     # How often the TMDB enrichment job fetches a batch of not-yet-enriched Plex titles, in minutes.
     tmdb_enrich_interval_min: int = 120
     # Titles fetched per TMDB enrichment run (TMDB is fast + generously rate-limited).
     tmdb_enrich_batch: int = 100
+    # How often the people job fetches a batch of person bios from TMDB and portraits through Plex,
+    # in minutes, and how many of each per run: ~18k linked people at 300 per 10 min is about ten hours
+    # once, then only the newcomers.
+    people_enrich_interval_min: int = 10
+    people_enrich_batch: int = 300
 
     @property
     def allowed_email_set(self) -> set[str]:
@@ -325,6 +399,17 @@ class Settings(BaseSettings):
         https OAUTH_REDIRECT_URL as the signal for 'real deployment' vs local dev."""
         return self.oauth_redirect_url.lower().startswith("https://")
 
+    @field_validator("*", mode="before")
+    @classmethod
+    def _canonical_choice(cls, value: object, info: ValidationInfo) -> object:
+        """A choice setting accepts its value in any letter case (`LOG_LEVEL=debug`) and stores the
+        canonical spelling; an unknown value still fails the boot with pydantic's own message."""
+        field = cls.model_fields.get(info.field_name or "")
+        options = choices_of(field.annotation) if field else ()
+        if options and isinstance(value, str):
+            return canonical_choice(options, value) or value
+        return value
+
     @model_validator(mode="after")
     def _enforce_production_secrets(self) -> "Settings":
         """Fail fast rather than boot a public instance with the shipped placeholder

backend/app/db.py

@@ -1,6 +1,6 @@
 from collections.abc import Iterator
 
-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, text
 from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
 
 from app.config import settings
@@ -12,7 +12,9 @@ class Base(DeclarativeBase):
 
 # Pool sized above the sync-endpoint threadpool (~40) so a burst of short DB sessions can't starve on
 # checkout. The image proxies deliberately DON'T hold a connection during their slow external fetch
-# (see routes/plex/), so this headroom is only for the many brief sessions, not long ones.
+# (see routes/plex/), so this headroom is only for the many brief sessions, not long ones. The one
+# long hold — a playlist sync's advisory claim, for a whole push — opens its own unpooled connection
+# (sync/playlists.py `_claim_engine`) instead of drawing a third one from here.
 engine = create_engine(
     settings.database_url,
     pool_pre_ping=True,
@@ -20,6 +22,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)
 
@@ -30,3 +36,50 @@ def get_db() -> Iterator[Session]:
         yield db
     finally:
         db.close()
+
+
+def release_read_connection(db: Session) -> None:
+    """End a request's READ transaction so its pooled connection goes back BEFORE a long await.
+
+    SQLAlchemy 2.0 autobegins on the first SELECT, so a request that has merely authenticated is
+    already holding one of the connections above — `idle in transaction` to Postgres, and nothing
+    times it out. A route that then awaits something slow (a request body still arriving, an
+    external fetch) pins it for the whole wait, which is precisely the invariant the pool is sized
+    on in the comment above. Measured: the next checkout after this call reuses the very backend
+    that was released, and a 1.8 s upload goes from one sustained `idle in transaction` to none.
+
+    Every route that reads its own body from a dependency needs this, and `test_body_limit.py`
+    holds that — the three that do are the ones with a raised (or self-imposed) body ceiling, and
+    they got here one at a time, which is how the upload route ended up the only one fixed.
+
+    The caller must have NOTHING PENDING, and that is checked rather than described. The session is
+    shared with every dependency that ran before, so a rollback here would silently discard a write
+    one of them staged — `service.enqueue` already learned that lesson the expensive way and uses a
+    SAVEPOINT for it. CLAUDE.md: a rule stated in a comment must also be enforced in code.
+
+    TWO checks, because the obvious one is blind to the shapes this codebase actually writes in.
+    `db.new`/`deleted`/`dirty` hold only UNFLUSHED unit-of-work: the moment a helper calls
+    `db.flush()` — CLAUDE.md's canonical split is "the handler commits; helpers flush" — the object
+    is persistent with no unflushed history and all three sets are empty again, and Core DML
+    (`db.execute(update(...))`) never enters them at all. Measured: after `add`+`flush` the sets are
+    empty, the old check passed, and the rollback lost the row. So the transaction is asked
+    directly. Postgres assigns a transaction id on the first WRITE and never for a read, so
+    `pg_current_xact_id_if_assigned()` is NULL for exactly the state this function is safe in — and
+    it sees a raw `text("UPDATE …")` too, which no session-level bookkeeping would.
+    """
+    if db.new or db.deleted or db.dirty:
+        raise RuntimeError(
+            "release_read_connection() with pending work: something ahead of this dependency "
+            "staged a write, which ending the transaction would discard. Commit it first, or do "
+            "it after the await."
+        )
+    if (
+        db.in_transaction()
+        and db.execute(text("SELECT pg_current_xact_id_if_assigned()")).scalar() is not None
+    ):
+        raise RuntimeError(
+            "release_read_connection() on a transaction that has already WRITTEN: something ahead "
+            "of this dependency flushed a row or ran an UPDATE/INSERT/DELETE, which ending the "
+            "transaction would discard. Commit it first, or do it after the await."
+        )
+    db.rollback()

backend/app/debugsession.py

@@ -0,0 +1,485 @@
+"""Debug sessions: Start → reproduce → Stop, and the evidence a bug report is built from.
+
+While a session is open its user's browser names it in `X-Debug-Session` on every request. The auth
+dependency accepts the header only for the caller's OWN open session (anything else is ignored, never
+an error — a stale tab must not break the app) and then logs that request at the session's level with
+every line tagged by its id; the browser tags its own events the same way. The issue is later built
+from exactly the rows carrying the tag, so what the review list shows is what gets sent.
+
+Starting a session IS the consent for its level, for its duration: the start dialog carries the
+consent text. It needs no change to the user's own diagnostics level, and none is made — when the
+session ends the level in force is simply the user's own again.
+
+A session is capped at `MAX_MINUTES`, set by the server at Start. An open one past its cap is over
+whether or not anything has closed it yet: it reads as over at once, a new Start closes it, and the
+hourly log job sweeps the rest. Sessions go with the logs they point at, after `log_retention_days`.
+
+Core layer: imports `models`, `diagnostics`.
+"""
+
+import secrets
+from datetime import datetime, timedelta, timezone
+from enum import StrEnum
+from typing import Literal, get_args
+from uuid import uuid4
+
+from sqlalchemy import and_, delete, func, not_, select, update
+from sqlalchemy.orm import Session, defer
+
+from app import diagnostics
+from app.models import DebugScreenshot, DebugSession, LogEvent, User
+
+HEADER = "x-debug-session"
+MAX_MINUTES = diagnostics.SESSION_MINUTES
+SCREENSHOT_MAX_BYTES = 10 * 1024 * 1024
+SCREENSHOTS_MAX = 8
+# What one user may keep in screenshots across ALL their sessions (until retention takes them): the
+# per-session cap alone would let Start → 8 images → Stop repeat without end.
+SCREENSHOT_USER_MAX_BYTES = 100 * 1024 * 1024
+# The screenshot types kept, and the extension each is exported and sent under — one table, so an
+# accepted type always has a name.
+IMAGE_TYPES = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}
+# What a screenshot is called in the zip and on the issue. `issues/bundle.py` builds the names from
+# this and `IMAGE_TYPES`; this module and `issues/gitea.py` read them back to tell a screenshot's
+# link from a log's. One definition, because three copies of a name is how the next rename breaks
+# `images_pending` into silence.
+SCREENSHOT_PREFIX = "screenshot-"
+# Rows an issue can carry. A 60-minute session at Teljes is a few thousand rows; past this the
+# bundle says how many it left out rather than growing without bound.
+BUNDLE_MAX = 5_000
+
+SessionLevel = Literal["DEBUG", "TRACE"]
+SESSION_LEVELS: tuple[str, ...] = get_args(SessionLevel)
+# Detail order of the diagnostics levels: a session raises the level in force, never lowers it.
+_DETAIL = {"INFO": 0, "DEBUG": 1, "TRACE": 2}
+_ID_LEN = 16
+
+
+class EndReason(StrEnum):
+    STOPPED = "stopped"
+    EXPIRED = "expired"
+
+
+def is_live(session: DebugSession, now: datetime | None = None) -> bool:
+    """Open and within its cap — THE liveness rule: an open session past its cap is over."""
+    return session.ended_at is None and session.until > (now or datetime.now(timezone.utc))
+
+
+def open_session(db: Session, user: User) -> DebugSession | None:
+    """The user's live session, or None. Read-only: one past its cap is over and reads as None;
+    `start` and the hourly sweep are what close it."""
+    session = _unclosed(db, user)
+    if session is None or not is_live(session, datetime.now(timezone.utc)):
+        return None
+    return session
+
+
+def _unclosed(db: Session, user: User) -> DebugSession | None:
+    return db.scalar(
+        select(DebugSession).where(DebugSession.user_id == user.id, DebugSession.ended_at.is_(None))
+    )
+
+
+def start(db: Session, user: User, level: SessionLevel) -> DebugSession:
+    """Open a session, or return the live one — a second tab pressing Start joins the recording
+    rather than ending it. One past its cap is closed first: the one-open-per-user index would
+    refuse the new row beside it. Flushes; the caller commits. Two concurrent Starts can still both
+    get here: the index refuses the second, and the caller joins the one that won."""
+    now = datetime.now(timezone.utc)
+    current = _unclosed(db, user)
+    if current is not None:
+        if is_live(current, now):
+            return current
+        end(current, EndReason.EXPIRED)
+        db.flush()
+    session = DebugSession(
+        id=secrets.token_hex(_ID_LEN // 2),
+        user_id=user.id,
+        level=level,
+        started_at=now,
+        until=now + timedelta(minutes=MAX_MINUTES),
+    )
+    db.add(session)
+    db.flush()
+    return session
+
+
+def stop(session: DebugSession) -> None:
+    """The user's Stop. Past its cap the session had already ended on its own, and a late Stop must
+    not rename that."""
+    end(session, EndReason.STOPPED if is_live(session) else EndReason.EXPIRED)
+
+
+def end(session: DebugSession, reason: EndReason) -> None:
+    """Close a session. An expired one is dated at its cap, not at whenever it was noticed."""
+    if session.ended_at is not None:
+        return
+    session.ended_at = (
+        session.until
+        if reason is EndReason.EXPIRED
+        else min(datetime.now(timezone.utc), session.until)
+    )
+    session.ended_reason = reason
+
+
+def from_header(db: Session, user: User, value: str | None) -> DebugSession | None:
+    """The session a request names, if it is the caller's own and still live; else None."""
+    if not value or len(value) != _ID_LEN or not all(c in "0123456789abcdef" for c in value):
+        return None
+    session = db.get(DebugSession, value)
+    if (
+        session is None
+        or session.user_id != user.id
+        or not is_live(session, datetime.now(timezone.utc))
+    ):
+        return None
+    return session
+
+
+def level_for(user: User, session: DebugSession | None) -> tuple[str, datetime | None]:
+    """The diagnostics level (and its expiry) a request is logged at: the user's own, raised to the
+    session's while one is named — whichever records more.
+
+    A named session also caps the expiry at its own: this pair is what the process tracks under the
+    session (app/logs.py), and an expiry outliving the recording would hold the root logger down
+    after it ended."""
+    own = diagnostics.effective_level(user)
+    until = user.diagnostics_until if own != diagnostics.BASE else None
+    if session is None:
+        return own, until
+    if _DETAIL[session.level] <= _DETAIL[own]:
+        return own, min(until, session.until) if until else session.until
+    return session.level, session.until
+
+
+def lock(db: Session, session: DebugSession) -> None:
+    """Re-read the session under a row lock, held until the caller commits. Everything that changes
+    what an issue is made of — the draft, the screenshots, the send itself — takes it first: a send
+    in flight sees none of them change under it, and each of them sees a send that committed."""
+    db.refresh(session, with_for_update=True)
+
+
+def save_draft(session: DebugSession, draft: dict) -> None:
+    """Keep the composer's draft (the caller validated, locked and commits). Shape: `title`, `body`
+    (the rendered markdown an export or an issue carries), `excluded` (log row ids taken out of the
+    evidence) and `form` (the composer's own fields, to reopen it as it was). A delivery's progress
+    is not the composer's to replace, and is kept."""
+    progress = (session.draft or {}).get("delivery")
+    session.draft = {**draft, "delivery": progress} if progress else draft
+
+
+# --- a delivery's progress -----------------------------------------------------------------
+# Written by app/issues/gitea.py into the draft; read HERE, so the send's decision and what the
+# composer shows are one reading of it.
+def delivery(session: DebugSession) -> dict:
+    return dict((session.draft or {}).get("delivery") or {})
+
+
+def not_uploaded(session: DebugSession) -> list[str]:
+    """The files a send that stopped half-way has still to upload — by name, as the issue carries
+    them. What the composer names to the user."""
+    return list(delivery(session).get("pending") or [])
+
+
+def images_pending(session: DebugSession) -> bool:
+    """Whether the issue's body still has to be edited to show the screenshots it already carries
+    (every upload went, the edit that shows them did not)."""
+    state = delivery(session)
+    shown = state.get("images_shown")
+    return not shown and any(n.startswith(SCREENSHOT_PREFIX) for n in state.get("links") or {})
+
+
+def unfinished(session: DebugSession) -> bool:
+    """Whether a send owes the issue anything — the retry's question."""
+    return bool(not_uploaded(session)) or images_pending(session)
+
+
+# A send claims the session while it talks to the tracker, instead of holding the row's lock across
+# those calls: a Stop, an autosave or a screenshot would queue behind a lock for the whole send.
+# They see the claim and are refused at once instead. A claim not renewed for this long was left by
+# a request that died mid-send (the process restarted), and the next send takes it over — which is
+# why a live send RENEWS it every time it reports progress (`set_delivery`). A claim is a lease, and
+# a send slower than the lease must not lose it while it is still running.
+SEND_CLAIM_SECONDS = 600
+
+
+def _claim(session: DebugSession) -> dict:
+    claim = delivery(session).get("sending")
+    return claim if isinstance(claim, dict) else {}
+
+
+def _stamp(token: str) -> dict:
+    return {"at": datetime.now(timezone.utc).isoformat(), "by": token}
+
+
+def sending(session: DebugSession) -> bool:
+    """Whether a send is under way right now (a live claim)."""
+    at = _claim(session).get("at")
+    if not at:
+        return False
+    return (datetime.now(timezone.utc) - datetime.fromisoformat(at)).total_seconds() < (
+        SEND_CLAIM_SECONDS
+    )
+
+
+def claim_send(session: DebugSession) -> str:
+    """Mark the session as being sent, and return the token that OWNS this claim. The caller holds
+    the lock and commits, which is what makes the claim visible to everyone else."""
+    token = uuid4().hex
+    _write_delivery(session, {**delivery(session), "sending": _stamp(token)})
+    return token
+
+
+def release_send(session: DebugSession, token: str) -> None:
+    """Give back our OWN claim, and only ours: one that aged out and was taken over belongs to the
+    send holding it now, and handing that one back would let a third send in beside it."""
+    if _claim(session).get("by") != token:
+        return
+    _write_delivery(session, {k: v for k, v in delivery(session).items() if k != "sending"})
+
+
+class SendClaimLost(Exception):
+    """This send's claim is no longer on the row: it aged out and another send took it over. The
+    send must stop — what it uploads from here it can no longer record, so a retry would send it
+    again — and it must not write, because the row now holds the other send's progress."""
+
+
+def claim_owner(db: Session, session: DebugSession) -> str | None:
+    """Who holds the row's claim RIGHT NOW, read from the ROW and not from the object.
+
+    `expire_on_commit` is off (app/db.py), so a checkpoint does not re-read: a send that stalled
+    past its lease still carries its own dead token in memory long after another send took over.
+    A targeted scalar, not `lock`/`db.refresh` — a refresh here would discard the `issue_url` that
+    `gitea.deliver` assigns one line before its first progress report, and that link is the one
+    thing the send must not lose."""
+    return db.scalar(
+        select(DebugSession.draft["delivery"]["sending"]["by"].as_string()).where(
+            DebugSession.id == session.id
+        )
+    )
+
+
+def set_delivery(db: Session, session: DebugSession, state: dict, token: str) -> None:
+    """Write a delivery's progress (app/issues/gitea.py keeps it; this module reads it), and renew
+    the claim while doing it — a send still reporting progress is still alive, so one slower than
+    the lease cannot expire while it is still running.
+
+    The claim is not the caller's to carry: `gitea.deliver` threads ONE snapshot of this dict
+    through a whole send, so a progress report that carried the claim wrote a stale one back at
+    every step. It is stamped from `token` here instead, and only after the ROW confirms the claim
+    is still ours. Without that check the write is a full-column overwrite with no WHERE: a send
+    that lost its lease came back and stomped the take-over send's committed links, then put its
+    own dead token back on an idle session. `release_send` has always made
+    the same check; this is the other half of it."""
+    if claim_owner(db, session) != token:
+        raise SendClaimLost(session.id)
+    state = {k: v for k, v in state.items() if k != "sending"}
+    state["sending"] = _stamp(token)
+    _write_delivery(session, state)
+
+
+def _write_delivery(session: DebugSession, state: dict) -> None:
+    # A new dict, so the JSONB column sees the change.
+    session.draft = {**(session.draft or {}), "delivery": state}
+
+
+def serialize(session: DebugSession | None, screenshots: int = 0) -> dict | None:
+    if session is None:
+        return None
+    return {
+        "id": session.id,
+        "level": session.level,
+        "started_at": session.started_at.isoformat(),
+        "until": session.until.isoformat(),
+        "ended_at": session.ended_at.isoformat() if session.ended_at else None,
+        "ended_reason": session.ended_reason,
+        "issue_url": session.issue_url,
+        # A send that stopped half-way: the files it has still to upload, and whether the issue's
+        # body has still to be edited to show the screenshots it already carries. Both are true of a
+        # send that is RUNNING too — every step commits its progress — so `sending` goes with them:
+        # without it a reload or a second tab renders a live send as a failed one, and offers a
+        # retry that is certain to be refused.
+        "pending_files": not_uploaded(session),
+        "images_pending": images_pending(session),
+        "sending": sending(session),
+        "screenshots": screenshots,
+        "draft": session.draft,
+    }
+
+
+def view(db: Session, session: DebugSession) -> dict:
+    """The session as the API serves it — one shape wherever it is served."""
+    return serialize(session, screenshot_count(db, session)) or {}
+
+
+def screenshot_count(db: Session, session: DebugSession) -> int:
+    return (
+        db.scalar(
+            select(func.count())
+            .select_from(DebugScreenshot)
+            .where(DebugScreenshot.session_id == session.id)
+        )
+        or 0
+    )
+
+
+# --- screenshots ---------------------------------------------------------------------------
+# By content, not by the declared type: what is stored is served back to a browser as an image.
+_SIGNATURES = (
+    (b"\x89PNG\r\n\x1a\n", "image/png"),
+    (b"\xff\xd8\xff", "image/jpeg"),
+)
+
+
+def sniff(data: bytes) -> str | None:
+    """The image type `data` really is — one of IMAGE_TYPES — or None."""
+    for magic, mime in _SIGNATURES:
+        if data.startswith(magic):
+            return mime
+    if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+def lock_user(db: Session, user_id: int) -> None:
+    """Hold this user's own lock for the rest of the transaction. A session's row lock bounds what
+    THAT session may keep; the byte cap below is the user's across all of them, and a lock on one
+    session cannot serialize a check that reads them all — two uploads to two sessions both read the
+    total before either commits, and both pass."""
+    db.execute(select(func.pg_advisory_xact_lock(user_id)))
+
+
+def stored_screenshot_bytes(db: Session, user_id: int) -> int:
+    return (
+        db.scalar(
+            select(func.coalesce(func.sum(DebugScreenshot.size), 0))
+            .join(DebugSession, DebugSession.id == DebugScreenshot.session_id)
+            .where(DebugSession.user_id == user_id)
+        )
+        or 0
+    )
+
+
+class ScreenshotRefused(Exception):
+    """A screenshot that cannot be kept; `code` is the refusal's machine word."""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+        self.code = code
+
+
+def add_screenshot(db: Session, session: DebugSession, data: bytes) -> DebugScreenshot:
+    """Keep one screenshot. Locks the user and the session, and flushes; the caller commits.
+    Refused while a send is under way or once the issue was sent (it can no longer carry it), past
+    the per-session count or the user's storage, or when it is not an image we can show."""
+    if not data:
+        raise ScreenshotRefused("empty")
+    mime = sniff(data)
+    if mime is None:
+        raise ScreenshotRefused("not_an_image")
+    # Under both locks: two uploads at once cannot both pass the count (the session's), nor both
+    # pass the user's byte cap from two different sessions (the user's). Always in this order.
+    lock_user(db, session.user_id)
+    lock(db, session)
+    if sending(session):
+        raise ScreenshotRefused("sending")
+    if session.issue_url is not None:
+        raise ScreenshotRefused("already_sent")
+    if screenshot_count(db, session) >= SCREENSHOTS_MAX:
+        raise ScreenshotRefused("too_many")
+    if stored_screenshot_bytes(db, session.user_id) + len(data) > SCREENSHOT_USER_MAX_BYTES:
+        raise ScreenshotRefused("storage_full")
+    shot = DebugScreenshot(
+        session_id=session.id,
+        created_at=datetime.now(timezone.utc),
+        mime=mime,
+        size=len(data),
+        data=data,
+    )
+    db.add(shot)
+    db.flush()
+    return shot
+
+
+def remove_screenshot(db: Session, session: DebugSession, shot: DebugScreenshot) -> None:
+    """Delete one screenshot, under the lock. Refused while a send is under way or unfinished: a
+    delivery names the screenshots by their order, and removing one would renumber what it still
+    has to send. Once the issue has everything, this only drops OUR copy — the issue keeps its
+    own. The caller commits."""
+    lock(db, session)
+    if sending(session):
+        raise ScreenshotRefused("sending")
+    if unfinished(session):
+        raise ScreenshotRefused("already_sent")
+    db.delete(shot)
+    db.flush()
+
+
+def screenshots(db: Session, session: DebugSession) -> list[DebugScreenshot]:
+    """The session's screenshots, oldest first, WITHOUT their bytes loaded."""
+    return list(
+        db.scalars(
+            select(DebugScreenshot)
+            .where(DebugScreenshot.session_id == session.id)
+            .options(defer(DebugScreenshot.data))
+            .order_by(DebugScreenshot.id)
+        )
+    )
+
+
+# --- the evidence --------------------------------------------------------------------------
+# The browser's own log upload (`POST` here, every few seconds while recording) is how the evidence
+# arrives, not part of it: its server lines would fill the bundle with the recording's plumbing. The
+# browser leaves its copies out for the same reason (frontend lib/diagnostics `isOwnRequest`).
+INGEST_PATH = "/api/diagnostics/events"
+
+
+def _evidence(session: DebugSession):
+    upload_line = and_(
+        LogEvent.event == "http.request", LogEvent.attrs["path"].astext == INGEST_PATH
+    )
+    # `IS TRUE`, not the bare condition: for a row with no event or no attrs it is NULL, and
+    # `NOT NULL` would drop exactly the rows that are evidence.
+    return (LogEvent.debug_session_id == session.id, not_(upload_line.is_(True)))
+
+
+def bundle(
+    db: Session, session: DebugSession, *, drop_excluded: bool = False
+) -> tuple[list[LogEvent], int]:
+    """The session's log rows, browser and server interleaved in time, capped at BUNDLE_MAX — and
+    how many rows it has in all, so a cut bundle can say so. `drop_excluded` leaves out the rows
+    the user took out in the composer: what an export or an issue carries."""
+    where = list(_evidence(session))
+    excluded = (session.draft or {}).get("excluded") or [] if drop_excluded else []
+    if excluded:
+        where.append(LogEvent.id.not_in(excluded))
+    rows = list(
+        db.scalars(
+            select(LogEvent).where(*where).order_by(LogEvent.ts, LogEvent.id).limit(BUNDLE_MAX)
+        )
+    )
+    total = len(rows)
+    if total == BUNDLE_MAX:
+        total = db.scalar(select(func.count()).select_from(LogEvent).where(*where)) or total
+    return rows, total
+
+
+# --- housekeeping (the hourly log job) -----------------------------------------------------
+def sweep(db: Session) -> int:
+    """Stage closing every open session past its cap; returns how many."""
+    now = datetime.now(timezone.utc)
+    result = db.execute(
+        update(DebugSession)
+        .where(DebugSession.ended_at.is_(None), DebugSession.until <= now)
+        .values(ended_at=DebugSession.until, ended_reason=EndReason.EXPIRED.value)
+        .execution_options(synchronize_session=False)
+    )
+    return result.rowcount or 0
+
+
+def gc(db: Session, retention_days: int) -> int:
+    """Stage deleting sessions (and by cascade their screenshots) started before the log retention
+    window — the rows they would bundle are gone by then too. Returns how many."""
+    cutoff = datetime.now(timezone.utc) - timedelta(days=max(1, retention_days))
+    result = db.execute(delete(DebugSession).where(DebugSession.started_at < cutoff))
+    return result.rowcount or 0

backend/app/demo.py

@@ -1,82 +0,0 @@
-"""Demo-account service: reset the shared demo sandbox to a clean, seeded baseline.
-
-Shared by the admin's manual reset endpoint (routes/admin.py) and the scheduled demo-reset job
-(scheduler.py). Lives in the service layer, not routes, so the scheduler can call it without an
-`app.routes -> app.scheduler` import cycle (the reason its import used to be lazy).
-"""
-
-from sqlalchemy import delete, func, select
-from sqlalchemy.orm import Session
-
-from app.models import Playlist, PlaylistItem, Subscription, User, Video, VideoState
-
-
-def _seed_demo_playlists(db: Session, demo: User) -> int:
-    """Seed a few sample playlists from the shared catalog so a freshly-reset demo isn't
-    empty — gives visitors something to play with. Best-effort: skips silently if the
-    catalog is too small."""
-    recent = (
-        db.execute(
-            select(Video.id)
-            .where(Video.is_short.is_(False), Video.live_status == "none")
-            .order_by(Video.published_at.desc().nullslast())
-            .limit(60)
-        )
-        .scalars()
-        .all()
-    )
-    if not recent:
-        return 0
-    samples = [
-        ("Fresh picks", recent[0:10]),
-        ("Quick watch", recent[10:18]),
-        ("Saved for later", recent[18:26]),
-    ]
-    created = 0
-    for pos, (name, vids) in enumerate(samples):
-        if not vids:
-            continue
-        pl = Playlist(user_id=demo.id, name=name, position=pos)
-        db.add(pl)
-        db.flush()
-        for ipos, vid in enumerate(vids):
-            db.add(PlaylistItem(playlist_id=pl.id, video_id=vid, position=ipos))
-        created += 1
-    return created
-
-
-def _seed_demo_subscriptions(db: Session, demo: User, n: int = 14) -> int:
-    """Seed the demo with a handful of catalog channels (the ones with the most videos) so its
-    Channel manager isn't empty — gives visitors something to explore and matches the landing-page
-    screenshot. Idempotent: clears the demo's subscriptions first, then re-adds the top N."""
-    db.execute(delete(Subscription).where(Subscription.user_id == demo.id))
-    top = (
-        db.execute(
-            select(Video.channel_id)
-            .where(Video.channel_id.is_not(None))
-            .group_by(Video.channel_id)
-            .order_by(func.count().desc())
-            .limit(n)
-        )
-        .scalars()
-        .all()
-    )
-    for channel_id in top:
-        db.add(Subscription(user_id=demo.id, channel_id=channel_id))
-    return len(top)
-
-
-def reset_demo_state(db: Session, demo: User) -> int:
-    """Wipe the demo account's per-user state (watch/save/hide states, playlists, preferences)
-    back to a clean baseline and re-seed a few sample playlists + channel subscriptions. Returns
-    the seeded playlist count. Shared by the admin's manual reset button and the scheduled demo
-    reset (see scheduler)."""
-    db.execute(delete(VideoState).where(VideoState.user_id == demo.id))
-    # Playlist items cascade on playlist delete (ondelete="CASCADE").
-    db.execute(delete(Playlist).where(Playlist.user_id == demo.id))
-    demo.preferences = {"language": "en"}
-    db.commit()
-    seeded = _seed_demo_playlists(db, demo)
-    _seed_demo_subscriptions(db, demo)
-    db.commit()
-    return seeded

backend/app/diagnostics.py

@@ -0,0 +1,64 @@
+"""A user's diagnostics level: what they consented to, and for how long.
+
+Three levels, named in the UI Alap / Részletes / Teljes:
+
+  * INFO  — the base, for everyone, no consent. The browser keeps its log in memory; nothing extra
+            is sent or stored.
+  * DEBUG — consented. The server logs this user's requests in detail and stores every line of
+            them, and the browser streams its own log to `POST /api/diagnostics/events`.
+  * TRACE — consented. As DEBUG, plus what the user typed into a search.
+
+A raised level always lapses after `ELEVATION_HOURS`: the expiry is computed HERE at consent time,
+never taken from the client, and an expired level reads as INFO without anything having to clear it.
+
+Core layer: imports `models` and `sysconfig`.
+"""
+
+from datetime import datetime, timedelta, timezone
+from typing import Literal, get_args
+
+from sqlalchemy.orm import Session
+
+from app import sysconfig
+from app.models import User
+
+DiagnosticsLevel = Literal["INFO", "DEBUG", "TRACE"]
+LEVELS: tuple[str, ...] = get_args(DiagnosticsLevel)
+BASE: DiagnosticsLevel = "INFO"
+ELEVATION_HOURS = 24
+# How long a debug session records at most (app/debugsession.py). Here, beside the other
+# consent window, because the start dialog's consent text states it and reads it from `state`.
+SESSION_MINUTES = 60
+
+
+def effective_level(user: User, now: datetime | None = None) -> DiagnosticsLevel:
+    """The level in force for `user` right now: the consented one until it expires, else BASE."""
+    level, until = user.diagnostics_level, user.diagnostics_until
+    if level not in LEVELS or level == BASE or until is None:
+        return BASE
+    if until <= (now or datetime.now(timezone.utc)):
+        return BASE
+    return level  # type: ignore[return-value] — narrowed by the LEVELS check above
+
+
+def state(db: Session, user: User) -> dict:
+    """The `/api/me` view of it: the level in force, when a raised one lapses, and how long stored
+    log lines are kept — the consent text states that number, so it must be the instance's own."""
+    level = effective_level(user)
+    return {
+        "level": level,
+        "until": user.diagnostics_until.isoformat() if level != BASE else None,
+        "retention_days": sysconfig.get_int(db, "log_retention_days"),
+        "session_minutes": SESSION_MINUTES,
+    }
+
+
+def set_level(user: User, level: DiagnosticsLevel) -> None:
+    """Record a consent (or its withdrawal). The caller commits. Raising the level again restarts
+    the clock — each consent is for the next ELEVATION_HOURS, not an extension of an older one."""
+    if level == BASE:
+        user.diagnostics_level = None
+        user.diagnostics_until = None
+        return
+    user.diagnostics_level = level
+    user.diagnostics_until = datetime.now(timezone.utc) + timedelta(hours=ELEVATION_HOURS)

backend/app/discover/__init__.py

@@ -1,4 +1,4 @@
-"""E24 — the read-model behind the Home surface ("Mit nézzek most?").
+"""The read-model behind the Home surface ("Mit nézzek most?").
 
 The anti-paralysis answer layer: one hero suggestion, a cross-source resume rail, and the user's own
 comfort shelf, all served from our own Postgres with no upstream call at serve time (the same rule

backend/app/discover/budget.py

@@ -1,4 +1,4 @@
-"""The time budget — E24's replacement for "what mood are you in?".
+"""The time budget — the replacement for "what mood are you in?".
 
 `random-gondolatok` 15/D asked for a mood questionnaire before the recommendations. The same file's
 later BA-interview note (#23) says the mood half is not what makes this work: the friction is

backend/app/discover/hero.py

@@ -48,6 +48,7 @@ def pick(
     shelf: list[dict] | None = None,
     exclude: set[str] | None = None,
     start: int = 0,
+    lang: str,
 ) -> dict | None:
     """`{"tier": ..., "card": ...}`, or None when nothing at all fits.
 
@@ -70,8 +71,8 @@ def pick(
     skip = exclude or set()
 
     def _resume() -> dict | None:
-        for card in rails.continue_watching(db, user) if resume is None else resume:
-            playable = rails.playable(db, user.id, card)
+        for card in rails.continue_watching(db, user, lang=lang) if resume is None else resume:
+            playable = rails.playable(db, user.id, card, lang=lang)
             # Excluded on the card the USER saw (the show), not only on what it resolves to, so a
             # rerolled-past show does not come straight back as its own next episode.
             if cards.key(card) in skip or (playable is not None and cards.key(playable) in skip):
@@ -81,7 +82,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), lang=lang)
+        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
@@ -89,7 +94,7 @@ def pick(
     def _surprise() -> dict | None:
         # A wider draw than the one card we need: the shuffle is seeded, so without the headroom an
         # excluded pick would leave the tier empty rather than move past it.
-        for card in rails.surprise(db, user, budget, seed, limit=SURPRISE_DRAW):
+        for card in rails.surprise(db, user, budget, seed, limit=SURPRISE_DRAW, lang=lang):
             if cards.key(card) not in skip:
                 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
 
@@ -44,8 +46,8 @@ def resolve_ref(db: Session, user: User, kind: str, ref: str) -> tuple[str, obje
     translation belongs here rather than in five call sites.
 
     The COLUMN half of every answer comes from `PIN_COLUMNS`; only the LOOKUP differs per kind
-    (a direct `db.get`, a rating-key translation, an int parse plus an ownership check). Before the
-    E24 review the branches spelled the column names out again and `PIN_COLUMNS` had no readers at
+    (a direct `db.get`, a rating-key translation, an int parse plus an ownership check). Before a
+    review the branches spelled the column names out again and `PIN_COLUMNS` had no readers at
     all — a constant that called itself the one vocabulary while nothing spoke it."""
     col = PIN_COLUMNS.get(kind)
     if col is None:
@@ -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, lang: str) -> 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:
@@ -127,7 +196,7 @@ def _shelf_card(db: Session, user: User, pin: ComfortPin) -> dict | None:
         if it is None:
             return None
         st = rollup.item_state_map(db, user.id, [it.id]).get(it.id)
-        card = cards.from_plex(leaf_card(it, st))
+        card = cards.from_plex(leaf_card(it, st, lang=lang))
         nxt = dict(card)  # a movie or a single episode plays itself
 
     elif pin.plex_show_id is not None:
@@ -135,15 +204,15 @@ def _shelf_card(db: Session, user: User, pin: ComfortPin) -> dict | None:
         if sh is None:
             return None
         status = rollup.state_map(db, user.id, [sh.id]).get(sh.id, "new")
-        card = cards.from_plex(show_card(sh, status))
-        ep = queries.next_episode(db, user.id, sh.id)
+        card = cards.from_plex(show_card(sh, status, lang=lang))
+        ep = queries.next_episode(db, user.id, sh.id, lang=lang)
         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, lang: str) -> 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, lang)
         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

@@ -40,11 +40,12 @@ from app.models import (
     VideoState,
 )
 from app.plex import rollup
-from app.plex.cards import leaf_card, movie_card, show_card
+from app.plex.cards import display_title, 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 ──────────────────────────────────────────────────────────────────────────────────────────
@@ -208,7 +221,9 @@ def _unseen_movie_conds(uid: int):
     return ~seen
 
 
-def plex_in_progress(db: Session, uid: int, limit: int = RAIL_LIMIT) -> list[tuple[object, dict]]:
+def plex_in_progress(
+    db: Session, uid: int, limit: int = RAIL_LIMIT, *, lang: str
+) -> list[tuple[object, dict]]:
     """In-progress movies + partially-watched shows as (progressed_at, card).
 
     Mirrors `routes/plex/discover.py::_continue_watching` — same `PlexState` predicate for movies (a
@@ -236,7 +251,7 @@ def plex_in_progress(db: Session, uid: int, limit: int = RAIL_LIMIT) -> list[tup
             .limit(limit)
         )
         for it, st in db.execute(mq).all():
-            out.append((st.progress_updated_at, movie_card(it, st)))
+            out.append((st.progress_updated_at, movie_card(it, st, lang=lang)))
 
     if show_libs:
         prog = rollup.agg_subquery(db, uid, include_resumed=True).subquery()
@@ -250,12 +265,14 @@ def plex_in_progress(db: Session, uid: int, limit: int = RAIL_LIMIT) -> list[tup
         for sh, resumed_at in db.execute(
             sq.order_by(prog.c.resumed_at.desc().nullslast()).limit(limit)
         ).all():
-            out.append((resumed_at, show_card(sh, "in_progress")))
+            out.append((resumed_at, show_card(sh, "in_progress", lang=lang)))
 
     return out
 
 
-def plex_surprise(db: Session, uid: int, budget: str, seed: int, limit: int) -> list[dict]:
+def plex_surprise(
+    db: Session, uid: int, budget: str, seed: int, limit: int, *, lang: str
+) -> list[dict]:
     """Unseen playable movies inside the budget, in seeded-shuffle order.
 
     Movies only. A show is not a thing you can start playing, and resolving every candidate show to
@@ -287,14 +304,14 @@ def plex_surprise(db: Session, uid: int, budget: str, seed: int, limit: int) ->
         q = q.where(PlexItem.duration_s <= hi)
     items = db.execute(q).scalars().all()
     states = rollup.item_state_map(db, uid, [it.id for it in items])
-    return [movie_card(it, states.get(it.id)) for it in items]
+    return [movie_card(it, states.get(it.id), lang=lang) for it in items]
 
 
 # Watch states that take an episode out of the running for "what would play next".
 _DONE = ("watched", "hidden")
 
 
-def next_episode(db: Session, uid: int, show_id: int) -> dict | None:
+def next_episode(db: Session, uid: int, show_id: int, *, lang: str) -> dict | None:
     """What "put that show on" means: the episode in progress, else the first unwatched one, else the
     first — over the same `(season, episode)` broadcast ordering `detail.py::_episode_nav` uses.
 
@@ -344,5 +361,9 @@ def next_episode(db: Session, uid: int, show_id: int) -> dict | None:
     ep, st = pick
     show = db.get(PlexShow, show_id)
     return leaf_card(
-        ep, st, show_title=show.title if show else None, show_rk=show.rating_key if show else None
+        ep,
+        st,
+        show_title=display_title(show, lang) if show else None,
+        show_rk=show.rating_key if show else None,
+        lang=lang,
     )

backend/app/discover/rails.py

@@ -22,7 +22,7 @@ def plex_available(db: Session) -> bool:
     return sysconfig.get_bool(db, "plex_enabled")
 
 
-def playable(db: Session, uid: int, card: dict) -> dict | None:
+def playable(db: Session, uid: int, card: dict, *, lang: str) -> dict | None:
     """The thing that would actually START from this card — itself for anything with a runtime, and
     for a Plex SHOW the episode that is next (in progress, else the first unwatched, else the first).
 
@@ -40,11 +40,11 @@ def playable(db: Session, uid: int, card: dict) -> dict | None:
     sh = by_rating_key(db, PlexShow, card["id"])
     if sh is None:
         return None
-    ep = queries.next_episode(db, uid, sh.id)
+    ep = queries.next_episode(db, uid, sh.id, lang=lang)
     return cards.from_plex(ep) if ep else None
 
 
-def continue_watching(db: Session, user: User, limit: int = RAIL_LIMIT) -> list[dict]:
+def continue_watching(db: Session, user: User, limit: int = RAIL_LIMIT, *, lang: str) -> list[dict]:
     """One resume rail across both sources, most recently progressed first.
 
     A Plex SHOW enters as a show CARD — that is what the Plex rail shows, and it is the artwork the
@@ -57,17 +57,22 @@ def continue_watching(db: Session, user: User, limit: int = RAIL_LIMIT) -> list[
         (ts, cards.from_video(r)) for ts, r in queries.yt_in_progress(db, user, limit)
     ]
     if plex_available(db):
-        rows += [(ts, cards.from_plex(c)) for ts, c in queries.plex_in_progress(db, user.id, limit)]
+        rows += [
+            (ts, cards.from_plex(c))
+            for ts, c in queries.plex_in_progress(db, user.id, limit, lang=lang)
+        ]
     rows.sort(key=lambda r: r[0] or NO_TS, reverse=True)
     out = [card for _, card in rows[:limit]]
     # Resolve AFTER the slice: only the rows that survive it are worth a query.
     for card in out:
         if card["kind"] == "show":
-            card["next"] = playable(db, user.id, card)
+            card["next"] = playable(db, user.id, card, lang=lang)
     return out
 
 
-def surprise(db: Session, user: User, budget: str, seed: int, limit: int = 3) -> list[dict]:
+def surprise(
+    db: Session, user: User, budget: str, seed: int, limit: int = 3, *, lang: str
+) -> list[dict]:
     """The hero's draw pool: unseen things that fit the budget, from both sources under ONE seed.
 
     Interleaved rather than concatenated — the same alternation `routes/plex/discover.py` uses for its
@@ -83,7 +88,9 @@ def surprise(db: Session, user: User, budget: str, seed: int, limit: int = 3) ->
         (cards.from_video, queries.yt_surprise(db, user, budget, seed, limit)),
         (
             cards.from_plex,
-            queries.plex_surprise(db, user.id, budget, seed, limit) if plex_available(db) else [],
+            queries.plex_surprise(db, user.id, budget, seed, limit, lang=lang)
+            if plex_available(db)
+            else [],
         ),
     ]
     if seed % 2:

backend/app/downloads/adapters.py

@@ -11,9 +11,22 @@ Resolution works both before extraction (from source_kind / URL host) and after
 `extractor_key` in the info dict), so a non-YouTube "url" job still lands on the right adapter.
 """
 
+import re
 from urllib.parse import urlparse
 
+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.
+FACEBOOK_PARSE_WALL = "cannot parse data"
+# A source's own verdicts on a link, raised from `resolve_url`. errors.py classifies them; it imports
+# them from here because this module must not import errors (errors → credentials → adapters).
+POST_WITHOUT_VIDEO_MESSAGE = "No single video was found in this post."
+POST_NOT_SHOWN_MESSAGE = "Facebook did not show this post to the signed-in session."
 
 
 class SourceAdapter:
@@ -22,9 +35,21 @@ class SourceAdapter:
     key = "generic"
 
     # --- extraction (worker._extract_with_fallback / backfill) ---------------------------------
-    def client_sets(self) -> list:
-        """Player-client sets to attempt, in order. A generic source needs no client override, so a
-        single default attempt (`[None]`) — the per-client fallback is a YouTube-only concept."""
+    def resolve_url(self, url: str, ydl_opts: dict) -> str:
+        """The link to hand yt-dlp for `url`, resolved BEFORE the first attempt. `ydl_opts` are the
+        download's own options (cookie, timeouts, address family) for any page this needs to read.
+
+        Raises a RuntimeError carrying one of this module's verdicts when the page read shows the
+        download cannot go ahead: the content is there but holds no single video
+        (`POST_WITHOUT_VIDEO_MESSAGE`), or the page is not the content at all — the login page a
+        refused cookie gets (`POST_NOT_SHOWN_MESSAGE`), never the no-video verdict. A failed page read
+        is raised as itself, so it is classified like any other download error. Generic: `url`."""
+        return url
+
+    def client_sets(self, authed: bool = False) -> list:
+        """Attempts to make, in order — each entry is handed back to `ydl_opts_extra`, and the next one
+        is tried when `retriable` says so. A generic source makes a single default attempt (`[None]`).
+        `authed` is whether the acting user's cookie file goes with the download."""
         return [None]
 
     def ydl_opts_extra(self, clients) -> dict:
@@ -37,6 +62,10 @@ class SourceAdapter:
         return False
 
     # --- metadata -----------------------------------------------------------------------------
+    def title(self, info: dict) -> str | None:
+        """The download's raw title, before `titles.normalize_title` cleans it. Generic: yt-dlp's."""
+        return info.get("title")
+
     def uploader_url(self, info: dict) -> str | None:
         """The channel/uploader page URL. Generic: whatever yt-dlp exposes directly (YouTube gives
         `channel_url`), else None (reddit / a raw media URL have no derivable channel page)."""
@@ -65,12 +94,46 @@ class YouTubeAdapter(SourceAdapter):
         "Requested format is not available",
         "Only images are available",
         "Sign in to confirm",
+        # Measured 2026-09-16: a gated video whose EXTRACTION succeeds and whose media fetch is then
+        # refused by the CDN ("unable to download video data: HTTP Error 403"). The wall moves
+        # between the player response and the stream, so this is the same per-client flakiness one
+        # step later — and it used to end the job on attempt 1, because the text classifies as
+        # `network` and nothing here matched it. The format URLs belong to the client that minted
+        # them, so the next client set is a real second chance.
+        "unable to download video data",
     )
+    # Measured in the worker against a REAL account cookie (2026-09-16, yt-dlp 2026.07.04): with
+    # `player_client=android_vr` yt-dlp logs `Skipping client "android_vr" since it does not support
+    # cookies`, drops it, and the request that is left with no client fails with "Requested format is
+    # not available" — which is already a retriable marker above, so the cost is a wasted attempt
+    # rather than a hard failure. Our primary set is android_vr ALONE, so without this filter every
+    # signed-in download would burn its first attempt that way before reaching the POT-backed web
+    # fallback the cookie exists for. The list is yt-dlp's own INNERTUBE_CLIENTS[...]
+    # ["SUPPORTS_COOKIES"], pinned by test_adapters against the installed yt-dlp, so a version bump
+    # that moves the table turns the gate red instead of silently un-authing every YouTube download.
+    _COOKIE_CAPABLE = frozenset(
+        {
+            "mweb",
+            "tv",
+            "tv_downgraded",
+            "web",
+            "web_creator",
+            "web_embedded",
+            "web_music",
+            "web_safari",
+        }
+    )
+    # Where a signed-in download lands when the admin's knobs hold no cookie-capable client at all.
+    # Both clients in ONE set: yt-dlp queries each and merges their formats, which is the cover for
+    # the per-client flakiness that the two-tier ladder gives a signed-out download.
+    _AUTHED_DEFAULT = ("web_safari", "web")
 
-    def client_sets(self) -> list:
-        return [
-            c for c in (settings.player_client_list, settings.player_client_fallback_list) if c
-        ] or [None]
+    def client_sets(self, authed: bool = False) -> list:
+        sets = [c for c in (settings.player_client_list, settings.player_client_fallback_list) if c]
+        if authed:
+            kept = [[c for c in s if c in self._COOKIE_CAPABLE] for s in sets]
+            return [s for s in kept if s] or [list(self._AUTHED_DEFAULT)]
+        return sets or [None]
 
     def ydl_opts_extra(self, clients) -> dict:
         # == --extractor-args "youtube:player_client=…;youtubepot-bgutilhttp:base_url=…" (list values).
@@ -93,6 +156,63 @@ class YouTubeAdapter(SourceAdapter):
 
 class FacebookAdapter(SourceAdapter):
     key = "facebook"
+    # Measured (yt-dlp 2026.07.04): with the user's cookie, some reels answer a plain request
+    # with "Cannot parse data" and parse only when the request looks like Chrome. Impersonation is a
+    # SECOND attempt behind that one error, not the default: the links that already download with the
+    # cookie keep their proven path, and only the ones stuck at the wall go through curl_cffi. Without
+    # a cookie the same error is the login wall, which no disguise gets past.
+    _IMPERSONATE = "impersonate"
+    # A post page is ~4–5 MB of inline JSON; anything far past that is not a post page.
+    _POST_PAGE_MAX_BYTES = 16 * 1024 * 1024
+
+    def resolve_url(self, url: str, ydl_opts: dict) -> str:
+        # Measured: given a group post's link, yt-dlp either finds no formats or — worse —
+        # downloads ANOTHER video from the page's feed data. The post's own video is the one Video node
+        # in the page scripts that carry the post id; its watch link downloads (plain first, then the
+        # Chrome retry above). Needs the cookie: signed out, the page is the login wall.
+        post_id = facebook_group_post_id(url)
+        if post_id is None or not ydl_opts.get("cookiefile"):
+            return url
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            raw = ydl.urlopen(url).read(self._POST_PAGE_MAX_BYTES)
+        page = raw.decode("utf-8", "replace")
+        # Measured: 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 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 StatedFailure(POST_WITHOUT_VIDEO_MESSAGE)
+        return f"https://www.facebook.com/watch/?v={video_id}"
+
+    def client_sets(self, authed: bool = False) -> list:
+        return [None, self._IMPERSONATE] if authed else [None]
+
+    def ydl_opts_extra(self, clients) -> dict:
+        if clients == self._IMPERSONATE:
+            return {"impersonate": ImpersonateTarget.from_str("chrome")}
+        return {}
+
+    def retriable(self, error_text: str) -> bool:
+        return FACEBOOK_PARSE_WALL in error_text.lower()
+
+    # Measured (2026-09-14): a SIGNED-IN read gives the placeholder "Video" (plain and as Chrome), and an
+    # 18+ reel only readable as Chrome gives "Facebook"; the post's text is still in `description`. A
+    # signed-out read titles the page with that same text behind the engagement counts, cut short.
+    _PLACEHOLDER_TITLES = frozenset({"video", "facebook"})
+
+    def title(self, info: dict) -> str | None:
+        raw = info.get("title")
+        if (raw or "").strip().lower() not in self._PLACEHOLDER_TITLES:
+            return raw
+        line = next(
+            (ln.strip() for ln in (info.get("description") or "").splitlines() if ln.strip()), ""
+        )
+        # The whole first line, never cut here with an ellipsis: normalize_title's NFKC turns "…" into
+        # "..." and then collapses it to ".", which read as a finished sentence ("… live at."). The
+        # stored title is unbounded; display_name and the file name clip it themselves.
+        return line or raw  # no description either (the 18+ reel): nothing better on the page
 
     def uploader_url(self, info: dict) -> str | None:
         # Facebook gives neither channel_url nor uploader_url, but exposes a numeric `uploader_id`
@@ -107,6 +227,39 @@ class FacebookAdapter(SourceAdapter):
         return True
 
 
+_FB_GROUP_POST_PATH = re.compile(r"^/groups/[^/]+/(?:permalink|posts)/(\d+)/?$")
+_SCRIPT_BLOCK = re.compile(r"<script[^>]*>(.*?)</script>", re.S)
+_VIDEO_NODE = re.compile(r'"__typename":"Video","id":"(\d+)"')
+
+
+def _quoted(post_id: str) -> str:
+    # How the page JSON carries the id: quoted, so a longer id that merely starts with it never counts.
+    return f'"{post_id}"'
+
+
+def facebook_group_post_id(url: str) -> str | None:
+    """The post id of a Facebook group post link (`/groups/<group>/permalink|posts/<id>/`), else None."""
+    parsed = urlparse(url)
+    if not _host_is(parsed.netloc.lower(), "facebook.com"):
+        return None
+    match = _FB_GROUP_POST_PATH.match(parsed.path)
+    return match.group(1) if match else None
+
+
+def facebook_post_video_id(page: str, post_id: str) -> str | None:
+    """The id of the one video attached to `post_id`, read from its page: the Video nodes of the script
+    blocks that carry the post id (the page's other ~10 videos — feed, reels — sit in other blocks).
+    None for no video AND for more than one: guessing between two would be the wrong-video bug again."""
+    quoted = _quoted(post_id)
+    ids = {
+        vid
+        for block in _SCRIPT_BLOCK.findall(page)
+        if quoted in block
+        for vid in _VIDEO_NODE.findall(block)
+    }
+    return ids.pop() if len(ids) == 1 else None
+
+
 class RedditAdapter(SourceAdapter):
     key = "reddit"
 

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

@@ -1,15 +1,17 @@
 """Per-user, per-host download cookies — the single source of truth for "does the acting user's
 cookie apply to this download, and how does that keep the result private".
 
-Two call sites depend on ONE consistent answer (house rule: an invariant lives in shared code, not
+Two sides depend on ONE consistent answer (house rule: an invariant lives in shared code, not
 in prose):
   * `enqueue` salts the MediaAsset cache signature with the user id WHEN a cookie applies, so the
-    authed download becomes a PRIVATE asset that is never cache-served to another user.
+    authed download becomes a PRIVATE asset that is never cache-served to another user. Retry
+    (`service.resume`) and Re-download (`service.redownload`) ask the same question again, so a
+    cookie the user added after a failure goes with the next attempt.
   * the worker attaches the cookie file to yt-dlp ONLY when a cookie still applies AND the asset it
     is downloading into is that private, salted identity — so a cookie can never poison a shared
     asset (the load-bearing cross-user privacy fix).
 
-Both go through `cookie_salt` / `authed_format_sig` / `host_key_for_url` here, so they can't drift.
+Both key the private identity on `cookie_salt` / `host_key_for_url` here, so they can't drift.
 
 Security controls enforced here:
   * **host scope (SEC-12)** — `host_key_for_url` matches the download URL's netloc against a curated
@@ -21,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
+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:
@@ -53,6 +55,11 @@ class HostSpec:
 # all derive from this, so there is nothing else to wire up.
 SUPPORTED_HOSTS: tuple[HostSpec, ...] = (
     HostSpec("facebook", "Facebook", ("facebook.com", "fb.watch")),
+    # YouTube gates INDIVIDUAL videos behind "Sign in to confirm you're not a bot" (measured on prod
+    # job 273: every player client fails on that one video while its neighbours download fine, and
+    # the newest yt-dlp fails the same way — a signed-in session is the only way through). Without a
+    # row here the `login_required` copy sent the user to a dropdown that could not help them.
+    HostSpec("youtube", "YouTube", ("youtube.com", "youtu.be", "youtube-nocookie.com")),
     HostSpec("instagram", "Instagram", ("instagram.com",)),
     HostSpec("twitter", "X (Twitter)", ("twitter.com", "x.com")),
     HostSpec("tiktok", "TikTok", ("tiktok.com",)),
@@ -99,11 +106,38 @@ def cookie_salt(user_id: int, host_key: str) -> str:
 
 
 def authed_format_sig(spec: dict, user_id: int, host_key: str) -> str:
-    """The salted `format_sig` an authed download for (user, host) resolves to — the private asset
-    identity. Both enqueue (to create it) and the worker (to recognise it) compute it HERE."""
+    """The salted `format_sig` an authed download for (user, host) resolves to under the current
+    signature version — the private asset enqueue creates, and one of the identities `is_authed_asset`
+    recognises. Neither calls it; the tests use it to hold the two to each other."""
     return formats.format_sig(spec, salt=cookie_salt(user_id, host_key))
 
 
+def rebuild_salt(asset_id: int, cookie: str | None) -> str:
+    """The salt of a Re-download's fresh asset: its OWN row id (so every rebuild is a new identity no
+    enqueue can ever compute), prefixed with the user's `cookie_salt` when a cookie applies. The id is
+    what makes it recognisable — the worker has the asset row, so `is_authed_asset` can recompute this
+    one, where a salt built from the job's previous asset id could not be."""
+    return f"{cookie}:rebuild:{asset_id}" if cookie else f"rebuild:{asset_id}"
+
+
+def is_authed_asset(asset: MediaAsset, spec: dict, user_id: int, url: str | None) -> bool:
+    """Whether an asset is `user_id`'s private, cookie-salted identity for `url`'s host — the one
+    kind of asset a cookie is ever attached to: the one enqueue creates (`authed_format_sig`), or a
+    Re-download's rebuild of it (`rebuild_salt`). The worker's cookie gate asks it before a download,
+    and the failure diagnosis asks it after one (a failure on this asset happened WITH the cookie).
+    Either signature version counts (`formats.format_sigs`): a job queued before a deploy that bumped
+    the version still downloads into the asset it was given."""
+    host_key = host_key_for_url(url)
+    if host_key is None:
+        return False
+    salt = cookie_salt(user_id, host_key)
+    if asset.format_sig in formats.format_sigs(spec, salt=salt):
+        return True
+    return asset.id is not None and asset.format_sig in formats.format_sigs(
+        spec, salt=rebuild_salt(asset.id, salt)
+    )
+
+
 def salt_for_enqueue(db: Session, user_id: int, url: str | None) -> str | None:
     """At enqueue: the cache salt to apply if this user has a cookie for `url`'s host, else None (a
     normal shared download). Returns the salt string so the caller passes it straight to
@@ -199,43 +233,55 @@ def status_list(db: Session, user_id: int) -> list[dict]:
 # --- worker: resolve + write the cookie file --------------------------------------------------
 
 
-def resolve_cookiefile(
-    db: Session,
-    user_id: int,
-    url: str | None,
-    asset_format_sig: str,
-    spec: dict,
-    staging: Path,
-) -> Path | None:
-    """In the worker child: the cookies.txt to hand yt-dlp for this download, or None.
+def usable_cookie(
+    db: Session, user_id: int, url: str | None, asset: MediaAsset, spec: dict
+) -> str | None:
+    """The user's cookie text a download of `url` into `asset` goes with, or None — the ONE decision
+    whether a download is signed in. The worker child writes it out for yt-dlp (`resolve_cookiefile`);
+    the worker asks it again for a job that inherits a failed asset. That second ask sees the
+    credential as it is when the job is claimed: a cookie the user removed or added since the failed
+    download changes this job's explanation to fit the cookie its Retry would go with.
 
     The double gate that prevents cross-user leakage:
       1. a credential must still exist for `url`'s host (host-scoped via `host_key_for_url`), AND
       2. the asset being downloaded into must BE this user's private, salted identity
-         (`asset_format_sig == authed_format_sig(...)`).
+         (`is_authed_asset`).
 
     If (2) fails the asset is the SHARED (unsalted) one — attaching the cookie would poison the
     global cache with a private-group video, so we attach nothing. An unreadable blob (rotated key →
-    InvalidToken) also yields None; the download then fails honestly on the login wall (S3's
-    `login_required`)."""
+    InvalidToken) also yields None; the download then fails honestly on the login wall (the
+    `login_required` category)."""
     host_key = host_key_for_url(url)
     if host_key is None:
         return None
     cred = get_credential(db, user_id, host_key)
     if cred is None:
         return None
-    if asset_format_sig != authed_format_sig(spec, user_id, host_key):
+    if not is_authed_asset(asset, spec, user_id, url):
         return None  # shared asset — never attach a cookie to a non-private identity
     raw = decrypt_optional(cred.cookies_enc)
     if not raw:
         log.warning(
             "download cookie for user %s host %s could not be decrypted (rotated key?) — "
-            "proceeding without it",
+            "treated as no cookie",
             user_id,
             host_key,
         )
         return None
-    return _write_cookiefile(raw, staging)
+    return raw
+
+
+def resolve_cookiefile(
+    db: Session,
+    user_id: int,
+    url: str | None,
+    asset: MediaAsset,
+    spec: dict,
+    staging: Path,
+) -> Path | None:
+    """In the worker child: the cookies.txt to hand yt-dlp for this download (`usable_cookie`), or None."""
+    raw = usable_cookie(db, user_id, url, asset, spec)
+    return _write_cookiefile(raw, staging) if raw else None
 
 
 def _write_cookiefile(raw: str, staging: Path) -> Path:

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:
@@ -165,6 +188,51 @@ def clip_duration(spec: dict, source_duration: int | None) -> int | None:
 
 # --- ffmpeg: trim / crop --------------------------------------------------------------------
 
+# Every libx264 / aac re-encode in this package uses these, so a re-encoded file is always the
+# phone-safe shape (`playable`): `-pix_fmt yuv420p` pins 8-bit 4:2:0 — without it libx264 keeps a
+# 10-bit or 4:4:4 source's pixel format and writes H.264 High 10 / High 4:4:4, which browsers decode
+# only patchily (the one safe H.264 is 8-bit 4:2:0).
+X264_ARGS = ["-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p"]
+AAC_ARGS = ["-c:a", "aac", "-b:a", "192k"]
+# The last step of every video filter chain a libx264 re-encode runs: 4:2:0 halves the chroma, so
+# libx264 refuses an odd width or height ("width not divisible by 2") — measured on an odd source
+# that is not 4:2:0 already (a 4:4:4 or RGB screen capture, 1365x767). A crop of a 4:2:0 source is
+# rounded to its chroma grid by ffmpeg itself; this holds every other path to the encoder to the same
+# even frame. Rounding down to even costs at most one pixel row/column.
+EVEN_FRAME = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
+
+# The demuxers ffmpeg/ffprobe may use to open a library file — single-file containers only. Without
+# it ffmpeg picks the demuxer from the file's CONTENT and NAME, and an upload's name is the user's:
+# a playlist-type demuxer (HLS, DASH, concat) opens whatever local paths its entries name, so a
+# crafted upload could copy another user's clip or a Plex file into its own converted asset. A file
+# no demuxer here can open fails the probe, and an unprobeable upload is a download-only 'file'.
+MEDIA_DEMUXERS = (
+    "mov",  # mp4, m4a, mov, 3gp
+    "matroska",  # mkv, webm
+    "mpegts",
+    "mpeg",
+    "avi",
+    "asf",
+    "flv",
+    "ogg",
+    "mp3",
+    "aac",
+    "ac3",
+    "eac3",
+    "flac",
+    "wav",
+    "w64",
+    "aiff",
+    "caf",
+    "amr",
+)
+INPUT_GUARD = ["-format_whitelist", ",".join(MEDIA_DEMUXERS)]
+# A downloaded thumbnail is the remote site's bytes under the suffix yt-dlp gave it (`.png`, `.webp`,
+# `.jpg` — `pipeline._THUMB_SUFFIXES`): only the single-image demuxers those open, so a "thumbnail"
+# that is really a playlist cannot pull a local file into the poster. Anything else fails, and the
+# poster falls back to a cut frame (`ensure_poster`).
+THUMB_GUARD = ["-format_whitelist", "png_pipe,jpeg_pipe,webp_pipe"]
+
 
 def build_edit_cmd(src: Path, dest: Path, spec: dict, out_ext: str) -> list[str]:
     """ffmpeg command for a trim/crop edit. `-progress pipe:1` streams machine-readable progress.
@@ -191,7 +259,7 @@ def build_edit_cmd(src: Path, dest: Path, spec: dict, out_ext: str) -> list[str]
     ]
     if start:
         cmd += ["-ss", f"{start:.3f}"]
-    cmd += ["-i", str(src)]
+    cmd += [*INPUT_GUARD, "-i", str(src)]
     if end is not None:
         dur = end - start
         if dur > 0:
@@ -199,21 +267,9 @@ def build_edit_cmd(src: Path, dest: Path, spec: dict, out_ext: str) -> list[str]
 
     if reencode:
         # Input -ss + re-encode is frame-accurate (decodes from the prior keyframe, discards up to
-        # the exact cut). A crop adds the filter; an accurate trim re-encodes with no filter.
-        if crop:
-            cmd += ["-vf", f"crop={crop['w']}:{crop['h']}:{crop['x']}:{crop['y']}"]
-        cmd += [
-            "-c:v",
-            "libx264",
-            "-preset",
-            "veryfast",
-            "-crf",
-            "20",
-            "-c:a",
-            "aac",
-            "-b:a",
-            "192k",
-        ]
+        # the exact cut). A crop adds the filter; an accurate trim only evens the frame.
+        cropf = f"crop={crop['w']}:{crop['h']}:{crop['x']}:{crop['y']}," if crop else ""
+        cmd += ["-vf", cropf + EVEN_FRAME, *X264_ARGS, *AAC_ARGS]
     else:
         cmd += ["-c", "copy", "-avoid_negative_ts", "make_zero"]
 
@@ -261,11 +317,14 @@ def build_concat_plan(src: Path, dest: Path, spec: dict, out_ext: str, staging:
         parts, labels = [], []
         for i, s in enumerate(segs):
             st, en = s["start_s"], s["end_s"]
-            parts.append(f"[0:v]trim=start={st}:end={en},setpts=PTS-STARTPTS{cropf}[v{i}]")
+            parts.append(
+                f"[0:v]trim=start={st}:end={en},setpts=PTS-STARTPTS{cropf},{EVEN_FRAME}[v{i}]"
+            )
             parts.append(f"[0:a]atrim=start={st}:end={en},asetpts=PTS-STARTPTS[a{i}]")
             labels.append(f"[v{i}][a{i}]")
         parts.append(f"{''.join(labels)}concat=n={len(segs)}:v=1:a=1[v][a]")
         cmd = head + [
+            *INPUT_GUARD,
             "-i",
             str(src),
             "-filter_complex",
@@ -274,26 +333,23 @@ def build_concat_plan(src: Path, dest: Path, spec: dict, out_ext: str, staging:
             "[v]",
             "-map",
             "[a]",
-            "-c:v",
-            "libx264",
-            "-preset",
-            "veryfast",
-            "-crf",
-            "20",
-            "-c:a",
-            "aac",
-            "-b:a",
-            "192k",
+            *X264_ARGS,
+            *AAC_ARGS,
         ]
     else:
         listp = staging / "concat.txt"
-        lines = []
+        lines = ["ffconcat version 1.0"]
         for s in segs:
             lines.append(f"file '{_concat_quote(src)}'")
+            # ffmpeg hands the list's whitelist (which must name `concat` to read the list) down to
+            # the file it names, so a library file whose bytes are a concat list would be read as one
+            # and open the paths inside it. Each entry's own whitelist replaces the inherited one.
+            lines.append(f"option format_whitelist {INPUT_GUARD[1]}")
             lines.append(f"inpoint {s['start_s']}")
             lines.append(f"outpoint {s['end_s']}")
         prep[listp] = "\n".join(lines) + "\n"
-        cmd = head + ["-f", "concat", "-safe", "0", "-i", str(listp), "-c", "copy"]
+        guard = ["-format_whitelist", "concat," + INPUT_GUARD[1]]
+        cmd = head + ["-f", "concat", "-safe", "0", *guard, "-i", str(listp), "-c", "copy"]
 
     if out_ext in ("mp4", "m4a", "mov"):
         cmd += ["-movflags", "+faststart"]
@@ -306,11 +362,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 +388,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 +408,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 +425,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)
+        # 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 +471,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 +485,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") from None
     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,17 +504,10 @@ 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 --------------------------------------------------
-# A downloaded file must play in EVERY browser, whatever the source shipped. Universal = H.264
-# video + AAC/MP3 audio in an mp4 container: H.264 is the only video codec all browsers decode
-# (VP9/AV1 fail on Safari/iOS; HEVC fails on Chrome/Firefox), and mp4/AAC is the safe pairing.
-# Anything else is fixed post-download: re-encode the offending stream(s), or just remux when the
-# codecs are already fine but the container isn't.
-_BROWSER_SAFE_VCODEC = ("h264",)
-_BROWSER_SAFE_ACODEC = ("aac", "mp3")
+# --- ffprobe ---------------------------------------------------------------------------------
 
 
 def run_ffprobe_json(
@@ -457,10 +519,10 @@ def run_ffprobe_json(
 ) -> dict | None:
     """One ffprobe call → its parsed JSON dict, or None on any failure (timeout, non-zero exit,
     missing binary, unparseable output). The SINGLE ffprobe-JSON-invocation point in the downloads
-    package: the browser-playability codec probe here and the shared media probe (`probe.probe_media`,
-    used by both the download worker's finalize and the upload ingest) both go through it, so the
+    package: the shared media probe (`probe.probe_json`: the stored facts and the phone-safe rule) goes
+    through it, so the
     subprocess flags/timeout/error handling live in one place instead of drifting copies."""
-    args = ["ffprobe", "-v", "error"]
+    args = ["ffprobe", "-v", "error", *INPUT_GUARD]
     if show_streams:
         args.append("-show_streams")
     if show_format:
@@ -471,39 +533,16 @@ 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
 
 
-def _codecs_from_streams(streams: list) -> tuple[str | None, str | None]:
-    """(video_codec, audio_codec) lowercased from an ffprobe JSON stream list — the first of each kind.
-
-    Parsed from the JSON `streams` list, NOT ffprobe's flat `default=nw=1` output: there the fields
-    arrive in ffprobe's own struct order, which puts `codec_name` BEFORE `codec_type`, so a line-by-line
-    "remember the last codec_type" parser attributes every name to the PREVIOUS stream. Measured on real
-    downloads: an ordinary H.264+AAC mp4 probed as `v=aac a=None` — the browser-playability check then
-    believed the video stream was AAC and re-encoded a perfectly fine file on every download. Reading each
-    stream dict by its own `codec_type` is immune to that ordering."""
-    vcodec = acodec = None
-    for s in streams:
-        name = (s.get("codec_name") or "").lower() or None
-        ctype = (s.get("codec_type") or "").lower()
-        if ctype == "video" and vcodec is None:
-            vcodec = name
-        elif ctype == "audio" and acodec is None:
-            acodec = name
-    return vcodec, acodec
-
-
-def probe_codecs(path: Path) -> tuple[str | None, str | None]:
-    """Return (video_codec, audio_codec) lowercased via one ffprobe call; None for a missing
-    stream or if ffprobe fails (a failed probe is treated as 'leave it alone' upstream)."""
-    data = run_ffprobe_json(path, entries="stream=codec_type,codec_name")
-    if data is None:
-        return None, None
-    return _codecs_from_streams(data.get("streams") or [])
-
-
 def probe_duration(path: Path) -> int:
     """Media duration in whole seconds via ffprobe, or 0 if unknown — a progress denominator for a
     re-encode when the yt-dlp info dict carried no `duration` (some URL/live extractions)."""
@@ -513,6 +552,7 @@ def probe_duration(path: Path) -> int:
                 "ffprobe",
                 "-v",
                 "error",
+                *INPUT_GUARD,
                 "-show_entries",
                 "format=duration",
                 "-of",
@@ -525,53 +565,16 @@ 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
 
 
-def browser_transcode_flags(
-    vcodec: str | None, acodec: str | None, is_mp4: bool
-) -> tuple[bool, bool, bool]:
-    """Decide what (if anything) makes a file universally browser-playable. Returns
-    (needs_change, reencode_video, reencode_audio). needs_change=False => already H.264 + AAC/MP3
-    in mp4. A None codec (no such stream, or a failed probe) is never re-encoded."""
-    rv = bool(vcodec) and vcodec not in _BROWSER_SAFE_VCODEC
-    ra = bool(acodec) and acodec not in _BROWSER_SAFE_ACODEC
-    return (rv or ra or not is_mp4), rv, ra
-
-
-def build_browser_safe_cmd(
-    src: Path, dest: Path, reencode_video: bool, reencode_audio: bool, threads: int | None = None
-) -> list[str]:
-    """ffmpeg command that lands `src` as a browser-safe mp4 (faststart): re-encode only the
-    stream(s) that need it (libx264 / aac), stream-copy the rest, always into mp4. `-progress
-    pipe:1` streams machine-readable progress for run_ffmpeg. `threads` caps the encoder so a
-    re-encode can't claim every core on the shared box (see the worker-child de-prioritization)."""
-    cmd = [
-        "ffmpeg",
-        "-y",
-        "-hide_banner",
-        "-loglevel",
-        "error",
-        "-nostdin",
-        "-progress",
-        "pipe:1",
-        "-nostats",
-        "-i",
-        str(src),
-    ]
-    cmd += (
-        ["-c:v", "libx264", "-preset", "veryfast", "-crf", "20"]
-        if reencode_video
-        else ["-c:v", "copy"]
-    )
-    cmd += ["-c:a", "aac", "-b:a", "192k"] if reencode_audio else ["-c:a", "copy"]
-    if threads and threads > 0:
-        cmd += ["-threads", str(threads)]
-    cmd += ["-movflags", "+faststart", str(dest)]
-    return cmd
-
-
 # --- filmstrip (editor scrub track) ---------------------------------------------------------
 
 _SB_COLS = 12
@@ -607,6 +610,7 @@ def build_storyboard_cmd(src: Path, dest: Path, duration_s: int | None, geom: di
         "-loglevel",
         "error",
         "-nostdin",
+        *INPUT_GUARD,
         "-i",
         str(src),
         "-frames:v",
@@ -630,6 +634,7 @@ def build_poster_cmd(src: Path, dest: Path, at_s: float) -> list[str]:
         "-nostdin",
         "-ss",
         f"{max(0.0, at_s):.3f}",
+        *INPUT_GUARD,
         "-i",
         str(src),
         "-frames:v",
@@ -651,6 +656,7 @@ def build_thumbnail_jpg_cmd(src: Path, dest: Path) -> list[str]:
         "-loglevel",
         "error",
         "-nostdin",
+        *THUMB_GUARD,
         "-i",
         str(src),
         "-frames:v",
@@ -670,15 +676,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)."""
+    """True if the file starts with the JPEG SOI marker (0xFF 0xD8 0xFF)."""
     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 +718,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 +751,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 +782,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/errors.py

@@ -1,4 +1,5 @@
-"""Classify a raw yt-dlp / ffmpeg failure string into a stable category code.
+"""Classify a raw yt-dlp / ffmpeg failure string into a stable category code — and, where a site's
+failure has been measured, into that site's entry of the failure catalog.
 
 The worker stores the raw exception text (truncated) for technical detail, but a raw
 `ERROR: [youtube] <id>: Private video. Sign in…` is noise to a user. `classify()` maps that text
@@ -6,22 +7,53 @@ to one of a small set of category codes; the frontend turns the code into a loca
 explanation (and decides whether a retry makes sense). The raw text stays available behind a
 "details" disclosure. This is the same string-matching approach the worker already trusts for
 `_RETRIABLE_MARKERS` — kept here as the single source of truth for "what kind of failure is this".
+
+**The failure catalog** (`_CATALOG`). A category is generic: "Sign-in required" cannot tell a
+Facebook user that the cookie they already gave was refused, and yt-dlp words several different
+Facebook walls identically (`Cannot parse data`). A catalog entry is scoped to ONE host and may also
+depend on whether a cookie was attached and on the kind of link, and names a `detail` code the UI has
+its own sentence for — why it failed on that site, and what the user can do. `diagnose()` tries the
+catalog first and falls back to the category. How an entry is added, every time a failure is reported:
+  1. reproduce it on dev (with and without the user's cookie) and keep the verbatim yt-dlp text;
+  2. add the entry below, scoped as narrowly as the measurement allows (a marker that is yt-dlp's
+     generic wording for every site must never match without its host; a marker another module also
+     decides on — the Facebook Chrome retry's FACEBOOK_PARSE_WALL — is imported, never retyped);
+  3. pin the real text in `tests/test_download_errors.py`;
+  4. add `downloads.errors.fail.catalog.<detail>.{short,body}` in EN and HU (a contract test checks it;
+     the group is not called `detail`, which `actionErrors.contract` reads as a raw `HttpError.detail`).
 """
 
-# Two worker-authored strings that this module owns because both are coupled to `_RULES`.
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import NamedTuple
+
+from app.downloads.adapters import (
+    FACEBOOK_PARSE_WALL,
+    POST_NOT_SHOWN_MESSAGE,
+    POST_WITHOUT_VIDEO_MESSAGE,
+    facebook_group_post_id,
+)
+from app.downloads.credentials import host_key_for_url
+
+# Worker-authored strings that this module owns because each is coupled to `_RULES`.
 #
 # QUOTA_FULL_MESSAGE is raised by the worker and must classify back to `quota_exceeded`; its rule
 # below matches a fragment of it, and test_download_errors pins the pair, because a message and its
 # rule drifting apart is exactly how a category silently becomes unreachable.
 #
-# NETWORK_REDACTED_MESSAGE is the opposite direction: it REPLACES a message after classification, so
-# it deliberately has no rule. Nothing re-classifies a stored `job.error` today; if anything ever
-# does, it must carry the original code rather than re-deriving one from this text.
+# NETWORK_REDACTED_MESSAGE REPLACES a message after classification (`user_error_text`). It is written
+# to the shared asset too, and a second job that inherits that failed asset re-diagnoses the stored
+# text (`worker._process_job`), so it has a rule of its own that gives the category back.
 #
 # Other worker-raised texts are still inline literals at their raise sites. The ffmpeg ones and
 # "produced no output file" have markers here; the urlguard refusal deliberately has none and
 # classifies as `unknown` — it is a refusal, not a diagnosis, and no category would say more.
+#
+# A source adapter's verdicts on a link (`SourceAdapter.resolve_url`) are adapters.py's
+# constants, imported above; each has a rule below that gives its category back, and a catalog entry
+# that gives the site's sentence.
 QUOTA_FULL_MESSAGE = "Your download storage is full — free up space, then try again."
+UPLOAD_MISSING_MESSAGE = "The uploaded file is missing."
 NETWORK_REDACTED_MESSAGE = "The server could not reach that address."
 
 # (marker, category) — first match wins, so order most-specific → most-general. Matching is
@@ -30,6 +62,12 @@ _RULES: tuple[tuple[str, str], ...] = (
     # Our own refusal: the worker found the user already at their storage cap (SEC-13). Placed
     # first — it is our wording, so it can never be a false match on an upstream message.
     ("download storage is full", "quota_exceeded"),
+    # Our own redaction of a transport failure (see NETWORK_REDACTED_MESSAGE) — our wording too.
+    (NETWORK_REDACTED_MESSAGE.lower(), "network"),
+    # Our own verdicts on a post link (adapters.py) — our wording too: its page holds no single video,
+    # or the site answered the signed-in read with something that is not the post at all.
+    (POST_WITHOUT_VIDEO_MESSAGE.lower(), "format_unavailable"),
+    (POST_NOT_SHOWN_MESSAGE.lower(), "login_required"),
     # Login / age / members / bot-check — the user must be signed in (we deliberately are not).
     ("sign in to confirm your age", "login_required"),
     ("confirm your age", "login_required"),
@@ -61,6 +99,8 @@ _RULES: tuple[tuple[str, str], ...] = (
     # An edit's source download went away — our own wording, and MORE specific than the generic
     # "no longer available" below, so it must be matched first.
     ("source download is no longer available", "source_missing"),
+    # An upload's original went away before its conversion ran — our wording (UPLOAD_MISSING_MESSAGE).
+    (UPLOAD_MISSING_MESSAGE.lower().rstrip("."), "upload_missing"),
     ("source file is missing", "source_missing"),
     # Private / deleted / removed / terminated.
     ("private video", "unavailable"),
@@ -101,6 +141,120 @@ _RULES: tuple[tuple[str, str], ...] = (
 )
 
 
+class Diagnosis(NamedTuple):
+    """What a failure was: the generic `code` (category) and, when a catalog entry matched, its
+    host-specific `detail`."""
+
+    code: str
+    detail: str | None = None
+
+
+@dataclass(frozen=True)
+class _Entry:
+    """One measured failure of one site. It matches when the download URL belongs to `host`
+    (`credentials.SUPPORTED_HOSTS`), every one of `markers` is in the message, the cookie state is
+    `cookie` (None: either), and — when `link` is given — it recognises the URL (a truthy result). A
+    link predicate is the adapter's own, so the catalog and the download agree on what a link is."""
+
+    host: str
+    markers: tuple[str, ...]
+    code: str
+    detail: str
+    cookie: bool | None = None
+    link: Callable[[str], object] | None = None
+
+
+_CATALOG: tuple[_Entry, ...] = (
+    # Facebook answers a signed-out client with a page yt-dlp cannot parse — an 18+ reel, a closed
+    # group's post (measured 2026-09-13: prod jobs 145, 156, 256 download once the owner's cookie is
+    # attached). "Cannot parse data" is yt-dlp's generic wording for a broken extractor on EVERY site,
+    # which is why the entry is scoped to Facebook and never becomes a general rule.
+    _Entry(
+        host="facebook",
+        markers=("[facebook]", FACEBOOK_PARSE_WALL),
+        code="login_required",
+        detail="facebook.login_wall",
+        cookie=False,
+    ),
+    # The same text WITH a cookie: an expired / signed-out cookie, or a page that also needs
+    # impersonation (prod job 257). Telling this user to add cookies would be wrong — they have.
+    _Entry(
+        host="facebook",
+        markers=("[facebook]", FACEBOOK_PARSE_WALL),
+        code="login_required",
+        detail="facebook.cookie_rejected",
+        cookie=True,
+    ),
+    # A group post read with a cookie that Facebook answered with its login page (measured with a
+    # refused cookie: no post id anywhere on the page) — the same refused cookie, found by the adapter.
+    _Entry(
+        host="facebook",
+        markers=(POST_NOT_SHOWN_MESSAGE.lower(),),
+        code="login_required",
+        detail="facebook.cookie_rejected",
+        cookie=True,
+    ),
+    # A group post with no single video of its own. With a cookie the adapter reads the post's page
+    # and says so itself (POST_WITHOUT_VIDEO_MESSAGE); without one yt-dlp is given the post link and
+    # answers "No video formats found" (measured on prod jobs 66 and 145, whose videos are reshared
+    # clips). With a cookie yt-dlp only ever gets the post's VIDEO link, so the same text there is about
+    # that video, not the post — the category says it. Only for group post links (the adapter's own
+    # test of one): a reel with no formats is a different failure.
+    _Entry(
+        host="facebook",
+        markers=(POST_WITHOUT_VIDEO_MESSAGE.lower(),),
+        code="format_unavailable",
+        detail="facebook.group_post_video",
+        link=facebook_group_post_id,
+    ),
+    _Entry(
+        host="facebook",
+        markers=("[facebook]", "no video formats found"),
+        code="format_unavailable",
+        detail="facebook.group_post_video",
+        cookie=False,
+        link=facebook_group_post_id,
+    ),
+    # YouTube gates INDIVIDUAL videos behind "Sign in to confirm you're not a bot" (measured on prod
+    # job 273, a festival set: all 12 of yt-dlp's player clients fail on that one video while its
+    # neighbours download fine, the POT sidecar is live and answering, and the newest yt-dlp fails
+    # identically — so this is the video's own signed-out gate, not a broken stack or a stale yt-dlp).
+    # The marker is quote-agnostic on purpose: YouTube writes the apostrophe as U+2019, so
+    # "you're not a bot" with a straight quote never matches the real text.
+    _Entry(
+        host="youtube",
+        markers=("[youtube]", "not a bot"),
+        code="login_required",
+        detail="youtube.bot_wall",
+        cookie=False,
+    ),
+    # The same wall WITH a cookie. Not yet reproduced with a real YouTube cookie (this user's first
+    # one is being added now) — but "add cookies" is provably the wrong advice for someone who has,
+    # and yt-dlp names the likeliest cause itself: "The provided YouTube account cookies are no
+    # longer valid. They have likely been rotated in the browser as a security measure."
+    _Entry(
+        host="youtube",
+        markers=("[youtube]", "not a bot"),
+        code="login_required",
+        detail="youtube.cookie_rejected",
+        cookie=True,
+    ),
+    # The same gate one step later: the player response comes back, and then the CDN refuses the
+    # stream itself ("unable to download video data: HTTP Error 403"). Measured 2026-09-16 on the
+    # very same video, ~90 minutes after it was answering with the bot message — signed out it
+    # 403'd on every attempt; with the owner's cookie attached it downloaded in full (519 MB). So
+    # the category this text carries generically, `network`, is a lie here: nothing was wrong with
+    # the network. Scoped to a cookie-less YouTube download, where that is what we measured.
+    _Entry(
+        host="youtube",
+        markers=("unable to download video data", "403"),
+        code="login_required",
+        detail="youtube.media_forbidden",
+        cookie=False,
+    ),
+)
+
+
 def classify(msg: str | None) -> str:
     """Return a category code for a raw failure message (``"unknown"`` if nothing matches)."""
     if not msg:
@@ -112,6 +266,36 @@ def classify(msg: str | None) -> str:
     return "unknown"
 
 
+def classify_conversion(msg: str | None) -> str:
+    """The category of an upload's failed conversion. The generic ffmpeg categories speak of a
+    download ("the video downloaded but…"), which an upload never was: a failed encode or an
+    unrecognised failure of one is `convert_failed`; a category of its own (a full quota, a missing
+    original) stays as it is."""
+    code = classify(msg)
+    return "convert_failed" if code in ("postprocess", "unknown") else code
+
+
+def diagnose(
+    msg: str | None, *, url: str | None = None, cookie_attached: bool = False
+) -> Diagnosis:
+    """The catalog entry for this failure of this link, else just its category (see the module doc).
+
+    `url` is the address yt-dlp was given; `cookie_attached` whether the acting user's cookie went
+    with it. Without a URL only the category can be known."""
+    host = host_key_for_url(url) if msg and url else None
+    if host is not None:
+        low = msg.lower()  # type: ignore[union-attr] — `host` is only set when `msg` is truthy
+        for e in _CATALOG:
+            if (
+                e.host == host
+                and all(m in low for m in e.markers)
+                and (e.cookie is None or e.cookie == cookie_attached)
+                and (e.link is None or e.link(url))  # type: ignore[arg-type] — as `msg` above
+            ):
+                return Diagnosis(e.code, e.detail)
+    return Diagnosis(classify(msg))
+
+
 def user_error_text(source_kind: str, msg: str, code: str) -> str:
     """The failure text to STORE on the job, given the raw message and its category.
 

backend/app/downloads/formats.py

@@ -13,12 +13,138 @@ spec shape (all keys optional; defaults + browser-playability clamp applied by `
     vcodec         always coerced to null → H.264 selected (see `normalize`); no opt-out
     embed_subs     bool     embed_chapters bool     embed_thumbnail bool     sponsorblock bool
 
-`normalize` clamps container/vcodec/audio_format so EVERY download plays in-browser (E7); the
+`normalize` clamps container/vcodec/audio_format so EVERY download plays in-browser; the
 `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 = (
@@ -56,7 +182,13 @@ _DEFAULTS = {
 # v4: EVERY download is clamped to the mp4/H.264/AAC compat profile (no more mkv/webm/VP9/AV1/Opus
 # opt-out), so any asset cached under an old non-compat spec — or a stale non-H.264 mp4 that slipped
 # the v3 net — must re-derive through the current browser-safe guarantee.
-_SIG_VERSION = 4
+# v5: the phone-safe rule (`playable`) also judges the pixel format, so a cached 10-bit / 4:4:4 H.264
+# asset (which v4 let through as "H.264") re-derives as 8-bit 4:2:0 instead of being reused.
+_SIG_VERSION = 5
+# Audio-only downloads version on their own, so a change to the audio bytes doesn't re-download every
+# cached video. v5: an extracted .mp3/.m4a is stored as itself instead of remuxed into an .mp4 that
+# iPad's WebKit refuses to play, so a cached remuxed audio asset must re-derive.
+_AUDIO_SIG_VERSION = 5
 
 _SPONSORBLOCK_CATEGORIES = ["sponsor", "selfpromo", "interaction"]
 
@@ -74,21 +206,28 @@ 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])
     # Audio-only files can't embed subtitles/thumbnails as video; keep the flags meaningful.
     if s["mode"] == "a":
         s["embed_subs"] = False
-    # Browser-playability guarantee (E7): the Download module exists to download → share → PLAY
+    # Browser-playability guarantee: the Download module exists to download → share → PLAY
     # in-browser, so every output must play in EVERY browser, iOS/Safari/WebKit included. The only
-    # universally-safe combo is mp4 + H.264 + AAC/MP3, so we CLAMP the spec to it HERE — the single
-    # point every path (picker, stored profile, raw API) flows through — instead of only hiding
-    # options in the UI. Non-mp4 containers (mkv doesn't play at all; webm/VP9/AV1 fail iOS) and any
-    # explicit vcodec are coerced to the compat profile; Opus audio (Safari-flaky as a bare file)
-    # falls back to AAC/m4a. A source that exposes no H.264 is still caught by the worker's
-    # browser-safe re-encode (`_ensure_browser_playable`), so playback is guaranteed end-to-end.
+    # universally-safe combo is mp4 + H.264 + AAC (an .mp3/.m4a for audio), so we CLAMP the spec to
+    # it HERE — the single point every path (picker, stored profile, raw API) flows through — instead
+    # of only hiding options in the UI. Non-mp4 containers (mkv plays nowhere on iOS; AV1 fails there,
+    # and webm/VP9 plays only on recent devices) and any explicit vcodec are coerced to the compat
+    # profile; Opus audio falls back to AAC/m4a. A source that exposes no H.264 (or a 10-bit one) is
+    # still caught by the worker's phone-safe step (`downloads.playable`), so playback is guaranteed
+    # end-to-end.
     s["container"] = "mp4"
     s["vcodec"] = None
     if s["audio_format"] not in ("m4a", "mp3"):
@@ -96,20 +235,34 @@ def normalize(spec: dict) -> dict:
     return s
 
 
-def format_sig(spec: dict, salt: str | None = None) -> str:
+def _sig_version(s: dict) -> int:
+    return _AUDIO_SIG_VERSION if s["mode"] == "a" else _SIG_VERSION
+
+
+def format_sig(spec: dict, salt: str | None = None, *, version: int | None = None) -> str:
     """Stable short hash of the output-affecting spec — the MediaAsset cache key component.
 
     `salt` forks a distinct, non-dedup identity for the same spec (used by force-redownload so it
-    always re-fetches into its own asset instead of sharing a cached file with other jobs)."""
+    always re-fetches into its own asset instead of sharing a cached file with other jobs).
+    `version` hashes under a signature version other than the current one (see `format_sigs`)."""
     s = normalize(spec)
     data = {k: s[k] for k in _SIG_KEYS}
-    data["_v"] = _SIG_VERSION
+    data["_v"] = _sig_version(s) if version is None else version
     if salt is not None:
         data["_salt"] = salt
     payload = json.dumps(data, sort_keys=True, separators=(",", ":"))
     return hashlib.sha256(payload.encode()).hexdigest()[:24]
 
 
+def format_sigs(spec: dict, salt: str | None = None) -> tuple[str, str]:
+    """`format_sig` under the current signature version and under the one before it. An asset keeps
+    the signature it was created with, so a job queued before a deploy that bumped the version and
+    run after it downloads into an asset carrying the previous one — which must still be recognised
+    as that user's private asset (`credentials.is_authed_asset`), or it downloads without its cookie."""
+    previous = _sig_version(normalize(spec)) - 1
+    return format_sig(spec, salt), format_sig(spec, salt, version=previous)
+
+
 def build_ydl_opts(
     spec: dict,
     outtmpl: str,
@@ -124,7 +277,7 @@ def build_ydl_opts(
     `extractor_args` with the player-client set + bgutil PO-token base_url); it is merged onto the
     generic options below. Everything here is source-agnostic.
 
-    `cookiefile` is the acting user's per-host cookies.txt path (S6), attached ONLY by the worker
+    `cookiefile` is the acting user's per-host cookies.txt path, attached ONLY by the worker
     after the host-scope + private-asset gate in `downloads.credentials`. It is set AFTER the `extra`
     merge so a source adapter can never clobber it.
 
@@ -163,6 +316,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.
     #
@@ -173,7 +332,7 @@ def build_ydl_opts(
     if max_bytes and max_bytes > 0:
         opts["max_filesize"] = max_bytes
 
-    # The acting user's per-host cookie (S6). AFTER the adapter merge on purpose: an adapter must not
+    # The acting user's per-host cookie. AFTER the adapter merge on purpose: an adapter must not
     # be able to override the authenticated session the worker resolved for this specific user.
     if cookiefile:
         opts["cookiefile"] = cookiefile
@@ -195,7 +354,7 @@ def build_ydl_opts(
         # inside mp4 — a VP9/AV1-in-mp4 file shows a broken player there — so H.264 is selected at the
         # SELECTION level, not merely preferred: a sort key can't conjure an H.264 stream a source
         # doesn't expose as video-only. A source that ships only non-H.264 is caught after download by
-        # the worker's browser-safe re-encode (`_ensure_browser_playable`).
+        # the worker's phone-safe step (`downloads.playable`).
         if s["mode"] == "v":
             # Video-only: keep it audio-free. Prefer an H.264 video-only stream, then any video-only,
             # and only fall to a progressive (audio-bearing) `best` as a last resort.

backend/app/downloads/gc.py

@@ -6,35 +6,34 @@ Five passes each run:
   2. Expiry deletion — delete assets past their TTL (files + row). The FK SET NULL nulls the
      holders' jobs' asset_id, so those jobs surface as "expired" (re-downloadable) in the UI.
   3. LRU eviction — if a total cache cap is set and exceeded, delete least-recently-accessed
-     ready assets until back under it.
+     ready assets (never an upload) until back under it.
   4. Orphan reap — delete errored, fileless, unreferenced asset rows (they carry no TTL, so
      passes 1-3 skip them; benign row-count hygiene).
   5. Orphan FILE sweep — delete on-disk files/dirs no surviving asset owns (cruft left when a
-     re-download renames an asset, e.g. old accented channel dirs), skipping system trees and
-     anything newer than an hour so an in-flight download is never touched.
+     re-download renames an asset, e.g. old accented channel dirs, or an upload's stranded file).
+     It skips the dot-prefixed system trees (all but `.uploads`) and anything newer than an hour,
+     so an in-flight download is never touched.
 
 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
 
-from sqlalchemy import func, select
+from sqlalchemy import func, or_, 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.downloads import quota, storage
 from app.models import DownloadJob, MediaAsset
 from app.notifications import create_notification
 
-log = logging.getLogger("siftlode.downloads.gc")
-
-# 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"}
+log = logs.get_logger(__name__)
+# The one dot-prefixed top-level tree the orphan sweep enters. The others are not part of the asset
+# layout (user clips, Plex HLS/img caches, in-progress staging, editor storyboards) and are skipped.
+_UPLOAD_TREE = ".uploads"
 _ORPHAN_MIN_AGE_S = 3600  # only sweep files older than this, so an in-flight download is never hit
 
 
@@ -69,16 +68,20 @@ def _delete_asset(db: Session, asset: MediaAsset, ntype: str) -> None:
 def _sweep_orphan_files(db: Session, download_root: str) -> int:
     """Delete media/sidecar files (and now-empty dirs) under DOWNLOAD_ROOT that no `ready` asset
     owns — cruft left when a re-download changes an asset's on-disk name (e.g. an old accented
-    channel dir, or a poster from a superseded naming scheme). Skips the dot-prefixed system trees
-    and only removes files older than `_ORPHAN_MIN_AGE_S`, so a just-completed or in-flight download
-    is never deleted, and only files NOT owned by a surviving asset."""
+    channel dir, or a poster from a superseded naming scheme) — or, under `.uploads`, that no upload
+    row names at all. Skips the other dot-prefixed system trees and only removes files older than
+    `_ORPHAN_MIN_AGE_S`, so a just-completed or in-flight download is never deleted, and only files
+    NOT owned by a surviving asset."""
     root = Path(download_root)
     if not root.is_dir():
         return 0
     keep: set[Path] = set()
+    # An upload's file is on disk from ingest on, whatever its state (a queued conversion's original,
+    # a failed one kept for Retry), so every upload row keeps its file — not only a ready one.
     for rel in db.execute(
         select(MediaAsset.rel_path).where(
-            MediaAsset.status == "ready", MediaAsset.rel_path.is_not(None)
+            or_(MediaAsset.status == "ready", MediaAsset.source_kind == "upload"),
+            MediaAsset.rel_path.is_not(None),
         )
     ).scalars():
         media = (root / rel).resolve()
@@ -99,8 +102,12 @@ 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
+        # .edits / .plex-* / .staging / .storyboards + any dotfile — but `.uploads` is swept: a
+        # conversion stopped between placing the new file and the commit that points at it (or the
+        # unlink of the original after it) leaves a file no row names, and nothing else finds it.
+        if entry.name.startswith(".") and entry.name != _UPLOAD_TREE:
             continue
         files = [entry] if entry.is_file() else [p for p in entry.rglob("*") if p.is_file()]
         for f in files:
@@ -111,7 +118,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 +129,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
 
 
@@ -179,17 +196,17 @@ def run_download_gc(db: Session) -> dict:
     if cap > 0:
         total = (
             db.execute(
-                select(func.coalesce(func.sum(MediaAsset.size_bytes), 0)).where(
-                    MediaAsset.status == "ready"
-                )
+                select(func.coalesce(func.sum(MediaAsset.size_bytes), 0)).where(quota.ON_DISK)
             ).scalar()
             or 0
         )
         if total > cap:
+            # An upload counts toward the total (it is disk like any other) but is never evicted:
+            # it has no source to fetch again, and it lives until its owner deletes it.
             candidates = (
                 db.execute(
                     select(MediaAsset)
-                    .where(MediaAsset.status == "ready")
+                    .where(MediaAsset.status == "ready", MediaAsset.source_kind != "upload")
                     .order_by(MediaAsset.last_access_at.asc().nulls_first())
                 )
                 .scalars()
@@ -223,6 +240,29 @@ def run_download_gc(db: Session) -> dict:
     if orphans:
         db.commit()
 
+    # 4b. Reap unheld uploads. An upload carries no expires_at, is never evicted and never re-enqueued,
+    #     so the passes above never free one that lost its last holder outside `release_asset` — a
+    #     conversion that finished after its job was cancelled, or one cancelled mid-run (the asset
+    #     was `downloading` then). Its file, ready or still the unconverted original, is at `rel_path`.
+    unheld = (
+        db.execute(
+            select(MediaAsset).where(
+                MediaAsset.source_kind == "upload",
+                MediaAsset.ref_count == 0,
+                MediaAsset.status != "downloading",
+            )
+        )
+        .scalars()
+        .all()
+    )
+    for asset in unheld:
+        if asset.rel_path:  # no holder is left to tell, so no notice — just the file and the row
+            storage.delete_asset_files(settings.download_root, asset.rel_path)
+        db.delete(asset)
+        reaped += 1
+    if unheld:
+        db.commit()
+
     # 5. Orphan FILE sweep — remove on-disk cruft no surviving asset owns (old accented dirs, stale
     #    posters). Runs last so the keep-set reflects the assets that survived passes 2-4.
     swept = _sweep_orphan_files(db, settings.download_root)

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
 
@@ -145,13 +147,14 @@ def _watch_tags(token: str, db: Session) -> str | None:
     return "\n    ".join(tags)
 
 
-def render_watch_html(token: str, index_html: Path, db: Session) -> str | None:
-    """Return index.html with the OG block replaced for this watch token, or None to serve the
-    generic page unchanged (invalid/expired/not-ready link, or a template without the markers)."""
+def render_watch_html(token: str, page_html: Path, db: Session) -> str | None:
+    """Return the watch page (watch.html) with the OG block replaced for this token, or None to
+    serve the generic page unchanged (invalid/expired/not-ready link, or a template without the
+    markers)."""
     tags = _watch_tags(token, db)
     if tags is None:
         return None
-    text = index_html.read_text(encoding="utf-8")
+    text = page_html.read_text(encoding="utf-8")
     if "<!--OG:START-->" not in text:
         return None
     # A function replacement avoids re.sub interpreting backslashes/group refs in `tags`.

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
@@ -8,14 +7,14 @@ from datetime import date, datetime, timedelta, timezone
 from pathlib import Path
 
 import yt_dlp
-from sqlalchemy import select
 
-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
 from app.downloads import errors as dlerrors
-from app.downloads import adapters, credentials, formats, mediakind, probe, quota, service, storage
+from app.downloads import adapters, credentials, formats, mediakind, playable, probe, quota
+from app.downloads import service, storage
 from app.downloads import urlguard
 from app.downloads.jobdb import (
     _edit_staging_dir,
@@ -25,12 +24,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.models import DISPLAY_TEXT_MAX, 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):
@@ -59,6 +59,10 @@ _DB_WRITE_INTERVAL_S = 1.0
 _CANCEL_POLL_INTERVAL_S = 1.0
 
 _THUMB_SUFFIXES = (".jpg", ".jpeg", ".png", ".webp")
+# The job phase while a file is brought into the phone-safe shape (`_ensure_phone_safe`) for a
+# download or an upload. Its own word, not yt-dlp's "processing": it reports ffmpeg's real progress,
+# so the queue row shows a % for it, where yt-dlp's post-steps only get an indeterminate pulse.
+CONVERTING = "converting"
 # yt-dlp's working files in the staging dir. None of them is ever the finished media, but several
 # CAN be the biggest file there (a video-only per-format stream, an abandoned fragment run), so the
 # staging fallback must exclude them by name — picking one would store e.g. a silent video-only
@@ -74,9 +78,9 @@ _YTDLP_TEMP_RE = re.compile(
 
 def _notify_download_done(db, user_id: int | None, title: str | None, job_id, *, kind: str) -> None:
     """Post a best-effort 'ready' notice to the owner's inbox — downloads/edits used to finish
-    silently while scheduler jobs and playlist-push already notified (R11 feedback symmetry). A
+    silently while scheduler jobs and playlist-push already notified (feedback symmetry). A
     notification failure must never mask the completed job, so it is isolated + rolled back (mirrors
-    scheduler._notify_done). `kind` ("download"/"edit") lets the inbox pick accurate copy; the
+    scheduler._notify_done). `kind` ("download"/"edit"/"upload") lets the inbox pick accurate copy; the
     English title here is only a fallback for an unknown type. `user_id`/`title` are captured by the
     caller BEFORE its commit, so reading them here needs no post-commit refresh of an expired row."""
     if user_id is None:
@@ -99,6 +103,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
 
@@ -114,9 +120,10 @@ def _fill_asset_meta_early(asset_id: int, info: dict) -> None:
         # `or info.get("id")` avoids a blank card while downloading when the cleaned title is empty
         # (e.g. a title that was only a social engagement prefix); the completion path later sets
         # the final title with its own source_ref fallback.
-        asset.title = normalize_title(info.get("title")) or info.get("id")
+        adapter = adapters.resolve_adapter(None, None, info)
+        asset.title = normalize_title(adapter.title(info)) or info.get("id")
         asset.uploader = info.get("uploader") or info.get("channel")
-        asset.uploader_url = adapters.resolve_adapter(None, None, info).uploader_url(info)
+        asset.uploader_url = adapter.uploader_url(info)
         asset.thumbnail_url = info.get("thumbnail")
         asset.duration_s = int(info["duration"]) if info.get("duration") else None
         asset.upload_date = _parse_upload_date(info.get("upload_date"))
@@ -138,7 +145,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():
@@ -210,7 +224,7 @@ def _ffmpeg_progress_writer(job_id: int, phase: str, *, now=time.monotonic):
     when the whole-percent value changed (the bar shows integers), plus a separate once-per-interval
     heartbeat while the percent is stuck (so a slow re-encode isn't mistaken for a stall)."""
     # Progress writes have their OWN 1/interval budget so a heartbeat can never delay a real write (the
-    # round-1 concern). The heartbeat, in turn, is gated on `last_touch` — the last DB write OR beat —
+    # original concern). The heartbeat, in turn, is gated on `last_touch` — the last DB write OR beat —
     # so a progress write (which already refreshes updated_at) suppresses a redundant heartbeat that
     # same interval, keeping active downloads at ~1 write/interval, not two.
     allow_write = _rate_limiter(_DB_WRITE_INTERVAL_S, now=now)
@@ -299,7 +313,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)
 
 
@@ -323,14 +337,33 @@ def _extract_with_fallback(
 ):
     """Download via yt-dlp using the source `adapter`'s client sets + options. For YouTube the adapter
     supplies the primary player-client set then a POT-backed fallback (retried on a bot/DRM/format
-    error); other sources make a single attempt. Returns the info dict of the successful attempt.
+    error); a Facebook download WITH a cookie is retried as Chrome behind "Cannot parse data"; other
+    sources make a single attempt. Returns the info dict of the successful attempt.
 
-    `cookiefile` (S6) is the acting user's per-host cookies.txt, already gated by
+    Before the first attempt the adapter may resolve `url` to the link that really holds the video (a
+    Facebook group post → its video's watch link); when the page shows no single video there, or is not
+    the post at all (a refused cookie's login page), the adapter raises its own verdict
+    (adapters.POST_*_MESSAGE) instead of letting yt-dlp guess, and a failed page read fails the
+    download as itself.
+
+    `cookiefile` is the acting user's per-host cookies.txt, already gated by
     `credentials.resolve_cookiefile`; passed to every attempt so the fallback stays authenticated.
 
     `max_bytes` (SEC-13) is the owner's remaining storage budget, applied to every attempt."""
-    client_sets = adapter.client_sets()
+    client_sets = adapter.client_sets(authed=cookiefile is not None)
     outtmpl = str(staging / "%(id)s.%(ext)s")
+    # Resolving may read a page first — network time the stall watchdog must not see as a stall.
+    _touch_job(job_id)
+    target = adapter.resolve_url(
+        url,
+        formats.build_ydl_opts(
+            spec,
+            outtmpl,
+            _make_progress_hook(job_id, asset_id),
+            cookiefile=cookiefile,
+            max_bytes=max_bytes,
+        ),
+    )
     last_exc: Exception | None = None
     for i, clients in enumerate(client_sets):
         opts = formats.build_ydl_opts(
@@ -348,7 +381,7 @@ def _extract_with_fallback(
         # killed — acceptable, as socket_timeout + extractor_retries bound one attempt well under it.)
         try:
             with yt_dlp.YoutubeDL(opts) as ydl:
-                return ydl.extract_info(url, download=True)
+                return ydl.extract_info(target, download=True)
         except yt_dlp.utils.DownloadError as exc:
             last_exc = exc
             if i < len(client_sets) - 1 and adapter.retriable(str(exc)):
@@ -356,13 +389,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
@@ -379,44 +421,50 @@ def _download_settings() -> tuple[str, int]:
         )
 
 
-def _ensure_browser_playable(job_id: int, produced: Path, spec: dict, info: dict) -> Path:
-    """Make an mp4-compat-profile download play in every browser: H.264 + AAC/MP3 in mp4. If the
-    download (whatever the source shipped) isn't already that, re-encode the offending stream(s) —
-    or just remux when the codecs are fine but the container isn't. **Scope:** only the mp4 compat
-    profile is normalized; an explicit `vcodec` or a non-mp4 custom profile is the user opting out
-    of the guarantee and is left as-is (so a `webm` profile can still ship VP9/Opus). Returns the
-    file to store (converted, or the original) and corrects `info`'s codec fields to match disk."""
-    if spec.get("container") != "mp4" or spec.get("vcodec"):
-        return produced
-    vcodec, acodec = editmod.probe_codecs(produced)
-    is_mp4 = produced.suffix.lower() == ".mp4"
-    needs, reenc_v, reenc_a = editmod.browser_transcode_flags(vcodec, acodec, is_mp4)
-    if not needs:
-        return produced
+def _ensure_phone_safe(
+    job_id: int,
+    produced: Path,
+    out_dir: Path,
+    phase: str,
+    total_s: int | None = None,
+    *,
+    keep_source: bool = False,
+) -> Path:
+    """Bring a file that is about to become a ready library asset into the phone-safe shape
+    (`playable`), writing any converted copy into `out_dir`. Returns the file to store — `produced`
+    itself when it already is that shape, or isn't media at all — and removes `produced` once a
+    converted copy exists, unless `keep_source` (an upload's original, which must outlive the
+    conversion until the database points at the new file). The job shows `phase` with real ffmpeg
+    progress while it converts.
 
-    dest = produced.with_name(produced.stem + ".browser.mp4")
-    action = "re-encode" if (reenc_v or reenc_a) else "remux"
+    Every ready path calls this — a download, an upload's worker conversion and an editor clip — so
+    a share link can only ever serve the one shape every phone and browser plays."""
+    p = playable.plan(probe.probe_json(produced), produced.suffix)
+    if p is None or not p.needs_change:
+        return produced
+    dest = out_dir / f"{produced.stem}.safe.{p.ext}"
+    action = "re-encode" if (p.reencode_video or p.reencode_audio) else "remux"
     log.info(
-        "job %s: %s (v=%s a=%s mp4=%s) -> browser-safe mp4", job_id, action, vcodec, acodec, is_mp4
+        "job %s: %s (video=%s audio=%s) -> phone-safe .%s",
+        job_id,
+        action,
+        p.reencode_video,
+        p.reencode_audio,
+        p.ext,
+        extra=logs.event("download.phone_safe", job_id=job_id, action=action, ext=p.ext),
     )
-    _set_job(job_id, phase="processing", progress=0, speed_bps=None, eta_s=None)
-    # Prefer the info duration; probe the file when the extractor didn't provide one, so a long
-    # re-encode still shows real progress instead of a frozen 0%.
-    total_s = int(info["duration"]) if info.get("duration") else editmod.probe_duration(produced)
+    _set_job(job_id, phase=phase, progress=0, speed_bps=None, eta_s=None)
+    # A re-encode with no known length would hold a frozen 0%; probe the file for a denominator.
     editmod.run_ffmpeg(
-        editmod.build_browser_safe_cmd(
-            produced, dest, reenc_v, reenc_a, threads=editmod.encode_thread_cap()
-        ),
-        total_s=total_s,
-        on_progress=_ffmpeg_progress_writer(job_id, "processing"),
+        playable.build_cmd(produced, dest, p, threads=editmod.encode_thread_cap()),
+        total_s=total_s or editmod.probe_duration(produced),
+        on_progress=_ffmpeg_progress_writer(job_id, phase),
         should_cancel=_cancel_poll(job_id),
     )
-    produced.unlink(missing_ok=True)
-    # Keep the stored asset metadata truthful about what's now on disk.
-    if reenc_v:
-        info["vcodec"] = "h264"
-    if reenc_a:
-        info["acodec"] = "aac"
+    if not dest.exists():
+        raise StatedFailure("ffmpeg produced no output file")
+    if not keep_source:
+        produced.unlink(missing_ok=True)
     return dest
 
 
@@ -425,6 +473,7 @@ def _download(
 ) -> None:
     staging = _staging_dir(asset_id)
     cookiefile: Path | None = None
+    url: str | None = None  # read by the failure branch, which can run before it is resolved
     try:
         if staging.exists():
             shutil.rmtree(staging, ignore_errors=True)
@@ -440,17 +489,15 @@ 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
-        # S6: attach the acting user's per-host cookie ONLY when it's host-scoped to this URL AND
+                raise StatedFailure(f"Refusing to download from this address ({e.reason}).") from e
+        # 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
         with SessionLocal() as cdb:
-            asset_sig = cdb.execute(
-                select(MediaAsset.format_sig).where(MediaAsset.id == asset_id)
-            ).scalar_one_or_none()
-            if asset_sig is not None:
+            target = cdb.get(MediaAsset, asset_id)
+            if target is not None:
                 cookiefile = credentials.resolve_cookiefile(
-                    cdb, user_id, url, asset_sig, spec, staging
+                    cdb, user_id, url, target, spec, staging
                 )
             # SEC-13: what this user has left. `check_enqueue` only compared the footprint as it
             # stood when the job was QUEUED — a download's size is unknown until it finishes, so a
@@ -482,15 +529,27 @@ def _download(
         adapter = adapters.resolve_adapter(source_kind, source_ref, info)
 
         produced = _produced_file(info, staging)
-        produced = _ensure_browser_playable(job_id, produced, spec, info)
+        produced = _ensure_phone_safe(
+            job_id,
+            produced,
+            staging,
+            CONVERTING,
+            int(info["duration"]) if info.get("duration") else None,
+        )
         ext = produced.suffix.lstrip(".").lower()
+        # Codecs/dims/duration come from a PROBE of the produced file — the ground truth — NOT yt-dlp's
+        # `info` dict, whose fields are absent for some sources (Facebook among them): deriving
+        # media_kind from those nulls misclassified a real H.264 video as a download-only 'file', and a
+        # missing duration hid the trim action. Probed before the sidecars so the .nfo runtime has it
+        # too. Same probe the upload ingest uses.
+        vcodec, acodec, width, height, duration_s = probe.resolve_media_facts(produced, info)
         meta = storage.MediaMeta(
             video_id=info.get("id") or source_ref,
-            title=normalize_title(info.get("title")) or source_ref,
+            title=normalize_title(adapter.title(info)) or source_ref,
             uploader=info.get("uploader") or info.get("channel") or "Unknown Channel",
             upload_date=_parse_upload_date(info.get("upload_date")),
             uniqueid_type=adapter.nfo_uniqueid_type(),
-            duration_s=int(info["duration"]) if info.get("duration") else None,
+            duration_s=duration_s,
             description=info.get("description"),
             thumbnail_url=info.get("thumbnail"),
         )
@@ -516,12 +575,11 @@ def _download(
                 asset.rel_path = rel
                 asset.size_bytes = size
                 asset.duration_s = meta.duration_s
-                # Codecs/dims come from a PROBE of the finished file — the ground truth — NOT yt-dlp's
-                # `info` dict, whose codec fields are absent for some sources (Facebook among them):
-                # deriving media_kind from those nulls misclassified a real H.264 video as a
-                # download-only 'file' with no in-app play/edit. Same probe the upload ingest uses.
-                asset.vcodec, asset.acodec, asset.width, asset.height = probe.resolve_media_facts(
-                    final, info
+                asset.vcodec, asset.acodec, asset.width, asset.height = (
+                    vcodec,
+                    acodec,
+                    width,
+                    height,
                 )
                 asset.container = ext
                 asset.media_kind = mediakind.derive(asset.vcodec, asset.acodec)
@@ -552,20 +610,30 @@ def _download(
             }
             if job and not job.display_name and meta.title:
                 # display_name is VARCHAR(255) — clip a long title (see _fill_asset_meta_early).
-                fields["display_name"] = meta.title[:255]
+                fields["display_name"] = meta.title[:DISPLAY_TEXT_MAX]
             # Atomic terminal write: finalizes ONLY while the row is still running, so a child that
             # finishes just after a route cancel/pause can't resurrect it (see finalize_if_running).
             finalized = service.finalize_if_running(db, job_id, **fields)
             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
@@ -578,6 +646,7 @@ def _download(
                 status=JobStatus.ERROR,
                 error=msg,
                 error_code=dlerrors.classify(msg),
+                error_detail=None,
                 phase=None,
             )
             db.commit()
@@ -585,29 +654,41 @@ 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]
-        code = dlerrors.classify(msg)
+        # The catalog needs the link and whether the user's cookie went with it: the same yt-dlp
+        # text is Facebook's login wall without one and a refused cookie with one.
+        diagnosis = dlerrors.diagnose(msg, url=url, cookie_attached=cookiefile is not None)
         # SEC-12: redact a transport-level readout for user-supplied URLs (see user_error_text).
-        msg = dlerrors.user_error_text(source_kind, msg, code)
+        msg = dlerrors.user_error_text(source_kind, msg, diagnosis.code)
         with SessionLocal() as db:
             asset = db.get(MediaAsset, asset_id)
             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,
                 status=JobStatus.ERROR,
                 error=msg,
-                error_code=code,
+                error_code=diagnosis.code,
+                error_detail=diagnosis.detail,
                 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).
@@ -616,7 +697,53 @@ 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, *, what: str = "edit"
+) -> None:
+    """Fail a local ffmpeg job — an edit, or an upload's conversion (`what="upload"`) — and say so
+    ONCE: every way one fails comes through here, so this is where its line and its event code
+    (`<what>.job.failed`) 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:
@@ -628,11 +755,29 @@ def _fail_edit(job_id: int, asset_id: int, msg: str) -> None:
             job_id,
             status=JobStatus.ERROR,
             error=msg,
-            error_code=dlerrors.classify(msg),
+            error_code=dlerrors.classify_conversion(msg)
+            if what == "upload"
+            else dlerrors.classify(msg),
             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(
+        "%s job %s failed: %s",
+        what,
+        job_id,
+        formats.log_safe(msg),
+        extra={
+            **logs.event(
+                f"{what}.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:
@@ -684,12 +829,18 @@ 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")
+        # A fast trim stream-copies the source's codecs and container, so the clip is only as
+        # playable as its source: hold it to the same rule as every other ready file.
+        dest_staging = _ensure_phone_safe(job_id, dest_staging, staging, "editing", total_s)
+        out_ext = dest_staging.suffix.lstrip(".").lower() or out_ext
 
         rel = storage.edit_rel_path(user_id, asset_id, out_ext)
         storage.place_file(dest_staging, settings.download_root, rel)
         final = storage.abs_path(settings.download_root, rel)
         size = final.stat().st_size if final.exists() else None
+        # The clip's real frame: a re-encode evens an odd crop or source (`editmod.EVEN_FRAME`).
+        _, _, out_w, out_h, _ = probe.probe_media(final)
         _, retention_days = _download_settings()
         expires = datetime.now(timezone.utc) + timedelta(days=retention_days)
 
@@ -701,7 +852,9 @@ def _process_edit(job_id: int, asset_id: int) -> None:
                 asset.size_bytes = size
                 asset.container = out_ext
                 asset.duration_s = total_s or asset.duration_s
-                if crop:
+                if out_w and out_h:
+                    asset.width, asset.height = out_w, out_h
+                elif crop:
                     asset.width = edit_spec["crop"]["w"]
                     asset.height = edit_spec["crop"]["h"]
                 else:
@@ -720,13 +873,184 @@ 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)
+
+
+def _check_converted_fits(owner_id: int | None, old_size: int, new_size: int) -> None:
+    """Refuse a converted upload that would push its owner over the storage cap: the upload was
+    charged at its original size, and a re-encode can come out larger. The original stays, counted,
+    for the owner to delete or keep."""
+    if owner_id is None:
+        return
+    with SessionLocal() as db:
+        if not quota.fits_after_conversion(db, owner_id, old_size, new_size):
+            raise StatedFailure(dlerrors.QUOTA_FULL_MESSAGE)
+
+
+def _unplace(placed: Path | None) -> None:
+    """Remove a converted upload that was placed at its new rel but never committed: the row still
+    names the original, so nothing else would ever find this file."""
+    if placed is not None:
+        placed.unlink(missing_ok=True)
+
+
+def _conversion_landed(asset_id: int, new_rel: str) -> bool | None:
+    """After the commit that makes a converted upload ready RAISED: did it land anyway? A commit can
+    reach the server and lose its answer (the connection drops after COMMIT). True/False by what the
+    row now says; None when the row cannot be read either."""
+    try:
+        with SessionLocal() as db:
+            asset = db.get(MediaAsset, asset_id)
+            return asset is not None and asset.status == "ready" and asset.rel_path == new_rel
+    except Exception:  # noqa: BLE001 — "cannot tell" is the answer, the caller acts on it
+        # silent-ok: the caller re-raises the commit's own error, which `_fail_edit` reports.
+        return None
+
+
+def _drop_original(job_id: int, src: Path) -> None:
+    """Remove an upload's original once the converted file is committed in its place. Best effort:
+    the job is done and its file is ready, so a failure here must not fail it — the original is
+    named by no row now, and the GC's `.uploads` sweep takes it."""
+    try:
+        src.unlink(missing_ok=True)
+    except OSError as exc:
+        log.warning(
+            "upload job %s: original not removed, left to the GC sweep: %s",
+            job_id,
+            exc,
+            extra=logs.event("upload.original.unlink_failed", job_id=job_id),
+        )
+
+
+def _free_unheld_upload(asset_id: int) -> bool:
+    """Free an upload no job holds any more — cancelled or deleted while its conversion ran, when
+    `release_asset` had to leave it because the conversion still read its file. Once that has
+    stopped, free it as the release would have; left alone, its file would sit on disk counted by no
+    owner's footprint until the GC's upload pass. False when a job still holds it (paused)."""
+    with SessionLocal() as db:
+        asset = db.get(MediaAsset, asset_id)
+        if asset is None or asset.ref_count != 0:
+            return False
+        if asset.rel_path:
+            storage.delete_asset_files(settings.download_root, asset.rel_path)
+        db.delete(asset)
+        db.commit()
+    return True
+
+
+def _convert_upload(job_id: int, asset_id: int) -> None:
+    """Convert a queued upload into the phone-safe shape (`playable`) and make it ready.
+
+    The original sits at the asset's `rel_path` (see `upload`); the converted file replaces it there
+    under the new extension, and only then is the original removed — so a failed or stopped
+    conversion leaves the original in place for Retry, and a delete still finds it by `rel_path`.
+    A converted file placed but never committed is removed again on the way out. When the commit's
+    own outcome is unknown neither file is removed: the row names one of them, and the GC's `.uploads`
+    sweep takes the one it does not — as it does an original whose unlink after the commit failed."""
+    with SessionLocal() as db:
+        asset = db.get(MediaAsset, asset_id)
+        old_rel = asset.rel_path if asset else None
+        old_ext = asset.container if asset else None
+        old_size = (asset.size_bytes or 0) if asset else 0
+        duration = asset.duration_s if asset else None
+        job = db.get(DownloadJob, job_id)
+        owner_id = job.user_id if job else None
+    src = storage.safe_abs_path(settings.download_root, old_rel) if old_rel else None
+    if old_rel is None or src is None or not src.exists():
+        _fail_edit(job_id, asset_id, dlerrors.UPLOAD_MISSING_MESSAGE, what="upload")
+        return
+    staging = _staging_dir(asset_id)
+    placed: Path | None = None  # the converted file while it is at its new rel, uncommitted
+    try:
+        shutil.rmtree(staging, ignore_errors=True)
+        staging.mkdir(parents=True, exist_ok=True)
+        safe = _ensure_phone_safe(job_id, src, staging, CONVERTING, duration, keep_source=True)
+        ext = safe.suffix.lstrip(".").lower()
+        new_rel = storage.with_ext(old_rel, old_ext, ext)
+        if safe != src:
+            _check_converted_fits(owner_id, old_size, safe.stat().st_size)
+            storage.place_file(safe, settings.download_root, new_rel)
+            if new_rel != old_rel:
+                placed = storage.abs_path(settings.download_root, new_rel)
+        final = storage.abs_path(settings.download_root, new_rel)
+        vcodec, acodec, width, height, dur = probe.probe_media(final)
+        with SessionLocal() as db:
+            asset = db.get(MediaAsset, asset_id)
+            if asset:
+                asset.status = "ready"
+                asset.rel_path = new_rel
+                asset.container = ext
+                asset.size_bytes = final.stat().st_size
+                asset.vcodec, asset.acodec = vcodec, acodec
+                asset.width, asset.height = width or asset.width, height or asset.height
+                asset.duration_s = dur or asset.duration_s
+                asset.error = None
+                asset.last_access_at = datetime.now(timezone.utc)
+            title = asset.title if asset else None
+            finalized = service.finalize_if_running(
+                db, job_id, status=JobStatus.DONE, progress=100, phase=None
+            )
+            try:
+                db.commit()
+            except Exception:
+                landed = _conversion_landed(asset_id, new_rel)
+                if landed is False:
+                    raise  # rolled back: the original is still the asset's file — fail as any step
+                # Landed, or cannot tell: the converted file may be the asset's file now, so it is
+                # never removed blind (the sweep takes whichever file no row names).
+                placed = None
+                if landed is None:
+                    raise
+                db.rollback()
+            placed = None
+            if finalized:
+                _notify_download_done(db, owner_id, title, job_id, kind="upload")
+        if new_rel != old_rel:
+            _drop_original(job_id, src)
+        if not finalized:
+            _free_unheld_upload(asset_id)  # finished after its job was cancelled or deleted
+        if finalized:
+            log.info(
+                "upload job %s converted: asset %s",
+                job_id,
+                asset_id,
+                extra=logs.event("upload.job.done", job_id=job_id, asset_id=asset_id, ext=ext),
+            )
+    except editmod.EditAborted:
+        # Paused/canceled mid-encode: the original is untouched. A paused job keeps it for its
+        # resume; one cancelled or deleted holds it no more, so it is freed now.
+        _unplace(placed)
+        if not _free_unheld_upload(asset_id):
+            _reset_asset_pending(asset_id)
+        log.info(
+            "upload job %s conversion aborted (pause/cancel)",
+            job_id,
+            extra=logs.event("upload.job.aborted", job_id=job_id),
+        )
+    except Exception as exc:  # noqa: BLE001 — surface the failure, keep the worker alive
+        # silent-ok: not silent — `_fail_edit` is the report, and it takes `exc` for its stack.
+        _unplace(placed)
+        _fail_edit(job_id, asset_id, str(exc)[:500], exc, what="upload")
+
     finally:
         shutil.rmtree(staging, ignore_errors=True)

backend/app/downloads/playable.py

@@ -0,0 +1,103 @@
+"""The phone-safe rule: what a library file must be so it plays wherever a share link lands.
+
+A shared `/watch` link is opened by whoever got it, on whatever they hold: an iPhone's WebKit, an
+Android Chrome, a desktop Firefox. The one shape every one of them plays:
+
+  * video → H.264, 8-bit 4:2:0 (`yuv420p`, or its full-range twin `yuvj420p`), AAC audio, in .mp4
+  * audio only → MP3 in .mp3, or AAC in .m4a
+
+Measured on the owner's iPhone + iPad (2026-10-05): AV1, Matroska, HEVC tagged `hev1` and MP3
+inside an .mp4 all fail there. VP9/WebM, HEVC `hvc1` and 10-bit H.264 played on those devices, but
+Chrome and Firefox do not decode HEVC and browsers decode 10-bit / 4:4:4 H.264 only patchily, so the
+rule is the shape every browser plays, not the shape one device plays.
+
+Every file that becomes a ready library asset passes through here — a download, an upload (the
+worker converts it, see `upload`), and an editor clip — so a link can only ever serve this shape.
+`plan` says what (if anything) must change; `build_cmd` is the one ffmpeg command that changes it:
+re-encode only the stream that fails, copy the rest, or just remux when only the container is wrong.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from app.downloads import edit as editmod
+from app.downloads import probe
+
+_SAFE_VCODEC = "h264"
+_SAFE_PIX_FMTS = frozenset({"yuv420p", "yuvj420p"})
+_VIDEO_EXT = "mp4"
+# An audio-only file: the codec, and the extension it plays in. Anything else becomes AAC in .m4a.
+_AUDIO_HOME = {"mp3": "mp3", "aac": "m4a"}
+_AUDIO_FALLBACK_EXT = "m4a"
+
+
+@dataclass(frozen=True)
+class Plan:
+    """What makes one file phone-safe. `ext` is the extension the safe file has (no dot)."""
+
+    ext: str
+    has_video: bool
+    reencode_video: bool
+    reencode_audio: bool
+    needs_change: bool
+
+
+def plan(data: dict | None, ext: str) -> Plan | None:
+    """The phone-safe plan for a file whose `probe.probe_json` is `data` and whose extension is
+    `ext`; None when it is not media at all (an unreadable probe, a still image, no audio or video
+    stream) — such a file is a download-only 'file' and never plays inline, so there is nothing to
+    make safe."""
+    if data is None:
+        return None
+    video, audio = probe.primary_streams(data)
+    ext = ext.lower().lstrip(".")
+    if video is not None:
+        rv = (video.get("codec_name") or "").lower() != _SAFE_VCODEC or (
+            video.get("pix_fmt") or ""
+        ).lower() not in _SAFE_PIX_FMTS
+        ra = audio is not None and (audio.get("codec_name") or "").lower() != "aac"
+        return Plan(_VIDEO_EXT, True, rv, ra, rv or ra or ext != _VIDEO_EXT)
+    if audio is not None:
+        home = _AUDIO_HOME.get((audio.get("codec_name") or "").lower())
+        target = home or _AUDIO_FALLBACK_EXT
+        return Plan(target, False, False, home is None, home is None or ext != target)
+    return None
+
+
+def build_cmd(src: Path, dest: Path, p: Plan, threads: int | None = None) -> list[str]:
+    """The ffmpeg command that writes `src` to `dest` (whose suffix is `p.ext`) in the phone-safe
+    shape: the failing stream(s) re-encoded with the package's shared encoder settings, the rest
+    stream-copied. An audio-only result drops any cover-art stream. `-progress pipe:1`
+    streams machine-readable progress; `threads` caps the encoder so a re-encode cannot claim every
+    core on the shared box (see the worker-child de-prioritization)."""
+    cmd = [
+        "ffmpeg",
+        "-y",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-nostdin",
+        "-progress",
+        "pipe:1",
+        "-nostats",
+        *editmod.INPUT_GUARD,
+        "-i",
+        str(src),
+    ]
+    # Exactly the two streams `plan` judged: `V` is a video stream that is not cover art. Nothing
+    # else rides along — a subtitle or data track the .mp4 muxer cannot take would fail the run.
+    if p.has_video:
+        cmd += ["-map", "0:V:0", "-map", "0:a:0?"]
+        if p.reencode_video:
+            cmd += ["-vf", editmod.EVEN_FRAME, *editmod.X264_ARGS]
+        else:
+            cmd += ["-c:v", "copy"]
+    else:
+        cmd += ["-map", "0:a:0"]
+    cmd += editmod.AAC_ARGS if p.reencode_audio else ["-c:a", "copy"]
+    if threads and threads > 0:
+        cmd += ["-threads", str(threads)]
+    if p.ext in ("mp4", "m4a"):
+        cmd += ["-movflags", "+faststart"]
+    cmd += [str(dest)]
+    return cmd

backend/app/downloads/probe.py

@@ -34,6 +34,28 @@ _IMAGE_FORMATS = {
 }
 
 
+def primary_streams(data: dict) -> tuple[dict | None, dict | None]:
+    """(video stream, audio stream) — the first of each kind — from a NON-None ffprobe JSON dict, by
+    the same reading the stored facts use: a still image / image-sequence container has neither (it
+    is a generic 'file'), and a video stream flagged `attached_pic` (an mp3/m4a's cover art) is not a
+    video track. The phone-safe rule (`playable`) judges exactly these two streams."""
+    fmt_names = {
+        n.strip() for n in ((data.get("format") or {}).get("format_name") or "").split(",")
+    }
+    if fmt_names & _IMAGE_FORMATS:
+        return None, None
+    video = audio = None
+    for stream in data.get("streams", []):
+        kind = stream.get("codec_type")
+        if kind == "video" and video is None:
+            if (stream.get("disposition") or {}).get("attached_pic"):
+                continue  # cover art, not a video track
+            video = stream
+        elif kind == "audio" and audio is None:
+            audio = stream
+    return video, audio
+
+
 def _facts_from_probe(
     data: dict,
 ) -> tuple[str | None, str | None, int | None, int | None, int | None]:
@@ -45,63 +67,79 @@ def _facts_from_probe(
     fmt_names = {n.strip() for n in (fmt.get("format_name") or "").split(",")}
     if fmt_names & _IMAGE_FORMATS:
         return None, None, None, None, None
-
-    vcodec = acodec = None
-    width = height = None
-    for stream in data.get("streams", []):
-        kind = stream.get("codec_type")
-        if kind == "video" and vcodec is None:
-            if (stream.get("disposition") or {}).get("attached_pic"):
-                continue  # cover art, not a video track
-            vcodec = stream.get("codec_name")
-            width = stream.get("width")
-            height = stream.get("height")
-        elif kind == "audio" and acodec is None:
-            acodec = stream.get("codec_name")
+    video, audio = primary_streams(data)
+    vcodec = video.get("codec_name") if video else None
+    width = video.get("width") if video else None
+    height = video.get("height") if video else None
+    acodec = audio.get("codec_name") if audio else None
 
     duration = None
     try:
         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
 
 
-def probe_media(path: Path) -> tuple[str | None, str | None, int | None, int | None, int | None]:
-    """(vcodec, acodec, width, height, duration_s) from one ffprobe call; all None if ffprobe fails
-    or the file isn't playable media (an unprobeable file — or a still image — is treated as a generic
-    non-media file, so it becomes a download-only 'file' rather than a broken 'video')."""
-    data = editmod.run_ffprobe_json(path, show_streams=True, show_format=True)
+def probe_json(path: Path) -> dict | None:
+    """The full ffprobe JSON (streams + format) of `path`, or None when ffprobe could not read it —
+    the one call both the stored facts (`facts`) and the phone-safe rule read from."""
+    return editmod.run_ffprobe_json(path, show_streams=True, show_format=True)
+
+
+def facts(
+    data: dict | None,
+) -> tuple[str | None, str | None, int | None, int | None, int | None]:
+    """(vcodec, acodec, width, height, duration_s) of a `probe_json` result; all None when it is None
+    (an unprobeable file is treated as a generic non-media file, so it becomes a download-only 'file'
+    rather than a broken 'video')."""
     if data is None:
         return None, None, None, None, None
     return _facts_from_probe(data)
 
 
+def probe_media(path: Path) -> tuple[str | None, str | None, int | None, int | None, int | None]:
+    """(vcodec, acodec, width, height, duration_s) from one ffprobe call; all None if ffprobe fails
+    or the file isn't playable media (a still image is a generic 'file', see `primary_streams`)."""
+    return facts(probe_json(path))
+
+
 def resolve_media_facts(
     path: Path, info: dict
-) -> tuple[str | None, str | None, int | None, int | None]:
-    """(vcodec, acodec, width, height) for the stored download asset: PROBE the finished file on disk
-    (the ground truth). yt-dlp's `info` omits codec/dimension fields for some sources (Facebook among
-    them), so deriving media_kind from it there labelled a real H.264 video a download-only 'file'.
+) -> tuple[str | None, str | None, int | None, int | None, int | None]:
+    """(vcodec, acodec, width, height, duration_s) for the stored download asset: PROBE the finished
+    file on disk (the ground truth). yt-dlp's `info` omits codec/dimension fields for some sources
+    (Facebook among them), so deriving media_kind from it there labelled a real H.264 video a
+    download-only 'file'. It omits the duration too (a Facebook reel, an Instagram reel), and a NULL
+    duration hides the Library row's trim action although the file plays for minutes.
 
     Precedence is by whether the probe RAN, not per-field: if ffprobe read the file, its codec verdict
     is authoritative — INCLUDING a deliberate None (cover-art-only audio, a still image). A per-field
     `probe or info` fallback would let `info`'s stale vcodec resurrect a video track the file doesn't
     have (yt-dlp reports a progressive `vcodec` for an audio-mode download whose video it then strips),
-    mislabelling an audio download as a broken in-app 'video'. Only when ffprobe could NOT read the
-    file at all do we fall back to `info` (the pre-probe behaviour, a safety net); the cosmetic
-    dimensions still gap-fill from `info` in either case."""
+    mislabelling an audio download as a broken in-app 'video'. When ffprobe could NOT read the file
+    at all, no codec is reported: the probe runs with the media demuxer whitelist, so a file it
+    cannot open is one the player and the editor cannot open either — and taking `info`'s codecs
+    for it would make it an editable 'video' whose bytes are whatever the remote site served. The
+    cosmetic dimensions and the duration still gap-fill from `info` in either case."""
     data = editmod.run_ffprobe_json(path, show_streams=True, show_format=True)
-    info_v = info.get("vcodec") if info.get("vcodec") not in (None, "none") else None
-    info_a = info.get("acodec") if info.get("acodec") not in (None, "none") else None
     info_w = int(info["width"]) if info.get("width") else None
     info_h = int(info["height"]) if info.get("height") else None
+    info_d = int(info["duration"]) if info.get("duration") else None
     if data is None:
-        # ffprobe could not read the file — fall back to the extractor's info entirely.
-        return info_v, info_a, info_w, info_h
-    pv, pa, pw, ph, _dur = _facts_from_probe(data)
+        # Unreadable to the guarded probe: a download-only 'file' (no codecs → media_kind FILE).
+        return None, None, info_w, info_h, info_d
+    pv, pa, pw, ph, pd = _facts_from_probe(data)
     # Probe ran → its codecs win outright (a None means "no such track", not "unknown"); info only
-    # gap-fills the cosmetic width/height the probe couldn't read.
-    return pv, pa, pw if pw is not None else info_w, ph if ph is not None else info_h
+    # gap-fills the width/height/duration the probe couldn't read.
+    return (
+        pv,
+        pa,
+        pw if pw is not None else info_w,
+        ph if ph is not None else info_h,
+        pd if pd is not None else info_d,
+    )

backend/app/downloads/quota.py

@@ -1,7 +1,9 @@
 """Per-user download limits + footprint accounting.
 
 A user's *footprint* is the total size of the ready assets their library references (cache hits
-count — it's "how much disk you're responsible for", not "how much you personally downloaded").
+count — it's "how much disk you're responsible for", not "how much you personally downloaded"). An
+upload counts from the moment it lands, ready or not: its original is on disk while its conversion
+waits, and stays there when the conversion fails (for Retry) — bytes a ready-only sum never saw.
 Limits come from a per-user DownloadQuota row if the admin set one, else the sysconfig defaults.
 `unlimited` (e.g. the admin's own account) bypasses the byte cap.
 
@@ -18,16 +20,24 @@ is unknown until it finishes. Edit jobs do not consult it at all (tracked as SEC
 
 from dataclasses import dataclass
 
-from sqlalchemy import func, select
+from sqlalchemy import and_, func, or_, select
 from sqlalchemy.orm import Session
 
 from app import sysconfig
+from app.downloads.status import JobStatus
 from app.models import DownloadJob, DownloadQuota, MediaAsset
 
 # Jobs a user is considered to be "holding" (occupy a job slot / footprint). Terminal failures
 # (error, canceled) don't count.
-_HOLDING = ("queued", "running", "paused", "done")
-_RUNNING = ("queued", "running")
+_HOLDING = (JobStatus.QUEUED, JobStatus.RUNNING, JobStatus.PAUSED, JobStatus.DONE)
+_RUNNING = (JobStatus.QUEUED, JobStatus.RUNNING)
+# An asset whose file is on disk: a ready one, or an upload in any state (its original lands at
+# ingest, see the module docstring). Every byte sum — a user's footprint, the GC's total-cap pass,
+# the admin's storage view — reads it, so they all count the same disk.
+ON_DISK = or_(
+    MediaAsset.status == "ready",
+    and_(MediaAsset.source_kind == "upload", MediaAsset.rel_path.is_not(None)),
+)
 
 
 @dataclass
@@ -67,12 +77,17 @@ def resolve(db: Session, user_id: int) -> QuotaLimits:
 
 
 def footprint(db: Session, user_id: int) -> int:
-    """Total bytes of the distinct ready assets this user's active jobs reference."""
+    """Total bytes of the distinct assets this user's jobs hold on disk: the ready ones their active
+    jobs reference, and every upload of theirs — including one whose conversion failed, which keeps
+    its original (see the module docstring)."""
     held_assets = (
         select(DownloadJob.asset_id)
         .where(
             DownloadJob.user_id == user_id,
-            DownloadJob.status.in_(_HOLDING),
+            or_(
+                DownloadJob.status.in_(_HOLDING),
+                and_(DownloadJob.job_kind == "upload", DownloadJob.status == JobStatus.ERROR),
+            ),
             DownloadJob.asset_id.is_not(None),
         )
         .distinct()
@@ -80,7 +95,7 @@ def footprint(db: Session, user_id: int) -> int:
     return int(
         db.execute(
             select(func.coalesce(func.sum(MediaAsset.size_bytes), 0)).where(
-                MediaAsset.id.in_(held_assets), MediaAsset.status == "ready"
+                MediaAsset.id.in_(held_assets), ON_DISK
             )
         ).scalar()
         or 0
@@ -111,7 +126,7 @@ def at_concurrency_limit(db: Session, user_id: int) -> bool:
     lim = resolve(db, user_id)
     if lim.unlimited:
         return False
-    running = _count(db, user_id, ("running",))
+    running = _count(db, user_id, (JobStatus.RUNNING,))
     return running >= lim.max_concurrent
 
 
@@ -160,6 +175,18 @@ def check_upload(db: Session, user_id: int, add_bytes: int) -> None:
         raise QuotaExceeded("max_bytes", lim.max_bytes, projected)
 
 
+def fits_after_conversion(db: Session, user_id: int, old_bytes: int, new_bytes: int) -> bool:
+    """Whether an upload converted from `old_bytes` (what it is charged at now) to `new_bytes` keeps
+    its owner within the cap. A re-encode can come out larger than the original, and nothing else
+    re-checks it once the upload was let in."""
+    if new_bytes <= old_bytes:  # a smaller file never breaks a cap the larger one was let in under
+        return True
+    lim = resolve(db, user_id)
+    if lim.unlimited:
+        return True
+    return footprint(db, user_id) - old_bytes + new_bytes <= lim.max_bytes
+
+
 def usage(db: Session, user_id: int) -> dict:
     """Compact usage snapshot for the UI (footprint + counts vs limits)."""
     lim = resolve(db, user_id)

backend/app/downloads/runner.py

@@ -11,18 +11,20 @@ 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
 import sys
 
+from app import logs
+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:
@@ -52,12 +54,21 @@ def _deprioritize() -> None:
 
 
 def main() -> None:
-    logging.basicConfig(level=logging.INFO)
+    logs.configure_logging("runner")
     _deprioritize()
     if len(sys.argv) != 2:
-        print("usage: python -m app.downloads.runner <job_id>", file=sys.stderr)
+        # 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
+    # output joins up with the worker's and the API's view of the same download.
+    logs.set_job(job_id)
+    logsink.start()  # flushed at exit (atexit) — this process has no shutdown hook of its own
 
     with SessionLocal() as db:
         job = db.get(DownloadJob, job_id)
@@ -71,14 +82,42 @@ 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
+    from app.downloads.pipeline import _convert_upload, _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)
+            elif job_kind == "upload":
+                _convert_upload(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
+            # 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

@@ -7,6 +7,7 @@ handles everything else. State transitions used by the routes (pause/resume/canc
 the worker live in `worker.py` / the routes; this module owns enqueue + asset bookkeeping.
 """
 
+import uuid
 from datetime import datetime, timezone
 
 from sqlalchemy import func, select, update
@@ -19,7 +20,7 @@ from app.downloads import credentials
 from app.downloads import edit as editmod
 from app.downloads import formats, mediakind, quota, storage
 from app.downloads.status import HOLDING, JobStatus
-from app.models import Channel, DownloadJob, MediaAsset, Video
+from app.models import DISPLAY_TEXT_MAX, Channel, DownloadJob, MediaAsset, Video
 
 
 class EditError(Exception):
@@ -80,11 +81,15 @@ def get_or_create_asset(
         status="pending",
         ref_count=0,
     )
-    db.add(asset)
     try:
-        db.flush()
+        # A SAVEPOINT: losing the race undoes only this insert, never the caller's own pending writes
+        # (Retry clears the job's error before it gets here; a whole-session rollback threw that away).
+        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:
-        db.rollback()
         asset = db.execute(stmt).scalar_one()
     return asset
 
@@ -174,7 +179,7 @@ def enqueue(
         profile_id=profile_id,
         profile_snapshot=spec,
         display_name=display_name
-        or (asset.title[:255] if asset.status == "ready" and asset.title else None),
+        or (asset.title[:DISPLAY_TEXT_MAX] if asset.status == "ready" and asset.title else None),
         status="queued",
         queue_pos=next_queue_pos(db),
     )
@@ -193,10 +198,13 @@ def enqueue(
 
 
 def _clip_title(source_title: str | None, display_name: str | None) -> str:
+    # Clipped to DISPLAY_TEXT_MAX, not to a literal: this feeds `DownloadJob.display_name` through
+    # `enqueue_edit`, the same column `display_text` guards. A machine-made title, so it is clipped
+    # rather than run through `display_text` — blank here means "no title", not None.
     if display_name:
-        return display_name[:255]
+        return display_name[:DISPLAY_TEXT_MAX]
     base = source_title or "Clip"
-    return f"{base} (clip)"[:255]
+    return f"{base} (clip)"[:DISPLAY_TEXT_MAX]
 
 
 def enqueue_edit(
@@ -250,7 +258,7 @@ def enqueue_edit(
         source_asset_id=src_asset.id,
         edit_spec=spec,
         profile_snapshot={},
-        display_name=display_name or asset.title,
+        display_name=display_name or asset.title[:DISPLAY_TEXT_MAX],
         status="queued",
         queue_pos=next_queue_pos(db),
     )
@@ -310,14 +318,22 @@ def release_asset(db: Session, job: DownloadJob) -> None:
     re-enqueuing the same (source,format) — get_or_create_asset would reset that row to `pending` and
     +1 it, and deleting it under that would FK-null the new job's asset (a lost update on ref_count).
     A ready asset is still freed at ref==0 (its file is the point); an orphaned errored row is cheap
-    (no file) and gets reused+reset by the next enqueue, or reclaimed by a later GC pass."""
+    (no file) and gets reused+reset by the next enqueue, or reclaimed by a later GC pass.
+
+    An UPLOAD is the exception: it is never shared or re-enqueued (its ref is unique), and while it
+    waits for or failed its phone-safe conversion the original file already sits at `rel_path` — so
+    it is freed at ref==0 whatever its state, except mid-conversion (`downloading`: the worker child
+    still reads it; the GC upload pass takes it once the child has stopped)."""
     if not job.asset_id or job.status not in HOLDING:
         return
     asset = db.get(MediaAsset, job.asset_id)
     if asset is None:
         return
     new_count = decr_ref_count(db, asset.id)
-    if new_count == 0 and asset.status == "ready":
+    freeable = asset.status == "ready" or (
+        asset.source_kind == "upload" and asset.status != "downloading"
+    )
+    if new_count == 0 and freeable:
         if asset.rel_path:
             storage.delete_asset_files(settings.download_root, asset.rel_path)
         db.delete(asset)
@@ -341,13 +357,20 @@ def pause(db: Session, job: DownloadJob) -> None:
 def resume(db: Session, job: DownloadJob) -> None:
     """Requeue a paused/errored job for a fresh attempt, clearing its error. If the SHARED asset itself
     failed, reset it to pending so the worker actually re-downloads — otherwise the requeued job would
-    instantly re-inherit the asset's stale error (the worker short-circuits an errored asset)."""
+    instantly re-inherit the asset's stale error (the worker short-circuits an errored asset).
+
+    A cookie the user added AFTER the job was queued moves the job onto their private asset first
+    (`_follow_the_cookie`): the worker only ever attaches a cookie to that identity, so without the move
+    the Retry a login-wall message asks for would fail on the same wall."""
     if job.status in (JobStatus.PAUSED, JobStatus.ERROR):
         job.progress = 0
         job.error = None
         job.error_code = None
+        job.error_detail = None
         if job.asset_id:
             asset = db.get(MediaAsset, job.asset_id)
+            if asset is not None:
+                asset = _follow_the_cookie(db, job, asset)
             if asset and asset.status == "error":  # MediaAsset.status (no enum), not a JobStatus
                 asset.status = "pending"
                 asset.error = None
@@ -355,6 +378,32 @@ def resume(db: Session, job: DownloadJob) -> None:
         db.commit()
 
 
+def _follow_the_cookie(db: Session, job: DownloadJob, asset: MediaAsset) -> MediaAsset:
+    """Re-point a requeued job at the asset enqueue would pick NOW, when the user has a cookie for the
+    link's host but the job still holds an asset the worker won't attach it to (queued before the
+    cookie existed). Returns the asset the job holds afterwards.
+
+    Only a `pending` / `error` asset moves — neither has a file nor a download in flight. A `ready` one
+    already has the file, and a `downloading` one may be this job's own child still being stopped by
+    the pause; the next Retry after it settles moves the job then. Removing a cookie never moves a job
+    back: the worker attaches nothing without a credential, so the private asset is as good as any."""
+    if asset.status not in ("pending", "error"):
+        return asset
+    url = source_url(job.source_kind, job.source_ref)
+    salt = credentials.salt_for_enqueue(db, job.user_id, url)
+    spec = formats.normalize(job.profile_snapshot)
+    if salt is None or credentials.is_authed_asset(asset, spec, job.user_id, url):
+        return asset
+    target = get_or_create_asset(
+        db, job.source_kind, job.source_ref, formats.format_sig(spec, salt=salt)
+    )
+    populate_from_catalog(db, target)
+    release_asset(db, job)  # drop the old hold BEFORE re-pointing — it keys off job.asset_id
+    incr_ref_count(db, target.id)
+    job.asset_id = target.id
+    return target
+
+
 def cancel(db: Session, job: DownloadJob) -> None:
     """Cancel a job unless it's already done/canceled, releasing its asset hold WHILE it still counts
     as holding — `canceled` ∉ HOLDING, so a later delete won't double-release."""
@@ -373,13 +422,31 @@ def delete(db: Session, job: DownloadJob) -> None:
 
 def redownload(db: Session, job: DownloadJob) -> None:
     """Rebuild a finished/failed job's file into a FRESH, private asset (the cache sig is salted with
-    the job id + current asset id, so it never reuses the dedup pool) and requeue the SAME job row —
+    the new asset's own id, so it never reuses the dedup pool) and requeue the SAME job row —
     so any public share link (DownloadLink -> job_id) keeps resolving to the newly-downloaded file.
     The old hold is dropped first (freeing the old file iff this job was its last holder). The caller
-    has already rejected edit clips + still-in-progress jobs (HTTP 409)."""
+    has already rejected edit clips + still-in-progress jobs (HTTP 409).
+
+    When the user has a cookie for the link's host, the salt carries it (`credentials.rebuild_salt`),
+    so the worker recognises the rebuild as their private identity and attaches the cookie — a cookie
+    download, or one the user added after a failure, rebuilds with the cookie."""
     spec = formats.normalize(job.profile_snapshot)
-    sig = formats.format_sig(spec, salt=f"{job.id}:{job.asset_id}")
-    asset = get_or_create_asset(db, job.source_kind, job.source_ref, sig)
+    cookie = credentials.salt_for_enqueue(
+        db, job.user_id, source_url(job.source_kind, job.source_ref)
+    )
+    # The salt names the row's own id, which exists only once the row does: insert it under a unique
+    # placeholder, then write the real signature in the same transaction (nobody sees the placeholder).
+    asset = MediaAsset(
+        source_kind=job.source_kind,
+        source_ref=job.source_ref,
+        format_sig=f"rebuild:{uuid.uuid4().hex}",
+        status="pending",
+        ref_count=0,
+    )
+    db.add(asset)
+    db.flush()
+    asset.format_sig = formats.format_sig(spec, salt=credentials.rebuild_salt(asset.id, cookie))
+    db.flush()
     populate_from_catalog(db, asset)
     # Drop the old hold BEFORE re-pointing the job — release_asset keys off the job's current asset.
     release_asset(db, job)
@@ -389,6 +456,8 @@ def redownload(db: Session, job: DownloadJob) -> None:
     job.progress = 0
     job.phase = None
     job.error = None
+    job.error_code = None  # a rebuild that fails again gets its own diagnosis, never the old one
+    job.error_detail = None
     job.speed_bps = None
     job.eta_s = None
     # Re-derive the display name from the freshly cleaned title on completion (else an older, un-cleaned

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.
@@ -165,13 +168,25 @@ def upload_rel_path(user_id: int, asset_id: int, filename: str) -> str:
     episode sidecars). The name is system-decided and bound to the asset id (`_a{id}` keeps two
     same-named uploads apart); the original filename is display metadata only. The extension is
     preserved (shell-safe, bounded) so the served file + its Content-Disposition carry a correct
-    suffix; an extensionless upload stays extensionless."""
-    stem = sanitize(Path(filename).stem, 80)
+    suffix; an extensionless upload stays extensionless.
+
+    The stem holds no dot, so the last dot of the name is always the extension's: every sibling
+    derived by swapping it (`with_suffix` — the poster, the converted file) keeps `_a{id}`. A dotted
+    stem with no extension ('Holiday.2024.ä') once lost it, and two such uploads shared one file."""
+    stem = sanitize(Path(filename).stem, 80).replace(".", "_")
     ext = _clean_upload_ext(filename)
     suffix = f".{ext}" if ext else ""
     return f".uploads/{user_id}/{stem}_a{asset_id}{suffix}"
 
 
+def with_ext(rel: str, old_ext: str | None, ext: str) -> str:
+    """`rel` with its extension — `old_ext`, the stored `container`, None for a bare name — swapped
+    for `ext`. Not `Path.with_suffix`: on a bare name whose stem holds a dot (an upload placed before
+    the stems lost their dots) that would take the stem's tail for the extension, and `_a{id}` with it."""
+    base = rel[: -len(old_ext) - 1] if old_ext and rel.endswith(f".{old_ext}") else rel
+    return f"{base}.{ext}"
+
+
 def upload_ext(filename: str) -> str | None:
     """The stored `container` for an uploaded file: its shell-safe lowercased extension, or None when
     the upload has no extension (a bare name). Shares `_clean_upload_ext` with `upload_rel_path` so the
@@ -294,7 +309,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 +325,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/downloads/upload.py

@@ -1,15 +1,24 @@
-"""Local file ingest for the download center (E7 S5) — the non-yt-dlp path into the media library.
+"""Local file ingest for the download center — the non-yt-dlp path into the media library.
 
 A user-uploaded file joins the SAME library as a downloaded one, so it inherits the whole function
 set already built (metadata chips, share links, and — for media — in-app play/edit). Unlike a
-download it bypasses yt-dlp AND the worker entirely: the file is already on the host, so ingest
-probes it, places it on disk, and creates an already-`ready` MediaAsset + `done` DownloadJob in one
-step — the same "the file exists, mark it done now" shortcut `service.enqueue` takes on a cache hit.
+download it bypasses yt-dlp: the file is already on the host, so ingest probes it and places it on
+disk. A file that already is the phone-safe shape (`playable`) — or is not media at all — becomes an
+already-`ready` MediaAsset + `done` DownloadJob in one step, the same "the file exists, mark it done
+now" shortcut `service.enqueue` takes on a cache hit.
+
+Media that is NOT phone-safe (an iPhone's HEVC .mov, a VP9 .webm, an .mkv) is placed as it came and
+queued: the asset stays `pending` and the job `queued`, and the download worker converts it
+(`pipeline._convert_upload`) — so a share link never hands a friend a file their phone cannot play.
+Only the converted file is kept (the owner's choice: one file per upload). A 10-bit HDR original
+becomes 8-bit H.264 with its colour tags kept — still tagged HDR (HLG/PQ, BT.2020), not tone-mapped
+to SDR (the owner's choice too). Until then the original sits at the asset's `rel_path`, which is
+what a failed conversion's Retry starts from again, and what a delete removes
+(`service.release_asset`).
 
 Kinds (the invariant lives in `mediakind`): a probe with a real video stream -> video, audio-only
 -> audio, neither -> a generic 'file' (pdf/zip/docx/…) that is download-only and never rendered
-inline (see the force-download serving in the file/watch routes). This module is the ingest seam a
-future sub-function (e.g. convert) plugs a new adapter into, mirroring how it sidesteps the worker.
+inline (see the force-download serving in the file/watch routes).
 
 An upload does NOT get an `expires_at`: it's user-provided and may be irreplaceable (there's no
 source to re-download), so it doesn't age out on the retention clock the way a re-fetchable download
@@ -24,8 +33,9 @@ from sqlalchemy.orm import Session
 
 from app.config import settings
 from app.downloads import edit as editmod
-from app.downloads import mediakind, probe, quota, service, storage
-from app.models import DownloadJob, MediaAsset
+from app.downloads import mediakind, playable, probe, quota, service, storage
+from app.downloads.status import JobStatus
+from app.models import DownloadJob, MediaAsset, display_text
 
 
 def _title_from_filename(filename: str) -> str:
@@ -44,15 +54,22 @@ def ingest_upload(
     size: int,
     display_name: str | None = None,
 ) -> DownloadJob:
-    """Ingest an already-uploaded file at `src_path` into `user_id`'s library and return the `done`
-    job. `src_path` is MOVED into place on success (the caller stages it to a temp file first).
+    """Ingest an already-uploaded file at `src_path` into `user_id`'s library and return its job —
+    `done`, or `queued` for the worker's phone-safe conversion (see the module docstring). `src_path`
+    is MOVED into place on success (the caller stages it to a temp file first).
 
     Raises quota.QuotaExceeded (holdings/footprint cap) — checked BEFORE any disk write, so a
     rejected upload leaves nothing behind and the caller just cleans up its temp file."""
     quota.check_upload(db, user_id, size)  # the file's size is known → charge it up front
 
-    vcodec, acodec, width, height, duration = probe.probe_media(src_path)
+    data = probe.probe_json(src_path)
+    vcodec, acodec, width, height, duration = probe.facts(data)
     kind = mediakind.derive(vcodec, acodec)
+    # Judged by the extension the file is PLACED under (and the worker re-judges), not the raw one:
+    # 'clip.mp4~' is stored as .mp4, and judging 'mp4~' queued a conversion with nothing to convert.
+    ext = storage.upload_ext(filename) or ""
+    safe = playable.plan(data, ext) if kind != mediakind.FILE else None
+    convert = safe is not None and safe.needs_change
 
     # An upload never dedups (each file is its own asset): a random ref makes the cache key unique,
     # so `format_sig` is a constant marker rather than a format hash.
@@ -66,17 +83,18 @@ def ingest_upload(
     rel = storage.upload_rel_path(user_id, asset.id, filename)
     storage.place_file(src_path, settings.download_root, rel)
     # From here the file is on disk under `.uploads/`. If the transaction fails before it commits, the
-    # asset/job rows roll back but the placed file would be ORPHANED — nothing references it, the
-    # per-user delete path keys off asset.rel_path (which is gone), and the GC orphan sweep skips the
-    # dot-prefixed `.uploads/` tree. So roll back the on-disk side too on any failure.
+    # asset/job rows roll back and nothing names the placed file: the per-user delete path keys off
+    # asset.rel_path (which is gone), and the GC's `.uploads` sweep reaches it only an hour later. So
+    # roll back the on-disk side too — unless the commit itself raised after it landed (see below).
+    asset_id = asset.id
     try:
         final = storage.abs_path(settings.download_root, rel)
         actual_size = final.stat().st_size if final.exists() else size
 
-        asset.status = "ready"
+        asset.status = "pending" if convert else "ready"
         asset.rel_path = rel
         asset.size_bytes = actual_size
-        asset.container = storage.upload_ext(filename)
+        asset.container = ext or None
         asset.vcodec = vcodec
         asset.acodec = acodec
         asset.width = width
@@ -99,9 +117,9 @@ def ingest_upload(
             source_kind="upload",
             source_ref=ref,
             profile_snapshot={},
-            display_name=(display_name or "").strip() or None,
-            status="done",
-            progress=100,
+            display_name=display_text(display_name),
+            status=JobStatus.QUEUED if convert else JobStatus.DONE,
+            progress=0 if convert else 100,
             queue_pos=service.next_queue_pos(db),
         )
         db.add(job)
@@ -109,6 +127,11 @@ def ingest_upload(
         db.commit()
     except Exception:
         db.rollback()
+        if _row_landed(db, asset_id) is not False:
+            # The commit reached the server and lost its answer, or the row cannot be read: the file
+            # may be the asset's now, so it is never removed blind — the sweep takes it if no row
+            # names it.
+            raise
         # The rows are gone; remove the now-unreferenced file so no bytes leak. Clean the poster by its
         # DETERMINISTIC path (rel with a .jpg suffix, the same path ensure_poster writes to) rather than
         # ensure_poster's return value: it writes the frame directly to that path and returns None on an
@@ -120,3 +143,13 @@ def ingest_upload(
         raise
     db.refresh(job)
     return job
+
+
+def _row_landed(db: Session, asset_id: int) -> bool | None:
+    """After the ingest transaction raised: is the asset row there anyway? A commit can reach the
+    server and lose its answer (the connection drops after COMMIT). None when it cannot be read."""
+    try:
+        return db.get(MediaAsset, asset_id) is not None
+    except Exception:  # noqa: BLE001 — "cannot tell" is the answer, the caller acts on it
+        # silent-ok: the caller re-raises the ingest's own error.
+        return None

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
 
@@ -189,7 +197,7 @@ def _next_step(verify_link: str | None, has_account: bool, hours: int, lang: str
 
     Three states, because a mail that guesses wrong sends someone looking for a link that isn't
     coming — or worse, tells them to sign in when their address is still unconfirmed and sign-in will
-    refuse them (E9.5 S4 named that state on screen; the mail must not contradict it).
+    refuse them (the sign-in screen names that state; the mail must not contradict it).
 
     The link branch is the point of the C option: in the common ordering — approve first, the person
     signs up later, or signs up and waits — they would otherwise have to find and open TWO separate
@@ -245,7 +253,7 @@ def send_access_invitation(
     the closing line offers no deadline — nudging is the one thing this mail must not do.
 
     Its language is the one place the app has no signal to read: the admin typed this address in, so
-    nobody has ever told us how to address its owner. That is why the send button asks (E9.5 S7).
+    nobody has ever told us how to address its owner. That is why the send button asks.
     """
     admin, contact = _reply_contact(lang)
     body = mailtext.text(

backend/app/feedquery.py

@@ -12,9 +12,10 @@ import binascii
 import json
 from datetime import date, datetime, timedelta, timezone
 
-from sqlalchemy import BigInteger, Select, and_, cast, false, func, or_, select
+from sqlalchemy import BigInteger, Select, and_, case, cast, false, func, or_, select
 from sqlalchemy.orm import Session, aliased
 
+from app.collation import collated
 from app.models import (
     LIVE_OR_UPCOMING,
     BlockedChannel,
@@ -30,7 +31,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:
@@ -105,15 +106,30 @@ def _tag_visible(user: User):
     return or_(ChannelTag.user_id.is_(None), ChannelTag.user_id == user.id)
 
 
-def tags_by_category(db: Session, tag_ids: list[int]) -> dict[str, list[int]]:
+# The pseudo-category of a selected tag id no Tag row answers (a saved view or the feed state outlives
+# a deleted tag). It filters like a category whose tags no channel carries — to nothing, in the SQL and
+# in feed_summary's mirror alike — instead of the id being dropped, which showed the WHOLE feed under
+# the view's old name. No real category is called this (language/topic/other).
+MISSING_TAG_CATEGORY = "missing"
+
+
+def tags_by_category(db: Session, user: User, tag_ids: list[int]) -> dict[str, list[int]]:
     """Group tag ids by their category (language/topic/other). The single source for the category split
     shared by the feed's tag WHERE (filtered_query) and the facet/count summary (feed_summary), so the
-    two can't disagree on which selected tag belongs to which category."""
+    two can't disagree on which selected tag belongs to which category. An unknown id lands in
+    MISSING_TAG_CATEGORY — and so does another user's private tag: resolving it to its real category
+    told the caller which foreign ids exist."""
     if not tag_ids:
         return {}  # skip the pointless `WHERE id IN ()` round-trip on the no-tag-filter hot path
     out: dict[str, list[int]] = {}
-    for tid, cat in db.execute(select(Tag.id, Tag.category).where(Tag.id.in_(tag_ids))).all():
+    visible = or_(Tag.user_id.is_(None), Tag.user_id == user.id)
+    for tid, cat in db.execute(
+        select(Tag.id, Tag.category).where(Tag.id.in_(tag_ids), visible)
+    ).all():
         out.setdefault(cat, []).append(tid)
+    known = {tid for ids in out.values() for tid in ids}
+    if missing := [tid for tid in tag_ids if tid not in known]:
+        out[MISSING_TAG_CATEGORY] = missing
     return out
 
 
@@ -264,7 +280,8 @@ def filtered_query(
     # the queries that surfaced the video > description; see Video.search_vector). YouTube-like
     # "fuzzy" matching: word-order-independent, multi-word AND, prefix on the word being typed,
     # accent-insensitive (unaccent_simple). The channel name still matches as a substring so
-    # channel searches work. `rank_expr` (weight-aware ts_rank) drives the "relevance" sort.
+    # channel searches work. `rank_expr` (weight-aware ts_rank) drives the "relevance" sort, over the
+    # newest RANK_WINDOW matches only (see there).
     rank_expr = None
     if q:
         # Resolve the channels whose NAME matches up front (there are only a few hundred channels, so
@@ -272,8 +289,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()
@@ -301,7 +319,7 @@ def filtered_query(
         # ALL its selected tags. ⚠️ feed_summary.passes() reimplements this exact rule in Python for the
         # sidebar count/facets — keep the two in lockstep (equivalence-tested by
         # test_feed_summary_matches_count_plus_facets).
-        by_category = tags_by_category(db, tags)
+        by_category = tags_by_category(db, user, tags)
         # Facet counting drops the category being counted so its own chips don't zero each
         # other out (standard drill-down faceting: a category's count ignores its own
         # selections but still honours the other categories' filters).
@@ -392,7 +410,7 @@ def feed_summary(db: Session, user: User, **params) -> dict:
         return {"count": 0, "facets": {}}
 
     # channel -> its visible tag ids, plus each tag's category (for grouping the facet output).
-    visible = or_(ChannelTag.user_id.is_(None), ChannelTag.user_id == user.id)
+    visible = _tag_visible(user)
     channel_tags: dict[str, set[int]] = {}
     tag_category: dict[int, str] = {}
     for cid, tid, cat in db.execute(
@@ -407,7 +425,7 @@ def feed_summary(db: Session, user: User, **params) -> dict:
     # base channel carries still filters everything out for its category — matching the SQL `IN (empty)`
     # behaviour).
     selected_by_cat: dict[str, set[int]] = {
-        cat: set(ids) for cat, ids in tags_by_category(db, params.get("tags") or []).items()
+        cat: set(ids) for cat, ids in tags_by_category(db, user, params.get("tags") or []).items()
     }
 
     def passes(ch_tags: set[int], exclude_cat: str | None) -> bool:
@@ -435,7 +453,7 @@ def feed_summary(db: Session, user: User, **params) -> dict:
         # Drop this category's own selections so its chips keep independent counts; a conjunctive
         # topic-AND keeps them (each remaining chip narrows to channels that ALSO have the selected).
         exclude = None if tag_modes.get(category, "or") == "and" else category
-        for cid, ch_tags in channel_tags.items():
+        for ch_tags in channel_tags.values():
             if not passes(ch_tags, exclude):
                 continue
             for tid in ch_tags:
@@ -445,7 +463,7 @@ def feed_summary(db: Session, user: User, **params) -> dict:
 
 
 def feed_years(db: Session, user: User, **params) -> list[dict]:
-    """Per-year video counts for the current filter context (item 8 / E8·S2): powers the year control's
+    """Per-year video counts for the current filter context: powers the year control's
     quick chips + the "more…" per-year-counts dialog. Every OTHER filter (tags, channels, content type,
     search, watch state, scope) still applies, but the publish-date narrowing itself is DROPPED —
     published_after/before and max_age_days — so the year list is the full set of years available and
@@ -477,8 +495,10 @@ def feed_years(db: Session, user: User, **params) -> list[dict]:
 # replaces OFFSET/LIMIT: deep scrolling no longer scans-and-discards skipped rows,
 # and the page boundary is stable even as the scheduler ingests new videos mid-scroll
 # (OFFSET would shift and duplicate/skip rows).
-def sort_keys(sort: str, seed: int, rank_expr=None) -> list[dict]:
+def sort_keys(sort: str, seed: int, rank_expr=None, lang: str | None = None) -> list[dict]:
+    """`lang` orders the title sorts in the reader's alphabet (`collation`); the other keys ignore it."""
     pub = {"expr": Video.published_at, "asc": False, "nullable": False, "kind": "dt"}
+    title = collated(Video.title, lang)
     table: dict[str, list[dict]] = {
         "newest": [pub],
         "oldest": [{**pub, "asc": True}],
@@ -490,10 +510,8 @@ def sort_keys(sort: str, seed: int, rank_expr=None) -> list[dict]:
         "duration_asc": [
             {"expr": Video.duration_seconds, "asc": True, "nullable": True, "kind": "num"}
         ],
-        "title": [{"expr": func.lower(Video.title), "asc": True, "nullable": True, "kind": "str"}],
-        "title_desc": [
-            {"expr": func.lower(Video.title), "asc": False, "nullable": True, "kind": "str"}
-        ],
+        "title": [{"expr": title, "asc": True, "nullable": True, "kind": "str"}],
+        "title_desc": [{"expr": title, "asc": False, "nullable": True, "kind": "str"}],
         "subscribers": [
             {"expr": Channel.subscriber_count, "asc": False, "nullable": True, "kind": "num"}
         ],
@@ -541,6 +559,54 @@ def sort_keys(sort: str, seed: int, rank_expr=None) -> list[dict]:
     return table.get(sort) or table["newest"]
 
 
+# Relevance ranks only the newest RANK_WINDOW matches: ts_rank reads every match's tsvector, and
+# a broad word matches most of the library ("a" ranked 193k rows in 6.8 s on prod, against 1.1 s to just
+# find them). The rows past the window keep rank 0, so they follow the ranked ones newest first; a word
+# that broad has no meaningful relevance order anyway, and a specific one fits the window whole.
+RANK_WINDOW = 2000
+
+
+def rank_window_start(db: Session, query: Select) -> datetime | None:
+    """The published_at the ranked window starts at: the RANK_WINDOW-th newest match, None when fewer
+    match (rank them all). The newest-first walk stops after RANK_WINDOW matches (40 ms for "a")."""
+    return db.scalar(
+        query.with_only_columns(Video.published_at)
+        .order_by(Video.published_at.desc())
+        .offset(RANK_WINDOW - 1)
+        .limit(1)
+    )
+
+
+def windowed_rank(rank_expr, since: datetime | None):
+    """`rank_expr` inside the window, 0 past it. CASE evaluates ts_rank only for the rows inside."""
+    if since is None:
+        return rank_expr
+    return case((Video.published_at >= since, rank_expr), else_=0)
+
+
+def windowed_relevance_rows(
+    db: Session, query: Select, keys: list[dict], window: datetime, cursor_id: str | None, n: int
+) -> list:
+    """Up to `n` rows of the windowed relevance order, read as its two halves: the window ranked, then
+    the rest newest first (every window row sorts before every row past it). As one ORDER BY the
+    planner computes the CASE for every match and sorts them all (2.7 s for "a" on prod); split, each
+    half rides an index (80 ms + 5 ms). With a cursor, `keys` carry its values (keyset_predicate)."""
+    pub_key = keys[1]  # relevance: [rank, published_at]
+    rows: list = []
+    if cursor_id is None or pub_key["value"] >= window:
+        inside = query.where(Video.published_at >= window).order_by(*order_by(keys))
+        if cursor_id is not None:
+            inside = inside.where(keyset_predicate(keys, cursor_id))
+        rows = list(db.execute(inside.limit(n)).all())
+    if len(rows) < n:
+        newest = [pub_key]  # past the window every rank is 0: the order is newest first
+        rest = query.where(Video.published_at < window).order_by(*order_by(newest))
+        if cursor_id is not None:
+            rest = rest.where(keyset_predicate(newest, cursor_id))
+        rows += db.execute(rest.limit(n - len(rows))).all()
+    return rows
+
+
 def order_by(keys: list[dict]):
     cols = []
     for k in keys:
@@ -587,26 +653,45 @@ def keyset_predicate(keys: list[dict], cursor_id: str):
     return rec(0)
 
 
-def encode_cursor(keys: list[dict], row) -> str:
+def encode_cursor(keys: list[dict], row, window: datetime | None = None) -> str:
+    """`window` is the relevance window's start: the cursor carries it, so every page ranks against the
+    window page one did. Recomputed per page, a video ingested mid-scroll would push the window's oldest
+    row to rank 0, behind the cursor, and the reader would see it twice."""
     vals = []
     for i, k in enumerate(keys):
         v = getattr(row, f"_k{i}")
         vals.append(v.isoformat() if (v is not None and k["kind"] == "dt") else v)
-    payload = json.dumps({"k": vals, "id": row.id})
+    body: dict = {"k": vals, "id": row.id}
+    if window is not None:
+        body["w"] = window.isoformat()
+    payload = json.dumps(body)
     return base64.urlsafe_b64encode(payload.encode()).decode()
 
 
-def decode_cursor(keys: list[dict], cursor: str) -> tuple[list, str]:
+def _cursor_dt(v):
+    """A cursor's timestamp: aware or refused. The server writes only aware ones (timestamptz), and
+    windowed_relevance_rows compares them in Python, where a naive one beside an aware one raises — a
+    500 for a hand-made cursor instead of the 400."""
+    if v is None:
+        return None
+    dt = datetime.fromisoformat(v)
+    if dt.tzinfo is None:
+        raise ValueError("naive cursor timestamp")
+    return dt
+
+
+def decode_cursor(keys: list[dict], cursor: str) -> tuple[list, str, datetime | None]:
     try:
         payload = json.loads(base64.urlsafe_b64decode(cursor.encode()))
         raw = payload["k"]
         if len(raw) != len(keys):
             raise ValueError("key arity mismatch")
-        vals = [
-            datetime.fromisoformat(v) if (v is not None and k["kind"] == "dt") else v
-            for k, v in zip(keys, raw)
-        ]
-        return vals, payload["id"]
+        vals = [_cursor_dt(v) if k["kind"] == "dt" else v for k, v in zip(keys, raw, strict=True)]
+        for k, v in zip(keys, vals, strict=True):
+            if v is None and not k["nullable"]:
+                raise ValueError("null value for a non-nullable key")
+        window = payload.get("w")
+        return vals, payload["id"], _cursor_dt(window) if window else None
     except (binascii.Error, json.JSONDecodeError, KeyError, ValueError, TypeError) as exc:
         # Framework-free: the route handler translates this into an HTTP 400 so the
         # read-model stays web-layer-agnostic (see routes/feed.get_feed).

backend/app/issues/__init__.py

@@ -0,0 +1,3 @@
+"""Bug reports built from debug sessions: the files an issue carries, and where they go —
+downloaded as a zip, or sent to a Gitea issue tracker. The session itself — what is recorded
+and tagged — is the core module `app/debugsession.py`."""

backend/app/issues/bundle.py

@@ -0,0 +1,79 @@
+"""What an issue from a debug session carries, as files — one definition for the zip export and the
+Gitea upload, so the two cannot drift apart.
+
+  * `issue.md` — the title and the body the user wrote and reviewed in the composer (rendered there,
+    in their language; the server does not rewrite it);
+  * `client.log` / `server.log` — the session's evidence (`debugsession.bundle`) minus the rows the
+    user took out, one JSON object per line, browser rows and server rows apart. `.log`, not
+    `.jsonl`: Gitea refuses that extension (measured);
+  * the screenshots, in the order they were taken.
+
+Every row is already redacted twice (at capture, and again when stored), and nothing here adds a
+field the review list did not show.
+"""
+
+import io
+import json
+import zipfile
+from dataclasses import dataclass
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app import debugsession, logsink
+from app.models import DebugScreenshot, DebugSession
+
+
+@dataclass(frozen=True)
+class IssueFile:
+    name: str
+    data: bytes
+    mime: str
+
+
+def title_of(session: DebugSession) -> str:
+    # Not a sentence of ours: the composer always saves a title in the user's language, and a
+    # session exported before it ever saved is named by its date alone, in no language at all.
+    title = ((session.draft or {}).get("title") or "").strip()
+    return title or f"{session.started_at:%Y-%m-%d %H:%M} · {session.id}"
+
+
+def body_of(session: DebugSession) -> str:
+    return ((session.draft or {}).get("body") or "").strip()
+
+
+def _lines(rows) -> bytes:
+    return "".join(
+        json.dumps(logsink.serialize(r), ensure_ascii=False, default=str) + "\n" for r in rows
+    ).encode()
+
+
+def files(db: Session, session: DebugSession) -> list[IssueFile]:
+    """The session's issue as files: the text, the two logs, the screenshots."""
+    rows, _ = debugsession.bundle(db, session, drop_excluded=True)
+    text = f"# {title_of(session)}\n\n{body_of(session)}\n"
+    out = [
+        IssueFile("issue.md", text.encode(), "text/markdown"),
+        IssueFile("client.log", _lines(r for r in rows if r.source == "web"), "text/plain"),
+        IssueFile("server.log", _lines(r for r in rows if r.source != "web"), "text/plain"),
+    ]
+    shots = db.scalars(
+        select(DebugScreenshot)
+        .where(DebugScreenshot.session_id == session.id)
+        .order_by(DebugScreenshot.id)
+    )
+    for n, shot in enumerate(shots, start=1):
+        ext = debugsession.IMAGE_TYPES[shot.mime]
+        name = f"{debugsession.SCREENSHOT_PREFIX}{n}.{ext}"
+        out.append(IssueFile(name, shot.data, shot.mime))
+    return out
+
+
+def zipped(items: list[IssueFile]) -> bytes:
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        for item in items:
+            # The images are compressed already: deflating them again costs time and wins nothing.
+            method = zipfile.ZIP_STORED if item.mime.startswith("image/") else zipfile.ZIP_DEFLATED
+            z.writestr(item.name, item.data, compress_type=method)
+    return buf.getvalue()

backend/app/issues/gitea.py

@@ -0,0 +1,288 @@
+"""The Gitea issue tracker a debug session's issue goes to — measured against Gitea 1.27.1
+before a line of this was written.
+
+Configured by an admin (sysconfig `issues_gitea_url` / `_repo` / `_token`, the token encrypted at
+rest). The repository must be PRIVATE: an issue carries its reporter's log — page titles, filter
+values, at Teljes (TRACE) what they typed into search — and a public repository would publish it. That is
+checked on every send, not only in the admin's "test connection", because a repository can be made
+public after the fact.
+
+What an issue is made of comes from `bundle.files` (the same files the zip export carries). Sending
+is three kinds of call, measured:
+  * `POST /repos/{repo}/issues` — the title and the body the user wrote;
+  * `POST /repos/{repo}/issues/{n}/assets?name=…` — ONE file per request (field `attachment`);
+  * `PATCH /repos/{repo}/issues/{n}` — the body again, with the screenshots shown inline once their
+    links exist.
+A private repository's attachment answers 404 to a browser not signed in to Gitea, which is why the
+composer's own preview shows our copies, never these links.
+
+Delivery keeps its progress in the session's draft (`delivery`: the issue number, the files still to
+upload, the links of those uploaded, whether the body shows the screenshots yet), so a failure
+half-way keeps the issue that exists and a retry does only what is missing — never a second issue.
+Every step is checkpointed (the caller's `db.commit`), so what did happen is kept whatever fails
+next — and the first checkpoint comes before the first call, with the tracker's settings read ABOVE
+it, so neither a row lock nor a read snapshot nor a pooled connection is held across the calls. The
+caller claims the session for the send first (`debugsession.claim_send`) and passes the claim's
+token in, which is what keeps a second send, an autosave or a screenshot out of the way; the claim
+is renewed by every progress report, and a report whose claim is gone raises rather than writing
+over the send that took it. `debugsession.not_uploaded` / `images_pending` read that progress.
+"""
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import Any, Literal
+
+import httpx
+from sqlalchemy.orm import Session
+
+from app import debugsession, logs, sysconfig
+from app.issues import bundle
+from app.models import DebugSession
+
+log = logs.get_logger(__name__)
+
+TIMEOUT_SECONDS = 20.0
+
+Reason = Literal[
+    "not_configured",  # url, repository or token missing
+    "unreachable",  # no answer, or a 5xx
+    "bad_token",  # 401/403: the token is wrong or lacks write:issue / read:repository
+    "repo_not_found",  # 404 on the repository
+    "public_repo",  # the repository is public — an issue would publish the reporter's log
+    "issues_disabled",  # the repository has its issue tracker switched off
+    "rejected",  # any other 4xx (a file type the instance does not allow, …), or an answer that is
+    # not the API's (a redirect — an http:// address behind https —, a page that is not JSON)
+]
+
+
+class GiteaError(Exception):
+    def __init__(self, reason: Reason) -> None:
+        super().__init__(reason)
+        self.reason: Reason = reason
+
+
+def _settings(db: Session) -> tuple[str, str, str]:
+    return (
+        sysconfig.get_str(db, "issues_gitea_url").strip().rstrip("/"),
+        sysconfig.get_str(db, "issues_gitea_repo").strip().strip("/"),
+        sysconfig.get_str(db, "issues_gitea_token").strip(),
+    )
+
+
+def target(db: Session) -> dict | None:
+    """Where a report goes, for the composer to say so — the repository — or None when no tracker is
+    configured (the report can then only be downloaded)."""
+    url, repo, token = _settings(db)
+    return {"repo": repo} if url and repo and token else None
+
+
+@contextmanager
+def _client(settings: tuple[str, str, str]) -> Iterator[tuple[httpx.Client, str]]:
+    # Takes the settings already read, not the session: reading them HERE opened a transaction one
+    # line after `deliver` had ended one, and held it across the calls below.
+    url, repo, token = settings
+    if not (url and repo and token):
+        raise GiteaError("not_configured")
+    with httpx.Client(
+        base_url=f"{url}/api/v1",
+        headers={"Authorization": f"token {token}", "Accept": "application/json"},
+        timeout=TIMEOUT_SECONDS,
+    ) as client:
+        yield client, repo
+
+
+def _call(client: httpx.Client, method: str, path: str, **kwargs) -> httpx.Response:
+    try:
+        r = client.request(method, path, **kwargs)
+    except httpx.HTTPError as exc:
+        log.warning(
+            "the issue tracker did not answer",
+            extra=logs.event("issues.gitea.unreachable", path=path, error=type(exc).__name__),
+        )
+        raise GiteaError("unreachable") from None
+    if r.status_code < 300:
+        return r
+    # The status only: Gitea's message can quote back what was sent — the user's own title.
+    log.warning(
+        "the issue tracker refused a call",
+        extra=logs.event("issues.gitea.refused", path=path, status=r.status_code),
+    )
+    if r.status_code in (401, 403):
+        raise GiteaError("bad_token")
+    if r.status_code == 404:
+        raise GiteaError("repo_not_found")
+    if r.status_code >= 500:
+        raise GiteaError("unreachable")
+    raise GiteaError("rejected")
+
+
+def _json(r: httpx.Response, *keys: str) -> dict[str, Any]:
+    """The answer as the API's JSON, holding `keys` — anything else is refused, not a crash, so a
+    step after the issue was created cannot take down the request that holds its record.
+
+    The CREATE call is the one place this cannot keep that record: its answer IS the record. An
+    answer it cannot read there leaves the session unsent, and a retry opens another issue — the
+    price of not being able to tell a refused create from an unreadable one."""
+    try:
+        data = r.json()
+    # silent-ok: not JSON is one of the answers refused (and logged) just below.
+    except ValueError:
+        data = None
+    if not isinstance(data, dict) or any(k not in data for k in keys):
+        log.warning(
+            "the issue tracker answered something that is not its API",
+            extra=logs.event("issues.gitea.unexpected", status=r.status_code),
+        )
+        raise GiteaError("rejected")
+    return data
+
+
+def _private_repo(client: httpx.Client, repo: str) -> dict:
+    data = _json(_call(client, "GET", f"/repos/{repo}"))
+    if not data.get("private"):
+        raise GiteaError("public_repo")
+    if not data.get("has_issues"):
+        raise GiteaError("issues_disabled")
+    return data
+
+
+def check(db: Session) -> dict:
+    """The admin's "test connection": the repository answers, is private and takes issues."""
+    with _client(_settings(db)) as (client, repo):
+        data = _private_repo(client, repo)
+    return {"repo": data.get("full_name") or repo, "url": data.get("html_url")}
+
+
+def preview(db: Session, text: str) -> str:
+    """The body as Gitea itself will render it (its markdown flavour, its sanitiser).
+
+    **No `Context`, deliberately — a repository context here does not fail the call, it kills the
+    tracker.** With one, Gitea's post-processor turns every hex-shaped word into a commit link, and
+    on the API's render path the commit checker it asks is nil: the whole Gitea process segfaults
+    and restarts, taking the git server (and, here, the container registry) down with it. Every
+    report carries hex — a tab id, a request id — so this was not an edge case but the only case.
+    Measured on throwaway instances (2026-09-20): `{"Mode": "gfm", "Context": "<repo>"}` with
+    `5645b1c0ae01` in the text crashes 1.26.4 and 1.27.1 and is fixed in 1.27.3 — but a self-hoster
+    runs whatever version they run, so the payload stays safe here rather than relying on theirs.
+    Dropping `Context` is not a downgrade of the preview: measured against the same body, the HTML
+    keeps its tables, its task lists and its highlighted code blocks. It only stops resolving
+    repo-relative links (a hash, a `#123`), which the issue page itself still resolves.
+    """
+    with _client(_settings(db)) as (client, _repo):
+        r = _call(client, "POST", "/markdown", json={"Text": text, "Mode": "gfm"})
+    return r.text
+
+
+def deliver(
+    db: Session,
+    session: DebugSession,
+    *,
+    token: str,
+    checkpoint: Callable[[], None],
+    before_create: Callable[[], None] | None = None,
+    on_created: Callable[[], None] | None = None,
+) -> str:
+    """Send the session's issue, or finish sending it; returns its URL.
+
+    `token` is the caller's claim on this session (`debugsession.claim_send`). Every progress report
+    renews it and checks the row still holds it, so a send that outlived its lease stops here rather
+    than writing over the one that took over (`debugsession.SendClaimLost`).
+
+    `checkpoint` persists what has happened so far and is called after every step (the caller's
+    commit — this module does not decide when a transaction ends). `before_create` runs right before
+    the tracker is asked to open a NEW issue, after the checks that can refuse it without asking,
+    and may raise to stop it; `on_created` runs right after one was opened, in time to be committed
+    by the SAME checkpoint that first writes `issue_url` — anything the caller must not be able to
+    lose separately from the link belongs there.
+    """
+    state = debugsession.delivery(session)
+    files = bundle.files(db, session)
+    attachments = [f for f in files if f.name != "issue.md"]
+    settings = _settings(db)
+    # Reading the bundle and the tracker's settings opened a transaction; end it before the first
+    # call, so nothing holds a snapshot (and an idle connection) across minutes of tracker I/O.
+    # The settings are read HERE and handed to `_client`, not read inside it: reading them there
+    # was a SELECT one line after this commit, which reopened the transaction and held it — idle,
+    # with its snapshot pinned — across the repository check and the create (a review
+    # measured it in pg_stat_activity). A comment saying otherwise sat right here.
+    checkpoint()
+    with _client(settings) as (client, repo):
+        _private_repo(client, repo)
+        if "number" not in state:
+            if before_create is not None:
+                before_create()
+            created = _json(
+                _call(
+                    client,
+                    "POST",
+                    f"/repos/{repo}/issues",
+                    json={"title": bundle.title_of(session), "body": bundle.body_of(session)},
+                ),
+                "number",
+                "html_url",
+            )
+            # Built ON the state read at the start so nothing already in it is dropped. The claim
+            # is NOT among those things, whatever this comment used to say: `set_delivery` strips
+            # any `sending` passed to it and stamps the row's own from `token` (removing
+            # the spread left the whole suite green, because the claim never travelled here).
+            state = {
+                **state,
+                "number": created["number"],
+                "pending": [f.name for f in attachments],
+                "links": {},
+            }
+            session.issue_url = created["html_url"]
+            try:
+                debugsession.set_delivery(db, session, state, token)
+            except debugsession.SendClaimLost:
+                # The one step where losing the claim costs something irreversible: the issue is
+                # already open on the tracker and this is what would have recorded its link. We
+                # still must not write — another send owns the row and is opening its own issue —
+                # so say which issue was left behind, because nothing else will.
+                # TRY400: the traceback is one SendClaimLost carrying the session id and
+                # nothing else; the issue number below is the whole news.
+                log.error(  # noqa: TRY400
+                    "an issue was created by a send that had already lost its claim",
+                    extra=logs.event(
+                        "issues.gitea.orphaned",
+                        number=created["number"],
+                        session_id=session.id,
+                    ),
+                )
+                raise
+            if on_created is not None:
+                on_created()
+            checkpoint()
+            log.info(
+                "issue created",
+                extra=logs.event("issues.gitea.created", number=created["number"]),
+            )
+        number = state["number"]
+        for item in attachments:
+            if item.name not in state["pending"]:
+                continue
+            asset = _json(
+                _call(
+                    client,
+                    "POST",
+                    f"/repos/{repo}/issues/{number}/assets",
+                    params={"name": item.name},
+                    files={"attachment": (item.name, item.data, item.mime)},
+                ),
+                "browser_download_url",
+            )
+            state = {
+                **state,
+                "pending": [n for n in state["pending"] if n != item.name],
+                "links": {**state["links"], item.name: asset["browser_download_url"]},
+            }
+            debugsession.set_delivery(db, session, state, token)
+            checkpoint()
+        shots = [n for n in state["links"] if n.startswith(debugsession.SCREENSHOT_PREFIX)]
+        if shots and not state.get("images_shown"):
+            images = "\n".join(f"![{n}]({state['links'][n]})" for n in sorted(shots))
+            body = f"{bundle.body_of(session)}\n\n---\n\n{images}"
+            _call(client, "PATCH", f"/repos/{repo}/issues/{number}", json={"body": body})
+            debugsession.set_delivery(db, session, {**state, "images_shown": True}, token)
+            checkpoint()
+    return session.issue_url or ""

backend/app/logs.py

@@ -0,0 +1,837 @@
+"""Structured logging for every Siftlode process — the ONE place logging is configured.
+
+Before this module a single deployment printed FOUR different log formats: uvicorn's
+`log_config.json` for the API, a hand-rolled StreamHandler in `main.py` for everything that did not
+start under uvicorn (tests, scripts), `logging.basicConfig()` in the worker and in the download
+child (no timestamp at all), and alembic's `fileConfig`. None of them carried a correlation id, and
+uvicorn's access log printed the query string of every request (`?account=1`, `?source=feed`) — so
+the logs were both unjoinable and leaky. `configure_logging()` replaces all four.
+
+Event shape — the OpenTelemetry log data model, without the SDK; one JSON object per line:
+    ts · level · sev · source · logger · event · msg · attrs
+plus whatever correlation the context carries (`request_id`, `user_id`, `debug_session_id`,
+`job_id`) and the app version. That shape is what the admin log console filters on and what a Gitea
+issue attachment will carry, so it is deliberately flat and stable.
+
+Call sites stay ordinary stdlib logging:
+
+    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
+what makes a line queryable later, so add one wherever the line matters.
+
+REDACTION IS APPLIED AT THE HANDLER, not at the call site: every message, every attr value and
+every traceback passes `redact()` on the way out. That is the whole point — a secret cannot be
+leaked by forgetting to redact it at one of ~125 call sites, and a new call site is safe by
+default. Never logged, at any level: passwords, tokens (session, reset/verify, setup, share,
+OAuth), cookie blobs, secret config values, and email addresses.
+"""
+
+import contextlib
+import contextvars
+import json
+import logging
+import logging.config
+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
+
+from app.config import settings
+from app.ratelimit import RateLimiter, client_key
+
+# One level below DEBUG for the "Teljes / TRACE" diagnostics level (search strings, redacted request
+# bodies). Registered on import so `logging.getLogger(...).log(logs.TRACE, …)` and a `LOG_LEVEL=TRACE`
+# both work in every process, including one that never calls configure_logging (a test).
+TRACE = 5
+logging.addLevelName(TRACE, "TRACE")
+
+# OpenTelemetry severity numbers for our level names. Kept beside the level because the number is
+# what a log backend sorts and filters on; the name is for humans reading a terminal.
+SEVERITY: dict[str, int] = {
+    "TRACE": 1,
+    "DEBUG": 5,
+    "INFO": 9,
+    "WARNING": 13,
+    "ERROR": 17,
+    "CRITICAL": 21,
+}
+
+# Which process this is. Set by configure_logging; every line carries it so one Loki/DB query can
+# separate the API's view of a job from the worker's.
+_source = "api"
+
+
+# --- correlation context -------------------------------------------------------------------
+# contextvars, like quota's actor attribution (app/quota.py): set at an entry point, read by the
+# formatter, never threaded through call signatures. A child task copies the context at creation,
+# so anything set before `await call_next(...)` is visible to the whole request.
+_request_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "log_request_id", default=None
+)
+_user_id: contextvars.ContextVar[int | None] = contextvars.ContextVar("log_user_id", default=None)
+_debug_session: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "log_debug_session", default=None
+)
+_job_id: contextvars.ContextVar[int | None] = contextvars.ContextVar("log_job_id", default=None)
+
+_CONTEXT_VARS = {
+    "request_id": _request_id,
+    "user_id": _user_id,
+    "debug_session_id": _debug_session,
+    "job_id": _job_id,
+}
+
+
+class _RequestScope:
+    """What the auth dependency learns about a request, for every line logged after it.
+
+    A MUTABLE object behind a contextvar, not plain contextvars, because of how a request actually
+    runs: FastAPI resolves a sync dependency (`auth.current_user`) in a threadpool on a COPY of the
+    context, so a `ContextVar.set()` there is gone by the time the handler runs — measured: that is
+    how the account never reached a handler's own lines. `log_requests` installs one scope per
+    request; every copied context shares the same object, so what the dependency writes is seen by
+    the handler and by the request line itself."""
+
+    __slots__ = ("user_id", "level", "debug_session_id")
+
+    def __init__(self) -> None:
+        self.user_id: int | None = None
+        # The user's consented diagnostics level as a logging number; None at the base level.
+        self.level: int | None = None
+        # The user's own open debug session this request named, else None.
+        self.debug_session_id: str | None = None
+
+
+_scope: contextvars.ContextVar[_RequestScope | None] = contextvars.ContextVar(
+    "log_request_scope", default=None
+)
+
+
+def set_user(
+    user_id: int | None,
+    level: str = "INFO",
+    until: datetime | None = None,
+    debug_session: str | None = None,
+) -> None:
+    """Attribute the rest of this request's log lines to `user_id`, and log them at the user's
+    consented diagnostics `level` until `until` ("INFO" = no elevation). Called from the
+    auth dependency — the one place the session is actually resolved into an account — rather than
+    from the request middleware, which runs OUTSIDE the session middleware.
+
+    `debug_session` tags every line with the user's open debug session. The caller has
+    already checked it is theirs and open; a session's level arrives here as `level`/`until`.
+
+    The root logger's floor is tracked per elevation: a request without the session's header (an
+    `<img>`, a `<video>` — the browser sends those itself) carries only the user's own level, and
+    must not lower the floor a concurrent request of the session still needs."""
+    _user_id.set(user_id)
+    scope = _scope.get()
+    if scope is None:  # outside log_requests (a script, a unit test): this context only
+        scope = _RequestScope()
+        _scope.set(scope)
+    elevated = level != "INFO" and until is not None and until > datetime.now(timezone.utc)
+    scope.user_id = user_id
+    scope.debug_session_id = debug_session
+    scope.level = resolve_level(level) if elevated else None
+    if user_id is not None:
+        key = user_id if debug_session is None else (user_id, debug_session)
+        _track_elevation(key, scope.level, until)
+
+
+def set_job(job_id: int | None) -> None:
+    """Attribute this process's log lines to a download job — for the download CHILD, whose whole
+    life is one job (the worker uses `bind()` per job instead, since it juggles several)."""
+    _job_id.set(job_id)
+
+
+@contextlib.contextmanager
+def bind(**fields: Any):
+    """Bind correlation fields for the duration of a block (a worker job, a scheduler run):
+
+        with logs.bind(job_id=job.id):
+            ...
+
+    Unknown field names are ignored rather than raising — a caller binding a field this module does
+    not know about is a typo, not a reason to take down a download."""
+    tokens = [(_CONTEXT_VARS[k].set(v)) for k, v in fields.items() if k in _CONTEXT_VARS]
+    keys = [k for k in fields if k in _CONTEXT_VARS]
+    try:
+        yield
+    finally:
+        for key, token in zip(keys, tokens, strict=True):
+            _CONTEXT_VARS[key].reset(token)
+
+
+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).
+
+    `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}
+
+
+# --- redaction -----------------------------------------------------------------------------
+# Substring matching, not exact keys: the same secret travels as `password`, `current_password`,
+# `new_password`, `smtp_password`, `plex_server_token`, `access_token`, … Matching on the PART is
+# what makes a key we have never seen safe by default.
+_SECRET_KEY_PARTS = (
+    "password",
+    "passphrase",
+    "token",
+    "secret",
+    "cookie",
+    "authorization",
+    "auth_header",
+    "ciphertext",
+    "private_key",
+    "api_key",
+    "apikey",
+    "credential",
+    "session_key",
+)
+
+# Query/fragment parameters that carry a credential in a URL we log (OAuth `code`/`state`, our own
+# `?token=` setup and share links, `#verify=` / `#reset=` fragments).
+_SECRET_PARAM_NAMES = (
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "token",
+    "code",
+    "state",
+    "key",
+    "secret",
+    "password",
+    "pwd",
+    "sig",
+    "signature",
+    "verify",
+    "reset",
+    "setup",
+)
+_SECRET_PARAM_RE = re.compile(
+    r"\b((?:" + "|".join(_SECRET_PARAM_NAMES) + r")=)([^&\s\"']+)",
+    re.IGNORECASE,
+)
+
+# Deliberately loose: over-matching redacts a non-address that looks like one (harmless), while
+# under-matching puts a real address in a log we attach to an issue (not harmless).
+_EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+
+REDACTED = "[redacted]"
+# `extra={PERSIST: False}` keeps a line out of the `log_events` table while stdout still gets it —
+# how `log_requests` caps anonymous traffic per client (app/logsink.py reads it).
+PERSIST = "persist"
+REDACTED_EMAIL = "[email]"
+
+
+def redact_text(text: str) -> str:
+    """Scrub a free-text string: credential-bearing URL params and email addresses."""
+    scrubbed = _SECRET_PARAM_RE.sub(lambda m: f"{m.group(1)}{REDACTED}", text)
+    return _EMAIL_RE.sub(REDACTED_EMAIL, scrubbed)
+
+
+def redact_query(query: str) -> str:
+    """Scrub a raw query string. DECODED first: the text rules match what was typed, and a browser
+    sends it percent-encoded — `someone%40example.com` is an address `_EMAIL_RE` cannot see. Each
+    parameter also goes through the key rules, so `?new_password=` goes as `redact` would drop it."""
+    pairs = parse_qsl(query, keep_blank_values=True)
+    return "&".join(f"{key}={_redact_param(key, value)}" for key, value in pairs)
+
+
+def _redact_param(key: str, value: str) -> str:
+    """One decoded `key=value` pair. The parameter-NAME rule is applied to the key here rather than
+    left to `_SECRET_PARAM_RE` over the rebuilt pair: that pattern was written for the raw,
+    percent-encoded query, where a value holds no literal space, `&` or quote, and its value class
+    stops at the first one. On decoded text `?state=a%20b` would keep its tail and `?code=%20abc`
+    would not match at all — the whole credential straight into the line."""
+    if key.lower() in _SECRET_PARAM_NAMES:
+        return REDACTED
+    return str(redact(value, key=key))
+
+
+def redact(value: Any, *, key: str = "") -> Any:
+    """Recursively scrub a structure destined for the log.
+
+    A value whose KEY names a secret is dropped whole (we never log a prefix of a token — a prefix
+    is still a leak and still useless). Everything else is scrubbed as text. Depth is bounded by
+    the structures we actually log (attrs dicts), and non-JSON types fall through to `str`."""
+    lowered = key.lower()
+    if key and any(part in lowered for part in _SECRET_KEY_PARTS):
+        return REDACTED
+    if isinstance(value, dict):
+        return {k: redact(v, key=str(k)) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [redact(v, key=key) for v in value]
+    if isinstance(value, str):
+        return redact_text(value)
+    return value
+
+
+# --- 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", _SCRUBBED_STACK}
+)
+
+
+class ContextFilter(logging.Filter):
+    """Copies the correlation contextvars onto the record. A Filter (not the formatter) so the
+    values are captured at emit time, before a QueueHandler can move the record to another
+    thread — the DB sink depends on that."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        for name, var in _CONTEXT_VARS.items():
+            value = var.get()
+            if value is not None and not hasattr(record, name):
+                setattr(record, name, value)
+        scope = _scope.get()
+        if scope is not None and scope.user_id is not None and not hasattr(record, "user_id"):
+            record.user_id = scope.user_id
+        if (
+            scope is not None
+            and scope.debug_session_id is not None
+            and not hasattr(record, "debug_session_id")
+        ):
+            record.debug_session_id = scope.debug_session_id
+        return True
+
+
+class LevelGate(logging.Filter):
+    """The configured level, enforced at the HANDLER, with one exception: the lines of a request
+    whose user raised their diagnostics level.
+
+    The root logger's level cannot do this alone: it is one number for the whole process, and the
+    point is to log ONE user's requests in detail while everyone else's stay at the base level. So
+    the root is lowered to the lowest level any active elevation needs (`_track_elevation`), and
+    this gate drops what only an elevation let through unless the line belongs to that elevated
+    request. It also marks such a line `elevated`, which is what makes the `log_events` sink keep
+    every line of that request, not just its warnings."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        scope = _scope.get()
+        if scope is not None and scope.level is not None:
+            record.elevated = True
+            return record.levelno >= min(scope.level, _base_level)
+        return record.levelno >= _base_level
+
+
+def _record_attrs(record: logging.LogRecord) -> dict[str, Any]:
+    extra = {k: v for k, v in vars(record).items() if k not in _RECORD_STANDARD}
+    attrs = dict(getattr(record, "attrs", None) or {})
+    attrs.update({k: v for k, v in extra.items() if k not in _CONTEXT_VARS})
+    return attrs
+
+
+def _safe_message(record: logging.LogRecord) -> str:
+    """`record.getMessage()` raises if the args don't match the format string. A broken log call
+    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})"
+
+
+def record_fields(record: logging.LogRecord) -> dict[str, Any]:
+    """The event as structured fields, REDACTED — the one definition both the stdout line and the
+    `log_events` row are built from, so the two sinks can never disagree about what is safe to keep.
+    Absent optional fields are left out; `ts` is an aware datetime."""
+    fields: dict[str, Any] = {
+        "ts": datetime.fromtimestamp(record.created, timezone.utc),
+        "level": record.levelname,
+        "sev": SEVERITY.get(record.levelname, 9),
+        "source": _source,
+        "logger": record.name,
+        "msg": redact_text(_safe_message(record)),
+    }
+    code = getattr(record, "event", None)
+    if code:
+        fields["event"] = code
+    for name in _CONTEXT_VARS:
+        value = getattr(record, name, None)
+        if value is not None:
+            fields[name] = value
+    attrs = _record_attrs(record)
+    if attrs:
+        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)
+    fields["version"] = settings.app_version
+    return fields
+
+
+class JsonFormatter(logging.Formatter):
+    """One JSON object per line — the shape Loki and the `log_events` table both ingest."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload = record_fields(record)
+        payload["ts"] = payload["ts"].isoformat(timespec="milliseconds")
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+class TextFormatter(logging.Formatter):
+    """Human-readable single line for a terminal (`LOG_FORMAT=text`): the same content, ordered for
+    reading. Redaction applies here too — a dev log is still a log someone pastes into an issue."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        stamp = datetime.fromtimestamp(record.created, timezone.utc).strftime("%H:%M:%S.%f")[:-3]
+        head = f"{stamp} {record.levelname:<5} [{record.name}]"
+        rid = getattr(record, "request_id", None)
+        if rid:
+            head += f" {rid}"
+        code = getattr(record, "event", None)
+        line = f"{head} {code + ' — ' if code else ''}{redact_text(_safe_message(record))}"
+        attrs = _record_attrs(record)
+        if attrs:
+            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
+
+
+# --- configuration -------------------------------------------------------------------------
+# Third-party loggers that are noisy at our own level. Pinned explicitly so the diagnostics knob can
+# lower the ROOT level to DEBUG/TRACE without drowning the output in SQL statements and HTTP chatter
+# — raising THESE is a deliberate, separate act (the admin log console).
+_THIRD_PARTY_LEVELS = {
+    "sqlalchemy": "WARNING",
+    "sqlalchemy.engine": "WARNING",
+    "apscheduler": "WARNING",
+    "urllib3": "WARNING",
+    "httpx": "WARNING",
+    "httpcore": "WARNING",
+    "asyncio": "WARNING",
+    "PIL": "WARNING",
+    "alembic": "INFO",
+    # uvicorn's own startup/shutdown/WebSocket lines are worth keeping; its ACCESS log is not —
+    # it is one line per request with the query string in it, replaced by `log_requests` below.
+    "uvicorn": "INFO",
+    "uvicorn.error": "INFO",
+    "uvicorn.access": "CRITICAL",
+}
+
+
+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 the console's
+    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."""
+    value = logging.getLevelName(name)
+    if not isinstance(value, int):
+        raise ValueError(f"unknown log level {name!r}")
+    return value
+
+
+def configure_logging(source: str) -> None:
+    """Configure logging for THIS process. Call once, first thing, in every entry point:
+    `main.py` (api), `worker.main`, `downloads/runner.main`, `alembic/env.py`.
+
+    `source` names the process in every line. The level starts at `LOG_LEVEL` (the bootstrap default);
+    the runtime admin knob goes through `set_level()` instead, so changing it needs no restart.
+
+    Our loggers deliberately keep `propagate=True` and own no handler: everything reaches the single
+    root StreamHandler. That is what keeps `caplog` working in tests, and it means a new logger name
+    is configured the moment it is created."""
+    global _source
+    _source = source
+    formatter = settings.log_format
+    logging.config.dictConfig(
+        {
+            "version": 1,
+            # Never disable loggers created at import time (module-level `getLogger` calls run
+            # before this function does).
+            "disable_existing_loggers": False,
+            "formatters": {
+                "json": {"()": f"{__name__}.JsonFormatter"},
+                "text": {"()": f"{__name__}.TextFormatter"},
+            },
+            "filters": {
+                "context": {"()": f"{__name__}.ContextFilter"},
+                "gate": {"()": f"{__name__}.LevelGate"},
+            },
+            "handlers": {
+                "stdout": {
+                    "class": "logging.StreamHandler",
+                    "stream": sys.stdout,
+                    "formatter": formatter,
+                    "filters": ["context", "gate"],
+                }
+            },
+            "root": {"level": resolve_level(settings.log_level), "handlers": ["stdout"]},
+            "loggers": {name: {"level": lvl} for name, lvl in _THIRD_PARTY_LEVELS.items()},
+        }
+    )
+    set_level(settings.log_level)
+
+
+def set_level(name: str) -> None:
+    """Change the running process's level (the `log_level` admin knob). Third-party loggers keep
+    their pinned levels, so turning on DEBUG shows OUR detail, not SQLAlchemy's."""
+    global _base_level
+    _base_level = resolve_level(name)
+    _apply_root_level(force=True)
+
+
+def current_level() -> str:
+    """The configured level — not the root logger's, which an active elevation may have lowered."""
+    return logging.getLevelName(_base_level or logging.getLogger().getEffectiveLevel())
+
+
+# --- per-user elevation -----------------------------------------------------------
+# The base level (`LOG_LEVEL`, then the admin knob). NOTSET until configure_logging runs — a unit
+# test, a script — so the gate lets everything through there, as it did before the gate existed.
+_base_level = logging.NOTSET
+# → (level number, expiry) for every elevation this process has seen and not yet expired: a user's
+# own, by user id, and a debug session's, by (user id, session id) — its requests alone carry
+# its level, so it is tracked apart from the user's own requests.
+_ElevationKey = int | tuple[int, str]
+_elevations: dict[_ElevationKey, tuple[int, datetime]] = {}
+_elevations_lock = threading.Lock()
+_root_applied: int | None = None
+
+
+def _track_elevation(key: _ElevationKey, level: int | None, until: datetime | None) -> None:
+    with _elevations_lock:
+        if level is None or until is None:
+            _elevations.pop(key, None)
+        else:
+            _elevations[key] = (level, until)
+        active = bool(_elevations)
+    if active or _root_applied != _base_level:
+        _apply_root_level()
+
+
+def _apply_root_level(force: bool = False) -> None:
+    """Root level = the lowest of the base and every unexpired elevation (expired ones are pruned
+    here). `setLevel` clears every logger's level cache, so it runs only when the number changes."""
+    global _root_applied
+    if _base_level == logging.NOTSET:
+        return  # not configured: the root keeps whatever the process set up
+    now = datetime.now(timezone.utc)
+    # The level is SET under the lock too, not just computed: two threads that each computed a
+    # different answer would otherwise apply them in either order, and the older one could win —
+    # the root back at the base while an elevation is still active.
+    with _elevations_lock:
+        for key in [k for k, (_, until) in _elevations.items() if until <= now]:
+            del _elevations[key]
+        lowest = min([_base_level, *(lvl for lvl, _ in _elevations.values())])
+        if force or lowest != _root_applied:
+            logging.getLogger().setLevel(lowest)
+            _root_applied = lowest
+
+
+# --- erased accounts ------------------------------------------------------------------------
+# `auth.purge_user` deletes an account's `log_events` rows, but a line about that account can still
+# be on its way: the erasing request's own access line is logged AFTER the handler committed, a queued
+# row waits for the sink's writer, a background task logs later. Those rows are stored without the
+# account (`logsink` asks here). Remembered for an hour in this process — a line later than that has
+# no request left to come from, and the retention job is the backstop for any other process.
+ERASED_MEMORY_SECONDS = 3600.0
+_erased: dict[int, float] = {}
+_erased_lock = threading.Lock()
+# Held by whoever checks rows against `is_erased` AND writes them (`erasure_guard`). `forget_user`
+# takes it too, so an erasure waits for a write that already passed the check to commit — and the
+# purge's DELETE, which runs after `forget_user`, then removes those rows as well. Without it a row
+# checked a moment before the erasure could be inserted a moment after the DELETE.
+_erasure_guard = threading.Lock()
+
+
+def erasure_guard() -> threading.Lock:
+    """Hold this around "drop erased accounts from these rows, insert them, commit"."""
+    return _erasure_guard
+
+
+def forget_user(user_id: int) -> None:
+    """Mark `user_id` erased: no line logged about it from now on is stored under its id. Call BEFORE
+    deleting its rows (see `_erasure_guard`)."""
+    now = time.monotonic()
+    with _erasure_guard, _erased_lock:
+        for stale in [u for u, at in _erased.items() if now - at > ERASED_MEMORY_SECONDS]:
+            del _erased[stale]
+        _erased[user_id] = now
+    with _elevations_lock:
+        for key in [
+            k for k in _elevations if k == user_id or (isinstance(k, tuple) and k[0] == user_id)
+        ]:
+            del _elevations[key]
+    # That pop can have removed the lowest elevation, and the root level is the lowest of the base
+    # and every unexpired one. Recomputed here rather than left to whichever later request happens
+    # to call `_track_elevation` — the invariant `_apply_root_level` documents holds at every pop.
+    _apply_root_level()
+
+
+def end_session_elevation(session_id: str) -> None:
+    """A debug session was stopped: its elevation ends now, not at its cap."""
+    with _elevations_lock:
+        for key in [k for k in _elevations if isinstance(k, tuple) and k[1] == session_id]:
+            del _elevations[key]
+    _apply_root_level()
+
+
+def is_erased(user_id: int | None) -> bool:
+    if user_id is None:
+        return False
+    with _erased_lock:
+        at = _erased.get(user_id)
+    return at is not None and time.monotonic() - at <= ERASED_MEMORY_SECONDS
+
+
+def current_source() -> str:
+    """The process name `configure_logging` was given (api, worker, runner, alembic)."""
+    return _source
+
+
+# --- request logging -----------------------------------------------------------------------
+# A client may supply its own request id so a browser log line and a server line join up.
+# Accepted only in this shape: it ends up in a log field, and an unbounded header would be a way to
+# write arbitrary text into the log.
+_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), 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")
+
+# 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/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):
+    """The single access-log line, replacing uvicorn's.
+
+    What changes versus `uvicorn.access`: the ROUTE TEMPLATE instead of the concrete path (so
+    `/api/videos/{video_id}` groups), never the query string (it carried `?account=`, and at TRACE
+    the redacted query belongs in attrs, not in the URL), a request id echoed back in
+    `X-Request-Id` (with the template in `X-Route`), the duration, and the account — read from `request.state`, which the auth
+    dependency fills, because this middleware sits outside both the session middleware and the
+    downstream task's context."""
+    incoming = request.headers.get("x-request-id", "")
+    rid = incoming if _REQUEST_ID_RE.match(incoming) else uuid.uuid4().hex[:16]
+    token = _request_id.set(rid)
+    scope = _RequestScope()
+    scope_token = _scope.set(scope)
+    request.state.request_id = rid
+    started = time.perf_counter()
+    try:
+        response = await call_next(request)
+    except Exception:
+        # The unhandled-exception path: FastAPI's ServerErrorMiddleware re-raises after its own
+        # 500, so without this the ONE request that most needs a log line is the one with no
+        # access-log entry at all.
+        _request_log.exception(
+            "request failed",
+            extra={
+                **event(
+                    "http.request",
+                    method=request.method,
+                    path=_route_template(request),
+                    duration_ms=round((time.perf_counter() - started) * 1000, 1),
+                ),
+                **_request_owner(request, logging.ERROR),
+            },
+        )
+        _scope.reset(scope_token)
+        _request_id.reset(token)
+        raise
+    duration_ms = round((time.perf_counter() - started) * 1000, 1)
+    status = response.status_code
+    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:
+        level = logging.WARNING
+    else:
+        level = logging.DEBUG if quiet else logging.INFO
+    attrs: dict[str, Any] = {
+        "method": request.method,
+        "path": _route_template(request),
+        "status": status,
+        "duration_ms": duration_ms,
+    }
+    # Teljes (TRACE) the user consented to: the query string too — redacted, and in attrs only, never
+    # in the message.
+    if request.url.query and _traced(scope):
+        attrs["query"] = redact_query(request.url.query)
+    _request_log.log(
+        level,
+        "%s %s %s",
+        request.method,
+        _route_template(request),
+        status,
+        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
+    # templates the path itself.
+    matched = _matched_route(request)
+    if matched:
+        response.headers["X-Route"] = matched
+    _scope.reset(scope_token)
+    _request_id.reset(token)
+    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
+    privacy policy promises those are kept only for a user who agreed to it."""
+    return scope.level is not None and scope.level <= TRACE
+
+
+# Anonymous request lines kept per client per minute. Signed-in traffic is not capped: it is a known
+# account and exactly what an admin needs to see. Anonymous traffic is where the volume can come from
+# nobody in particular — a scanner walking `/wp-login.php`, a bot on a share link — and each of its
+# 404s is a WARNING that would otherwise land in `log_events` without limit. The client key is an
+# in-memory counter key only; no address is ever written to a log line or a row.
+ANONYMOUS_LINES_PER_MINUTE = 60
+_anonymous_lines = RateLimiter(ANONYMOUS_LINES_PER_MINUTE, 60.0)
+
+
+def _request_owner(request, level: int) -> dict[str, Any]:
+    """`extra=` fields naming who the request belongs to, and whether its line may be stored. The
+    account comes from `request.state` (filled by the auth dependency), so it lands in the line's
+    top-level `user_id` — the correlation field — rather than in `attrs`."""
+    user_id = getattr(request.state, "user_id", None)
+    if user_id is not None:
+        return {"user_id": user_id}
+    if level < logging.INFO:
+        return {}  # a quiet line is never stored anyway — don't spend the client's allowance on it
+    return {} if _anonymous_lines.allow(client_key(request)) else {PERSIST: False}
+
+
+def _matched_route(request) -> str | None:
+    """The matched route's template (`/api/videos/{video_id}`), or None when nothing matched."""
+    return getattr(request.scope.get("route"), "path", None)
+
+
+def _route_template(request) -> str:
+    """The matched route's template, else the raw path for a 404 or a static file. Never the query
+    string."""
+    return _matched_route(request) or request.url.path

backend/app/logsink.py

@@ -0,0 +1,367 @@
+"""The `log_events` sink: the stored copy of the log the diagnostics console reads.
+
+stdout stays the complete log (docker keeps 3×50 MB of it); this table keeps the part worth querying
+for `log_retention_days`:
+
+  * every WARNING and above,
+  * the `http.request` line of every request at INFO or above (not the DEBUG-level health checks and
+    static files),
+  * every line of a request whose user raised their diagnostics level (`logs.LevelGate`
+    marks them), which is the detail they consented to have kept,
+  * nothing a caller marked `extra={logs.PERSIST: False}` — how the request log caps anonymous
+    traffic per client.
+
+What the table must never do is slow down or break the code that logs. So a line is redacted and
+turned into a row on the CALLER's thread (the same `logs.record_fields` the stdout line is built
+from), put on a bounded queue without blocking, and written in batches by one background thread
+on its own connection — never inside a request's transaction. A full queue drops the row and
+counts it; a failed write drops the batch and says so on stderr. Both are reported rather than
+retried: a log that retries into a sick database is how a small outage becomes a big one.
+
+Flood control is the second half. On 2026-09-16 a YouTube RSS outage made prod log 11k near-identical
+warnings in four hours. stdout keeps them all; the table keeps `REPEATS_PER_MINUTE` of each message
+template per minute and one `log.repeats_suppressed` row saying how many more there were.
+
+Core layer: imports `logs`, `db`, `models`, `config` — nothing above them.
+"""
+
+import atexit
+import json
+import logging
+import queue
+import re
+import sys
+import threading
+import time
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from sqlalchemy import delete, insert
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session
+
+from app import logs
+from app.config import settings
+from app.db import engine
+from app.models import LogEvent
+from app.utils import iso
+
+QUEUE_MAX = 10_000
+BATCH_MAX = 500
+FLUSH_SECONDS = 1.0
+REPEATS_PER_MINUTE = 30
+REPEAT_WINDOW_SECONDS = 60.0
+# Distinct templates tracked per window. Past this many, a new template is stored without counting
+# — the limiter must not become the unbounded thing it exists to prevent.
+_REPEAT_KEYS_MAX = 2_000
+
+# Column widths from models.LogEvent. A value past its column would fail the WHOLE batch it rides in.
+_LIMITS = {
+    "level": 10,
+    "source": 16,
+    "logger": 128,
+    "event": 64,
+    "request_id": 64,
+    "debug_session_id": 64,
+    "version": 64,
+    "msg": 8_000,
+    "exc": 32_000,
+}
+
+_log = logs.get_logger(__name__)
+
+
+def should_store(record: logging.LogRecord) -> bool:
+    """Whether this record belongs in `log_events` (see the module docstring)."""
+    if getattr(record, logs.PERSIST, True) is False:
+        return False
+    if record.levelno >= logging.WARNING or getattr(record, "elevated", False):
+        return True
+    return getattr(record, "event", None) == "http.request" and record.levelno >= logging.INFO
+
+
+def _without_nul(value: Any) -> Any:
+    """`value` with every NUL character replaced, in keys and nested values alike. Postgres refuses
+    NUL in text and `\\u0000` in JSONB, and a refused row fails the WHOLE batch it rides in — every
+    user's rows with it. Anything logged can carry one (`GET /assets/%00` logs the decoded path)."""
+    if isinstance(value, str):
+        return value.replace("\x00", "�")
+    if isinstance(value, dict):
+        return {_without_nul(k): _without_nul(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_without_nul(v) for v in value]
+    return value
+
+
+def to_row(fields: dict[str, Any]) -> dict[str, Any]:
+    """`logs.record_fields` output → a `log_events` row: known columns only, text clipped to its
+    column and free of NUL, attrs made JSON-safe (anything exotic becomes its `str`, as on stdout)."""
+    row = {
+        column: fields.get(column) for column in LogEvent.__table__.columns.keys() if column != "id"
+    }
+    for column, limit in _LIMITS.items():
+        value = row.get(column)
+        if isinstance(value, str):
+            value = _without_nul(value)
+            row[column] = value[: limit - 1] + "…" if len(value) > limit else value
+    if row["attrs"] is not None:
+        row["attrs"] = _without_nul(
+            json.loads(json.dumps(row["attrs"], ensure_ascii=False, default=str))
+        )
+    return row
+
+
+def without_erased(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """The rows, with the account taken off any whose account was erased meanwhile
+    (`logs.forget_user`). Checked right before the INSERT, under `logs.erasure_guard()` held until
+    the commit: a row built before the erasure can still be waiting for its batch."""
+    for row in rows:
+        if logs.is_erased(row.get("user_id")):
+            row["user_id"] = None
+    return rows
+
+
+def _notice(code: str, msg: str, **attrs: Any) -> dict[str, Any]:
+    """A row the sink writes about ITSELF. Built directly, not logged: logging it would route it back
+    through this sink (and the writer thread's own records are deliberately ignored)."""
+    return to_row(
+        {
+            "ts": datetime.now(timezone.utc),
+            "level": "WARNING",
+            "sev": logs.SEVERITY["WARNING"],
+            "source": logs.current_source(),
+            "logger": _log.name,
+            "event": code,
+            "msg": msg,
+            "attrs": attrs,
+            "version": settings.app_version,
+        }
+    )
+
+
+_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)."""
+
+    def __init__(self, per_window: int, window_seconds: float):
+        self.per_window = per_window
+        self.window = window_seconds
+        self.started = time.monotonic()
+        self.seen: dict[tuple[str, str, int], int] = {}
+
+    def admit(self, key: tuple[str, str, int] | None) -> bool:
+        if key is None:
+            return True
+        count = self.seen.get(key)
+        if count is None and len(self.seen) >= _REPEAT_KEYS_MAX:
+            return True
+        self.seen[key] = (count or 0) + 1
+        return self.seen[key] <= self.per_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(
+                "log.repeats_suppressed",
+                f"{count - self.per_window} more like this were not stored",
+                logger=logger,
+                template=logs.redact_text(template),
+                suppressed=count - self.per_window,
+                window_seconds=int(self.window),
+            )
+            for (logger, template, _level), count in self.seen.items()
+            if count > self.per_window
+        ]
+        self.seen.clear()
+        self.started = now
+        return notices
+
+
+class LogSink(logging.Handler):
+    """The handler plus its writer. `start()` runs the writer thread; a test drives `write_pending()`
+    directly instead, on its own thread, with no timing involved."""
+
+    def __init__(self, bind: Engine = engine):
+        super().__init__(level=logging.NOTSET)
+        # Correlation fields are contextvars: capture them now, on the thread that logged.
+        self.addFilter(logs.ContextFilter())
+        self._bind = bind
+        self._queue: queue.Queue[tuple[tuple[str, str, int] | None, dict[str, Any]]] = queue.Queue(
+            QUEUE_MAX
+        )
+        self._dropped = 0
+        self._dropped_lock = threading.Lock()
+        self._repeats = _Repeats(REPEATS_PER_MINUTE, REPEAT_WINDOW_SECONDS)
+        self._stopping = threading.Event()
+        self._writer: threading.Thread | None = None
+
+    # --- caller side ---------------------------------------------------------------------------
+    def emit(self, record: logging.LogRecord) -> None:
+        if threading.current_thread() is self._writer:
+            return  # the writer's own trouble (a driver warning mid-insert) must not feed itself
+        if not should_store(record):
+            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
+        # Request lines are one per request by nature; only the repeated SAME message is a flood.
+        key = (
+            None
+            if row["event"] == "http.request"
+            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, *, 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. `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:
+            key, row = item
+            if self._repeats.admit(key):
+                rows.append(row)
+            if len(rows) >= BATCH_MAX:
+                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(), final=final))
+        with self._dropped_lock:
+            dropped, self._dropped = self._dropped, 0
+        if dropped:
+            rows.append(
+                _notice("log.sink.dropped", f"{dropped} log events were dropped", dropped=dropped)
+            )
+        if not rows:
+            return 0
+        try:
+            # The connection is checked out BEFORE the guard, and every request path takes them in
+            # that order too (its session already holds a connection when it reaches the guard). The
+            # other way round, this thread would hold a process-global lock while waiting up to
+            # `pool_timeout` for a connection, and the requests that could return one are the ones
+            # blocked on the lock. The guard still spans the check, the insert and the commit.
+            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
+            # 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
+        return len(rows)
+
+    def _run(self) -> None:
+        while not self._stopping.is_set():
+            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)
+        self._writer.start()
+
+    def stop(self, timeout: float = 5.0) -> None:
+        self._stopping.set()
+        if self._writer is not None:
+            self._writer.join(timeout)
+
+
+_sink: LogSink | None = None
+
+
+def start() -> None:
+    """Attach the sink to the root logger and start its writer. Call after `logs.configure_logging`
+    (which replaces the root handlers) and once the schema exists. A no-op when `LOG_DB_SINK` is off
+    or it is already running."""
+    global _sink
+    if _sink is not None or not settings.log_db_sink:
+        return
+    _sink = LogSink()
+    # The same level gate as stdout: the root may be lowered for one user's elevated requests, and
+    # everyone else's detail must not reach the table through that gap either.
+    _sink.addFilter(logs.LevelGate())
+    logging.getLogger().addHandler(_sink)
+    _sink.start()
+    # A short-lived process (the download child) exits without a lifespan: flush on the way out.
+    atexit.register(stop)
+
+
+def stop() -> None:
+    """Detach the sink and write what is still queued."""
+    global _sink
+    if _sink is None:
+        return
+    logging.getLogger().removeHandler(_sink)
+    _sink.stop()
+    _sink = None
+
+
+def gc(db: Session, retention_days: int) -> int:
+    """Stage the deletion of rows older than `retention_days` (at least one day — stored logs always
+    expire). The caller commits. Returns the number of rows removed."""
+    cutoff = datetime.now(timezone.utc) - timedelta(days=max(1, retention_days))
+    result = db.execute(delete(LogEvent).where(LogEvent.ts < cutoff))
+    return result.rowcount or 0
+
+
+def serialize(row: LogEvent) -> dict:
+    """A stored row as the API sends it — one shape for every reader: the admin console and
+    a debug session's evidence list."""
+    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,
+    }

backend/app/mailtext.py

@@ -1,5 +1,5 @@
 """Bilingual text for every outbound mail, and the one resolver that decides which language a
-recipient gets (E9.5 S7).
+recipient gets.
 
 Why a catalog instead of literals in `email.py`: HU/EN parity is a house rule for every user-facing
 string, and a mail is the one user-facing surface the reader CANNOT re-render by switching the UI
@@ -53,7 +53,7 @@ def lang_for_user(user: User | None) -> str:
 
 def lang_for_email(db: Session, email: str) -> str:
     """The language for an address that may not have an account yet: their own account preference,
-    else the language they filled our access-request form in, else English.
+    else the language their access request came in (the locale Google reported), else English.
 
     Matched CANONICALLY like every other identity lookup in this epic, and it walks past rows that
     carry no usable code instead of stopping at the first one — prod really does hold two accounts
@@ -82,8 +82,8 @@ def lang_for_email(db: Session, email: str) -> str:
 # a name, not a translated string, and giving them keys would invite someone to "translate" them.
 MAIL_TEXT: dict[str, dict[str, str]] = {
     # ── How long a link lasts ───────────────────────────────────────────────────────────────
-    # Rendered, not interpolated as a raw hour count: the approval mail's token lives seven days
-    # (E9.5 S6), and "expires in 168 hours" is a unit no reader converts.
+    # Rendered, not interpolated as a raw hour count: the approval mail's token lives seven days,
+    # and "expires in 168 hours" is a unit no reader converts.
     "duration.hours": {"en": "{n} hours", "hu": "{n} óra"},
     "duration.days": {"en": "{n} days", "hu": "{n} nap"},
     # ── Shared closing fragments ────────────────────────────────────────────────────────────────

backend/app/main.py

@@ -1,49 +1,49 @@
 import asyncio
-import logging
 import math
-import sys
+import mimetypes
 from contextlib import asynccontextmanager, suppress
 from pathlib import Path
 
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import RequestValidationError
-
-# When started via uvicorn --log-config the "siftlode" logger is already configured
-# (see log_config.json). This block is a timestamped fallback for other entrypoints
-# (tests, scripts) so our logs are never silently dropped.
-_siftlode_logger = logging.getLogger("siftlode")
-if not _siftlode_logger.handlers:
-    _handler = logging.StreamHandler(sys.stdout)
-    _handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-5s [%(name)s] %(message)s"))
-    _siftlode_logger.addHandler(_handler)
-    _siftlode_logger.setLevel(logging.INFO)
-    _siftlode_logger.propagate = False
-
-log = logging.getLogger("siftlode.app")
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 from sqlalchemy.exc import DataError
 from starlette.middleware.sessions import SessionMiddleware
 
-from app import state
-from app.config import settings
-from app.db import SessionLocal
-from app.plex import stream as plex_stream
-from app.plex import subtitles as plex_subtitles
-from app.routes import (
+# Logging is configured HERE, before the app's own modules are imported, so a line one of them logs
+# WHILE importing already has the format (a logger is configured whenever it is created —
+# app/logs.py — but a line emitted before `configure_logging` goes out raw). ONE format for the api,
+# the worker, the download child and alembic alike — 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. The imports after it are E402 on purpose, each one marked.
+from app import logs
+from app.logs import configure_logging, current_level, log_requests, set_level
+
+configure_logging("api")
+
+log = logs.get_logger(__name__)
+from app import bodylimit, collation, logsink, state, sysconfig  # noqa: E402 — logging is configured first
+from app.config import settings  # noqa: E402 — logging is configured first
+from app.db import SessionLocal, engine  # noqa: E402 — logging is configured first
+from app.plex import stream as plex_stream  # noqa: E402 — logging is configured first
+from app.plex import subtitles as plex_subtitles  # noqa: E402 — logging is configured first
+from app.routes import (  # noqa: E402 — logging is configured first
     admin,
+    admin_logs as admin_logs_routes,
     audit as audit_routes,
     auth as auth_routes,
     channels,
     config as config_routes,
+    debug_sessions as debug_sessions_routes,
+    diagnostics as diagnostics_routes,
     discover as discover_routes,
     downloads,
     feed,
     health,
     me,
-    messages,
     notifications,
     playlists,
     plex as plex_routes,
@@ -57,22 +57,34 @@ from app.routes import (
     tags,
     version,
 )
-from app.scheduler import shutdown_scheduler, start_scheduler
+from app.scheduler import shutdown_scheduler, start_scheduler  # noqa: E402 — logging is configured first
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     log.info("Siftlode starting up")
+    # The stored copy of the log (log_events). The entrypoint has already migrated the schema.
+    logsink.start()
     # First-run: if the instance isn't configured yet, mint a fresh one-time setup token and print
     # the wizard URL so the operator can open it (the app runs in setup mode until they finish).
     with SessionLocal() as db:
+        # The admin's runtime level (sysconfig `log_level`) wins over the LOG_LEVEL bootstrap
+        # default, so a level chosen in the UI survives a restart without touching the environment.
+        # Best-effort on purpose: a LOGGING knob must never be the thing that stops the app from
+        # 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:  # 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
@@ -83,6 +95,9 @@ async def lifespan(app: FastAPI):
     # owns, so racing it against early playback is safe.
     sweep = asyncio.create_task(_sweep_hls_orphans())
     reaper = asyncio.create_task(_reap_hls_sessions())
+    # Fire and forget as well: a rebuild after an ICU upgrade takes seconds, and the title sorts serve
+    # meanwhile (CONCURRENTLY) in the old index's order, as they did before the restart.
+    heal = asyncio.create_task(_heal_collation_drift())
     start_scheduler()
     try:
         yield
@@ -92,7 +107,7 @@ async def lifespan(app: FastAPI):
         # pending ("Task was destroyed but it is pending!" — noise that reads like a bug during
         # triage). Cancelling does NOT interrupt the rmtree thread itself; this only makes our own
         # bookkeeping honest.
-        for task in (sweep, reaper):
+        for task in (sweep, reaper, heal):
             task.cancel()
             with suppress(asyncio.CancelledError):
                 await task
@@ -100,6 +115,7 @@ async def lifespan(app: FastAPI):
         # Kills a running subtitle extraction: its worker would otherwise hold interpreter exit for
         # the rest of the read (see plex_subtitles.shutdown).
         plex_subtitles.shutdown()
+        logsink.stop()  # last: write what the shutdown itself just logged
 
 
 # How often idle HLS sessions are reaped (see plex/stream.py `reap_idle`).
@@ -115,7 +131,7 @@ async def _reap_hls_sessions() -> None:
     A FINISHED session is reaped on the short rule here, not kept for the full idle window: an open
     player checkpoints every 10 s and that route touches the session, so a paused viewer is no longer
     invisible to this pass (see `reap_idle`). Keeping every finished session for ten minutes instead
-    held one whole segmented copy of a film per item on the download volume (round 5)."""
+    held one whole segmented copy of a film per item on the download volume."""
     while True:
         await asyncio.sleep(_HLS_REAP_EVERY_S)
         try:
@@ -124,6 +140,18 @@ async def _reap_hls_sessions() -> None:
             log.exception("HLS session reap failed")
 
 
+async def _heal_collation_drift() -> None:
+    """Background startup check of the ICU collation the title-sort indexes are built in (see
+    `collation.heal_drift`). A failure is logged, never fatal: the sorts still answer, only possibly in
+    the old order."""
+    try:
+        await asyncio.to_thread(collation.heal_drift, engine)
+    except asyncio.CancelledError:
+        raise
+    except Exception:
+        log.exception("ICU collation drift check failed")
+
+
 async def _sweep_hls_orphans() -> None:
     """Background half of the startup HLS sweep (see lifespan). Owns its own errors: a failure here
     must never take the app down, and a cancelled shutdown is not one."""
@@ -159,8 +187,8 @@ async def _nul_in_text(request: Request, exc: DataError) -> JSONResponse:
     NUL in text, so the driver refuses to even send the query — and a `%00` in a query parameter or
     an escaped NUL in a JSON body (a playlist's `contains=`, a reorder's key list, a collection
     search) was a 500 with a traceback wherever it reached a comparison. Guarding each site did not
-    hold: round 3 guarded the by-rating_key lookup and missed the rest. Any other DataError is left
-    alone — re-raised, it stays the 500 it always was."""
+    hold: an earlier fix guarded the by-rating_key lookup and missed the rest. Any other DataError
+    is left alone — re-raised, it stays the 500 it always was."""
     if "NUL (0x00)" not in str(exc.orig):
         raise exc
     return JSONResponse(
@@ -175,15 +203,6 @@ app.add_middleware(
     https_only=settings.session_https_only,  # Secure flag when served over HTTPS (prod)
 )
 
-if settings.frontend_origin:
-    app.add_middleware(
-        CORSMiddleware,
-        allow_origins=[settings.frontend_origin],
-        allow_credentials=True,
-        allow_methods=["*"],
-        allow_headers=["*"],
-    )
-
 # Paths reachable while the instance is unconfigured (setup mode). Everything else under /api or
 # /auth is locked until the wizard finishes; static/SPA always loads so the wizard page can render.
 _SETUP_OPEN_PREFIXES = ("/api/setup", "/api/version")
@@ -203,6 +222,34 @@ async def setup_gate(request, call_next):
     return await call_next(request)
 
 
+# SEC-20 — the global request-body cap (app/bodylimit.py). FastAPI reads a declared body IN FULL
+# before the first dependency, so without this the anonymous login route is a free memory/time sink.
+#
+# WHERE it sits is the whole design, and it is pinned by `test_body_limit.py` rather than by this
+# comment, because `add_middleware` inverts the reading order (last registered = OUTERMOST) and a
+# stack described in prose drifts. Registered here it lands directly INSIDE CORS and directly
+# OUTSIDE the setup gate, which is the narrowest position that satisfies both constraints:
+#
+#   * inside CORS and the security headers, so the 413 is decorated like every other response. A
+#     refusal the browser drops for a missing Access-Control-Allow-Origin is no better than a hang,
+#     and `capped_body`'s 413 one layer down IS decorated — two shapes for one fact is exactly what
+#     bodylimit.py exists to avoid.
+#   * outside the setup gate, the session and every auth dependency under the router — none of which
+#     run for a body that is already too large. The setup gate matters specifically: on an instance
+#     that is not yet configured it opens a DB session per request, which is precisely the anonymous
+#     pre-auth work SEC-20 exists to remove.
+app.add_middleware(bodylimit.BodyLimitMiddleware)
+
+if settings.frontend_origin:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=[settings.frontend_origin],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
 @app.middleware("http")
 async def static_cache_headers(request, call_next):
     """Long-cache the content-hashed SPA bundles. Vite hashes their filename, so a given
@@ -243,6 +290,15 @@ async def security_headers(request, call_next):
     return response
 
 
+# The access log (app/logs.py): request id, route template, status, duration — one line, never a
+# query string. Registered LAST so it is the OUTERMOST http middleware and therefore times the whole
+# request, including what every layer above does — the body cap included, so a 413 is still logged
+# with its request id and duration. Being outermost also puts it OUTSIDE SessionMiddleware,
+# which is why the account comes from `request.state.user_id` (set by the auth dependency, the one
+# place a session is actually resolved into an account) rather than from `request.session`.
+app.middleware("http")(log_requests)
+
+
 app.include_router(health.router)
 app.include_router(auth_routes.router)
 app.include_router(sync.router)
@@ -251,8 +307,9 @@ app.include_router(feed.router)
 app.include_router(discover_routes.router)
 app.include_router(search_routes.router)
 app.include_router(me.router)
+app.include_router(diagnostics_routes.router)
+app.include_router(debug_sessions_routes.router)
 app.include_router(notifications.router)
-app.include_router(messages.router)
 app.include_router(channels.router)
 app.include_router(playlists.router)
 app.include_router(saved_views.router)
@@ -264,14 +321,13 @@ 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)
 
 # Ensure modern image types resolve to the right Content-Type when FileResponse guesses from the
 # filename (the runtime's mimetypes db doesn't always know .webp → it'd fall back to octet-stream).
-import mimetypes
-
 mimetypes.add_type("image/webp", ".webp")
 mimetypes.add_type("image/avif", ".avif")
 
@@ -283,6 +339,8 @@ STATIC_DIR = Path(__file__).parent / "static_spa"
 # stay cached but forces revalidation (cheap 304 via the FileResponse ETag) on every load. The
 # hashed bundles under /assets can cache forever (a new build changes their filename).
 INDEX_HTML = STATIC_DIR / "index.html"
+# A public share link's own page: the player alone, without the app's bundle (frontend/watch.html).
+WATCH_HTML = STATIC_DIR / "watch.html"
 INDEX_HEADERS = {"Cache-Control": "no-cache"}
 app.mount(
     "/assets",
@@ -298,16 +356,16 @@ async def index() -> FileResponse:
 
 @app.get("/watch/{token}")
 async def watch_page(token: str):
-    """Serve the SPA for a public share link, but with per-video Open Graph tags injected so the
+    """Serve the public player page for a share link, with per-video Open Graph tags injected so the
     link unfurls richly (title/channel/thumbnail) in Messenger/social crawlers. A real browser
-    ignores the extra tags and hydrates WatchPage as usual; invalid/expired/password links fall
-    back to the generic card."""
+    ignores the extra tags and boots WatchPage; invalid/expired/password links fall back to the
+    generic card."""
     from app.downloads import og
 
     with SessionLocal() as db:
-        rendered = og.render_watch_html(token, INDEX_HTML, db)
+        rendered = og.render_watch_html(token, WATCH_HTML, db)
     if rendered is None:
-        return FileResponse(INDEX_HTML, headers=INDEX_HEADERS)
+        return FileResponse(WATCH_HTML, headers=INDEX_HEADERS)
     return HTMLResponse(rendered, headers=INDEX_HEADERS)
 
 
@@ -325,4 +383,8 @@ async def spa_fallback(full_path: str) -> FileResponse:
             # Real SPA-root assets (welcome images, favicon, robots.txt) rarely change and have
             # stable names, so a moderate cache is safe and satisfies the cache-lifetime audit.
             return FileResponse(candidate, headers={"Cache-Control": "public, max-age=604800"})
+    # A /watch/ path the route above does not match (a trailing segment, no token) is still the
+    # player's: WatchPage reads the token off the path and says when a link is gone.
+    if full_path.startswith("watch/"):
+        return FileResponse(WATCH_HTML, headers=INDEX_HEADERS)
     return FileResponse(INDEX_HTML, headers=INDEX_HEADERS)

backend/app/models.py

@@ -12,6 +12,8 @@ from sqlalchemy import (
     Index,
     Integer,
     JSON,
+    LargeBinary,
+    SmallInteger,
     String,
     Text,
     UniqueConstraint,
@@ -23,6 +25,32 @@ from sqlalchemy.orm import Mapped, mapped_column, relationship, validates
 from app.db import Base
 from app.utils import canonical_email
 
+# Every user-supplied display string in this schema shares one width, and it lives HERE so the
+# columns below are declared with it rather than with a literal: a name a person typed goes into
+# `User.display_name` (their Google profile name), `DownloadJob.display_name` and
+# `DownloadJob.display_uploader`. A value wider than the column is a psycopg DataError, which
+# `main.py` re-raises for everything but the NUL case — i.e. a bare 500 for a name somebody pasted.
+DISPLAY_TEXT_MAX = 255
+
+
+def display_text(raw: str | None) -> str | None:
+    """A user-supplied display string on its way into one of those columns: stripped, truncated,
+    blank -> None.
+
+    One definition because there are SIX writers and they had drifted: `POST /api/downloads`,
+    `POST /api/downloads/edit`, `POST /api/downloads/upload`, the metadata PATCH's two fields, and
+    the Google sign-in callback. Only the PATCH truncated. Truncating is the right answer rather
+    than refusing: the name is a label on work the user has already done — a file already
+    transferred, an account already authenticated — and losing its tail is not worth failing the
+    request over.
+
+    `test_upload.py` holds both halves: that every route assigning one of these fields goes through
+    this helper (parsed, not grepped), and that each of those routes truncates rather than 500s. A
+    sweep is exactly the kind of thing that gets done five-sixths of the way, which is how this
+    ended up being written twice.
+    """
+    return (raw or "").strip()[:DISPLAY_TEXT_MAX] or None
+
 
 # The resume-position columns (VideoState / PlexState.position_seconds) are int4. The checkpoint
 # routes bound their bodies by this, so an out-of-range position is a 422 rather than a 500.
@@ -31,7 +59,7 @@ POSITION_MAX_S = 2**31 - 1
 
 class TimestampMixin:
     """Adds a server-defaulted `created_at`. Models that index created_at or order it
-    differently (QuotaEvent, Notification, Message) keep their own column on purpose."""
+    differently (QuotaEvent, Notification) keep their own column on purpose."""
 
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
 
@@ -73,15 +101,15 @@ class User(Base, TimestampMixin, CanonicalEmailMixin):
     # Google sign-in that failed to find it), and a migration must not merge accounts on its own.
     email_canonical: Mapped[str] = mapped_column(String(320), index=True, server_default="")
     # The address Google asserted for this account, recorded at sign-in / link time. NOT the same
-    # thing as `email`: since E9.5 S3 a Google sign-in no longer overwrites the address the user
+    # thing as `email`: a Google sign-in no longer overwrites the address the user
     # registered with, so a deliberate `me+siftlode@gmail.com` survives — and this is where the other
     # half of the truth lives, for the UI to show when the two differ. NULL until the next Google
     # sign-in for accounts linked before this column existed.
     google_email: Mapped[str | None] = mapped_column(String(320))
-    # argon2id hash for email+password login; NULL for Google-only / demo accounts.
+    # argon2id hash for email+password login; NULL for Google-only accounts.
     password_hash: Mapped[str | None] = mapped_column(String(255))
     # When SEC-10 dropped a preset password on Google adoption (see the single caller of
-    # auth.revoke_preset_password_if_unverified; admin approval no longer revokes — E9.5 S1). Without
+    # auth.revoke_untrusted_preset_password; admin approval no longer revokes). Without
     # this trace a revoked account was indistinguishable from a Google-only one, so it failed the
     # password-reset eligibility check and could never be recovered — it could neither sign in nor
     # reset. Set = "had a password, lost it to the guard" -> reset-eligible. Cleared whenever a
@@ -95,25 +123,29 @@ class User(Base, TimestampMixin, CanonicalEmailMixin):
     is_active: Mapped[bool] = mapped_column(Boolean, default=True, server_default="true")
     # Admin-imposed access block, distinct from is_active (approval lifecycle). A suspended
     # account can't sign in by any method and its live sessions are rejected; the user is told
-    # why and pointed at the operator's contact. The demo account is never suspendable.
+    # why and pointed at the operator's contact.
     is_suspended: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
     # Server-side session revocation (SA4): a monotonic counter bumped on password reset, password
     # change, or "log out everywhere". A signed session cookie records the epoch it was minted under;
     # current_user rejects any cookie whose epoch is stale, so a stolen/copied cookie dies on those
     # events (client-side signed cookies otherwise stay valid until they expire).
     session_epoch: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
-    display_name: Mapped[str | None] = mapped_column(String(255))
+    # When this account last signed in (Google or password), stamped by the one sign-in path,
+    # routes/auth._establish_session. NULL = not since the column existed (0085; no backfill is
+    # possible).
+    last_login_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    # The diagnostics level this user consented to and when it lapses back to the base
+    # level. Both NULL = base. Written only by `PUT /api/me/diagnostics`, which computes the expiry
+    # itself; read through `app.diagnostics.effective_level`, never directly (an expired level is
+    # not cleared eagerly — it simply stops counting).
+    diagnostics_level: Mapped[str | None] = mapped_column(String(8))
+    diagnostics_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    display_name: Mapped[str | None] = mapped_column(String(DISPLAY_TEXT_MAX))
     avatar_url: Mapped[str | None] = mapped_column(String(1024))
     role: Mapped[str] = mapped_column(String(16), default="user", server_default="user")
     # The user's own YouTube channel id, resolved lazily (channels.list?mine=true) and
     # cached. Used to exclude their own channel from playlist discovery. NULL = unresolved.
     yt_channel_id: Mapped[str | None] = mapped_column(String(32))
-    # The single shared "demo" account: signed into without Google OAuth (via a whitelisted
-    # email on the login page), has no OAuth token / YouTube scope, and its per-user state is
-    # shared by everyone who enters this way. Exactly one such row is expected.
-    is_demo: Mapped[bool] = mapped_column(
-        Boolean, default=False, server_default="false", index=True
-    )
     # Free-form UI preferences (theme, color scheme, font scale, default filters…).
     preferences: Mapped[dict | None] = mapped_column(JSON)
 
@@ -180,25 +212,12 @@ class Invite(Base, CanonicalEmailMixin):
     # The language this person asked us in ("en"/"hu"), captured when the request was made: the page
     # their form was on, or the locale Google reported for a refused sign-in. NULL for a row the
     # admin whitelisted by hand — nobody has told us anything about that mailbox, which is exactly
-    # why the invitation send asks (E9.5 S7). Captured rather than derived for the same reason
+    # why the invitation send asks. Captured rather than derived for the same reason
     # `preferences.language` and `google_email` are: the signal exists only in that one moment and
     # cannot be backfilled afterwards.
     lang: Mapped[str | None] = mapped_column(String(8))
 
 
-class DemoWhitelist(Base, TimestampMixin):
-    """Emails that may enter the shared demo account from the login page (no Google OAuth).
-    A hidden, admin-curated list of "keys to the same door" — every entry logs into the one
-    shared demo user. Distinct from Invite (which gates real Google sign-in)."""
-
-    __tablename__ = "demo_whitelist"
-
-    id: Mapped[int] = mapped_column(primary_key=True)
-    email: Mapped[str] = mapped_column(String(320), unique=True, index=True)
-    note: Mapped[str | None] = mapped_column(Text)
-    added_by: Mapped[str | None] = mapped_column(String(320))  # admin email
-
-
 class Channel(Base, TimestampMixin):
     """A YouTube channel. Shared across all users (one channel's videos are the same
     for everyone), so its expensive metadata is fetched and stored only once."""
@@ -230,6 +249,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
@@ -287,10 +309,12 @@ class Video(Base, TimestampMixin):
     __tablename__ = "videos"
 
     id: Mapped[str] = mapped_column(String(16), primary_key=True)  # video id
-    # No standalone channel_id index: the composite `ix_videos_channel_pub_desc`
-    # (channel_id, published_at DESC NULLS LAST, id) from migration 0067 leads with channel_id, so it
-    # serves every channel_id lookup (FK cascade, sync upsert, channel-detail) AND the per-channel feed
-    # sort. Like the search_vector GIN, this composite is migration-defined, not an inline `index=True`.
+    # No standalone channel_id index: the composite `ix_videos_channel_pub_cover`
+    # (channel_id, published_at DESC NULLS LAST, id) from migration 0095 leads with channel_id, so it
+    # serves every channel_id lookup (FK cascade, sync upsert, channel-detail) and the per-channel feed
+    # sort. Its INCLUDEd columns make the channel manager's sums and the feed sidebar's counts Index Only
+    # Scans (no heap): a column those queries start reading belongs in it (test_channel_list_index_only).
+    # Like the search_vector GIN, this composite is migration-defined, not an inline `index=True`.
     channel_id: Mapped[str] = mapped_column(ForeignKey("channels.id", ondelete="CASCADE"))
     title: Mapped[str | None] = mapped_column(Text)  # normalized for display (see app.titles)
     original_title: Mapped[str | None] = mapped_column(Text)  # raw YouTube title, preserved
@@ -304,6 +328,9 @@ class Video(Base, TimestampMixin):
         DateTime(timezone=True), index=True, nullable=False, server_default=func.now()
     )
     thumbnail_url: Mapped[str | None] = mapped_column(String(1024))
+    # The feed's views / duration / title sorts each ride a migration-defined index in their exact
+    # ORDER BY, one per direction (and per ICU collation for title): migration 0096, held to
+    # `feedquery.order_by` by test_feed_sort_indexes.
     duration_seconds: Mapped[int | None] = mapped_column(Integer)
     view_count: Mapped[int | None] = mapped_column(BigInteger)
     like_count: Mapped[int | None] = mapped_column(BigInteger)
@@ -435,6 +462,27 @@ class VideoState(Base, UpdatedAtMixin):
     progress_updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
 
 
+class LibraryState(Base):
+    """Where a user stopped in a library item (their own download, or one shared with them) — the
+    library player's resume point. Keyed by the JOB, not the file: a job is the user's library entry,
+    a re-download keeps it, and deleting the job deletes the row; the shared file under it may outlive
+    both. A revoked share leaves its recipient's row behind, unread — only a job the user can still
+    reach is ever read or written — and it is back if the item is shared again. Rows exist only for a
+    position worth keeping (see `routes._common.kept_position`); no row means "from the start"."""
+
+    __tablename__ = "library_states"
+    __table_args__ = (UniqueConstraint("user_id", "job_id", name="uq_library_user_job"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    job_id: Mapped[int] = mapped_column(
+        ForeignKey("download_jobs.id", ondelete="CASCADE"), index=True
+    )
+    # int4: a checkpoint body must stay under POSITION_MAX_S, or the flush is a DataError (a 500).
+    position_seconds: Mapped[int] = mapped_column(Integer, nullable=False)
+    progress_updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+
 class SearchFind(Base, TimestampMixin):
     """Per-user record of a video the user surfaced via their own live YouTube search.
 
@@ -539,6 +587,91 @@ class AuditLog(Base):
     )
 
 
+class LogEvent(Base):
+    """One stored log event — the `log_events` table the diagnostics console reads. Rows are
+    written by app/logsink.py's background writer, never inside a request's transaction, already
+    redacted (the same `logs.record_fields` the stdout line is built from).
+
+    `user_id` has NO foreign key on purpose: the writer runs behind the event, so a line about an
+    account can arrive after that account was purged, and a constraint would make it fail the whole
+    batch it travels in. `auth.purge_user` deletes an account's rows explicitly instead, after
+    `logs.forget_user` makes every later write in this process store such a line without the account;
+    the retention job (`log_retention_days`) bounds whatever another process writes late."""
+
+    __tablename__ = "log_events"
+    __table_args__ = (
+        Index("ix_log_events_user_ts", "user_id", "ts"),
+        # An issue's bundle is `WHERE debug_session_id = …`; nearly every row has none.
+        Index(
+            "ix_log_events_debug_session",
+            "debug_session_id",
+            postgresql_where="debug_session_id IS NOT NULL",
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    ts: Mapped[datetime] = mapped_column(DateTime(timezone=True), index=True)
+    level: Mapped[str] = mapped_column(String(10))
+    sev: Mapped[int] = mapped_column(SmallInteger)
+    source: Mapped[str] = mapped_column(String(16))
+    logger: Mapped[str] = mapped_column(String(128))
+    event: Mapped[str | None] = mapped_column(String(64))
+    msg: Mapped[str] = mapped_column(Text)
+    attrs: Mapped[dict | None] = mapped_column(JSONB)
+    exc: Mapped[str | None] = mapped_column(Text)
+    request_id: Mapped[str | None] = mapped_column(String(64), index=True)
+    user_id: Mapped[int | None] = mapped_column(Integer)
+    debug_session_id: Mapped[str | None] = mapped_column(String(64))
+    job_id: Mapped[int | None] = mapped_column(Integer)
+    version: Mapped[str | None] = mapped_column(String(64))
+
+
+class DebugSession(Base):
+    """One recording: Start → reproduce → Stop (app/debugsession.py). While it is open, every
+    request of its user that names it (`X-Debug-Session`) is logged at `level` and tagged with `id`,
+    and the issue it ends in is built from the rows carrying that tag. `until` is the hard cap the
+    server set at Start; an open session past it is over whether or not the sweep has closed it yet.
+    One OPEN session per user (`uq_debug_sessions_open_per_user`, partial on `ended_at IS NULL`)."""
+
+    __tablename__ = "debug_sessions"
+    __table_args__ = (
+        Index(
+            "uq_debug_sessions_open_per_user",
+            "user_id",
+            unique=True,
+            postgresql_where="ended_at IS NULL",
+        ),
+    )
+
+    id: Mapped[str] = mapped_column(String(16), primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+    level: Mapped[str] = mapped_column(String(8))
+    started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    until: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    ended_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    # app/debugsession.py `EndReason`: stopped by the user, or past `until`.
+    ended_reason: Mapped[str | None] = mapped_column(String(16))
+    issue_url: Mapped[str | None] = mapped_column(String(512))
+    # The issue being written from it (app/debugsession.py `save_draft` holds its shape).
+    draft: Mapped[dict | None] = mapped_column(JSONB)
+
+
+class DebugScreenshot(Base):
+    """A screenshot attached to a debug session — pasted, dropped, or captured from the pill.
+    Stored in the row: bounded per session (app/debugsession.py), and gone with it by cascade."""
+
+    __tablename__ = "debug_screenshots"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    session_id: Mapped[str] = mapped_column(
+        ForeignKey("debug_sessions.id", ondelete="CASCADE"), index=True
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    mime: Mapped[str] = mapped_column(String(16))
+    size: Mapped[int] = mapped_column(Integer)
+    data: Mapped[bytes] = mapped_column(LargeBinary)
+
+
 class AppState(Base):
     """Single-row global app state (admin-controlled)."""
 
@@ -683,44 +816,6 @@ class Notification(Base):
     )
 
 
-class Message(Base):
-    """A message in the notification module (phase 2).
-
-    Two kinds share this table:
-      - `kind="user"`: a private, END-TO-END ENCRYPTED direct message between two users. The
-        server only ever stores `ciphertext` + `iv` (base64); it never holds the plaintext or
-        the keys, so not even an admin can read it. A conversation is just the set of messages
-        between two users — no separate thread entity; queries group by the {sender, recipient}
-        pair.
-      - `kind="system"`: a server-authored plaintext message (e.g. the welcome, or future admin
-        announcements). `sender_id` is NULL and `body` holds the text. These are non-private
-        boilerplate, readable without any E2EE key setup, and surface as a "Siftlode" conversation.
-
-    `read_at` is stamped when the recipient opens the thread (NULL = unread, feeds the nav
-    badge). The recipient FK cascades (and sender, for user messages) so a GDPR account erasure
-    removes that user's messages outright."""
-
-    __tablename__ = "messages"
-
-    id: Mapped[int] = mapped_column(primary_key=True)
-    kind: Mapped[str] = mapped_column(String(16), default="user", server_default="user")
-    # NULL for system messages (no human sender).
-    sender_id: Mapped[int | None] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
-    )
-    recipient_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
-    )
-    # System messages carry plaintext `body`; user messages carry `ciphertext`+`iv` (base64).
-    body: Mapped[str | None] = mapped_column(Text)
-    ciphertext: Mapped[str | None] = mapped_column(Text)
-    iv: Mapped[str | None] = mapped_column(String(32))
-    read_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=func.now(), index=True
-    )
-
-
 class MediaAsset(Base, TimestampMixin):
     """A physical downloaded media file — the SHARED cache layer of the download center.
 
@@ -815,8 +910,8 @@ class DownloadJob(Base, TimestampMixin, UpdatedAtMixin):
     """A user's request to download one source — the per-user layer over `MediaAsset`.
 
     The worker claims `queued` jobs with ``FOR UPDATE SKIP LOCKED`` and writes live
-    `progress`/`speed_bps`/`eta_s`/`phase` here (the frontend polls via useLiveQuery — the
-    worker is a separate process and can't reach the in-process WS registry). `profile_snapshot`
+    `progress`/`speed_bps`/`eta_s`/`phase` here (the frontend polls via useLiveQuery: there is
+    no server push channel, and the worker is a separate process anyway). `profile_snapshot`
     freezes the spec at enqueue so later edits/deletion of the profile don't change this job.
     `display_name` is the user's own name for the file (display + the Content-Disposition on
     local download); the on-disk asset is never renamed. `asset_id` links to the shared file
@@ -838,7 +933,8 @@ class DownloadJob(Base, TimestampMixin, UpdatedAtMixin):
     )
     source_kind: Mapped[str] = mapped_column(String(16))  # "youtube" | "url"
     source_ref: Mapped[str] = mapped_column(String(512))
-    # "download" (default) or "edit" (a per-user trim/crop derivative of another job).
+    # "download" (default), "edit" (a per-user trim/crop derivative of another job) or "upload" (a
+    # user's own file, converted by the worker when it is not phone-safe — see `downloads.upload`).
     job_kind: Mapped[str] = mapped_column(String(16), default="download", server_default="download")
     # For edit jobs: the parent download this clip is cut from (SET NULL if the parent is deleted).
     source_job_id: Mapped[int | None] = mapped_column(
@@ -853,11 +949,11 @@ class DownloadJob(Base, TimestampMixin, UpdatedAtMixin):
         ForeignKey("download_profiles.id", ondelete="SET NULL")
     )
     profile_snapshot: Mapped[dict] = mapped_column(JSON)
-    display_name: Mapped[str | None] = mapped_column(String(255))
+    display_name: Mapped[str | None] = mapped_column(String(DISPLAY_TEXT_MAX))
     # Per-user display overrides + extras (like display_name — metadata only, never the file).
     # `display_uploader`/`display_uploader_url` override the asset's auto channel name/link;
     # `extra_links` is an optional list of extra reference URLs shown on the card + watch page.
-    display_uploader: Mapped[str | None] = mapped_column(String(255))
+    display_uploader: Mapped[str | None] = mapped_column(String(DISPLAY_TEXT_MAX))
     display_uploader_url: Mapped[str | None] = mapped_column(Text)
     extra_links: Mapped[list | None] = mapped_column(JSON)
     status: Mapped[str] = mapped_column(
@@ -871,6 +967,8 @@ class DownloadJob(Base, TimestampMixin, UpdatedAtMixin):
     error_code: Mapped[str | None] = mapped_column(
         String(24)
     )  # category, see downloads.errors.classify
+    # The host-specific failure-catalog entry on top of the category (`facebook.login_wall`), or NULL.
+    error_detail: Mapped[str | None] = mapped_column(String(48))  # see downloads.errors.diagnose
     queue_pos: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
 
 
@@ -961,29 +1059,6 @@ class DownloadCredential(Base, TimestampMixin, UpdatedAtMixin):
     cookies_enc: Mapped[str] = mapped_column(Text)  # Fernet ciphertext — never returned/logged
 
 
-class MessageKey(Base, TimestampMixin):
-    """A user's end-to-end-encryption key material for direct messaging (phase 2).
-
-    One row per user. `public_key` (base64 SPKI, ECDH P-256) is shared with others so they can
-    derive the pairwise conversation key. `wrapped_private_key` is the user's private key
-    encrypted IN THE BROWSER with a key derived (PBKDF2) from a message passphrase the server
-    never sees — so the server stores only an opaque blob it cannot unwrap. `salt`/`wrap_iv`
-    parameterise that derivation; `key_check` is a small ciphertext the client decrypts to
-    verify a passphrase on unlock. The server is purely a key directory + blob store; it can
-    never read any message."""
-
-    __tablename__ = "message_keys"
-
-    user_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), primary_key=True
-    )
-    public_key: Mapped[str] = mapped_column(Text)
-    wrapped_private_key: Mapped[str] = mapped_column(Text)
-    salt: Mapped[str] = mapped_column(String(64))
-    wrap_iv: Mapped[str] = mapped_column(String(32))
-    key_check: Mapped[str] = mapped_column(Text)
-
-
 # --- Plex integration (optional) -------------------------------------------------------------
 # A dedicated, self-contained catalog mirrored from a locally-reachable Plex server. Playback is
 # from the LOCAL physical file (Plex is metadata only); per-user watch state lives in plex_states
@@ -1004,7 +1079,7 @@ class PlexLibrary(Base, TimestampMixin, UpdatedAtMixin):
     kind: Mapped[str] = mapped_column(String(16))  # "movie" | "show"
     enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default="true")
     synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    # HU-overlay support (E5 S5). `metadata_lang` tags the section's metadata language. An OVERLAY
+    # HU-overlay support. `metadata_lang` tags the section's metadata language. An OVERLAY
     # library (overlay_of set) is the Hungarian-metadata twin of another section: it is never browsable
     # on its own — its titles' HU fields are written onto the matched EN rows (paired by `guid`).
     metadata_lang: Mapped[str] = mapped_column(String(8), default="en", server_default="en")
@@ -1033,7 +1108,7 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
         ForeignKey("plex_libraries.id", ondelete="CASCADE"), index=True
     )
     # Canonical external id (e.g. "tmdb:12345") — the key that pairs this EN row with its HU-overlay
-    # twin during sync (E5 S5). Indexed for the guid->row overlay match.
+    # twin during sync. Indexed for the guid->row overlay match.
     guid: Mapped[str | None] = mapped_column(String(64), index=True)
     title: Mapped[str] = mapped_column(String(512))
     summary: Mapped[str | None] = mapped_column(Text)
@@ -1063,7 +1138,7 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
     )  # cast+directors, folded into search_vector
     # Set once the show's FULL cast has been rich-fetched by the backfill; NULL = still the listing top-3.
     people_enriched_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    # Rich-fetch-only detail fields, persisted by the same backfill that fills the full cast (E5 S5b) so
+    # Rich-fetch-only detail fields, persisted by the same backfill that fills the full cast so
     # the info page serves from this row instead of a live plex.metadata() call. NULL until enriched.
     imdb_rating: Mapped[float | None] = mapped_column(
         Float
@@ -1073,7 +1148,7 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
     full_cast: Mapped[list | None] = mapped_column(
         JSONB(none_as_null=True)
     )  # ordered [{name, role, thumb}]
-    # --- TMDB enrichment (E5 S2): see the identical block on plex_items for the full rationale. Additive;
+    # --- TMDB enrichment: see the identical block on plex_items for the full rationale. Additive;
     #     served from the row; NULL until enriched. (`budget`/`revenue` stay NULL for shows — TV has none.) ---
     tmdb_id: Mapped[int | None] = mapped_column(Integer)
     tmdb_enriched_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
@@ -1091,9 +1166,10 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
     production_countries: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))  # [str]
     recommendations: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))
     backdrops: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))
-    # Hungarian-metadata twin fields, written by the overlay sync (E5 S5). NULL = no HU twin matched,
+    # Hungarian-metadata twin fields, written by the overlay sync. NULL = no HU twin matched,
     # so serving falls back to the EN columns. `people_text` is language-neutral, reused for both vectors.
     title_hu: Mapped[str | None] = mapped_column(String(512))
+    tagline_hu: Mapped[str | None] = mapped_column(Text)  # the HU overlay's tagline
     summary_hu: Mapped[str | None] = mapped_column(Text)
     genres_hu: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))
     search_vector: Mapped[object | None] = mapped_column(
@@ -1155,7 +1231,7 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     )
     kind: Mapped[str] = mapped_column(String(16), index=True)  # "movie" | "episode"
     # Canonical external id (e.g. "tmdb:12345") — pairs a MOVIE row with its HU-overlay twin during
-    # sync (E5 S5); indexed for the guid->row match. Episodes carry it too but it's unused for them.
+    # sync; indexed for the guid->row match. Episodes carry it too but it's unused for them.
     guid: Mapped[str | None] = mapped_column(String(64), index=True)
     show_id: Mapped[int | None] = mapped_column(
         ForeignKey("plex_shows.id", ondelete="CASCADE"), index=True
@@ -1182,7 +1258,7 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     # Browser-playability class from ffprobe: "direct" | "remux" | "transcode" (None = unprobed).
     playable: Mapped[str | None] = mapped_column(String(12), index=True)
     probed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    # Transcode HW-capability facet (E7 playback-class filter). NULL for non-transcode items; for a
+    # Transcode HW-capability facet (the playback-class filter). NULL for non-transcode items; for a
     # `playable="transcode"` item: True = the prod iGPU can hardware-transcode it (codec is HW-decodable
     # AND the source is 8-bit SDR), False = software libx264 only (AV1/XviD, or a 10-bit/HDR source that
     # breaks the VAAPI nv12 pipeline — see plex/stream.py). Derived by `plex.sync.transcode_hw_capable`:
@@ -1198,8 +1274,6 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     # bit-depth/HDR. NULL = never (the backfill's work-list). Only HW-decodable transcode items are
     # probed (the rest are SW-only by codec and need no bit-depth); see `_probe_media_batch`.
     media_probed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    # Intro/credit markers: [{"type": "intro"|"credits", "start_s": int, "end_s": int}, ...]
-    markers: Mapped[list | None] = mapped_column(JSON)
     added_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), index=True)
     # Filterable / orderable metadata mirrored from the Plex section listing (no extra API calls;
     # `rating` = Plex audienceRating, which is ~the IMDb score). The arrays back genre/person/studio
@@ -1218,7 +1292,7 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     people_text: Mapped[str | None] = mapped_column(Text)
     # Set once the movie's FULL cast has been rich-fetched by the backfill; NULL = still the listing top-3.
     people_enriched_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    # Rich-fetch-only detail fields, persisted by the same backfill that fills the full cast (E5 S5b) so
+    # Rich-fetch-only detail fields, persisted by the same backfill that fills the full cast so
     # the info page serves from this row instead of a live plex.metadata() call. NULL until enriched.
     imdb_rating: Mapped[float | None] = mapped_column(
         Float
@@ -1228,7 +1302,7 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     full_cast: Mapped[list | None] = mapped_column(
         JSONB(none_as_null=True)
     )  # ordered [{name, role, thumb}]
-    # --- TMDB enrichment (E5 S2): matched by the canonical `guid` ("tmdb:12345"), filled by the TMDB
+    # --- TMDB enrichment: matched by the canonical `guid` ("tmdb:12345"), filled by the TMDB
     #     backfill job, SERVED FROM THIS ROW (never a live TMDB call). Additive — imdb_rating/rating
     #     above stay Plex-sourced; `tmdb_rating` is the distinct TMDb community score. NULL until enriched;
     #     `tmdb_enriched_at` is the "tried" watermark (stamped on a definitive no-match too, so an
@@ -1251,10 +1325,11 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     recommendations: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))
     backdrops: Mapped[list | None] = mapped_column(
         JSONB(none_as_null=True)
-    )  # TMDB backdrop file_paths [str] (crossfade pool, S8)
-    # Hungarian-metadata twin fields, written by the overlay sync (E5 S5). NULL = no HU twin matched
+    )  # TMDB backdrop file_paths [str] (crossfade pool)
+    # Hungarian-metadata twin fields, written by the overlay sync. NULL = no HU twin matched
     # (serving falls back to the EN columns). `people_text` is language-neutral, reused for both vectors.
     title_hu: Mapped[str | None] = mapped_column(String(512))
+    tagline_hu: Mapped[str | None] = mapped_column(Text)  # the HU overlay's tagline
     summary_hu: Mapped[str | None] = mapped_column(Text)
     genres_hu: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))
     search_vector: Mapped[object | None] = mapped_column(
@@ -1285,21 +1360,26 @@ class PlexPerson(Base, TimestampMixin, UpdatedAtMixin):
     top few cast. Rows whose name no longer appears in ANY item's cast_names/directors (a library
     removal orphaned them) are pruned by the maintenance sweep, mirroring how Plex drops orphaned
     metadata. The filterable cast lives in plex_items/plex_shows.cast_names (self-cleaning with the
-    row); this table is ONLY the headshot cache."""
+    row); this table is the people's own facts: the headshot link, the TMDB link and the TMDB bio
+    (the headshot FILE lives in the image cache, filled by the people_enrich job)."""
 
     __tablename__ = "plex_people"
 
     id: Mapped[int] = mapped_column(primary_key=True)
     name: Mapped[str] = mapped_column(String(255), unique=True, index=True)
     photo_thumb: Mapped[str | None] = mapped_column(Text)  # proxied /person-image URL, or None
-    # TMDB person id, linked by name from a title's TMDB credits (E5 S2 lays the foundation; the /person
-    # biography fetch + person-page render land in S6). NULL until a TMDB-enriched title names this person.
+    # TMDB person id, linked by name from a title's TMDB credits (the /person
+    # biography fetch builds on it). NULL until a TMDB-enriched title names this person.
     tmdb_person_id: Mapped[int | None] = mapped_column(Integer)
-    # --- TMDB person enrichment (E5 S6): fetched from /person/{tmdb_person_id} the first time the person
-    #     page is opened, then SERVED FROM THE ROW. `tmdb_enriched_at` is the watermark (set even on a
+    # --- TMDB person enrichment: fetched from /person/{tmdb_person_id} by the people_enrich job,
+    #     or by the first person-page open the job hasn't reached, then SERVED FROM THE ROW. `tmdb_enriched_at` is the watermark (set even on a
     #     no-op fetch so it isn't retried every open). `known_for` = top combined-credits [{tmdb_id,
     #     media_type, title}], resolved to library rows by guid at serve time (like recommendations). ---
     biography: Mapped[str | None] = mapped_column(Text)
+    # TMDB's Hungarian biography, from the same request's `translations`; a Hungarian reader is
+    # served it, and the instance-language `biography` when TMDB has none. Birthplace, aliases and
+    # keywords have no Hungarian on TMDB, so they stay in the instance language.
+    biography_hu: Mapped[str | None] = mapped_column(Text)
     birthday: Mapped[str | None] = mapped_column(String(10))  # "YYYY-MM-DD", served as-is
     deathday: Mapped[str | None] = mapped_column(String(10))
     place_of_birth: Mapped[str | None] = mapped_column(Text)
@@ -1337,7 +1417,7 @@ class PlexCollection(Base, TimestampMixin, UpdatedAtMixin):
 class PlexState(Base, UpdatedAtMixin):
     """Per-user watch state for a Plex item — mirrors VideoState. Lives in Siftlode's own DB so
     it works for users WITHOUT a Plex account (the whole point of the access-layer design).
-    `synced_to_plex` marks whether this state was pushed back to a linked Plex account (P5)."""
+    `synced_to_plex` marks whether this state was pushed back to a linked Plex account."""
 
     __tablename__ = "plex_states"
     __table_args__ = (UniqueConstraint("user_id", "item_id", name="uq_plex_user_item"),)
@@ -1416,7 +1496,7 @@ class PlexPlaylistItem(Base):
 
 
 class ComfortPin(Base, TimestampMixin):
-    """One entry on a user's comfort shelf — the anti-paralysis fallback: "just put on X" (E24).
+    """One entry on a user's comfort shelf — the anti-paralysis fallback: "just put on X".
 
     Deliberately NOT a boolean on `VideoState`/`PlexState`, and NOT a polymorphic `(kind, ref)` string
     pair. A flag cannot ORDER a shelf and cannot hold a channel or a show — and comfort media is

backend/app/plex/cards.py

@@ -15,20 +15,35 @@ def _art_url(rating_key: str, art_key: str | None) -> str | None:
 
 
 # Card hover-overview: a short synopsis for the reveal panel, trimmed so a strip/related row of cards
-# stays a few hundred bytes each rather than carrying full synopses. (These non-grid card paths serve
-# the EN summary/rating; the main grid coalesces the HU twin in browse.unified_library.)
+# stays a few hundred bytes each rather than carrying full synopses.
 def _card_summary(summary: str | None) -> str | None:
     return (summary or "")[:300] or None
 
 
-def movie_card(it: PlexItem, st: PlexState | None) -> dict:
+def norm_lang(lang: str | None) -> str:
+    """The overlay has an EN base + an optional HU twin; anything other than `hu` serves EN."""
+    return "hu" if lang == "hu" else "en"
+
+
+# Every card speaks the reader's language: `lang="hu"` serves the HU overlay twin's title and
+# summary, falling back to EN where a row has none — the same rule as browse.unified_library's
+# `title_col`/`summary_col`. These rails once served English to a Hungarian reader.
+def display_title(row: PlexItem | PlexShow, lang: str) -> str:
+    return (row.title_hu or row.title) if lang == "hu" else row.title
+
+
+def display_summary(row: PlexItem | PlexShow, lang: str) -> str | None:
+    return (row.summary_hu or row.summary) if lang == "hu" else row.summary
+
+
+def movie_card(it: PlexItem, st: PlexState | None, *, lang: str) -> dict:
     return {
         "id": it.rating_key,
         "type": "movie",
-        "title": it.title,
+        "title": display_title(it, lang),
         "year": it.year,
         "rating": it.rating,
-        "summary": _card_summary(it.summary),
+        "summary": _card_summary(display_summary(it, lang)),
         "duration_seconds": it.duration_s,
         "thumb": f"/api/plex/image/{it.rating_key}",
         "art": _art_url(it.rating_key, it.art_key),
@@ -39,14 +54,14 @@ def movie_card(it: PlexItem, st: PlexState | None) -> dict:
     }
 
 
-def show_card(sh: PlexShow, status: str = "new") -> dict:
+def show_card(sh: PlexShow, status: str = "new", *, lang: str) -> dict:
     return {
         "id": sh.rating_key,
         "type": "show",
-        "title": sh.title,
+        "title": display_title(sh, lang),
         "year": sh.year,
         "rating": sh.rating,
-        "summary": _card_summary(sh.summary),
+        "summary": _card_summary(display_summary(sh, lang)),
         "thumb": f"/api/plex/image/{sh.rating_key}",
         "art": _art_url(sh.rating_key, sh.art_key),
         "season_count": sh.child_count,
@@ -55,12 +70,12 @@ def show_card(sh: PlexShow, status: str = "new") -> dict:
     }
 
 
-def episode_card(e: PlexItem, st: PlexState | None) -> dict:
+def episode_card(e: PlexItem, st: PlexState | None, *, lang: str) -> dict:
     return {
         "id": e.rating_key,
         "type": "episode",
-        "title": e.title,
-        "summary": e.summary,
+        "title": display_title(e, lang),
+        "summary": display_summary(e, lang),
         "season_number": e.season_number,
         "episode_number": e.episode_number,
         "duration_seconds": e.duration_s,
@@ -77,12 +92,15 @@ def leaf_card(
     st: PlexState | None,
     show_title: str | None = None,
     show_rk: str | None = None,
+    *,
+    lang: str,
 ) -> dict:
     """A playable-leaf card (movie or episode). Used by playlists, which can mix both kinds.
-    `show_rk` (the show's rating_key) lets the client group a playlist's episodes by show/season."""
+    `show_rk` (the show's rating_key) lets the client group a playlist's episodes by show/season.
+    `show_title` is the caller's, already in `lang` (see `display_title`)."""
     if it.kind == "episode":
-        card = episode_card(it, st)
+        card = episode_card(it, st, lang=lang)
         card["show_title"] = show_title
         card["show_id"] = show_rk
         return card
-    return movie_card(it, st)
+    return movie_card(it, st, lang=lang)

backend/app/plex/client.py

@@ -2,20 +2,19 @@
 
 Server-side ONLY: uses the admin ``X-Plex-Token`` from sysconfig. Playback never goes through
 this client — Siftlode plays the LOCAL physical file (see app.plex.paths). Plex is used purely for
-metadata, image proxying, and (P5) optional watch-state write-back. Requests JSON via the
+metadata, image proxying, and optional watch-state write-back. Requests JSON via the
 ``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):
@@ -66,7 +65,7 @@ class PlexClient:
         except ValueError as e:
             raise PlexError("Plex returned a non-JSON response") from e
 
-    # --- Connectivity + sections (P0) ---
+    # --- Connectivity + sections ---
     def server_info(self) -> dict:
         """Root identity (friendlyName / version) — used by the admin 'Test connection'."""
         return self._get("/")
@@ -76,25 +75,29 @@ class PlexClient:
         mc = self._get("/library/sections")
         return mc.get("Directory", []) or []
 
-    # --- Catalog mirror (P1) ---
+    # --- Catalog mirror ---
     def section_items(
         self, key: str, item_type: int, start: int = 0, size: int = 200
-    ) -> tuple[list[dict], int]:
+    ) -> tuple[list[dict], int | None]:
         """A page of a section's top-level items. type 1 = movie, 2 = show. Returns
-        (items, total_size)."""
+        (items, total_size); the total is None when the answer carries none, so a container that
+        says "0" (a genuinely empty section) stays distinguishable from one that says nothing."""
         mc = self._get(
             f"/library/sections/{key}/all",
             params={
                 "type": item_type,
                 # includeGuids=1 carries each item's Guid array (tmdb/imdb/tvdb ids) in the cheap
                 # listing, so the sync can capture the canonical guid without a per-item rich fetch —
-                # the pairing key for the HU overlay (E5 S5).
+                # the pairing key for the HU overlay.
                 "includeGuids": 1,
                 "X-Plex-Container-Start": start,
                 "X-Plex-Container-Size": size,
             },
         )
-        return mc.get("Metadata", []) or [], int(mc.get("totalSize", mc.get("size", 0)) or 0)
+        # `totalSize` only: `size` is THIS page's count, and read as the total it made a single
+        # page look like the whole section — "complete" to a prune or a reconcile.
+        total = mc.get("totalSize")
+        return mc.get("Metadata", []) or [], None if total is None else int(total)
 
     def children(self, rating_key: str) -> list[dict]:
         """Direct children (show → seasons, season → episodes)."""
@@ -106,7 +109,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 []:
@@ -123,12 +137,17 @@ class PlexClient:
         mc = self._get(f"/library/collections/{rating_key}/children")
         return mc.get("Metadata", []) or []
 
-    # --- Collection editing (P2 — write-back to Plex; all shared/global, admin-gated in the routes) ---
+    # --- Collection editing (write-back to Plex; all shared/global, admin-gated in the routes) ---
     @property
     def machine_id(self) -> str:
-        """Server machineIdentifier — needed in the `uri` of collection add/create calls. Cached."""
+        """Server machineIdentifier — needed in the `uri` of collection add/create calls. Cached.
+        Without one the uri would read `server:///…`, a malformed write Plex answers in its own way;
+        it is refused here, by name."""
         if not getattr(self, "_machine_id", None):
-            self._machine_id = self._get("/identity").get("machineIdentifier") or ""
+            mid = self._get("/identity").get("machineIdentifier")
+            if not mid:
+                raise PlexError("Plex did not report its machine identifier")
+            self._machine_id = mid
         return self._machine_id
 
     def _write(self, method: str, path: str) -> dict:
@@ -139,6 +158,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 {}
 
@@ -146,12 +167,16 @@ class PlexClient:
         keys = ",".join(str(k) for k in rating_keys)
         return f"server://{self.machine_id}/com.plexapp.plugins.library/library/metadata/{keys}"
 
-    def create_collection(self, section_key: str, title: str, item_rating_key: str) -> dict:
-        """Create a (dumb) collection seeded with one item; returns its Metadata (incl. ratingKey)."""
+    def create_collection(
+        self, section_key: str, title: str, item_rating_key: str, item_type: int = 1
+    ) -> dict:
+        """Create a (dumb) collection seeded with one item; returns its Metadata (incl. ratingKey).
+        `item_type` is the Plex metadata type of its members — 1 movie, 2 show. Measured: a collection
+        made as type 1 in a TV section came out EMPTY with a show seed, and refused the show after."""
         uri = quote(self._metadata_uri(item_rating_key), safe="")
         mc = self._write(
             "POST",
-            f"/library/collections?type=1&smart=0&sectionId={section_key}"
+            f"/library/collections?type={item_type}&smart=0&sectionId={section_key}"
             f"&title={quote(title, safe='')}&uri={uri}",
         )
         items = mc.get("Metadata", []) or []
@@ -185,7 +210,7 @@ class PlexClient:
         items = mc.get("Metadata", []) or []
         return items[0] if items else None
 
-    # --- Watch-state write-back (P5 Phase B — Siftlode→Plex push; acts on the token's account) ---
+    # --- Watch-state write-back (Siftlode→Plex push; acts on the token's account) ---
     _LIBRARY_IDENTIFIER = "com.plexapp.plugins.library"
 
     def scrobble(self, rating_key: str) -> None:
@@ -222,7 +247,7 @@ class PlexClient:
             f"&state={state}&time={int(time_ms)}&duration={int(duration_ms)}",
         )
 
-    # --- Watch-state read for incremental sync (P5 Phase C) ---
+    # --- Watch-state read for incremental sync ---
     def accounts(self) -> list[dict]:
         """Server accounts (the owner + any managed/home users): id, name. Used to resolve the
         owner's accountID so the shared watch-history feed can be filtered to just their views."""

backend/app/plex/detail.py

@@ -1,5 +1,5 @@
 """Parse the "info page" rich metadata out of a full Plex metadata dict, and persist the subset that
-the detail endpoints serve from the DB row (E5 S5b).
+the detail endpoints serve from the DB row.
 
 Shared by the live info-page path (routes.plex.browse) and the background rich re-sync (plex.sync) so
 the two never diverge — the same one-parser rule that keeps `people.py`'s cast handling consistent.
@@ -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/genres.py

@@ -0,0 +1,100 @@
+"""One Hungarian word per Plex genre.
+
+Plex's Hungarian agent returns a MIXED vocabulary: some genres come back translated ("Dráma",
+"Vígjáték"), others stay English ("Action", "Adventure", "Biography"), and a title with no HU twin has
+only its English genres. The HU genre list therefore offered "Drama" beside "Dráma" and a dozen English
+words. This map sends every genre word we have met — English (Plex EN agent, TMDB, IMDb) or Plex's
+Hungarian — to the ONE word a Hungarian reader sees. The overlay sync writes it into `genres_hu`, and a
+genre filter is read through it too, so a saved filter still holding "Action" keeps matching "Akció".
+
+A word not in the map passes through unchanged: an unknown genre stays visible (in whatever language
+Plex gave it) rather than disappearing.
+"""
+
+from collections.abc import Iterable
+
+# Keys are matched case-insensitively (see `_BY_KEY`). The Hungarian values double as keys mapping to
+# themselves, so running a list through twice changes nothing.
+_HU: dict[str, str] = {
+    "Action": "Akció",
+    "Action & Adventure": "Akció és kaland",
+    "Adventure": "Kaland",
+    "Animation": "Animációs",
+    "Anime": "Anime",
+    "Biography": "Életrajzi",
+    "Children": "Gyerek",
+    "Comedy": "Vígjáték",
+    "Crime": "Bűnügyi",
+    "Documentary": "Dokumentum",
+    "Drama": "Dráma",
+    "Family": "Családi",
+    "Fantasy": "Fantasy",
+    "Film-Noir": "Film noir",
+    "Food": "Gasztronómia",
+    "Game Show": "Vetélkedő",
+    "Game-Show": "Vetélkedő",
+    "History": "Történelmi",
+    "Home and Garden": "Otthon és kert",
+    "Horror": "Horror",
+    "Indie": "Független",
+    "Kids": "Gyerek",
+    "Martial Arts": "Harcművészet",
+    "Mini-Series": "Minisorozat",
+    "Music": "Zenei",
+    "Musical": "Musical",
+    "Mystery": "Rejtély",
+    "News": "Hírek",
+    "Reality": "Valóságshow",
+    "Reality-TV": "Valóságshow",
+    "Romance": "Romantikus",
+    "Sci-Fi": "Sci-Fi",
+    "Sci-Fi & Fantasy": "Sci-Fi és fantasy",
+    "Science Fiction": "Sci-Fi",
+    "Short": "Rövidfilm",
+    "Soap": "Szappanopera",
+    "Sport": "Sport",
+    "Suspense": "Feszültség",
+    "Talk": "Talkshow",
+    "Talk Show": "Talkshow",
+    "Thriller": "Thriller",
+    "Travel": "Utazás",
+    "TV Movie": "TV film",
+    "War": "Háborús",
+    "War & Politics": "Háború és politika",
+    "Western": "Western",
+    # Plex's own Hungarian words, pinned to themselves (and to the spelling above where they differ).
+    "Akció": "Akció",
+    "Animációs": "Animációs",
+    "Bűnügyi": "Bűnügyi",
+    "Családi": "Családi",
+    "Dokumentum": "Dokumentum",
+    "Dokumentumfilm": "Dokumentum",
+    "Dráma": "Dráma",
+    "Életrajzi": "Életrajzi",
+    "Háborús": "Háborús",
+    "Kaland": "Kaland",
+    "Rejtély": "Rejtély",
+    "Romantikus": "Romantikus",
+    "Történelmi": "Történelmi",
+    "TV film": "TV film",
+    "Vígjáték": "Vígjáték",
+    "Zene": "Zenei",
+    "Zenei": "Zenei",
+}
+_BY_KEY = {k.casefold(): v for k, v in _HU.items()}
+
+
+def hu_genre(word: str) -> str:
+    """The Hungarian word for one genre; an unknown word comes back unchanged."""
+    return _BY_KEY.get(word.strip().casefold(), word)
+
+
+def hu_genres(words: Iterable[str] | None) -> list[str] | None:
+    """A genre list in Hungarian, in its first-seen order, each word once ("Drama" + "Dráma" → one
+    "Dráma"). None or empty stays None, like the listing's own `_tags`."""
+    out: list[str] = []
+    for w in words or ():
+        hu = hu_genre(w)
+        if hu not in out:
+            out.append(hu)
+    return out or None

backend/app/plex/imgcache.py

@@ -8,18 +8,38 @@ few hundred MB at most for a big library — acceptable, matching the download d
 The cache directory (``cache.CACHE_DIR``) is shared with the subtitle cache (see ``subtitles.py``).
 """
 
+import time
+from datetime import timedelta
+
 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/
-# strips), so 400px covers 2× DPR; the faint backdrop art only needs ~1280px. Keeps images ~tens of KB.
-SIZES = {"thumb": (400, 600), "art": (1280, 720)}
+# Target box per variant — Plex resizes to these server-side. The full poster (400px) covers a detail
+# page's ≤224px poster at 2× DPR, the full art (1280px) a hero backdrop. A card is much smaller: a grid
+# poster is ~144px and a shelf's landscape art ~212px, so the `_sm` pair serves those at 1.33× DPR
+# (cards used to fetch the 400 poster, 42 KB, and the 1280 art for a 212px picture). The browser
+# picks between a pair itself (`srcset`, built by the frontend's `lib/plexImage` cardImage, whose
+# widths plexImage.contract.test holds to these).
+SIZES = {
+    "thumb": (400, 600),
+    "thumb_sm": (240, 360),
+    "art": (1280, 720),
+    "art_sm": (480, 270),
+}
+
+
+def picture(variant: str) -> str:
+    """Which stored picture a size variant is cut from: the poster (`thumb`) or the backdrop (`art`)."""
+    return "art" if variant.startswith("art") else "thumb"
 
 
 def key_for(db: Session, rating_key: str, variant: str) -> str | None:
@@ -46,11 +66,56 @@ 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
 
 
+def has(key: str) -> bool:
+    """A cached, non-empty file exists for `key` (a prefetch's cheap check — no read)."""
+    for ext, _ in _EXT_CT:
+        try:
+            if (CACHE_DIR / f"{key}.{ext}").stat().st_size > 0:
+                return True
+        # silent-ok: a miss, as in read().
+        except OSError:
+            pass
+    return False
+
+
+def drop(key: str) -> None:
+    """Remove `key`'s file, whatever its extension (a superseded variant). Best-effort."""
+    for ext, _ in _EXT_CT:
+        try:
+            (CACHE_DIR / f"{key}.{ext}").unlink(missing_ok=True)
+        # silent-ok: a leftover original only costs disk; the small twin is already written.
+        except OSError:
+            pass
+
+
+def mark_miss(key: str) -> None:
+    """Remember that `key`'s source could not be fetched (an empty `.miss` file; its mtime is when), so
+    a prefetch can leave a dead source alone for a while. Best-effort."""
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        (CACHE_DIR / f"{key}.miss").touch()
+    # silent-ok: without the mark the dead source is only asked for again on the next run.
+    except OSError:
+        pass
+
+
+def missed_within(key: str, age: timedelta) -> bool:
+    """`key` was marked as a miss less than `age` ago."""
+    try:
+        mtime = (CACHE_DIR / f"{key}.miss").stat().st_mtime
+    # silent-ok: no mark (the usual case).
+    except OSError:
+        return False
+    return time.time() - mtime < age.total_seconds()
+
+
 def write(key: str, data: bytes, ct: str) -> None:
     ext = _CT_EXT.get((ct or "").split(";")[0].strip(), "jpg")
     try:
@@ -58,8 +123,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/overlay.py

@@ -0,0 +1,150 @@
+"""The HU overlay: a Hungarian Plex section written onto its English twin's rows, split out of
+`plex/sync.py`, which runs it once per paired section during the full sync.
+
+The pairing is admin-configured (`plex_overlay_map`, ``huKey:enKey,...``). An overlay section creates
+no browsable rows of its own; it only fills the `*_hu` columns of the EN rows it matches by guid.
+`plex/sync.py` and this module import each other as MODULES (attribute access at call time), which is
+what lets either be imported first.
+"""
+
+from collections.abc import Iterable
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app import logs, sysconfig
+from app.models import PlexItem, PlexLibrary, PlexShow
+from app.plex import sync as plex_sync
+from app.plex.client import PlexClient
+from app.plex.genres import hu_genres
+
+log = logs.get_logger(__name__)
+
+
+def overlay_map(db: Session) -> dict[str, str]:
+    """The configured HU-overlay pairing: {huSectionKey: enSectionKey} from `plex_overlay_map`
+    ('huKey:enKey,...'). Each HU section is synced as a non-browsable overlay onto its EN twin.
+    Malformed pairs are skipped."""
+    raw = sysconfig.get_str(db, "plex_overlay_map")
+    out: dict[str, str] = {}
+    for pair in raw.split(","):
+        hu, sep, en = pair.partition(":")
+        hu, en = hu.strip(), en.strip()
+        if sep and hu and en:
+            out[hu] = en
+    return out
+
+
+def sync_overlay(
+    db: Session, plex: PlexClient, lib: PlexLibrary, en_lib_id: int, stats: dict
+) -> None:
+    """Write an overlay section's Hungarian metadata onto its EN twin's rows, matched by guid. Creates
+    NO browsable rows — an overlay library is never listed on its own. Only title/summary/tagline/genres
+    differ by language; the language-neutral people_text feeds both search vectors. A show section's
+    episodes are overlaid too: the HU section lists every episode with its Hungarian title and
+    summary, and the episode rows live in the EN show library.
+
+    This is a full RECONCILE: after a COMPLETE HU listing every guid-bearing EN row's HU fields are
+    cleared, then the matches are repopulated — so an EN row whose HU twin vanished (or was re-guid'd)
+    falls back to EN instead of keeping stale Hungarian metadata. A listing cut short only adds. HU
+    items with no EN match are skipped."""
+    if lib.kind == "movie":
+        passes = [
+            (
+                plex_sync._TYPE_MOVIE,
+                select(PlexItem).where(
+                    PlexItem.library_id == en_lib_id,
+                    PlexItem.kind == "movie",
+                    PlexItem.guid.is_not(None),
+                ),
+            )
+        ]
+    else:
+        passes = [
+            (
+                plex_sync._TYPE_SHOW,
+                select(PlexShow).where(
+                    PlexShow.library_id == en_lib_id, PlexShow.guid.is_not(None)
+                ),
+            ),
+            (
+                plex_sync._TYPE_EPISODE,
+                select(PlexItem).where(
+                    PlexItem.library_id == en_lib_id,
+                    PlexItem.kind == "episode",
+                    PlexItem.guid.is_not(None),
+                ),
+            ),
+        ]
+    for item_type, rows_q in passes:
+        _overlay_pass(db, plex, lib, item_type, db.execute(rows_q).scalars(), stats)
+    db.flush()
+
+
+def _overlay_pass(
+    db: Session,
+    plex: PlexClient,
+    lib: PlexLibrary,
+    item_type: int,
+    rows: Iterable[PlexItem] | Iterable[PlexShow],
+    stats: dict,
+) -> None:
+    """One kind of the overlay (movies, shows or episodes) — see `sync_overlay`."""
+    # guid -> the EN rows carrying it (a list: two editions of one film can share a guid; both overlay).
+    by_guid: dict[str, list[PlexItem | PlexShow]] = {}
+    for r in rows:
+        if r.guid:  # the passes select guid-bearing rows only
+            by_guid.setdefault(r.guid, []).append(r)
+    # The HU listing is read first and applied after, so the clear can wait for its verdict.
+    hu_by_guid, complete = _read_hu_listing(plex, lib, item_type, by_guid)
+    episodes = item_type == plex_sync._TYPE_EPISODE
+    if complete:
+        _clear_hu(by_guid, episodes)
+    else:
+        stats["overlay_incomplete"] = stats.get("overlay_incomplete", 0) + 1
+        log.warning(
+            "the HU listing ended before the server's total; existing HU text is kept",
+            extra=logs.event("plex.sync.overlay_incomplete", library=lib.plex_key),
+        )
+    for g, meta in hu_by_guid.items():
+        targets = by_guid[g]
+        title_hu = (meta.get("title") or "").strip() or None
+        summary_hu = meta.get("summary")
+        tagline_hu = (meta.get("tagline") or "").strip() or None
+        genres_hu = hu_genres(plex_sync._tags(meta, "Genre"))
+        for row in targets:
+            row.title_hu = title_hu
+            row.summary_hu = summary_hu
+            if not episodes:
+                row.tagline_hu = tagline_hu
+                row.genres_hu = genres_hu or row.genres_hu
+        stats["overlaid"] = stats.get("overlaid", 0) + 1
+
+
+def _read_hu_listing(
+    plex: PlexClient, lib: PlexLibrary, item_type: int, by_guid: dict
+) -> tuple[dict[str, dict], bool]:
+    """The HU section's entries for the guids the EN side carries, and whether the walk reached the
+    server's total. The first HU entry for a guid wins; a dup HU item can't overwrite or double-count."""
+    progress: dict = {}
+    hu_by_guid: dict[str, dict] = {}
+    for meta in plex_sync._paginate(plex, lib.plex_key, item_type, progress):
+        g = plex_sync._canonical_guid(meta)
+        if g and g in by_guid and g not in hu_by_guid:
+            hu_by_guid[g] = meta
+    return hu_by_guid, bool(progress.get("complete"))
+
+
+def _clear_hu(by_guid: dict, episodes: bool) -> None:
+    """Reconcile step: clear HU fields on all guid-bearing rows; the matches are re-set after. Only
+    rows that actually held HU data become dirty (SQLAlchemy skips a no-net-change UPDATE), so this is
+    cheap. The genres are the exception: every row gets Hungarian ones, from its HU twin or, lacking
+    one, from its own English list — otherwise the HU genre list mixed "Drama" (no twin) with "Dráma".
+    Only after a COMPLETE listing: one a Plex hiccup cut short would clear the HU text of every title
+    it failed to reach, until the next full sync (the watch reconcile's twin)."""
+    for group in by_guid.values():
+        for row in group:
+            row.title_hu = row.summary_hu = None
+            if not episodes:
+                row.tagline_hu = None
+                row.genres_hu = hu_genres(row.genres)

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/people.py

@@ -3,13 +3,23 @@ or show (cast_names + the people_text search blob + the plex_people headshot cac
 orphaned people. Used by BOTH the info-page lazy enrichment (routes.plex) and the background rich
 re-sync (plex.sync), so the two paths never diverge."""
 
-from urllib.parse import quote
+import hashlib
+import re
+from datetime import timedelta
+from typing import Literal
+from urllib.parse import quote, unquote
 
+import httpx
 from sqlalchemy import select, text
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
+from app import logs, sysconfig
 from app.models import PlexPerson
+from app.plex import imgcache
+from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+
+log = logs.get_logger(__name__)
 
 # Cast/crew photos come from Plex's PUBLIC metadata CDN (no token). We proxy them (host-whitelisted)
 # so the user's browser makes no third-party request (privacy + self-host CSP friendliness).
@@ -19,9 +29,7 @@ PERSON_IMG_HOST = "https://metadata-static.plex.tv/"
 def person_thumb_url(thumb: str | None) -> str | None:
     """Proxied /person-image URL for a Plex CDN headshot, or None when it's missing / off-CDN."""
     t = str(thumb or "")
-    return (
-        f"/api/plex/person-image?u={quote(t, safe='')}" if t.startswith(PERSON_IMG_HOST) else None
-    )
+    return f"/api/plex/person-image?u={quote(t, safe='')}" if is_portrait_url(t) else None
 
 
 def cast_from_meta(meta: dict, limit: int = 24) -> list[dict]:
@@ -89,14 +97,23 @@ def enrich_row_people(db: Session, row, cast: list[dict]) -> bool:
     return dirty
 
 
+# Every credit reference: one person name per (movie/show, credit column). The ONE list of credit
+# columns, so the orphan prune and the enrichment order never disagree about who is credited.
+_CREDIT_COLUMNS = [
+    (table, col) for table in ("plex_items", "plex_shows") for col in ("cast_names", "directors")
+]
+
+
+def _credit_refs_sql(union: Literal["UNION", "UNION ALL"]) -> str:
+    return f" {union} ".join(
+        f"SELECT jsonb_array_elements_text({col}) FROM {table} WHERE jsonb_typeof({col}) = 'array'"
+        for table, col in _CREDIT_COLUMNS
+    )
+
+
 # The person names still referenced by ANY movie/show (cast OR directors). plex_people rows outside
 # this set are orphans left by a library removal.
-_REFERENCED_PEOPLE_SQL = """
-    SELECT jsonb_array_elements_text(cast_names) FROM plex_items WHERE jsonb_typeof(cast_names) = 'array'
-    UNION SELECT jsonb_array_elements_text(directors) FROM plex_items WHERE jsonb_typeof(directors) = 'array'
-    UNION SELECT jsonb_array_elements_text(cast_names) FROM plex_shows WHERE jsonb_typeof(cast_names) = 'array'
-    UNION SELECT jsonb_array_elements_text(directors) FROM plex_shows WHERE jsonb_typeof(directors) = 'array'
-"""
+_REFERENCED_PEOPLE_SQL = _credit_refs_sql("UNION")
 
 
 def prune_orphan_people(db: Session) -> int:
@@ -113,3 +130,152 @@ def prune_orphan_people(db: Session) -> int:
     )
     db.commit()
     return res.rowcount or 0
+
+
+# How often each person is credited across movies, shows and episodes (cast OR director) — the order the
+# people_enrich job works in, so the faces met most often are local first.
+_CREDIT_COUNTS_SQL = (
+    f"SELECT ref, count(*) AS n FROM ({_credit_refs_sql('UNION ALL')}) AS refs(ref) GROUP BY ref"
+)
+_NEEDS = {
+    # linked to TMDB, bio never fetched
+    "bio": "p.tmdb_person_id IS NOT NULL AND p.tmdb_enriched_at IS NULL",
+    # has a Plex headshot (whether it is cached is the disk's answer, not the row's)
+    "portrait": "p.photo_thumb IS NOT NULL",
+}
+
+
+def people_by_credits(
+    db: Session, need: Literal["bio", "portrait"], limit: int | None
+) -> list[int]:
+    """plex_people ids that `need` something, the most-credited first (ties by id)."""
+    rows = db.execute(
+        text(
+            f"SELECT p.id FROM plex_people p LEFT JOIN ({_CREDIT_COUNTS_SQL}) c ON c.ref = p.name "
+            f"WHERE {_NEEDS[need]} ORDER BY coalesce(c.n, 0) DESC, p.id"
+            + (" LIMIT :limit" if limit is not None else "")
+        ),
+        {"limit": limit} if limit is not None else {},
+    )
+    return [r[0] for r in rows]
+
+
+# --- Portraits ---------------------------------------------------------------------------
+# A Plex CDN headshot is a full-size original (~170 KB on average, measured). Plex's photo transcoder
+# fits it into this box (~13 KB), which covers the largest place a portrait is drawn (the person page's
+# 6rem avatar) at 2x density and a raised text size. The box is part of the cache key, like a poster's:
+# a new box re-caches instead of serving a stale size. Only a resized image is ever written under it —
+# an original fetched without Plex keeps its own key, and goes once its small twin lands.
+PORTRAIT_BOX = 320
+# A headshot Plex answered "not found" for (a dead CDN file) is not asked for again this long, so a
+# few dead faces never hold up the rest of the prefetch.
+PORTRAIT_RETRY = timedelta(days=7)
+# The one shape a Plex CDN headshot has (…/7/people/<hash>.jpg): plain path segments, no query, no
+# fragment, no dot segment or empty segment (an HTTP client folds `a/../b` and the CDN `a//b` onto one
+# file). The person-image proxy takes nothing else, so it cannot be made to cache endless spellings of
+# one file (the image cache has no eviction). Used where a stored headshot is made, served and warmed.
+_SEGMENT = r"[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*"  # a name, dots only between its parts
+_PORTRAIT_URL = re.compile(re.escape(PERSON_IMG_HOST) + _SEGMENT + rf"(?:/{_SEGMENT})*")
+
+
+def is_portrait_url(url: str) -> bool:
+    return _PORTRAIT_URL.fullmatch(url) is not None
+
+
+def _portrait_keys(url: str) -> tuple[str, str]:
+    """(the resized portrait's key, the full-size original's key)."""
+    base = "person_" + hashlib.sha1(url.encode()).hexdigest()
+    return f"{base}_{PORTRAIT_BOX}", base
+
+
+def portrait_cached(url: str) -> tuple[bytes, str] | None:
+    """The cached portrait: the resized one, else an original kept from a time without Plex."""
+    small, original = _portrait_keys(url)
+    return imgcache.read(small) or imgcache.read(original)
+
+
+def cache_portrait(plex: PlexClient | None, url: str) -> tuple[bytes, str]:
+    """Fetch one CDN headshot and cache it. With a Plex client it is resized (the box key; the original
+    is removed); without one the original comes straight from the public CDN and is cached under its own
+    key, so the job still resizes it once Plex is there. Raises PlexError / httpx.HTTPError."""
+    small, original = _portrait_keys(url)
+    if plex is None:
+        with httpx.Client(timeout=10.0, follow_redirects=True) as c:
+            r = c.get(url)
+            r.raise_for_status()
+        data, ct = r.content, r.headers.get("content-type", "image/jpeg")
+        imgcache.write(original, data, ct)
+        return data, ct
+    data, ct = plex.image_bytes(url, PORTRAIT_BOX, PORTRAIT_BOX)
+    imgcache.write(small, data, ct)
+    imgcache.drop(original)
+    return data, ct
+
+
+def cdn_url(photo_thumb: str) -> str | None:
+    """The CDN url inside a stored proxied `/person-image?u=` value (see person_thumb_url)."""
+    _, _, q = photo_thumb.partition("?u=")
+    url = unquote(q)
+    return url if is_portrait_url(url) else None
+
+
+# Plex failing this many headshots in a row ends a run: it is Plex that is failing, not the files.
+_PLEX_DOWN_AFTER = 3
+# The statuses that mean the one file is gone.
+_DEAD = frozenset({404, 410})
+
+
+def warm_portraits(db: Session, limit: int) -> dict:
+    """Cache up to `limit` not-yet-cached headshots, the most-credited people first, so a
+    person's face comes from local disk. Needs Plex (the resize) and the Plex module on; without them
+    nothing is prefetched — full-size originals for every person would cost gigabytes. A headshot Plex
+    answers "not found" for is marked and left for PORTRAIT_RETRY; Plex failing in a row ends the run."""
+    if not sysconfig.get_bool(db, "plex_enabled"):
+        return {"cached": 0, "skipped": "disabled"}
+    try:
+        plex = PlexClient(db)
+    # silent-ok: no Plex server set up is a setting, not a failure; the run's result says "disabled".
+    except PlexNotConfigured:
+        return {"cached": 0, "skipped": "disabled"}
+    photos: dict[int, str] = {
+        pid: thumb
+        for pid, thumb in db.execute(
+            select(PlexPerson.id, PlexPerson.photo_thumb).where(PlexPerson.photo_thumb.is_not(None))
+        ).tuples()
+        if thumb
+    }
+    # `down` counts Plex failing in a row (any answer from Plex breaks it), `plex_failed` in all
+    done = dead = plex_failed = down = 0
+    with plex:
+        for pid in people_by_credits(db, "portrait", None):
+            if done + dead >= limit or down >= _PLEX_DOWN_AFTER:
+                break
+            url = cdn_url(photos.get(pid) or "")
+            if url is None:
+                continue
+            key = _portrait_keys(url)[0]
+            if imgcache.has(key) or imgcache.missed_within(key, PORTRAIT_RETRY):
+                continue
+            try:
+                cache_portrait(plex, url)
+                done, down = done + 1, 0
+            except PlexError as exc:
+                # "Not found" is Plex's answer about this one file (a dead CDN headshot: measured 404,
+                # the CDN itself says 403). Anything else — no answer, a refused token, a 5xx — is
+                # Plex failing, which must neither mark the file nor keep the run going.
+                cause = exc.__cause__
+                if isinstance(cause, httpx.HTTPStatusError) and cause.response.status_code in _DEAD:
+                    dead, down = dead + 1, 0  # Plex answered: it is up, the streak is broken
+                    imgcache.mark_miss(key)
+                else:
+                    plex_failed, down = plex_failed + 1, down + 1
+                log.warning(
+                    "a portrait could not be cached",
+                    extra=logs.event(
+                        "plex.people.portrait_failed",
+                        person_id=pid,
+                        reason=type(exc.__cause__).__name__,
+                    ),
+                )
+    failed = dead + plex_failed
+    return {"cached": done, **({"failed": failed} if failed else {})}

backend/app/plex/query.py

@@ -11,6 +11,7 @@ from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Session
 
 from app.models import PlexItem, PlexLibrary
+from app.plex.genres import hu_genre
 
 TS_CONFIG = "public.unaccent_simple"
 
@@ -30,9 +31,9 @@ PLEX_SORT_KEYS: tuple[str, ...] = (
     "title",
 )
 
-# --- Language-aware column pickers (E5 S6) ----------------------------------
+# --- Language-aware column pickers ----------------------------------
 #
-# The HU-overlay twin (E5 S5) stores Hungarian metadata in `*_hu` columns on the SAME EN row. When
+# The HU-overlay twin stores Hungarian metadata in `*_hu` columns on the SAME EN row. When
 # the app language is `hu` we serve those, falling back to the EN column where a row has no HU twin.
 # Two flavours of picker, on purpose:
 #   * DISPLAY / FILTER (`title_col`/`genres_col`): `coalesce(*_hu, *)` — an EN fallback so a row with
@@ -40,8 +41,8 @@ PLEX_SORT_KEYS: tuple[str, ...] = (
 #     HU summary directly off the loaded row, so no `summary_col` SQL helper is needed.)
 #   * SEARCH (`vector_col` + `field_recheck`): the raw `*_hu` column coalesced to '' — MIRRORING the
 #     generated `search_vector_hu` definition (which uses `coalesce(title_hu, '')`, NOT an EN
-#     fallback), so the field recheck stays a strict subset of the GIN vector prefilter (the S2
-#     invariant). `people_text` is language-neutral and shared by both vectors.
+#     fallback), so the field recheck stays a strict subset of the GIN vector prefilter (the
+#     field-search invariant). `people_text` is language-neutral and shared by both vectors.
 
 
 def title_col(model, lang: str):
@@ -183,7 +184,13 @@ def meta_filter_conds(model, p: dict, lang: str = "en") -> list:
     gsel = split_csv(p.get("genres"))
     if gsel:
         gcol = genres_col(model, lang)
-        gc = [gcol.contains([g]) for g in gsel]
+        if lang == "hu":
+            # The HU column holds one Hungarian word per genre (plex/genres.py), so a filter saved while
+            # it offered "Action" is read as "Akció" too. The word as picked still matches as well: a row
+            # the sync has not reached since keeps its English (or Plex's mixed) list until it does.
+            gc = [or_(*(gcol.contains([w]) for w in dict.fromkeys((hu_genre(g), g)))) for g in gsel]
+        else:
+            gc = [gcol.contains([g]) for g in gsel]
         conds.append(and_(*gc) if p.get("genre_mode") == "all" else or_(*gc))
     crs = split_csv(p.get("content_ratings"))
     if crs:
@@ -209,7 +216,7 @@ def meta_filter_conds(model, p: dict, lang: str = "en") -> list:
     stds = split_csv(p.get("studios"))
     if stds:  # OR
         conds.append(model.studio.in_(stds))
-    for kw in split_csv(p.get("keywords")):  # AND — TMDB keyword chips from the detail page (E5 S5)
+    for kw in split_csv(p.get("keywords")):  # AND — TMDB keyword chips from the detail page
         conds.append(model.keywords.contains([kw]))
     csel = split_csv(p.get("collections"))
     if (
@@ -225,7 +232,7 @@ def apply_meta_filters(q, model, p: dict, lang: str = "en"):
     return q.where(*conds) if conds else q
 
 
-# --- Playback-class filter (E7) — MOVIE-ONLY (a show is an aggregate with no single class) ---------
+# --- Playback-class filter — MOVIE-ONLY (a show is an aggregate with no single class) ---------
 # The 4 classes the feed filter + facet expose, derived from the stored `playable` + `transcode_hw`.
 # ONE definition (this SQL CASE) so the filter WHERE and the facet counts can't drift: `playable_conds`
 # filters on it, `facets` groups by it. transcode_hw IS NOT True groups NULL (unprobed) with software.
@@ -271,7 +278,7 @@ class LibraryFilters:
     actors: str | None = None
     actor_mode: str = "any"  # how multiple actors combine: any (OR, default) | all (AND)
     studios: str | None = None
-    keywords: str | None = None  # TMDB keyword chips (E5 S5), CSV; language-neutral
+    keywords: str | None = None  # TMDB keyword chips, CSV; language-neutral
     collections: str | None = None  # CSV of collection rating_keys
     collection_mode: str = "any"  # how multiple collections combine: any (OR, default) | all (AND)
     playable: str | None = None  # CSV of playback classes: direct|remux|transcode_hw|transcode_sw
@@ -298,17 +305,13 @@ 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
 # watch state. The SAME predicate has to be applied in two places — `unified_library` (the grid) and
 # `facets.wsq` (so the facet counts reflect exactly the visible set) — and they MUST stay identical:
 # a hidden movie kept out of the grid must not inflate the facets either. These helpers are the one
-# home for that predicate so the two call sites can't drift (E3 S1; pinned by test_plex_facets_grid_
+# home for that predicate so the two call sites can't drift (pinned by test_plex_facets_grid_
 # parity). Callers pass the already-joined state expressions, so this module stays model-agnostic:
 #   * movies — `st` is an aliased PlexState outer-joined on (item_id, user_id).
 #   * shows  — `tot`/`wat`/`inp` are the coalesced totals from `rollup.agg_subquery`.
@@ -364,9 +367,9 @@ def apply_show_state_filter(query, tot, wat, inp, show: str):
 def content_libs(db: Session) -> tuple[list[int], list[int]]:
     """The BROWSABLE content libraries, partitioned into (movie_lib_ids, show_lib_ids) — the single
     source of the browse scope. Excludes HU overlay libraries (`overlay_of` set): those are never
-    browsed on their own, they only lend their Hungarian metadata to the EN twin's rows (E5 S5).
+    browsed on their own, they only lend their Hungarian metadata to the EN twin's rows.
 
-    Lives here, in the query layer, rather than in `routes/plex/_shared.py` where it started: E24's
+    Lives here, in the query layer, rather than in `routes/plex/_shared.py` where it started: the
     Home surface needs the same scope, and a domain package importing from `routes/` would invert the
     one-way dependency CLAUDE.md draws. It never touched request state, so nothing was lost by the
     move."""

backend/app/plex/rollup.py

@@ -13,10 +13,10 @@ from app.models import PlexItem, PlexState
 # Sort sentinel for a rail row whose timestamp is missing, so `key=lambda r: r[0] or NO_TS` reads the
 # same at every rail that merges two type-homogeneous lists in Python.
 #
-# It is NOT a crash fix, whatever the E24 commit that introduced it says. The `(ts is not None, ts)`
+# It is NOT a crash fix, whatever the commit that introduced it says. The `(ts is not None, ts)`
 # key it replaced cannot raise: tuple comparison finds the first UNEQUAL element via `==`, so two
 # `(False, None)` keys compare equal and `None < None` is never reached — verified by execution
-# during the E24 epic-end review, over every permutation of null/non-null rows. What the sentinel
+# during a review, over every permutation of null/non-null rows. What the sentinel
 # buys is one idiom instead of two, and a key that says "missing sorts last" outright rather than
 # encoding it in a boolean flag. A BARE `r[0]` would genuinely raise, which is the mutation the
 # rails' tests do guard against.
@@ -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

@@ -15,10 +15,9 @@ HLS muxer does the segmentation (the only reliable way to cut a stream-copy at k
 
 Sessions live in this (single) API process; a periodic reaper kills idle ones and frees the temp
 segments. The remux is CPU-light (video copy + a tiny audio transcode), so it runs fine on the
-CPU-only prod host; only P3's full transcode is CPU-heavy.
+CPU-only prod host; only the 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
-        # 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,
+        # 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.
+        # 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]:
@@ -231,8 +245,19 @@ def _probe_video_kind(src: Path) -> str:
             capture_output=True,
             text=True,
             timeout=10,
+            # A non-zero exit is a failed probe (CalledProcessError, a SubprocessError → the branch
+            # below), not an answer: whatever it printed before refusing is not the file's truth.
+            check=True,
+        )
+    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__),
         )
-    except (subprocess.SubprocessError, OSError):
         return _VK_HWSAFE
     pix_fmt = bits = transfer = ""
     for line in out.stdout.splitlines():
@@ -261,7 +286,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
 
 
@@ -381,7 +413,7 @@ def _venc_opts(
 def _render_node_present() -> bool:
     """Whether the VAAPI render node is available — i.e. `/dev/dri` was passed into the container.
     Present on prod after the iGPU enablement; absent on the CPU-only dev box and in the localdev
-    Docker. Its own function so the selection is monkeypatchable in tests and one place for S1c's knob."""
+    Docker. Its own function so the selection is monkeypatchable in tests and the one place to change it."""
     return Path(_VAAPI_DEVICE).exists()
 
 
@@ -404,7 +436,7 @@ def _select_encode(db: DbSession, item: PlexItem, transcode: bool, src: Path) ->
     source that has an OpenCL runtime, while a 10-bit SDR source drops to software."""
     if not transcode:
         return (False, False)
-    mode = (sysconfig.get_str(db, "plex_transcode_hw") or "auto").lower()
+    mode = sysconfig.get_str(db, "plex_transcode_hw")
     if mode == "off" or not _render_node_present():
         return (False, False)
     if mode == "on":
@@ -447,6 +479,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
 
@@ -471,9 +505,19 @@ def _probe_audio_langs(src: Path) -> list[str]:
             capture_output=True,
             text=True,
             timeout=10,
+            # A non-zero exit is a failed probe (CalledProcessError, a SubprocessError → the branch
+            # below), not an answer: whatever it printed before refusing is not the file's truth.
+            check=True,
         )
         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 []
 
 
@@ -532,7 +576,7 @@ def _ffmpeg_cmd(
                 entry += ",default:yes"
             var.append(entry)
         # The name patterns come from the vocabulary functions, with ffmpeg's own placeholders passed
-        # through them — so the producer and the parser cannot spell the layout differently (round 7).
+        # through them — so the producer and the parser cannot spell the layout differently.
         args += _HLS_TAIL + [
             "-master_pl_name",
             _MASTER_PL,
@@ -577,13 +621,22 @@ def _probe_first_pts(seg: Path) -> float | None:
             capture_output=True,
             text=True,
             timeout=10,
+            # A non-zero exit is a failed probe (CalledProcessError, a SubprocessError → the branch
+            # below), not an answer: whatever it printed before refusing is not the file's truth.
+            check=True,
         )
         for line in out.stdout.splitlines():
             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 +645,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 +720,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 +733,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)
@@ -657,14 +744,14 @@ def start_session(
         # `replace_only` makes the supersede identity-aware for the runtime fallback: the whole
         # check-and-replace happens under ONE _lock, so a newer same-key session (a concurrent
         # seek-restart) installed between the fallback's decision and here is never clobbered. When the
-        # registered session is no longer `replace_only`, we abort and return None (the caller yields to
-        # whoever is registered now). The INITIAL spawn passes replace_only=None and always supersedes —
-        # that is the seek-restart's intended last-writer-wins.
+        # registered session is no longer `replace_only`, we abort and return None, and the caller
+        # answers with its own dead session — never the newer one, whose id a stale requester would
+        # stop. The INITIAL spawn never gets None — see its call site.
         # Software-fallback encode tuning — read only on the SW transcode path (the VAAPI path and
         # remux ignore preset/crf/max_height, and remux must not touch the DB for them).
         preset, crf, max_height = "veryfast", 20, 0
         if transcode and not hw:
-            preset = sysconfig.get_str(db, "plex_transcode_preset") or "veryfast"
+            preset = sysconfig.get_str(db, "plex_transcode_preset")
             crf = sysconfig.get_int(db, "plex_transcode_crf")
             max_height = sysconfig.get_int(db, "plex_transcode_max_height")
         # Nice the SOFTWARE transcode child (not the HW path, and not remux) so a CPU-bound re-encode
@@ -672,9 +759,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,14 +795,35 @@ 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))
+    assert s is not None  # replace_only=None always supersedes: a seek-restart's last-writer-wins
     # Wait for the first video segment outside the lock (this blocks on ffmpeg, and we must not hold up
     # other sessions). Pass the proc so a HW session that dies at VAAPI init fails fast (not after 25s).
     ready = wait_for(_seg(0), timeout=25.0, proc=s.proc)
@@ -728,16 +836,18 @@ 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:
-            # Superseded/culled mid-fallback — yield whoever is registered now (a newer seek-restart), or
-            # our own now-dead session if the key was cap-culled. Never None here: the POST /session route
-            # 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
+            # Superseded/culled mid-fallback — answer with our own now-dead session. Never the newer one
+            # registered meanwhile: this answer goes to the request that LOST, whose player drops it as
+            # stale and stops the session it names (`stop_session`), which stopped the playback that won.
+            # Never None either: the POST /session route 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 s
         s = respawned
         ready = wait_for(_seg(0), timeout=25.0, proc=s.proc)
     if ready:
@@ -768,9 +878,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
@@ -779,7 +889,7 @@ def current_session(key: str) -> HlsSession | None:
 # The names ffmpeg writes into a session directory, in ONE place — and "one place" means the argv
 # BUILDS its patterns from these same functions (`segment_name("%d", "%v")`), not that a comment
 # says so. Getting this wrong is invisible in both directions: a name we failed to anticipate used
-# to fall back to "wait and see" (round 6's HIGH), and now that the rule is positive it falls back
+# to fall back to "wait and see", and now that the rule is positive it falls back
 # to a 404 instead — so the producer and the parser have to be literally the same spelling.
 #
 # MEASURED (ffmpeg 7.1.5 in the API container — the binary that actually writes these files — and
@@ -793,7 +903,7 @@ def current_session(key: str) -> HlsSession | None:
 # SESSION and not to HLS in general: a single-audio session can never write `master.m3u8`,
 # `stream_*.m3u8` or any `seg_<variant>_<n>.ts`, and a multi-audio one can never write `index.m3u8`
 # or `seg_<n>.ts`. Accepting the union meant a hopeless name of the other shape was waited out for
-# the full playlist/segment timeout — the threadpool parking this guard exists to end (round 7).
+# the full playlist/segment timeout — the threadpool parking this guard exists to end.
 _MASTER_PL = "master.m3u8"
 _INDEX_PL = "index.m3u8"
 _SEG_NAME_RE = re.compile(r"^seg_(?:([0-9a-z]{1,4})_)?(\d{1,9})\.ts$")
@@ -845,12 +955,12 @@ def artifact_may_arrive(s: "HlsSession", filename: str) -> bool:
     name belonging to the other shape is as hopeless here as a random string. Reading those as "an
     HLS name, so wait and see" left the whole class reachable — measured through the real route
     against a live single-audio session, `master.m3u8` and `stream_q7z.m3u8` were 404s after 30.0 s
-    and `seg_a0_0.ts` / `seg_zzzz_0.ts` after 20.1 s each (deep-review round 7).
+    and `seg_a0_0.ts` / `seg_zzzz_0.ts` after 20.1 s each.
 
     Saying no at once matters because the route that waits is a SYNC one: it holds a thread off the
     ~40-slot pool, and a pooled DB connection with it, for the whole timeout. An ordinary seek past
     the produced region was enough to park one for 20 s, and forty concurrent requests for a name
-    that will never exist parked the whole API (deep-review round 5). Round 5's guard read only
+    that will never exist parked the whole API. An earlier guard read only
     single-audio segment names, so both halves of that were still fully reachable: every multi-audio
     name fell through, and so did any `.m3u8`/`.vtt` name at all."""
     if filename in playlist_names(s.variants):
@@ -867,7 +977,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 +1010,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 +1052,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 +1071,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()):
@@ -954,35 +1095,52 @@ def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
     A finished session is also what a PAUSED viewer has: a remux runs far faster than realtime, so
     ffmpeg is done a minute or two in and writes ENDLIST; hls.js then stops asking for the playlist,
     and with its forward buffer full a paused player fetches nothing at all. With the 30 s rule that
-    killed a one-minute pause, and playback died ~30 s after resuming (deep-review round 4).
+    killed a one-minute pause, and playback died ~30 s after resuming.
 
     What makes the short rule safe again is that fetching is no longer the only signal: a player
     parked MID-ITEM checkpoints its position every 10 s, and that route calls `touch_session`, so a
-    viewer who is merely paused says so far more often than this rule asks (round 5). The heartbeat
+    viewer who is merely paused says so far more often than this rule asks. The heartbeat
     stops once the item is finished or before a position is known (`usePlexProgress.flush`) — both
     states where reaping is correct, and where the player's 404 → reclaim recovers a viewer who
-    scrubs back in anyway. Do not restate this as "every 10 s whether or not it is playing": round 6
-    found that claim in two comments and not in the code. Round 4's blanket
+    scrubs back in anyway. Do not restate this as "every 10 s whether or not it is playing":
+    a review found that claim in two comments and not in the code. An earlier blanket
     `reap_abandoned` bought the same safety by keeping every finished session for ten minutes — each
     one a whole segmented copy of the film on a volume shared with the download center."""
     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 stop_session(user_id: int, key: str, session_id: str) -> bool:
+    """Stop this viewer's session for `key` now, because the player that asked for it is gone (left
+    the item, closed, unloaded the page). Left to `reap_idle`, a transcode ran on to the end of the
+    film first — measured: ~4 cores for a minute after leaving a resumed 480p film.
+
+    Only while `session_id` is still the registered one: the player names the session it played, and
+    a seek-restart or a second tab may have replaced it meanwhile — that newer session is somebody's
+    current playback, not this request's to end."""
+    with _lock:
+        s = _sessions.get((user_id, key))
+        if s is None or s.id != session_id:
+            return False
+        _kill(s)
+        _sessions.pop((user_id, key), None)
+    return True
+
+
+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

@@ -32,18 +32,20 @@ window still took the full 145 s and emitted the whole track), so windows are ex
 zero-based clock and shifted back to absolute time here with `shift_vtt`.
 """
 
+import codecs
 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 +53,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 +105,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 +123,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 +138,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)
 
 
@@ -150,7 +162,8 @@ def ffmpeg_to_vtt(src: str, sub_ord: int | None) -> str:
         "webvtt",
         "pipe:1",
     ]
-    r = subprocess.run(cmd, capture_output=True, timeout=EXTRACT_TIMEOUT_S)
+    # check=False: the exit status is read on the next line, with ffmpeg's own stderr as the reason.
+    r = subprocess.run(cmd, capture_output=True, timeout=EXTRACT_TIMEOUT_S, check=False)
     if r.returncode != 0 or not r.stdout:
         raise PlexError(
             (r.stderr or b"").decode("utf-8", "replace")[:200] or "ffmpeg subtitle convert failed"
@@ -162,7 +175,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 +196,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
 
 
@@ -189,7 +219,11 @@ _FULL_END_S = 1_000_000_000.0  # stand-in for "to the end of the file" (JSON can
 
 
 def cache_key(rating_key: str, sub_ord: int) -> str:
-    return f"sub_{rating_key}_{sub_ord}"
+    # Versioned whenever `decode_subtitle` changes what a track decodes to — `sub2_` when legacy code
+    # pages were cached as U+FFFD, `sub3_` when a stray byte, an untagged file or Serbian still went
+    # to the wrong code page. The cache has no eviction, so every track is read again once rather
+    # than a broken one being served for good; the older files are just left behind.
+    return f"sub3_{rating_key}_{sub_ord}"
 
 
 def _vtt_path(key: str) -> Path:
@@ -206,7 +240,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 +260,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 +272,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 +291,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 +325,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 +364,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 +381,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 +467,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 +528,7 @@ def reset_state() -> None:
     global _STOPPING
     with _LOCK:
         _INFLIGHT.clear()
+        _FULL_OWNERS.clear()
         _FAILURES.clear()
         _FULL_FAILED.clear()
         _WIN_FAILED.clear()
@@ -531,7 +612,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 +655,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 +688,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 +726,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 +760,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 +798,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 +865,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,15 +892,108 @@ 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}"))
+
+
+# The legacy code page a subtitle in this language (Plex's ISO 639-2 `languageCode`) was most likely
+# saved in. Serbian sits here, not with Cyrillic: its releases are overwhelmingly Latin script in
+# Windows-1250, like Croatian and Bosnian.
+_CP1250 = {
+    "hun",
+    "ces",
+    "cze",
+    "pol",
+    "slk",
+    "slo",
+    "slv",
+    "hrv",
+    "bos",
+    "srp",
+    "ron",
+    "rum",
+    "sqi",
+    "alb",
+}
+_CP1251 = {"rus", "ukr", "bel", "bul", "mkd", "mac"}
+# Western European languages keep Windows-1252 (cp1250 has no à/è/ñ). An UNTAGGED file falls to
+# Windows-1250: its ASCII and á/é/í/ó/ö/ú/ü match Windows-1252 byte for byte, and it also gets ő/ű
+# right, which Windows-1252 turns into õ/û — the library this reads is mostly Hungarian.
+_CP1252 = {
+    "eng",
+    "fre",
+    "fra",
+    "ger",
+    "deu",
+    "spa",
+    "ita",
+    "por",
+    "dut",
+    "nld",
+    "swe",
+    "dan",
+    "nor",
+    "fin",
+    "ice",
+    "isl",
+    "cat",
+}
+# A file that is almost all valid UTF-8 is UTF-8 with a few stray bytes (a pasted Windows-1252 quote),
+# not a legacy file: accents in a legacy code page are nearly never valid UTF-8 sequences, so a real
+# legacy file has hardly any. At least this many valid multi-byte characters per invalid byte.
+_UTF8_VALID_PER_STRAY = 10
+
+
+def decode_subtitle(raw: bytes, language_code: str | None) -> str:
+    """A sidecar subtitle file as text. SubRip carries no charset, and a Hungarian release is
+    typically Windows-1250: decoded as UTF-8 with `replace`, every ő/ű/é came out as U+FFFD (found
+    live, 1391 of them in one episode). So: a BOM decides; else valid UTF-8 stays UTF-8 (a legacy
+    code page with accents is almost never valid UTF-8), and so does NEARLY valid UTF-8 — one stray
+    byte must not send a whole UTF-8 file to a legacy code page; else the language's legacy code page."""
+    if raw.startswith(codecs.BOM_UTF8):
+        return raw[len(codecs.BOM_UTF8) :].decode("utf-8", "replace")
+    if raw.startswith((codecs.BOM_UTF16_LE, codecs.BOM_UTF16_BE)):
+        return raw.decode("utf-16", "replace")
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        # silent-ok: not strictly UTF-8 — nearly-UTF-8 or a legacy code page, told apart below.
+        pass
+    lenient = raw.decode("utf-8", "replace")
+    stray = lenient.count("�")
+    valid = sum(1 for ch in lenient if ch > "" and ch != "�")
+    if valid >= stray * _UTF8_VALID_PER_STRAY:
+        return lenient
+    lang = (language_code or "").lower()
+    legacy = "cp1251" if lang in _CP1251 else "cp1252" if lang in _CP1252 else "cp1250"
+    return raw.decode(legacy, "replace")
+
+
 def _sidecar_vtt(db: Session, stream: dict) -> str:
-    """An external subtitle file, fetched through Plex and converted to WebVTT."""
+    """An external subtitle file, fetched through Plex and converted to WebVTT. Its bytes are made
+    UTF-8 first (`decode_subtitle`), on the ffmpeg path too: ffmpeg reads a text subtitle as UTF-8."""
     with PlexClient(db) as plex:
         raw = plex.raw_get(stream["key"])
+    text = decode_subtitle(raw, stream.get("languageCode"))
     codec = (stream.get("codec") or stream.get("format") or "").lower()
     if codec in ("srt", "subrip", ""):
-        return srt_to_vtt(raw.decode("utf-8", "replace"))
+        return srt_to_vtt(text)
     with tempfile.NamedTemporaryFile(suffix="." + (codec or "sub"), delete=False) as fh:
-        fh.write(raw)
+        fh.write(text.encode("utf-8"))
         tmp = fh.name
     try:
         return ffmpeg_to_vtt(tmp, None)
@@ -794,9 +1023,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 +1059,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

@@ -12,23 +12,22 @@ on a NON-empty listing — a section that returns zero items is left untouched,
 glitch that yields an empty page can't wipe a library (the metadata is cheap to re-sync; an accidental
 mass-delete is the only real risk). Library-level reconcile (dropping a whole removed section, the
 dead `enabled` column) is a separate follow-up. Cast + intro/credit markers are fetched lazily on the
-item-detail/player path (P2), not here.
+item-detail/player path, 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 import detail, overlay, people
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+from app.plex.genres import hu_genres
 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 +101,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 +114,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 +124,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 +140,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
 
@@ -144,7 +150,7 @@ _GUID_PREFERENCE = ("tmdb", "imdb", "tvdb")
 
 
 def _canonical_guid(meta: dict) -> str | None:
-    """The canonical external id used to pair an EN title with its HU-overlay twin (E5 S5). Reads the
+    """The canonical external id used to pair an EN title with its HU-overlay twin. Reads the
     `Guid` array (present only with includeGuids=1 in the listing), preferring tmdb > imdb > tvdb,
     normalised to '<provider>:<id>' (e.g. 'tmdb:12345'). None when no known provider id is present."""
     found: dict[str, str] = {}
@@ -187,20 +193,6 @@ def _enabled_section_keys(db: Session) -> set[str] | None:
     return keys or None
 
 
-def _overlay_map(db: Session) -> dict[str, str]:
-    """The configured HU-overlay pairing: {huSectionKey: enSectionKey} from `plex_overlay_map`
-    ('huKey:enKey,...'). Each HU section is synced as a non-browsable overlay onto its EN twin.
-    Malformed pairs are skipped."""
-    raw = sysconfig.get_str(db, "plex_overlay_map")
-    out: dict[str, str] = {}
-    for pair in raw.split(","):
-        hu, sep, en = pair.partition(":")
-        hu, en = hu.strip(), en.strip()
-        if sep and hu and en:
-            out[hu] = en
-    return out
-
-
 def sync(db: Session) -> dict:
     """Full reconcile of the enabled movie/show sections. Returns a small stats dict."""
     if not sysconfig.get_bool(db, "plex_enabled"):
@@ -216,7 +208,7 @@ def sync(db: Session) -> dict:
         "pruned": 0,
     }
     wanted = _enabled_section_keys(db)
-    overlay_map = _overlay_map(db)  # {huKey: enKey}
+    overlay_map = overlay.overlay_map(db)  # {huKey: enKey}
     overlay_keys = set(overlay_map)
     try:
         with PlexClient(db) as plex:
@@ -260,21 +252,25 @@ def sync(db: Session) -> dict:
                 lib.metadata_lang = "hu"
                 lib.overlay_of = en_lib.id
                 db.flush()
-                _sync_overlay(db, plex, lib, en_lib.id, stats)
+                overlay.sync_overlay(db, plex, lib, en_lib.id, stats)
                 db.commit()
             # Rich-fetch a bounded batch of not-yet-enriched titles' FULL cast, so the whole library
             # 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:  # 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:  # 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 +281,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:  # 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 +321,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 +370,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))
@@ -419,7 +418,10 @@ def _paginate(plex: PlexClient, key: str, item_type: int, progress: dict | None
     if progress is not None:
         # A truthy `total` we reached = a trustworthy complete listing. `total` unknown/zero-with-rows
         # (a Plex that doesn't report totalSize) is treated as NOT complete, so prune stays conservative.
+        # `total` itself is kept for a caller to whom a server that SAID 0 is news it can trust (the
+        # watch reconcile); an empty mirror or overlay must not read it so.
         progress["complete"] = bool(total) and start >= total
+        progress["total"] = total
 
 
 # The section listing exposes at most the top ~20 cast (Plex's own cap); a stored cast longer than this
@@ -436,12 +438,16 @@ def _apply_facet_fields(row, meta: dict) -> None:
     row.studio = (meta.get("studio") or None) and str(meta.get("studio"))[:255]
     row.originally_available_at = _date(meta.get("originallyAvailableAt"))
     row.genres = _tags(meta, "Genre")
+    # Every row has Hungarian genres, not only one with an HU overlay twin (the overlay pass, which runs
+    # after this, puts the twin's own list over it): the HU genre facets and filter read this column,
+    # and an English word there could never match a filter read in Hungarian.
+    row.genres_hu = hu_genres(row.genres)
     row.directors = _tags(meta, "Director")
     # The listing carries only the top ~20 cast, so re-applying it would DOWNGRADE an already-enriched
     # full cast (up to 24, grown by the rich backfill/info-page enrich), silently breaking the
     # person-page cast filter for names past the top ~20. The watermark gate below (`people_enriched_at
     # is None`) normally protects this, but it is NOT enough on its own: a migration that resets the
-    # watermark re-opens the regression (0065 nulled it, which is exactly how the S5b fix got undone in
+    # watermark re-opens the regression (0065 nulled it, which is exactly how a fix got undone in
     # prod). So guard STRUCTURALLY too, by LENGTH against the listing cap: a stored cast LONGER than the
     # cap can only be an enriched fuller list, so keep it (robust to any watermark reset). A stored cast
     # at or below the cap is itself listing-sourced, so take the fresh listing — which tracks Plex cast
@@ -643,59 +649,6 @@ def _sync_shows(db: Session, plex: PlexClient, lib: PlexLibrary, stats: dict) ->
     _prune_stale(db, shows, shows_seen, stats, complete=shows_progress.get("complete", False))
 
 
-def _sync_overlay(
-    db: Session, plex: PlexClient, lib: PlexLibrary, en_lib_id: int, stats: dict
-) -> None:
-    """Write an overlay section's Hungarian metadata onto its EN twin's rows, matched by guid. Creates
-    NO browsable rows — an overlay library is never listed on its own. Only title/summary/genres differ
-    by language; the language-neutral people_text feeds both search vectors.
-
-    This is a full RECONCILE: every guid-bearing EN row's HU fields are cleared first, then the HU
-    section repopulates the matches — so an EN row whose HU twin vanished (or was re-guid'd) falls back
-    to EN instead of keeping stale Hungarian metadata. HU items with no EN match are skipped."""
-    if lib.kind == "movie":
-        rows = db.execute(
-            select(PlexItem).where(
-                PlexItem.library_id == en_lib_id,
-                PlexItem.kind == "movie",
-                PlexItem.guid.is_not(None),
-            )
-        ).scalars()
-        item_type = _TYPE_MOVIE
-    else:
-        rows = db.execute(
-            select(PlexShow).where(PlexShow.library_id == en_lib_id, PlexShow.guid.is_not(None))
-        ).scalars()
-        item_type = _TYPE_SHOW
-    # guid -> the EN rows carrying it (a list: two editions of one film can share a guid; both overlay).
-    by_guid: dict[str, list] = {}
-    for r in rows:
-        by_guid.setdefault(r.guid, []).append(r)
-    # Reconcile step: clear HU fields on all guid-bearing rows. Only rows that actually held HU data
-    # become dirty (SQLAlchemy skips a no-net-change UPDATE), so this is cheap; matches are re-set below.
-    for group in by_guid.values():
-        for row in group:
-            row.title_hu = row.summary_hu = row.genres_hu = None
-    seen: set[str] = (
-        set()
-    )  # first HU entry for a guid wins; a dup HU item can't overwrite or double-count
-    for meta in _paginate(plex, lib.plex_key, item_type):
-        g = _canonical_guid(meta)
-        targets = by_guid.get(g) if g else None
-        if not targets or g in seen:
-            continue
-        seen.add(g)
-        title_hu = (meta.get("title") or "").strip() or None
-        summary_hu = meta.get("summary")
-        genres_hu = _tags(meta, "Genre")
-        for row in targets:
-            row.title_hu = title_hu
-            row.summary_hu = summary_hu
-            row.genres_hu = genres_hu
-        stats["overlaid"] = stats.get("overlaid", 0) + 1
-    db.flush()
-
-
 def _upsert_collection(
     db: Session, existing: PlexCollection | None, rk: str, lib_id: int, meta: dict
 ) -> PlexCollection:
@@ -721,9 +674,11 @@ def resync_collection(db: Session, plex: PlexClient, lib: PlexLibrary, rk: str)
     meta = plex.metadata(rk) or {}
     col = _upsert_collection(db, by_rating_key(db, PlexCollection, rk), rk, lib.id, meta)
     Model = PlexItem if lib.kind == "movie" else PlexShow
-    new_members = {
-        str(c.get("ratingKey")) for c in plex.collection_children(rk) if c.get("ratingKey")
-    }
+    children = _believed_children(plex, rk, meta)
+    if children is None:
+        db.flush()
+        return col
+    new_members = {str(c.get("ratingKey")) for c in children if c.get("ratingKey")}
     current = db.execute(select(Model).where(Model.collection_keys.contains([rk]))).scalars().all()
     for row in current:  # drop rk from rows that are no longer members
         if row.rating_key not in new_members:
@@ -736,6 +691,22 @@ def resync_collection(db: Session, plex: PlexClient, lib: PlexLibrary, rk: str)
     return col
 
 
+def _believed_children(plex: PlexClient, rk: str, meta: dict) -> list[dict] | None:
+    """A collection's members, or None when the answer is not believed: no members from a collection
+    whose own listing counts some (`childCount`) is a glitch, not a collection emptied — the same
+    empty-answer rule as the collection listing's. Rebuilding on it showed the
+    collection empty until the next sync."""
+    children = plex.collection_children(rk)
+    count = str(meta.get("childCount") or "0")
+    if children or not count.isdigit() or int(count) == 0:
+        return children
+    log.warning(
+        "Plex listed no members for a non-empty collection; keeping its membership",
+        extra=logs.event("plex.sync.collection_children_empty", collection=rk),
+    )
+    return None
+
+
 def delete_collection_local(db: Session, lib: PlexLibrary, rk: str) -> None:
     """Local cleanup after a collection is deleted from Plex: strip rk from members + drop the row."""
     Model = PlexItem if lib.kind == "movie" else PlexShow
@@ -747,6 +718,19 @@ def delete_collection_local(db: Session, lib: PlexLibrary, rk: str) -> None:
     db.flush()
 
 
+def _rebuild_membership(
+    db: Session, lib: PlexLibrary, membership: dict[str, list[str]], kept: set[str]
+) -> None:
+    """Rebuild collection_keys on every member row of this library (clear + set), carrying over the
+    keys of a collection whose empty answer was not believed (`_believed_children`)."""
+    for Model in (PlexItem, PlexShow):
+        for row in db.execute(select(Model).where(Model.library_id == lib.id)).scalars():
+            held = [k for k in (row.collection_keys or []) if k in kept]
+            keys = [*membership.get(row.rating_key, []), *held]
+            row.collection_keys = list(dict.fromkeys(keys)) or None
+    db.flush()
+
+
 def _sync_collections(db: Session, plex: PlexClient, lib: PlexLibrary, stats: dict) -> None:
     """Mirror a library's collections + membership. Reads never touch Plex afterwards. Membership is
     written as `collection_keys` on member movies (plex_items) / shows (plex_shows). A full reconcile:
@@ -758,7 +742,17 @@ def _sync_collections(db: Session, plex: PlexClient, lib: PlexLibrary, stats: di
             select(PlexCollection).where(PlexCollection.library_id == lib.id)
         ).scalars()
     }
+    if not cols and existing:
+        # The catalog's own rule (see the module doc): an empty listing while we hold rows is a Plex
+        # glitch, not a library emptied of collections. Reconciling on it dropped every collection
+        # (its user-set `editable` flag with it) and every member's keys.
+        log.warning(
+            "Plex listed no collections for a library that has some; keeping them this run",
+            extra=logs.event("plex.sync.collections_empty", library=lib.plex_key),
+        )
+        return
     seen: set[str] = set()
+    kept: set[str] = set()  # collections whose empty children answer is not believed
     membership: dict[str, list[str]] = {}  # member rating_key -> [collection rating_key, ...]
     for meta in cols:
         rk = str(meta.get("ratingKey") or "")
@@ -766,7 +760,10 @@ def _sync_collections(db: Session, plex: PlexClient, lib: PlexLibrary, stats: di
             continue
         _upsert_collection(db, existing.get(rk), rk, lib.id, meta)
         seen.add(rk)
-        for child in plex.collection_children(rk):
+        children = _believed_children(plex, rk, meta)
+        if children is None:
+            kept.add(rk)
+        for child in children or []:
             crk = str(child.get("ratingKey") or "")
             if crk:
                 membership.setdefault(crk, []).append(rk)
@@ -775,9 +772,4 @@ def _sync_collections(db: Session, plex: PlexClient, lib: PlexLibrary, stats: di
     for rk, col in existing.items():
         if rk not in seen:
             db.delete(col)
-    # Rebuild collection_keys on every member row of this library (clear + set).
-    for row in db.execute(select(PlexItem).where(PlexItem.library_id == lib.id)).scalars():
-        row.collection_keys = membership.get(row.rating_key) or None
-    for row in db.execute(select(PlexShow).where(PlexShow.library_id == lib.id)).scalars():
-        row.collection_keys = membership.get(row.rating_key) or None
-    db.flush()
+    _rebuild_membership(db, lib, membership, kept)

backend/app/plex/tmdb.py

@@ -1,4 +1,4 @@
-"""TMDB enrichment for the mirrored Plex catalog (E5 S2).
+"""TMDB enrichment for the mirrored Plex catalog.
 
 A thin synchronous TMDB v3 client plus the parse/persist of the enrichment fields onto plex_items /
 plex_shows, matched by the stored canonical `guid` ("tmdb:12345", or imdb/tvdb resolved via /find).
@@ -10,21 +10,23 @@ 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 re
 import time
 from datetime import datetime, timezone
+from typing import cast
 
 import httpx
 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
+from app.plex.cards import display_title
+from app.plex.people import people_by_credits, warm_portraits
 
-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
 
@@ -126,9 +128,17 @@ class TmdbClient:
         """Resolve an external id (imdb_id / tvdb_id) to TMDB items via /find."""
         return self._get(f"/find/{external_id}", {"external_source": source})
 
+    def countries(self) -> list[dict] | None:
+        """TMDB's country list: `[{iso_3166_1, english_name, native_name}]` (a JSON array, which
+        `_get`'s dict annotation does not describe)."""
+        return cast("list[dict] | None", self._get("/configuration/countries"))
+
     def fetch_person(self, person_id: int) -> dict | None:
-        """One person's bio + combined credits (E5 S6), in a single append_to_response request."""
-        return self._get(f"/person/{person_id}", {"append_to_response": "combined_credits"})
+        """One person's bio + combined credits + the bio's translations, in a single
+        append_to_response request."""
+        return self._get(
+            f"/person/{person_id}", {"append_to_response": "combined_credits,translations"}
+        )
 
 
 def guid_to_tmdb_id(guid: str | None, media_type: str, tmdb: TmdbClient) -> int | None:
@@ -142,6 +152,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:
@@ -210,7 +226,7 @@ def parse_tmdb(payload: dict, media_type: str) -> dict:
     crew.sort(key=lambda c: priority.get(c["job"], 99))
     crew = crew[:12]
 
-    # name -> tmdb person id, for the plex_people foundation (S6 fetches bios off these ids).
+    # name -> tmdb person id, for the plex_people foundation (bios are fetched off these ids).
     people: list[dict] = []
     for c in (credits.get("cast") or [])[:30]:
         if c.get("name") and c.get("id"):
@@ -250,8 +266,12 @@ def parse_tmdb(payload: dict, media_type: str) -> dict:
             c.get("name") for c in (payload.get("production_companies") or []) if c.get("name")
         ][:8]
         or None,
+        # The ISO code beside TMDB's English name: the client names the country in the reader's
+        # language from the code; the name is the fallback for a code it cannot name.
         "production_countries": [
-            c.get("name") for c in (payload.get("production_countries") or []) if c.get("name")
+            {"code": c.get("iso_3166_1") or None, "name": c["name"]}
+            for c in (payload.get("production_countries") or [])
+            if c.get("name")
         ]
         or None,
         "recommendations": recs or None,
@@ -297,8 +317,8 @@ def _link_people(db: Session, links: dict[str, int]) -> None:
 
 
 def enrich_batch(db: Session, tmdb: TmdbClient, limit: int) -> int:
-    """Enrich up to `limit` not-yet-TMDB-enriched titles (movies first, shows fill the remainder —
-    mirrors _enrich_people_batch). A transient TmdbError leaves the watermark NULL for retry; a
+    """Enrich up to `limit` not-yet-TMDB-enriched titles (movies first, shows fill the
+    remainder). A transient TmdbError leaves the watermark NULL for retry; a
     definitive no-match (unresolvable guid / TMDB 404) still stamps the watermark so it isn't re-fetched
     every run. One commit at the end. Returns the number processed (matched OR definitively unmatched)."""
     movies = (
@@ -352,13 +372,62 @@ def enrich_batch(db: Session, tmdb: TmdbClient, limit: int) -> int:
     return processed
 
 
+def _country(c: dict | str) -> dict:
+    """One stored production country as served: `{code, name}`. An older row stored the
+    bare English name; until `backfill_country_codes` reaches it, it serves with no code (the client
+    shows the name)."""
+    return c if isinstance(c, dict) else {"code": None, "name": c}
+
+
+def backfill_country_codes(db: Session, tmdb: TmdbClient) -> int:
+    """Give the older countries (bare English names) their ISO codes, from TMDB's own
+    country list — the names came from that list, so they match it exactly. One request, and only
+    while such a row is left: re-fetching each title instead would take the enrichment batch days.
+    A name the list does not hold keeps no code. Returns the number of rows rewritten."""
+    stale = [
+        row
+        for model in (PlexItem, PlexShow)
+        for row in db.execute(
+            select(model).where(func.jsonb_typeof(model.production_countries[0]) == "string")
+        ).scalars()
+    ]
+    if not stale:
+        return 0
+    codes = {
+        c["english_name"]: c["iso_3166_1"]
+        for c in tmdb.countries() or []
+        if c.get("english_name") and c.get("iso_3166_1")
+    }
+    for row in stale:
+        row.production_countries = [
+            {"code": codes.get(c), "name": c} if isinstance(c, str) else c
+            for c in row.production_countries or []
+        ]
+    db.commit()
+    return len(stale)
+
+
 def run_enrich(db: Session) -> dict:
     """Scheduler entry point. No-op (never an error) when the TMDB key isn't configured."""
     if not sysconfig.get_str(db, "tmdb_api_key"):
         return {"enriched": 0, "skipped": "tmdb_api_key not set"}
     with TmdbClient(db) as tmdb:
+        coded = backfill_country_codes(db, tmdb)
         n = enrich_batch(db, tmdb, settings.tmdb_enrich_batch)
-    return {"enriched": n}
+    return {"enriched": n, **({"countries_coded": coded} if coded else {})}
+
+
+def run_people_enrich(db: Session) -> dict:
+    """Scheduler entry point of people_enrich: a batch of person bios (the most-credited
+    first) and a batch of portraits. Each half is a no-op — never an error — without its TMDB key /
+    without Plex."""
+    batch = settings.people_enrich_batch
+    if sysconfig.get_str(db, "tmdb_api_key"):
+        with TmdbClient(db) as tmdb:
+            bios = enrich_people_batch(db, tmdb, batch)
+    else:
+        bios = {"skipped": "tmdb_api_key not set"}
+    return {"bios": bios, "portraits": warm_portraits(db, batch)}
 
 
 def resolve_library_guids(
@@ -402,10 +471,11 @@ def resolve_library_guids(
     return movies, shows
 
 
-def resolve_recs(db: Session, recs: list[dict] | None) -> list[dict]:
+def resolve_recs(db: Session, recs: list[dict] | None, *, lang: str) -> list[dict]:
     """Tag each recommendation with whether it's in OUR library (matched by guid `tmdb:<id>`, bucketed
     by media_type — see resolve_library_guids) and, if so, its rating_key — so the client can deep-link
-    the ones we have and merely display the rest."""
+    the ones we have and merely display the rest. One we have is named as the library names it, in
+    `lang`; one we lack keeps the title TMDB gave."""
     if not recs:
         return []
     movies, shows = resolve_library_guids(db, recs)
@@ -413,13 +483,19 @@ def resolve_recs(db: Session, recs: list[dict] | None) -> list[dict]:
     for r in recs:
         g = f"tmdb:{r.get('tmdb_id')}"
         row = shows.get(g) if r.get("media_type") == "tv" else movies.get(g)
+        named = {"title": display_title(row, lang)} if row is not None else {}
         out.append(
-            {**r, "in_library": row is not None, "rating_key": row.rating_key if row else None}
+            {
+                **r,
+                **named,
+                "in_library": row is not None,
+                "rating_key": row.rating_key if row else None,
+            }
         )
     return out
 
 
-def serve_block(db: Session, row) -> dict | None:
+def serve_block(db: Session, row, *, lang: str) -> dict | None:
     """The TMDB extras for a movie/show detail response, served from the row (no live TMDB call).
     None until the row has been TMDB-enriched (the client then shows nothing extra)."""
     if row.tmdb_enriched_at is None:
@@ -433,30 +509,58 @@ def serve_block(db: Session, row) -> dict | None:
         "keywords": row.keywords or [],
         "crew": row.crew or [],
         "studios": row.studios or [],
-        "production_countries": row.production_countries or [],
-        "recommendations": resolve_recs(db, row.recommendations),
+        "production_countries": [_country(c) for c in row.production_countries or []],
+        "recommendations": resolve_recs(db, row.recommendations, lang=lang),
         "backdrops": row.backdrops or [],
     }
 
 
-# --- Person enrichment (E5 S6) -------------------------------------------------------------------
-# A person's bio + birth facts + a "Known for" credit pool, fetched once (the first person-page open)
-# and served from the plex_people row. `known_for` stores the top combined-credits ids; the person
+# --- Person enrichment -------------------------------------------------------------------
+# A person's bio + birth facts + a "Known for" credit pool, fetched once — by the people_enrich job, or
+# by the first person-page open if the job has not reached them yet — and served from the plex_people row. `known_for` stores the top combined-credits ids; the person
 # endpoint resolves them to library rows by guid at serve time (like recommendations).
 
-_KNOWN_FOR_MAX = 15
+# The candidate pool kept per person. Only the titles that are in the library are shown (at most
+# routes.plex.people._KNOWN_FOR_SHOWN), so the pool is deeper than the rail: a star's 15 most-voted
+# credits are often not the 15 a given library holds.
+_KNOWN_FOR_MAX = 40
+# TMDB genre ids of the shows a person visits as a guest (News, Reality, Talk). Ranked by popularity,
+# talk-show visits crowded out the films (Tom Cruise: 14 of 15 were talk shows).
+_GUEST_GENRES = {10763, 10764, 10767}
+# A credit in which the person plays themselves ("Self", "Himself - Guest", "Herself (archive footage)").
+_SELF_CREDIT = re.compile(r"^\s*(self|himself|herself|themselves)\b", re.IGNORECASE)
+# The crew jobs that make a title the person's own work (a director is known for what they directed).
+_KNOWN_FOR_CREW_JOBS = {"Director", "Creator"}
+
+
+def _known_for_credit(c: dict, crew: bool) -> bool:
+    if crew:
+        return c.get("job") in _KNOWN_FOR_CREW_JOBS
+    if _SELF_CREDIT.match(c.get("character") or ""):
+        return False
+    return not _GUEST_GENRES.intersection(c.get("genre_ids") or [])
 
 
 def parse_person(payload: dict) -> dict:
     """TMDB /person/{id} (+combined_credits) → the persisted bio fields. `known_for` = the person's
-    most-popular movie/tv credits (deduped by id), top `_KNOWN_FOR_MAX`, resolved to library later."""
-    credits = (payload.get("combined_credits") or {}).get("cast") or []
+    most-voted movie/tv credits — roles and directed works, not guest visits as themselves — deduped,
+    the top `_KNOWN_FOR_MAX`, resolved to library rows at serve time. Ranked by vote count, as TMDB's
+    own "Known for" is: popularity is this week's attention, which a talk-show visit wins."""
+    combined = payload.get("combined_credits") or {}
+    credits = [c for c in combined.get("cast") or [] if _known_for_credit(c, crew=False)] + [
+        c for c in combined.get("crew") or [] if _known_for_credit(c, crew=True)
+    ]
     # Dedup on (id, media_type), not the bare id: TMDB movie ids and tv ids are independent sequences
     # (id 603 can be both a movie and a show — see resolve_library_guids), so a same-id movie+show pair
     # is two distinct credits and both must survive.
     seen: set[tuple[int, str]] = set()
     known: list[dict] = []
-    for c in sorted(credits, key=lambda c: c.get("popularity") or 0, reverse=True):
+    ranked = sorted(
+        credits,
+        key=lambda c: (c.get("vote_count") or 0, c.get("popularity") or 0),
+        reverse=True,
+    )
+    for c in ranked:
         tid, mt = c.get("id"), c.get("media_type")
         if not tid or mt not in ("movie", "tv") or (tid, mt) in seen:
             continue
@@ -466,6 +570,7 @@ def parse_person(payload: dict) -> dict:
             break
     return {
         "biography": (payload.get("biography") or "").strip() or None,
+        "biography_hu": _translated_bio(payload, "hu"),
         "birthday": payload.get("birthday") or None,
         "deathday": payload.get("deathday") or None,
         "place_of_birth": payload.get("place_of_birth") or None,
@@ -475,8 +580,17 @@ def parse_person(payload: dict) -> dict:
     }
 
 
+def _translated_bio(payload: dict, lang: str) -> str | None:
+    """The `lang` biography from the appended `translations` (TMDB leaves an untranslated one blank)."""
+    for tr in (payload.get("translations") or {}).get("translations") or []:
+        if tr.get("iso_639_1") == lang:
+            return ((tr.get("data") or {}).get("biography") or "").strip() or None
+    return None
+
+
 def apply_person(row: PlexPerson, parsed: dict) -> None:
     row.biography = parsed["biography"]
+    row.biography_hu = parsed["biography_hu"]
     row.birthday = parsed["birthday"]
     row.deathday = parsed["deathday"]
     row.place_of_birth = parsed["place_of_birth"]
@@ -486,11 +600,22 @@ def apply_person(row: PlexPerson, parsed: dict) -> None:
     row.tmdb_enriched_at = datetime.now(timezone.utc)
 
 
+def _fetch_person_into(tmdb: TmdbClient, person: PlexPerson) -> None:
+    """Fetch one person from TMDB and write the row (not committed). A 404 (deleted person) stamps the
+    watermark with empty fields so it isn't fetched again. Raises TmdbError on a transient failure,
+    leaving the row untouched and `tmdb_enriched_at` NULL for a retry."""
+    payload = tmdb.fetch_person(cast(int, person.tmdb_person_id))
+    if payload is None:
+        person.tmdb_enriched_at = datetime.now(timezone.utc)
+    else:
+        apply_person(person, parse_person(payload))
+
+
 def enrich_person(db: Session, person: PlexPerson) -> bool:
-    """Lazily fetch + persist one person's TMDB bio (first person-page open), committing the write so it
-    survives regardless of the read path. No-op (False) without a key or a `tmdb_person_id`; a transient
-    error leaves `tmdb_enriched_at` NULL so the next open retries. A 404 (deleted person) stamps the
-    watermark with empty fields so we don't refetch it every open."""
+    """Lazily fetch + persist one person's TMDB bio (a person page opened before the background job
+    reached them), committing the write so it survives regardless of the read path. No-op (False)
+    without a key or a `tmdb_person_id`; a transient error leaves `tmdb_enriched_at` NULL so the next
+    open retries."""
     if not person.tmdb_person_id or not sysconfig.get_str(db, "tmdb_api_key"):
         return False
     try:
@@ -498,12 +623,54 @@ def enrich_person(db: Session, person: PlexPerson) -> bool:
         # longer blocks a serve; still cap the outbound TMDB call with a short timeout so a hanging TMDB
         # 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:
+            _fetch_person_into(tmdb, person)
+    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)
-    else:
-        apply_person(person, parse_person(payload))
     db.commit()
     return True
+
+
+# Lookups failing this many people in a row end a people batch: TMDB itself is degraded, and hammering
+# it helps nobody. One person failing alone is skipped, so an id TMDB keeps refusing never stalls the rest.
+_PEOPLE_FAILS_IN_A_ROW = 3
+
+
+def enrich_people_batch(db: Session, tmdb: TmdbClient, limit: int) -> dict:
+    """Fetch up to `limit` linked, not-yet-enriched people, the most-credited first, so a
+    person page reads its bio from the row instead of waiting on TMDB. Each person is committed as it
+    lands: a page open during the run already sees it. A failed lookup is skipped (left unstamped for the
+    next run); _PEOPLE_FAILS_IN_A_ROW of them in a row end the batch."""
+    ids = people_by_credits(db, "bio", limit)
+    done = failed = in_a_row = 0
+    for pid in ids:
+        if in_a_row >= _PEOPLE_FAILS_IN_A_ROW:
+            break
+        person = db.get(PlexPerson, pid)
+        # A page open may have enriched this person since the select: skip, don't fetch twice.
+        if person is None or person.tmdb_enriched_at is not None:
+            continue
+        try:
+            _fetch_person_into(tmdb, person)
+        except TmdbError as exc:
+            db.rollback()
+            failed, in_a_row = failed + 1, in_a_row + 1
+            log.warning(
+                "a TMDB person lookup in the batch failed",
+                extra=logs.event(
+                    "plex.tmdb.people_batch_failed", person_id=pid, reason=type(exc).__name__
+                ),
+            )
+            continue
+        db.commit()
+        done, in_a_row = done + 1, 0
+    return {"enriched": done, **({"failed": failed} if failed else {})}

backend/app/plex/watch_sync.py

@@ -11,22 +11,25 @@ already pages) and upsert them into the owner's `plex_states`. Plex wins on over
 exist only in Siftlode are left untouched (union, Plex-authoritative on the intersection).
 
 Phases B (Siftlode→Plex push via scrobble/timeline) and C (incremental Plex→Siftlode via the watch
-history + onDeck) build on this and land in later ships. As of S2 Plex is the source of truth: the
+history + onDeck) build on this and land in later ships. Plex is now the source of truth: the
 player pushes the resume position back to Plex on the periodic checkpoint (not just the final flush),
 and the incremental pull resolves a genuine divergence to Plex's state (see `_pull_apply`) rather than
 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.models import PlexItem, PlexLibrary, PlexLink, PlexState
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.sync import (
     _TYPE_EPISODE,
@@ -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
@@ -70,13 +72,27 @@ def _rk_to_id(db: Session) -> dict[str, int]:
 
 def _scan_plex_states(
     db: Session, plex: PlexClient
-) -> tuple[dict[int, tuple[str, int, datetime | None, datetime | None]], int]:
+) -> tuple[dict[int, tuple[str, int, datetime | None, datetime | None]], int, set[str], set[str]]:
     """Scan the enabled movie/show sections and return ``{item_id: (status, pos, watched_at,
-    prog_at)}`` for every mirrored leaf Plex holds a watch signal for, plus the scanned-leaf count.
-    Shared by the one-time import and the full reconcile (both need Plex's whole current picture)."""
+    prog_at)}`` for every mirrored leaf Plex holds a watch signal for, the scanned-leaf count, the
+    keys of the sections SETTLED — walked to the server's total (or said empty by a server we mirror
+    nothing from) — and the keys of every section walked.
+    Shared by the one-time import and the full reconcile (both need Plex's whole current picture).
+    The settled keys matter to the reconcile alone: it reads "absent from the scan" as "Plex
+    un-watched it", which a walk cut short by a Plex hiccup does not mean (see `_paginate`). Settled
+    is decided PER SECTION: one section that never settles (a library emptied on Plex while its
+    mirrored items are kept) must not stop un-watches syncing in all the others."""
     item_id_by_rk = _rk_to_id(db)
     wanted = _enabled_section_keys(db)
+    # The sections we mirror something from: a total of 0 from one of those contradicts the mirror.
+    mirrored = set(
+        db.execute(
+            select(PlexLibrary.plex_key).join(PlexItem, PlexItem.library_id == PlexLibrary.id)
+        ).scalars()
+    )
     scanned = 0
+    settled: set[str] = set()
+    walked: set[str] = set()
     out: dict[int, tuple[str, int, datetime | None, datetime | None]] = {}
     for s in plex.sections():
         stype = s.get("type")
@@ -86,7 +102,10 @@ def _scan_plex_states(
         if wanted is not None and key not in wanted:
             continue
         item_type = _TYPE_MOVIE if stype == "movie" else _TYPE_EPISODE
-        for meta in _paginate(plex, key, item_type):
+        walked.add(key)
+        progress: dict = {}
+        before = scanned
+        for meta in _paginate(plex, key, item_type, progress):
             scanned += 1
             item_id = item_id_by_rk.get(str(meta.get("ratingKey") or ""))
             if item_id is None:
@@ -96,7 +115,15 @@ def _scan_plex_states(
             )
             if res is not None:
                 out[item_id] = res
-    return out, scanned
+        # A section the server SAYS is empty (total 0, nothing listed) settles too. Believed only for
+        # a section we mirror nothing from: one whose items we hold answering 0 is a Plex that lost
+        # the library for a moment, not one that un-watched all of it — so it is left
+        # unsettled, and its rows are not cleared.
+        listed = scanned > before
+        said_empty = progress.get("total") == 0 and not listed and key not in mirrored
+        if (progress.get("complete") and listed) or said_empty:
+            settled.add(key)
+    return out, scanned, settled, walked
 
 
 def import_owner_watch_state(db: Session, link: PlexLink) -> dict:
@@ -109,7 +136,8 @@ def import_owner_watch_state(db: Session, link: PlexLink) -> dict:
     stats = {"watched": 0, "in_progress": 0, "scanned": 0}
     try:
         with PlexClient(db) as plex:
-            scanned_states, stats["scanned"] = _scan_plex_states(db, plex)
+            # A partial scan is still safe here: the import only ever ADDS what Plex reports.
+            scanned_states, stats["scanned"], _settled, _walked = _scan_plex_states(db, plex)
             # One row per item (keyed by item_id → inherently de-duped) then bulk-UPSERT. An upsert is
             # idempotent AND concurrency-safe: a repeated/overlapping enable (the toggle firing twice
             # while the multi-second import runs) can't raise a duplicate-key error — it re-updates.
@@ -148,6 +176,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 +356,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
@@ -362,7 +402,7 @@ def _pull_apply(
         if st is not None and not st.synced_to_plex:
             st.synced_to_plex = True  # already matches Plex → just settle the flag, no churn
         return None
-    # Plex-authoritative (S2): on a genuine divergence for an item Plex knows about, Plex wins — no
+    # Plex-authoritative: on a genuine divergence for an item Plex knows about, Plex wins — no
     # last-write-wins tug-of-war. This is safe because prompt write-back (playback.py pushes the resume
     # position to Plex on the ~10s checkpoint, not just on the final flush) keeps Plex current, so a
     # local edit that's "newer" than Plex has almost always already been pushed and matched above by
@@ -566,6 +606,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:
@@ -575,6 +616,27 @@ def run_plex_watch_sync(db: Session) -> dict:
     return total
 
 
+def _clear_unwatched(db: Session, user_id: int, plex_states: dict, settled: set[str]) -> int:
+    """Clear the user's rows Plex no longer has a record for — the mirrored ones (Plex un-watched
+    them); hidden and dirty rows stay (a dirty one is re-pushed by `_repush_dirty`). Only rows of the
+    sections the scan SETTLED: a walk a Plex hiccup cut short leaves out rows it merely failed to
+    reach, and clearing those un-watched them here until the next complete run; an item of
+    a library the allowlist leaves out is absent from every scan, and was cleared on every run."""
+    n = 0
+    rows = db.execute(
+        select(PlexState)
+        .join(PlexItem, PlexItem.id == PlexState.item_id)
+        .join(PlexLibrary, PlexLibrary.id == PlexItem.library_id)
+        .where(PlexState.user_id == user_id, PlexLibrary.plex_key.in_(settled))
+    )
+    for st in rows.scalars().all():
+        if st.item_id in plex_states or st.status == "hidden" or not st.synced_to_plex:
+            continue
+        db.delete(st)
+        n += 1
+    return n
+
+
 def run_plex_watch_reconcile(db: Session) -> dict:
     """Scheduler job (default daily) — the authoritative full reconcile. Rescans every section and,
     per item, uses `synced_to_plex` to settle what the incremental feed can't:
@@ -593,7 +655,7 @@ def run_plex_watch_reconcile(db: Session) -> dict:
         try:
             with PlexClient(db) as plex:
                 _resolve_account_id(db, plex, link)
-                plex_states, scanned = _scan_plex_states(db, plex)
+                plex_states, scanned, settled, walked = _scan_plex_states(db, plex)
                 total["scanned"] += scanned
 
                 for item_id, (status, pos, watched_at, prog_at) in plex_states.items():
@@ -601,22 +663,24 @@ def run_plex_watch_reconcile(db: Session) -> dict:
                     if ch:
                         total["applied"] += 1
 
-                # Siftlode rows Plex no longer has a record for: clear the ones that were mirrored
-                # (Plex un-watched them); leave hidden + dirty (dirty gets re-pushed just below).
-                for st in (
-                    db.execute(select(PlexState).where(PlexState.user_id == link.user_id))
-                    .scalars()
-                    .all()
-                ):
-                    if st.item_id in plex_states or st.status == "hidden":
-                        continue
-                    if st.synced_to_plex:
-                        db.delete(st)
-                        total["cleared"] += 1
+                total["cleared"] += _clear_unwatched(db, link.user_id, plex_states, settled)
+                if unsettled := sorted(walked - settled):
+                    total["incomplete"] = total.get("incomplete", 0) + 1
+                    log.warning(
+                        "Plex sections %s were cut short or answered empty; their rows are not cleared"
+                        " this run",
+                        ", ".join(unsettled),
+                        extra=logs.event(
+                            "plex.watch.reconcile_incomplete",
+                            user_id=link.user_id,
+                            sections=unsettled,
+                        ),
+                    )
 
                 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/progress.py

@@ -8,7 +8,7 @@ its own thread/context) never cross wires. When no sink is bound (e.g. a manual
 """
 
 import contextvars
-from typing import Callable, Optional
+from typing import Callable, Literal, Optional
 
 Sink = Callable[[int, Optional[int], Optional[str]], None]
 
@@ -24,6 +24,19 @@ def report(current: int, total: int | None = None, phase: str | None = None) ->
         sink(current, total, phase)
 
 
+class JobFailed(RuntimeError):
+    """A job's own failure, said so the reader's language can name it: the client reads
+    `scheduler.failure.<reason>` and interpolates `params` (keep them to values the reader may see —
+    numbers, ids, short codes). The message is the English line the log and `last_error` keep. An
+    upstream's own error (a timeout, a refused connection) is not one of these: it stays as raised,
+    being diagnostic."""
+
+    def __init__(self, reason: str, message: str, **params: object):
+        super().__init__(message)
+        self.reason = reason
+        self.params = params
+
+
 class bind:
     """Context manager that binds a progress sink for the duration of a job run."""
 
@@ -35,7 +48,9 @@ class bind:
         self._token = _sink.set(self._sink)
         return self
 
-    def __exit__(self, *exc) -> bool:
+    # Literal[False], not bool: this never swallows the job's exception, and saying so is what lets
+    # a type checker know a name assigned inside `with bind(...)` is bound after it.
+    def __exit__(self, *exc) -> Literal[False]:
         if self._token is not None:
             _sink.reset(self._token)
         return False

backend/app/quota.py

@@ -7,11 +7,13 @@ always be allowed; expensive backfill must yield to the remaining budget.
 
 import contextlib
 import contextvars
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
+from typing import Any, cast
 from zoneinfo import ZoneInfo
 
-from sqlalchemy import func, select
+from sqlalchemy import delete, func, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.engine import CursorResult
 from sqlalchemy.orm import Session
 
 from app import sysconfig
@@ -37,6 +39,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"
@@ -95,6 +98,20 @@ def pacific_today():
     return datetime.now(_PACIFIC).date()
 
 
+def gc(db: Session, retention_days: int) -> int:
+    """Delete quota-history rows older than `retention_days` (<= 0 keeps them forever) and return how
+    many went. Flushes only; the cleanup job commits. Today's rows are never in reach: the per-user
+    search cap counts them, and the floor of two days outlasts any Pacific day (25 h at most)."""
+    if retention_days <= 0:
+        return 0
+    cutoff = datetime.now(timezone.utc) - timedelta(days=max(2, retention_days))
+    # A DELETE answers with a CursorResult; `execute` is typed as the general Result, without rowcount.
+    result = cast(
+        CursorResult[Any], db.execute(delete(QuotaEvent).where(QuotaEvent.created_at < cutoff))
+    )
+    return result.rowcount or 0
+
+
 def pacific_day_start_utc() -> datetime:
     """UTC instant of the current Pacific day's midnight — aligns 'today' with the budget reset."""
     start = datetime.now(_PACIFIC).replace(hour=0, minute=0, second=0, microsecond=0)

backend/app/ratelimit.py

@@ -1,21 +1,30 @@
 """A tiny in-process sliding-window rate limiter.
 
-Generic groundwork: keyed by an arbitrary string (e.g. a client IP), so it can throttle any
+Generic groundwork: keyed by an arbitrary string (e.g. a client — `client_key`), so it can throttle any
 endpoint. Single-worker uvicorn → in-memory state is sufficient; it resets on restart, which
 is fine for abuse throttling (not for anything that must survive a deploy). Not shared across
 processes — if we ever run multiple workers, swap the backing store for Redis behind the same
 ``allow()`` interface.
 """
 
+import ipaddress
 import threading
 import time
 
+from fastapi import Request
+
+from app.config import settings
+
 
 class RateLimiter:
-    def __init__(self, max_events: int, window_seconds: float):
+    """At most `max_events` attempts per `window_seconds` per key — or, when each attempt passes a
+    `cost`, at most that much total cost (a byte budget counts bytes, not calls)."""
+
+    def __init__(self, max_events: float, window_seconds: float):
         self.max_events = max_events
         self.window = window_seconds
-        self._hits: dict[str, list[float]] = {}
+        # key → (monotonic time, cost) of every counted attempt still inside the window
+        self._hits: dict[str, list[tuple[float, float]]] = {}
         self._lock = threading.Lock()
 
     def reset(self) -> None:
@@ -25,27 +34,74 @@ class RateLimiter:
         with self._lock:
             self._hits.clear()
 
-    def allow(self, key: str) -> bool:
-        """Record an attempt for ``key`` and return whether it is within the limit.
+    def exhausted(self, key: str) -> bool:
+        """Whether ``key``'s window is already full (``allow`` would refuse it), WITHOUT counting an
+        attempt — for a limit that counts only some outcomes: ask it first, ``allow`` the ones that
+        count."""
+        cutoff = time.monotonic() - self.window
+        with self._lock:
+            return sum(c for t, c in self._hits.get(key, []) if t > cutoff) >= self.max_events
 
-        True  -> under the cap (the attempt is counted).
-        False -> the cap for the current window is already reached (attempt NOT counted, so a
+    def allow(self, key: str, cost: float = 1) -> bool:
+        """Record an attempt costing ``cost`` for ``key`` and return whether it is within the limit.
+
+        True  -> within the cap (the attempt is counted).
+        False -> the attempt would pass the cap for the current window (attempt NOT counted, so a
                  blocked caller can't keep pushing the window forward)."""
         now = time.monotonic()
         cutoff = now - self.window
         with self._lock:
-            hits = [t for t in self._hits.get(key, []) if t > cutoff]
-            if len(hits) >= self.max_events:
+            hits = [(t, c) for t, c in self._hits.get(key, []) if t > cutoff]
+            if sum(c for _, c in hits) + cost > self.max_events:
                 self._hits[key] = hits
                 return False
-            hits.append(now)
+            hits.append((now, cost))
             self._hits[key] = hits
             # Opportunistic cleanup so abandoned keys don't accumulate unboundedly.
             if len(self._hits) > 4096:
                 for k in list(self._hits):
-                    fresh = [t for t in self._hits[k] if t > cutoff]
+                    fresh = [(t, c) for t, c in self._hits[k] if t > cutoff]
                     if fresh:
                         self._hits[k] = fresh
                     else:
                         del self._hits[k]
             return True
+
+
+def _norm_ip(s: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
+    """Parse an IP for comparison, unwrapping IPv4-mapped IPv6 (`::ffff:10.0.0.1` → `10.0.0.1`) so a
+    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
+
+
+def client_key(request: Request) -> str:
+    """Best-effort client identity for rate limiting: its IP, or for IPv6 the /64 the address sits in — a
+    subscriber is handed a whole /64, so keyed on the full address one client would have endless identities
+    to spread its attempts over. X-Forwarded-For is client-controlled, so we trust it
+    ONLY when the request actually arrived from a configured reverse proxy (settings.trusted_proxy_ips
+    — the address the proxy connects FROM, e.g. the VPS Caddy's WireGuard peer IP). Our proxy APPENDS
+    the client it saw to XFF, so the RIGHTMOST entry is the real client and can't be forged by a
+    client pre-seeding the header. Any other peer (someone hitting the app port directly, bypassing the
+    proxy) is untrusted — we use its real socket IP, so it can't spoof its rate-limit identity.
+
+    SAFETY: this relies on `request.client` being the TRUE socket peer. uvicorn is started WITHOUT
+    `--proxy-headers` (see entrypoint.sh) precisely so it never rewrites `request.client` from XFF —
+    do NOT add that flag, or the trust check below would compare against a forgeable value."""
+    peer = request.client.host if request.client else "unknown"
+    client = peer
+    trusted = {_norm_ip(p) for p in settings.trusted_proxy_ip_set} - {None}
+    if _norm_ip(peer) in trusted:
+        xff = request.headers.get("x-forwarded-for")
+        parts = [p.strip() for p in (xff or "").split(",") if p.strip()]
+        if parts:
+            client = parts[-1]
+    ip = _norm_ip(client)
+    if isinstance(ip, ipaddress.IPv6Address):
+        return str(ipaddress.IPv6Network((ip, 64), strict=False))
+    return client

backend/app/realtime.py

@@ -1,61 +0,0 @@
-"""In-process WebSocket connection registry for live server→client push.
-
-Generic groundwork (notification module phase 2 is the first user): connections are kept in
-this process's memory, keyed by user_id, so a request handler can push an event to all of a
-user's open tabs/devices. Single-uvicorn-process assumption — if we ever run multiple workers,
-replace the in-memory map with a Redis pub/sub fan-out behind the same `push()` interface (same
-note as app.ratelimit).
-
-`push()` is intentionally SYNC-callable: ordinary (sync) route handlers run in a threadpool, so
-they schedule the actual send onto the WebSocket event loop via run_coroutine_threadsafe. The
-connect/disconnect/_push coroutines all run on that one loop, so the connection map is only ever
-mutated from a single thread.
-"""
-
-import asyncio
-import logging
-from collections import defaultdict
-
-from starlette.websockets import WebSocket
-
-log = logging.getLogger("siftlode.realtime")
-
-
-class ConnectionManager:
-    def __init__(self) -> None:
-        self._conns: dict[int, set[WebSocket]] = defaultdict(set)
-        self._loop: asyncio.AbstractEventLoop | None = None
-
-    async def connect(self, user_id: int, ws: WebSocket) -> None:
-        self._loop = asyncio.get_running_loop()
-        await ws.accept()
-        self._conns[user_id].add(ws)
-
-    async def disconnect(self, user_id: int, ws: WebSocket) -> None:
-        conns = self._conns.get(user_id)
-        if conns:
-            conns.discard(ws)
-            if not conns:
-                self._conns.pop(user_id, None)
-
-    async def _push(self, user_id: int, payload: dict) -> None:
-        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
-
-    def push(self, user_id: int, payload: dict) -> None:
-        """Schedule a push onto the WebSocket event loop. Safe to call from a sync route
-        handler (threadpool). No-op if no WebSocket has ever connected (no loop captured)."""
-        loop = self._loop
-        if loop is None:
-            return
-        try:
-            asyncio.run_coroutine_threadsafe(self._push(user_id, payload), loop)
-        except Exception:
-            log.debug("ws push failed", exc_info=True)
-
-
-manager = ConnectionManager()

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

@@ -1,4 +1,4 @@
-"""Route-layer shared helpers for the API contract (R6 S1a).
+"""Route-layer shared helpers for the API contract.
 
 Small, dependency-light guards that several route modules had hand-rolled with subtle
 drift. Keeping them here (imported by the route modules) means the "fetch a row or 404"
@@ -6,16 +6,55 @@ and "fetch a row this user owns or 404" idioms have one definition, one status c
 one existence-leak policy.
 """
 
-from typing import Any, TypeVar
+from typing import IO, Any, TypeVar
 
-from fastapi import HTTPException
+from fastapi import HTTPException, Request
+from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy.orm import Session
 
 from app.db import Base
-from app.models import User
+from app.models import POSITION_MAX_S, User
+from app.issues import gitea
+from app.refusal import refused
+from app.youtube.client import YouTubeError, refusal_reason
 
 M = TypeVar("M", bound=Base)
 
+# Resume-position thresholds of a player that only keeps a resume point (the YouTube player, the
+# library's): positions below this are "didn't really start" and within this of the end are
+# "basically finished" — neither is worth storing, so the position is cleared instead (no progress
+# bar). The client's local resume (`lib/resume.ts`) keeps the same two numbers, held equal by
+# `resume.contract.test.ts` beside it. NB: the Plex player intentionally uses a LARGER finish margin
+# (30s) because it marks long-form items watched, not just clears a resume bar — see
+# routes/plex/playback.py.
+PROGRESS_MIN_SECONDS = 5
+FINISH_MARGIN_SECONDS = 10
+
+
+class ProgressIn(BaseModel):
+    """A player's resume checkpoint (sent every few seconds while it plays, and as a beacon when the
+    page goes away)."""
+
+    # Finite only: JSON parsing here accepts `Infinity`/`NaN`, and the handler's `int()` turned
+    # one into a 500.
+    model_config = ConfigDict(allow_inf_nan=False)
+
+    # Accept a float and truncate (`kept_position`) — the player may post a raw currentTime (a float),
+    # which the old `int(payload.get(...))` silently truncated. A plain `int` field would 422 that on
+    # the progress hot path, losing the resume position; `float` keeps the old tolerance.
+    # Bounded above by the int4 column (see POSITION_MAX_S): past it the flush was a 500.
+    position_seconds: float = Field(0, le=POSITION_MAX_S)
+    duration_seconds: float = Field(0, le=POSITION_MAX_S)
+
+
+def kept_position(body: ProgressIn) -> int:
+    """The whole-second resume point worth storing for `body`, or 0 for "clear it" (too early to
+    count as started, or close enough to the end to count as finished)."""
+    position = max(0, int(body.position_seconds))
+    duration = int(body.duration_seconds)
+    near_end = duration > 0 and position > duration - FINISH_MARGIN_SECONDS
+    return position if position >= PROGRESS_MIN_SECONDS and not near_end else 0
+
 
 def not_found(what: str = "generic") -> HTTPException:
     """The 404 for a row that is gone — structured, so the bilingual UI says it in the reader's
@@ -25,10 +64,13 @@ def not_found(what: str = "generic") -> HTTPException:
     return HTTPException(status_code=404, detail={"code": "not_found", "reason": what})
 
 
-def get_or_404(db: Session, model: type[M], id_: Any, *, what: str = "generic") -> M:
+def get_or_404(
+    db: Session, model: type[M], id_: Any, *, what: str = "generic", lock: bool = False
+) -> M:
     """Fetch a row by primary key or raise 404. Replaces the `db.get(Model, id); if None: 404`
-    idiom repeated across routes."""
-    obj = db.get(model, id_)
+    idiom repeated across routes. `lock` takes it FOR UPDATE (bypassing the identity map), so two
+    requests that read-then-write its children (a playlist's item positions) run one after the other."""
+    obj = db.get(model, id_, with_for_update=True if lock else None)
     if obj is None:
         raise not_found(what)
     return obj
@@ -42,12 +84,101 @@ def owned_or_404(
     *,
     owner_attr: str = "user_id",
     what: str = "generic",
+    lock: bool = False,
 ) -> M:
-    """Fetch a row by primary key that `user` owns, or raise 404. A row owned by someone
+    """Fetch a row by primary key that `user` owns, or raise 404 (`lock`: see `get_or_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)."""
-    obj = get_or_404(db, model, id_, what=what)
+    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, lock=lock)
     if getattr(obj, owner_attr) != user.id:
         raise not_found(what)
     return obj
+
+
+def youtube_refusal(exc: Exception, *, playlist: bool = False) -> 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. `playlist`: the route acts on one
+    playlist the user picked, so a missing playlist is THAT one, gone (`refusal_reason`)."""
+    reason = (
+        refusal_reason(exc, playlist=playlist) if isinstance(exc, YouTubeError) else "unavailable"
+    )
+    return HTTPException(status_code=422, detail={"code": "youtube", "reason": reason})
+
+
+async def capped_body(request: Request, limit: int) -> bytes:
+    """The request body, refused (413 `too_large`) the moment it passes `limit` bytes while still
+    arriving. Counted, not taken from Content-Length: a declared length can be absent (chunked) or
+    wrong, and counting stops reading at the same point a declared-length check would have."""
+    body = bytearray()
+    async for chunk in request.stream():
+        body += chunk
+        if len(body) > limit:
+            raise HTTPException(status_code=413, detail={"code": "too_large"})
+    return bytes(body)
+
+
+async def capped_stream_to(
+    request: Request, out: IO[bytes], limit: int, refusal: HTTPException
+) -> int:
+    """`capped_body`'s sibling for a body too large to hold: the same counting rule, written
+    straight to `out` instead of accumulated, returning the size.
+
+    Two deliberate differences from `capped_body`. It never builds a `bytearray` — the upload route
+    admits 500 MiB by default, so holding the body would trade a disk problem for a memory one. And
+    the refusal is the CALLER'S, passed in rather than assumed: `capped_body`'s flat 413 is right
+    for a screenshot, while the upload route answers 422 `upload_too_large` carrying the admin
+    knob's own number, which is what its dialog shows the user. One counting rule, two answers,
+    neither of them a second copy of the loop.
+
+    The caller owns `out` and owns cleaning it up: a body refused half-way has already written what
+    arrived before the limit was passed.
+
+    **The refusal DRAINS the rest of the body before it is raised, and that is not politeness.**
+    Answering mid-upload and closing the connection is what the client sees as a network failure,
+    not as a refusal: the browser's XHR fires `onerror` before it can read the response, so a file
+    over the limit reported itself as "the server couldn't be reached" instead of naming the limit —
+    measured in a real browser, not reasoned about. Reading the remainder to nowhere lets the client
+    finish sending, read the 422 and say the true thing.
+
+    The bytes are discarded, never written, and the whole request is already bounded by
+    `bodylimit`'s per-route ceiling — so the worst case is bandwidth an authenticated caller was
+    sending anyway, against the old behaviour which wrote exactly those bytes to disk."""
+    size = 0
+    over = False
+    async for chunk in request.stream():
+        size += len(chunk)
+        if over:
+            continue  # draining — see the docstring; counted, not stored
+        if size > limit:
+            over = True
+            continue
+        out.write(chunk)
+    if over:
+        raise refusal
+    return size
+
+
+def issue_refused(exc: gitea.GiteaError) -> HTTPException:
+    """The refusal an issue-tracker failure answers as — the send, the preview and the
+    admin's connection test alike. Literal reasons, one per case: the frontend's contract test reads
+    them to require a sentence for each in both languages."""
+    match exc.reason:
+        case "not_configured":
+            return refused(400, "issues_not_configured")
+        case "unreachable":
+            return refused(422, "issues_unreachable")
+        case "bad_token":
+            return refused(422, "issues_bad_token")
+        case "repo_not_found":
+            return refused(422, "issues_repo_not_found")
+        case "public_repo":
+            return refused(422, "issues_public_repo")
+        case "issues_disabled":
+            return refused(422, "issues_disabled")
+        case _:
+            return refused(422, "issues_rejected")

backend/app/routes/admin.py

@@ -1,5 +1,4 @@
-"""Admin-only onboarding: review access requests (Invites), approve/deny, manual add.
-Also the demo-account admin surface: the demo email whitelist + a manual state reset."""
+"""Admin-only onboarding: review access requests (Invites), approve/deny, manual add."""
 
 from collections.abc import Iterable
 from datetime import datetime, timezone
@@ -19,15 +18,12 @@ from app.auth import (
     count_admins,
     env_allowed_canonicals,
     find_user_by_email,
-    get_or_create_demo_user,
     is_allowed,
     operator_contact,
     purge_user,
 )
 from app.db import get_db
-from app.demo import reset_demo_state
 from app.models import (
-    DemoWhitelist,
     Invite,
     User,
 )
@@ -39,6 +35,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"])
 
@@ -130,7 +127,7 @@ def _welcome_mail_parts(db: Session, email: str) -> tuple[str | None, bool, int]
     """
     hours = int(APPROVAL_VERIFY_TTL.total_seconds() // 3600)
     user = find_user_by_email(db, email)
-    if user is None or user.is_demo:
+    if user is None:
         return None, False, hours
     if user.email_verified or not email_mod.email_enabled(db):
         return None, True, hours
@@ -141,20 +138,21 @@ def _activate_user_by_email(db: Session, email: str) -> None:
     """Approving access activates a matching (e.g. pending password-registration) account so
     it can sign in. No-op if no such user exists yet (a Google user is created at first login).
 
-    E9.5 S1: this path deliberately does NOT revoke a preset password. Revoking here destroyed the
+    This path deliberately does NOT revoke a preset password. Revoking here destroyed the
     password a legitimate registrant had just chosen and made "your password was cleared for
     security" the DEFAULT experience, because approve-before-verify is the normal ordering.
 
-    S1 justified that by saying `password_login` refuses an unverified account BEFORE it looks at
-    `is_active`, so a pre-emptor could not sign in "approved or not". A review of the finished epic
-    showed that argument only holds while the address stays unverified — and S6's approval mail
-    hands the real owner a confirmation link precisely so they will end that state. Nothing replaced
-    the revoke, and that is deliberate: round 2 of the same review tried "the newest registration
-    owns an unverified account" and reverted it, because the rule is symmetric — an attacker can
-    always register last — and it handed anonymous callers a write onto a real account's credential.
-    The owner's recourse is password-reset, which proves the mailbox, rewrites the hash and bumps
-    the session epoch. The residual is logged as SEC-16. The revoke also stays on the Google-adoption path
-    (auth.revoke_preset_password_if_unverified), where ownership is actually attested."""
+    That was once justified by saying `password_login` refuses an unverified account BEFORE it
+    looks at `is_active`, so a pre-emptor could not sign in "approved or not". A review of the
+    finished epic showed that argument only holds while the address stays unverified — and the
+    approval mail hands the real owner a confirmation link precisely so they will end that state.
+    Nothing replaced the revoke, and that is deliberate: the same review later tried "the newest
+    registration owns an unverified account" and reverted it, because the rule is symmetric — an
+    attacker can always register last — and it handed anonymous callers a write onto a real
+    account's credential. The owner's recourse is password-reset, which proves the mailbox, rewrites
+    the hash and bumps the session epoch. The residual is logged as SEC-16. The revoke also stays on
+    the Google-adoption path (auth.revoke_untrusted_preset_password), where ownership is
+    actually attested."""
     # Canonical, with the literal spelling preferred when both exist: approving
     # `npeter83.temu@gmail.com` must activate the account that registered as `npeter83temu@gmail.com`,
     # since Gmail delivers both to one mailbox and the admin decided about the mailbox.
@@ -169,7 +167,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 +177,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 +189,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 +208,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 +227,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 +244,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 +261,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 +370,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,
@@ -396,18 +397,19 @@ def _serialize_user(u: User) -> dict:
         "is_active": u.is_active,
         "is_suspended": u.is_suspended,
         "email_verified": u.email_verified,
-        "is_demo": u.is_demo,
         "has_password": u.password_hash is not None,
         # Distinguishes "this account never had a password" (Google-only) from "SEC-10 cleared it" —
         # the same distinction _send_reset_if_eligible needs, and the one an admin has to see before
         # deciding what kind of help someone needs.
         "password_revoked_at": iso(u.password_revoked_at),
         "has_google": u.google_sub is not None,
-        # Only when it DIFFERS from the account address (E9.5 S3): "connected" is not the same
+        # Only when it DIFFERS from the account address: "connected" is not the same
         # statement as "connected as someone else", and the second one is the one that explains a
         # confusing sign-in.
         "google_email": u.google_email if u.google_email != u.email else None,
         "created_at": iso(u.created_at),
+        # NULL = no sign-in since the column existed (0085).
+        "last_login_at": iso(u.last_login_at),
     }
 
 
@@ -429,23 +431,21 @@ def set_user_role(
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Promote/demote a user. Guards: can't change your own role, can't touch the demo
-    account, and can't remove the last remaining admin. Emails the user when it actually changes."""
+    """Promote/demote a user. Guards: can't change your own role 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.")
     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(
@@ -484,23 +484,20 @@ def set_user_suspended(
     db: Session = Depends(get_db),
 ) -> dict:
     """Suspend or un-suspend an account. A suspended user can't sign in by any method and any
-    live session is dropped on its next request. Guards: can't suspend the demo account, can't
-    suspend yourself, and can't suspend the last active admin (that would lock admin out). On
+    live session is dropped on its next request. Guards: can't suspend yourself, and can't suspend the last active admin (that would lock admin out). On
     un-suspend the user is emailed they can return (suspend is announced reactively, on a blocked
     sign-in)."""
     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.")
     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(
@@ -532,20 +529,16 @@ def admin_delete_user(
 ) -> dict:
     """Admin-triggered account deletion — the same full erasure a user can perform on themselves
     (cascade delete of all personal data + access-request cleanup + Google-grant revoke). Guards:
-    not the demo account, not yourself (use Settings → Account), and not the last admin."""
+    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.")
     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,
@@ -559,10 +552,7 @@ def admin_delete_user(
     return {"deleted": user_id}
 
 
-# --- Demo account: email whitelist + state reset -------------------------------------
-
-
-# --- Stuck sign-ups: the admin lifeline (E9.5 S5, roadmap UX-25) ---------------------------------
+# --- Stuck sign-ups: the admin lifeline -----------------------------------------------------------
 
 
 def _pending_access_rows(db: Session) -> list[User]:
@@ -583,7 +573,6 @@ def _pending_access_rows(db: Session) -> list[User]:
         db.execute(
             select(User)
             .where(
-                User.is_demo.is_(False),
                 User.is_suspended.is_(False),
                 or_(User.is_active.is_(False), User.email_verified.is_(False)),
             )
@@ -621,7 +610,7 @@ def user_access(
     _: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Everything the account panel shows about why this person can or cannot get in (E12 S5).
+    """Everything the account panel shows about why this person can or cannot get in.
 
     Its own endpoint rather than extra columns on /users: `is_allowed` and `can_activate` each run a
     query, and the panel opens for ONE user at a time — folding them into the list would pay that cost
@@ -640,7 +629,7 @@ def create_set_password_link(
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Mint a one-time link that lets this account set a password, with no email involved (E12 S5).
+    """Mint a one-time link that lets this account set a password, with no email involved.
 
     The answer to SEC-15, SEC-16 and "no SMTP and someone forgot their password" at once. The admin
     hands the link over by whatever channel they trust; opening it sets a password and signs out
@@ -649,13 +638,8 @@ def create_set_password_link(
     Deliberately NOT gated on the account's state. It is useful for a pre-empted address, for a
     revoked password, for a Google-only account that wants one, and for a plain forgotten password on
     an instance with no mail — narrowing it to one of those would only make the admin's real case the
-    one it refuses. The demo account is the single exception: it is shared, so handing anyone a way to
-    change its password is handing them everyone else's session."""
+    one it refuses."""
     target = get_or_404(db, User, user_id, what="user")
-    if target.is_demo:
-        raise HTTPException(
-            status_code=400, detail={"code": "setpw", "reason": "demo", "email": target.email}
-        )
     url, expires_at = issue_set_password_link(db, target)
     # The URL itself is NOT recorded: the audit log is read by humans and kept long, and a live
     # credential-setting link is the last thing that belongs in it. That the link was issued, by whom,
@@ -688,8 +672,6 @@ def activate_user(
     already do exactly this by re-entering the address in the whitelist box (`add_invite` →
     `_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.")
     if target.is_active:
         return _serialize_user(target)  # idempotent: a double click is not an error
     if not is_allowed(db, target.email):
@@ -727,7 +709,7 @@ def resend_user_verification(
     Not rate-limited: an admin is not a threat model to enumerate against, and the deliberate silence
     of the public endpoint is exactly what this exists to escape."""
     target = get_or_404(db, User, user_id, what="user")
-    if target.is_demo or target.email_verified:
+    if target.email_verified:
         raise HTTPException(
             status_code=409,
             detail={"code": "resend", "reason": "not_applicable", "email": target.email},
@@ -753,89 +735,6 @@ def resend_user_verification(
     return {"ok": True, "email": target.email}
 
 
-def _serialize_demo(row: DemoWhitelist) -> dict:
-    return {
-        "id": row.id,
-        "email": row.email,
-        "note": row.note,
-        "added_by": row.added_by,
-        "created_at": iso(row.created_at),
-    }
-
-
-@router.get("/demo/whitelist")
-def list_demo_whitelist(_: User = Depends(admin_user), db: Session = Depends(get_db)) -> list[dict]:
-    rows = (
-        db.execute(select(DemoWhitelist).order_by(DemoWhitelist.created_at.desc())).scalars().all()
-    )
-    return [_serialize_demo(r) for r in rows]
-
-
-class AddDemoWhitelistIn(BaseModel):
-    email: str = ""
-    note: str | None = None
-
-
-@router.post("/demo/whitelist")
-def add_demo_whitelist(
-    body: AddDemoWhitelistIn,
-    admin: User = Depends(admin_user),
-    db: Session = Depends(get_db),
-) -> dict:
-    """Add an email that may enter the shared demo account from the login page (no Google
-    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.")
-    row = db.execute(select(DemoWhitelist).where(DemoWhitelist.email == email)).scalar_one_or_none()
-    if row is None:
-        row = DemoWhitelist(
-            email=email,
-            note=(body.note or "").strip() or None,
-            added_by=admin.email,
-        )
-        db.add(row)
-        audit.record(
-            db, admin.id, AuditAction.DEMO_ADD, target_type="demo", target_id=email, summary=email
-        )
-        db.commit()
-    return _serialize_demo(row)
-
-
-@router.delete("/demo/whitelist/{entry_id}")
-def remove_demo_whitelist(
-    entry_id: int,
-    admin: User = Depends(admin_user),
-    db: Session = Depends(get_db),
-) -> dict:
-    row = db.get(DemoWhitelist, entry_id)
-    if row is not None:
-        audit.record(
-            db,
-            admin.id,
-            AuditAction.DEMO_REMOVE,
-            target_type="demo",
-            target_id=row.email,
-            summary=row.email,
-        )
-        db.delete(row)
-        db.commit()
-    return {"deleted": entry_id}
-
-
-@router.post("/demo/reset")
-def reset_demo(admin: User = Depends(admin_user), db: Session = Depends(get_db)) -> dict:
-    """Manually clean up the shared demo sandbox back to a baseline. A scheduled job does the
-    same automatically (admin-tunable interval); this is the admin's on-demand button."""
-    demo = get_or_create_demo_user(db)
-    seeded = reset_demo_state(db, demo)
-    audit.record(
-        db, admin.id, AuditAction.DEMO_RESET, summary=f"{seeded} sample playlists re-seeded"
-    )
-    db.commit()
-    return {"reset": True, "playlists_seeded": seeded}
-
-
 @router.post("/purge-discovery")
 def purge_discovery(admin: User = Depends(admin_user), db: Session = Depends(get_db)) -> dict:
     """Reclaim all un-kept discovery content NOW (ignoring the grace period): live-search result
@@ -852,4 +751,4 @@ def purge_discovery(admin: User = Depends(admin_user), db: Session = Depends(get
         after=result,
     )
     db.commit()
-    return result
+    return {"ok": True, **result}