release: 0.97.0 (feature/e30-app-in-hungarian)

- Person page: a bio ask that fails says so with a retry instead of reading as 'no biography'.
- Show page: the summary is a ClampedText (5 lines + More), like the person and collection pages;
  one More/Less pair (plex.textMore/textLess) for all three.
- Channels: a re-slotted row is placed in the language the server orders by (the stored
  preference, else English), not the UI's guess.
- A skipped run's body is only the reason (its title already says skipped).
- HU: Behúzási kvótatartalék; Eseménynapló ürítve / az eseménynaplót; indok; közvetlenül
  játszható / közvetlen közvetítés in the Plex hints.
- Tests: ClampedText re-measures on a resize, the show summary clamp, serverOrderLang.

.gitea/workflows/check.yml

@@ -1,22 +1,50 @@
 # 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:
+# independent of any one machine. Two 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
 #
+# They are declared side by side but they DO NOT run in parallel: the lab has a single act_runner
+# with one slot, so they queue. Measured across runs #86-#91 — the backend job starts at the exact
+# second the frontend one ends, every time, and the pair costs ~4 + ~6 = **~10 minutes from the
+# push**. Anything that waits on this gate has to budget for the sum, not the max; the ops
+# `release` read-back timed out on its first real run for believing otherwise.
+#
 # 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`).
+# failed to come up is a hard error, never a silent skip.
+#
+# The frontend container's node major is NOT free: it must equal the prod build image's and the dev
+# machine's, because vitest/tsc read the engine's own Intl and web-API implementations and those split
+# between majors. `.nvmrc` is the single source of truth and
+# `frontend/src/lib/nodeEngine.contract.test.ts` fails this gate if any of them drift apart.
 name: gate
 
-on: [push, pull_request]
+# Branch pushes only. A release pushes `main` and then the `v<ver>` tag, and a bare `on: [push]`
+# treated the tag as a second push of the IDENTICAL commit — every release ran this whole gate
+# twice, to the same verdict, for nothing (runs #81-#90 are five such pairs). `branches: ['**']`
+# keeps every branch covered and drops tag refs.
+#
+# It has to be `branches`, NOT the `tags-ignore` this obviously wants to be. Gitea's matchPushEvent
+# requires EVERY named filter to match, and each one bails on the wrong ref kind: `tags-ignore`
+# starts with `if !refName.IsTag() { break }`, so a filter meant to skip tags rejects every BRANCH
+# push and the gate stops running entirely. `branches` bails the same way on a tag, which is the
+# direction we want. (Measured in go-gitea v1.27.3 modules/actions/workflows.go, not assumed — it
+# differs from GitHub, where `tags-ignore` alone leaves branches unfiltered.)
+#
+# If that filter were ever wrong the gate would not run at all — which is why `siftlode release`
+# now ends by reading the verdict back for the sha it pushed, and says so out loud when there is
+# no run for it. A gate that silently stops running is the failure this repo already lived through.
+on:
+  push:
+    branches: ["**"]
+  pull_request:
 
 jobs:
   frontend:
     runs-on: ubuntu-latest
-    container: node:22-bookworm
+    container: node:24-bookworm
     defaults:
       run:
         working-directory: frontend
@@ -34,7 +62,11 @@ jobs:
     # 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
+    #
+    # This node runs the checkout action, never our code, so it is deliberately OUTSIDE the engine
+    # contract the frontend job is held to — it tracks `.nvmrc` as hygiene (node 20 went EOL in April
+    # 2026), but a missing upstream tag here must never be able to block the gate.
+    container: nikolaik/python-nodejs:python3.12-nodejs24
     services:
       postgres:
         image: postgres:16-alpine
@@ -61,6 +93,22 @@ jobs:
         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
+      # The ninth lane (E27 S3). Run from backend/ so it resolves exactly as the local lane does —
+      # pyrightconfig.json's include/extraPaths are relative to the config, but the baseline is
+      # found relative to the working directory. New errors fail; the ~200 pre-existing ones are in
+      # .basedpyright/baseline.json and burn down epic by epic. Matching is per (file, rule, column
+      # span) plus a count, so a new error of the SAME shape in a file where a sibling was just
+      # fixed is absorbed — burn the hot files down first.
+      #
+      # The second step is not redundant. basedpyright TIGHTENS the baseline in place when the count
+      # drops, with no --writebaseline, and CI throws its workspace away — so without this a
+      # burn-down is green here and red on the developer's `siftlode check`, which has the same
+      # guard. Two gates over one tree must not answer differently.
+      - name: basedpyright
+        run: python -m basedpyright --project pyrightconfig.json
+        working-directory: backend
+      - name: basedpyright baseline is committed
+        run: git diff --exit-code -- backend/.basedpyright/baseline.json
       - name: pytest
         run: python -m pytest
         working-directory: backend

.gitignore

@@ -37,3 +37,7 @@ 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

.nvmrc

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

.python-version

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

CLAUDE.md

@@ -7,17 +7,18 @@ 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
+The local gate is **ruff (`check` + `format --check`) + basedpyright (backend) + 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.
 
 - 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).
+- **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` and burn down epic by epic. Fixed some? Regenerate with `--writebaseline`.
 - New DB-backed test? It must actually run, not silently skip — assume `SIFTLODE_TEST_REQUIRE_DB=1`.
 
 ## Workflow
@@ -45,20 +46,22 @@ 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`, `logs`, `logsink`, `diagnostics`) → `models/db/config`. **Dependency direction is one-way: core never imports routes.**
+`downloads/`, `youtube/`, `issues/` (shared by routes + scheduler + worker) → flat core (`auth`, `quota`,
+`sysconfig`, `state`, `audit`, `notifications`, `userscope`, `realtime`, `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 → `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
@@ -74,29 +77,37 @@ 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 |
-| FE network call         | `req`/`uploadReq`/`beacon`, or `lib/http.ts` `send` (public pages) | a bare `fetch`/`XMLHttpRequest`/`WebSocket` (lint-enforced) |
-| 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 |
+| 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 button                            | `ui/Button` (a `SIZES` rung) · `IconButton` · `Pressable` (a clickable card/row) · `Chip` · `DragHandle`                | a raw `<button>` or `FocusSafeButton` outside the control primitives (lint-enforced) |
+| 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 text field / checkbox / slider    | `ui/Input` · `Textarea` · `InnerInput` in a `fieldClass` frame · `Checkbox`/`CheckRow` · `Slider`                       | a raw `<input>`/`<textarea>` anywhere but those primitives (lint-enforced)           |
+| FE glass surface                     | a role: `SURFACE.panel` / `card` / `menu` / `popover` / `tooltip` (`ui/surfaces.ts`)                                    | a bare `glass`/`glass-card`/`glass-menu` beside a hand-picked radius (lint-enforced) |
+| 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 control                           | `SegmentedToggle`; a long or user's list: `FilterSelect`                                                                | a native `<select>` (lint-enforced)                                                  |
+| FE loading/empty/error               | `QueryState` / `StateMessage`                                                                                           | ad-hoc conditionals                                                                  |
+| FE failed write                      | `meta.failTitle`, else `notifyActionError(err, title)`                                                                  | a bare `catch {}` or `notify()` with no error attached                               |
+| FE network call                      | `req`/`uploadReq`/`beacon`, or `lib/http.ts` `send` (public pages)                                                      | a bare `fetch`/`XMLHttpRequest`/`WebSocket` (lint-enforced)                          |
+| 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+), else a latest-value ref                                                                 | an excused dep list asserting the same thing in prose                                |
+| FE hook suppression                  | an inline `eslint-disable-next-line` NAMING the invariant                                                               | `eslint-suppressions.json` (deliberately absent — E27 S2)                            |
 
 ## House rules that bite (learned from real bugs)
 

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, the CI gate's image and the dev machine 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 ./

VERSION

@@ -1 +1 @@
-0.90.0
+0.97.0

backend/alembic/versions/0088_channels_feed_fallback_at.py

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

backend/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/app/README.md

@@ -13,16 +13,18 @@ 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`, `logs` (the one logging
-   configuration), `logsink` (its `log_events` table) and `diagnostics` (a user's consented log
-   level), … are single-file primitives many layers import. They depend on nothing above them (a core
+   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

backend/app/audit.py

@@ -58,6 +58,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"
+    # E16: 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

@@ -4,7 +4,7 @@ from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 from starlette.requests import HTTPConnection
 
-from app import diagnostics
+from app import debugsession
 from app import email as email_mod
 from app import logs
 from app import mailtext
@@ -14,6 +14,7 @@ from app.db import get_db
 from app.models import Invite, LogEvent, User
 from app.security import decrypt_optional
 from app.utils import canonical_email
+from app.refusal import refused
 
 PASSWORD_MIN_LEN = 10
 
@@ -341,19 +342,19 @@ def current_user(request: Request, db: Session = Depends(get_db)) -> User:
 
 def _session_user(request: Request, db: Session, user_id: int | None, is_default: bool) -> User:
     if not user_id:
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        raise refused(401, "not_authenticated")
     user = db.get(User, user_id)
     if user is None or not user.is_active or user.is_suspended:
         # Suspended/deactivated mid-session → end it so the block takes effect at once.
         _end_account_session(request, user_id, is_default)
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        raise refused(401, "not_authenticated")
     # SA4: reject a cookie whose recorded epoch is behind the account's current one (revoked by a
     # password reset/change or "log out everywhere"). A cookie with no recorded epoch (pre-SA4, or an
     # account signed in before this shipped) is treated as epoch 0 — so the FIRST bump revokes it too.
     epochs = request.session.get("epochs") or {}
     if int(epochs.get(str(user_id), 0)) != (user.session_epoch or 0):
         _end_account_session(request, user_id, is_default)
-        raise HTTPException(status_code=401, detail="Not authenticated")
+        raise refused(401, "not_authenticated")
     # Always keep the session default in the switchable list — covers sessions created before
     # multi-session existed (their account_ids was never seeded), so the switcher isn't empty.
     default_id = request.session.get("user_id")
@@ -366,7 +367,11 @@ def _session_user(request: Request, db: Session, user_id: int | None, is_default
     # 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 (S5).
-    logs.set_user(user.id, diagnostics.effective_level(user), user.diagnostics_until)
+    # So does a debug session the request names (E16): 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
 
@@ -418,10 +423,7 @@ def require_write_scope(user: User = Depends(require_human)) -> User:
     checks that had drifted into three different 403 messages across channels/playlists. Layers on
     `require_human` because writing to YouTube needs a real, non-demo identity."""
     if not has_write_scope(user):
-        raise HTTPException(
-            status_code=403,
-            detail="Enable YouTube editing in Settings first.",
-        )
+        raise refused(403, "youtube_editing_off")
     return user
 
 
@@ -429,7 +431,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 until P1: it declared
+# `file: UploadFile = File(...)`, so an anonymous caller could make the process write the whole
+# per-file allowance to temp before `require_human` 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 since P1 — 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 (deep-review round 1):
+    #   * 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:  # noqa: BLE001 — 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,39 @@
+"""Alphabetical order in the reader's language (E30 S3).
+
+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."""
+
+from typing import Any
+
+from sqlalchemy import SQLColumnExpression, column, func, select, values
+from sqlalchemy.orm import Session
+from sqlalchemy.sql.elements import ColumnElement
+from sqlalchemy.types import String
+
+from app.mailtext import normalize
+
+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)))

backend/app/config.py

@@ -1,7 +1,7 @@
 from pathlib import Path
 from typing import Literal, get_args, get_origin
 
-from pydantic import ValidationInfo, field_validator, 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.
@@ -119,6 +119,9 @@ class Settings(BaseSettings):
     # Recent-first backfill: how far back to fetch on the first pass per channel.
     backfill_recent_max_videos: int = 100
     backfill_recent_max_days: int = 365
+    # A channel whose RSS feed has not answered for this many hours gets its newest uploads read
+    # through the Data API instead (1 unit), at most once per this many hours. 0 = never.
+    rss_fallback_hours: int = 2
 
     # Shorts are confirmed by probing youtube.com/shorts/<id>. Only videos at or below
     # this duration (and not livestreams) are probed; longer videos are never Shorts.
@@ -244,7 +247,11 @@ class Settings(BaseSettings):
     # Per-file cap for local uploads (E7). 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
@@ -312,6 +319,10 @@ class Settings(BaseSettings):
     # re-encode is CPU-heavy (the VAAPI hardware path is far cheaper and could sustain more); direct-serve
     # and remux (stream-copy) are not capped by this.
     plex_max_transcodes: int = 4
+    # Max concurrent playback sessions of ANY kind — remux (stream-copy) included. Cheap on the CPU but
+    # each one is a whole segmented copy of the film on the scratch volume, written faster than
+    # realtime. One account holds at most two regardless (plex/stream.py `_MAX_SESSIONS_PER_USER`).
+    plex_max_sessions: int = 8
     # --- Transcode (playable="transcode") re-encode tuning (E6 S1) ---
     # Hardware-encoder policy: "auto" = VAAPI (h264_vaapi) when the iGPU render node is present AND the
     # source codec is hardware-decodable, else libx264 software; "on" = force VAAPI wherever the render
@@ -344,10 +355,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 (E16): 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 (E30 S6) 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]:

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,
@@ -34,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 (E16): 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 (deep-review round 4). `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/diagnostics.py

@@ -27,6 +27,9 @@ 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 (E16, 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:
@@ -47,6 +50,7 @@ def state(db: Session, user: User) -> dict:
         "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,
     }
 
 

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
 
@@ -73,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(
@@ -103,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
@@ -117,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:
@@ -129,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:
@@ -137,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
 
@@ -159,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
@@ -171,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/pipeline.py

@@ -25,7 +25,7 @@ from app.downloads.jobdb import (
 )
 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
 
@@ -597,7 +597,7 @@ 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)

backend/app/downloads/service.py

@@ -20,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):
@@ -179,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),
     )
@@ -198,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(
@@ -255,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),
     )

backend/app/downloads/upload.py

@@ -25,7 +25,7 @@ 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.models import DownloadJob, MediaAsset, display_text
 
 
 def _title_from_filename(filename: str) -> str:
@@ -99,7 +99,7 @@ def ingest_upload(
             source_kind="upload",
             source_ref=ref,
             profile_snapshot={},
-            display_name=(display_name or "").strip() or None,
+            display_name=display_text(display_name),
             status="done",
             progress=100,
             queue_pos=service.next_queue_pos(db),

backend/app/feedquery.py

@@ -15,6 +15,7 @@ from datetime import date, datetime, timedelta, timezone
 from sqlalchemy import BigInteger, Select, and_, cast, false, func, or_, select
 from sqlalchemy.orm import Session, aliased
 
+from app.collation import collated
 from app.models import (
     LIVE_OR_UPCOMING,
     BlockedChannel,
@@ -478,8 +479,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}],
@@ -491,10 +494,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"}
         ],

backend/app/issues/__init__.py

@@ -0,0 +1,3 @@
+"""Bug reports built from debug sessions (E16): the files an issue carries, and where they go —
+downloaded as a zip, or (S4) 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, plans/e16 S0);
+  * 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 (E16 S4) — measured against Gitea 1.27.1
+before a line of this was written (plans/e16-debug-issue.md, S0).
+
+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 (deep-review round 4).
+    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 (deep-review round 4
+    # 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` (round 4 — 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.
+                # noqa 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

@@ -100,12 +100,14 @@ class _RequestScope:
     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")
+    __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 (E16), else None.
+        self.debug_session_id: str | None = None
 
 
 _scope: contextvars.ContextVar[_RequestScope | None] = contextvars.ContextVar(
@@ -113,11 +115,23 @@ _scope: contextvars.ContextVar[_RequestScope | None] = contextvars.ContextVar(
 )
 
 
-def set_user(user_id: int | None, level: str = "INFO", until: datetime | None = None) -> 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` (E22 S5; "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."""
+    from the request middleware, which runs OUTSIDE the session middleware.
+
+    `debug_session` tags every line with the user's open debug session (E16). 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
@@ -125,9 +139,11 @@ def set_user(user_id: int | None, level: str = "INFO", until: datetime | None =
         _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:
-        _track_elevation(user_id, scope.level, until)
+        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:
@@ -328,6 +344,12 @@ class ContextFilter(logging.Filter):
         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
 
 
@@ -444,7 +466,6 @@ _THIRD_PARTY_LEVELS = {
     "httpx": "WARNING",
     "httpcore": "WARNING",
     "asyncio": "WARNING",
-    "multipart": "WARNING",
     "PIL": "WARNING",
     "alembic": "INFO",
     # uvicorn's own startup/shutdown/WebSocket lines are worth keeping; its ACCESS log is not —
@@ -545,18 +566,21 @@ def current_level() -> str:
 # 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
-# user id → (level number, expiry) for every elevation this process has seen and not yet expired.
-_elevations: dict[int, tuple[int, datetime]] = {}
+# → (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 (E16), 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(user_id: int, level: int | None, until: datetime | 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(user_id, None)
+            _elevations.pop(key, None)
         else:
-            _elevations[user_id] = (level, until)
+            _elevations[key] = (level, until)
         active = bool(_elevations)
     if active or _root_applied != _base_level:
         _apply_root_level()
@@ -573,8 +597,8 @@ def _apply_root_level(force: bool = False) -> None:
     # 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 user_id in [u for u, (_, until) in _elevations.items() if until <= now]:
-            del _elevations[user_id]
+        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)
@@ -611,13 +635,24 @@ def forget_user(user_id: int) -> None:
             del _erased[stale]
         _erased[user_id] = now
     with _elevations_lock:
-        _elevations.pop(user_id, None)
+        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
@@ -644,6 +679,27 @@ _REQUEST_ID_RE = re.compile(r"^[A-Za-z0-9._-]{8,64}$")
 # — 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/messages/unread_count",
+        "/api/downloads",
+        "/api/downloads/index",
+        "/api/downloads/usage",
+        "/api/sync/my-status",
+        "/api/admin/scheduler",
+        "/api/admin/downloads",
+        "/api/admin/downloads/storage",
+        "/api/plex/subtitle/{rating_key}/{sub_ord}/status",
+    }
+)
+
 # Not `siftlode.logs`: this is the replacement for uvicorn's ACCESS log, and `siftlode.http` is
 # what an operator pins a level on when they want request lines and nothing else. The module it
 # happens to live in is not what the name is about.
@@ -689,7 +745,9 @@ async def log_requests(request, call_next):
         raise
     duration_ms = round((time.perf_counter() - started) * 1000, 1)
     status = response.status_code
-    quiet = request.url.path.startswith(_QUIET_PREFIXES)
+    quiet = request.url.path.startswith(_QUIET_PREFIXES) or (
+        request.method == "GET" and _route_template(request) in _POLLED_ROUTES
+    )
     if status >= 500:
         level = logging.ERROR
     elif status >= 400:
@@ -715,6 +773,10 @@ async def log_requests(request, call_next):
         extra={**event("http.request", **attrs), **_request_owner(request, level)},
     )
     response.headers["X-Request-Id"] = rid
+    # The browser logs its own copy of this line (frontend lib/http.ts) and must pick the same level:
+    # it learns "this one is quiet" here instead of keeping a second copy of the polled-route list.
+    if level == logging.DEBUG:
+        response.headers["X-Log-Quiet"] = "1"
     # The template, so the browser's copy of this line groups the same way (frontend lib/http.ts).
     # Only a MATCHED route's: a template never carries a path parameter's value (a share token stays
     # `{token}`), while the raw-path fallback of an unmatched request could — the browser then

backend/app/logsink.py

@@ -44,6 +44,7 @@ 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
@@ -343,3 +344,24 @@ def gc(db: Session, retention_days: int) -> int:
     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 (E22.6) and
+    a debug session's evidence list (E16)."""
+    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/main.py

@@ -23,6 +23,7 @@ from fastapi.staticfiles import StaticFiles
 from sqlalchemy.exc import DataError
 from starlette.middleware.sessions import SessionMiddleware
 
+from app import bodylimit
 from app import logsink
 from app import state
 from app import sysconfig
@@ -37,6 +38,7 @@ from app.routes import (
     auth as auth_routes,
     channels,
     config as config_routes,
+    debug_sessions as debug_sessions_routes,
     diagnostics as diagnostics_routes,
     discover as discover_routes,
     downloads,
@@ -188,15 +190,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")
@@ -216,6 +209,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
@@ -258,7 +279,8 @@ async def security_headers(request, call_next):
 
 # 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 the three above do. Being outermost also puts it OUTSIDE SessionMiddleware,
+# 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)
@@ -273,6 +295,7 @@ 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)

backend/app/models.py

@@ -12,6 +12,7 @@ from sqlalchemy import (
     Index,
     Integer,
     JSON,
+    LargeBinary,
     SmallInteger,
     String,
     Text,
@@ -22,6 +23,34 @@ from sqlalchemy.dialects.postgresql import JSONB, TSVECTOR
 from sqlalchemy.orm import Mapped, mapped_column, relationship, validates
 
 from app.db import Base
+
+# 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
+
+
 from app.utils import canonical_email
 
 
@@ -113,7 +142,7 @@ class User(Base, TimestampMixin, CanonicalEmailMixin):
     # 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(255))
+    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
@@ -241,6 +270,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
@@ -562,7 +594,15 @@ class LogEvent(Base):
     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"),)
+    __table_args__ = (
+        Index("ix_log_events_user_ts", "user_id", "ts"),
+        # E16: 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)
@@ -581,6 +621,52 @@ class LogEvent(Base):
     version: Mapped[str | None] = mapped_column(String(64))
 
 
+class DebugSession(Base):
+    """One recording: Start → reproduce → Stop (E16, 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 (E16 S3; 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 (E16) — 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)."""
 
@@ -895,11 +981,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(
@@ -1138,6 +1224,7 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
     # Hungarian-metadata twin fields, written by the overlay sync (E5 S5). 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 (E30)
     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(
@@ -1299,6 +1386,7 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     # Hungarian-metadata twin fields, written by the overlay sync (E5 S5). 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 (E30)
     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(
@@ -1329,7 +1417,8 @@ 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"
 
@@ -1339,11 +1428,15 @@ class PlexPerson(Base, TimestampMixin, UpdatedAtMixin):
     # 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: 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 (E5 S6): fetched from /person/{tmdb_person_id} by the people_enrich job
+    #     (E30 S6), 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 (E30 S4), 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)

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 (E30): `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/genres.py

@@ -0,0 +1,100 @@
+"""One Hungarian word per Plex genre (E30).
+
+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,6 +8,9 @@ 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
 
@@ -56,6 +59,49 @@ def read(key: str) -> tuple[bytes, str] | None:
     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:

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 (E30 S6) ---------------------------------------------------------------------------
+# 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 (E30 S6), 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"
 
@@ -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:

backend/app/plex/rollup.py

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

backend/app/plex/stream.py

@@ -60,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.
@@ -72,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".
@@ -88,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:
@@ -102,16 +115,17 @@ class HlsSession:
         transcode: bool = False,
         hw: bool = False,
         tonemap: bool = False,
+        user_id: int = 0,
     ):
-        # Unguessable per-session id, carried in the URLs the client is handed. Sessions are keyed
-        # by rating_key alone, so a seek-restart or a SECOND viewer of the same item replaces the
-        # registered one — and the old viewer's next request for `seg_12.ts`, resolved by rating_key,
-        # was answered 200 with the NEW session's twelfth segment, produced from a different offset
+        # Unguessable per-session id, carried in the URLs the client is handed. A seek-restart
+        # replaces the viewer's registered session for the item — and the old player's next request
+        # for `seg_12.ts`, resolved by (viewer, rating_key) alone, was answered 200 with the NEW session's twelfth segment, produced from a different offset
         # under `-copyts`. Wrong bytes, not an error, so the client's reclaim never fired on it
         # (deep-review round 5). A request naming a session that is no longer registered is a 404,
         # which the player recovers from by restarting at the playhead.
         self.id = secrets.token_urlsafe(9)
-        self.key = key
+        self.key = key  # the item's rating_key (what the logs name)
+        self.user_id = user_id  # whose session it is: the registry key is (user_id, key)
         self.dir = directory
         self.proc = proc
         self.transcode = transcode  # video re-encoded (non-h264 source), not stream-copied
@@ -637,29 +651,47 @@ def _kill(s: HlsSession) -> None:
     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]:
-        # Somebody's playback stops here. 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.
-        log.info(
-            "a transcode session was dropped to stay under the cap",
-            extra=logs.event("plex.stream.session_culled", key=key, cap=cap, sessions=len(tx)),
-        )
-        _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,
@@ -679,6 +711,7 @@ def start_session(
     # session respawn (the HW->SW fallback) must not pick up a mid-playback config change.
     loudnorm = sysconfig.get_bool(db, "plex_audio_loudnorm")
     key = item.rating_key
+    reg = (user_id, key)  # the registry key: one session per viewer per item
     start_s = max(0.0, float(start_s))
     audio_langs = _probe_audio_langs(src) if multi else []
     is_multi = len(audio_langs) > 1  # only worth a master playlist when there really are ≥2 tracks
@@ -691,7 +724,7 @@ def start_session(
     # the tag with a DASH — `_SESSION_DIR_RE` treats the tag as one underscore-free field, and that
     # regex is the only thing keeping the orphan sweep off a shared scratch path (see its comment).
     tag = ("multi" if is_multi else str(audio_ord)) + ("-ln" if loudnorm else "")
-    directory = _HLS_ROOT / f"{key}_{int(start_s)}_{tag}_{aoff:+.2f}"
+    directory = _HLS_ROOT / f"{key}_u{user_id}_{int(start_s)}_{tag}_{aoff:+.2f}"
 
     def _seg(i: int) -> Path:
         return directory / segment_name(i, _VIDEO_VARIANT if variants else None)
@@ -717,9 +750,9 @@ def start_session(
         # platform without fork (the API always runs in a Linux container in prod) it's simply omitted.
         preexec = _sw_child_preexec if (transcode and not hw and os.name == "posix") else None
         with _lock:
-            if replace_only is not None and _sessions.get(key) is not replace_only:
+            if replace_only is not None and _sessions.get(reg) is not replace_only:
                 return None  # superseded/culled while we waited out of lock — don't clobber the newer one
-            old = _sessions.pop(key, None)
+            old = _sessions.pop(reg, None)
             if old is not None:
                 _kill(old)
             shutil.rmtree(directory, ignore_errors=True)
@@ -753,8 +786,9 @@ def start_session(
                 transcode=transcode,
                 hw=hw,
                 tonemap=tonemap,
+                user_id=user_id,
             )
-            _sessions[key] = s
+            _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.
@@ -770,9 +804,13 @@ def start_session(
                     start_s=round(start_s, 1),
                 ),
             )
-            # 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")))
+            # 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")),
+            )
         return s
 
     s = _spawn(*_select_encode(db, item, transcode, src))
@@ -798,7 +836,7 @@ def start_session(
             # turns a None return into a "Media file not found on disk" 404 — dishonest for a file that
             # exists. A (dead) session instead degrades to a retryable 404 ("No active playback session" /
             # "Not available yet") the client re-requests.
-            return current_session(key) or s
+            return current_session(user_id, key) or s
         s = respawned
         ready = wait_for(_seg(0), timeout=25.0, proc=s.proc)
     if ready:
@@ -829,9 +867,9 @@ def start_session(
     return s
 
 
-def current_session(key: str) -> HlsSession | None:
+def current_session(user_id: int, key: str) -> HlsSession | None:
     with _lock:
-        s = _sessions.get(key)
+        s = _sessions.get((user_id, key))
         if s is not None:
             s.last_access = time.time()
         return s
@@ -1060,21 +1098,21 @@ def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
     now = time.time()
     dropped = 0
     with _lock:
-        for key, s in list(_sessions.items()):
+        for reg, s in list(_sessions.items()):
             done = s.proc.poll() is not None
             idle = now - s.last_access
             if idle > _SESSION_IDLE_S or (done and idle > finished_idle_s):
                 _kill(s)
-                _sessions.pop(key, None)
+                _sessions.pop(reg, None)
                 dropped += 1
     return dropped
 
 
-def touch_session(key: str) -> None:
-    """Say a viewer is still there for `key`, without fetching anything. `last_access` used to move
+def touch_session(user_id: int, key: str) -> None:
+    """Say this viewer is still there for `key`, without fetching anything. `last_access` used to move
     only on an HLS file fetch, which a paused player does not do — so the only way to keep a paused
     viewer's session alive was to keep EVERY abandoned one just as long."""
     with _lock:
-        s = _sessions.get(key)
+        s = _sessions.get((user_id, key))
         if s is not None:
             s.last_access = time.time()

backend/app/plex/subtitles.py

@@ -32,6 +32,7 @@ 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 re
 import subprocess
@@ -217,7 +218,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:
@@ -461,11 +466,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).
@@ -515,6 +527,7 @@ def reset_state() -> None:
     global _STOPPING
     with _LOCK:
         _INFLIGHT.clear()
+        _FULL_OWNERS.clear()
         _FAILURES.clear()
         _FULL_FAILED.clear()
         _WIN_FAILED.clear()
@@ -598,7 +611,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``
@@ -641,8 +654,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]:
@@ -659,7 +687,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
@@ -692,8 +725,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
@@ -757,6 +797,8 @@ def _run(
     finally:
         with _LOCK:
             _INFLIGHT.pop(ident, None)
+            if ident[0] == "full":
+                _FULL_OWNERS.pop(rating_key, None)
 
 
 def _pass_failed(
@@ -822,10 +864,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
@@ -846,15 +891,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)
@@ -884,9 +1022,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).

backend/app/plex/sync.py

@@ -15,6 +15,7 @@ dead `enabled` column) is a separate follow-up. Cast + intro/credit markers are
 item-detail/player path (P2), not here.
 """
 
+from collections.abc import Iterable
 from datetime import datetime, timezone
 
 from sqlalchemy import func, select
@@ -24,6 +25,7 @@ from app import logs, sysconfig
 from app.models import PlexCollection, PlexItem, PlexLibrary, PlexSeason, PlexShow
 from app.plex import detail, people
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+from app.plex.genres import hu_genres
 from app.plex.lookups import by_rating_key
 
 log = logs.get_logger(__name__)
@@ -448,6 +450,10 @@ 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
@@ -659,35 +665,72 @@ 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.
+    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 (E30): 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: 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),
+        passes = [
+            (
+                _TYPE_MOVIE,
+                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
+        passes = [
+            (
+                _TYPE_SHOW,
+                select(PlexShow).where(
+                    PlexShow.library_id == en_lib_id, PlexShow.guid.is_not(None)
+                ),
+            ),
+            (
+                _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] = {}
+    by_guid: dict[str, list[PlexItem | PlexShow]] = {}
     for r in rows:
-        by_guid.setdefault(r.guid, []).append(r)
+        if r.guid:  # the passes select guid-bearing rows only
+            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.
+    # 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".
+    episodes = item_type == _TYPE_EPISODE
     for group in by_guid.values():
         for row in group:
-            row.title_hu = row.summary_hu = row.genres_hu = None
+            row.title_hu = row.summary_hu = None
+            if not episodes:
+                row.tagline_hu = None
+                row.genres_hu = hu_genres(row.genres)
     seen: set[str] = (
         set()
     )  # first HU entry for a guid wins; a dup HU item can't overwrite or double-count
@@ -699,13 +742,15 @@ def _sync_overlay(
         seen.add(g)
         title_hu = (meta.get("title") or "").strip() or None
         summary_hu = meta.get("summary")
-        genres_hu = _tags(meta, "Genre")
+        tagline_hu = (meta.get("tagline") or "").strip() or None
+        genres_hu = hu_genres(_tags(meta, "Genre"))
         for row in targets:
             row.title_hu = title_hu
             row.summary_hu = summary_hu
-            row.genres_hu = genres_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
-    db.flush()
 
 
 def _upsert_collection(

backend/app/plex/tmdb.py

@@ -10,8 +10,10 @@ 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 re
 import time
 from datetime import datetime, timezone
+from typing import cast
 
 import httpx
 from sqlalchemy import func, select
@@ -21,6 +23,8 @@ from sqlalchemy.orm import Session
 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 = logs.get_logger(__name__)
 # Politeness throttle: TMDB tolerates ~50 req/s; ~33/s leaves comfortable headroom for a shared host.
@@ -124,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 (E5 S6) + the bio's translations (E30 S4), 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:
@@ -254,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 (E30): 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,
@@ -301,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 = (
@@ -356,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}`. A row enriched before E30 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 countries stored before E30 (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 (E30 S6): 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(
@@ -406,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` (E30); one we lack keeps the title TMDB gave."""
     if not recs:
         return []
     movies, shows = resolve_library_guids(db, recs)
@@ -417,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:
@@ -437,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
+# 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; E30 S6).
+_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
@@ -470,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,
@@ -479,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"]
@@ -490,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:
@@ -502,7 +623,7 @@ 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)
+            _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.
@@ -515,9 +636,41 @@ def enrich_person(db: Session, person: PlexPerson) -> bool:
             ),
         )
         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 (E30 S6), 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/quota.py

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

backend/app/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

@@ -6,13 +6,16 @@ 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 sqlalchemy.orm import Session
 
 from app.db import Base
 from app.models import User
+from app.issues import gitea
+from app.refusal import refused
+from app.youtube.client import YouTubeError, refusal_reason
 
 M = TypeVar("M", bound=Base)
 
@@ -25,10 +28,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 +48,98 @@ 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) -> HTTPException:
+    """The answer to an action YouTube refused: a 422 whose reason the UI translates
+    (`errors.youtube.<reason>`). One definition, because the routes had grown three shapes of it —
+    a bare English string quoting the upstream message, a playlist-scoped reason, and nothing at
+    all (a raw 500 from the manual syncs). The upstream failure is already logged where it
+    happened (`youtube.api.error`). A failure that is not the Data API's (the search scraper's) is
+    YouTube being unavailable to us — the retryable answer."""
+    reason = refusal_reason(exc) if isinstance(exc, YouTubeError) else "unavailable"
+    return HTTPException(status_code=422, detail={"code": "youtube", "reason": reason})
+
+
+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 (E16) 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

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

backend/app/routes/admin_logs.py

@@ -26,10 +26,11 @@ from fastapi import APIRouter, Depends, HTTPException, Query
 from sqlalchemy import Text, and_, cast, func, or_, select
 from sqlalchemy.orm import Session
 
+from app import logsink
 from app.auth import admin_user
 from app.db import get_db
 from app.models import LogEvent, User
-from app.utils import iso, like_escape
+from app.utils import like_escape
 
 router = APIRouter(prefix="/api/admin/logs", tags=["admin"])
 
@@ -66,25 +67,6 @@ def _decode_cursor(cursor: str) -> tuple[datetime, int]:
         raise HTTPException(status_code=400, detail={"code": "bad_cursor"}) from exc
 
 
-def _serialize(row: LogEvent) -> dict:
-    return {
-        "id": row.id,
-        "ts": iso(row.ts),
-        "level": row.level,
-        "source": row.source,
-        "logger": row.logger,
-        "event": row.event,
-        "msg": row.msg,
-        "attrs": row.attrs,
-        "exc": row.exc,
-        "request_id": row.request_id,
-        "user_id": row.user_id,
-        "job_id": row.job_id,
-        "debug_session_id": row.debug_session_id,
-        "version": row.version,
-    }
-
-
 def _accounts(db: Session, user_ids: set[int]) -> dict[str, str]:
     """The accounts a page names, by id → address. An id with no account left (erased after the
     line was written) is simply absent, and the client shows the bare id."""
@@ -196,7 +178,7 @@ def list_logs(
     more = len(rows) > limit
     rows = rows[:limit]
     return {
-        "items": [_serialize(r) for r in rows],
+        "items": [logsink.serialize(r) for r in rows],
         "accounts": _accounts(db, {r.user_id for r in rows if r.user_id is not None}),
         "next_cursor": _encode_cursor(rows[-1]) if more else None,
     }

backend/app/routes/audit.py

@@ -66,6 +66,12 @@ def list_audit(
 def clear_audit(admin: User = Depends(admin_user), db: Session = Depends(get_db)) -> dict:
     """Clear the audit log. Leaves ONE row recording who cleared it + how many (tamper-evidence)."""
     n = db.execute(delete(AuditLog)).rowcount or 0
-    audit.record(db, admin.id, AuditAction.AUDIT_CLEAR, summary=f"Cleared {n} audit entries")
+    audit.record(
+        db,
+        admin.id,
+        AuditAction.AUDIT_CLEAR,
+        summary=f"Cleared {n} audit entries",
+        after={"cleared": n},  # the count as data: the log names it in the reader's language
+    )
     db.commit()
-    return {"cleared": n}
+    return {"ok": True, "cleared": n}

backend/app/routes/auth.py

@@ -39,10 +39,11 @@ from app.auth import (
 )
 from app.config import settings
 from app.db import SessionLocal, get_db
-from app.models import AuthToken, DemoWhitelist, Invite, OAuthToken, User
+from app.models import AuthToken, DemoWhitelist, Invite, OAuthToken, User, display_text
 from app.ratelimit import RateLimiter, client_key
 from app.security import encrypt, hash_password, hash_token, verify_password
 from app.utils import canonical_email, valid_email
+from app.refusal import refused
 
 VERIFY_TTL = timedelta(hours=24)
 # A confirmation link that rides an APPROVAL or an invitation lives longer than one the person is
@@ -378,7 +379,7 @@ async def callback(
 
     userinfo = token.get("userinfo")
     if not userinfo or not userinfo.get("sub"):
-        raise HTTPException(status_code=400, detail="No user info returned by Google")
+        raise refused(400, "google_no_userinfo")
 
     sub = userinfo["sub"]
     email = (userinfo.get("email") or "").lower()
@@ -471,7 +472,7 @@ async def callback(
     if email:
         user.google_email = email
     _sync_google_email(db, user, email)
-    user.display_name = userinfo.get("name")
+    user.display_name = display_text(userinfo.get("name"))
     user.avatar_url = userinfo.get("picture")
     # ADMIN_EMAILS (env) is the bootstrap admin list and always wins, so the configured admin can't
     # be locked out. Everyone else's role is managed in the admin UI and stored in the DB, so a
@@ -593,7 +594,7 @@ def _complete_link(
     if linked_email:
         user.google_email = linked_email  # see the sign-in callback: the other half of the identity
     if not user.display_name:
-        user.display_name = userinfo.get("name")
+        user.display_name = display_text(userinfo.get("name"))
     if not user.avatar_url:
         user.avatar_url = userinfo.get("picture")
     _store_token(db, user, token)
@@ -653,15 +654,15 @@ async def request_access(
     endpoint can't be probed for throttling either."""
     email = (body.email or "").strip().lower()
     if not valid_email(email):
-        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+        raise refused(400, "invalid_email")
     if not _request_access_limiter.allow(client_key(request)):
-        return {"status": "pending"}
+        return {"ok": True, "status": "pending"}
     if is_allowed(db, email):
-        return {"status": "pending"}  # already allowed — don't reveal it
+        return {"ok": True, "status": "pending"}  # already allowed — don't reveal it
     req = upsert_pending_invite(db, email, body.lang)
     if req.is_new:
         notify_admins_of_request(db, background, email)
-    return {"status": "pending"}
+    return {"ok": True, "status": "pending"}
 
 
 @router.post("/demo")
@@ -672,7 +673,7 @@ def demo_login(body: EmailIn, request: Request, db: Session = Depends(get_db)) -
     exactly like a non-match (authenticated=false) so the field can't be hammered as an
     enumeration oracle. On a match it sets the session and the client reloads into the app."""
     if not _demo_limiter.allow(client_key(request)):
-        return {"authenticated": False}
+        return {"ok": True, "authenticated": False}
     email = (body.email or "").strip().lower()
     if valid_email(email) and is_demo_allowed(db, email):
         demo = get_or_create_demo_user(db)
@@ -683,8 +684,8 @@ def demo_login(body: EmailIn, request: Request, db: Session = Depends(get_db)) -
         _remember_epoch(request, demo)
         # The demo key IS an address, so it is not in the line — see the denied branch above.
         log.info("signed in", extra=logs.event("auth.login.ok", method="demo", uid=demo.id))
-        return {"authenticated": True}
-    return {"authenticated": False}
+        return {"ok": True, "authenticated": True}
+    return {"ok": True, "authenticated": False}
 
 
 def _establish_session(request: Request, user: User) -> None:
@@ -815,23 +816,20 @@ def register(
     password = body.password or ""
     # Input validation is safe to reveal (independent of whether the email exists).
     if not valid_email(email):
-        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+        raise refused(400, "invalid_email")
     if len(password) < PASSWORD_MIN_LEN:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Password must be at least {PASSWORD_MIN_LEN} characters.",
-        )
+        raise refused(400, "weak_password", min=PASSWORD_MIN_LEN)
     if not sysconfig.get_bool(db, "allow_registration"):
-        raise HTTPException(status_code=403, detail="Registration is currently closed.")
+        raise refused(403, "registration_closed")
     if not _register_limiter.allow(client_key(request)):
-        return {"status": "ok"}  # silently throttle; uniform response
+        return {"ok": True, "status": "ok"}  # silently throttle; uniform response
 
     # Do the existence check + account creation OFF the response path (a background task with its own
     # session). The create path hashes the password + writes several rows + schedules emails; doing it
     # inline would make a NEW email respond measurably slower than an already-registered one (which
     # skips all that) — a timing oracle for enumeration. Off-path, any valid email responds the same.
     background.add_task(_register_account, email, password, body.lang)
-    return {"status": "ok"}
+    return {"ok": True, "status": "ok"}
 
 
 def _register_account(email: str, password: str, lang: str | None = None) -> None:
@@ -997,11 +995,11 @@ def verify_email_resend(
     mail had no way back. Uniform response + timing regardless of whether the email has a pending
     account (the lookup runs off the response path), so it can't probe for registered emails."""
     if not _verify_resend_limiter.allow(client_key(request)):
-        return {"status": "ok"}  # silently throttle; uniform response
+        return {"ok": True, "status": "ok"}  # silently throttle; uniform response
     email = (body.email or "").strip().lower()
     if valid_email(email):
         background.add_task(_resend_verify_if_eligible, email)
-    return {"status": "ok"}
+    return {"ok": True, "status": "ok"}
 
 
 def _resend_verify_if_eligible(email: str) -> None:
@@ -1091,14 +1089,14 @@ def password_reset_request(
     """Request a password-reset link. Uniform response + timing regardless of whether the email has a
     password account (the lookup runs off the response path), so it can't probe for registered emails."""
     if not _reset_limiter.allow(client_key(request)):
-        return {"status": "ok"}
+        return {"ok": True, "status": "ok"}
     email = (body.email or "").strip().lower()
     # Do the account lookup + token issue + email OFF the response path (a background task with its
     # own session), so the endpoint takes the same time for any valid email whether or not it has a
     # password account — no timing-based enumeration. Any valid email schedules the same task.
     if valid_email(email):
         background.add_task(_send_reset_if_eligible, email)
-    return {"status": "ok"}
+    return {"ok": True, "status": "ok"}
 
 
 def _send_reset_if_eligible(email: str) -> None:
@@ -1293,13 +1291,10 @@ def set_password(
         raise HTTPException(status_code=403, detail={"code": "demo"})
     new_password = body.password or ""
     if len(new_password) < PASSWORD_MIN_LEN:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Password must be at least {PASSWORD_MIN_LEN} characters.",
-        )
+        raise refused(400, "weak_password", min=PASSWORD_MIN_LEN)
     if user.password_hash:
         if not verify_password(body.current_password or "", user.password_hash):
-            raise HTTPException(status_code=403, detail="Current password is incorrect.")
+            raise refused(403, "wrong_password")
     user.password_hash = hash_password(new_password)
     user.password_revoked_at = None  # same as the reset path: a password exists again
     # SA4: a password change logs out every OTHER session; re-stamp this cookie at the new epoch so

backend/app/routes/channels.py

@@ -4,11 +4,13 @@ hidden, tags) and per-channel sync state. Local reads/writes plus YouTube-side w
 
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from fastapi import APIRouter, BackgroundTasks, Depends
 from pydantic import BaseModel
 from sqlalchemy import func, select, update
 from sqlalchemy.orm import Session
 
+from app.collation import collated, sorted_words
+from app.mailtext import lang_for_user
 from app import logs, quota
 from app.auth import admin_user, current_user, require_human, require_write_scope
 from app.db import get_db
@@ -25,12 +27,13 @@ from app.models import (
     User,
     Video,
 )
-from app.routes._common import get_or_404, not_found, owned_or_404
+from app.routes._common import get_or_404, not_found, owned_or_404, youtube_refusal
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import backfill_channel_now, run_recent_backfill
-from app.sync.subscriptions import apply_channel_details
+from app.sync.subscriptions import apply_channel_details, details_stale
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/channels", tags=["channels"])
 
@@ -43,7 +46,7 @@ def list_channels(user: User = Depends(current_user), db: Session = Depends(get_
         select(Subscription, Channel)
         .join(Channel, Channel.id == Subscription.channel_id)
         .where(Subscription.user_id == user.id)
-        .order_by(Subscription.priority.desc(), func.lower(Channel.title))
+        .order_by(Subscription.priority.desc(), collated(Channel.title, lang_for_user(user)))
     ).all()
 
     # Per-channel aggregates over the shared catalog in ONE grouped pass: stored count, last
@@ -138,7 +141,7 @@ def _discovery_rows(db: Session, user: User) -> list:
     return db.execute(
         q.group_by(Channel.id).order_by(
             func.count(func.distinct(PlaylistItem.video_id)).desc(),
-            func.lower(Channel.title),
+            collated(Channel.title, lang_for_user(user)),
         )
     ).all()
 
@@ -189,12 +192,16 @@ def discover_channels(
                 quota.attribute(user.id, quota.QuotaAction.CHANNELS_DISCOVER),
                 YouTubeClient(db, user) as yt,
             ):
-                apply_channel_details(db, yt.get_channels(need))
+                apply_channel_details(db, yt.get_channels(need), need)
             db.commit()
-            # Match _discovery_rows' ORDER BY exactly: video-count DESC, then title (NULLs LAST,
-            # as Postgres orders them — coercing NULL→"" would wrongly float untitled channels up).
+            # Match _discovery_rows' ORDER BY exactly: video-count DESC, then title in the reader's
+            # alphabet (NULLs LAST, as Postgres orders them — coercing NULL→"" would wrongly float
+            # untitled channels up).
+            titles = [r[0].title for r in rows if r[0].title is not None]
+            alpha = {w: i for i, w in enumerate(sorted_words(db, titles, lang_for_user(user)))}
             rows = sorted(
-                rows, key=lambda r: (-int(r[1]), r[0].title is None, (r[0].title or "").lower())
+                rows,
+                key=lambda r: (-int(r[1]), r[0].title is None, alpha.get(r[0].title or "", 0)),
             )
         except YouTubeError as exc:
             log.warning(
@@ -295,17 +302,20 @@ def channel_detail(
     """One channel's "About" detail for the channel page header/About tab, plus this user's
     relationship to it (subscribed / explored) and how many of its videos are in the catalog.
     Lazily fills the About metadata (view count, join date, banner, links) the first time it's
-    needed — a stub, or a channel last enriched before those fields existed (published_at is a
-    reliable sentinel: every real channel has a creation date). The enrich uses the API key
-    (1 unit, cached after), so it's skipped for the quota-less demo account."""
+    needed (a stub) and refreshes it once it is stale (`DETAILS_MAX_AGE`), which is how a channel nobody subscribes to (an explored one, outside the
+    subscription import) gets a banner that still resolves. The enrich uses the API key (1 unit,
+    cached after), so it's skipped for the quota-less demo account."""
     channel = get_or_404(db, Channel, channel_id, what="channel")
-    if channel.published_at is None and not user.is_demo:
+    # No `published_at is None` sentinel: a terminated channel never gets one, so it re-fetched on
+    # every view; rows enriched before that field existed are long past DETAILS_MAX_AGE anyway.
+    stale = details_stale(channel, datetime.now(timezone.utc))
+    if stale and not user.is_demo:
         try:
             with (
                 quota.attribute(user.id, quota.QuotaAction.CHANNELS_DISCOVER),
                 YouTubeClient(db, user) as yt,
             ):
-                apply_channel_details(db, yt.get_channels([channel_id]))
+                apply_channel_details(db, yt.get_channels([channel_id]), [channel_id])
             db.commit()
             channel = db.get(Channel, channel_id)
         except YouTubeError as exc:
@@ -383,12 +393,9 @@ def explore_channel(
     backfill quota reserve; blocked for the demo account (it spends shared quota)."""
     channel = get_or_404(db, Channel, channel_id, what="channel")
     if _is_blocked(db, user, channel_id):
-        raise HTTPException(status_code=403, detail="You've blocked this channel.")
+        raise refused(403, "channel_blocked")
     if quota.backfill_reserve_reached():
-        raise HTTPException(
-            status_code=429,
-            detail="The shared daily quota reserve is reached — try exploring later.",
-        )
+        raise refused(429, "quota_reserve")
 
     # Record/refresh the exploration (DB only) before ingesting, so the explorer can see the
     # videos as soon as they land. Flag the channel ephemeral unless it's organically followed.
@@ -414,18 +421,17 @@ def explore_channel(
             YouTubeClient(db, user) as yt,
         ):
             # Enrich for the About panel + the uploads playlist id (needed to ingest videos).
-            if (
-                channel.details_synced_at is None
-                or channel.uploads_playlist_id is None
-                or channel.published_at is None
-            ):
-                apply_channel_details(db, yt.get_channels([channel_id]))
+            # Stale, not "a field is missing": a terminated channel never gets an uploads playlist
+            # or a creation date, and asking again on every explore would spend quota on a miss.
+            if details_stale(channel, datetime.now(timezone.utc)):
+                apply_channel_details(db, yt.get_channels([channel_id]), [channel_id])
                 db.commit()
                 channel = db.get(Channel, channel_id)
             result = explore_ingest_page(db, yt, channel, page_token)
     except YouTubeError as exc:
-        raise HTTPException(status_code=422, detail=f"YouTube couldn't load this channel: {exc}")
+        raise youtube_refusal(exc)
     return {
+        "ok": True,
         "channel_id": channel_id,
         "ingested": result["ingested"],
         "next_page_token": result["next_page_token"],
@@ -507,6 +513,7 @@ def update_channel(
         background.add_task(backfill_channel_now, channel_id, user.id)
 
     return {
+        "ok": True,
         "id": channel_id,
         "priority": sub.priority,
         "hidden": sub.hidden,
@@ -541,7 +548,7 @@ def reset_backfill(
     db.commit()
     with quota.attribute(user.id, quota.QuotaAction.VIDEOS_BACKFILL_RECENT):
         run_recent_backfill(db, [channel], max_channels=1)
-    return {"id": channel_id, "reset": True}
+    return {"ok": True, "id": channel_id, "reset": True}
 
 
 @router.post("/{channel_id}/subscribe")
@@ -562,7 +569,7 @@ def subscribe(
         )
     ).scalar_one_or_none()
     if existing is not None:
-        raise HTTPException(status_code=409, detail="Already subscribed to this channel.")
+        raise refused(409, "already_subscribed")
     with (
         quota.attribute(user.id, quota.QuotaAction.CHANNELS_SUBSCRIBE),
         YouTubeClient(db, user) as yt,
@@ -583,16 +590,14 @@ def subscribe(
             if "subscriptionDuplicate" in exc.reason.split(","):
                 yt_sub_id = ""
             else:
-                raise HTTPException(
-                    status_code=422, detail=f"YouTube couldn't subscribe you: {exc}"
-                )
+                raise youtube_refusal(exc)
         # Enrich a stub channel (title/thumbnail/subscriber count) so it shows up properly right
         # away, on BOTH the normal and the desync path — a resurfaced stub still needs metadata to
         # render. Keep the client open (we're still inside the `with`); a metadata failure here
         # must not block recording the subscription the user asked for.
         if channel.details_synced_at is None:
             try:
-                apply_channel_details(db, yt.get_channels([channel_id]))
+                apply_channel_details(db, yt.get_channels([channel_id]), [channel_id])
             except YouTubeError as exc:
                 log.warning(
                     "subscribe: stub enrich failed: %s",
@@ -622,7 +627,7 @@ def subscribe(
             .values(via_explore=False)
         )
     db.commit()
-    return {"subscribed": channel_id}
+    return {"ok": True, "subscribed": channel_id}
 
 
 @router.delete("/{channel_id}/subscription")
@@ -636,10 +641,7 @@ def unsubscribe(
     should Hide instead."""
     sub = _user_subscription(db, user, channel_id)
     if not sub.yt_subscription_id:
-        raise HTTPException(
-            status_code=400,
-            detail="No YouTube subscription id on record — sync subscriptions first.",
-        )
+        raise refused(400, "no_subscription_id")
     try:
         with (
             quota.attribute(user.id, quota.QuotaAction.CHANNELS_UNSUBSCRIBE),
@@ -649,10 +651,10 @@ def unsubscribe(
     except YouTubeError as exc:
         # 422 (a real, explainable error → speaking modal), not 502 which the client treats as
         # a transient "connection lost" gateway blip.
-        raise HTTPException(status_code=422, detail=f"YouTube couldn't unsubscribe you: {exc}")
+        raise youtube_refusal(exc)
     db.delete(sub)
     db.commit()
-    return {"unsubscribed": channel_id}
+    return {"ok": True, "unsubscribed": channel_id}
 
 
 @router.get("/blocked/list")
@@ -663,7 +665,7 @@ def list_blocked(user: User = Depends(current_user), db: Session = Depends(get_d
             select(Channel)
             .join(BlockedChannel, BlockedChannel.channel_id == Channel.id)
             .where(BlockedChannel.user_id == user.id)
-            .order_by(func.lower(Channel.title))
+            .order_by(collated(Channel.title, lang_for_user(user)))
         )
         .scalars()
         .all()
@@ -693,7 +695,7 @@ def block_channel(
             )
         )
         db.commit()
-    return {"blocked": channel_id}
+    return {"ok": True, "blocked": channel_id}
 
 
 @router.delete("/{channel_id}/block")
@@ -708,7 +710,7 @@ def unblock_channel(
         )
     )
     db.commit()
-    return {"unblocked": channel_id}
+    return {"ok": True, "unblocked": channel_id}
 
 
 class AttachTagIn(BaseModel):
@@ -743,7 +745,7 @@ def attach_tag(
             )
         )
         db.commit()
-    return {"channel_id": channel_id, "tag_id": body.tag_id}
+    return {"ok": True, "channel_id": channel_id, "tag_id": body.tag_id}
 
 
 @router.delete("/{channel_id}/tags/{tag_id}")
@@ -763,4 +765,4 @@ def detach_tag(
     if row is not None:
         db.delete(row)
         db.commit()
-    return {"channel_id": channel_id, "tag_id": tag_id}
+    return {"ok": True, "channel_id": channel_id, "tag_id": tag_id}

backend/app/routes/config.py

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

backend/app/routes/debug_sessions.py

@@ -0,0 +1,418 @@
+"""Debug sessions (E16): Start → reproduce → Stop, the screenshots, and the evidence under review.
+
+The session itself — what tags a request, its cap, its level — is `app/debugsession.py`. These routes
+are the user's handle on their OWN sessions only: another user's id 404s (`owned_or_404`), including
+for an admin, who reads everyone's lines in the diagnostics console instead. The shared demo account
+cannot record: its log would interleave every visitor under one account.
+
+Screenshots arrive as a raw image body (`image/png`, `image/jpeg`, `image/webp`), not a multipart
+form — one image per request, capped while it arrives, and kept only if its bytes really are one of
+those types, whatever the Content-Type claimed.
+"""
+
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from app import audit, debugsession, logs, logsink
+from app.audit import AuditAction
+from app.auth import require_human
+from app.db import get_db, release_read_connection
+from app.issues import bundle, gitea
+from app.ratelimit import RateLimiter
+from app.refusal import refused
+from app.models import DebugScreenshot, DebugSession, User
+from app.routes._common import capped_body, issue_refused, not_found, owned_or_404
+from app.utils import iso
+
+router = APIRouter(prefix="/api/debug-sessions", tags=["diagnostics"])
+log = logs.get_logger(__name__)
+
+# Sessions listed in Settings → Diagnosztika, newest first: enough to reach last week's unsent draft.
+LIST_MAX = 20
+
+
+class StartIn(BaseModel):
+    level: debugsession.SessionLevel
+
+
+_view = debugsession.view
+
+# New sessions a user may open per hour (joining the running one is not counted): a session is a
+# place to keep screenshots, and this — with the per-user storage cap — bounds how many there are.
+_new_sessions = RateLimiter(max_events=20, window_seconds=3600)
+
+
+@router.post("")
+def start_session(
+    body: StartIn,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Start recording, or join the recording already running (another tab started it)."""
+    joining = debugsession.open_session(db, user) is not None
+    if not joining and not _new_sessions.allow(str(user.id)):
+        raise refused(429, "debug_session_rate_limited", limit=_new_sessions.max_events)
+    try:
+        session = debugsession.start(db, user, body.level)
+        db.commit()
+    except IntegrityError:
+        # A concurrent Start won the one-open-per-user index: join that one.
+        db.rollback()
+        session = debugsession.open_session(db, user)
+        if session is None:
+            raise refused(409, "debug_session_conflict") from None
+    # The rest of THIS request is part of the session too.
+    level, until = debugsession.level_for(user, session)
+    logs.set_user(user.id, level, until, session.id)
+    log.info(
+        "debug session started",
+        extra=logs.event("debug.session.started", level=session.level, until=iso(session.until)),
+    )
+    return {"ok": True, "session": _view(db, session)}
+
+
+@router.post("/{sid}/stop")
+def stop_session(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> dict:
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    if session.ended_at is None:
+        # Logged BEFORE the session closes, while this request still carries its tag: the last line
+        # of the evidence is the Stop itself.
+        log.info("debug session stopped", extra=logs.event("debug.session.stopped"))
+        debugsession.stop(session)
+        db.commit()
+        logs.end_session_elevation(session.id)
+    return {"ok": True, "session": _view(db, session)}
+
+
+@router.get("")
+def list_sessions(user: User = Depends(require_human), db: Session = Depends(get_db)) -> dict:
+    sessions = db.scalars(
+        select(DebugSession)
+        .where(DebugSession.user_id == user.id)
+        .order_by(DebugSession.started_at.desc())
+        .limit(LIST_MAX)
+    ).all()
+    return {"items": [_view(db, s) for s in sessions]}
+
+
+@router.get("/{sid}")
+def get_session(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> dict:
+    return _view(db, owned_or_404(db, DebugSession, sid, user, what="debug_session"))
+
+
+@router.get("/{sid}/events")
+def session_events(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> dict:
+    """The rows an issue from this session would carry — browser and server, in time order."""
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    rows, total = debugsession.bundle(db, session)
+    return {"items": [logsink.serialize(r) for r in rows], "total": total}
+
+
+# --- the draft and its export ---------------------------------------------------------------
+# The composer's own fields (steps, description…) are its business, kept whole so it reopens as it
+# was — bounded here so a draft cannot become a place to store anything else.
+FORM_MAX_BYTES = 64 * 1024
+# Zips a user may build per minute: each holds every screenshot in memory while it is built.
+_exports = RateLimiter(max_events=6, window_seconds=60)
+
+
+class DraftIn(BaseModel):
+    title: str = Field(max_length=200)
+    # The rendered markdown the export and the issue carry.
+    body: str = Field(max_length=50_000)
+    # Log rows taken out of the evidence in the review.
+    excluded: list[int] = Field(default_factory=list, max_length=debugsession.BUNDLE_MAX)
+    form: dict[str, Any] = Field(default_factory=dict)
+
+
+@router.put("/{sid}/draft")
+def save_draft(
+    sid: str,
+    body: DraftIn,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    if len(json.dumps(body.form, ensure_ascii=False).encode()) > FORM_MAX_BYTES:
+        raise HTTPException(status_code=413, detail={"code": "too_large"})
+    # Under the lock, and refused while a send is under way: the issue is being built from the draft
+    # as it was saved, and this would change it under the send.
+    debugsession.lock(db, session)
+    if debugsession.sending(session):
+        raise refused(409, "issue_sending")
+    if session.issue_url is not None:
+        # Sent: the issue is on the tracker now, and a draft edited after it would say otherwise.
+        raise refused(409, "issue_already_sent")
+    debugsession.save_draft(session, body.model_dump())
+    db.commit()
+    return {"ok": True, "session": _view(db, session)}
+
+
+@router.get("/{sid}/export")
+def export_session(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> Response:
+    """The issue as a zip — the text, the two logs and the screenshots — for an instance without an
+    issue tracker, or for sending it by hand. Built from the SAVED draft: what the composer shows is
+    what it saved."""
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    if not _exports.allow(str(user.id)):
+        raise refused(429, "export_rate_limited")
+    data = bundle.zipped(bundle.files(db, session))
+    name = f"siftlode-debug-{session.started_at:%Y%m%d-%H%M}-{session.id[:6]}.zip"
+    return Response(
+        content=data,
+        media_type="application/zip",
+        headers={
+            "Content-Disposition": f'attachment; filename="{name}"',
+            "Cache-Control": "no-store",
+        },
+    )
+
+
+# --- the issue tracker (S4) -----------------------------------------------------------------
+# Issues a user may open per hour — counted once the tracker is ASKED to open one (an answer that
+# goes missing may still have created it, so an attempt cannot be given back); finishing a half-sent
+# one, or an attempt refused before the tracker was asked, is not counted. The composer sends one at
+# a time; this is room for a bad afternoon, not a pace anything legitimate keeps up.
+_new_issues = RateLimiter(max_events=5, window_seconds=3600)
+# Attempts on the tracker per hour, creating or finishing. Deliberately NOT the budget above: a
+# half-sent issue must always be finishable, so the pace that guards creating one must never be what
+# stands between a user and their own report. This one only bounds a loop — every attempt re-reads
+# the whole bundle into memory and re-offers the pending file to the tracker, and a retry that is
+# refused for good (the tracker's own limits) never leaves `pending`. No hand reaches it.
+_sends = RateLimiter(max_events=60, window_seconds=3600)
+# The composer's live preview, rendered BY the tracker: one authenticated call each, with our token.
+# The composer's toggle fires it once per switch INTO preview — the editor is the other branch, so
+# no keystroke can change the query key while the preview is up — and react-query's cache makes an
+# unchanged draft free. (It does NOT debounce, whatever this comment used to say: a key that changes
+# per keystroke is one fetch per keystroke, measured. Showing the preview BESIDE the fields would
+# need a real debounce first.) This bounds what a loop can aim at the tracker.
+_previews = RateLimiter(max_events=60, window_seconds=60)
+
+
+def _issues_rate_limited() -> HTTPException:
+    return refused(429, "issues_rate_limited", limit=_new_issues.max_events)
+
+
+@router.post("/{sid}/issue")
+def send_issue(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> dict:
+    """Send the session's issue to the tracker — from the SAVED draft, as the export is built — or
+    finish a send that stopped half-way (the issue exists; only what is missing is sent)."""
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    # The session is CLAIMED for the send rather than locked through it: the tracker is slow (a
+    # dozen calls, 20 s each), and a row lock held across them would queue this user's Stop, their
+    # autosave and their screenshots behind it. They see the claim instead and are refused at once.
+    debugsession.lock(db, session)
+    if debugsession.sending(session):
+        raise refused(409, "issue_sending")
+    new = session.issue_url is None
+    if not new and not debugsession.unfinished(session):
+        return {"ok": True, "session": _view(db, session)}
+    key = str(user.id)
+    if new:
+        if not ((session.draft or {}).get("title") or "").strip():
+            raise refused(422, "issue_title_required")
+        if _new_issues.exhausted(key):
+            raise _issues_rate_limited()
+    if not _sends.allow(key):
+        raise refused(429, "issue_rate_limited", limit=_sends.max_events)
+    token = debugsession.claim_send(session)
+    db.commit()  # the claim is what everything else sees; the lock ends here
+
+    def count_new_issue() -> None:
+        if not _new_issues.allow(key):
+            raise _issues_rate_limited()
+
+    try:
+        gitea.deliver(
+            db,
+            session,
+            token=token,
+            checkpoint=db.commit,
+            before_create=count_new_issue,
+            on_created=lambda: _record_created(db, user, session),
+        )
+    except debugsession.SendClaimLost:
+        # This send outlived its lease and another one took the session over while it was still
+        # talking to the tracker. It stopped rather than writing over that one's progress — and a
+        # send IS under way, just not ours, which is what the caller needs to hear.
+        raise refused(409, "issue_sending") from None
+    except gitea.GiteaError as exc:
+        # Keep what did happen: an issue created before an upload failed stays linked, and the
+        # retry does only what is still missing.
+        raise issue_refused(exc) from None
+    except HTTPException:
+        raise  # the pace, refused before the tracker was asked
+    finally:
+        _end_send(db, session, token)
+    return {"ok": True, "session": _view(db, session)}
+
+
+def _end_send(db: Session, session: DebugSession, token: str) -> None:
+    """Give the claim back, whatever else happened. A failure here must not replace the failure that
+    brought us: a dead transaction (the database went away mid-send) is rolled back, and the claim
+    then simply ages out."""
+    try:
+        debugsession.lock(db, session)
+        debugsession.release_send(session, token)
+        db.commit()
+    except Exception:  # noqa: BLE001 — whatever went wrong here, the send's own failure is the news
+        db.rollback()
+        log.warning(
+            "a send could not give its claim back",
+            extra=logs.event("issues.claim.stuck", session_id=session.id),
+        )
+
+
+def _record_created(db: Session, user: User, session: DebugSession) -> None:
+    """The trail for the one act that takes a user's log off this instance. Staged inside the send,
+    so the checkpoint that first writes `issue_url` commits BOTH — recorded later it could be lost
+    on its own (the process dies mid-send), and no retry could write it afterwards: the next send
+    sees the link and knows the issue is not new."""
+    audit.record(
+        db,
+        user.id,
+        AuditAction.ISSUE_CREATE,
+        target_type="debug_session",
+        target_id=session.id,
+        summary=session.issue_url or "",
+    )
+
+
+class PreviewIn(BaseModel):
+    text: str = Field(max_length=50_000)
+
+
+@router.post("/{sid}/preview")
+def preview_issue(
+    sid: str,
+    body: PreviewIn,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The body as the tracker will render it. Gitea sanitises its own output; the composer still
+    shows it in a sandboxed frame, never in the app's own document."""
+    owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    if not _previews.allow(str(user.id)):
+        raise refused(429, "preview_rate_limited")
+    try:
+        return {"ok": True, "html": gitea.preview(db, body.text)}
+    except gitea.GiteaError as exc:
+        raise issue_refused(exc) from None
+
+
+# --- screenshots ---------------------------------------------------------------------------
+def _shot_view(shot: DebugScreenshot) -> dict:
+    return {"id": shot.id, "mime": shot.mime, "size": shot.size, "created_at": iso(shot.created_at)}
+
+
+@router.get("/{sid}/screenshots")
+def list_screenshots(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> dict:
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    return {"items": [_shot_view(s) for s in debugsession.screenshots(db, session)]}
+
+
+def _upload_target(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> DebugSession:
+    return owned_or_404(db, DebugSession, sid, user, what="debug_session")
+
+
+async def _image_body(request: Request, db: Session = Depends(get_db)) -> bytes:
+    # The owner check above has already run, and it was a SELECT — so this session is holding a
+    # pooled connection `idle in transaction` and would hold it for the whole 10 MiB upload, from a
+    # client that may be on a phone. Hand it back first; the handler's own work re-takes one. The
+    # `session` object the handler holds is expired by this and reloads on its next attribute read,
+    # which is the correct moment to touch the database again.
+    release_read_connection(db)
+    return await capped_body(request, debugsession.SCREENSHOT_MAX_BYTES)
+
+
+@router.post("/{sid}/screenshots")
+def add_screenshot(
+    # The owner check FIRST: dependencies resolve in order, so a stranger's upload is refused
+    # before a byte of it is read.
+    session: DebugSession = Depends(_upload_target),
+    data: bytes = Depends(_image_body),
+    db: Session = Depends(get_db),
+) -> dict:
+    try:
+        shot = debugsession.add_screenshot(db, session, data)
+    except debugsession.ScreenshotRefused as exc:
+        raise _screenshot_refused(exc.code) from None
+    db.commit()
+    return {"ok": True, "screenshot": _shot_view(shot)}
+
+
+def _screenshot_refused(code: str) -> HTTPException:
+    # Literal reasons, one per case: the frontend's contract test reads them to require a sentence
+    # for each in both languages.
+    if code == "already_sent":
+        return refused(409, "screenshot_already_sent")
+    if code == "too_many":
+        return refused(422, "screenshot_too_many", limit=debugsession.SCREENSHOTS_MAX)
+    if code == "sending":
+        return refused(409, "issue_sending")
+    if code == "storage_full":
+        mb = debugsession.SCREENSHOT_USER_MAX_BYTES // (1024 * 1024)
+        return refused(422, "screenshot_storage_full", limit=mb)
+    if code == "empty":
+        return refused(422, "screenshot_empty")
+    return refused(422, "screenshot_not_an_image")
+
+
+def _session_screenshot(db: Session, sid: str, shot_id: int, user: User) -> DebugScreenshot:
+    return _screenshot_of(
+        db, owned_or_404(db, DebugSession, sid, user, what="debug_session"), shot_id
+    )
+
+
+def _screenshot_of(db: Session, session: DebugSession, shot_id: int) -> DebugScreenshot:
+    shot = db.get(DebugScreenshot, shot_id)
+    if shot is None or shot.session_id != session.id:
+        raise not_found("screenshot")
+    return shot
+
+
+@router.get("/{sid}/screenshots/{shot_id}")
+def get_screenshot(
+    sid: str, shot_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> Response:
+    shot = _session_screenshot(db, sid, shot_id, user)
+    # `nosniff`: the type was checked against the bytes at upload, and the browser must not guess.
+    return Response(
+        content=shot.data,
+        media_type=shot.mime,
+        headers={"Cache-Control": "private, max-age=3600", "X-Content-Type-Options": "nosniff"},
+    )
+
+
+@router.delete("/{sid}/screenshots/{shot_id}")
+def delete_screenshot(
+    sid: str, shot_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> dict:
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    shot = _screenshot_of(db, session, shot_id)
+    try:
+        debugsession.remove_screenshot(db, session, shot)
+    except debugsession.ScreenshotRefused as exc:
+        raise _screenshot_refused(exc.code) from None
+    db.commit()
+    return {"ok": True, "deleted": shot_id}

backend/app/routes/diagnostics.py

@@ -13,7 +13,9 @@ Nothing from the body is trusted as-is:
   * everything is redacted AGAIN with the server's own rules — the client redacts at capture, but a
     modified client would not;
   * an event below the consented level is dropped (a Részletes consent does not store what only
-    Teljes may carry), and so is the whole batch once the level has lapsed;
+    Teljes may carry), and so is the whole batch once the level has lapsed — where an open debug
+    session the request names counts as consent to ITS level (E16), and only its own events keep
+    its tag;
   * the timestamp is clamped to the consent window, so a row cannot dodge the retention job by
     claiming to come from the future.
 """
@@ -27,11 +29,12 @@ from pydantic import BaseModel, Field, ValidationError
 from sqlalchemy import insert
 from sqlalchemy.orm import Session
 
-from app import diagnostics, logs, logsink
+from app import debugsession, diagnostics, logs, logsink
 from app.auth import current_user
-from app.db import get_db
-from app.models import LogEvent, User
+from app.db import get_db, release_read_connection
+from app.models import DebugSession, LogEvent, User
 from app.ratelimit import RateLimiter
+from app.routes._common import capped_body
 
 router = APIRouter(prefix="/api/diagnostics", tags=["diagnostics"])
 
@@ -60,6 +63,9 @@ class ClientEvent(BaseModel):
     attrs: dict[str, Any] | None = None
     request_id: str | None = Field(default=None, pattern=r"^[A-Za-z0-9._-]{8,64}$")
     tab_id: str | None = Field(default=None, pattern=r"^[A-Za-z0-9_-]{1,32}$")
+    # The debug session the event was captured in (E16); kept only when it is the one this request
+    # names in `X-Debug-Session` and the auth dependency found it the caller's own and open.
+    debug_session_id: str | None = Field(default=None, pattern=r"^[0-9a-f]{16}$")
     version: str | None = Field(default=None, max_length=64)
 
 
@@ -67,19 +73,7 @@ class ClientEventsIn(BaseModel):
     events: list[ClientEvent] = Field(max_length=EVENTS_MAX)
 
 
-async def _capped_body(request: Request) -> bytes:
-    """The request body, refused the moment it passes BODY_MAX_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) > BODY_MAX_BYTES:
-            raise HTTPException(status_code=413, detail={"code": "too_large"})
-    return bytes(body)
-
-
-async def _parsed_events(request: Request) -> ClientEventsIn:
+async def _parsed_events(request: Request, db: Session = Depends(get_db)) -> ClientEventsIn:
     """The body as the model — parsed only after the size cap, which is why this is a dependency and
     not a plain body parameter (FastAPI reads a declared body in full before anything else runs).
 
@@ -89,14 +83,24 @@ async def _parsed_events(request: Request) -> ClientEventsIn:
     media_type = request.headers.get("content-type", "").split(";")[0].strip().lower()
     if media_type != "application/json" and not media_type.endswith("+json"):
         raise HTTPException(status_code=415, detail={"code": "json_required"})
-    raw = await _capped_body(request)
+    # `current_user` resolved above on a SELECT, so this session is holding a pooled connection.
+    # Give it back before awaiting the body — the sink is a background beacon and its sender may be
+    # on a link far slower than the 512 KiB suggests. See `db.release_read_connection`.
+    release_read_connection(db)
+    raw = await capped_body(request, BODY_MAX_BYTES)
     try:
         return ClientEventsIn.model_validate_json(raw)
     except ValidationError as exc:
         raise HTTPException(status_code=422, detail=json.loads(exc.json())) from exc
 
 
-def _row(item: ClientEvent, user: User, now: datetime, window_start: datetime) -> dict[str, Any]:
+def _row(
+    item: ClientEvent,
+    user: User,
+    now: datetime,
+    window_start: datetime,
+    session: DebugSession | None,
+) -> dict[str, Any]:
     attrs = logs.redact(item.attrs) if item.attrs else None
     if attrs is not None:
         size = len(json.dumps(attrs, ensure_ascii=False, default=str).encode())
@@ -117,6 +121,9 @@ def _row(item: ClientEvent, user: User, now: datetime, window_start: datetime) -
             "attrs": attrs,
             "request_id": item.request_id,
             "user_id": user.id,
+            "debug_session_id": (
+                session.id if session and item.debug_session_id == session.id else None
+            ),
             "version": item.version,
         }
     )
@@ -126,11 +133,15 @@ def _row(item: ClientEvent, user: User, now: datetime, window_start: datetime) -
 def ingest_events(
     # The account first: dependencies resolve in order, so an anonymous caller is refused before a
     # byte of its body is read.
+    request: Request,
     user: User = Depends(current_user),
     body: ClientEventsIn = Depends(_parsed_events),
     db: Session = Depends(get_db),
 ) -> dict:
-    level = diagnostics.effective_level(user)
+    # A debug session the request names raises the level for its own events (E16): starting one is
+    # the consent to that level for its duration, whatever the user's own level is.
+    session = debugsession.from_header(db, user, request.headers.get(debugsession.HEADER))
+    level, _ = debugsession.level_for(user, session)
     if level == diagnostics.BASE:
         # Lapsed or withdrawn: the client stops streaming when it sees this.
         raise HTTPException(status_code=409, detail={"code": "diagnostics_off"})
@@ -140,7 +151,7 @@ def ingest_events(
     window_start = now - timedelta(hours=diagnostics.ELEVATION_HOURS)
     floor = logs.SEVERITY[level]
     rows = [
-        _row(item, user, now, window_start)
+        _row(item, user, now, window_start, session)
         for item in body.events
         if logs.SEVERITY[item.level] >= floor
     ]

backend/app/routes/discover.py

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

backend/app/routes/downloads.py

@@ -9,20 +9,24 @@ serves finished files (range-aware, with the user's custom display name), and sh
 import os
 import re
 import tempfile
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from urllib.parse import parse_qs, urlparse
+from urllib.parse import parse_qs, unquote, urlparse
 
-from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app.mailtext import lang_for_user
+from app.collation import collated
 from app import audit, sysconfig
 from app.auth import admin_user, require_human
 from app.config import settings
-from app.db import get_db
+from app.db import get_db, release_read_connection
 from app.downloads import credentials as dlcreds
 from app.downloads import edit as editmod
 from app.downloads import links as linksmod
@@ -37,11 +41,13 @@ from app.models import (
     DownloadShare,
     MediaAsset,
     User,
+    display_text,
 )
-from app.routes._common import get_or_404, not_found
+from app.routes._common import capped_stream_to, get_or_404, not_found, owned_or_404
 from app.security import hash_password
 from app.userscope import is_messageable_user, messageable_clauses
 from app.utils import iso
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/downloads", tags=["downloads"])
 admin_router = APIRouter(prefix="/api/admin/downloads", tags=["admin-downloads"])
@@ -63,7 +69,7 @@ def resolve_source(raw: str) -> tuple[str, str]:
     as a raw URL for yt-dlp's generic extractor."""
     raw = (raw or "").strip()
     if not raw:
-        raise HTTPException(status_code=400, detail="A video link or id is required.")
+        raise refused(400, "link_required")
     if _VIDEO_ID.match(raw):
         return "youtube", raw
     if raw.startswith(("http://", "https://")):
@@ -93,7 +99,7 @@ def resolve_source(raw: str) -> tuple[str, str]:
             if _VIDEO_ID.match(vid):
                 return "youtube", vid
         return "url", raw
-    raise HTTPException(status_code=400, detail="That doesn't look like a valid video link.")
+    raise refused(400, "invalid_link")
 
 
 def _serialize(job: DownloadJob, asset: MediaAsset | None) -> dict:
@@ -166,15 +172,8 @@ def _serialize_job(db: Session, job: DownloadJob) -> dict:
     return _serialize(job, asset)
 
 
-def _own_job(db: Session, user: User, job_id: int) -> DownloadJob:
-    job = db.get(DownloadJob, job_id)
-    if job is None or job.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown download")
-    return job
-
-
 def _own_job_for_update(db: Session, user: User, job_id: int) -> DownloadJob:
-    """`_own_job` for a transition that moves its asset's ref count (resume, cancel, delete, redownload)
+    """The ownership check (`owned_or_404`) for a transition that moves its asset's ref count (resume, cancel, delete, redownload)
     or writes the status those decide on (pause). The job is re-read under a row lock, so two
     overlapping requests for one job run one after the other and the second decides on the first's
     committed result — never both releasing the same hold, and never a pause turning a job a cancel
@@ -183,7 +182,7 @@ def _own_job_for_update(db: Session, user: User, job_id: int) -> DownloadJob:
     The asset is locked BEFORE the job: the order a finishing worker child takes them in
     (`service.finalize_if_running`), so the two can never deadlock."""
     while True:
-        asset_id = _own_job(db, user, job_id).asset_id
+        asset_id = owned_or_404(db, DownloadJob, job_id, user, what="download").asset_id
         if asset_id is not None:
             db.execute(select(MediaAsset.id).where(MediaAsset.id == asset_id).with_for_update())
         job = db.execute(
@@ -193,7 +192,7 @@ def _own_job_for_update(db: Session, user: User, job_id: int) -> DownloadJob:
             .execution_options(populate_existing=True)
         ).scalar_one_or_none()
         if job is None:
-            raise HTTPException(status_code=404, detail="Unknown download")
+            raise not_found("download")
         if job.asset_id == asset_id:
             return job
         db.rollback()  # another request moved the job to another asset meanwhile: lock that one
@@ -240,7 +239,7 @@ def create_profile(
     name = body.name.strip()
     spec = body.spec
     if not name:
-        raise HTTPException(status_code=400, detail="A profile name is required.")
+        raise refused(400, "profile_name_required")
     maxpos = db.execute(
         select(func.coalesce(func.max(DownloadProfile.sort_order), 100)).where(
             DownloadProfile.user_id == user.id
@@ -268,16 +267,16 @@ def update_profile(
 ) -> dict:
     p = db.get(DownloadProfile, profile_id)
     if p is None or p.is_builtin or p.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown profile")
+        raise not_found("profile")
     sent = body.model_fields_set
     if "name" in sent:
         name = (body.name or "").strip()
         if not name:
-            raise HTTPException(status_code=400, detail="A profile name is required.")
+            raise refused(400, "profile_name_required")
         p.name = name[:80]
     if "spec" in sent:
         if body.spec is None:
-            raise HTTPException(status_code=400, detail="spec must be an object")
+            raise refused(400, "spec_not_object")
         p.spec = body.spec
     db.commit()
     return _serialize_profile(p)
@@ -289,7 +288,7 @@ def delete_profile(
 ) -> dict:
     p = db.get(DownloadProfile, profile_id)
     if p is None or p.is_builtin or p.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown profile")
+        raise not_found("profile")
     db.delete(p)
     db.commit()
     return {"deleted": profile_id}
@@ -319,7 +318,7 @@ def set_credential(
     """Store (encrypted) this user's cookies.txt for one supported host. Write-only: the value is
     never echoed back, logged, or audited — only the fact that it changed."""
     if not dlcreds.is_supported_host(host_key):
-        raise HTTPException(status_code=404, detail="Unknown host")
+        raise not_found("host")
     try:
         cleaned = dlcreds.validate_cookies(body.cookies)
     except dlcreds.InvalidCookies as e:
@@ -341,7 +340,7 @@ def delete_credential(
     host_key: str, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
     if not dlcreds.is_supported_host(host_key):
-        raise HTTPException(status_code=404, detail="Unknown host")
+        raise not_found("host")
     if dlcreds.delete_credential(db, user.id, host_key):
         audit.record(
             db,
@@ -362,7 +361,7 @@ def _resolve_spec(
     if profile_id is not None:
         p = db.get(DownloadProfile, profile_id)
         if p is None or (not p.is_builtin and p.user_id != user.id):
-            raise HTTPException(status_code=404, detail="Unknown profile")
+            raise not_found("profile")
         return p.spec, p.id
     if spec is not None:
         return spec, None
@@ -373,7 +372,7 @@ def _resolve_spec(
         .limit(1)
     ).scalar_one_or_none()
     if fallback is None:
-        raise HTTPException(status_code=400, detail="No download profile available.")
+        raise refused(400, "no_profile")
     return fallback.spec, fallback.id
 
 
@@ -404,7 +403,7 @@ def enqueue_download(
                 status_code=422, detail={"code": "url_blocked", "reason": e.reason}
             ) from e
     spec, profile_id = _resolve_spec(db, user, body.profile_id, body.spec)
-    display_name = (body.display_name or "").strip() or None
+    display_name = display_text(body.display_name)
     try:
         job = service.enqueue(db, user.id, source_kind, source_ref, spec, profile_id, display_name)
     except quota.QuotaExceeded as e:
@@ -412,61 +411,119 @@ def enqueue_download(
     return _serialize_job(db, job)
 
 
-# Read the upload in 1 MiB chunks so a large file never sits fully in memory, and the size cap is
-# enforced on the ACTUAL bytes read (a client-set Content-Length can't be trusted to gate it).
-_UPLOAD_CHUNK = 1024 * 1024
+# The upload's filename and display name travel as HEADERS, not as multipart parts. That is not a
+# style choice: a DECLARED body parameter (`file: UploadFile = File(...)`) is read and spooled by
+# FastAPI *before the first dependency runs*, so `require_human` could not gate it and an anonymous
+# caller could make the process write the whole per-file allowance to temp, per request (P1; SEC-20
+# bounded the number but could not stop the writing). Reading the body ourselves, from a dependency
+# declared AFTER the auth one, is the only shape that closes it — the same one
+# `POST /api/debug-sessions/{sid}/screenshots` uses, and `test_body_limit.py` now enforces it for
+# every route with a raised ceiling rather than leaving it to a comment like this one.
+#
+# Headers are latin-1 on the wire, so both are percent-encoded by the client and unquoted here; a
+# Hungarian filename would otherwise be unsendable.
+UPLOAD_FILENAME_HEADER = "x-upload-filename"
+UPLOAD_DISPLAY_NAME_HEADER = "x-upload-display-name"
 
 
-@router.post("/upload")
-def upload_download(
-    file: UploadFile = File(...),
-    display_name: str | None = Form(None),
+@dataclass(frozen=True)
+class SpooledUpload:
+    """What the body dependency hands the handler: the bytes already on disk, plus the two names
+    that came alongside them."""
+
+    path: Path
+    size: int
+    user_id: int
+    filename: str
+    display_name: str | None
+
+
+def _header_text(request: Request, name: str) -> str:
+    """One percent-encoded header, decoded. A header that is not valid UTF-8 once unquoted is the
+    caller's doing, not a server fault — it degrades to empty rather than 500ing, and the route's
+    own fallback names the file."""
+    raw = request.headers.get(name, "")
+    try:
+        return unquote(raw, errors="strict").strip()
+    except (UnicodeDecodeError, ValueError):
+        # silent-ok: a mis-encoded header is the caller's own malformed request, and this one is
+        # cosmetic — it names the file. Refusing the upload over it would fail a 500 MiB transfer on
+        # a label; logging it would hand any client a free log line per request.
+        return ""
+
+
+async def spool_upload(
+    request: Request,
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
-) -> dict:
-    """Ingest a local file into the caller's library (E7 S5). Any file type is accepted; media
-    (video/audio) gets the full function set, a generic file is download-only. The file is streamed
-    to a temp path under the download volume (enforcing the per-file cap as it goes), then handed to
-    the non-yt-dlp ingest which probes + places it and returns an already-`done` job.
+) -> AsyncIterator[SpooledUpload]:
+    """Stream the request body to a staging temp file, enforcing the per-file cap as it arrives.
 
-    A sync (threadpool) handler on purpose: the ingest does blocking work — an ffprobe of up to 30s
-    plus sync DB writes — so it must NOT run on the event loop. `file.file` is the sync file object
-    Starlette spools the multipart body into."""
+    `user` is taken but unused: it is the whole point. Dependencies resolve in declaration order, so
+    naming `require_human` here makes the auth check a precondition of reading the body at all — a
+    stranger is refused before a byte moves. The `yield` shape owns the temp file's life: ingest
+    MOVES it into place on success (the unlink is then a no-op), and on any other exit — cap hit,
+    empty, quota, probe or move error, a client that vanished mid-upload — it is removed."""
     cap = sysconfig.get_int(db, "download_upload_max_bytes")
+    user_id = user.id
+    # Hand the pooled connection back BEFORE the transfer starts — see `db.release_read_connection`
+    # for why, and for the precondition it enforces. Everything this dependency still needs is
+    # already an int or a header in hand: touching an ORM attribute below would reload `user` and
+    # check a connection straight back out.
+    release_read_connection(db)
     staging = Path(settings.download_root) / ".staging" / "uploads"
     staging.mkdir(parents=True, exist_ok=True)
     fd, tmp = tempfile.mkstemp(dir=str(staging))
     tmp_path = Path(tmp)
     try:
-        size = 0
         with os.fdopen(fd, "wb") as out:
-            while chunk := file.file.read(_UPLOAD_CHUNK):
-                size += len(chunk)
-                if cap and size > cap:
-                    raise HTTPException(
-                        status_code=422, detail={"code": "upload_too_large", "limit": cap}
-                    )
-                out.write(chunk)
-        if size == 0:
-            raise HTTPException(status_code=400, detail={"code": "upload_empty"})
-        try:
-            job = uploadmod.ingest_upload(
-                db,
-                user.id,
-                filename=file.filename or "upload",
-                src_path=tmp_path,
-                size=size,
-                display_name=(display_name or "").strip() or None,
+            size = await capped_stream_to(
+                request,
+                out,
+                cap,
+                HTTPException(status_code=422, detail={"code": "upload_too_large", "limit": cap}),
             )
-        except quota.QuotaExceeded as e:
-            raise HTTPException(status_code=422, detail=_quota_detail(e))
-        return _serialize_job(db, job)
+        yield SpooledUpload(
+            path=tmp_path,
+            size=size,
+            user_id=user_id,
+            filename=_header_text(request, UPLOAD_FILENAME_HEADER) or "upload",
+            display_name=display_text(_header_text(request, UPLOAD_DISPLAY_NAME_HEADER)),
+        )
     finally:
-        # Ingest MOVES the temp file into place on success (unlink is then a no-op); on any early exit
-        # — cap hit, empty, quota, probe/move error — this removes the abandoned staging file.
         tmp_path.unlink(missing_ok=True)
 
 
+@router.post("/upload")
+def upload_download(
+    upload: SpooledUpload = Depends(spool_upload),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Ingest a local file into the caller's library (E7 S5). Any file type is accepted; media
+    (video/audio) gets the full function set, a generic file is download-only. The body IS the file
+    (see the header note above); `spool_upload` has already authenticated the caller and streamed it
+    to a temp path under the download volume, so what is left here is the non-yt-dlp ingest which
+    probes + places it and returns an already-`done` job.
+
+    A sync (threadpool) handler on purpose: the ingest does blocking work — an ffprobe of up to 30s
+    plus sync DB writes — so it must NOT run on the event loop. The streaming half is async because
+    reading the body is; keeping them in separate callables is what lets each run where it belongs."""
+    if upload.size == 0:
+        raise HTTPException(status_code=400, detail={"code": "upload_empty"})
+    try:
+        job = uploadmod.ingest_upload(
+            db,
+            upload.user_id,
+            filename=upload.filename,
+            src_path=upload.path,
+            size=upload.size,
+            display_name=upload.display_name,
+        )
+    except quota.QuotaExceeded as e:
+        raise HTTPException(status_code=422, detail=_quota_detail(e))
+    return _serialize_job(db, job)
+
+
 class EnqueueEditIn(BaseModel):
     source_job_id: int = 0
     edit_spec: dict
@@ -484,9 +541,9 @@ def enqueue_edit(
     source file is only read, never modified, so editing a shared video is safe."""
     source_job = _accessible_job(db, user, body.source_job_id)
     if source_job.status != "done" or source_job.asset_id is None:
-        raise HTTPException(status_code=409, detail="You can only edit a finished download.")
+        raise refused(409, "edit_unfinished")
     spec = body.edit_spec
-    display_name = (body.display_name or "").strip() or None
+    display_name = display_text(body.display_name)
     try:
         job = service.enqueue_edit(db, user.id, source_job, spec, display_name)
     except quota.QuotaExceeded as e:
@@ -522,7 +579,20 @@ def list_downloads(
 
 @router.get("/usage")
 def my_usage(user: User = Depends(require_human), db: Session = Depends(get_db)) -> dict:
-    return quota.usage(db, user.id)
+    """The caller's download quota, plus the per-file upload cap.
+
+    The cap rides here rather than in `quota.usage` because it is not a quota value — it is a
+    `sysconfig` knob about one route — and this is the route layer, where composing the two is the
+    job. The upload dialog needs it to refuse an over-cap file BEFORE sending it: both server-side
+    caps answer too late to be pleasant (the edge ceiling refuses the request outright, see
+    `bodylimit.ROUTE_MAX_BODY_BYTES`), and making the user push 600 MB up the wire to be told the
+    limit is 500 is a bad answer even when it is a correct one. It is a convenience, not the
+    boundary: the caps stay where they are and still refuse a client that ignores this.
+    """
+    return {
+        **quota.usage(db, user.id),
+        "upload_max_bytes": sysconfig.get_int(db, "download_upload_max_bytes"),
+    }
 
 
 # Priority when a source has several jobs (e.g. a done one plus a fresh queued one).
@@ -614,12 +684,12 @@ def update_download_meta(
 ) -> dict:
     """Update a download's display metadata: title, channel name + link, and extra reference URLs.
     All are display-only overrides — the on-disk file keeps its system-decided, id-bound name."""
-    job = _own_job(db, user, job_id)
+    job = owned_or_404(db, DownloadJob, job_id, user, what="download")
     sent = body.model_fields_set
     if "display_name" in sent:
-        job.display_name = ((body.display_name or "").strip())[:255] or None
+        job.display_name = display_text(body.display_name)
     if "display_uploader" in sent:
-        job.display_uploader = ((body.display_uploader or "").strip())[:255] or None
+        job.display_uploader = display_text(body.display_uploader)
     if "display_uploader_url" in sent:
         job.display_uploader_url = _clean_url(body.display_uploader_url)
     if "extra_links" in sent:
@@ -668,9 +738,9 @@ def redownload_download(
     if job.job_kind in ("edit", "upload"):
         # Neither has a re-fetchable source: an editor clip is derived locally, an upload IS the
         # source. Re-running yt-dlp against source_kind='upload'/'edit' would just fail.
-        raise HTTPException(status_code=409, detail="This item can't be re-downloaded.")
+        raise refused(409, "not_redownloadable")
     if job.status in ("queued", "running", "paused"):
-        raise HTTPException(status_code=409, detail="This download is still in progress.")
+        raise refused(409, "still_downloading")
     service.redownload(db, job)
     return _serialize_job(db, job)
 
@@ -699,7 +769,7 @@ def delete_download(
 def _accessible_job(db: Session, user: User, job_id: int) -> DownloadJob:
     job = db.get(DownloadJob, job_id)
     if job is None:
-        raise HTTPException(status_code=404, detail="Unknown download")
+        raise not_found("download")
     if job.user_id == user.id:
         return job
     shared = db.execute(
@@ -708,7 +778,7 @@ def _accessible_job(db: Session, user: User, job_id: int) -> DownloadJob:
         )
     ).first()
     if shared is None:
-        raise HTTPException(status_code=404, detail="Unknown download")
+        raise not_found("download")
     return job
 
 
@@ -722,10 +792,10 @@ def download_file(
     job = _accessible_job(db, user, job_id)
     asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
     if asset is None or asset.status != "ready" or not asset.rel_path:
-        raise HTTPException(status_code=409, detail="This download isn't ready.")
+        raise refused(409, "download_not_ready")
     path = storage.safe_abs_path(settings.download_root, asset.rel_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="File is no longer available.")
+        raise not_found("file")
 
     filename = storage.download_filename(
         job.display_name or asset.title or asset.source_ref, asset.container, path
@@ -764,7 +834,7 @@ def storyboard_meta(
     job = _accessible_job(db, user, job_id)
     asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
     if asset is None or asset.status != "ready" or not asset.rel_path:
-        raise HTTPException(status_code=409, detail="This download isn't ready.")
+        raise refused(409, "download_not_ready")
     meta = editmod.ensure_storyboard(asset, settings.download_root)
     if meta is None:
         return {"available": False}
@@ -785,10 +855,10 @@ def poster_image(job_id: int, user: User = Depends(require_human), db: Session =
     job = _accessible_job(db, user, job_id)
     asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
     if asset is None or not asset.poster_path:
-        raise HTTPException(status_code=404, detail="No poster.")
+        raise not_found("poster")
     path = storage.safe_abs_path(settings.download_root, asset.poster_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="No poster.")
+        raise not_found("poster")
     return FileResponse(path, media_type="image/jpeg")
 
 
@@ -799,10 +869,10 @@ def storyboard_image(
     job = _accessible_job(db, user, job_id)
     asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
     if asset is None or not asset.storyboard_path:
-        raise HTTPException(status_code=404, detail="No filmstrip.")
+        raise not_found("filmstrip")
     path = storage.safe_abs_path(settings.download_root, asset.storyboard_path)
     if path is None:
-        raise HTTPException(status_code=404, detail="No filmstrip.")
+        raise not_found("filmstrip")
     return FileResponse(path, media_type="image/jpeg")
 
 
@@ -820,12 +890,12 @@ def share_download(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    job = _own_job(db, user, job_id)
+    job = owned_or_404(db, DownloadJob, job_id, user, what="download")
     if job.status != "done" or job.asset_id is None:
-        raise HTTPException(status_code=409, detail="Only a finished download can be shared.")
+        raise refused(409, "share_unfinished")
     target = body.email.strip().lower()
     if not target:
-        raise HTTPException(status_code=400, detail="A recipient email is required.")
+        raise refused(400, "recipient_required")
     recipient = db.execute(
         select(User).where(func.lower(User.email) == target)
     ).scalar_one_or_none()
@@ -834,7 +904,7 @@ def share_download(
     if not is_messageable_user(recipient):
         raise not_found("recipient")
     if recipient.id == user.id:
-        raise HTTPException(status_code=400, detail="That's already your download.")
+        raise refused(400, "share_own")
     exists = db.execute(
         select(DownloadShare.id).where(
             DownloadShare.job_id == job_id, DownloadShare.to_user_id == recipient.id
@@ -849,11 +919,18 @@ def share_download(
             user_id=recipient.id,
             type="download_shared",
             title=(job.display_name or "A download") + " was shared with you",
-            data={"kind": "download_shared", "from": user.email, "job_id": job_id},
+            # The client names the notice in the reader's language from `data` (E30); the title is the
+            # English fallback only.
+            data={
+                "kind": "download_shared",
+                "from": user.email,
+                "job_id": job_id,
+                "title": job.display_name,
+            },
             commit=False,
         )
         db.commit()
-    return {"shared_with": recipient.email}
+    return {"ok": True, "shared_with": recipient.email}
 
 
 @router.delete("/{job_id}/share/{email}")
@@ -863,7 +940,9 @@ def unshare_download(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    _own_job(db, user, job_id)  # ownership guard (404s if not the caller's job)
+    owned_or_404(
+        db, DownloadJob, job_id, user, what="download"
+    )  # ownership guard (404s if not the caller's job)
     recipient = db.execute(
         select(User).where(func.lower(User.email) == email.strip().lower())
     ).scalar_one_or_none()
@@ -895,7 +974,7 @@ def remove_shared_with_me(
     if row is not None:
         db.delete(row)
         db.commit()
-    return {"removed": job_id}
+    return {"ok": True, "removed": job_id}
 
 
 # --- recipients (for the internal "share with a user" picker) ------------------------------
@@ -911,7 +990,7 @@ def share_recipients(
         db.execute(
             select(User)
             .where(User.id != user.id, *messageable_clauses())
-            .order_by(func.lower(User.email))
+            .order_by(collated(User.email, lang_for_user(user)))
         )
         .scalars()
         .all()
@@ -925,10 +1004,10 @@ def share_recipients(
 def _own_link(db: Session, user: User, link_id: int) -> DownloadLink:
     link = db.get(DownloadLink, link_id)
     if link is None:
-        raise HTTPException(status_code=404, detail="Unknown link")
+        raise not_found("link")
     job = db.get(DownloadJob, link.job_id)
     if job is None or job.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown link")
+        raise not_found("link")
     return link
 
 
@@ -944,7 +1023,7 @@ def _link_expiry(days: int | None) -> datetime | None:
 def list_links(
     job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> list[dict]:
-    _own_job(db, user, job_id)
+    owned_or_404(db, DownloadJob, job_id, user, what="download")
     rows = (
         db.execute(
             select(DownloadLink)
@@ -975,9 +1054,9 @@ def create_link(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    job = _own_job(db, user, job_id)
+    job = owned_or_404(db, DownloadJob, job_id, user, what="download")
     if job.status != "done" or job.asset_id is None:
-        raise HTTPException(status_code=409, detail="Only a finished download can be shared.")
+        raise refused(409, "share_unfinished")
     pw = body.password.strip()
     link = DownloadLink(
         job_id=job_id,

backend/app/routes/feed.py

@@ -1,6 +1,6 @@
 from datetime import date, datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, Query
 from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
@@ -10,6 +10,7 @@ from sqlalchemy.orm.exc import StaleDataError
 from app import quota
 from app.auth import current_user
 from app.db import get_db
+from app.mailtext import lang_for_user
 from app.feedquery import (
     decode_cursor,
     encode_cursor,
@@ -29,10 +30,11 @@ from app.models import (
     Video,
     VideoState,
 )
-from app.routes._common import get_or_404
+from app.routes._common import get_or_404, youtube_refusal, not_found
 from app.sync.videos import parse_iso8601_duration
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
+from app.refusal import refused
 
 router = APIRouter(prefix="/api", tags=["feed"])
 
@@ -107,7 +109,7 @@ def get_feed(
     db: Session = Depends(get_db),
 ) -> dict:
     query, rank_expr = filtered_query(db, user, **params)
-    keys = sort_keys(sort, seed, rank_expr)
+    keys = sort_keys(sort, seed, rank_expr, lang_for_user(user))
 
     # Expose each key column on the row so we can build the next cursor from the last item.
     query = query.add_columns(*[k["expr"].label(f"_k{i}") for i, k in enumerate(keys)])
@@ -120,7 +122,7 @@ def get_feed(
             vals, cursor_id = decode_cursor(keys, cursor)
         except ValueError:
             # `from None`: the ValueError is an expected bad-input signal, not an error to chain.
-            raise HTTPException(status_code=400, detail="Invalid feed cursor") from None
+            raise refused(400, "invalid_cursor") from None
         for k, v in zip(keys, vals):
             k["value"] = v
         query = query.where(keyset_predicate(keys, cursor_id))
@@ -235,7 +237,7 @@ def set_video_state(
 ) -> dict:
     status = body.status
     if status not in VALID_STATES:
-        raise HTTPException(status_code=400, detail=f"status must be one of {VALID_STATES}")
+        raise refused(400, "invalid_status")
     get_or_404(db, Video, video_id, what="video")
 
     now = datetime.now(timezone.utc)
@@ -260,7 +262,7 @@ def set_video_state(
             # or moved this row. The state the caller asked for is the state that holds either way.
             except StaleDataError:
                 db.rollback()
-        return {"video_id": video_id, "status": "new"}
+        return {"ok": True, "video_id": video_id, "status": "new"}
 
     # watched / hidden: atomic upsert. The player marks "watched" at end-of-playback at
     # the same instant a progress checkpoint may DELETE the in-progress row; a plain
@@ -281,7 +283,7 @@ def set_video_state(
     )
     db.execute(stmt)
     db.commit()
-    return {"video_id": video_id, "status": status}
+    return {"ok": True, "video_id": video_id, "status": status}
 
 
 @router.delete("/videos/{video_id}/state")
@@ -303,7 +305,7 @@ def clear_video_state(
         # silent-ok: the row went under the delete, which is the outcome the delete wanted.
         except StaleDataError:
             db.rollback()
-    return {"video_id": video_id, "status": "new", "position_seconds": 0}
+    return {"ok": True, "video_id": video_id, "status": "new", "position_seconds": 0}
 
 
 class VideoProgressIn(BaseModel):
@@ -361,7 +363,7 @@ def set_video_progress(
             # silent-ok: exactly the race the comment above describes; the response stays true.
             except StaleDataError:
                 db.rollback()
-        return {"video_id": video_id, "position_seconds": 0}
+        return {"ok": True, "video_id": video_id, "position_seconds": 0}
 
     if row is None:
         row = VideoState(user_id=user.id, video_id=video_id)
@@ -369,7 +371,7 @@ def set_video_progress(
     row.position_seconds = position
     row.progress_updated_at = datetime.now(timezone.utc)
     db.commit()
-    return {"video_id": video_id, "position_seconds": position}
+    return {"ok": True, "video_id": video_id, "position_seconds": position}
 
 
 @router.get("/videos/{video_id}")
@@ -402,7 +404,7 @@ def get_video_detail(
     # The DB path above is free; the off-catalog YouTube lookup below spends a quota unit, so the
     # demo account can't reach it — it just sees "unknown" for a video we don't already store.
     if user.is_demo:
-        raise HTTPException(status_code=404, detail="Unknown video")
+        raise not_found("video")
 
     try:
         with (
@@ -411,9 +413,9 @@ def get_video_detail(
         ):
             items = yt.get_videos([video_id])
     except YouTubeError as exc:
-        raise HTTPException(status_code=422, detail=f"YouTube lookup failed: {exc}")
+        raise youtube_refusal(exc)
     if not items:
-        raise HTTPException(status_code=404, detail="Unknown video")
+        raise not_found("video")
 
     snippet = items[0].get("snippet", {})
     stats = items[0].get("statistics", {})

backend/app/routes/me.py

@@ -17,12 +17,16 @@ from app.auth import (
     optional_current_user,
     purge_user,
 )
-from app import diagnostics
+from app import debugsession, diagnostics
+from app.issues import gitea
 from app import email as email_mod
 from app import logs
 from app import sysconfig
 from app.db import get_db
 from app.models import Invite, User
+from app.utils import iso
+from app.refusal import refused
+from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/me", tags=["me"])
 
@@ -69,7 +73,7 @@ def switch_account(
     here) are allowed, and access is re-checked in case the invite was revoked since."""
     target = body.user_id
     if target not in (request.session.get("account_ids") or []):
-        raise HTTPException(status_code=403, detail="Not an account you've signed into here.")
+        raise refused(403, "not_your_account")
     # An account `_session_user` would refuse — gone, deactivated, suspended, or its session revoked — is
     # refused here too, and dropped from the switch list the way `_session_user` drops it. Made the session
     # default instead, the next request's current_user would refuse it as the DEFAULT and clear the whole
@@ -77,22 +81,20 @@ def switch_account(
     u = db.get(User, target)
     if u is None:
         drop_from_wallet(request.session, target)
-        raise HTTPException(status_code=404, detail="That account no longer exists.")
+        raise not_found("account")
     if not is_allowed(db, u.email):
-        raise HTTPException(status_code=403, detail="That account no longer has access.")
+        raise refused(403, "account_no_access")
     if not u.is_active:
         drop_from_wallet(request.session, target)
-        raise HTTPException(status_code=403, detail="That account no longer has access.")
+        raise refused(403, "account_no_access")
     if u.is_suspended:
         drop_from_wallet(request.session, target)
-        raise HTTPException(status_code=403, detail="That account is suspended.")
+        raise refused(403, "account_suspended")
     # Revoked: a password reset/change or "log out everywhere" bumped the account's epoch.
     epochs = request.session.get("epochs") or {}
     if int(epochs.get(str(target), 0)) != (u.session_epoch or 0):
         drop_from_wallet(request.session, target)
-        raise HTTPException(
-            status_code=403, detail="That account was signed out elsewhere — sign in again."
-        )
+        raise refused(403, "account_signed_out")
     request.session["user_id"] = target
     return {"ok": True, "user_id": target}
 
@@ -138,6 +140,9 @@ def get_me(
             user.google_email if user.google_email and user.google_email != user.email else None
         ),
         "has_password": user.password_hash is not None,
+        # The account's latest sign-in on any device — shown in Settings → Account, so a sign-in the
+        # user does not recognise is something they can see (null: none since 0.88, or the demo).
+        "last_login_at": iso(user.last_login_at),
         # Instance-wide: whether Google sign-in / YouTube connect is available at all (the UI hides
         # YouTube-access affordances and the onboarding nudge when it isn't configured).
         "google_enabled": google_enabled(db),
@@ -154,9 +159,18 @@ def get_me(
         # The consented diagnostics level in force and when it lapses (E22 S5). The client applies
         # it to its own log and streams that log while it is raised.
         "diagnostics": diagnostics.state(db, user),
+        # The live debug session, if one is recording (E16) — a reload resumes it.
+        "debug_session": _live_session(db, user),
+        # Where a bug report goes (E16 S4): the tracker's repository, or None — download only.
+        "issues": gitea.target(db),
     }
 
 
+def _live_session(db: Session, user: User) -> dict | None:
+    session = debugsession.open_session(db, user)
+    return None if session is None else debugsession.view(db, session)
+
+
 @router.delete("/account")
 def delete_my_account(
     request: Request,
@@ -177,10 +191,7 @@ def delete_my_account(
     if user.is_demo:
         raise HTTPException(status_code=403, detail={"code": "demo", "reason": "delete_account"})
     if user.role == "admin" and count_admins(db) <= 1:
-        raise HTTPException(
-            status_code=400,
-            detail="You're the only admin — promote another admin before deleting your account.",
-        )
+        raise refused(400, "only_admin_delete")
     user_id = user.id
     # Full erasure (cascades) + access-request cleanup + Google-grant revocation; shared with the
     # admin delete path. Capture the id first — `user` is detached once purge_user deletes the row.
@@ -213,7 +224,7 @@ def update_preferences(
     user.preferences = merged
     db.add(user)
     db.commit()
-    return {"preferences": merged}
+    return {"ok": True, "preferences": merged}
 
 
 class DiagnosticsIn(BaseModel):

backend/app/routes/messages.py

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

backend/app/routes/notifications.py

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

backend/app/routes/playlists.py

@@ -3,10 +3,8 @@ CRUD (create / rename / delete, add / remove / reorder items) plus YouTube two-w
 mirror the user's own YouTube playlists in (`/sync-youtube`) and push/revert local edits back
 out (`/{id}/push-plan`, `/{id}/revert-youtube`), behind the optional write scope."""
 
-from datetime import datetime, timezone
-
 from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from sqlalchemy import func, select, and_
 from sqlalchemy.orm import Session, aliased
 
@@ -16,14 +14,18 @@ from app.db import get_db
 from app.feedquery import feed_columns, serialize
 from app.models import Channel, Playlist, PlaylistItem, User, Video, VideoState
 from app.sync.playlists import (
+    PlaylistGone,
+    lock_playlists,
     merge_playlist,
     plan_merge,
     recompute_dirty,
+    pull_user_playlists,
     repull_playlist,
-    sync_user_playlists,
+    sync_claim,
+    user_sync_claim,
 )
 from app.ratelimit import RateLimiter
-from app.routes._common import get_or_404, owned_or_404
+from app.routes._common import get_or_404, not_found, owned_or_404, youtube_refusal
 from app.youtube.client import YouTubeClient, YouTubeError
 
 router = APIRouter(prefix="/api/playlists", tags=["playlists"])
@@ -48,10 +50,6 @@ def _check_pull_cooldown(user: User) -> None:
         raise HTTPException(status_code=429, detail={"code": "sync_cooldown"})
 
 
-def _own_playlist(db: Session, user: User, playlist_id: int) -> Playlist:
-    return owned_or_404(db, Playlist, playlist_id, user, what="playlist")
-
-
 def _refused(status: int, reason: str) -> HTTPException:
     """A playlist action the server refuses, as a reason the UI translates
     (`playlists.errors.<reason>`) — a bare English detail reached the Hungarian UI verbatim."""
@@ -64,8 +62,11 @@ def _touch(pl: Playlist) -> None:
     `UpdatedAtMixin`'s `onupdate` fires on an UPDATE of the PLAYLIST row, and add / remove /
     reorder / move write the item rows instead — so without this the rail's "recently changed"
     sort would only ever see renames. The assignment is what makes the column mean "last time
-    this list changed", which is what the rail promises the reader."""
-    pl.updated_at = datetime.now(timezone.utc)
+    this list changed", which is what the rail promises the reader.
+
+    The DATABASE's clock, like the mixin's own `onupdate`: one sort key written from two clocks
+    (this process's and Postgres's) could order a rename and an item edit the wrong way round."""
+    pl.updated_at = func.now()
 
 
 def _next_playlist_position(db: Session, user_id: int) -> int:
@@ -81,7 +82,10 @@ def _next_playlist_position(db: Session, user_id: int) -> int:
 
 
 def _next_item_position(db: Session, playlist_id: int) -> int:
-    """Append position for a new item at the end of a playlist."""
+    """Append position for a new item at the end of a playlist. Locks the playlist row first: two
+    adds (two tabs, the rail and the page) otherwise both read the same max and land on one
+    position, and the list's order between them is then arbitrary."""
+    lock_playlists(db, playlist_id)
     return (
         db.scalar(
             select(func.coalesce(func.max(PlaylistItem.position), -1)).where(
@@ -94,7 +98,10 @@ def _next_item_position(db: Session, playlist_id: int) -> int:
 
 def _add_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) -> bool:
     """Append a video to a playlist if not already present (idempotent). Returns whether it
-    was added. `mark_dirty` recomputes the YouTube-sync dirty flag (skip for Watch later)."""
+    was added. `mark_dirty` recomputes the YouTube-sync dirty flag (skip for Watch later).
+    Locked BEFORE the presence check: two adds of one video both saw "absent" and the second one's
+    insert hit uq_playlist_video as a 500."""
+    lock_playlists(db, pl.id)
     exists = db.scalar(
         select(PlaylistItem).where(
             PlaylistItem.playlist_id == pl.id, PlaylistItem.video_id == video_id
@@ -108,13 +115,14 @@ def _add_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) ->
     if mark_dirty:
         recompute_dirty(db, pl)
     _touch(pl)
-    db.commit()
+    db.flush()  # the handler commits (CLAUDE.md: helpers flush)
     return True
 
 
 def _remove_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) -> bool:
     """Remove a video from a playlist if present (idempotent). Returns whether it was removed.
     `mark_dirty` recomputes the YouTube-sync dirty flag (skip for Watch later)."""
+    lock_playlists(db, pl.id)
     item = db.scalar(
         select(PlaylistItem).where(
             PlaylistItem.playlist_id == pl.id, PlaylistItem.video_id == video_id
@@ -126,7 +134,7 @@ def _remove_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool)
     if mark_dirty:
         recompute_dirty(db, pl)
     _touch(pl)
-    db.commit()
+    db.flush()  # the handler commits (CLAUDE.md: helpers flush)
     return True
 
 
@@ -280,7 +288,7 @@ def _watch_later(db: Session, user: User) -> Playlist:
             position=_next_playlist_position(db, user.id),
         )
         db.add(pl)
-        db.commit()
+        db.flush()  # the id, for the item the caller adds next; the handler commits
     return pl
 
 
@@ -295,7 +303,8 @@ def add_watch_later(
     get_or_404(db, Video, video_id, what="video")
     pl = _watch_later(db, user)
     _add_item(db, pl, video_id, mark_dirty=False)
-    return {"saved": True, "playlist_id": pl.id}
+    db.commit()
+    return {"ok": True, "saved": True, "playlist_id": pl.id}
 
 
 @router.delete("/watch-later/{video_id}")
@@ -309,7 +318,8 @@ def remove_watch_later(
     )
     if pl is not None:
         _remove_item(db, pl, video_id, mark_dirty=False)
-    return {"saved": False}
+        db.commit()
+    return {"ok": True, "saved": False}
 
 
 @router.post("/sync-youtube")
@@ -321,9 +331,18 @@ def sync_youtube(
     Also runs automatically on the scheduler; this is the manual 'sync now'."""
     if not has_read_scope(user):
         raise _refused(403, "youtube_read_scope")
-    _check_pull_cooldown(user)
-    with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
-        return sync_user_playlists(db, user)
+    with user_sync_claim(db, user.id) as free:
+        if not free:
+            # Another run (the scheduler, another tab) is pulling right now: "0 synced" would lie.
+            raise _refused(409, "sync_all_busy")
+        # After the claim, like the re-pull's: a refused attempt must not spend one of the pulls.
+        _check_pull_cooldown(user)
+        try:
+            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
+                return {"ok": True, **pull_user_playlists(db, user)}
+        except YouTubeError as exc:
+            db.rollback()
+            raise youtube_refusal(exc)
 
 
 @router.post("/{playlist_id}/revert-youtube")
@@ -335,24 +354,31 @@ def revert_youtube(
     """Reset one YouTube-linked playlist to its current YouTube state, discarding local
     edits (and clearing the dirty flag). The user-facing 'undo all my changes' for a list
     once the in-session undo history is gone."""
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     if not pl.yt_playlist_id:
         raise _refused(400, "not_on_youtube")
     if not has_read_scope(user):
         raise _refused(403, "youtube_read_scope")
-    _check_pull_cooldown(user)
-    try:
-        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
-            return repull_playlist(db, user, pl)
-    except YouTubeError:
-        db.rollback()
-        raise _refused(422, "youtube_failed")
+    with sync_claim(db, pl.id) as free:
+        if not free:
+            raise _refused(409, "sync_busy")
+        # The cooldown is spent only by a pull that runs: checked after the claim, so clicking
+        # Revert while a push is in flight does not use up the three pulls per ten minutes.
+        _check_pull_cooldown(user)
+        try:
+            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
+                return {"ok": True, **repull_playlist(db, user, pl)}
+        except PlaylistGone:
+            raise not_found("playlist")
+        except YouTubeError as exc:
+            db.rollback()
+            raise youtube_refusal(exc)
 
 
 def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
     """A local playlist the user may push to YouTube (create or update). The built-in
     Watch later and read-only YouTube mirrors are never pushable."""
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     if pl.kind == "watch_later":
         raise _refused(400, "watch_later_not_pushable")
     return pl
@@ -371,8 +397,8 @@ def push_plan(
     try:
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
             plan = plan_merge(db, user, pl)
-    except YouTubeError:
-        raise _refused(422, "youtube_failed")
+    except YouTubeError as exc:
+        raise youtube_refusal(exc)
     plan["remaining_today"] = quota.remaining_today(db)
     plan["affordable"] = plan["units_estimate"] <= plan["remaining_today"]
     return plan
@@ -388,25 +414,32 @@ def push(
     neither side loses an item). Refuses if the estimated quota exceeds what's left today, so a
     big sync can't strand half-applied. Write scope required (require_write_scope)."""
     pl = _pushable(db, user, playlist_id)
-    try:
-        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
-            # Read the live playlist ONCE (linked playlists only) and share it with both the
-            # plan and the merge, halving read-quota and closing the second read→write TOCTOU
-            # window. A fresh export (no yt_playlist_id) reads nothing.
-            live = None
-            if pl.yt_playlist_id:
-                with YouTubeClient(db, user) as yt:
-                    live = (
-                        list(yt.iter_playlist_items_with_ids(pl.yt_playlist_id)),
-                        yt.get_playlist_snippet(pl.yt_playlist_id),
-                    )
-            plan = plan_merge(db, user, pl, live=live)
-            if plan["units_estimate"] > quota.remaining_today(db):
-                raise _refused(429, "quota_exceeded")
-            return merge_playlist(db, user, pl, live=live)
-    except YouTubeError:
-        db.rollback()
-        raise _refused(422, "youtube_failed")
+    # One sync of a list at a time, across tabs, devices and the scheduler (`sync_claim`): the
+    # client's own in-flight flag only covers the menus of one page.
+    with sync_claim(db, pl.id) as free:
+        if not free:
+            raise _refused(409, "sync_busy")
+        try:
+            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
+                # Read the live playlist ONCE (linked playlists only) and share it with both the
+                # plan and the merge, halving read-quota and closing the second read→write TOCTOU
+                # window. A fresh export (no yt_playlist_id) reads nothing.
+                live = None
+                if pl.yt_playlist_id:
+                    with YouTubeClient(db, user) as yt:
+                        live = (
+                            list(yt.iter_playlist_items_with_ids(pl.yt_playlist_id)),
+                            yt.get_playlist_snippet(pl.yt_playlist_id),
+                        )
+                plan = plan_merge(db, user, pl, live=live)
+                if plan["units_estimate"] > quota.remaining_today(db):
+                    raise _refused(429, "quota_exceeded")
+                return {"ok": True, **merge_playlist(db, user, pl, live=live)}
+        except PlaylistGone:
+            raise not_found("playlist")
+        except YouTubeError as exc:
+            db.rollback()
+            raise youtube_refusal(exc)
 
 
 @router.get("/{playlist_id}")
@@ -415,7 +448,7 @@ def get_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     state = aliased(VideoState)
     rows = db.execute(
         select(*feed_columns(user, state))
@@ -423,7 +456,8 @@ def get_playlist(
         .join(Channel, Channel.id == Video.channel_id)
         .outerjoin(state, and_(state.video_id == Video.id, state.user_id == user.id))
         .where(PlaylistItem.playlist_id == pl.id)
-        .order_by(PlaylistItem.position)
+        # `id` breaks a position tie the same way on every read (the renumbering add does too).
+        .order_by(PlaylistItem.position, PlaylistItem.id)
     ).all()
     return {
         "id": pl.id,
@@ -447,7 +481,8 @@ def rename_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    # Locked: the new name moves `dirty`, which the scheduled mirror refresh reads under this lock.
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist", lock=True)
     if "name" in body.model_fields_set:
         name = (body.name or "").strip()
         if not name:
@@ -484,37 +519,70 @@ def delete_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     if pl.kind == "watch_later":
         raise _refused(400, "watch_later_undeletable")
-    if on_youtube:
-        if not pl.yt_playlist_id:
-            raise _refused(400, "not_on_youtube")
-        if not has_write_scope(user):
-            raise _refused(403, "youtube_editing_off")
-        try:
-            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_DELETE):
-                with YouTubeClient(db, user) as yt:
-                    yt.delete_playlist(pl.yt_playlist_id)
-        except YouTubeError:
-            raise _refused(422, "youtube_failed")
-    db.delete(pl)  # items cascade
-    db.commit()
+    # Not in the middle of a sync of it (`sync_claim`): a push that read the list before the delete
+    # and wrote YouTube after it planned from no items at all, so it emptied the YouTube playlist a
+    # local-only delete means to keep. The push checks for a vanished list too (`PlaylistGone`);
+    # this refuses the delete while a sync runs rather than race it.
+    with sync_claim(db, pl.id) as free:
+        if not free:
+            raise _refused(409, "sync_busy")
+        if on_youtube:
+            if not pl.yt_playlist_id:
+                raise _refused(400, "not_on_youtube")
+            if not has_write_scope(user):
+                raise _refused(403, "youtube_editing_off")
+            try:
+                with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_DELETE):
+                    with YouTubeClient(db, user) as yt:
+                        yt.delete_playlist(pl.yt_playlist_id)
+            except YouTubeError as exc:
+                raise youtube_refusal(exc)
+        # The playlist first, as every item write: the cascade deletes the items before the list row.
+        lock_playlists(db, pl.id)
+        db.delete(pl)  # items cascade
+        db.commit()
     return {"deleted": playlist_id}
 
 
+class AddItemIn(VideoRefIn):
+    # Where the video lands among the list's items, in their stored order (0 = first). Omitted, it
+    # is appended. The list page's "Undo" of a removal puts the row back where it was with this —
+    # ONE request, because append-then-reorder leaves it at the end whenever the second call fails.
+    position: int | None = Field(default=None, ge=0)
+
+
 @router.post("/{playlist_id}/items")
 def add_item(
     playlist_id: int,
-    body: VideoRefIn,
+    body: AddItemIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     video_id = body.video_id
     get_or_404(db, Video, video_id, what="video")
-    _add_item(db, pl, video_id, mark_dirty=True)
-    return {"playlist_id": pl.id, "video_id": video_id}
+    added = _add_item(db, pl, video_id, mark_dirty=False)
+    if added and body.position is not None:
+        # Renumber the whole list with the new row at `position` (clamped to the end): positions
+        # can have gaps after removals, so "index N" is only meaningful over the ordered rows.
+        rows = list(
+            db.execute(
+                select(PlaylistItem)
+                .where(PlaylistItem.playlist_id == pl.id)
+                .order_by(PlaylistItem.position, PlaylistItem.id)
+            ).scalars()
+        )
+        new = next(r for r in rows if r.video_id == video_id)
+        rows.remove(new)
+        rows.insert(min(body.position, len(rows)), new)
+        for pos, row in enumerate(rows):
+            row.position = pos
+    recompute_dirty(db, pl)
+    db.commit()
+    return {"ok": True, "playlist_id": pl.id, "video_id": video_id}
 
 
 @router.delete("/{playlist_id}/items/{video_id}")
@@ -524,9 +592,10 @@ def remove_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     _remove_item(db, pl, video_id, mark_dirty=True)
-    return {"playlist_id": pl.id, "video_id": video_id}
+    db.commit()
+    return {"ok": True, "playlist_id": pl.id, "video_id": video_id}
 
 
 class MoveItemIn(BaseModel):
@@ -548,7 +617,7 @@ def move_item(
     exactly the kind of half-applied state this codebase treats as a bug rather than an edge
     case. Idempotent: if the video is already in the target, the source row is simply dropped
     (moving into a list that already has it is a removal, not a duplicate)."""
-    src = _own_playlist(db, user, playlist_id)
+    src = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
     # Its own reason: "this playlist doesn't exist any more" about a TARGET that is gone was read as
     # the list on screen — which is still there.
     dst = owned_or_404(db, Playlist, body.target_playlist_id, user, what="move_target")
@@ -556,6 +625,8 @@ def move_item(
         raise HTTPException(
             status_code=400, detail={"code": "playlist_move", "reason": "same_playlist"}
         )
+    # Both lists, in id order: a move A→B beside a move B→A would otherwise lock crosswise.
+    lock_playlists(db, src.id, dst.id)
     item = db.scalar(
         select(PlaylistItem).where(
             PlaylistItem.playlist_id == src.id, PlaylistItem.video_id == video_id
@@ -571,19 +642,24 @@ def move_item(
             PlaylistItem.playlist_id == dst.id, PlaylistItem.video_id == video_id
         )
     )
-    if already is not None:
-        db.delete(item)  # the uq_playlist_video constraint would reject a second row anyway
-    else:
+    dst_changed = False
+    if already is None:
         # Re-parent the existing row rather than delete+insert: `added_at` ("when I saved this")
-        # survives the move, and there is no window where the video belongs to neither list.
+        # survives the move, and there is no window where the video belongs to neither list. The
+        # check above holds: both lists are locked, and an insert into the target (another tab's
+        # add, a YouTube merge) waits for the lock — its foreign key needs the target row.
         item.playlist_id = dst.id
         item.position = _next_item_position(db, dst.id)
-    # Both sides changed, so both get the dirty recompute and the timestamp — the asymmetric
-    # version of this (touching only the source) is the recurring smell CLAUDE.md warns about.
+        dst_changed = True
+    if not dst_changed:
+        db.delete(item)
+    # The source always changed; the target only when the row landed in it. `_touch` on a target
+    # that already had the video promoted an untouched list in the rail's "recently changed" sort.
     recompute_dirty(db, src)
-    recompute_dirty(db, dst)
     _touch(src)
-    _touch(dst)
+    if dst_changed:
+        recompute_dirty(db, dst)
+        _touch(dst)
     db.commit()
     return {"ok": True, "from_playlist_id": src.id, "to_playlist_id": dst.id, "video_id": video_id}
 
@@ -599,7 +675,8 @@ def reorder_items(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    # Locked: a concurrent add between reading the items and writing the order would collide.
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist", lock=True)
     order = body.video_ids
     items = {
         it.video_id: it
@@ -625,4 +702,4 @@ def reorder_items(
     recompute_dirty(db, pl)
     _touch(pl)
     db.commit()
-    return {"playlist_id": pl.id, "count": pos}
+    return {"ok": True, "playlist_id": pl.id, "count": pos}

backend/app/routes/plex/_shared.py

@@ -1,11 +1,12 @@
 """Shared helpers, serializers and constants for the plex route package."""
 
-from fastapi import HTTPException
 from sqlalchemy.orm import Session
 
 from app import logs
 from app.models import PlexItem
+from app.plex.cards import norm_lang as _norm_lang  # noqa: F401 — the package's historic name
 from app.plex.lookups import by_rating_key
+from app.routes._common import not_found
 
 log = logs.get_logger(__name__)
 
@@ -13,10 +14,5 @@ log = logs.get_logger(__name__)
 def item_or_404(db: Session, rating_key: str) -> PlexItem:
     it = by_rating_key(db, PlexItem, rating_key)
     if it is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex item")
+        raise not_found("plex_item")
     return it
-
-
-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"

backend/app/routes/plex/admin.py

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

backend/app/routes/plex/browse.py

@@ -10,10 +10,13 @@ from sqlalchemy import (
     func,
     literal,
     null,
+    or_,
     select,
 )
 from sqlalchemy.orm import Session, aliased
 
+from app.mailtext import lang_for_user
+from app.collation import collated, sorted_words
 from app import sysconfig
 from app.auth import current_user
 from app.db import get_db
@@ -25,7 +28,7 @@ from app.models import (
     User,
 )
 from app.plex import rollup
-from app.plex.cards import episode_card
+from app.plex.cards import display_title, episode_card
 from app.plex.query import (
     FIELD_COLUMNS,
     PLAYBACK_CLASSES,
@@ -54,14 +57,15 @@ from app.utils import to_tsquery_str
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
 
-def sort_column(u, sort: str):
+def sort_column(u, sort: str, lang: str = "en"):
     """The browse grid's sort key -> orderable column on the union subquery. Module-level (not inline
     in the handler) so a test can pin its vocabulary to `PLEX_SORT_KEYS` — a key the Sort control
     offers but this cannot order would quietly fall back to `added_at` and look like a broken control.
-    An unknown key (a stale bookmark, a hand-edited URL) deliberately keeps that fallback."""
+    An unknown key (a stale bookmark, a hand-edited URL) deliberately keeps that fallback. The title sorts
+    in the reader's alphabet (`collation`)."""
     return {
         "added": u.c.added_at,
-        "title": func.lower(u.c.title),
+        "title": collated(u.c.title, lang),
         "year": u.c.year,
         "rating": u.c.rating,
         "duration": u.c.duration_s,
@@ -78,7 +82,7 @@ def list_libraries(user: User = Depends(current_user), db: Session = Depends(get
         db.execute(
             select(PlexLibrary)
             .where(PlexLibrary.overlay_of.is_(None))
-            .order_by(PlexLibrary.kind.desc(), PlexLibrary.title)
+            .order_by(PlexLibrary.kind.desc(), collated(PlexLibrary.title, lang_for_user(user)))
         )
         .scalars()
         .all()
@@ -237,7 +241,7 @@ def unified_library(
         if tsq is not None:
             order = [u.c.rank.desc()]
         else:
-            col = sort_column(u, sort)
+            col = sort_column(u, sort, lang)
             order = [(col.asc() if sort_dir == "asc" else col.desc()).nullslast()]
         order.append(u.c.rk.desc())
         rows = db.execute(select(u).order_by(*order).offset(offset).limit(limit)).all()
@@ -281,26 +285,32 @@ def unified_library(
     episodes = []
     if tsq is not None and want_shows and field in ("all", "episode"):
         ep_st = aliased(PlexState)
-        ep_vec = (
-            func.to_tsvector(TS_CONFIG, func.coalesce(PlexItem.title, ""))
-            if field == "episode"
-            else PlexItem.search_vector
-        )
+        # In HU an episode is found by its Hungarian title too (E30: the overlay now fills it) — and
+        # still by its English one, like `vector_match` does for the grid.
+        if field == "episode":
+            ep_vec = func.to_tsvector(TS_CONFIG, func.coalesce(PlexItem.title, ""))
+            ep_vec_hu = func.to_tsvector(TS_CONFIG, func.coalesce(PlexItem.title_hu, ""))
+        else:
+            ep_vec, ep_vec_hu = PlexItem.search_vector, PlexItem.search_vector_hu
+        hit = ep_vec.op("@@")(tsq)
+        if lang == "hu":
+            hit = or_(ep_vec_hu.op("@@")(tsq), hit)
+            ep_vec = ep_vec_hu
         eps = db.execute(
-            select(PlexItem, ep_st, PlexShow.title.label("show_title"))
+            select(PlexItem, ep_st, PlexShow)
             .outerjoin(ep_st, and_(ep_st.item_id == PlexItem.id, ep_st.user_id == user.id))
             .outerjoin(PlexShow, PlexShow.id == PlexItem.show_id)
             .where(
                 PlexItem.kind == "episode",
                 PlexItem.library_id.in_(show_lib_ids),
-                ep_vec.op("@@")(tsq),
+                hit,
             )
             .order_by(func.ts_rank(ep_vec, tsq).desc())
             .limit(24)
         ).all()
-        for e, s, show_title in eps:
-            card = episode_card(e, s)
-            card["show_title"] = show_title
+        for e, s, sh in eps:
+            card = episode_card(e, s, lang=lang)
+            card["show_title"] = display_title(sh, lang) if sh is not None else None
             episodes.append(card)
 
     return {
@@ -523,16 +533,19 @@ def facets(
     for c in split_csv(f.playable):
         if c in PLAYBACK_CLASSES:
             playable_counts.setdefault(c, 0)
+    # Names in the reader's alphabet: the genres are Hungarian words for a Hungarian reader (E30 S1).
+    alpha = {w: i for i, w in enumerate(sorted_words(db, [*genre_counts, *studio_counts], lang))}
     return {
         "genres": [
-            {"value": g, "count": c} for g, c in sorted(genre_counts.items(), key=lambda kv: kv[0])
+            {"value": g, "count": c}
+            for g, c in sorted(genre_counts.items(), key=lambda kv: alpha[kv[0]])
         ],
         "content_ratings": [
             {"value": cr, "count": c} for cr, c in sorted(cr_counts.items(), key=lambda kv: -kv[1])
         ],
         "studios": [
             {"value": s, "count": c}
-            for s, c in sorted(studio_counts.items(), key=lambda kv: (-kv[1], kv[0]))
+            for s, c in sorted(studio_counts.items(), key=lambda kv: (-kv[1], alpha[kv[0]]))
         ],
         # Fixed good→heavy order (not by count), so the class list reads as a severity scale.
         "playable": [

backend/app/routes/plex/collections.py

@@ -9,6 +9,9 @@ from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app.mailtext import lang_for_user
+from app.collation import collated, sorted_words
+from app import logs
 from app.auth import admin_user, current_user
 from app.db import get_db
 from app.models import (
@@ -21,11 +24,15 @@ from app.models import (
 )
 from app.plex import rollup
 from app.plex import sync as plex_sync
-from app.plex.cards import movie_card, show_card
+from app.plex.cards import display_title, movie_card, norm_lang, show_card
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
-from app.plex.query import content_libs, runtime_by_key, top_art_keys
+from app.plex.query import content_libs, runtime_by_key, title_col, top_art_keys
 from app.utils import like_escape
+from app.refusal import refused
+from app.routes._common import not_found
+
+log = logs.get_logger(__name__)
 
 # The most-restrictive → least ordering used to pick a collection's effective content rating from its
 # members (Plex shows one cert on the collection; we don't store it, so derive it).
@@ -137,7 +144,7 @@ def collections(
         db.execute(
             query.order_by(
                 PlexCollection.child_count.desc().nullslast(),
-                func.lower(PlexCollection.title),
+                collated(PlexCollection.title, lang_for_user(user)),
             )
         )
         .scalars()
@@ -203,16 +210,24 @@ MEMBER_SORT_KEYS: dict[str, Callable[[Member], Any]] = {
 DEFAULT_MEMBER_SORT = "year"
 
 
-def sort_members(members: list[Member], sort: str, sort_dir: str) -> list[Member]:
+def sort_members(
+    members: list[Member], sort: str, sort_dir: str, alpha: dict[str, int] | None = None
+) -> list[Member]:
     """Order a collection's members by one of `PLEX_SORT_KEYS`.
 
     Two properties worth stating because they are easy to get wrong with a plain `reverse=True`:
     members with no value for the key sink to the END in BOTH directions (matching the browse grid's
     `nullslast()` — a movie with no rating is not "the worst rated"), and ties always resolve
     title-ascending, so flipping the direction reverses the ranking rather than the alphabet inside
-    it. An unknown key falls back to the page's default instead of returning an arbitrary order."""
+    it. An unknown key falls back to the page's default instead of returning an arbitrary order.
+
+    `alpha` ranks each title in the reader's alphabet (`collation.sorted_words`); without it, titles
+    compare as Python strings, which puts every accented initial after "z"."""
+    by_title = (lambda m: alpha[m.title]) if alpha is not None else (lambda m: m.title)
     key = MEMBER_SORT_KEYS.get(sort, MEMBER_SORT_KEYS[DEFAULT_MEMBER_SORT])
-    ordered = sorted(members, key=lambda m: m.title)  # stable secondary, applied first
+    if key is MEMBER_SORT_KEYS["title"]:
+        key = by_title
+    ordered = sorted(members, key=by_title)  # stable secondary, applied first
     have = [m for m in ordered if key(m) is not None]
     missing = [m for m in ordered if key(m) is None]
     have.sort(key=key, reverse=sort_dir != "asc")
@@ -224,6 +239,7 @@ def collection_detail(
     rating_key: str,
     sort: str = DEFAULT_MEMBER_SORT,
     sort_dir: str = "asc",
+    lang: str = "en",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -232,14 +248,15 @@ def collection_detail(
     control means the same thing on both surfaces; the default is release year ascending, which is
     what this page did before it had a control. Read-only here; edits go through the admin mutation
     endpoints below."""
+    lang = norm_lang(lang)
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     movies = (
         db.execute(
             select(PlexItem)
             .where(PlexItem.kind == "movie", PlexItem.collection_keys.contains([rating_key]))
-            .order_by(PlexItem.year.asc().nullslast(), func.lower(PlexItem.title))
+            .order_by(PlexItem.year.asc().nullslast(), collated(title_col(PlexItem, lang), lang))
         )
         .scalars()
         .all()
@@ -248,7 +265,7 @@ def collection_detail(
         db.execute(
             select(PlexShow)
             .where(PlexShow.collection_keys.contains([rating_key]))
-            .order_by(PlexShow.year.asc().nullslast(), func.lower(PlexShow.title))
+            .order_by(PlexShow.year.asc().nullslast(), collated(title_col(PlexShow, lang), lang))
         )
         .scalars()
         .all()
@@ -280,7 +297,7 @@ def collection_detail(
         Member(
             kind="movie",
             obj=m,
-            title=(m.title or "").lower(),
+            title=display_title(m, lang).lower(),
             year=m.year,
             rating=m.rating,
             added=m.added_at,
@@ -293,7 +310,7 @@ def collection_detail(
         Member(
             kind="show",
             obj=sh,
-            title=(sh.title or "").lower(),
+            title=display_title(sh, lang).lower(),
             year=sh.year,
             rating=sh.rating,
             added=sh.added_at,
@@ -303,11 +320,12 @@ def collection_detail(
         )
         for sh in shows
     ]
-    members = sort_members(members, sort, sort_dir)
+    alpha = {w: i for i, w in enumerate(sorted_words(db, [m.title for m in members], lang))}
+    members = sort_members(members, sort, sort_dir, alpha)
     items = [
-        movie_card(m.obj, mstate.get(m.obj.id))
+        movie_card(m.obj, mstate.get(m.obj.id), lang=lang)
         if m.kind == "movie"
-        else show_card(m.obj, sstate.get(m.obj.id, "new"))
+        else show_card(m.obj, sstate.get(m.obj.id, "new"), lang=lang)
         for m in members
     ]
     years = [m.year for m in members if m.year is not None]
@@ -325,9 +343,9 @@ def collection_detail(
 def _editable_collection_or_403(db: Session, rating_key: str) -> PlexCollection:
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     if not _collection_editable(col):
-        raise HTTPException(status_code=403, detail="This collection is read-only")
+        raise refused(403, "collection_read_only")
     return col
 
 
@@ -362,14 +380,13 @@ def _write_or_pending_error(wrote: bool, e: Exception) -> HTTPException:
     Both use 422, NOT a 5xx: the frontend treats 502/503/504 as "gateway unreachable" and raises a
     sticky offline banner (see api/core.ts RETRIABLE_GATEWAY). A 422 surfaces the detail as an ordinary
     action-error toast, which is what both of these are — the app answered, it didn't go unreachable."""
-    if wrote:
-        detail = (
-            "Collection updated in Plex, but refreshing the local copy failed; "
-            f"it will reconcile on the next sync ({e})"
-        )
-    else:
-        detail = f"Plex write failed: {e}"
-    return HTTPException(status_code=422, detail=detail)
+    log.warning(
+        "a Plex collection write did not settle",
+        extra=logs.event(
+            "plex.collections.write_failed", wrote=wrote, reason=type(e).__name__, error=str(e)
+        ),
+    )
+    return refused(422, "collection_pending_sync") if wrote else refused(422, "plex_write_failed")
 
 
 class CreateCollectionIn(BaseModel):
@@ -389,7 +406,7 @@ def create_collection(
     title = body.title.strip()
     seed = body.item_rating_key
     if not title or not seed:
-        raise HTTPException(status_code=400, detail="title and item_rating_key are required")
+        raise refused(400, "collection_fields_required")
     if library:
         lib = (
             db.execute(select(PlexLibrary).where(PlexLibrary.plex_key == library)).scalars().first()
@@ -399,7 +416,7 @@ def create_collection(
         seed_item = by_rating_key(db, PlexItem, seed) or by_rating_key(db, PlexShow, seed)
         lib = db.get(PlexLibrary, seed_item.library_id) if seed_item else None
     if lib is None:
-        raise HTTPException(status_code=404, detail="Unknown library")
+        raise not_found("library")
     _reject_duplicate_name(db, lib.id, title)
     wrote = False
     try:
@@ -473,7 +490,7 @@ def collection_rename(
     col = _editable_collection_or_403(db, rating_key)
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     _reject_duplicate_name(db, col.library_id, title, exclude_rk=rating_key)
     lib = db.get(PlexLibrary, col.library_id)
     wrote = False
@@ -502,7 +519,7 @@ def collection_delete(
         db.commit()
     except (PlexError, PlexNotConfigured) as e:
         db.rollback()
-        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
+        raise _write_or_pending_error(False, e) from None
     return {"deleted": rating_key}
 
 
@@ -521,13 +538,10 @@ def collection_set_editable(
     (IMDb/TMDb/…) can never be made editable — they're regenerated outside Plex."""
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
-        raise HTTPException(status_code=404, detail="Unknown collection")
+        raise not_found("collection")
     want = body.editable
     if want and (col.smart or _collection_source(col) != "collection"):
-        raise HTTPException(
-            status_code=400,
-            detail="Smart / auto-list collections can't be made editable",
-        )
+        raise refused(400, "collection_smart")
     col.editable = want
     db.commit()
     return _collection_card(col)

backend/app/routes/plex/detail.py

@@ -1,14 +1,16 @@
 """Plex show/item detail: the show drill-down + the per-item player payload (markers, cast, nav)."""
 
+import re
 import threading
 import time
 from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy import func, select
+from fastapi import APIRouter, Depends
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
+from app.collation import collated, sorted_words
 from app import logs
 from app.auth import current_user
 from app.db import get_db
@@ -24,12 +26,14 @@ from app.models import (
 from app.plex import detail as plex_detail
 from app.plex import people as plex_people
 from app.plex import rollup, subtitles
+from app.plex.query import title_col
 from app.plex import tmdb as plex_tmdb
 from app.plex.cards import episode_card, movie_card, show_card
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
 from app.routes.plex._shared import _norm_lang, item_or_404
 from app.routes.plex.collections import _collection_source
+from app.routes._common import not_found
 
 log = logs.get_logger(__name__)
 
@@ -106,10 +110,11 @@ def show_detail(
     db: Session = Depends(get_db),
 ) -> dict:
     """A show's seasons + episodes (the drill-down view) with per-user watch state."""
-    hu = _norm_lang(lang) == "hu"
+    lang = _norm_lang(lang)
+    hu = lang == "hu"
     sh = by_rating_key(db, PlexShow, rating_key)
     if sh is None:
-        raise HTTPException(status_code=404, detail="Unknown Plex show")
+        raise not_found("show")
     seasons = (
         db.execute(
             select(PlexSeason)
@@ -143,7 +148,7 @@ def show_detail(
     by_season: dict[int | None, list] = {}
     all_cards: list[dict] = []  # every episode, in season/episode order → show-level rollup
     for e in eps:
-        card = episode_card(e, states.get(e.id))
+        card = episode_card(e, states.get(e.id), lang=lang)
         by_season.setdefault(e.season_id, []).append(card)
         all_cards.append(card)
     show_roll = rollup.rollup(all_cards)
@@ -155,7 +160,7 @@ def show_detail(
     related: list[dict] = []
     try:
         meta, related_raw = _show_enrichment(db, sh.rating_key)
-        related = _relatedshow_cards(db, user.id, related_raw, exclude=sh.id)
+        related = _relatedshow_cards(db, user.id, related_raw, exclude=sh.id, lang=lang)
         if sh.people_enriched_at is None and meta:
             plex_people.enrich_row_people(db, sh, plex_people.cast_from_meta(meta))
             plex_detail.apply_rich_detail(sh, meta)  # imdb/tagline/full_cast for future views
@@ -209,7 +214,7 @@ def show_detail(
             "episode_count": show_roll["episode_count"],
             "collection_keys": sh.collection_keys or [],
             # TMDB enrichment (E5 S2), served from the row.
-            "tmdb": plex_tmdb.serve_block(db, sh),
+            "tmdb": plex_tmdb.serve_block(db, sh, lang=lang),
         },
         "seasons": [_season_block(se, by_season.get(se.id, [])) for se in seasons],
         "related": related,
@@ -233,7 +238,9 @@ def _season_block(se: PlexSeason, cards: list[dict]) -> dict:
     }
 
 
-def _relatedshow_cards(db: Session, user_id: int, related: list[dict], exclude: int) -> list[dict]:
+def _relatedshow_cards(
+    db: Session, user_id: int, related: list[dict], exclude: int, lang: str
+) -> list[dict]:
     """Map Plex 'related' metadata to show cards for the shows we actually mirror (so they're openable),
     excluding the current show. Order preserved; capped."""
     rks = [str(m.get("ratingKey")) for m in related if m.get("ratingKey")]
@@ -253,13 +260,13 @@ def _relatedshow_cards(db: Session, user_id: int, related: list[dict], exclude:
         if sh is None or rk in seen:
             continue
         seen.add(rk)
-        out.append(show_card(sh, statuses.get(sh.id, "new")))
+        out.append(show_card(sh, statuses.get(sh.id, "new"), lang=lang))
         if len(out) >= 20:
             break
     return out
 
 
-def _collection_strips(db: Session, it: PlexItem, user_id: int) -> list[dict]:
+def _collection_strips(db: Session, it: PlexItem, user_id: int, lang: str) -> list[dict]:
     """The collections this movie belongs to, each with its member titles (playable cards) — the
     'Avatar Collection' strip on the info page. Pure local lookup (no Plex call)."""
     keys = it.collection_keys or []
@@ -272,7 +279,8 @@ def _collection_strips(db: Session, it: PlexItem, user_id: int) -> list[dict]:
         ).scalars()
     }
     # Smallest (most specific — e.g. a franchise) first; the big auto-lists (IMDb/TMDb Popular) last.
-    ordered = sorted((c for c in cols.values()), key=lambda c: (c.child_count or 0, c.title))
+    alpha = {w: i for i, w in enumerate(sorted_words(db, [c.title for c in cols.values()], lang))}
+    ordered = sorted(cols.values(), key=lambda c: (c.child_count or 0, alpha[c.title]))
     out = []
     for col in ordered:
         rk = col.rating_key
@@ -284,7 +292,9 @@ def _collection_strips(db: Session, it: PlexItem, user_id: int) -> list[dict]:
                     PlexItem.kind == "movie",
                     PlexItem.collection_keys.contains([rk]),
                 )
-                .order_by(PlexItem.year.asc().nullslast(), func.lower(PlexItem.title))
+                .order_by(
+                    PlexItem.year.asc().nullslast(), collated(title_col(PlexItem, lang), lang)
+                )
                 .limit(60)
             )
             .scalars()
@@ -304,7 +314,7 @@ def _collection_strips(db: Session, it: PlexItem, user_id: int) -> list[dict]:
                 "id": rk,
                 "title": col.title,
                 "source": _collection_source(col),
-                "items": [movie_card(m, states.get(m.id)) for m in members],
+                "items": [movie_card(m, states.get(m.id), lang=lang) for m in members],
             }
         )
     return out
@@ -338,6 +348,26 @@ def _episode_nav(db: Session, it: PlexItem) -> tuple[str | None, str | None]:
     return (keys[i - 1] if i > 0 else None), (keys[i + 1] if i < len(keys) - 1 else None)
 
 
+# The technical tail of Plex's track title — "English (AC3 5.1)" → "AC3 5.1".
+_TRACK_TAIL = re.compile(r"\(([^()]+)\)\s*$")
+
+
+def _track_naming(s: dict) -> dict:
+    """What the player names a track from (E30). Plex's `displayTitle` is in the SERVER's language
+    ("English (AC3 5.1)", "magyar Forced", "中文 (EAC3 Stereo)"), so it is sent only as the fallback
+    `label`; the client builds the name in the reader's language from the language tag, the
+    forced / SDH flags and the codec tail. No title and no language → no label (the client numbers it)."""
+    title = s.get("displayTitle") or s.get("language") or None
+    tail = _TRACK_TAIL.search(title) if title else None
+    return {
+        "label": title,
+        "lang_tag": s.get("languageTag") or None,
+        "forced": bool(s.get("forced")),
+        "hearing_impaired": bool(s.get("hearingImpaired")),
+        "detail": tail.group(1).strip() if tail else None,
+    }
+
+
 @router.get("/item/{rating_key}")
 def item_detail(
     rating_key: str,
@@ -383,9 +413,7 @@ def item_detail(
                 audio_streams.append(
                     {
                         "ord": len(audio_streams),
-                        "label": s.get("displayTitle")
-                        or s.get("language")
-                        or f"Audio {len(audio_streams) + 1}",
+                        **_track_naming(s),
                         "language": s.get("languageTag") or s.get("language"),
                         "default": bool(s.get("selected") or s.get("default")),
                     }
@@ -395,9 +423,7 @@ def item_detail(
                 subtitle_streams.append(
                     {
                         "ord": len(subtitle_streams),
-                        "label": s.get("displayTitle")
-                        or s.get("language")
-                        or f"Subtitle {len(subtitle_streams) + 1}",
+                        **_track_naming(s),
                         "language": s.get("languageTag") or s.get("language"),
                         "codec": codec,
                         # Text subs (srt/ass/…) can be served as WebVTT tracks; image subs (PGS/VobSub)
@@ -467,7 +493,7 @@ def item_detail(
             "genres": (it.genres_hu or it.genres if hu else it.genres) or [],
             "directors": it.directors or [],
             "studio": it.studio,
-            "tagline": it.tagline,
+            "tagline": (it.tagline_hu or it.tagline) if hu else it.tagline,
         }
     else:
         rich = plex_detail.rich_detail(meta)
@@ -511,7 +537,7 @@ def item_detail(
         "episode_number": it.episode_number,
         "prev_id": prev_id,
         "next_id": next_id,
-        "collections": _collection_strips(db, it, user.id),
+        "collections": _collection_strips(db, it, user.id, lang),
         # TMDB enrichment (E5 S2), served from the row — movies only (episodes aren't enriched).
-        "tmdb": plex_tmdb.serve_block(db, it) if it.kind == "movie" else None,
+        "tmdb": plex_tmdb.serve_block(db, it, lang=lang) if it.kind == "movie" else None,
     }

backend/app/routes/plex/discover.py

@@ -18,11 +18,12 @@ from fastapi import APIRouter, Depends, Query
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.orm import Session
 
+from app.collation import sorted_words
 from app.auth import current_user
 from app.db import get_db
 from app.models import PlexItem, PlexShow, PlexState, User
 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 (
     LibraryFilters,
     apply_meta_filters,
@@ -32,12 +33,12 @@ from app.plex.query import (
     meta_filter_conds,
     top_art_keys,
 )
+from app.discover.queries import RAIL_LIMIT
 from app.plex.tmdb import resolve_recs
 from app.routes.plex._shared import _norm_lang
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
-RAIL_LIMIT = 20
 GENRE_TILES = 12
 SURPRISE_PER_KIND = 3  # Surprise-me: at most this many movies + this many shows (6 total)
 
@@ -61,14 +62,14 @@ def _movie_meta(q, p: dict, lang: str, f: LibraryFilters):
     return q
 
 
-def _movie_cards(db: Session, uid: int, items: list[PlexItem]) -> list[dict]:
+def _movie_cards(db: Session, uid: int, items: list[PlexItem], lang: str) -> list[dict]:
     sts = rollup.item_state_map(db, uid, [it.id for it in items])
-    return [movie_card(it, sts.get(it.id)) for it in items]
+    return [movie_card(it, sts.get(it.id), lang=lang) for it in items]
 
 
-def _show_cards(db: Session, uid: int, shows: list[PlexShow]) -> list[dict]:
+def _show_cards(db: Session, uid: int, shows: list[PlexShow], lang: str) -> list[dict]:
     statuses = rollup.state_map(db, uid, [s.id for s in shows])
-    return [show_card(s, statuses.get(s.id, "new")) for s in shows]
+    return [show_card(s, statuses.get(s.id, "new"), lang=lang) for s in shows]
 
 
 def _recently_added(
@@ -123,8 +124,8 @@ def _recently_added(
     # share one), so the merge doesn't depend on object identity staying alive.
     top_movies = [o for _, kind, o in top if kind == "movie"]
     top_shows = [o for _, kind, o in top if kind == "show"]
-    mcards = {m.rating_key: c for m, c in zip(top_movies, _movie_cards(db, uid, top_movies))}
-    scards = {s.rating_key: c for s, c in zip(top_shows, _show_cards(db, uid, top_shows))}
+    mcards = {m.rating_key: c for m, c in zip(top_movies, _movie_cards(db, uid, top_movies, lang))}
+    scards = {s.rating_key: c for s, c in zip(top_shows, _show_cards(db, uid, top_shows, lang))}
     return [mcards[o.rating_key] if kind == "movie" else scards[o.rating_key] for _, kind, o in top]
 
 
@@ -156,10 +157,10 @@ def _recently_watched(
             .order_by(PlexState.watched_at.desc().nullslast())
             .limit(RAIL_LIMIT)
         ).all():
-            rows.append((st.watched_at, leaf_card(it, st)))
+            rows.append((st.watched_at, leaf_card(it, st, lang=lang)))
     if show_ids:
         eq = (
-            select(PlexItem, PlexState, PlexShow.title, PlexShow.rating_key)
+            select(PlexItem, PlexState, PlexShow)
             .join(PlexState, and_(PlexState.item_id == PlexItem.id, PlexState.user_id == uid))
             .join(PlexShow, PlexShow.id == PlexItem.show_id)
             .where(
@@ -170,8 +171,11 @@ def _recently_watched(
             .order_by(PlexState.watched_at.desc().nullslast())
             .limit(RAIL_LIMIT)
         )
-        for ep, st, sh_title, sh_rk in db.execute(eq).all():
-            rows.append((st.watched_at, leaf_card(ep, st, show_title=sh_title, show_rk=sh_rk)))
+        for ep, st, sh in db.execute(eq).all():
+            card = leaf_card(
+                ep, st, show_title=display_title(sh, lang), show_rk=sh.rating_key, lang=lang
+            )
+            rows.append((st.watched_at, card))
     rows.sort(key=lambda r: r[0] or rollup.NO_TS, reverse=True)
     return [card for _, card in rows[:RAIL_LIMIT]]
 
@@ -214,7 +218,7 @@ def _continue_watching(
             .limit(RAIL_LIMIT)
         ).all()
         for it, st in mrows:
-            rows.append((st.progress_updated_at, movie_card(it, st)))
+            rows.append((st.progress_updated_at, movie_card(it, st, lang=lang)))
 
     if show_ids:
         # Reuse the shared per-show episode rollup (total/watched/inprog) rather than re-inlining it, plus
@@ -234,7 +238,7 @@ def _continue_watching(
             .limit(RAIL_LIMIT)
         ).all()
         for sh, resumed_at in srows:
-            rows.append((resumed_at, show_card(sh, "in_progress")))
+            rows.append((resumed_at, show_card(sh, "in_progress", lang=lang)))
 
     rows.sort(key=lambda r: r[0] or rollup.NO_TS, reverse=True)
     return [card for _, card in rows[:RAIL_LIMIT]]
@@ -261,7 +265,8 @@ def _genre_tiles(
         expanded = base.subquery()
         for g, c in db.execute(select(expanded.c.g, func.count()).group_by(expanded.c.g)).all():
             counts[g] = counts.get(g, 0) + c
-    top = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))[:GENRE_TILES]
+    alpha = {w: i for i, w in enumerate(sorted_words(db, list(counts), lang))}
+    top = sorted(counts.items(), key=lambda kv: (-kv[1], alpha[kv[0]]))[:GENRE_TILES]
     # A 2×2 poster collage per tile: the top movies in that genre (color hash is the client fallback).
     art = top_art_keys(
         db,
@@ -310,7 +315,7 @@ def _because_you_watched(
     )
     if anchor is None:
         return None
-    resolved = resolve_recs(db, anchor.recommendations)
+    resolved = resolve_recs(db, anchor.recommendations, lang=lang)
     # Preserve TMDB's recommendation order, keep only in-library hits, and drop the anchor itself.
     rks = [
         r["rating_key"]
@@ -346,9 +351,11 @@ def _because_you_watched(
     ordered_shows = [shows[rk] for rk in rks if rk in shows]
     # rating_key is globally unique in Plex, so it keys the serialized cards back safely (no id()).
     mcards = {
-        m.rating_key: c for m, c in zip(ordered_movies, _movie_cards(db, uid, ordered_movies))
+        m.rating_key: c for m, c in zip(ordered_movies, _movie_cards(db, uid, ordered_movies, lang))
+    }
+    scards = {
+        s.rating_key: c for s, c in zip(ordered_shows, _show_cards(db, uid, ordered_shows, lang))
     }
-    scards = {s.rating_key: c for s, c in zip(ordered_shows, _show_cards(db, uid, ordered_shows))}
     items: list[dict] = []
     for rk in rks:
         if rk in mcards:
@@ -357,7 +364,10 @@ def _because_you_watched(
             items.append(scards[rk])
     if not items:
         return None
-    return {"anchor": {"id": anchor.rating_key, "title": anchor.title}, "items": items}
+    return {
+        "anchor": {"id": anchor.rating_key, "title": display_title(anchor, lang)},
+        "items": items,
+    }
 
 
 @router.get("/discover")
@@ -456,8 +466,8 @@ def surprise(
             .scalars()
             .all()
         )
-    mcards = _movie_cards(db, user.id, movies)
-    scards = _show_cards(db, user.id, shows)
+    mcards = _movie_cards(db, user.id, movies, lang)
+    scards = _show_cards(db, user.id, shows, lang)
     # Interleave movie/show cards, then trim to `limit`.
     items: list[dict] = []
     for i in range(max(len(mcards), len(scards))):

backend/app/routes/plex/people.py

@@ -7,7 +7,8 @@ from fastapi import APIRouter, BackgroundTasks, Depends
 from sqlalchemy import func, or_, select
 from sqlalchemy.orm import Session
 
-from app import logs
+from app.collation import collated
+from app import logs, sysconfig
 from app.auth import current_user
 from app.db import SessionLocal, get_db
 from app.models import (
@@ -18,22 +19,28 @@ from app.models import (
 )
 from app.plex import rollup
 from app.plex import tmdb as plex_tmdb
-from app.plex.cards import movie_card, show_card
-from app.plex.query import content_libs, split_csv
+from app.plex.cards import movie_card, norm_lang, show_card
+from app.plex.query import content_libs, split_csv, title_col
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 log = logs.get_logger(__name__)
 
 
+# How many "Known for" titles the person page shows (the stored pool is deeper; see plex.tmdb).
+_KNOWN_FOR_SHOWN = 15
+
+
 def _resolve_known_for(
     db: Session,
     known_for: list | None,
     uid: int,
     movie_lib_ids: list[int],
     show_lib_ids: list[int],
+    lang: str,
 ) -> list[dict]:
-    """The person's TMDB "Known for" credits (top by popularity) that are IN our library, as cards, in
-    popularity order. Matched by the canonical guid `tmdb:<id>`; out-of-library credits are dropped."""
+    """The person's TMDB "Known for" credits (most-voted first) that are IN our library, as cards, in
+    that order, at most _KNOWN_FOR_SHOWN. Matched by the canonical guid `tmdb:<id>`; out-of-library
+    credits are dropped."""
     if not known_for:
         return []
     # Match each credit to a library row by guid, bucketed by media_type (movie ids and tv ids collide
@@ -50,10 +57,10 @@ def _resolve_known_for(
         # A credit resolves against its OWN media_type's bucket only.
         if k.get("media_type") == "tv":
             if g in shows:
-                out.append(show_card(shows[g], show_statuses.get(shows[g].id, "new")))
+                out.append(show_card(shows[g], show_statuses.get(shows[g].id, "new"), lang=lang))
         elif g in movies:
-            out.append(movie_card(movies[g], m_states.get(movies[g].id)))
-    return out
+            out.append(movie_card(movies[g], m_states.get(movies[g].id), lang=lang))
+    return out[:_KNOWN_FOR_SHOWN]
 
 
 @router.get("/people/cards")
@@ -159,6 +166,7 @@ def _enrich_person_bg(person_id: int) -> None:
 def person_detail(
     name: str,
     background_tasks: BackgroundTasks,
+    lang: str = "en",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -171,18 +179,24 @@ def person_detail(
     E5 S6: the first time a page is opened, the person's TMDB bio + "Known for" credits are lazily
     fetched (from the S2-linked `tmdb_person_id`) and persisted, then served from the row on every open.
     The fetch runs OFF the request path (a background task); the first open serves whatever's in the row
-    (bio possibly still null) and the bio lands from the row by the next open.
+    with `enriching` set, and the page asks again until the bio lands. E30 S6: the people_enrich job
+    fetches everyone ahead of time, so this lazy path is only for a person the job hasn't reached yet.
     """
+    lang = norm_lang(lang)
     person = db.execute(select(PlexPerson).where(PlexPerson.name == name)).scalars().first()
     # Lazy one-time bio enrich, scheduled AFTER the response so the TMDB call is never on the serve path.
     # Gated by a per-person cooldown so concurrent/rapid opens (or repeated opens while TMDB is degraded)
     # can't pile background tasks onto the shared threadpool.
-    if (
+    # `enriching` tells the page the bio is on its way (E30 S6): it asks again shortly instead of showing
+    # an empty page until the next open. True while a fetch is pending, including one an earlier open
+    # already reserved.
+    enriching = (
         person is not None
-        and person.tmdb_person_id
+        and bool(person.tmdb_person_id)
         and person.tmdb_enriched_at is None
-        and _should_schedule_enrich(person.id)
-    ):
+        and bool(sysconfig.get_str(db, "tmdb_api_key"))
+    )
+    if enriching and person is not None and _should_schedule_enrich(person.id):
         background_tasks.add_task(_enrich_person_bg, person.id)
     movie_lib_ids, show_lib_ids = content_libs(db)
 
@@ -199,14 +213,16 @@ def person_detail(
                         PlexItem.directors.contains([name]),
                     ),
                 )
-                .order_by(PlexItem.year.desc().nullslast(), func.lower(PlexItem.title))
+                .order_by(
+                    PlexItem.year.desc().nullslast(), collated(title_col(PlexItem, lang), lang)
+                )
                 .limit(_PERSON_SECTION_MAX)
             )
             .scalars()
             .all()
         )
         states = rollup.item_state_map(db, user.id, [it.id for it in items])
-        movies = [movie_card(it, states.get(it.id)) for it in items]
+        movies = [movie_card(it, states.get(it.id), lang=lang) for it in items]
 
     shows: list[dict] = []
     if show_lib_ids:
@@ -220,28 +236,34 @@ def person_detail(
                         PlexShow.directors.contains([name]),
                     ),
                 )
-                .order_by(PlexShow.year.desc().nullslast(), func.lower(PlexShow.title))
+                .order_by(
+                    PlexShow.year.desc().nullslast(), collated(title_col(PlexShow, lang), lang)
+                )
                 .limit(_PERSON_SECTION_MAX)
             )
             .scalars()
             .all()
         )
         statuses = rollup.state_map(db, user.id, [s.id for s in show_rows])
-        shows = [show_card(sh, statuses.get(sh.id, "new")) for sh in show_rows]
+        shows = [show_card(sh, statuses.get(sh.id, "new"), lang=lang) for sh in show_rows]
 
     known_for = _resolve_known_for(
-        db, person.known_for if person else None, user.id, movie_lib_ids, show_lib_ids
+        db, person.known_for if person else None, user.id, movie_lib_ids, show_lib_ids, lang
     )
     return {
         "name": name,
         "photo": person.photo_thumb if person else None,
-        "biography": person.biography if person else None,
+        # The Hungarian biography for a Hungarian reader, the instance-language one when TMDB has none.
+        "biography": ((person.biography_hu if lang == "hu" else None) or person.biography)
+        if person
+        else None,
         "birthday": person.birthday if person else None,
         "deathday": person.deathday if person else None,
         "place_of_birth": person.place_of_birth if person else None,
         "known_for_department": person.known_for_department if person else None,
         "also_known_as": (person.also_known_as if person else None) or [],
         "known_for": known_for,
+        "enriching": enriching,
         "movies": movies,
         "shows": shows,
     }

backend/app/routes/plex/playback.py

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

backend/app/routes/plex/playlists.py

@@ -2,9 +2,11 @@
 
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
-from sqlalchemy import delete, func, select, update
+from fastapi import APIRouter, Depends
+from typing import Annotated
+
+from pydantic import BaseModel, Field, model_validator
+from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 
 from app.auth import current_user
@@ -17,17 +19,14 @@ from app.models import (
     PlexState,
     User,
 )
-from app.plex.cards import leaf_card
+from app.plex.cards import display_title, leaf_card, norm_lang
 from app.plex.lookups import by_rating_key
-from app.routes._common import owned_or_404
+from app.routes._common import owned_or_404, not_found
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
 
-def _own_playlist_or_404(db: Session, pid: int, user: User) -> PlexPlaylist:
-    return owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
-
-
 def _playlist_card(pl: PlexPlaylist, count: int, thumb_rk: str | None) -> dict:
     return {
         "id": pl.id,
@@ -120,7 +119,7 @@ def create_playlist(
 ) -> dict:
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     pl = PlexPlaylist(user_id=user.id, title=title)
     db.add(pl)
     db.flush()
@@ -138,9 +137,13 @@ def create_playlist(
 
 @router.get("/playlists/{pid}")
 def playlist_detail(
-    pid: int, user: User = Depends(current_user), db: Session = Depends(get_db)
+    pid: int,
+    lang: str = "en",
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    lang = norm_lang(lang)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     rows = db.execute(_playlist_item_query(pid)).all()
     items = [it for (_pi, it) in rows]
     states = {
@@ -164,8 +167,9 @@ def playlist_detail(
         leaf_card(
             it,
             states.get(it.id),
-            shows[it.show_id].title if it.show_id in shows else None,
+            display_title(shows[it.show_id], lang) if it.show_id in shows else None,
             shows[it.show_id].rating_key if it.show_id in shows else None,
+            lang=lang,
         )
         for it in items
     ]
@@ -183,10 +187,10 @@ def rename_playlist(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     title = body.title.strip()
     if not title:
-        raise HTTPException(status_code=400, detail="title is required")
+        raise refused(400, "title_required")
     pl.title = title
     db.commit()
     count = (
@@ -203,7 +207,7 @@ def rename_playlist(
 def delete_playlist(
     pid: int, user: User = Depends(current_user), db: Session = Depends(get_db)
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     db.delete(pl)
     db.commit()
     return {"deleted": pid}
@@ -220,10 +224,11 @@ def playlist_add_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    # Locked (like every add / reorder here): two adds otherwise read the same max position.
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
     it = by_rating_key(db, PlexItem, body.item_rating_key)
     if it is None:
-        raise HTTPException(status_code=404, detail="Unknown item")
+        raise not_found("item")
     exists = (
         db.execute(
             select(PlexPlaylistItem).where(
@@ -252,7 +257,9 @@ def playlist_remove_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist_or_404(db, pid, user)
+    # Locked like the adds and the reorder: the list row first, then its items — a remove that
+    # locked an item row before a reorder locked the list deadlocked against it.
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
     it = by_rating_key(db, PlexItem, item_rating_key)
     if it is not None:
         db.execute(
@@ -288,16 +295,75 @@ def _items_by_rks(db: Session, rks: list) -> list[PlexItem]:
     return out
 
 
+class PlexItemAddBulkIn(PlexItemKeysIn):
+    # Where each key goes back (E28 S3e2, the list page's "Undo" of a removal): an index over the
+    # ORDERED rows, one per key. The two-call shape (append, then send the whole order) leaves the rows
+    # at the end whenever the second call fails, and the order it sends would overwrite anything
+    # another tab changed in between.
+    positions: list[Annotated[int, Field(ge=0)]] | None = None
+
+    @model_validator(mode="after")
+    def _one_position_per_key(self):
+        if self.positions is not None and len(self.positions) != len(self.item_rating_keys):
+            raise ValueError("positions must pair one-to-one with item_rating_keys")
+        return self
+
+
+def _insert_at(db: Session, pid: int, placed: list[tuple[int, PlexItem]]) -> int:
+    """Insert new rows at their indices (ascending, so each index is where the row stood when the
+    rows before it were back), renumber the whole list 0..n-1, and say how many were added. An item
+    already in the list does not move: the add stays idempotent."""
+    rows = list(
+        db.execute(
+            select(PlexPlaylistItem)
+            .where(PlexPlaylistItem.playlist_id == pid)
+            .order_by(PlexPlaylistItem.position, PlexPlaylistItem.id)
+        ).scalars()
+    )
+    present = {r.item_id for r in rows}
+    added = 0
+    for at, it in sorted(placed, key=lambda p: p[0]):
+        if it.id in present:
+            continue
+        row = PlexPlaylistItem(playlist_id=pid, item_id=it.id, position=0)
+        db.add(row)
+        rows.insert(min(at, len(rows)), row)
+        present.add(it.id)
+        added += 1
+    for i, r in enumerate(rows):
+        r.position = i
+    return added
+
+
 @router.post("/playlists/{pid}/items/bulk")
 def playlist_add_bulk(
     pid: int,
-    body: PlexItemKeysIn,
+    body: PlexItemAddBulkIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """Append many items at once (a whole season/show). Already-present items are skipped; the input
-    order is preserved for the newly-added ones. Returns how many were added + the new total."""
-    pl = _own_playlist_or_404(db, pid, user)
+    order is preserved for the newly-added ones. With `positions`, each key is put back at its index
+    instead of appended. Returns how many were added + the new total."""
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
+    if body.positions is not None:
+        by_rk = {it.rating_key: it for it in _items_by_rks(db, body.item_rating_keys)}
+        placed = [
+            (at, by_rk[str(rk)])
+            for rk, at in zip(body.item_rating_keys, body.positions, strict=True)
+            if str(rk) in by_rk
+        ]
+        added = _insert_at(db, pid, placed)
+        if added:
+            pl.updated_at = datetime.now(timezone.utc)
+        db.commit()
+        total = (
+            db.scalar(
+                select(func.count(PlexPlaylistItem.id)).where(PlexPlaylistItem.playlist_id == pid)
+            )
+            or 0
+        )
+        return {"ok": True, "added": added, "item_count": total}
     items = _items_by_rks(db, body.item_rating_keys)
     existing = set(
         db.execute(
@@ -328,7 +394,7 @@ def playlist_add_bulk(
         )
         or 0
     )
-    return {"added": added, "item_count": total}
+    return {"ok": True, "added": added, "item_count": total}
 
 
 @router.post("/playlists/{pid}/items/remove-bulk")
@@ -340,7 +406,7 @@ def playlist_remove_bulk(
 ) -> dict:
     """Remove many items at once (a whole season/show, or a multi-select). Returns how many were
     removed + the new total."""
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
     ids = [it.id for it in _items_by_rks(db, body.item_rating_keys)]
     removed = 0
     if ids:
@@ -359,7 +425,7 @@ def playlist_remove_bulk(
         )
         or 0
     )
-    return {"removed": removed, "item_count": total}
+    return {"ok": True, "removed": removed, "item_count": total}
 
 
 @router.put("/playlists/{pid}/order")
@@ -370,7 +436,7 @@ def reorder_playlist(
     db: Session = Depends(get_db),
 ) -> dict:
     """Set the playlist order from an explicit list of item rating_keys (0-based positions)."""
-    pl = _own_playlist_or_404(db, pid, user)
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
     order = body.item_rating_keys
     id_by_rk = {
         it.rating_key: it.id
@@ -378,14 +444,27 @@ def reorder_playlist(
             select(PlexItem).where(PlexItem.rating_key.in_(order or [""]))
         ).scalars()
     }
-    for pos, rk in enumerate(order):
-        iid = id_by_rk.get(rk)
-        if iid is not None:
-            db.execute(
-                update(PlexPlaylistItem)
-                .where(PlexPlaylistItem.playlist_id == pid, PlexPlaylistItem.item_id == iid)
-                .values(position=pos)
-            )
+    rows = {
+        r.item_id: r
+        for r in db.execute(
+            select(PlexPlaylistItem).where(PlexPlaylistItem.playlist_id == pid)
+        ).scalars()
+    }
+    pos = 0
+    seen: set[int] = set()
+    for rk in order:
+        row = rows.get(id_by_rk.get(rk, -1))
+        if row is not None and row.item_id not in seen:
+            row.position = pos
+            pos += 1
+            seen.add(row.item_id)
+    # Rows the payload omitted (added in another tab meanwhile) keep their relative order after
+    # the given ones, so no two rows share a position (the YouTube reorder does the same).
+    for row in sorted(
+        (r for iid, r in rows.items() if iid not in seen), key=lambda r: (r.position, r.id)
+    ):
+        row.position = pos
+        pos += 1
     pl.updated_at = datetime.now(timezone.utc)
     db.commit()
     return {"ok": True}

backend/app/routes/public.py

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

backend/app/routes/saved_views.py

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

backend/app/routes/scheduler.py

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

backend/app/routes/search.py

@@ -16,7 +16,7 @@ dropped from the search response up front)."""
 from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel
 from sqlalchemy import and_, delete, func, or_, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
@@ -44,6 +44,8 @@ from app.sync.videos import insert_stubs, apply_video_details, parse_dt
 from app.youtube import search_scrape
 from app.youtube.client import YouTubeClient, YouTubeError
 from app.youtube.shorts import make_client, probe_is_short
+from app.refusal import refused
+from app.routes._common import youtube_refusal
 
 log = logs.get_logger(__name__)
 router = APIRouter(prefix="/api/search", tags=["search"])
@@ -128,7 +130,7 @@ def _ingest_candidates(
         try:
             with quota.attribute(user.id, quota.QuotaAction.CHANNELS_DISCOVER):
                 details = yt.get_channels(new_channel_ids)
-            apply_channel_details(db, details)
+            apply_channel_details(db, details, new_channel_ids)
             db.commit()
         except YouTubeError:
             # The stubs remain and the details can be backfilled later — but until they are, those
@@ -258,7 +260,7 @@ def search_youtube(
     page, so it returns a single page (≤50) regardless. `cursor` lets the caller fetch further."""
     term = (q or "").strip()
     if not term:
-        raise HTTPException(status_code=400, detail="A search term is required.")
+        raise refused(400, "search_term_required")
     limit = max(1, min(limit, 100))
 
     # Source: "scrape" (InnerTube, no API quota) or "api" (search.list, 100 units/page).
@@ -275,20 +277,14 @@ def search_youtube(
             "a live search was refused: the per-user daily cap is spent",
             extra=logs.event("search.refused", reason="daily_cap", limit=daily_limit),
         )
-        raise HTTPException(
-            status_code=429,
-            detail=f"You've reached today's YouTube search limit ({daily_limit}). Try again tomorrow.",
-        )
+        raise refused(429, "search_daily_limit", limit=daily_limit)
     # The 100-unit budget pre-check only applies to the API source.
     if source == "api" and not quota.can_spend(db, SEARCH_COST):
         log.info(
             "a live search was refused: the shared YouTube budget is spent",
             extra=logs.event("search.refused", reason="shared_quota", cost=SEARCH_COST),
         )
-        raise HTTPException(
-            status_code=429,
-            detail="The shared YouTube quota for today is used up. Try again tomorrow.",
-        )
+        raise refused(429, "quota_spent")
 
     # Channels this user has blocked are dropped before ingestion — never shown, never stored.
     blocked = set(
@@ -313,9 +309,14 @@ def search_youtube(
                 # dropout (auto-retry + "connection lost" banner — lib/api/core RETRIABLE_GATEWAY),
                 # which hides the real message and burns a second quota-costed search. Upstream failure
                 # on a JSON endpoint = 422 + message; reserve 5xx for the raw byte-proxies. (B-core-1)
-                raise HTTPException(
-                    status_code=422, detail=f"YouTube search failed: {exc}"
-                ) from exc
+                # A Data API failure is logged where it happened; the scraper's is not, and its text
+                # no longer rides the answer — so it is said here.
+                if isinstance(exc, search_scrape.ScrapeError):
+                    log.warning(
+                        "the YouTube search scrape failed",
+                        extra=logs.event("search.scrape_failed", error=str(exc)),
+                    )
+                raise youtube_refusal(exc) from exc
 
             # Drop currently-live/upcoming, channel-less, and blocked-channel results.
             candidates = [
@@ -357,9 +358,7 @@ def search_youtube(
                     )
                 if collected:
                     break  # keep what earlier pages already gathered
-                raise HTTPException(
-                    status_code=422, detail=f"YouTube search failed: {exc}"
-                ) from exc
+                raise youtube_refusal(exc) from exc
             next_cursor = page["next_page_token"]
             # The API source pages cost 100 units each — never auto-page; one page per request.
             if source == "api" or len(collected) >= limit or not next_cursor:
@@ -412,7 +411,7 @@ def clear_search(
     find. Kept videos and organically-owned ones are left untouched."""
     ids = body.video_ids
     if not ids:
-        return {"removed": 0}
+        return {"ok": True, "removed": 0}
     db.execute(
         delete(SearchFind).where(SearchFind.user_id == user.id, SearchFind.video_id.in_(ids))
     )
@@ -432,4 +431,4 @@ def clear_search(
         )
     ).rowcount
     db.commit()
-    return {"removed": removed}
+    return {"ok": True, "removed": removed}

backend/app/routes/setup.py

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

backend/app/routes/sync.py

@@ -7,10 +7,13 @@ from app.audit import AuditAction
 from app.auth import admin_user, current_user, has_read_scope, require_human
 from app.db import get_db
 from app.models import Channel, Subscription, User, Video
+from app.routes._common import youtube_refusal
 from app.ratelimit import RateLimiter
 from app.sync.runner import estimate_deep_backfill
 from app.sync.subscriptions import import_subscriptions
 from app.scheduler import running_job_ids
+from app.youtube.client import YouTubeError
+from app.refusal import refused
 
 router = APIRouter(prefix="/api/sync", tags=["sync"])
 
@@ -26,17 +29,20 @@ _sync_limiter = RateLimiter(max_events=3, window_seconds=600)
 def sync_subscriptions(user: User = Depends(require_human), db: Session = Depends(get_db)) -> dict:
     if not has_read_scope(user):
         # No YouTube read grant yet — the onboarding wizard hasn't been completed.
-        raise HTTPException(
-            status_code=403,
-            detail="Connect your YouTube account (read access) to import subscriptions.",
-        )
+        raise refused(403, "youtube_read_scope")
     if not _sync_limiter.allow(str(user.id)):
         raise HTTPException(status_code=429, detail={"code": "sync_cooldown"})
-    with quota.measured(db, user.id, quota.QuotaAction.SUBSCRIPTIONS_PULL) as m:
-        result = import_subscriptions(db, user)
+    try:
+        with quota.measured(db, user.id, quota.QuotaAction.SUBSCRIPTIONS_PULL) as m:
+            result = import_subscriptions(db, user)
+    except YouTubeError as exc:
+        # The onboarding wizard's first call: an unguarded failure here was a raw 500 and the
+        # blocking "Server error" dialog, with nothing the user could act on (E9 F1).
+        db.rollback()
+        raise youtube_refusal(exc)
     result["quota_used_estimate"] = m.used
     result["quota_remaining_today"] = m.remaining
-    return result
+    return {"ok": True, **result}
 
 
 @router.get("/status")
@@ -65,7 +71,7 @@ def sync_status(user: User = Depends(current_user), db: Session = Depends(get_db
 def my_status(user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
     """Per-user sync progress: how far the channels *this* user subscribes to have synced."""
     sub_join = and_(Subscription.channel_id == Channel.id, Subscription.user_id == user.id)
-    total, details_synced, recent_synced, deep_done = db.execute(
+    total, details_synced, recent_synced, all_deep_done = db.execute(
         select(
             func.count(Channel.id),
             func.count(Channel.details_synced_at),
@@ -76,7 +82,7 @@ def my_status(user: User = Depends(current_user), db: Session = Depends(get_db))
         .join(Subscription, sub_join)
     ).one()
     total = total or 0
-    deep_done = int(deep_done or 0)
+    all_deep_done = int(all_deep_done or 0)
 
     # Per-user full-history (deep) backfill: channels this user has opted in, and an ETA
     # for the still-pending ones (quota-bound estimate).
@@ -91,6 +97,10 @@ def my_status(user: User = Depends(current_user), db: Session = Depends(get_db))
         .all()
     )
     deep_eta = estimate_deep_backfill(db, deep_requested_channels)
+    # "done / requested" is shown as one ratio, so both halves count the SAME channels: the ones this
+    # user asked full history for. Counting every subscribed channel whose back-catalog happens to be
+    # complete (another user asked, or it was short) gave "342/329".
+    deep_done = sum(1 for c in deep_requested_channels if c.backfill_done)
 
     my_videos = db.scalar(
         select(func.count(Video.id)).join(
@@ -111,7 +121,7 @@ def my_status(user: User = Depends(current_user), db: Session = Depends(get_db))
         "channels_recent_synced": recent_synced,
         "channels_deep_done": deep_done,
         "channels_recent_pending": total - recent_synced,
-        "channels_deep_pending": total - deep_done,
+        "channels_deep_pending": total - all_deep_done,
         "channels_deep_requested": len(deep_requested_channels),
         "deep_pending_count": deep_eta["channels_pending"],
         "deep_eta_seconds": deep_eta["eta_seconds"],
@@ -137,7 +147,7 @@ def deep_all(
         update(Subscription).where(Subscription.user_id == user.id).values(deep_requested=on)
     )
     db.commit()
-    return {"updated": result.rowcount, "deep_requested": on}
+    return {"ok": True, "updated": result.rowcount, "deep_requested": on}
 
 
 @router.post("/pause")
@@ -145,7 +155,7 @@ def pause_sync(admin: User = Depends(admin_user), db: Session = Depends(get_db))
     state.set_sync_paused(db, True)
     audit.record(db, admin.id, AuditAction.SYNC_PAUSE, summary="Background sync paused")
     db.commit()
-    return {"paused": True}
+    return {"ok": True, "paused": True}
 
 
 @router.post("/resume")
@@ -153,4 +163,4 @@ def resume_sync(admin: User = Depends(admin_user), db: Session = Depends(get_db)
     state.set_sync_paused(db, False)
     audit.record(db, admin.id, AuditAction.SYNC_RESUME, summary="Background sync resumed")
     db.commit()
-    return {"paused": False}
+    return {"ok": True, "paused": False}

backend/app/routes/tags.py

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

backend/app/scheduler.py

@@ -9,7 +9,7 @@ from typing import Callable
 from apscheduler.schedulers.background import BackgroundScheduler
 from sqlalchemy import select
 
-from app import audit, logs, logsink, progress, quota
+from app import audit, debugsession, logs, logsink, progress, quota
 from app.audit import AuditAction
 from app.config import settings
 from app.db import SessionLocal
@@ -18,6 +18,7 @@ from app.downloads.gc import run_download_gc
 from app.models import SchedulerSetting, User
 from app.plex.sync import sync as run_plex_sync
 from app.plex.tmdb import run_enrich as run_tmdb_enrich
+from app.plex.tmdb import run_people_enrich
 from app.plex.watch_sync import run_plex_watch_reconcile, run_plex_watch_sync
 from app.notifications import create_notification
 from app.state import is_sync_paused
@@ -69,6 +70,7 @@ JOB_INTERVALS: dict[str, int] = {
     "plex_watch_sync": settings.plex_watch_sync_interval_min,
     "plex_watch_reconcile": settings.plex_watch_reconcile_interval_min,
     "tmdb_enrich": settings.tmdb_enrich_interval_min,
+    "people_enrich": settings.people_enrich_interval_min,
     "audit_gc": settings.audit_gc_minutes,
     "log_gc": settings.log_gc_minutes,
 }
@@ -115,7 +117,9 @@ def _record(name: str, **fields) -> None:
         _activity.setdefault(name, {}).update(fields)
 
 
-def _notify_done(db, actor_id: int, job_id: str, status: str, summary: str | None) -> None:
+def _notify_done(
+    db, actor_id: int, job_id: str, status: str, summary: str | None, result: dict | None = None
+) -> None:
     """Post a completion notice to the triggering admin's inbox (manual runs only). Best
     effort — a notification failure must never mask the job's own outcome."""
     try:
@@ -125,7 +129,7 @@ def _notify_done(db, actor_id: int, job_id: str, status: str, summary: str | Non
             type="scheduler",
             title=f"{job_id}: {status}",  # English fallback; UI renders translated from data
             body=summary,
-            data={"job_id": job_id, "status": status, "summary": summary},
+            data={"job_id": job_id, "status": status, "summary": summary, "result": result},
         )
     except Exception:
         db.rollback()
@@ -140,7 +144,12 @@ def _run_changed(result) -> bool:
     if result is None:
         return False
     if isinstance(result, dict):
-        return any(isinstance(v, (int, float)) and v for v in result.values())
+        # A phased job (backfill's recent/deep, people_enrich's bios/portraits) nests a result per
+        # phase: a count inside a phase is a change too.
+        return any(
+            _run_changed(v) if isinstance(v, dict) else isinstance(v, (int, float)) and bool(v)
+            for v in result.values()
+        )
     if isinstance(result, (int, float)):
         return result != 0
     return bool(result)
@@ -152,6 +161,9 @@ def _audit_run(db, actor_id, job_id, status, summary, result) -> None:
     they changed something, so routine no-op polls don't spam the trail. Best-effort."""
     if actor_id is None and status == "ok" and not _run_changed(result):
         return
+    # The result as data too (E30): the audit log names it in the reader's language, as the inbox
+    # does; `summary` stays the English line of the row's own summary column.
+    data = _result_data(result)
     try:
         audit.record(
             db,
@@ -160,7 +172,7 @@ def _audit_run(db, actor_id, job_id, status, summary, result) -> None:
             target_type="job",
             target_id=job_id,
             summary=f"{job_id}: {status}" + (f" — {summary}" if summary else ""),
-            after={"status": status, "summary": summary},
+            after={"status": status, "summary": summary, **({"result": data} if data else {})},
         )
         db.commit()
     except Exception:
@@ -192,25 +204,41 @@ def _job(name: str, fn) -> None:
                 status="skipped",
                 last_finished=_now_iso(),
                 last_result="paused",
+                result=_PAUSED,
                 progress=None,
             )
             if actor_id is not None:
-                _notify_done(db, actor_id, name, "skipped", "sync paused")
-                _audit_run(db, actor_id, name, "skipped", "sync paused", None)
+                _notify_done(db, actor_id, name, "skipped", "sync paused", _PAUSED)
+                _audit_run(db, actor_id, name, "skipped", "sync paused", _PAUSED)
             return
         with progress.bind(sink):
             result = fn(db)
         summary = _summarize(result)
+        data = _result_data(result)
         log.info("job %s -> %s", name, result)
-        _record(name, status="ok", last_finished=_now_iso(), last_result=summary, progress=None)
+        _record(
+            name,
+            status="ok",
+            last_finished=_now_iso(),
+            last_result=summary,
+            result=data,
+            progress=None,
+        )
         if actor_id is not None:
-            _notify_done(db, actor_id, name, "ok", summary)
+            _notify_done(db, actor_id, name, "ok", summary, data)
         _audit_run(db, actor_id, name, "ok", summary, result)
     except Exception as exc:
         db.rollback()
-        log.exception("job %s failed", name)
+        log.exception("job %s failed", name, extra=logs.event("scheduler.job.failed", job=name))
         err = str(exc) or exc.__class__.__name__
-        _record(name, status="error", last_finished=_now_iso(), last_error=err, progress=None)
+        _record(
+            name,
+            status="error",
+            last_finished=_now_iso(),
+            last_error=err,
+            result=None,
+            progress=None,
+        )
         if actor_id is not None:
             _notify_done(db, actor_id, name, "error", err)
         _audit_run(db, actor_id, name, "error", err, None)
@@ -221,6 +249,21 @@ def _job(name: str, fn) -> None:
         db.close()
 
 
+# A skipped run's result, in the same shape as a job's own `{"skipped": …}`.
+_PAUSED = {"skipped": "sync paused"}
+
+
+def _result_data(result) -> dict | None:
+    """A job's result as the client names it in the reader's language (E30): the dict itself (counts,
+    a `skipped` / `reason` word, a nested dict per phase), `enrich`'s bare count as one. The one-line
+    `_summarize` is the English fallback."""
+    if isinstance(result, dict):
+        return result or None
+    if isinstance(result, int) and not isinstance(result, bool):
+        return {"enriched": result}
+    return None
+
+
 def _summarize(result) -> str | None:
     """Compact one-line rendering of a job's return value for the dashboard."""
     if result is None:
@@ -259,6 +302,7 @@ def scheduler_snapshot() -> dict:
                 "last_started": a.get("last_started"),
                 "last_finished": a.get("last_finished"),
                 "last_result": a.get("last_result"),
+                "result": a.get("result"),
                 "last_error": a.get("last_error"),
                 "progress": a.get("progress"),
             }
@@ -369,6 +413,12 @@ def _tmdb_enrich_job() -> None:
     _job("tmdb_enrich", run_tmdb_enrich)
 
 
+def _people_enrich_job() -> None:
+    # Make the people local (E30 S6): a batch of person bios from TMDB and a batch of portraits resized
+    # through Plex, so a person page and a cast strip never wait on an outside service.
+    _job("people_enrich", run_people_enrich)
+
+
 def _audit_gc_job() -> None:
     # Prune audit-log rows older than the admin-set retention (audit_retention_days; 0 = keep
     # forever). Pure DB, no quota.
@@ -386,9 +436,13 @@ def _log_gc_job() -> None:
     def work(db):
         from app import sysconfig
 
-        reaped = logsink.gc(db, sysconfig.get_int(db, "log_retention_days"))
+        days = sysconfig.get_int(db, "log_retention_days")
+        reaped = logsink.gc(db, days)
+        # Debug sessions (E16) go with the rows they bundle; an open one past its cap is closed.
+        closed = debugsession.sweep(db)
+        sessions = debugsession.gc(db, days)
         db.commit()
-        return {"reaped": reaped}
+        return {"reaped": reaped, "sessions_closed": closed, "sessions_reaped": sessions}
 
     _job("log_gc", work)
 
@@ -411,6 +465,7 @@ JOB_FUNCS: dict[str, Callable[[], None]] = {
     "plex_watch_sync": _plex_watch_sync_job,
     "plex_watch_reconcile": _plex_watch_reconcile_job,
     "tmdb_enrich": _tmdb_enrich_job,
+    "people_enrich": _people_enrich_job,
     "audit_gc": _audit_gc_job,
     "log_gc": _log_gc_job,
 }

backend/app/sync/autotag.py

@@ -115,7 +115,9 @@ _TOPIC_SLUGS = {
     "Tourism": "Travel",
     "Fashion": "Fashion & Beauty",
     "Physical_attractiveness": "Fashion & Beauty",
-    "Humor": "Comedy",
+    # YouTube links the British page (…/wiki/Humour); the key was "Humor", so no channel ever got Comedy
+    # from its topic (E30).
+    "Humour": "Comedy",
     "Entertainment": "Entertainment",
     "Film": "Film",
     "Television_program": "TV",

backend/app/sync/playlists.py

@@ -8,13 +8,15 @@ ingested (with a stub channel) so the mirror is faithful."""
 
 import hashlib
 import json
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, contextmanager
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import TypeVar
 
-from sqlalchemy import delete, select
+from sqlalchemy import Engine, create_engine, delete, func, select
 from sqlalchemy.orm import Session
+from sqlalchemy.pool import NullPool
 
 from app import logs, progress, quota
 from app.auth import has_read_scope
@@ -27,6 +29,87 @@ log = logs.get_logger(__name__)
 # Cost of a single YouTube write op (playlists/playlistItems insert/update/delete).
 WRITE_UNIT_COST = 50
 
+# The advisory-lock namespaces ("PL" per playlist, "PU" per user), so a key cannot meet another
+# feature's lock on the same number (Postgres keeps the two-int keys apart from the one-bigint ones).
+_SYNC_LOCK_NS = 0x504C
+_USER_SYNC_LOCK_NS = 0x5055
+
+# The claims' own connections, outside the app pool: a claim is held for a whole push (seconds of
+# YouTube calls) beside the request's pooled session and quota's, so a burst of pushes drawing a
+# third pooled connection each ran the pool dry and stalled every other request for pool_timeout.
+# NullPool opens one per claim and closes it after, so a lock can never ride back into a pool either.
+_claim_engines: dict[str, Engine] = {}
+
+
+def _claim_engine(db: Session) -> Engine:
+    url = db.get_bind().engine.url
+    key = url.render_as_string(hide_password=False)
+    eng = _claim_engines.get(key)
+    if eng is None:
+        eng = _claim_engines[key] = create_engine(url, poolclass=NullPool, hide_parameters=True)
+    return eng
+
+
+@contextmanager
+def _advisory_claim(db: Session, ns: int, key: int) -> Iterator[bool]:
+    """Try a session-level advisory lock for the block on a connection of its own; yields whether it
+    was free. It survives the block's commits, and a crashed worker's lock dies with its connection
+    — no claim column that a crash leaves stuck."""
+    conn = _claim_engine(db).connect()
+    held = False
+    try:
+        held = bool(conn.scalar(select(func.pg_try_advisory_lock(ns, key))))
+        conn.commit()
+        yield held
+    finally:
+        try:
+            if held:
+                conn.scalar(select(func.pg_advisory_unlock(ns, key)))
+                conn.commit()
+        finally:
+            conn.close()
+
+
+def sync_claim(db: Session, playlist_id: int) -> AbstractContextManager[bool]:
+    """Claim one playlist's YouTube sync (push, re-pull, the scheduled mirror refresh) for the block;
+    yields whether it was free. A push reads YouTube, then writes both sides for seconds and commits
+    step by step, so a row lock ends at its first commit and two tabs (or a push and the scheduler)
+    interleave into a doubled YouTube item or a baseline recorded over the other's writes."""
+    return _advisory_claim(db, _SYNC_LOCK_NS, playlist_id)
+
+
+class PlaylistGone(Exception):
+    """The list a sync was working on was deleted meanwhile (another tab, the mirror drop). Its
+    items went with it, so a plan made now reads "every item removed here" — and would delete them
+    all from the YouTube playlist the reader chose to keep. The route answers 404."""
+
+
+def lock_playlists(db: Session, *playlist_ids: int) -> set[int]:
+    """Row-lock playlists before touching their items, several in id order. Every item write takes
+    the PLAYLIST first — the route edits, a push, a re-pull, the scheduled mirror refresh and a
+    delete alike: a writer that locked an item row first and the playlist second (a push's item
+    replace beside a remove) deadlocks against one that went the other way, and the loser is a
+    500. The rows are re-read, so `dirty`, the name and the sync baseline are the ones a finished
+    writer committed. Held to the caller's next commit — so no commit may come between this and
+    the write it guards. Returns the ids it found: a list deleted meanwhile is not among them."""
+    rows = db.scalars(
+        select(Playlist)
+        .where(Playlist.id.in_(sorted(set(playlist_ids))))
+        .order_by(Playlist.id)
+        .with_for_update()
+        .execution_options(populate_existing=True)
+    ).all()  # consumed: rows fetched are what refreshes the loaded objects
+    return {pl.id for pl in rows}
+
+
+def _lock_or_gone(db: Session, pl: Playlist) -> None:
+    """`lock_playlists` for a sync that goes on to write YouTube or the items: a list deleted since
+    it was read raises `PlaylistGone` (rolled back) instead of being planned as an empty one."""
+    pl_id = pl.id  # read first: the rollback expires `pl`, and its row is gone
+    if pl_id not in lock_playlists(db, pl_id):
+        db.rollback()
+        raise PlaylistGone(pl_id)
+
 
 def fingerprint(name: str, ids: list[str]) -> str:
     """A stable checksum of a playlist's name + ordered video ids. Stored as the synced
@@ -91,11 +174,18 @@ def parse_unavailable(pl: Playlist) -> set[str]:
     return _load_baseline(pl)[1]
 
 
-def _set_baseline(pl: Playlist, ids: list[str], unavailable: list[str] | None = None) -> None:
+def _set_baseline(
+    pl: Playlist,
+    ids: list[str],
+    unavailable: list[str] | None = None,
+    *,
+    name: str | None = None,
+) -> None:
     """Record `ids` as both the hash (drives `dirty`, over the local ids only) and the raw ordered
     set (drives merge). `unavailable` = un-ingestable-but-live YouTube ids to carry forward so the
-    next merge skips them; stored only when non-empty (keeps the common case a plain list)."""
-    pl.synced_fingerprint = fingerprint(pl.name, ids)
+    next merge skips them; stored only when non-empty (keeps the common case a plain list). `name`:
+    the title YouTube now has, when that may differ from the list's own (see the push)."""
+    pl.synced_fingerprint = fingerprint(pl.name if name is None else name, ids)
     if unavailable:
         pl.synced_video_ids = json.dumps({"ids": ids, "unavailable": list(unavailable)})
     else:
@@ -103,6 +193,25 @@ def _set_baseline(pl: Playlist, ids: list[str], unavailable: list[str] | None =
     pl.dirty = False
 
 
+def _set_baseline_under_lock(
+    db: Session,
+    pl: Playlist,
+    ids: list[str],
+    unavailable: list[str] | None = None,
+    *,
+    name: str,
+) -> None:
+    """A push's closing baseline: `ids` and `name` are what YouTube now holds. The push spent
+    seconds on YouTube writes since it replaced the local items, so an edit may have landed
+    meanwhile — lock the list and derive `dirty` from what is there, or the edit would read as
+    synced and never reach YouTube. The name too: the lock re-reads a rename made meanwhile, and a
+    baseline taken over THAT name matched it, so the list read clean with YouTube's title still the
+    old one (E28 review round 4)."""
+    _lock_or_gone(db, pl)
+    _set_baseline(pl, ids, unavailable, name=name)
+    recompute_dirty(db, pl)
+
+
 def recompute_dirty(db: Session, pl: Playlist) -> None:
     """Set `dirty` by comparing the current state to the synced baseline. Unlinked lists
     (and Watch later) are never dirty; a missing baseline counts as dirty (unknown YT state)."""
@@ -159,15 +268,13 @@ def _ensure_videos(db: Session, yt: YouTubeClient, video_ids: list[str]) -> None
     db.commit()
 
 
-def _replace_items_from_youtube(
-    db: Session, yt: YouTubeClient, pl: Playlist, ids: list[str]
-) -> list[str]:
+def _replace_items_from_youtube(db: Session, pl: Playlist, ids: list[str]) -> list[str]:
     """Mirror a YouTube playlist's ordered video ids into `pl`'s local items (authoritative
-    replace): ensure the videos exist in the catalog, keep only those present in their YT
-    order (de-duplicated), swap the items out, and reset the synced fingerprint + dirty flag.
-    `pl.name` must already be set to the desired name. The caller commits. Returns the final
-    ordered ids."""
-    _ensure_videos(db, yt, ids)
+    replace): keep only those present in the catalog in their YT order (de-duplicated), swap the
+    items out, and reset the synced fingerprint + dirty flag. The caller has ingested `ids`
+    (`_ensure_videos`, which commits) and THEN taken `lock_playlists`, set `pl.name`, and commits
+    after: an ingest in here re-fetched every id YouTube will not return (a private or deleted
+    video) and its commit let go of the lock before the replace. Returns the final ordered ids."""
     present = (
         set(db.execute(select(Video.id).where(Video.id.in_(ids))).scalars().all()) if ids else set()
     )
@@ -196,6 +303,21 @@ def sync_user_playlists(db: Session, user: User) -> dict:
     the user's local playlists and the built-in Watch later untouched."""
     if not has_read_scope(user):
         return {"synced": 0, "reason": "no read scope"}
+    with user_sync_claim(db, user.id) as free:
+        if not free:
+            return {"synced": 0, "reason": "busy"}
+        return pull_user_playlists(db, user)
+
+
+def user_sync_claim(db: Session, user_id: int) -> AbstractContextManager[bool]:
+    """Claim a user's bulk mirror pull for the block; yields whether it was free. Two runs at once
+    (the scheduler beside a manual "sync now", two tabs) both saw a YouTube list unmirrored and
+    each created its mirror — a duplicate row."""
+    return _advisory_claim(db, _USER_SYNC_LOCK_NS, user_id)
+
+
+def pull_user_playlists(db: Session, user: User) -> dict:
+    """The mirror pull itself; the caller holds `user_sync_claim`."""
     synced = 0
     with YouTubeClient(db, user) as yt:
         yt_playlists = list(yt.iter_my_playlists())
@@ -219,11 +341,15 @@ def sync_user_playlists(db: Session, user: User) -> dict:
             .scalars()
             .all()
         )
-        # Drop mirrors whose YouTube playlist no longer exists.
-        for ytid, pl in existing.items():
-            if ytid not in yt_ids:
-                db.delete(pl)
-        db.flush()
+        # Drop mirrors whose YouTube playlist no longer exists — locked first, as every item write.
+        gone = [pl for ytid, pl in existing.items() if ytid not in yt_ids]
+        if gone:
+            lock_playlists(db, *(pl.id for pl in gone))
+        for pl in gone:
+            db.delete(pl)
+        # Committed now: a run where no list below commits (all dirty, or all claimed) would
+        # otherwise drop the deletions with the session.
+        db.commit()
 
         for idx, p in enumerate(yt_playlists):
             ytid = p.get("id")
@@ -245,12 +371,27 @@ def sync_user_playlists(db: Session, user: User) -> dict:
                 )
                 db.add(pl)
                 db.flush()
-            else:
+            with sync_claim(db, pl.id) as free:
+                if not free:
+                    # The user is pushing or re-pulling this very list: it writes the same rows.
+                    # The next scheduled run refreshes it.
+                    continue
+                ids = list(yt.iter_my_playlist_video_ids(ytid))
+                # Ingest first — it commits — so the row lock below is held from the dirty check
+                # to the commit that replaces the items.
+                _ensure_videos(db, yt, ids)
+                # `dirty` read above is a snapshot from before the YouTube calls (sessions keep
+                # loaded rows past a commit): a remove or reorder made meanwhile must not be
+                # replaced by YouTube's order. Item writes lock the playlist row, so this waits for
+                # one in flight and sees what it committed.
+                lock_playlists(db, pl.id)
+                if pl.dirty:
+                    db.rollback()
+                    continue
                 pl.name = p.get("title") or pl.name
-            # Mirror is authoritative: replace the items to match YouTube's order.
-            ids = list(yt.iter_my_playlist_video_ids(ytid))
-            _replace_items_from_youtube(db, yt, pl, ids)
-            db.commit()
+                # Mirror is authoritative: replace the items to match YouTube's order.
+                _replace_items_from_youtube(db, pl, ids)
+                db.commit()
             synced += 1
     return {"synced": synced}
 
@@ -488,7 +629,8 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
     breaker = _Breaker(playlist_id=pl.id)
     with YouTubeClient(db, user) as yt:
         if not pl.yt_playlist_id:
-            pl.yt_playlist_id = yt.create_playlist(pl.name)
+            pushed_name = pl.name
+            pl.yt_playlist_id = yt.create_playlist(pushed_name)
             db.commit()
             created = 1
             # Brand-new playlist: just append every local video in order.
@@ -501,7 +643,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
                 if not isinstance(added, _Failed):
                     inserted += 1
             if not failures:
-                _set_baseline(pl, local)
+                _set_baseline_under_lock(db, pl, local, name=pushed_name)
             db.commit()
             return {
                 "created": created,
@@ -542,6 +684,14 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
         # merged order authoritatively. Do this first so local reflects the merge even if a later
         # YouTube write trips the breaker.
         _ensure_videos(db, yt, mp.add_to_local)
+        # `local` was read before the YouTube calls above: an add or remove committed meanwhile
+        # (another tab) would be undone by the replace below. Lock the list — the ingest's commit is
+        # behind us — and plan again from what is there now. Nothing new needs ingesting: a video
+        # the re-read adds is already a local row. A list deleted meanwhile stops here, before a plan
+        # over its now-empty items removes them all from YouTube.
+        _lock_or_gone(db, pl)
+        local = _local_video_ids(db, pl)
+        mp = merge_plan(parse_baseline(pl), local, yt_ids, effective_unavailable)
         # Only the ids that actually exist in the catalog can become local rows (a private/deleted
         # YouTube video won't ingest); keep the merged order, dropping any that didn't materialize.
         present = (
@@ -555,10 +705,12 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
         _set_local_items(db, pl, final_local)
         db.commit()
 
-        # --- YouTube side (metered, breaker-guarded).
-        if snippet is not None and (snippet.get("title") or "") != pl.name:
+        # --- YouTube side (metered, breaker-guarded). The name as of the lock above: the closing
+        # baseline records THIS one, whatever a rename made during the writes below says.
+        pushed_name = pl.name
+        if snippet is not None and (snippet.get("title") or "") != pushed_name:
             try:
-                yt.update_playlist_title(pl.yt_playlist_id, pl.name)
+                yt.update_playlist_title(pl.yt_playlist_id, pushed_name)
             except YouTubeError as exc:
                 # All the caller passes on is the word "title", which says the rename did not
                 # happen but not that YouTube refused it, or why.
@@ -626,7 +778,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
                 (effective_unavailable | {v for v in mp.add_to_local if v not in present})
                 & yt_id_set
             )
-            _set_baseline(pl, final_local, unavailable)
+            _set_baseline_under_lock(db, pl, final_local, unavailable, name=pushed_name)
         db.commit()
     return {
         "created": created,
@@ -652,9 +804,11 @@ def repull_playlist(db: Session, user: User, pl: Playlist) -> dict:
         snippet = yt.get_playlist_snippet(pl.yt_playlist_id)
         if snippet is None:
             raise YouTubeError("Playlist no longer exists on YouTube")
-        pl.name = snippet.get("title") or pl.name
         ids = list(yt.iter_my_playlist_video_ids(pl.yt_playlist_id))
-        ordered = _replace_items_from_youtube(db, yt, pl, ids)
+        _ensure_videos(db, yt, ids)
+        _lock_or_gone(db, pl)
+        pl.name = snippet.get("title") or pl.name
+        ordered = _replace_items_from_youtube(db, pl, ids)
         db.commit()
     return {"items": len(ordered)}
 
@@ -670,11 +824,19 @@ def sync_all_playlists(db: Session) -> dict:
         try:
             with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
                 total += sync_user_playlists(db, user).get("synced", 0)
-        except YouTubeError:
+        except YouTubeError as exc:
             db.rollback()
-            log.warning("Playlist sync failed for user %s", user.id)
+            log.warning(
+                "Playlist sync failed for user %s",
+                user.id,
+                extra=logs.event("sync.playlists.failed", user_id=user.id, reason=exc.reason),
+            )
         except Exception:
             db.rollback()
-            log.exception("Playlist sync crashed for user %s", user.id)
+            log.exception(
+                "Playlist sync crashed for user %s",
+                user.id,
+                extra=logs.event("sync.playlists.crashed", user_id=user.id),
+            )
         progress.report(i, len(users), "playlist_sync")
     return {"users": len(users), "playlists_synced": total}

backend/app/sync/runner.py

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

backend/app/sync/subscriptions.py

@@ -1,8 +1,9 @@
 """Import the authenticated user's YouTube subscriptions and channel metadata."""
 
-from datetime import datetime, timezone
+from collections.abc import Iterable
+from datetime import datetime, timedelta, timezone
 
-from sqlalchemy import select
+from sqlalchemy import or_, select
 from sqlalchemy.orm import Session
 
 from app import logs
@@ -47,8 +48,37 @@ def _external_links(branding: dict) -> list | None:
     return out or None
 
 
-def apply_channel_details(db: Session, items: list[dict]) -> None:
+# How old a channel's metadata may get before it is fetched again. Banners, avatars, descriptions and
+# counts change on YouTube, and an old banner URL stops resolving at all — without a refresh a channel
+# kept whatever it had the day it was first seen. A week keeps counts roughly current at almost no
+# cost: `channels.list` is 1 quota unit per 50 channels, and only the stale ones are asked for.
+DETAILS_MAX_AGE = timedelta(days=7)
+
+
+def details_stale(channel: Channel, now: datetime) -> bool:
+    """Whether `channel`'s metadata is missing or older than DETAILS_MAX_AGE (see `details_stale_clause`)."""
+    synced = channel.details_synced_at
+    return synced is None or synced < now - DETAILS_MAX_AGE
+
+
+def details_stale_clause(now: datetime):
+    """`details_stale` as a WHERE clause, so the batch import and a single channel agree on "stale"."""
+    return or_(
+        Channel.details_synced_at.is_(None),
+        Channel.details_synced_at < now - DETAILS_MAX_AGE,
+    )
+
+
+def apply_channel_details(db: Session, items: list[dict], asked: Iterable[str]) -> None:
+    """Write `channels.list`'s answer onto the rows. `asked` is every id the call asked for: one
+    YouTube did not return (terminated, deleted) is stamped as synced too — otherwise it stays
+    stale forever and every view / import asks for it again, spending quota on a known miss."""
     now = datetime.now(timezone.utc)
+    returned = {item["id"] for item in items}
+    for cid in set(asked) - returned:
+        missing = db.get(Channel, cid)
+        if missing is not None:
+            missing.details_synced_at = now
     for item in items:
         channel = db.get(Channel, item["id"])
         if channel is None:
@@ -92,7 +122,7 @@ def should_prune(fetched_count: int, existing_count: int) -> bool:
 def import_subscriptions(db: Session, user: User) -> dict:
     """Pull all subscriptions for `user`, upsert channels + subscription links, prune
     channels the user has unsubscribed from on YouTube, and fetch channel details for
-    any channel we don't have details for yet."""
+    any channel whose details are missing or stale (`DETAILS_MAX_AGE`)."""
     fetched: dict[str, dict] = {}
     new_channels = 0
 
@@ -145,12 +175,12 @@ def import_subscriptions(db: Session, user: User) -> dict:
                     removed += 1
         db.commit()
 
-        # Fetch details for channels that don't have them yet.
+        # Fetch details for channels that don't have them yet, or had them too long ago.
         need_details = (
             db.execute(
                 select(Channel).where(
                     Channel.id.in_(fetched.keys()),
-                    Channel.details_synced_at.is_(None),
+                    details_stale_clause(datetime.now(timezone.utc)),
                 )
             )
             .scalars()
@@ -158,8 +188,9 @@ def import_subscriptions(db: Session, user: User) -> dict:
         )
         detailed = 0
         if need_details:
-            items = yt.get_channels([c.id for c in need_details])
-            apply_channel_details(db, items)
+            ids = [c.id for c in need_details]
+            items = yt.get_channels(ids)
+            apply_channel_details(db, items, ids)
             detailed = len(items)
         db.commit()
 

backend/app/sysconfig.py

@@ -91,6 +91,7 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec(
         "backfill_recent_max_days", "int", "backfill", "backfill_recent_max_days", min=1, max=36_500
     ),
+    ConfigSpec("rss_fallback_hours", "int", "backfill", "rss_fallback_hours", min=0, max=168),
     # --- Shorts probe ---
     ConfigSpec(
         "shorts_probe_max_seconds", "int", "shorts", "shorts_probe_max_seconds", min=1, max=3_600
@@ -136,10 +137,29 @@ SPECS: tuple[ConfigSpec, ...] = (
         min=1,
         max=100_000,
     ),
-    # min=1, NOT 0: the per-file cap is enforced as `if cap and size > cap`, so a stored 0 would read
-    # as falsy and SILENTLY disable the limit (an unbounded streamed write to the volume). Floor it at
-    # 1 so the cap is always active; the overall footprint is separately bounded by the byte quota.
-    ConfigSpec("download_upload_max_bytes", "int", "downloads", "download_upload_max_bytes", min=1),
+    # min=1, NOT 0: a stored 0 used to read as "no per-file cap" (the cap was enforced as
+    # `if cap and size > cap`, so a falsy value disabled it). Since P1 the route passes this number
+    # straight to `capped_stream_to`, where 0 would refuse every upload instead — the opposite
+    # failure, and the reason `config.download_upload_max_bytes` carries its own `ge=1`. Either way
+    # a stored 0 is wrong, so it is floored at 1; the overall footprint is separately bounded by the
+    # byte quota.
+    # `max` is not cosmetic: `bodylimit.ROUTE_MAX_BODY_BYTES` refuses an upload body over exactly
+    # this number at the edge, before the route's own check ever sees it. An admin allowed to raise
+    # the knob past the edge would get 413s from a layer the admin page never mentions, so the two
+    # are pinned together here and `tests/test_body_limit.py` holds them that way. Below the edge is
+    # the useful direction and the one the knob exists for: a lowered knob is what makes the route's
+    # own 422 — the one carrying this figure — the answer the user gets. `_coerce` also
+    # REJECTS a stored value outside these bounds on read (falling back to the env default, with a
+    # warning) — neither bound has always been what it is now, so a legal-when-written override can
+    # be sitting in the database already.
+    ConfigSpec(
+        "download_upload_max_bytes",
+        "int",
+        "downloads",
+        "download_upload_max_bytes",
+        min=1,
+        max=settings.download_upload_max_bytes,
+    ),
     ConfigSpec(
         "download_retention_days", "int", "downloads", "download_retention_days", min=0, max=3_650
     ),
@@ -175,6 +195,7 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec("plex_overlay_map", "str", "plex", "plex_overlay_map"),
     # (plex_sync_interval_min is tuned from the Scheduler dashboard, not here — it's a scheduler job.)
     ConfigSpec("plex_max_transcodes", "int", "plex", "plex_max_transcodes", min=0, max=16),
+    ConfigSpec("plex_max_sessions", "int", "plex", "plex_max_sessions", min=1, max=64),
     # Transcode re-encode tuning (E6 S1). The libx264 knobs apply only to the software fallback.
     # crf 0–51 (x264 range); max_height 0 = source.
     ConfigSpec("plex_transcode_hw", "choice", "plex", "plex_transcode_hw"),
@@ -190,6 +211,10 @@ SPECS: tuple[ConfigSpec, ...] = (
     # --- TMDB enrichment (E5 S2; optional) — the API key is the only secret ---
     ConfigSpec("tmdb_api_key", "str", "tmdb", "tmdb_api_key", secret=True),
     ConfigSpec("tmdb_language", "str", "tmdb", "tmdb_language"),
+    # --- Bug reports (E16): the Gitea issue tracker a debug session's issue goes to ---
+    ConfigSpec("issues_gitea_url", "str", "issues", "issues_gitea_url"),
+    ConfigSpec("issues_gitea_repo", "str", "issues", "issues_gitea_repo"),
+    ConfigSpec("issues_gitea_token", "str", "issues", "issues_gitea_token", secret=True),
     # (tmdb_enrich_interval_min is a scheduler job, tuned from the Scheduler dashboard; tmdb_enrich_batch
     # is a config.py default — both stay out of SPECS, like plex_sync_interval_min.)
 )
@@ -210,17 +235,49 @@ def _default(s: ConfigSpec):
     return getattr(settings, s.default_attr)
 
 
+class InvalidSetting(ValueError):
+    """A value `set_value` refuses, as a reason the UI translates (`errors.refused.setting_<reason>`)
+    plus what the sentence needs — the English message is for logs only. A ValueError still, so a
+    caller that only needs "refused or not" keeps working."""
+
+    def __init__(self, key: str, reason: str, **params: object):
+        super().__init__(f"{key}: {reason} {params}")
+        self.key = key
+        self.reason = reason
+        self.params = params
+
+
 def _choice(s: ConfigSpec, raw: object) -> str:
-    """The canonical spelling of `raw` among the key's choices (any letter case), or ValueError."""
+    """The canonical spelling of `raw` among the key's choices (any letter case), or InvalidSetting."""
     option = canonical_choice(s.choices, raw)
     if option is None:
-        raise ValueError(f"{s.key} must be one of: {', '.join(s.choices)}")
+        raise InvalidSetting(s.key, "not_a_choice", choices=", ".join(s.choices))
     return option
 
 
+class OutOfRange(ValueError):
+    """A stored int override that no longer satisfies its spec's bounds."""
+
+
 def _coerce(s: ConfigSpec, raw: str):
     if s.type == "int":
-        return int(raw)
+        # Bounds are checked on READ, not only in `set_value`. Bounds get ADDED to a spec
+        # (download_upload_max_bytes gained a `max` when SEC-20 started enforcing the same number at
+        # the edge; its `min` went 0 → 1 during E7) and env defaults get LOWERED, and either leaves
+        # a stored value that was legal when it was written. Serving it is how one layer ends up
+        # acting on a number another layer refuses, with the admin page showing a value outside the
+        # range it renders.
+        #
+        # It raises rather than CLAMPING, and that distinction cost a round: clamping is a silent
+        # rewrite, and silently rewriting is exactly what this module refuses to do elsewhere. The
+        # case that settles it is a stored 0 for download_upload_max_bytes — legal when `min` was 0,
+        # and meaning "no per-file cap" to the route that reads it. Clamped to `min=1` it becomes a
+        # ONE-BYTE cap and uploads stop working with nothing in the log. Raising drops it into the
+        # same fallback the uncoercible path uses: the env default, and one warning.
+        v = int(raw)
+        if (s.min is not None and v < s.min) or (s.max is not None and v > s.max):
+            raise OutOfRange(f"{v} is outside [{s.min}, {s.max}]")
+        return v
     if s.type == "bool":
         return raw == "true"
     if s.type == "choice":
@@ -273,14 +330,19 @@ def get(db: Session, key: str):
         return _coerce(s, raw)
     except (TypeError, ValueError) as exc:
         # The admin set this in the UI and it is quietly not in force: the app runs on the env
-        # default while the settings page goes on showing the value that was saved.
+        # default while the settings page goes on showing the value that was saved. An OutOfRange is
+        # the same situation arrived at from the other direction — the value was fine when it was
+        # written and the spec moved under it — so it gets the same treatment and its own code.
+        event = (
+            "sysconfig.override_out_of_range"
+            if isinstance(exc, OutOfRange)
+            else "sysconfig.override_uncoercible"
+        )
         if (s.key, raw) not in _coerce_warned:
             _coerce_warned.add((s.key, raw))
             log.warning(
-                "a stored setting could not be coerced; the default is used instead",
-                extra=logs.event(
-                    "sysconfig.override_uncoercible", key=s.key, reason=type(exc).__name__
-                ),
+                "a stored setting is not usable; the default is used instead",
+                extra=logs.event(event, key=s.key, reason=type(exc).__name__),
             )
         return _default(s)
 
@@ -304,11 +366,14 @@ def set_value(db: Session, key: str, value) -> None:
     (B-core-10). The staged value is visible to a same-session `get()` before the commit."""
     s = _BY_KEY[key]
     if s.type == "int":
-        v = int(value)
+        try:
+            v = int(value)
+        except (TypeError, ValueError):
+            raise InvalidSetting(key, "not_a_number") from None
         if s.min is not None and v < s.min:
-            raise ValueError(f"{key} must be >= {s.min}")
+            raise InvalidSetting(key, "too_low", min=s.min)
         if s.max is not None and v > s.max:
-            raise ValueError(f"{key} must be <= {s.max}")
+            raise InvalidSetting(key, "too_high", max=s.max)
         raw = str(v)
     elif s.type == "bool":
         raw = "true" if value else "false"
@@ -320,7 +385,7 @@ def set_value(db: Session, key: str, value) -> None:
     stored, encrypted = raw, False
     if s.secret:
         if not secrets_manageable():
-            raise RuntimeError("TOKEN_ENCRYPTION_KEY is not configured")
+            raise InvalidSetting(key, "no_encryption_key")
         stored, encrypted = security.encrypt(raw) or "", True
 
     row = db.get(SystemConfig, key)

backend/app/worker.py

@@ -43,7 +43,7 @@ from app.downloads.jobdb import (
     _staging_dir,
 )
 from app.downloads.status import STOPPED_BY_ROUTE, JobStatus
-from app.models import DownloadJob, MediaAsset
+from app.models import DISPLAY_TEXT_MAX, DownloadJob, MediaAsset
 
 log = logs.get_logger(__name__)
 _stop = threading.Event()
@@ -562,7 +562,7 @@ def _finish_from_cache(job_id: int, asset_id: int) -> None:
             fields = {"status": JobStatus.DONE, "progress": 100, "phase": None}
             if not job.display_name and asset.title:
                 # display_name is VARCHAR(255); a title can be longer (e.g. a recipe in the title).
-                fields["display_name"] = asset.title[:255]
+                fields["display_name"] = asset.title[:DISPLAY_TEXT_MAX]
             asset.last_access_at = datetime.now(timezone.utc)
             # Atomic finalize: only marks the job done while it is still running, so a concurrent
             # cancel/pause is never resurrected (see service.finalize_if_running).

backend/app/youtube/client.py

@@ -6,8 +6,10 @@ so they don't depend on a specific user's token; subscriptions.list?mine=true al
 uses OAuth.
 """
 
+import logging
 from collections.abc import Iterator
 from datetime import datetime, timedelta, timezone
+from typing import Literal
 
 import httpx
 
@@ -25,11 +27,15 @@ class YouTubeError(Exception):
 
     `reason` is the API's own error reason code (`quotaExceeded`, `subscriptionDuplicate`,
     `videoNotFound`, …) when the body carried one. Branch on THAT, never on the message: the
-    message is prose, it changes under us, and it is deliberately the poorer of the two here."""
+    message is prose, it changes under us, and it is deliberately the poorer of the two here.
 
-    def __init__(self, message: str, *, reason: str = ""):
+    `path` is the API endpoint that ANSWERED with the failure (`playlistItems`); empty when no
+    endpoint did — the request never got through (`transport`) or the token step refused first."""
+
+    def __init__(self, message: str, *, reason: str = "", path: str = ""):
         super().__init__(message)
         self.reason = reason
+        self.path = path
 
 
 def _error_reason(resp: httpx.Response) -> str:
@@ -50,7 +56,9 @@ def _error_reason(resp: httpx.Response) -> str:
     return reasons or "<none>"
 
 
-def _upstream_failure(method: str, path: str, resp: httpx.Response) -> YouTubeError:
+def _upstream_failure(
+    method: str, path: str, resp: httpx.Response, expected: frozenset[str] = frozenset()
+) -> YouTubeError:
     """Report one upstream failure and build the error to raise. Every YouTube response that is
     not a success goes through here — the Data API's reads, writes and deletes and the OAuth
     token refresh — so what may appear in a log line cannot drift apart between them, and the
@@ -59,7 +67,11 @@ def _upstream_failure(method: str, path: str, resp: httpx.Response) -> YouTubeEr
     response at all is `_send`'s, with the reason `transport`.) The body is logged only under
     the requesting user's own Teljes consent: it is the request quoted back."""
     reason = _error_reason(resp)
-    log.warning(
+    # A reason the caller named as an answer rather than a failure (`channelNotFound` on a `mine`
+    # read: the account simply has no channel) is still raised, but it is not a warning — it came
+    # back every six hours for an account that will never have one.
+    log.log(
+        logging.DEBUG if reason in expected else logging.WARNING,
         "YouTube %s %s -> %s (%s)",
         method,
         path,
@@ -80,7 +92,45 @@ def _upstream_failure(method: str, path: str, resp: httpx.Response) -> YouTubeEr
             # log-pii-ok: only under this user's own Teljes consent, which is what it is for
             extra=logs.event("youtube.api.body", body=resp.text[:500]),
         )
-    return YouTubeError(f"{method} {path} -> {resp.status_code}: {reason}", reason=reason)
+    return YouTubeError(
+        f"{method} {path} -> {resp.status_code}: {reason}", reason=reason, path=path
+    )
+
+
+# The `mine` reads' answer for a Google account that has no YouTube channel.
+_NO_CHANNEL = frozenset({"channelNotFound"})
+
+# The reasons that mean the project's quota is spent: every further call today gets the same answer.
+_QUOTA_REASONS = frozenset({"quotaExceeded", "dailyLimitExceeded"})
+
+
+def is_quota_refusal(exc: YouTubeError) -> bool:
+    """Whether the API refused for want of quota. `reason` can list several codes, comma-joined."""
+    return any(r in _QUOTA_REASONS for r in exc.reason.split(","))
+
+
+# The token endpoint's answer for a revoked or expired grant — the one refusal a reconnect fixes.
+_DEAD_GRANT = "invalid_grant"
+
+# What a refused YouTube action means to the person who asked for it — the three things they can
+# act on differently: wait for tomorrow's budget, reconnect the account, or try again later.
+YouTubeRefusal = Literal["quota", "reconnect", "unavailable"]
+
+
+def refusal_reason(exc: YouTubeError) -> YouTubeRefusal:
+    """Sort a failure by what the user can do about it. A dead grant (Google refused the refresh
+    with `invalid_grant`, which also drops the grant — see `_drop_dead_grant`) or no usable token at
+    all (raised before any endpoint answered, so with no path and no transport reason) means the
+    account must be reconnected; retrying cannot help. Any other token-endpoint failure — a 5xx, a
+    429, a misconfigured client — leaves the grant as it was: reconnecting would not fix it, and
+    the account would still read as connected, with no connect button to press."""
+    if is_quota_refusal(exc):
+        return "quota"
+    if exc.path == "oauth2/token":
+        return "reconnect" if exc.reason == _DEAD_GRANT else "unavailable"
+    if not exc.path and exc.reason != "transport":
+        return "reconnect"
+    return "unavailable"
 
 
 def _chunks(items: list, size: int) -> Iterator[list]:
@@ -156,7 +206,10 @@ class YouTubeClient:
             },
         )
         if resp.status_code != 200:
-            raise _upstream_failure("POST", "oauth2/token", resp)
+            exc = _upstream_failure("POST", "oauth2/token", resp)
+            if exc.reason == _DEAD_GRANT:
+                self._drop_dead_grant(tok)
+            raise exc
         data = resp.json()
         access = data["access_token"]
         tok.access_token = encrypt(access)
@@ -166,8 +219,34 @@ class YouTubeClient:
         log.info("Refreshed access token for user %s", self.user.id)
         return access
 
+    def _drop_dead_grant(self, tok) -> None:
+        """Google answered the refresh with `invalid_grant`: the grant was revoked or expired, and no
+        retry will revive it. Forget it, so the account reads as NOT connected — Settings and the
+        onboarding wizard then offer the connect button again (a fresh consent issues a new refresh
+        token). Kept as "granted", the UI showed a live connection with no way to renew it while
+        every call failed. Committed like the refresh above: the caller rolls back on the error."""
+        tok.scopes = None
+        tok.access_token = None
+        tok.refresh_token_enc = None
+        tok.expiry = None
+        self.db.add(tok)
+        self.db.commit()
+        # INFO: the refusal itself is already the warning (`youtube.api.error`, invalid_grant).
+        log.info(
+            "cleared the dead YouTube grant of user %s",
+            self.user.id,
+            extra=logs.event("youtube.grant.cleared"),
+        )
+
     # --- core request ---
-    def _get(self, path: str, params: dict, cost: int = 1, allow_key: bool = True) -> dict:
+    def _get(
+        self,
+        path: str,
+        params: dict,
+        cost: int = 1,
+        allow_key: bool = True,
+        expected: frozenset[str] = frozenset(),
+    ) -> dict:
         p = dict(params)
         headers = {}
         api_key = sysconfig.get_str(self.db, "youtube_api_key")
@@ -178,7 +257,7 @@ class YouTubeClient:
         resp = self._send("GET", f"{API_BASE}/{path}", params=p, headers=headers)
         quota.record_usage(cost)
         if resp.status_code != 200:
-            raise _upstream_failure("GET", path, resp)
+            raise _upstream_failure("GET", path, resp, expected)
         return resp.json()
 
     # --- endpoints ---
@@ -218,7 +297,14 @@ class YouTubeClient:
             params = {"part": "snippet,contentDetails", "mine": "true", "maxResults": 50}
             if page_token:
                 params["pageToken"] = page_token
-            data = self._get("playlists", params, cost=1, allow_key=False)
+            try:
+                data = self._get("playlists", params, cost=1, allow_key=False, expected=_NO_CHANNEL)
+            except YouTubeError as exc:
+                # A Google account without a YouTube channel has no playlists, and YouTube says
+                # so as a 404. That is an empty list, not a failed sync.
+                if exc.reason in _NO_CHANNEL:
+                    return
+                raise
             for item in data.get("items", []):
                 sn = item.get("snippet", {})
                 yield {

backend/pyrightconfig.json

@@ -0,0 +1,31 @@
+// The backend type-check lane (E27 S3) — the gate's ninth lane, and the first thing that has ever
+// type-checked the ~36k lines of `app/`. Read as JSONC: pyright accepts comments here.
+//
+// basedpyright, not mypy: measured on this tree with the dependencies actually installed, both land
+// ~190-200 errors with the same distribution, so the choice was made on the things that differ —
+// basedpyright is ~2x faster, needs no MYPYPATH to resolve our `app.*` imports, and has a FIRST-CLASS
+// baseline (`--writebaseline`), which is the whole ratchet. mypy would have needed a third-party tool
+// for that.
+//
+// It runs in the pytest test image, never on the host: `requirements.lock` cannot be installed on
+// Windows at all (uvloop refuses to build there), so a host run would type-check against absent
+// third-party packages and report nonsense. The version is pinned in requirements-dev.txt, which the
+// image installs — so the lane's version IS the pin, with no host-vs-pin check to drift.
+//
+// `pythonVersion` is not free-standing: `/.python-version` is the single source of truth and
+// `tests/test_python_engine_contract.py` fails this gate if this file, the two Dockerfiles, the CI
+// container or ruff's target-version disagree with it.
+//
+// `include` covers `alembic` for the same reason the ruff lane was widened to it: migrations run on
+// every container start, so one that raises there crash-loops prod, and "it is generated code" is
+// not an argument when the generated code is what boots the system. `tests/` is deliberately OUT —
+// a test's job is to fail loudly when it is wrong, which is the opposite of the silent runtime
+// failure this lane exists to catch, and annotating fixtures to a checker's satisfaction is churn
+// the ratchet exists to avoid.
+{
+  "include": ["app", "alembic"],
+  "extraPaths": ["."],
+  "typeCheckingMode": "basic",
+  "pythonVersion": "3.12",
+  "pythonPlatform": "Linux"
+}

backend/requirements-dev.txt

@@ -4,6 +4,10 @@
 # backend lint lane runs on the host (the gate fails when the host's ruff is not this one). httpx2:
 # Starlette 1.x's TestClient is built on it (`import httpx2 as httpx`) and only falls back to the
 # app's own httpx with a deprecation warning on every run.
+# basedpyright: the backend type-check lane (E27 S3). Pinned like everything else here — a type
+# checker whose version floats silently changes what "clean" means, and the ratchet baseline it
+# writes is keyed to the diagnostics THIS version produces.
+basedpyright==1.40.1
 pytest==8.4.2
 ruff==0.15.21
 httpx2==2.13.0

backend/requirements.lock

@@ -47,7 +47,6 @@ pydantic-settings==2.15.0
 pydantic==2.13.4
 pydantic_core==2.46.4
 python-dotenv==1.2.3
-python-multipart==0.0.32
 requests==2.34.2
 rich==15.0.0
 starlette==1.6.0

backend/requirements.txt

@@ -1,7 +1,4 @@
 fastapi>=0.115,<1.0
-# Multipart form parsing — required by Starlette/FastAPI to accept file uploads (UploadFile/Form).
-# The download center's local-file Upload (E7) is the only multipart endpoint in the app.
-python-multipart>=0.0.9,<1.0
 uvicorn[standard]>=0.30,<1.0
 sqlalchemy>=2.0,<2.1
 psycopg[binary]>=3.2,<4.0

backend/ruff.toml

@@ -7,6 +7,10 @@
 # the repo wrap at the same width, and it's the width `ruff format` enforces (gated via
 # `ruff format --check` alongside `ruff check`).
 line-length = 100
+# The interpreter this code actually runs on, so ruff judges syntax and upgrade hints against the
+# right one. Left unset it falls back to a default that has nothing to do with us. `/.python-version`
+# is the single source of truth; tests/test_python_engine_contract.py holds this to it.
+target-version = "py312"
 
 [lint]
 # Beyond the default set, the rules that hold a LOG LINE to what E22.5 makes of it:

backend/tests/conftest.py

@@ -15,13 +15,15 @@ tests that COMMIT (the whole point of this lane — transaction-ownership behavi
 
 import os
 import shutil
+from urllib.parse import quote
 
 import pytest
 from alembic import command
 from alembic.config import Config
 from fastapi import HTTPException, Request
 from fastapi.testclient import TestClient
-from sqlalchemy import create_engine, text
+from sqlalchemy import create_engine, event, text
+from starlette.requests import HTTPConnection
 
 import app.models  # noqa: F401 — register every model on Base.metadata
 import app.state as app_state
@@ -100,17 +102,67 @@ def pytest_configure(config):
         )
 
 
+def _request_dep(db, unfinished: list[str]):
+    """`get_db` for a test request: the test's own session, plus the check a shared session hides.
+
+    A route helper flushes and its HANDLER commits (CLAUDE.md). Production's `get_db` closes the
+    session after the request, which rolls back anything flushed but not committed — yet here every
+    request shares the test's session, so a follow-up GET or an assertion reads the flushed write
+    and the suite stays green over a handler that forgot to commit (deep review, debt burn). So a
+    request that ends normally with a write it did not commit — flushed, or still only staged — is
+    recorded, and the test fails on it at teardown. Only the ROOT transaction's end clears it: a
+    savepoint released inside the handler commits nothing. The test's own staged rows are flushed before the request starts — they are the
+    test's business, not the handler's. A request that raises is rolled back, as production's
+    `close()` rolls it back: without that, what a failing handler flushed but never committed stayed
+    readable to the rest of the test — the one state production cannot be in (E16: an issue created
+    on the tracker before a failed upload was kept only by an explicit commit, and nothing saw it
+    missing)."""
+
+    def dep(conn: HTTPConnection):
+        db.flush()
+        state = {"dirty": False}
+
+        def flushed(session, ctx):
+            state["dirty"] = True
+
+        def ended(session, transaction):
+            if transaction.parent is None:
+                state["dirty"] = False
+
+        hooks = (("after_flush", flushed), ("after_transaction_end", ended))
+        for name, fn in hooks:
+            event.listen(db, name, fn)
+        try:
+            yield db
+            staged = db.new or db.deleted or any(db.is_modified(o) for o in db.dirty)
+            if state["dirty"] or staged:
+                unfinished.append(f"{conn.scope.get('method', 'WS')} {conn.url.path}")
+        except Exception:
+            db.rollback()
+            raise
+        finally:
+            for name, fn in hooks:
+                event.remove(db, name, fn)
+
+    return dep
+
+
 @pytest.fixture
 def db(_schema):
     """A real session against the test Postgres, on a clean (empty) database. The code under test
-    may commit freely."""
+    may commit freely. `db.info["request"]` is the `get_db` override for a request against it — the
+    one every test client uses — and a handler that left a write uncommitted fails the test here."""
     _truncate_all()
     session = SessionLocal()
+    unfinished: list[str] = []
+    session.info["request"] = _request_dep(session, unfinished)
+    session.info["unfinished"] = unfinished  # the requests recorded so far (the check's own test)
     try:
         yield session
     finally:
         session.rollback()
         session.close()
+    assert unfinished == [], "a handler left a write uncommitted"
 
 
 @pytest.fixture
@@ -168,7 +220,7 @@ def client(db, override_dep, _configured):
     `current_user` override — so login, the wallet gate and epoch revoke are exercised end to end.
     Starlette's SessionMiddleware round-trips the signed cookie, so a login in one call authenticates
     the next on this same instance. No lifespan (the scheduler / HLS sweep stay off)."""
-    override_dep(get_db, lambda: db)
+    override_dep(get_db, db.info["request"])
     return TestClient(app)
 
 
@@ -187,7 +239,7 @@ def as_user(db, override_dep, _configured):
             raise HTTPException(status_code=401, detail="Not authenticated")
         return registry[uid]
 
-    override_dep(get_db, lambda: db)
+    override_dep(get_db, db.info["request"])
     override_dep(current_user, _resolver)
 
     def _as(user: User) -> TestClient:
@@ -197,6 +249,27 @@ def as_user(db, override_dep, _configured):
     return _as
 
 
+@pytest.fixture
+def upload_headers():
+    """Build the headers `POST /api/downloads/upload` takes since P1.
+
+    Shared, because two test modules drive that route and a second copy of this is exactly the drift
+    that lets the wire shape change in one place only. The body IS the file now; the names ride as
+    percent-encoded headers (`quote` mirrors the client's `encodeURIComponent`, since headers are
+    latin-1 and a Hungarian filename would not survive raw)."""
+
+    def _headers(filename: str, display_name: str | None = None) -> dict[str, str]:
+        headers = {
+            "content-type": "application/octet-stream",
+            "x-upload-filename": quote(filename),
+        }
+        if display_name is not None:
+            headers["x-upload-display-name"] = quote(display_name)
+        return headers
+
+    return _headers
+
+
 @pytest.fixture(autouse=True)
 def _reset_rate_limiters():
     """Every RateLimiter is a module-level singleton keyed by client IP, and TestClient always

backend/tests/test_abuse_limits.py

@@ -100,7 +100,7 @@ def test_the_single_playlist_repull_shares_the_pull_cooldown(db, as_user, make_u
     db.commit()
     monkeypatch.setattr(plroutes, "has_read_scope", lambda u: True)
     monkeypatch.setattr(plroutes, "repull_playlist", lambda d, u, p: {"ok": True})
-    monkeypatch.setattr(plroutes, "sync_user_playlists", lambda d, u: {"ok": True})
+    monkeypatch.setattr(plroutes, "pull_user_playlists", lambda d, u: {"ok": True})
 
     c = as_user(user)
     codes = [c.post(f"/api/playlists/{pl.id}/revert-youtube").status_code for _ in range(4)]

backend/tests/test_admin_invites.py

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