release: 0.70.0 (improvement/e4-frontend-platform)

Bump VERSION to 0.70.0 and add the user-facing release-notes entry for the E4
Frontend Platform epic: full bookmarkable/shareable address-bar URLs (retiring the
"Share view" button), touch-visible card action buttons with a shape (not
colour-only) watched marker, and the bookmark-page-closes-on-modal-close fix — over
a large internal front-end refactor (god-component splits, usePref, useUrlMirror,
FilterRail, Modal focus). No DB migration.

.gitea/workflows/check.yml

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

CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md — working agreement for AI agents on Siftlode
+
+This repository is **fully AI-authored** — every line was written by an AI agent, and it continues to
+be developed that way. This file is the rules of the road: read it before you touch anything. It is
+loaded into every agent session, so keep it **short and true**. A rule here that has gone stale is
+worse than no rule — if you change how the code works, change this file in the same commit.
+
+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.
+
+## The gate — never merge or ship red
+
+The local gate is **ruff + 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` and `pytest` (the DB-lane needs Postgres).
+- New DB-backed test? It must actually run, not silently skip — assume `SIFTLODE_TEST_REQUIRE_DB=1`.
+
+## Workflow
+
+- **Trunk model.** One long-lived branch, `main`. Branch off it (`feature/`, `bug/`, `improvement/`),
+  keep commits logical and Conventional-Commit-styled.
+- **No AI attribution in commits.** No `Co-Authored-By` trailer, no "generated by" lines. (This file
+  being AI-written is the intended, visible exception; commits are not.)
+- **Release is a deliberate, user-owned step** (`siftlode release` from the feature branch: merge to
+  `main` → publish → deploy → verify `/api/version`). Do not self-ship; bring work to a green,
+  committed state and stop for the user's go-ahead.
+- **Public repo.** Keep ops/topology/secrets out — those live in a separate private repo. Nothing here
+  should assume or leak them.
+
+## Architecture shape (don't fight it)
+
+`routes/*` (HTTP only: validation, auth-dependency, serialization) → domain packages `sync/`, `plex/`,
+`downloads/`, `youtube/` (shared by routes + scheduler + worker) → flat core (`auth`, `quota`,
+`sysconfig`, `state`, `audit`, `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`,
+`security`) → `models/db/config`. **Dependency direction is one-way: core never imports routes.**
+Frontend: `main.tsx` provider tree → `App.tsx` shell → `moduleRegistry` route-chunks → components; data
+via react-query (`qk` factory), per-account `localStorage`, and server prefs; API through `lib/api/*`
+slices over `core.req<T>`.
+
+**Not wanted** (reviewed and rejected as over-engineering for this size): microservices, event bus,
+CQRS, a repository/DI framework, a router library, a generic CRUD-router factory or base serializer.
+
+## 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 control | the chip/segmented primitives (`Select` only for >6 options) | a native `<select>` |
+| FE loading/empty/error | `QueryState` / `StateMessage` | ad-hoc conditionals |
+
+## House rules that bite (learned from real bugs)
+
+- **A rule stated in a comment must also be enforced in code.** The worst bugs here came from a comment
+  and the code/migration drifting apart (a `cancelled`≠`canceled` literal killed a cancel path). Put the
+  invariant in an enum/constant/shared function, not in prose.
+- **Fix a principle everywhere, in one sweep.** If you correct one owner/commit/serialization site,
+  `grep` for the siblings and fix them too — asymmetric fixes are a recurring smell here.
+- **Honest states.** An error must not render as an empty state; a swallowed failure must not look like
+  "no results". Reads degrade honestly; writes are conditional (`UPDATE … WHERE status='running'`).
+- **i18n parity.** HU/EN, zero key drift. Every user-facing string is translated.
+- **Comment the "why", keep it current.** This codebase uses comments as its architecture doc; a stale
+  "why" is a liability, so update it when the behavior changes.
+
+---
+
+*A fuller written-conventions doc (`docs/development.md`) is planned; once it lands, this file slims to a
+pointer plus the gate/workflow/no-attribution rules. Until then, the table above is the source of truth.*

Dockerfile

@@ -10,7 +10,7 @@ ARG GIT_SHA=unknown
 ARG BUILD_DATE=
 
 # Stage 1: build the frontend SPA
-FROM node:20-alpine AS frontend
+FROM node:22-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 ./
@@ -57,9 +57,12 @@ RUN apt-get update \
     && rm /tmp/deno.zip \
     && rm -rf /var/lib/apt/lists/*
 
-COPY backend/requirements.txt .
+# Install from the PINNED lock (requirements.lock, generated from requirements.txt) so the image is
+# byte-reproducible and the exact versions are the ones pip-audit scanned in CI — not whatever floats
+# up from the floor ranges on build day. Regenerate the lock when requirements.txt changes (see its header).
+COPY backend/requirements.lock .
 RUN --mount=type=cache,target=/root/.cache/pip \
-    pip install --upgrade pip && pip install -r requirements.txt
+    pip install --upgrade pip && pip install -r requirements.lock
 
 COPY --chown=appuser backend/ .
 # Read at runtime by config.py as the app_version (a committed single source of truth).

VERSION

@@ -1 +1 @@
-0.60.4
+0.70.0

backend/Dockerfile.test

@@ -8,5 +8,13 @@
 #   docker run --rm -v "<repo>/backend:/app" -w /app siftlode-test:local python -m pytest
 FROM python:3.12-slim
 WORKDIR /app
-COPY requirements.txt requirements-dev.txt ./
+# ffmpeg so the thumbnail/poster tests (needs_ffmpeg) actually run in the gate instead of skipping
-RUN pip install --no-cache-dir -r requirements.txt -r requirements-dev.txt
+# silently — the runtime image already ships ffmpeg, so the test image should too (see conftest's
+# SIFTLODE_TEST_REQUIRE_DB, which now also refuses to run if ffmpeg is missing).
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+# Install the SAME pinned lock as the prod image (+ the test-only tooling), so the tests run against
+# the exact dependency versions prod ships.
+COPY requirements.lock requirements-dev.txt ./
+RUN pip install --no-cache-dir -r requirements.lock -r requirements-dev.txt

backend/alembic/versions/0062_drop_redundant_idx.py

@@ -0,0 +1,53 @@
+"""drop 10 redundant single-column FK indexes (R12 S5)
+
+Each of these columns already leads a composite UNIQUE constraint, whose btree covers leftmost-prefix
+lookups on that column (and the ON DELETE CASCADE reverse lookups too) — so the extra single-column
+`index=True` was pure write-amplification. Dropping them costs nothing on reads and saves an index
+write per insert/update. Fast (index-only drop, no table rewrite). Reversible (downgrade recreates).
+
+Redundant index -> the composite that already covers it:
+  ix_subscriptions_user_id            <- uq_user_channel (user_id, channel_id)
+  ix_video_states_user_id             <- uq_user_video (user_id, video_id)
+  ix_search_finds_user_id             <- uq_user_search_video (user_id, video_id)
+  ix_explored_channels_user_id        <- uq_user_explored_channel (user_id, channel_id)
+  ix_blocked_channels_user_id         <- uq_user_blocked_channel (user_id, channel_id)
+  ix_saved_views_user_id              <- uq_user_saved_view (user_id, name)
+  ix_playlist_items_playlist_id       <- uq_playlist_video (playlist_id, video_id)
+  ix_download_shares_job_id           <- uq_download_share (job_id, to_user_id)
+  ix_plex_states_user_id              <- uq_plex_user_item (user_id, item_id)
+  ix_plex_playlist_items_playlist_id  <- uq_plex_playlist_item (playlist_id, item_id)
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "0062_drop_redundant_idx"
+down_revision: Union[str, None] = "0061_dl_job_error_code"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# (index_name, table_name, column)
+_REDUNDANT: list[tuple[str, str, str]] = [
+    ("ix_subscriptions_user_id", "subscriptions", "user_id"),
+    ("ix_video_states_user_id", "video_states", "user_id"),
+    ("ix_search_finds_user_id", "search_finds", "user_id"),
+    ("ix_explored_channels_user_id", "explored_channels", "user_id"),
+    ("ix_blocked_channels_user_id", "blocked_channels", "user_id"),
+    ("ix_saved_views_user_id", "saved_views", "user_id"),
+    ("ix_playlist_items_playlist_id", "playlist_items", "playlist_id"),
+    ("ix_download_shares_job_id", "download_shares", "job_id"),
+    ("ix_plex_states_user_id", "plex_states", "user_id"),
+    ("ix_plex_playlist_items_playlist_id", "plex_playlist_items", "playlist_id"),
+]
+
+
+def upgrade() -> None:
+    for idx, _table, _col in _REDUNDANT:
+        # IF EXISTS: a DB whose schema was stamped from a create_all (tests) won't have these once
+        # the models drop index=True, so a plain drop_index would error there.
+        op.execute(f"DROP INDEX IF EXISTS {idx}")
+
+
+def downgrade() -> None:
+    for idx, table, col in _REDUNDANT:
+        op.create_index(idx, table, [col])

backend/alembic/versions/0063_plex_library_overlay.py

@@ -0,0 +1,39 @@
+"""plex library HU-overlay columns (E5 S5a)
+
+Adds `metadata_lang` (default 'en') and a self-referential `overlay_of` to plex_libraries. An
+OVERLAY library is the Hungarian-metadata twin of another section: it is never browsed on its own —
+its titles' HU fields are written onto the matched EN rows (paired by `guid`, see 0064). Cheap:
+metadata-only, no table rewrite.
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0063_plex_library_overlay"
+down_revision: Union[str, None] = "0062_drop_redundant_idx"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "plex_libraries",
+        sa.Column("metadata_lang", sa.String(8), nullable=False, server_default="en"),
+    )
+    op.add_column(
+        "plex_libraries",
+        sa.Column(
+            "overlay_of",
+            sa.Integer(),
+            sa.ForeignKey("plex_libraries.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+    )
+    op.create_index("ix_plex_libraries_overlay_of", "plex_libraries", ["overlay_of"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_plex_libraries_overlay_of", table_name="plex_libraries")
+    op.drop_column("plex_libraries", "overlay_of")
+    op.drop_column("plex_libraries", "metadata_lang")

backend/alembic/versions/0064_plex_hu_overlay_cols.py

@@ -0,0 +1,58 @@
+"""plex HU-overlay item/show columns + guid (E5 S5a)
+
+On plex_items and plex_shows: `guid` (canonical external id, the EN<->HU pairing key), the Hungarian
+twin fields `title_hu`/`summary_hu`/`genres_hu`, and a STORED generated `search_vector_hu` mirroring
+the EN vector (title_hu A / people_text B / left(summary_hu,1000) C) + a GIN index. people_text is
+language-neutral, reused for both vectors.
+
+Run BEFORE the first HU overlay sync: while the *_hu columns are all NULL the generated-column build
+is trivial. ADD only (no drop/rebuild of the EN search_vector). NOTE: adding a STORED generated
+column + its GIN takes an ACCESS EXCLUSIVE lock and rewrites the table — brief, but flag it on prod.
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0064_plex_hu_overlay_cols"
+down_revision: Union[str, None] = "0063_plex_library_overlay"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_TABLES = ("plex_items", "plex_shows")
+
+# Mirror of the EN search_vector (models.py) but over the HU twin columns; people_text is shared.
+_VECTOR_HU = (
+    "setweight(to_tsvector('public.unaccent_simple', coalesce(title_hu, '')), 'A') || "
+    "setweight(to_tsvector('public.unaccent_simple', coalesce(people_text, '')), 'B') || "
+    "setweight(to_tsvector('public.unaccent_simple', left(coalesce(summary_hu, ''), 1000)), 'C')"
+)
+
+
+def upgrade() -> None:
+    for t in _TABLES:
+        op.add_column(t, sa.Column("guid", sa.String(64), nullable=True))
+        op.add_column(t, sa.Column("title_hu", sa.String(512), nullable=True))
+        op.add_column(t, sa.Column("summary_hu", sa.Text(), nullable=True))
+        op.add_column(t, sa.Column("genres_hu", postgresql.JSONB(), nullable=True))
+        op.create_index(f"ix_{t}_guid", t, ["guid"])
+        op.create_index(f"ix_{t}_genres_hu_gin", t, ["genres_hu"], postgresql_using="gin")
+        # Generated column can't be expressed via add_column — raw DDL, matching the EN idiom (0044).
+        op.execute(
+            f"ALTER TABLE {t} ADD COLUMN search_vector_hu tsvector "
+            f"GENERATED ALWAYS AS ({_VECTOR_HU}) STORED"
+        )
+        op.execute(f"CREATE INDEX ix_{t}_search_vector_hu ON {t} USING gin (search_vector_hu)")
+
+
+def downgrade() -> None:
+    for t in _TABLES:
+        op.execute(f"DROP INDEX IF EXISTS ix_{t}_search_vector_hu")
+        op.execute(f"ALTER TABLE {t} DROP COLUMN IF EXISTS search_vector_hu")
+        op.drop_index(f"ix_{t}_genres_hu_gin", table_name=t)
+        op.drop_index(f"ix_{t}_guid", table_name=t)
+        op.drop_column(t, "genres_hu")
+        op.drop_column(t, "summary_hu")
+        op.drop_column(t, "title_hu")
+        op.drop_column(t, "guid")

backend/alembic/versions/0065_plex_detail_fields.py

@@ -0,0 +1,45 @@
+"""plex rich-detail item/show columns (E5 S5b)
+
+On plex_items and plex_shows: the fields that were previously read LIVE from plex.metadata() on every
+info-page view — `imdb_rating` (the IMDb-specific score, distinct from `rating` = audienceRating),
+`imdb_id` (tt…), `tagline`, and `full_cast` (ordered [{name, role, thumb}]). Persisting them lets the
+detail endpoints serve from the DB row instead of a live Plex call (outage-resilient, and the
+precondition for S6's pure-DB language-aware serving).
+
+These are filled by the same rich backfill that already fills the full cast (`_enrich_people_batch`),
+so the data step below resets `people_enriched_at` to NULL on movie/show rows: the backfill re-fetches
+each once (60/run, self-throttled) and stamps the new columns. ADD-only, all nullable → no table
+rewrite, no generated column, no ACCESS EXCLUSIVE lock (unlike 0064).
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0065_plex_detail_fields"
+down_revision: Union[str, None] = "0064_plex_hu_overlay_cols"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_TABLES = ("plex_items", "plex_shows")
+
+
+def upgrade() -> None:
+    for t in _TABLES:
+        op.add_column(t, sa.Column("imdb_rating", sa.Float(), nullable=True))
+        op.add_column(t, sa.Column("imdb_id", sa.String(16), nullable=True))
+        op.add_column(t, sa.Column("tagline", sa.Text(), nullable=True))
+        op.add_column(t, sa.Column("full_cast", postgresql.JSONB(), nullable=True))
+    # Force a one-time re-enrich so already-enriched rows gain the new columns (episodes are never
+    # enriched, so their NULL people_enriched_at is unaffected; they keep serving detail live).
+    op.execute("UPDATE plex_items SET people_enriched_at = NULL WHERE kind = 'movie'")
+    op.execute("UPDATE plex_shows SET people_enriched_at = NULL")
+
+
+def downgrade() -> None:
+    for t in _TABLES:
+        op.drop_column(t, "full_cast")
+        op.drop_column(t, "tagline")
+        op.drop_column(t, "imdb_id")
+        op.drop_column(t, "imdb_rating")

backend/alembic/versions/0066_notif_created_at_notnull.py

@@ -0,0 +1,24 @@
+"""notifications.created_at NOT NULL (align schema to the model)
+
+The model has always declared `Notification.created_at: Mapped[datetime]` (NOT NULL) with
+`server_default=func.now()`, but migration 0017 created the column without `nullable=False`, so the live
+schema allowed NULL — a model/schema drift the new migration drift-test (E1 S2) surfaced. The
+server_default has filled every row since day one, so no NULLs exist; enforcing NOT NULL just makes the
+schema match the contract the model already promises. Pure DDL, reversible.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "0066_notif_created_at_notnull"
+down_revision: Union[str, None] = "0065_plex_detail_fields"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.alter_column("notifications", "created_at", nullable=False)
+
+
+def downgrade() -> None:
+    op.alter_column("notifications", "created_at", nullable=True)

backend/alembic/versions/0067_feed_sort_indexes.py

@@ -0,0 +1,55 @@
+"""feed sort indexes: published_at DESC NULLS LAST composite(s) for the default feed (PERF-1)
+
+The feed's default `newest` sort is `published_at DESC NULLS LAST, id ASC` (feedquery.order_by), but the
+only published_at index was a plain ASC btree (`ix_videos_published_at`). A btree read backwards satisfies
+`DESC NULLS FIRST`, not the `DESC NULLS LAST` the query asks for, so the planner could not use it for
+ordering — every feed page fell back to a full `videos` scan + top-N sort. Measured on a prod-sized reseed
+(257k videos): the default page went from ~44.8k shared buffers (dev planner) / ~169k (prod planner, the
+per-channel nested loop that is the likely "prod feed is slow" root cause) down to ~624 buffers with the
+matching index.
+
+This adds two indexes in the exact feed order:
+  - ix_videos_published_at_desc  (published_at DESC NULLS LAST, id ASC) — the global feed / Library sort.
+  - ix_videos_channel_pub_desc   (channel_id, published_at DESC NULLS LAST, id ASC) — the per-channel feed
+    (channel page, channel_ids filter). It leads with channel_id, so it is a strict superset of the old
+    single-column `ix_videos_channel_id` (FK cascade, sync upsert, autotag, channel-detail all still ride
+    it) — that redundant index is dropped.
+
+The plain ASC `ix_videos_published_at` stays: it already serves the `oldest` sort (ASC NULLS LAST = btree
+default) as an Index Scan.
+
+CONCURRENTLY (in alembic's autocommit_block, since it can't run inside a transaction) so a live prod builds
+these without blocking reads/writes; downtime ~0. IF (NOT) EXISTS keeps the drift test's
+downgrade->re-upgrade round-trip idempotent.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "0067_feed_sort_indexes"
+down_revision: Union[str, None] = "0066_notif_created_at_notnull"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.get_context().autocommit_block():
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_published_at_desc "
+            "ON videos (published_at DESC NULLS LAST, id ASC)"
+        )
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_channel_pub_desc "
+            "ON videos (channel_id, published_at DESC NULLS LAST, id ASC)"
+        )
+        # Redundant now — ix_videos_channel_pub_desc leads with channel_id (a strict superset).
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_channel_id")
+
+
+def downgrade() -> None:
+    with op.get_context().autocommit_block():
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_channel_id ON videos (channel_id)"
+        )
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_channel_pub_desc")
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_published_at_desc")

backend/alembic/versions/0068_published_at_not_null.py

@@ -0,0 +1,36 @@
+"""videos.published_at NOT NULL DEFAULT now() (PERF-15)
+
+Every video in practice carries a publish date (0 NULLs in the 257k-row prod-sized reseed), but the
+column was nullable, which forced the feed's keyset predicate into a non-sargable
+`... OR published_at IS NULL` disjunction — blocking the ix_videos_published_at_desc range so deep
+`newest` pages scanned from the top of the index and filtered (51.8k buffers). Making it NOT NULL lets
+the keyset drop that disjunction and take a `published_at <=` range bound (deep page -> ~0.5k buffers).
+
+server_default now() is the safety net for the rare date-less ingest path (the enrich overwrites it with
+the real date); the app-side ingest paths also fall back to now() so they never write an explicit NULL.
+
+Note: `SET NOT NULL` validates with a brief ACCESS EXCLUSIVE lock + one table scan (it cannot run
+CONCURRENTLY). On the prod row count (~235k) that is sub-second; still, it is a short write-blocking lock
+rather than the ~0 of 0067's CONCURRENTLY index build.
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0068_published_at_not_null"
+down_revision: Union[str, None] = "0067_feed_sort_indexes"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Backfill any stray NULLs first so SET NOT NULL can't fail (0 in prod, but be safe).
+    op.execute("UPDATE videos SET published_at = now() WHERE published_at IS NULL")
+    op.alter_column(
+        "videos", "published_at", nullable=False, server_default=sa.text("now()")
+    )
+
+
+def downgrade() -> None:
+    op.alter_column("videos", "published_at", nullable=True, server_default=None)

backend/alembic/versions/0069_job_index_hygiene.py

@@ -0,0 +1,93 @@
+"""scheduler-job partial indexes + boolean-index cleanup (PERF-17/18/3)
+
+Two scheduler jobs full-seq-scanned the 257k-row videos table every run:
+  - PERF-17: enrich_pending (`WHERE enriched_at IS NULL LIMIT N`, every few minutes) — 44.6k buffers /
+    run even when nothing is pending. A partial index over just the pending rows makes it a 1-buffer
+    (empty) index scan.
+  - PERF-18: maintenance revalidate (`WHERE unavailable_since IS NULL ORDER BY last_checked_at NULLS
+    FIRST LIMIT N`, ~300 pages/run) — 44.7k buffers/page; ix_videos_last_checked_at had idx_scan=0. A
+    partial index in that exact order serves it as an index scan (~36 buffers/page) and replaces the
+    unused plain one.
+
+PERF-3: the videos table also carried plain btrees on low-cardinality boolean columns the planner never
+picks (a `col IS false` majority predicate can't ride a btree). Drop the never-useful ones (is_short,
+via_explore) and slim the rest to partial indexes over the small/shrinking subset the job queries target
+(via_search=true, NOT shorts_probed, unavailable_since IS NOT NULL) — less write amplification on the
+biggest table, same lookups. live_status is left alone (a separate finding).
+
+All CONCURRENTLY (autocommit_block) — downtime ~0; IF (NOT) EXISTS keeps the drift test's
+downgrade->re-upgrade idempotent.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "0069_job_index_hygiene"
+down_revision: Union[str, None] = "0068_published_at_not_null"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.get_context().autocommit_block():
+        # PERF-17: enrich-pending partial (empty when nothing is pending -> 1-buffer scan).
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_enrich_pending "
+            "ON videos (id) WHERE enriched_at IS NULL"
+        )
+        # PERF-18: maintenance revalidate order, as a partial in the exact WHERE + ORDER BY shape.
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_recheck_order "
+            "ON videos (last_checked_at ASC NULLS FIRST) WHERE unavailable_since IS NULL"
+        )
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_last_checked_at")
+        # PERF-3: drop the never-picked boolean btrees; slim the rest to partials over the target subset.
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_is_short")
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_via_explore")
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_via_search")
+        # Predicate MUST match the query's `.is_(True)`/`.is_(False)` form (SQL `IS TRUE`/`IS FALSE`):
+        # Postgres's partial-index prover does NOT match a `col IS TRUE` clause to a bare `col` predicate,
+        # so `WHERE via_search` / `WHERE NOT shorts_probed` would leave the queries seq-scanning.
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_via_search "
+            "ON videos (id) WHERE via_search IS TRUE"
+        )
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_shorts_probed")
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_shorts_probed "
+            "ON videos (id) WHERE shorts_probed IS FALSE"
+        )
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_unavailable_since")
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_unavailable_since "
+            "ON videos (unavailable_since) WHERE unavailable_since IS NOT NULL"
+        )
+
+
+def downgrade() -> None:
+    with op.get_context().autocommit_block():
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_enrich_pending")
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_recheck_order")
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_last_checked_at "
+            "ON videos (last_checked_at)"
+        )
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_is_short ON videos (is_short)"
+        )
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_via_explore ON videos (via_explore)"
+        )
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_via_search")
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_via_search ON videos (via_search)"
+        )
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_shorts_probed")
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_shorts_probed ON videos (shorts_probed)"
+        )
+        op.execute("DROP INDEX CONCURRENTLY IF EXISTS ix_videos_unavailable_since")
+        op.execute(
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_videos_unavailable_since "
+            "ON videos (unavailable_since)"
+        )

backend/alembic/versions/0070_fold_maintenance_batch.py

@@ -0,0 +1,47 @@
+"""Fold the maintenance re-validation batch from app_state into sysconfig (B-core-11)
+
+The admin-tunable `maintenance_revalidate_batch` lived in its own `app_state` column with a
+hand-rolled override-or-default reader in `app.state`, duplicating the sysconfig SPECS pattern. It's
+now a sysconfig key (`system_config` store), so every admin knob lives in one place. This migration
+carries any existing override into the sysconfig store, then drops the dead column. Reversible.
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0070_fold_maintenance_batch"
+down_revision: Union[str, None] = "0069_job_index_hygiene"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Preserve a customized override: copy it into the sysconfig store before the column goes.
+    op.execute(
+        """
+        INSERT INTO system_config (key, value, encrypted)
+        SELECT 'maintenance_revalidate_batch', maintenance_revalidate_batch::text, false
+        FROM app_state
+        WHERE id = 1 AND maintenance_revalidate_batch IS NOT NULL
+        ON CONFLICT (key) DO NOTHING
+        """
+    )
+    op.drop_column("app_state", "maintenance_revalidate_batch")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "app_state",
+        sa.Column("maintenance_revalidate_batch", sa.Integer(), nullable=True),
+    )
+    # Carry the value back onto the row, then drop the sysconfig override (symmetric restore).
+    op.execute(
+        """
+        UPDATE app_state SET maintenance_revalidate_batch =
+            (SELECT value::int FROM system_config WHERE key = 'maintenance_revalidate_batch')
+        WHERE id = 1
+          AND EXISTS (SELECT 1 FROM system_config WHERE key = 'maintenance_revalidate_batch')
+        """
+    )
+    op.execute("DELETE FROM system_config WHERE key = 'maintenance_revalidate_batch'")

backend/app/README.md

@@ -0,0 +1,75 @@
+# Backend conventions
+
+The rules below are already followed across `backend/app` — they lived only in a few module
+docstrings (`demo.py`, `userscope.py`, `routes/_common.py`) until this file collected them (E3 S3,
+B-core-20). When you add code, match these so the next reader doesn't have to guess "which pattern do
+I copy".
+
+## Module layering
+
+Three layers, by *who* runs the code — not by feature:
+
+1. **`routes/…` — request-only.** A route module holds HTTP concerns: auth dependencies, request/
+   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
+   **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.
+
+3. **Flat `app/*.py` core modules — cross-cutting primitives.** `auth`, `sysconfig`, `quota`, `audit`,
+   `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`, … are single-file primitives many
+   layers import. They depend on nothing above them (a core module must never import a `routes/…`
+   module).
+
+**Extraction trigger: the SECOND consumer.** Keep new logic inline in its first caller. The moment a
+*second* caller needs it (a worker as well as a route; a scheduler as well as a route), extract it down
+a layer — into the relevant domain package, or a flat core module if it's cross-cutting. Don't
+pre-abstract for a single caller; don't leave shared logic duplicated once there are two.
+
+## Transaction ownership
+
+This follows CLAUDE.md's canonical rule verbatim — **"the handler/job-wrapper commits; helpers flush
+(only `quota` owns its session)"** — so read it that way, not as an exception to it. The commit belongs
+to the **operation owner**; anything called *inside* another transaction only stages its change
+(`db.add` / `flush`) and lets the owner commit, so the whole operation is one transaction.
+`audit.record()` is the reference: it adds the audit row and the caller commits it together with the
+mutation it records, so an audit entry can never exist without its change (or vice-versa).
+
+- The **operation owner** is usually the route handler. A `service.*` operation the handler delegates a
+  whole transition to (e.g. `service.cancel`) *is* that owner and commits its one transition — it isn't
+  a mid-operation helper. A helper that owns its OWN short-lived session (the worker's `jobdb` writes,
+  the same carve-out CLAUDE.md grants `quota`) commits that session. Everything else flushes.
+- `SessionLocal` is `expire_on_commit=False`: after a raw `UPDATE` + commit, an ORM object you already
+  loaded is **stale**. Read the fresh value from the row (RETURNING, or a re-`SELECT`), not the ORM
+  attribute — see `service.decr_ref_count`.
+
+## Shared counters and status: do it atomically at the DB
+
+- **Never read-modify-write a shared counter in Python** (`x.count = x.count + 1`). Concurrent sessions
+  lose an update. Use a DB-atomic statement — `col = col + 1`, or `greatest(col - 1, 0)` with
+  `RETURNING` so the caller branches on the post-value under the row lock (`service.incr_ref_count` /
+  `decr_ref_count`).
+- **Download job status is a `JobStatus` StrEnum** (`downloads/status.py`), not bare strings. The
+  `HOLDING` set defines which states hold a `MediaAsset` (so release accounting stays correct);
+  `STOPPED_BY_ROUTE` is the route-initiated stop set. A worker child's terminal write goes through
+  `service.finalize_if_running` (an atomic `UPDATE … WHERE status='running'`) so a finishing child can't
+  resurrect a job a route just stopped.
+
+## Config: one home per kind
+
+- **`app.config.settings`** — boot/env config (DB URL, download root, worker concurrency): read once at
+  startup, not user-tunable at runtime.
+- **`sysconfig.SPECS`** — the runtime admin knobs (DB-override-or-default). A new admin-tunable value
+  goes in `SPECS`; don't invent a fourth store. (`state.py`'s `maintenance_batch` predates this and is
+  slated to fold into `sysconfig` — do not add more like it.)
+
+## The gate
+
+Everything below must be green before a change is done (run via `siftlode check`):
+`ruff` (backend) · `tsc` ×3 + `eslint` + `prettier` + `knip` (frontend) · `vitest` · `pytest`. The
+pytest lane runs in `backend/docker-compose.test.yml` — an ephemeral Postgres + the backend tree
+bind-mounted — so the DB-backed integration tests (the `db` fixture) actually run; `SIFTLODE_TEST_
+REQUIRE_DB=1` there turns a would-be silent skip into a hard failure. See `docs/development.md`.

backend/app/config.py

@@ -57,7 +57,7 @@ class Settings(BaseSettings):
     # VPS Caddy front door. A request from any other peer (someone hitting the app port directly)
     # is NOT trusted and its raw socket IP is used, so it can't spoof its rate-limit identity via
     # XFF. Empty = trust no proxy (use the direct peer) — correct for a directly-exposed / local-dev
-    # deploy. Comma-separated. See auth._client_ip + the deploy docs.
+    # deploy. Comma-separated. See routes.auth._client_ip + the deploy docs.
     trusted_proxy_ips: str = ""
 
     # --- Outbound email (onboarding: access-request + approval notices) ---
@@ -173,6 +173,18 @@ class Settings(BaseSettings):
     download_worker_concurrency: int = 2
     # How often (empty pending queue) the worker polls for a new job, in seconds.
     download_poll_seconds: int = 5
+    # --- download-subprocess watchdog (each download/edit runs in a supervised child process so a
+    # wedged yt-dlp/ffmpeg can be hard-killed; a thread cannot) ---
+    # Kill a running download if its job row hasn't advanced (no progress written) for this long.
+    # Generous: a live download writes progress ~1/s, so only a genuine 0-progress stall trips it.
+    download_stall_timeout_seconds: int = 150
+    # Absolute ceiling on a single download/edit regardless of progress (a legitimately huge file
+    # still finishes well under this; a runaway is capped).
+    download_wall_clock_max_seconds: int = 7200  # 2 hours
+    # How often the supervisor checks the child's liveness + the job row.
+    download_supervisor_poll_seconds: int = 3
+    # Grace between SIGTERM and SIGKILL when stopping a child (matches run_ffmpeg's escalation).
+    download_kill_grace_seconds: int = 5
     # Total cache size cap across ALL users (bytes). When >0 and exceeded, the GC evicts the
     # least-recently-accessed ready assets until under it. 0 = unlimited (disk is the limit).
     download_total_max_bytes: int = 0
@@ -209,6 +221,10 @@ class Settings(BaseSettings):
     plex_path_map: str = ""
     # Which Plex library section keys are exposed (comma-separated). Empty = all enabled sections.
     plex_libraries: str = ""
+    # HU-overlay mapping (E5 S5): comma-separated `huSectionKey:enSectionKey` pairs. Each named HU
+    # section is synced as a non-browsable overlay whose Hungarian metadata is written onto the EN
+    # twin section's rows (matched by guid). Empty = no overlays. E.g. "3:4,5:1".
+    plex_overlay_map: str = ""
     # Stable client identifier Siftlode presents to Plex (X-Plex-Client-Identifier).
     plex_client_id: str = "siftlode-server"
     # How often the catalog sync job mirrors Plex metadata, in minutes.

backend/app/db.py

@@ -12,7 +12,7 @@ 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.py), 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.
 engine = create_engine(
     settings.database_url,
     pool_pre_ping=True,

backend/app/demo.py

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

backend/app/downloads/adapters.py

@@ -0,0 +1,151 @@
+"""Per-source adapters — a thin Strategy over yt-dlp, keyed by the media source (youtube / facebook
+/ reddit / generic).
+
+yt-dlp stays the download engine; an adapter only contributes source-specific POLICY around it. The
+base class IS the generic behaviour (yt-dlp does everything, the ref is already a URL), and a
+subclass overrides ONLY what its source genuinely needs. This replaces knowledge that used to be
+scattered across worker.py / backfill.py / service.py with no shared source identity.
+
+Adapters are stateless singletons; get one with `resolve_adapter(source_kind, source_ref, info)`.
+Resolution works both before extraction (from source_kind / URL host) and after (from the yt-dlp
+`extractor_key` in the info dict), so a non-YouTube "url" job still lands on the right adapter.
+"""
+from urllib.parse import urlparse
+
+from app.config import settings
+
+
+class SourceAdapter:
+    """Generic source: yt-dlp handles everything and the ref is already a fetchable URL."""
+
+    key = "generic"
+
+    # --- extraction (worker._extract_with_fallback / backfill) ---------------------------------
+    def client_sets(self) -> list:
+        """Player-client sets to attempt, in order. A generic source needs no client override, so a
+        single default attempt (`[None]`) — the per-client fallback is a YouTube-only concept."""
+        return [None]
+
+    def ydl_opts_extra(self, clients) -> dict:
+        """yt-dlp options this source contributes (merged into `build_ydl_opts`). `clients` is the
+        current entry from `client_sets()`. Generic: nothing."""
+        return {}
+
+    def retriable(self, error_text: str) -> bool:
+        """Retry the extraction with the NEXT client set on this error? Generic: no (single attempt)."""
+        return False
+
+    # --- metadata -----------------------------------------------------------------------------
+    def uploader_url(self, info: dict) -> str | None:
+        """The channel/uploader page URL. Generic: whatever yt-dlp exposes directly (YouTube gives
+        `channel_url`), else None (reddit / a raw media URL have no derivable channel page)."""
+        return info.get("channel_url") or info.get("uploader_url")
+
+    def wants_metadata_backfill(self) -> bool:
+        """Whether the one-off metadata backfill should re-fetch this source. Generic: no."""
+        return False
+
+    # --- source ref ↔ URL ---------------------------------------------------------------------
+    def source_url(self, source_ref: str) -> str:
+        """A fetchable URL for `source_ref`. Generic: the ref is already a URL."""
+        return source_ref
+
+    def nfo_uniqueid_type(self) -> str:
+        """The `<uniqueid type=...>` written into the Kodi/Plex `.nfo` sidecar."""
+        return self.key
+
+
+class YouTubeAdapter(SourceAdapter):
+    key = "youtube"
+    # Errors worth retrying with a different player-client set (YouTube per-client flakiness).
+    _RETRIABLE = (
+        "not a bot",
+        "DRM protected",
+        "Requested format is not available",
+        "Only images are available",
+        "Sign in to confirm",
+    )
+
+    def client_sets(self) -> list:
+        return [
+            c for c in (settings.player_client_list, settings.player_client_fallback_list) if c
+        ] or [None]
+
+    def ydl_opts_extra(self, clients) -> dict:
+        # == --extractor-args "youtube:player_client=…;youtubepot-bgutilhttp:base_url=…" (list values).
+        ea: dict = {}
+        if clients:
+            ea["youtube"] = {"player_client": clients}
+        if settings.download_pot_base_url:
+            ea["youtubepot-bgutilhttp"] = {"base_url": [settings.download_pot_base_url]}
+        return {"extractor_args": ea} if ea else {}
+
+    def retriable(self, error_text: str) -> bool:
+        return any(m in error_text for m in self._RETRIABLE)
+
+    def wants_metadata_backfill(self) -> bool:
+        return True
+
+    def source_url(self, source_ref: str) -> str:
+        return f"https://www.youtube.com/watch?v={source_ref}"
+
+
+class FacebookAdapter(SourceAdapter):
+    key = "facebook"
+
+    def uploader_url(self, info: dict) -> str | None:
+        # Facebook gives neither channel_url nor uploader_url, but exposes a numeric `uploader_id`
+        # (the page id) that resolves at facebook.com/<id>.
+        base = super().uploader_url(info)
+        if base:
+            return base
+        uid = info.get("uploader_id")
+        return f"https://www.facebook.com/{uid}" if uid else None
+
+    def wants_metadata_backfill(self) -> bool:
+        return True
+
+
+class RedditAdapter(SourceAdapter):
+    key = "reddit"
+
+
+_YOUTUBE = YouTubeAdapter()
+_FACEBOOK = FacebookAdapter()
+_REDDIT = RedditAdapter()
+_GENERIC = SourceAdapter()
+
+
+def _host_is(host: str, *domains: str) -> bool:
+    """True if `host` is exactly one of `domains` or a subdomain of it — a netloc-scoped match, NOT a
+    loose substring, so a look-alike host ('myyoutube.com', 'youtube.com.evil') never matches."""
+    return any(host == d or host.endswith("." + d) for d in domains)
+
+
+def resolve_adapter(
+    source_kind: str | None, source_ref: str | None = None, info: dict | None = None
+) -> SourceAdapter:
+    """Pick the adapter for a job. Matches on `source_kind`, the yt-dlp `extractor_key` from `info`
+    (post-extraction, authoritative), and the netloc of any URL we hold — the `source_ref`
+    (pre-extraction) and yt-dlp's `webpage_url` (post-extraction). Host matching is netloc-scoped, and
+    the webpage_url is used by HOST only (never a substring over its path, which could carry a sibling
+    source's name). Falls back to the generic adapter — behaviour unchanged for any un-dedicated source."""
+    extractor = (info.get("extractor_key") or info.get("extractor") or "").lower() if info else ""
+    hosts = []
+    if source_ref:
+        hosts.append(urlparse(source_ref).netloc.lower())
+    if info and info.get("webpage_url"):
+        hosts.append(urlparse(info["webpage_url"]).netloc.lower())
+
+    def host_is(*domains: str) -> bool:
+        return any(_host_is(h, *domains) for h in hosts)
+
+    if source_kind == "youtube" or "youtube" in extractor or host_is(
+        "youtube.com", "youtu.be", "youtube-nocookie.com"
+    ):
+        return _YOUTUBE
+    if "facebook" in extractor or host_is("facebook.com", "fb.watch"):
+        return _FACEBOOK
+    if "reddit" in extractor or host_is("reddit.com"):
+        return _REDDIT
+    return _GENERIC

backend/app/downloads/backfill.py

@@ -11,40 +11,26 @@ Run once per environment:
     docker exec siftlode-worker-1 python -c "from app.downloads import backfill; print(backfill.run())"
 """
 import logging
-from urllib.parse import urlparse
 
 import yt_dlp
 from sqlalchemy import select
 
 from app.config import settings
 from app.db import SessionLocal
+from app.downloads import adapters
 from app.downloads import edit as editmod
 from app.downloads import formats, service
 from app.models import MediaAsset
-from app.worker import _uploader_url
 
 log = logging.getLogger("siftlode.backfill")
 
 
-def _should_refetch(asset: MediaAsset) -> bool:
+def _extract_meta(url: str, adapter: adapters.SourceAdapter) -> dict | None:
-    """Only YouTube + Facebook sources have a derivable channel URL worth a network round-trip."""
+    """Metadata-only yt-dlp extraction, using the source adapter's client sets + options (YouTube
-    if asset.source_kind == "youtube":
+    needs the POT/player-client strategy even just to extract)."""
-        return True
+    for clients in adapter.client_sets():
-    if asset.source_kind == "url":
-        host = urlparse(asset.source_ref).netloc.lower()
-        return "facebook.com" in host or "fb.watch" in host
-    return False
-
-
-def _extract_meta(url: str) -> dict | None:
-    """Metadata-only yt-dlp extraction, trying the same client sets as the worker (YouTube needs the
-    POT/player-client strategy even just to extract)."""
-    client_sets = [
-        c for c in (settings.player_client_list, settings.player_client_fallback_list) if c
-    ] or [None]
-    for clients in client_sets:
         opts = formats.build_ydl_opts(
-            {}, "%(id)s.%(ext)s", lambda d: None, settings.download_pot_base_url, clients
+            {}, "%(id)s.%(ext)s", lambda d: None, extra=adapter.ydl_opts_extra(clients)
         )
         opts["skip_download"] = True
         try:
@@ -70,10 +56,11 @@ def run() -> dict:
             .all()
         )
         for a in assets:
-            if a.uploader_url is None and _should_refetch(a):
+            adapter = adapters.resolve_adapter(a.source_kind, a.source_ref)
+            if a.uploader_url is None and adapter.wants_metadata_backfill():
                 url = a.source_webpage_url or service.source_url(a.source_kind, a.source_ref)
-                info = _extract_meta(url)
+                info = _extract_meta(url, adapter)
-                uu = _uploader_url(info) if info else None
+                uu = adapter.uploader_url(info) if info else None
                 if uu:
                     a.uploader_url = uu
                     filled_url += 1

backend/app/downloads/edit.py

@@ -25,6 +25,7 @@ import json
 import logging
 import math
 import queue
+import shutil
 import subprocess
 import threading
 import time
@@ -287,20 +288,30 @@ def _drain_tail(stream, sink: list[str]) -> None:
         pass
 
 
-def _stop(proc: subprocess.Popen) -> None:
+def escalate_kill(proc: subprocess.Popen, terminate, kill, grace_s: float, label: str) -> None:
-    """Terminate, then kill — never wait unbounded on a process we've given up on. Safe to call on
+    """terminate → wait(grace) → kill → wait(grace) escalation for a process we've given up on, so it
-    a process that already exited (the single exit path below may reach it after a clean wait)."""
+    is never waited on unboundedly. `terminate`/`kill` deliver the stop to whatever scope the caller
+    owns — a single process (`proc.terminate`/`proc.kill`) or its whole group (`os.killpg`). No-op if
+    the process already exited."""
     if proc.poll() is not None:
         return
-    proc.terminate()
+    terminate()
     try:
-        proc.wait(timeout=5)
+        proc.wait(timeout=grace_s)
+        return
     except subprocess.TimeoutExpired:
-        proc.kill()
+        pass
-        try:
+    kill()
-            proc.wait(timeout=5)
+    try:
-        except subprocess.TimeoutExpired:
+        proc.wait(timeout=grace_s)
-            log.error("ffmpeg pid %s survived SIGKILL", proc.pid)
+    except subprocess.TimeoutExpired:
+        log.error("%s pid %s survived SIGKILL", label, proc.pid)
+
+
+def _stop(proc: subprocess.Popen) -> None:
+    """Terminate, then kill — never wait unbounded on a process we've given up on. Safe to call on
+    a process that already exited."""
+    escalate_kill(proc, proc.terminate, proc.kill, grace_s=5, label="ffmpeg")
 
 
 def run_ffmpeg(cmd, total_s, on_progress, should_cancel, stall_timeout_s=_FFMPEG_STALL_TIMEOUT_S) -> None:
@@ -489,6 +500,61 @@ def build_poster_cmd(src: Path, dest: Path, at_s: float) -> list[str]:
     ]
 
 
+def build_thumbnail_jpg_cmd(src: Path, dest: Path) -> list[str]:
+    """Decode a downloaded thumbnail (webp/png/…) to a single baseline JPEG frame."""
+    return [
+        "ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-nostdin",
+        "-i", str(src), "-frames:v", "1", "-update", "1", str(dest),
+    ]
+
+
+def _run_ffmpeg_best_effort(cmd: list[str], timeout_s: int) -> Exception | None:
+    """Run a one-shot ffmpeg command, bounded by `timeout_s`. Returns None on success, or the
+    exception on a timeout/non-zero-exit/OS error — never raises. Shared by the best-effort image
+    steps (poster / thumbnail / storyboard) so the run+timeout+swallow policy lives in ONE place;
+    each caller logs its own context from the returned exception. (The download/transcode path uses
+    the richer `run_ffmpeg` instead, which streams progress and honours cooperative cancel.)"""
+    try:
+        subprocess.run(cmd, capture_output=True, timeout=timeout_s, check=True)
+        return None
+    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError) as exc:
+        return exc
+
+
+def _is_jpeg(path: Path) -> bool:
+    """True if the file starts with the JPEG SOI marker (FF D8 FF)."""
+    try:
+        with path.open("rb") as f:
+            return f.read(3) == b"\xff\xd8\xff"
+    except OSError:
+        return False
+
+
+def thumbnail_to_jpg(src: Path | None, dest: Path, timeout_s: int = 30) -> Path | None:
+    """Turn a downloaded thumbnail (webp / png / jpeg — whatever the source shipped) into a real
+    baseline JPEG for the `<name>.jpg` poster + og:image share sidecar.
+
+    Deliberately NOT yt-dlp's `FFmpegThumbnailsConvertor` (whose `-bsf:v mjpeg2jpeg` path crashes on
+    some already-JPEG thumbnails, e.g. Reddit's, and used to fail the entire download). A thumbnail
+    that is already JPEG is copied as-is; anything else is decoded via ffmpeg. Best-effort: returns
+    None on any failure, so the caller falls back to a cut video frame (`ensure_poster`) and the
+    download still succeeds."""
+    if src is None or not src.exists():
+        return None
+    if _is_jpeg(src):  # already JPEG (e.g. Facebook) — no decode/re-encode needed
+        try:
+            shutil.copyfile(src, dest)
+            return dest
+        except OSError as exc:
+            log.info("thumbnail copy failed (%s); poster falls back to a cut frame", str(exc)[:120])
+            return None
+    err = _run_ffmpeg_best_effort(build_thumbnail_jpg_cmd(src, dest), timeout_s)
+    if err is not None:
+        log.info("thumbnail->jpg conversion failed (%s); poster falls back to a cut frame", str(err)[:120])
+        return None
+    return dest if dest.exists() else None
+
+
 def ensure_poster(asset, download_root: str, timeout_s: int = 30) -> str | None:
     """Generate a poster frame for a ready asset that has no thumbnail (e.g. a direct media URL
     like a reddit HLS manifest, which yt-dlp can't get a thumbnail for). Written as the media's
@@ -506,10 +572,9 @@ def ensure_poster(asset, download_root: str, timeout_s: int = 30) -> str | None:
     if dest.exists():
         return rel
     at = min(3.0, (asset.duration_s or 10) * 0.1)
-    try:
+    err = _run_ffmpeg_best_effort(build_poster_cmd(src, dest, at), timeout_s)
-        subprocess.run(build_poster_cmd(src, dest, at), capture_output=True, timeout=timeout_s, check=True)
+    if err is not None:
-    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError) as exc:
+        log.info("poster gen skipped for asset %s: %s", asset.id, str(err)[:120])
-        log.info("poster gen skipped for asset %s: %s", asset.id, str(exc)[:120])
         return None
     return rel if dest.exists() else None
 
@@ -538,10 +603,9 @@ def ensure_storyboard(asset, download_root: str, timeout_s: int = 90) -> dict |
         return None
     dest.parent.mkdir(parents=True, exist_ok=True)
     cmd = build_storyboard_cmd(src, dest, asset.duration_s, geom)
-    try:
+    err = _run_ffmpeg_best_effort(cmd, timeout_s)
-        subprocess.run(cmd, capture_output=True, timeout=timeout_s, check=True)
+    if err is not None:
-    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError) as exc:
+        log.info("storyboard gen skipped for asset %s: %s", asset.id, str(err)[:120])
-        log.info("storyboard gen skipped for asset %s: %s", asset.id, str(exc)[:120])
         return None
     if not dest.exists():
         return None

backend/app/downloads/errors.py

@@ -21,6 +21,9 @@ _RULES: tuple[tuple[str, str], ...] = (
     ("available to this channel's members", "login_required"),
     ("join this channel", "login_required"),
     ("this video is only available to", "login_required"),
+    # Some extractors (e.g. Reddit) gate content behind a logged-in account: "Account
+    # authentication is required." — an auth wall we deliberately don't cross, not a transient error.
+    ("authentication is required", "login_required"),
     # Geo-restricted.
     ("in your country", "geo_blocked"),
     ("available in your location", "geo_blocked"),

backend/app/downloads/formats.py

@@ -96,13 +96,13 @@ def build_ydl_opts(
     spec: dict,
     outtmpl: str,
     progress_hook,
-    pot_base_url: str | None = None,
+    extra: dict | None = None,
-    player_clients: list[str] | None = None,
 ) -> dict:
     """Assemble yt-dlp options for a single download to `outtmpl` (a full path template).
 
-    `pot_base_url` points the bgutil PO-token provider plugin at the sidecar server;
+    `extra` is source-specific options contributed by the SourceAdapter (e.g. YouTube's
-    `player_clients` picks which YouTube clients to use (POT-capable ones like web use the token)."""
+    `extractor_args` with the player-client set + bgutil PO-token base_url); it is merged onto the
+    generic options below. Everything here is source-agnostic."""
     s = normalize(spec)
     h = s["max_height"]
     opts: dict = {
@@ -127,16 +127,9 @@ def build_ydl_opts(
         "socket_timeout": 30,
     }
 
-    # Extractor args: which YouTube clients to use + where the bgutil PO-token sidecar lives
+    # Source-specific options from the adapter (e.g. YouTube's extractor_args: player_client + POT).
-    # (== --extractor-args "youtube:player_client=…;youtubepot-bgutilhttp:base_url=…"). Values
+    if extra:
-    # are lists in the Python API.
+        opts.update(extra)
-    ea: dict = {}
-    if player_clients:
-        ea["youtube"] = {"player_client": player_clients}
-    if pot_base_url:
-        ea["youtubepot-bgutilhttp"] = {"base_url": [pot_base_url]}
-    if ea:
-        opts["extractor_args"] = ea
 
     if s["mode"] == "a":
         opts["format"] = "bestaudio/best"
@@ -211,9 +204,16 @@ def build_ydl_opts(
         opts["postprocessors"].append(
             {"key": "FFmpegMetadata", "add_chapters": True, "add_metadata": True}
         )
-    # Normalize the written thumbnail to jpg so we always have a `<name>.jpg` poster sidecar.
+    # NOTE: we deliberately do NOT add yt-dlp's `FFmpegThumbnailsConvertor` here. Its jpg conversion
-    # `already_have_thumbnail` keeps that file on disk after embedding (default deletes it).
+    # runs `ffmpeg -bsf:v mjpeg2jpeg` when the written thumbnail is already JPEG bytes (Reddit serves
-    opts["postprocessors"].append({"key": "FFmpegThumbnailsConvertor", "format": "jpg"})
+    # a JPEG under a `.png` name), and that bitstream filter *fails* on some such images — and since a
+    # postprocessor error is fatal, it used to kill the WHOLE download even though the media was fine.
+    # The `<name>.jpg` poster sidecar is instead produced robustly by our own pipeline (worker
+    # `_download` → `editmod.thumbnail_to_jpg`, with `ensure_poster` cutting a video frame as a
+    # fallback), so the og:image share preview (Facebook Messenger / MS Teams) keeps working.
+    # The opt-in EmbedThumbnail below is unaffected: it does its OWN format handling — it embeds a
+    # jpg/png thumbnail directly and converts anything else to PNG (not the crashing mjpeg2jpeg-to-jpg
+    # path), so it never needed the convertor and does not reintroduce the crash.
     if s["embed_thumbnail"]:
         opts["postprocessors"].append(
             {"key": "EmbedThumbnail", "already_have_thumbnail": True}

backend/app/downloads/jobdb.py

@@ -0,0 +1,73 @@
+"""Short-lived-session DB helpers + staging paths shared by the worker parent and the child pipeline."""
+from pathlib import Path
+
+from sqlalchemy import text
+
+from app.config import settings
+from app.db import SessionLocal
+from app.models import DownloadJob, MediaAsset
+
+
+# --- small DB helpers (short-lived sessions; the download itself holds no transaction) -------
+
+def _set_job(job_id: int, **fields) -> None:
+    with SessionLocal() as db:
+        job = db.get(DownloadJob, job_id)
+        if job is None:
+            return
+        for k, v in fields.items():
+            setattr(job, k, v)
+        db.commit()
+
+
+def _job_status(job_id: int) -> str | None:
+    with SessionLocal() as db:
+        return db.execute(
+            text("SELECT status FROM download_jobs WHERE id = :id"), {"id": job_id}
+        ).scalar()
+
+
+def _touch_job(job_id: int) -> None:
+    """Bump a running job's `updated_at` without changing any value — a stall-watchdog heartbeat for
+    phases that legitimately write no progress. Extraction writes nothing, and a multi-client-set
+    fallback re-writes identical values (progress 0 / phase 'downloading'), so ORM `onupdate` would
+    NOT fire and two slow extraction attempts could otherwise cross the stall timeout and be killed
+    mid-extraction though they'd have succeeded."""
+    with SessionLocal() as db:
+        db.execute(
+            text("UPDATE download_jobs SET updated_at=now() WHERE id=:id AND status='running'"),
+            {"id": job_id},
+        )
+        db.commit()
+
+
+def _requeue_if_running(job_id: int, phase: str) -> None:
+    """Put the job back to 'queued' for a later retry, but ONLY while it is still 'running'. The
+    route flips status to paused/cancelled to stop a job; a blind `status='queued'` here would
+    clobber that and silently revive a job the user just cancelled. The conditional WHERE makes the
+    requeue a no-op unless we still own a running job."""
+    with SessionLocal() as db:
+        db.execute(
+            text(
+                "UPDATE download_jobs SET status='queued', phase=:phase, updated_at=now() "
+                "WHERE id=:id AND status='running'"
+            ),
+            {"id": job_id, "phase": phase},
+        )
+        db.commit()
+
+
+def _reset_asset_pending(asset_id: int) -> None:
+    with SessionLocal() as db:
+        asset = db.get(MediaAsset, asset_id)
+        if asset and asset.status == "downloading":
+            asset.status = "pending"
+            db.commit()
+
+
+def _staging_dir(asset_id: int) -> Path:
+    return Path(settings.download_root) / ".staging" / f"asset-{asset_id}"
+
+
+def _edit_staging_dir(asset_id: int) -> Path:
+    return Path(settings.download_root) / ".staging" / f"edit-{asset_id}"

backend/app/downloads/pipeline.py

@@ -0,0 +1,601 @@
+"""Child-side download/edit pipeline — the yt-dlp download + ffmpeg edit that runs in the spawned subprocess."""
+import logging
+import re
+import shutil
+import time
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+
+import yt_dlp
+
+from app import sysconfig
+from app.config import settings
+from app.db import SessionLocal
+from app.downloads import edit as editmod
+from app.downloads import errors as dlerrors
+from app.downloads import adapters, formats, service, storage
+from app.downloads.jobdb import (
+    _edit_staging_dir,
+    _job_status,
+    _reset_asset_pending,
+    _set_job,
+    _staging_dir,
+    _touch_job,
+)
+from app.downloads.status import JobStatus
+from app.models import DownloadJob, MediaAsset
+from app.notifications import create_notification
+from app.titles import normalize_title
+
+log = logging.getLogger("siftlode.worker")
+
+
+class _Aborted(Exception):
+    """Raised inside the progress hook when the job was paused/canceled mid-download."""
+
+
+# Both progress sources call back FAR faster than the database should be touched: yt-dlp fires its
+# hook per chunk, and ffmpeg's `-progress pipe:1` emits a block of ~12 lines every ~0.5s while
+# run_ffmpeg calls its callbacks once per LINE. Every callback here is a round-trip (`_job_status`
+# opens a session and SELECTs; `_set_job` opens one and UPDATE+COMMITs), so unthrottled they cost
+# ~10^5 queries on a long job. ONE interval, ONE implementation, used by both paths — three
+# hand-rolled copies is how the ffmpeg side ended up unthrottled while the download side was fine.
+_DB_WRITE_INTERVAL_S = 1.0
+_CANCEL_POLL_INTERVAL_S = 1.0
+
+_THUMB_SUFFIXES = (".jpg", ".jpeg", ".png", ".webp")
+# yt-dlp's working files in the staging dir. None of them is ever the finished media, but several
+# CAN be the biggest file there (a video-only per-format stream, an abandoned fragment run), so the
+# staging fallback must exclude them by name — picking one would store e.g. a silent video-only
+# stream as a ready asset.
+_YTDLP_TEMP_RE = re.compile(
+    r"\.part(-Frag\d+)?$"  # in-flight download / fragment
+    r"|\.ytdl$"  # resume state
+    r"|\.temp\.[^.]+$"  # merge/postprocess temp
+    r"|\.f\d+\.[^.]+$",  # per-format stream kept before the merge
+    re.IGNORECASE,
+)
+
+
+def _notify_download_done(
+    db, user_id: int | None, title: str | None, job_id, *, kind: str
+) -> None:
+    """Post a best-effort 'ready' notice to the owner's inbox — downloads/edits used to finish
+    silently while scheduler jobs and playlist-push already notified (R11 feedback symmetry). A
+    notification failure must never mask the completed job, so it is isolated + rolled back (mirrors
+    scheduler._notify_done). `kind` ("download"/"edit") lets the inbox pick accurate copy; the
+    English title here is only a fallback for an unknown type. `user_id`/`title` are captured by the
+    caller BEFORE its commit, so reading them here needs no post-commit refresh of an expired row."""
+    if user_id is None:
+        return
+    try:
+        create_notification(
+            db,
+            user_id=user_id,
+            type="download_done",
+            title=f"Ready to watch: {title}" if title else "Ready to watch",
+            data={"title": title, "kind": kind},
+        )
+    except Exception:
+        db.rollback()
+        log.exception("failed to write download-done notification for job %s", job_id)
+
+
+def _parse_upload_date(raw) -> date | None:
+    if not raw:
+        return None
+    try:
+        return datetime.strptime(str(raw), "%Y%m%d").date()
+    except ValueError:
+        return None
+
+
+def _fill_asset_meta_early(asset_id: int, info: dict) -> None:
+    """Populate an asset's display metadata from yt-dlp's info_dict the first time it's seen
+    (only if not already filled at enqueue from our catalog) — so an ad-hoc URL's row shows a
+    real title + thumbnail while it downloads, not just the URL. Zero extra network cost."""
+    with SessionLocal() as db:
+        asset = db.get(MediaAsset, asset_id)
+        if asset is None or asset.title:
+            return
+        # `or info.get("id")` avoids a blank card while downloading when the cleaned title is empty
+        # (e.g. a title that was only a social engagement prefix); the completion path later sets
+        # the final title with its own source_ref fallback.
+        asset.title = normalize_title(info.get("title")) or info.get("id")
+        asset.uploader = info.get("uploader") or info.get("channel")
+        asset.uploader_url = adapters.resolve_adapter(None, None, info).uploader_url(info)
+        asset.thumbnail_url = info.get("thumbnail")
+        asset.duration_s = int(info["duration"]) if info.get("duration") else None
+        asset.upload_date = _parse_upload_date(info.get("upload_date"))
+        asset.source_webpage_url = info.get("webpage_url")
+        db.commit()
+
+
+def _make_progress_hook(job_id: int, asset_id: int):
+    state = {"meta_done": False}
+    cancelled = _cancel_poll(job_id)          # same policy as the ffmpeg path
+    allow_write = _rate_limiter(_DB_WRITE_INTERVAL_S)
+
+    def hook(d: dict) -> None:
+        # Cooperative pause/cancel: if the job is no longer 'running', abort the download.
+        if cancelled():
+            raise _Aborted
+        if not state["meta_done"] and d.get("info_dict"):
+            state["meta_done"] = True
+            try:
+                _fill_asset_meta_early(asset_id, d["info_dict"])
+            except Exception:  # noqa: BLE001 — metadata is best-effort, never fail a download
+                pass
+        if d.get("status") != "downloading":
+            return
+        if not allow_write():
+            return
+        # yt-dlp downloads the video and audio streams SEPARATELY (each 0→100%), then merges.
+        # Label the phase so the user understands the bar resetting between streams instead of
+        # seeing a mysterious 95%→5% jump.
+        info = d.get("info_dict") or {}
+        vcodec = info.get("vcodec") or "none"
+        acodec = info.get("acodec") or "none"
+        if vcodec != "none" and acodec == "none":
+            phase = "video"
+        elif acodec != "none" and vcodec == "none":
+            phase = "audio"
+        else:
+            phase = "media"
+        total = d.get("total_bytes") or d.get("total_bytes_estimate") or 0
+        done = d.get("downloaded_bytes") or 0
+        pct = int(done * 100 / total) if total else 0
+        _set_job(
+            job_id,
+            progress=min(pct, 99),
+            speed_bps=int(d["speed"]) if d.get("speed") else None,
+            eta_s=int(d["eta"]) if d.get("eta") else None,
+            phase=phase,
+        )
+
+    return hook
+
+
+def _rate_limiter(interval_s: float, *, now=time.monotonic):
+    """`should_run()` → True at most once per `interval_s` (the first call always passes).
+    `now` is injectable so tests drive a clock instead of patching the global one."""
+    # `None`, not 0.0: "never ran" has to be a VALUE, not a falsy timestamp. A truthiness test here
+    # reads a legitimate `now() == 0.0` as "never ran" and lets a second call straight through —
+    # unreachable with real `time.monotonic()`, but `now` exists to be injected, and a test clock
+    # starting at 0 is the obvious choice. That would let a throttle test encode the wrong
+    # behaviour and still pass.
+    state: dict[str, float | None] = {"at": None}
+
+    def should_run() -> bool:
+        t = now()
+        last = state["at"]
+        if last is not None and t - last < interval_s:
+            return False
+        state["at"] = t
+        return True
+
+    return should_run
+
+
+def _cancel_poll(job_id: int, interval_s: float = _CANCEL_POLL_INTERVAL_S, *, now=time.monotonic):
+    """Cooperative "has this job been paused/cancelled?" poll, rate-limited and sticky: once it
+    says yes it never queries again. Shared by the yt-dlp hook and run_ffmpeg so cancel latency is
+    one policy, not one per call site."""
+    allow = _rate_limiter(interval_s, now=now)
+    state = {"cancelled": False}
+
+    def cancelled() -> bool:
+        if not state["cancelled"] and allow():
+            state["cancelled"] = _job_status(job_id) not in ("running", None)
+        return state["cancelled"]
+
+    return cancelled
+
+
+def _ffmpeg_progress_writer(job_id: int, phase: str, *, now=time.monotonic):
+    """`on_progress` for run_ffmpeg: persist a progress row write at most once per interval and only
+    when the whole-percent value changed (the bar shows integers), plus a separate once-per-interval
+    heartbeat while the percent is stuck (so a slow re-encode isn't mistaken for a stall)."""
+    # Progress writes have their OWN 1/interval budget so a heartbeat can never delay a real write (the
+    # round-1 concern). The heartbeat, in turn, is gated on `last_touch` — the last DB write OR beat —
+    # so a progress write (which already refreshes updated_at) suppresses a redundant heartbeat that
+    # same interval, keeping active downloads at ~1 write/interval, not two.
+    allow_write = _rate_limiter(_DB_WRITE_INTERVAL_S, now=now)
+    state = {"pct": -1}
+    last_touch: dict = {"t": None}  # monotonic time of the last DB write/heartbeat
+
+    def write(pct: float) -> None:
+        whole = int(pct)
+        if whole != state["pct"]:
+            if allow_write():
+                state["pct"] = whole
+                _set_job(job_id, progress=whole, phase=phase)
+                last_touch["t"] = now()
+            return
+        # Same integer percent, but ffmpeg IS still working — a slow re-encode (AV1/VP9 -> H.264 or a
+        # crop on the CPU-only host) can sit on one percent for minutes. Heartbeat updated_at so the
+        # stall watchdog doesn't kill a live job (B-sub-4) — but only if no write/beat already touched
+        # the row this interval, so a progressing download doesn't pay a redundant write.
+        t = now()
+        if last_touch["t"] is None or t - last_touch["t"] >= _DB_WRITE_INTERVAL_S:
+            _touch_job(job_id)
+            last_touch["t"] = t
+
+    return write
+
+
+def _pp_phase(pp: str) -> str:
+    """Map a yt-dlp postprocessor class name to a user-facing phase label. ffmpeg post-steps
+    aren't byte-progress operations (no %), so the UI shows the step name + an indeterminate
+    pulse — this makes the long merge/finalize legible instead of a silent 'Processing'."""
+    if "Merg" in pp:
+        return "merging"
+    if "ExtractAudio" in pp:
+        return "audio_extract"
+    if "Thumbnail" in pp:
+        return "thumbnail"
+    if "SponsorBlock" in pp or "ModifyChapters" in pp:
+        return "sponsorblock"
+    if "Metadata" in pp:
+        return "metadata"
+    return "processing"
+
+
+def _make_pp_hook(job_id: int):
+    """Postprocessor hook: surface the current ffmpeg step so the bar shows a concrete label
+    (Merging / Embedding thumbnail / …) instead of freezing at 100% after the streams finish."""
+
+    def hook(d: dict) -> None:
+        if d.get("status") in ("started", "processing"):
+            _set_job(job_id, phase=_pp_phase(d.get("postprocessor") or ""), speed_bps=None, eta_s=None)
+
+    return hook
+
+
+def _find_thumbnail(staging: Path, media: Path) -> Path | None:
+    for p in staging.iterdir():
+        if p != media and p.suffix.lower() in _THUMB_SUFFIXES:
+            return p
+    return None
+
+
+def _produced_file(info: dict, staging: Path) -> Path:
+    """The media file yt-dlp actually wrote.
+
+    `requested_downloads[0].filepath` is the authoritative answer on YouTube, but an arbitrary-URL
+    extractor may not fill it in at all — and `Path("")` is `Path(".")`, which *passes* `.exists()`,
+    so a missing value used to sail past the fallback and blow up two steps later (`with_name` on an
+    empty name: the BBC-news failure). Anything that isn't a real file counts as absent; then fall
+    back to the largest file left in staging that is neither a thumbnail nor one of yt-dlp's own
+    working files (see `_YTDLP_TEMP_RE`)."""
+    req = (info.get("requested_downloads") or [{}])[0]
+    fp = req.get("filepath") or req.get("_filename") or info.get("filepath") or info.get("_filename")
+    if fp:
+        produced = Path(str(fp))
+        if produced.is_file():
+            return produced
+    cands = [
+        p
+        for p in staging.iterdir()
+        if p.is_file()
+        and p.suffix.lower() not in _THUMB_SUFFIXES
+        and not _YTDLP_TEMP_RE.search(p.name)
+    ]
+    if not cands:
+        raise RuntimeError("yt-dlp produced no output file")
+    return max(cands, key=lambda p: p.stat().st_size)
+
+
+def _media_info(info: dict) -> dict:
+    """Unwrap a playlist/multi_video extraction to the entry that carries the download.
+
+    A single non-YouTube page (a news article's video, a multi-rendition embed) can extract as a
+    wrapper whose own dict has no `requested_downloads` — the media lives on an entry. Pick the
+    FIRST entry that actually downloaded something: on a page with a skipped teaser in front of the
+    real video, entries[0] carries no file, and taking it blindly would label the produced file
+    with the wrong id/title/duration."""
+    entries = [e for e in (info.get("entries") or []) if e]
+    if not entries or info.get("requested_downloads"):
+        return info
+    chosen = next((e for e in entries if e.get("requested_downloads")), entries[0])
+    return {**info, **chosen}
+
+
+def _extract_with_fallback(job_id, asset_id, url, spec, staging, adapter):
+    """Download via yt-dlp using the source `adapter`'s client sets + options. For YouTube the adapter
+    supplies the primary player-client set then a POT-backed fallback (retried on a bot/DRM/format
+    error); other sources make a single attempt. Returns the info dict of the successful attempt."""
+    client_sets = adapter.client_sets()
+    outtmpl = str(staging / "%(id)s.%(ext)s")
+    last_exc: Exception | None = None
+    for i, clients in enumerate(client_sets):
+        opts = formats.build_ydl_opts(
+            spec, outtmpl, _make_progress_hook(job_id, asset_id),
+            extra=adapter.ydl_opts_extra(clients),
+        )
+        opts["postprocessor_hooks"] = [_make_pp_hook(job_id)]
+        _touch_job(job_id)  # stall-watchdog heartbeat: extraction writes no progress, so a slow /
+        # multi-client-set fallback would otherwise cross the stall timeout with a stale updated_at.
+        # (Per-ATTEMPT only; a single extract_info that itself runs past the stall timeout is still
+        # killed — acceptable, as socket_timeout + extractor_retries bound one attempt well under it.)
+        try:
+            with yt_dlp.YoutubeDL(opts) as ydl:
+                return ydl.extract_info(url, download=True)
+        except yt_dlp.utils.DownloadError as exc:
+            last_exc = exc
+            if i < len(client_sets) - 1 and adapter.retriable(str(exc)):
+                log.info("job %s: clients %s failed (%s); retrying with fallback", job_id, clients, str(exc)[:70])
+                for p in list(staging.iterdir()):  # drop partials before the retry
+                    try:
+                        p.unlink()
+                    except OSError:
+                        pass
+                _set_job(job_id, progress=0, phase="downloading")
+                continue
+            raise
+    raise last_exc  # unreachable (loop either returns or raises)
+
+
+def _download_settings() -> tuple[str, int]:
+    """Layout + retention days from the DB config (admin-overridable on the Configuration page),
+    falling back to the env defaults. Read here, not from `settings`, so an admin edit takes effect."""
+    with SessionLocal() as db:
+        return (
+            sysconfig.get_str(db, "download_layout"),
+            sysconfig.get_int(db, "download_retention_days"),
+        )
+
+
+def _ensure_browser_playable(job_id: int, produced: Path, spec: dict, info: dict) -> Path:
+    """Make an mp4-compat-profile download play in every browser: H.264 + AAC/MP3 in mp4. If the
+    download (whatever the source shipped) isn't already that, re-encode the offending stream(s) —
+    or just remux when the codecs are fine but the container isn't. **Scope:** only the mp4 compat
+    profile is normalized; an explicit `vcodec` or a non-mp4 custom profile is the user opting out
+    of the guarantee and is left as-is (so a `webm` profile can still ship VP9/Opus). Returns the
+    file to store (converted, or the original) and corrects `info`'s codec fields to match disk."""
+    if spec.get("container") != "mp4" or spec.get("vcodec"):
+        return produced
+    vcodec, acodec = editmod.probe_codecs(produced)
+    is_mp4 = produced.suffix.lower() == ".mp4"
+    needs, reenc_v, reenc_a = editmod.browser_transcode_flags(vcodec, acodec, is_mp4)
+    if not needs:
+        return produced
+
+    dest = produced.with_name(produced.stem + ".browser.mp4")
+    action = "re-encode" if (reenc_v or reenc_a) else "remux"
+    log.info("job %s: %s (v=%s a=%s mp4=%s) -> browser-safe mp4", job_id, action, vcodec, acodec, is_mp4)
+    _set_job(job_id, phase="processing", progress=0, speed_bps=None, eta_s=None)
+    # Prefer the info duration; probe the file when the extractor didn't provide one, so a long
+    # re-encode still shows real progress instead of a frozen 0%.
+    total_s = int(info["duration"]) if info.get("duration") else editmod.probe_duration(produced)
+    editmod.run_ffmpeg(
+        editmod.build_browser_safe_cmd(produced, dest, reenc_v, reenc_a),
+        total_s=total_s,
+        on_progress=_ffmpeg_progress_writer(job_id, "processing"),
+        should_cancel=_cancel_poll(job_id),
+    )
+    produced.unlink(missing_ok=True)
+    # Keep the stored asset metadata truthful about what's now on disk.
+    if reenc_v:
+        info["vcodec"] = "h264"
+    if reenc_a:
+        info["acodec"] = "aac"
+    return dest
+
+
+def _download(job_id: int, asset_id: int, source_kind: str, source_ref: str, spec: dict) -> None:
+    staging = _staging_dir(asset_id)
+    try:
+        if staging.exists():
+            shutil.rmtree(staging, ignore_errors=True)
+        staging.mkdir(parents=True, exist_ok=True)
+
+        _set_job(job_id, phase="downloading", progress=0)
+        adapter = adapters.resolve_adapter(source_kind, source_ref)
+        url = service.source_url(source_kind, source_ref)
+        info = _media_info(_extract_with_fallback(job_id, asset_id, url, spec, staging, adapter))
+        # Re-resolve now that yt-dlp's info reveals the true source (a bare/redirected url only
+        # identifies post-extraction) so the .nfo uniqueid type + uploader_url agree on one source.
+        adapter = adapters.resolve_adapter(source_kind, source_ref, info)
+
+        produced = _produced_file(info, staging)
+        produced = _ensure_browser_playable(job_id, produced, spec, info)
+        ext = produced.suffix.lstrip(".").lower()
+        meta = storage.MediaMeta(
+            video_id=info.get("id") or source_ref,
+            title=normalize_title(info.get("title")) or source_ref,
+            uploader=info.get("uploader") or info.get("channel") or "Unknown Channel",
+            upload_date=_parse_upload_date(info.get("upload_date")),
+            uniqueid_type=adapter.nfo_uniqueid_type(),
+            duration_s=int(info["duration"]) if info.get("duration") else None,
+            description=info.get("description"),
+            thumbnail_url=info.get("thumbnail"),
+        )
+
+        layout, retention_days = _download_settings()
+        rel = storage.rel_path(meta, ext, layout, asset_id=asset_id)
+        thumb = _find_thumbnail(staging, produced)
+        # Convert the raw thumbnail (webp/png/jpeg) to a real JPEG ourselves — robustly — for the
+        # poster + og:image sidecar, now that yt-dlp's fatal thumbnail convertor is gone. On failure
+        # this is None and write_sidecars writes no poster, so ensure_poster cuts a frame instead.
+        poster_jpg = editmod.thumbnail_to_jpg(thumb, staging / "poster.jpg")
+        storage.place_file(produced, settings.download_root, rel)
+        nfo_ok = storage.write_sidecars(settings.download_root, rel, meta, poster_jpg)
+
+        final = storage.abs_path(settings.download_root, rel)
+        size = final.stat().st_size if final.exists() else None
+        expires = datetime.now(timezone.utc) + timedelta(days=retention_days)
+
+        with SessionLocal() as db:
+            asset = db.get(MediaAsset, asset_id)
+            if asset:
+                asset.status = "ready"
+                asset.rel_path = rel
+                asset.size_bytes = size
+                asset.duration_s = meta.duration_s
+                asset.width = int(info["width"]) if info.get("width") else None
+                asset.height = int(info["height"]) if info.get("height") else None
+                asset.container = ext
+                asset.vcodec = info.get("vcodec") if info.get("vcodec") not in (None, "none") else None
+                asset.acodec = info.get("acodec") if info.get("acodec") not in (None, "none") else None
+                asset.title = meta.title
+                asset.uploader = meta.uploader
+                asset.uploader_url = adapter.uploader_url(info)
+                asset.upload_date = meta.upload_date
+                asset.thumbnail_url = meta.thumbnail_url
+                # Record a self-hosted poster for every download: it's the reliable link-preview
+                # (og:image) source — a remote thumbnail, esp. Facebook's signed CDN URL, expires
+                # and can't be relied on cross-origin. write_sidecars already wrote <base>.jpg from
+                # the thumbnail; ensure_poster returns that, or cuts a frame if there was none.
+                asset.poster_path = editmod.ensure_poster(asset, settings.download_root)
+                asset.source_webpage_url = info.get("webpage_url")
+                asset.nfo_written = nfo_ok
+                asset.error = None
+                asset.last_access_at = datetime.now(timezone.utc)
+                asset.expires_at = expires
+            job = db.get(DownloadJob, job_id)
+            # Capture the owner before commit expires the row (avoids a refresh SELECT just to notify).
+            owner_id = job.user_id if job else None
+            fields = {"status": JobStatus.DONE, "progress": 100, "phase": None, "speed_bps": None,
+                      "eta_s": None}
+            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]
+            # Atomic terminal write: finalizes ONLY while the row is still running, so a child that
+            # finishes just after a route cancel/pause can't resurrect it (see finalize_if_running).
+            finalized = service.finalize_if_running(db, job_id, **fields)
+            db.commit()
+            if finalized:
+                _notify_download_done(db, owner_id, meta.title, job_id, kind="download")
+                log.info("job %s done: %s", job_id, rel)
+
+    except (_Aborted, editmod.EditAborted):
+        # Paused/canceled mid-download or mid-transcode: free the asset for a later retry; keep the
+        # job's status (the route set it to paused/canceled). ref_count is adjusted by the route.
+        _reset_asset_pending(asset_id)
+        log.info("job %s aborted (pause/cancel)", job_id)
+    except Exception as exc:  # noqa: BLE001 — surface any failure to the user, keep worker alive
+        msg = str(exc)[:500]
+        with SessionLocal() as db:
+            asset = db.get(MediaAsset, asset_id)
+            if asset:
+                asset.status = "error"
+                asset.error = msg
+            # Atomic fail: only while still running, so a route-set cancel/pause is never overwritten
+            # with `error` (error also holds the asset → would re-open the double-release class).
+            service.finalize_if_running(
+                db, job_id, status=JobStatus.ERROR, error=msg,
+                error_code=dlerrors.classify(msg), phase=None,
+            )
+            db.commit()
+        log.warning("job %s failed: %s", job_id, msg)
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)
+
+
+def _fail_edit(job_id: int, asset_id: int, msg: str) -> None:
+    with SessionLocal() as db:
+        asset = db.get(MediaAsset, asset_id)
+        if asset:
+            asset.status = "error"
+            asset.error = msg
+        # Atomic fail: only while still running (see the download error path).
+        service.finalize_if_running(
+            db, job_id, status=JobStatus.ERROR, error=msg,
+            error_code=dlerrors.classify(msg), phase=None,
+        )
+        db.commit()
+    log.warning("edit job %s failed: %s", job_id, msg)
+
+
+def _process_edit(job_id: int, asset_id: int) -> None:
+    """Produce a per-user trim/crop clip from the source asset's downloaded file via ffmpeg."""
+    with SessionLocal() as db:
+        job = db.get(DownloadJob, job_id)
+        src = db.get(MediaAsset, job.source_asset_id) if job and job.source_asset_id else None
+        edit_spec = dict(job.edit_spec or {}) if job else {}
+        user_id = job.user_id if job else None
+        src_ready = src is not None and src.status == "ready" and bool(src.rel_path)
+        src_rel = src.rel_path if src else None
+        src_w, src_h, src_dur = (src.width, src.height, src.duration_s) if src else (None, None, None)
+
+    if not src_ready or not src_rel:
+        _fail_edit(job_id, asset_id, "The source download is no longer available.")
+        return
+    src_path = storage.abs_path(settings.download_root, src_rel)
+    if not src_path.exists():
+        _fail_edit(job_id, asset_id, "The source file is missing.")
+        return
+
+    src_ext = src_path.suffix.lstrip(".").lower() or "mp4"
+    crop = editmod.has_crop(edit_spec)
+    out_ext = "mp4" if editmod.needs_reencode(edit_spec) else src_ext
+    total_s = editmod.clip_duration(edit_spec, src_dur) or src_dur or 0
+    staging = _edit_staging_dir(asset_id)
+
+    try:
+        if staging.exists():
+            shutil.rmtree(staging, ignore_errors=True)
+        staging.mkdir(parents=True, exist_ok=True)
+        dest_staging = staging / f"out.{out_ext}"
+
+        _set_job(job_id, phase="editing", progress=0, speed_bps=None, eta_s=None)
+        if edit_spec.get("segments"):
+            cmd, prep = editmod.build_concat_plan(src_path, dest_staging, edit_spec, out_ext, staging)
+            for p, content in prep.items():
+                p.write_text(content, encoding="utf-8")
+        else:
+            cmd = editmod.build_edit_cmd(src_path, dest_staging, edit_spec, out_ext)
+        editmod.run_ffmpeg(
+            cmd,
+            total_s,
+            on_progress=_ffmpeg_progress_writer(job_id, "editing"),
+            should_cancel=_cancel_poll(job_id),
+        )
+        if not dest_staging.exists():
+            raise RuntimeError("ffmpeg produced no output file")
+
+        rel = storage.edit_rel_path(user_id, asset_id, out_ext)
+        storage.place_file(dest_staging, settings.download_root, rel)
+        final = storage.abs_path(settings.download_root, rel)
+        size = final.stat().st_size if final.exists() else None
+        _, retention_days = _download_settings()
+        expires = datetime.now(timezone.utc) + timedelta(days=retention_days)
+
+        with SessionLocal() as db:
+            asset = db.get(MediaAsset, asset_id)
+            if asset:
+                asset.status = "ready"
+                asset.rel_path = rel
+                asset.size_bytes = size
+                asset.container = out_ext
+                asset.duration_s = total_s or asset.duration_s
+                if crop:
+                    asset.width = edit_spec["crop"]["w"]
+                    asset.height = edit_spec["crop"]["h"]
+                else:
+                    asset.width, asset.height = src_w, src_h
+                asset.error = None
+                asset.last_access_at = datetime.now(timezone.utc)
+                asset.expires_at = expires
+            job = db.get(DownloadJob, job_id)
+            # Capture owner + title before commit expires the rows (avoids a refresh SELECT).
+            owner_id = job.user_id if job else None
+            dl_title = asset.title if asset else None
+            # Atomic terminal write (see the download path): don't resurrect a route-stopped job.
+            finalized = service.finalize_if_running(
+                db, job_id, status=JobStatus.DONE, progress=100, phase=None
+            )
+            db.commit()
+            if finalized:
+                _notify_download_done(db, owner_id, dl_title, job_id, kind="edit")
+                log.info("edit job %s done: %s", job_id, rel)
+
+    except editmod.EditAborted:
+        # Paused/canceled mid-encode: free the asset for a later retry (ref_count is the route's job).
+        _reset_asset_pending(asset_id)
+        log.info("edit job %s aborted (pause/cancel)", job_id)
+    except Exception as exc:  # noqa: BLE001 — surface the failure, keep the worker alive
+        _fail_edit(job_id, asset_id, str(exc)[:500])
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)

backend/app/downloads/quota.py

@@ -43,10 +43,16 @@ class QuotaExceeded(Exception):
 def resolve(db: Session, user_id: int) -> QuotaLimits:
     row = db.get(DownloadQuota, user_id)
     if row is not None:
-        return QuotaLimits(row.max_bytes, row.max_concurrent, row.max_jobs, row.unlimited)
+        # Floor max_concurrent at 1 (admin_set_quota already does on write; the sysconfig default's
+        # min is 1). A stored 0 is nonsensical for a concurrency limit AND would diverge the two
+        # "at limit" checks — the worker's claim-window exclusion vs at_concurrency_limit — since a
+        # 0-limit user is "capped" with zero running jobs, which the SQL exclusion can't see. Keep
+        # them consistent by never letting the effective limit drop below 1. (To BLOCK a user's
+        # downloads, suspend them or set max_jobs=0, not max_concurrent=0.)
+        return QuotaLimits(row.max_bytes, max(1, row.max_concurrent), row.max_jobs, row.unlimited)
     return QuotaLimits(
         max_bytes=sysconfig.get_int(db, "download_default_max_bytes"),
-        max_concurrent=sysconfig.get_int(db, "download_default_max_concurrent"),
+        max_concurrent=max(1, sysconfig.get_int(db, "download_default_max_concurrent")),
         max_jobs=sysconfig.get_int(db, "download_default_max_jobs"),
         unlimited=False,
     )

backend/app/downloads/runner.py

@@ -0,0 +1,51 @@
+"""Download/edit child process — runs ONE job's heavy work (yt-dlp download or ffmpeg edit) in its
+own process, launched and supervised by the worker (`app.worker._run_supervised`).
+
+Why a separate process: a worker THREAD can't be killed, a C-level spin (a catastrophic regex, a
+tight yt-dlp retry loop) can't even be cooperatively cancelled, and one such thread starves the
+others via the GIL. Running the work in a child means the supervisor can SIGTERM/SIGKILL it (and its
+process group, so ffmpeg grandchildren die too) on a stall / pause / wall-clock breach.
+
+Contract: the asset is already claimed ('downloading') by the parent. This process does the work and
+writes the terminal job/asset state itself (done / error, or a cooperative pause via the in-flight
+progress hook), then exits 0. An unexpected crash exits non-zero and the parent fails the job.
+"""
+import logging
+import sys
+
+from app.db import SessionLocal
+from app.models import DownloadJob
+
+log = logging.getLogger("siftlode.worker.runner")
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+    if len(sys.argv) != 2:
+        print("usage: python -m app.downloads.runner <job_id>", file=sys.stderr)
+        raise SystemExit(2)
+    job_id = int(sys.argv[1])
+
+    with SessionLocal() as db:
+        job = db.get(DownloadJob, job_id)
+        if job is None:
+            return
+        asset_id = job.asset_id
+        job_kind = job.job_kind
+        spec = dict(job.profile_snapshot or {})
+        source_kind, source_ref = job.source_kind, job.source_ref
+    if asset_id is None:
+        return
+
+    # Imported here (not at module top) so the child pays the yt-dlp import cost only when it has
+    # real work, and to keep the import graph obvious: runner is a thin entry over the pipeline.
+    from app.downloads.pipeline import _download, _process_edit
+
+    if job_kind == "edit":
+        _process_edit(job_id, asset_id)
+    else:
+        _download(job_id, asset_id, source_kind, source_ref, spec)
+
+
+if __name__ == "__main__":
+    main()

backend/app/downloads/service.py

@@ -8,12 +8,15 @@ the worker live in `worker.py` / the routes; this module owns enqueue + asset bo
 """
 from datetime import datetime, timezone
 
-from sqlalchemy import func, select
+from sqlalchemy import func, select, update
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
+from app.config import settings
+from app.downloads import adapters
 from app.downloads import edit as editmod
-from app.downloads import formats, quota
+from app.downloads import formats, quota, storage
+from app.downloads.status import HOLDING, JobStatus
 from app.models import Channel, DownloadJob, MediaAsset, Video
 
 
@@ -26,10 +29,9 @@ class EditError(Exception):
 
 
 def source_url(source_kind: str, source_ref: str) -> str:
-    """The URL yt-dlp should fetch. YouTube stores the 11-char id; ad-hoc stores the URL."""
+    """The URL yt-dlp should fetch. YouTube stores the 11-char id (the adapter reconstructs the watch
-    if source_kind == "youtube":
+    URL); ad-hoc sources store the URL verbatim."""
-        return f"https://www.youtube.com/watch?v={source_ref}"
+    return adapters.resolve_adapter(source_kind, source_ref).source_url(source_ref)
-    return source_ref
 
 
 def reference_url(job, asset) -> str | None:
@@ -110,6 +112,34 @@ def next_queue_pos(db: Session) -> int:
     return (db.execute(select(func.coalesce(func.max(DownloadJob.queue_pos), 0))).scalar() or 0) + 1
 
 
+def incr_ref_count(db: Session, asset_id: int) -> None:
+    """Atomically +1 an asset's hold count AT THE DB. A Python read-modify-write
+    (`asset.ref_count = asset.ref_count + 1`) loses an update when two enqueues of the same
+    (source,format) run in parallel — both read the same value and write the same +1 — leaving the
+    count one short, so the first release can free a file another job still holds (B-sub-5)."""
+    db.execute(
+        update(MediaAsset)
+        .where(MediaAsset.id == asset_id)
+        .values(ref_count=MediaAsset.ref_count + 1)
+        .execution_options(synchronize_session=False)
+    )
+
+
+def decr_ref_count(db: Session, asset_id: int) -> int:
+    """Atomically -1 an asset's hold count (clamped at 0) and RETURN the new value. The caller decides
+    whether to free the asset from the returned count while still holding the row's write lock, so two
+    concurrent releases can't both observe the same pre-decrement value and double-free — Postgres
+    serialises the two UPDATEs on the row lock (B-sub-5). synchronize_session=False: the ORM copy is
+    intentionally left stale; callers read the returned value, not `asset.ref_count`."""
+    return db.execute(
+        update(MediaAsset)
+        .where(MediaAsset.id == asset_id)
+        .values(ref_count=func.greatest(MediaAsset.ref_count - 1, 0))
+        .returning(MediaAsset.ref_count)
+        .execution_options(synchronize_session=False)
+    ).scalar_one()
+
+
 def enqueue(
     db: Session,
     user_id: int,
@@ -141,7 +171,7 @@ def enqueue(
         queue_pos=next_queue_pos(db),
     )
     db.add(job)
-    asset.ref_count = (asset.ref_count or 0) + 1
+    incr_ref_count(db, asset.id)
 
     # Cache hit: the file already exists — no worker round-trip needed.
     if asset.status == "ready":
@@ -210,7 +240,7 @@ def enqueue_edit(
         queue_pos=next_queue_pos(db),
     )
     db.add(job)
-    asset.ref_count = (asset.ref_count or 0) + 1
+    incr_ref_count(db, asset.id)
 
     if asset.status == "ready":  # identical clip already produced for this user → instant
         job.status = "done"
@@ -220,3 +250,134 @@ def enqueue_edit(
     db.commit()
     db.refresh(job)
     return job
+
+
+def finalize_if_running(db: Session, job_id: int, **fields) -> bool:
+    """Write terminal `fields` to a job in ONE atomic ``UPDATE ... WHERE status='running'`` and report
+    whether it fired. This is the single owner of the invariant "a finishing worker child must never
+    resurrect a job a route just stopped": the atomic WHERE closes the read-then-write race an
+    ``if job.status == 'running'`` guard leaves open, so a concurrent cancel/pause can no longer be
+    overwritten with done/error (which would re-open the double-release → file-delete-under-live-holder
+    class, since `done`/`error` hold the asset but `canceled` does not — see release_asset).
+
+    Runs in the CALLER's session and does NOT commit — the caller commits it together with its asset
+    writes in one transaction. It flushes first so any pending asset write takes its row lock BEFORE
+    this takes the job's, matching the cancel route's asset-then-job order (no deadlock). `fields` are
+    mapped-column kwargs (never user input). Returns True when the row was still running and got
+    updated, False when a route had already moved it out of 'running'."""
+    if not fields:
+        return False
+    db.flush()  # asset-then-job lock order: push pending asset writes before we lock the job row
+    # A Core UPDATE with the guard as a WHERE — same atomic "only while still running" write as the
+    # rest of the codebase's 2.0 statements, no hand-built SQL string. synchronize_session=False: this
+    # is a terminal write, so we don't pay to sync the (about-to-be-discarded) ORM identity map. Bound
+    # StrEnum values bind as their plain str literal (StrEnum is a str subclass).
+    result = db.execute(
+        update(DownloadJob)
+        .where(DownloadJob.id == job_id, DownloadJob.status == JobStatus.RUNNING.value)
+        .values(**fields)
+        .execution_options(synchronize_session=False)
+    )
+    return result.rowcount > 0
+
+
+def release_asset(db: Session, job: DownloadJob) -> None:
+    """Drop this job's hold on its asset when it leaves a holding state. Once NO job holds the
+    asset anymore, delete the file + row immediately — a deleted download should free its disk,
+    and the shared cache only needs to span *overlapping* holders (a later re-add just downloads
+    again). `error` counts as holding: enqueue always +1'd ref_count and the worker never
+    decrements on failure (ref_count is the route's job), so an errored job releases here on
+    delete — else its +1 leaks and a later resume→ready keeps the file pinned past its last holder.
+    Idempotent for the cancel path: cancel already released while the job was holding, then set it
+    `canceled` (∉ the set below), so delete-after-cancel is a no-op and never double-releases.
+
+    We DON'T delete an errored asset row here even at ref==0: another request may be concurrently
+    re-enqueuing the same (source,format) — get_or_create_asset would reset that row to `pending` and
+    +1 it, and deleting it under that would FK-null the new job's asset (a lost update on ref_count).
+    A ready asset is still freed at ref==0 (its file is the point); an orphaned errored row is cheap
+    (no file) and gets reused+reset by the next enqueue, or reclaimed by a later GC pass."""
+    if not job.asset_id or job.status not in HOLDING:
+        return
+    asset = db.get(MediaAsset, job.asset_id)
+    if asset is None:
+        return
+    new_count = decr_ref_count(db, asset.id)
+    if new_count == 0 and asset.status == "ready":
+        if asset.rel_path:
+            storage.delete_asset_files(settings.download_root, asset.rel_path)
+        db.delete(asset)
+
+
+# --- Job state transitions ---------------------------------------------------------------------
+# The single home for the pause/resume/cancel/delete/redownload transitions + their asset
+# bookkeeping (release, failed-asset reset, fresh-asset rebuild), so the routes are thin callers and
+# the worker/GC could share the same definitions (B-sub-8). Each commits its own transition; the
+# route keeps only auth + HTTP mapping + serialization.
+
+
+def pause(db: Session, job: DownloadJob) -> None:
+    """Pause a queued/running job (a running worker aborts cooperatively via the cancel poll); a no-op
+    in any other state."""
+    if job.status in (JobStatus.QUEUED, JobStatus.RUNNING):
+        job.status = JobStatus.PAUSED
+        db.commit()
+
+
+def resume(db: Session, job: DownloadJob) -> None:
+    """Requeue a paused/errored job for a fresh attempt, clearing its error. If the SHARED asset itself
+    failed, reset it to pending so the worker actually re-downloads — otherwise the requeued job would
+    instantly re-inherit the asset's stale error (the worker short-circuits an errored asset)."""
+    if job.status in (JobStatus.PAUSED, JobStatus.ERROR):
+        job.progress = 0
+        job.error = None
+        job.error_code = None
+        if job.asset_id:
+            asset = db.get(MediaAsset, job.asset_id)
+            if asset and asset.status == "error":  # MediaAsset.status (no enum), not a JobStatus
+                asset.status = "pending"
+                asset.error = None
+        job.status = JobStatus.QUEUED
+        db.commit()
+
+
+def cancel(db: Session, job: DownloadJob) -> None:
+    """Cancel a job unless it's already done/canceled, releasing its asset hold WHILE it still counts
+    as holding — `canceled` ∉ HOLDING, so a later delete won't double-release."""
+    if job.status not in (JobStatus.DONE, JobStatus.CANCELED):
+        release_asset(db, job)  # release while the job still counts as holding
+        job.status = JobStatus.CANCELED
+        db.commit()
+
+
+def delete(db: Session, job: DownloadJob) -> None:
+    """Delete a job, releasing its asset hold first (which frees the file iff this was the last holder)."""
+    release_asset(db, job)
+    db.delete(job)
+    db.commit()
+
+
+def redownload(db: Session, job: DownloadJob) -> None:
+    """Rebuild a finished/failed job's file into a FRESH, private asset (the cache sig is salted with
+    the job id + current asset id, so it never reuses the dedup pool) and requeue the SAME job row —
+    so any public share link (DownloadLink -> job_id) keeps resolving to the newly-downloaded file.
+    The old hold is dropped first (freeing the old file iff this job was its last holder). The caller
+    has already rejected edit clips + still-in-progress jobs (HTTP 409)."""
+    spec = formats.normalize(job.profile_snapshot)
+    sig = formats.format_sig(spec, salt=f"{job.id}:{job.asset_id}")
+    asset = get_or_create_asset(db, job.source_kind, job.source_ref, sig)
+    populate_from_catalog(db, asset)
+    # Drop the old hold BEFORE re-pointing the job — release_asset keys off the job's current asset.
+    release_asset(db, job)
+    incr_ref_count(db, asset.id)
+    job.asset_id = asset.id
+    job.status = JobStatus.QUEUED
+    job.progress = 0
+    job.phase = None
+    job.error = None
+    job.speed_bps = None
+    job.eta_s = None
+    # Re-derive the display name from the freshly cleaned title on completion (else an older, un-cleaned
+    # name would survive the rebuild).
+    job.display_name = None
+    job.queue_pos = next_queue_pos(db)  # tail of the queue, not its stale original slot
+    db.commit()

backend/app/downloads/status.py

@@ -0,0 +1,38 @@
+"""Canonical download-job status values — the ONE source of truth for the lifecycle literals.
+
+A job's status is written from several places: the worker (claim → running, terminal done/error,
+requeue), the routes (pause/cancel/redownload/delete), the service (enqueue), and the GC. Keeping the
+literals here is a data-safety measure, not tidiness. A British/American drift once silently broke
+cancellation: the supervisor compared the live status against ``"cancelled"`` while the cancel route
+wrote ``"canceled"`` (models.py), so the supervisor's "a route stopped it → kill the child, free the
+asset" branch was DEAD. A canceled job's child then ran to completion and wrote ``"done"``
+unconditionally over the route's ``"canceled"``; because ``done`` counts as a holding state but
+``canceled`` does not (see ``service.release_asset``), a later delete released the asset a SECOND time,
+dropping ``ref_count`` below the live holder count and deleting a file still in use. Import these names
+instead of typing the strings.
+"""
+
+from enum import StrEnum
+
+
+class JobStatus(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    PAUSED = "paused"
+    DONE = "done"
+    ERROR = "error"
+    CANCELED = "canceled"
+
+
+# A job "holds" its media asset (the +1 on ``ref_count`` from enqueue) while in any of these states;
+# ``release_asset`` on a status OUTSIDE this set is a no-op. ``CANCELED`` is deliberately excluded: the
+# cancel route releases once while the job is still holding, then sets ``CANCELED``, so a later delete
+# does not double-release. This invariant only holds while a finishing child cannot flip ``CANCELED``
+# back into the set — hence the worker's terminal writes are conditional on the row still being RUNNING.
+HOLDING = frozenset(
+    {JobStatus.QUEUED, JobStatus.RUNNING, JobStatus.PAUSED, JobStatus.DONE, JobStatus.ERROR}
+)
+
+# States a route sets to STOP a running job. The worker's supervisor must step in (kill the child, free
+# the asset, leave the route's status intact) when it observes one of these on a job it is running.
+STOPPED_BY_ROUTE = frozenset({JobStatus.PAUSED, JobStatus.CANCELED})

backend/app/downloads/storage.py

@@ -59,6 +59,10 @@ class MediaMeta:
     title: str
     uploader: str
     upload_date: date | None
+    # The .nfo <uniqueid type=...> — the source's scraper type (youtube / facebook / …), set from
+    # the SourceAdapter. Defaults to the source-neutral "generic" so an un-updated caller is at worst
+    # uninformative, never actively mislabelling a non-YouTube download as "youtube".
+    uniqueid_type: str = "generic"
     duration_s: int | None = None
     description: str | None = None
     thumbnail_url: str | None = None
@@ -170,7 +174,7 @@ def _nfo_xml(meta: MediaMeta) -> str:
         f"  <premiered>{aired}</premiered>",
         f"  <year>{year}</year>",
         f"  <plot>{escape(meta.description or '')}</plot>",
-        f"  <uniqueid type=\"youtube\" default=\"true\">{escape(meta.video_id)}</uniqueid>",
+        f"  <uniqueid type=\"{escape(meta.uniqueid_type)}\" default=\"true\">{escape(meta.video_id)}</uniqueid>",
     ]
     if meta.duration_s:
         parts.append(f"  <runtime>{round(meta.duration_s / 60)}</runtime>")
@@ -178,16 +182,23 @@ def _nfo_xml(meta: MediaMeta) -> str:
     return "\n".join(parts)
 
 
+def _sidecar(media: Path, ext: str) -> Path:
+    """The sibling sidecar path (`.nfo` / `.jpg`) for a media file. Swaps the extension on the FULL
+    media path — NOT via `media.with_suffix("")` first: stripping the real extension leaves a stem
+    whose OWN last dot may be inside the title (e.g. "Sonka Házilag."), which `with_suffix` would
+    then read as the extension and clobber, orphaning the sidecar under a truncated name."""
+    return media.with_suffix(ext)
+
+
 def write_sidecars(
     download_root: str, rel: str, meta: MediaMeta, thumb_src: Path | None
 ) -> bool:
     """Write `<basename>.nfo` + `<basename>.jpg` next to the media file. Returns True if written."""
     media = abs_path(download_root, rel)
-    base = media.with_suffix("")
     try:
-        base.with_suffix(".nfo").write_text(_nfo_xml(meta), encoding="utf-8")
+        _sidecar(media, ".nfo").write_text(_nfo_xml(meta), encoding="utf-8")
         if thumb_src and thumb_src.exists():
-            shutil.copyfile(str(thumb_src), str(base.with_suffix(".jpg")))
+            shutil.copyfile(str(thumb_src), str(_sidecar(media, ".jpg")))
         return True
     except OSError:
         return False
@@ -196,8 +207,7 @@ def write_sidecars(
 def delete_asset_files(download_root: str, rel: str) -> None:
     """Remove the media file and its sidecars; prune now-empty parent dirs (best effort)."""
     media = abs_path(download_root, rel)
-    base = media.with_suffix("")
+    for p in (media, _sidecar(media, ".nfo"), _sidecar(media, ".jpg")):
-    for p in (media, base.with_suffix(".nfo"), base.with_suffix(".jpg")):
         try:
             p.unlink()
         except OSError:

backend/app/email.py

@@ -83,6 +83,19 @@ def send_access_approved(email: str) -> bool:
     return _send([email], "You're in — your Siftlode access is approved", body, reply_to=admin)
 
 
+def send_access_denied(email: str) -> bool:
+    admin = _admin_contact()
+    body = (
+        "Hi,\n\n"
+        "Thanks for your interest in Siftlode. After review, your access request wasn't approved "
+        "this time.\n\n"
+        "If you think this was a mistake, you're welcome to reply and let us know.\n\n"
+        "— Siftlode"
+        + (f"\n\nQuestions? Just reply to this email ({admin})." if admin else "")
+    )
+    return _send([email], "About your Siftlode access request", body, reply_to=admin)
+
+
 def send_role_changed(to: str, role: str, operator: str | None) -> bool:
     line = (
         "You've been granted admin access on Siftlode — you can now manage settings, the "

backend/app/feedquery.py

@@ -0,0 +1,537 @@
+"""Feed read-model: the pure query-building and row-serialization layer behind the feed.
+
+Extracted from `routes/feed.py` so the read-model has one home instead of living inside the
+router module — the feed route handlers and the playlist-detail query share these helpers (the
+projection, the filter builder, and keyset paging). Nothing here defines a route or reaches for
+request state; it's all `(db, user, params) -> query`, and a malformed cursor raises a plain
+`ValueError` for the route handler to translate (the tsquery sanitizer lives in `app.utils`).
+"""
+
+import base64
+import binascii
+import json
+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.models import (
+    LIVE_OR_UPCOMING,
+    BlockedChannel,
+    Channel,
+    ChannelTag,
+    ExploredChannel,
+    Playlist,
+    PlaylistItem,
+    SearchFind,
+    Subscription,
+    Tag,
+    User,
+    Video,
+    VideoState,
+)
+from app.utils import iso, to_tsquery_str
+
+
+def _channel_url(channel_id: str, handle: str | None) -> str:
+    if handle and handle.startswith("@"):
+        return f"https://www.youtube.com/{handle}"
+    return f"https://www.youtube.com/channel/{channel_id}"
+
+
+def _saved_expr(user: User):
+    """A correlated EXISTS labelled `saved`: is this video in the user's Watch later list?
+    (Watch later is the built-in playlist that replaced the old per-video 'saved' status.)"""
+    return (
+        select(1)
+        .select_from(PlaylistItem)
+        .join(Playlist, Playlist.id == PlaylistItem.playlist_id)
+        .where(
+            Playlist.user_id == user.id,
+            Playlist.kind == "watch_later",
+            PlaylistItem.video_id == Video.id,
+        )
+        .exists()
+        .label("saved")
+    )
+
+
+def feed_columns(user: User, state) -> list:
+    """The shared feed-row projection (joined Channel fields + per-user watch state +
+    `saved`), consumed by both the feed query and the playlist-detail query so a new column
+    is added in exactly one place. `state` is the caller's aliased VideoState (outer-joined)."""
+    return [
+        Video.id,
+        Video.title,
+        Video.channel_id,
+        Channel.title.label("channel_title"),
+        Channel.thumbnail_url.label("channel_thumbnail"),
+        Channel.handle.label("channel_handle"),
+        Video.published_at,
+        Video.thumbnail_url,
+        Video.duration_seconds,
+        Video.view_count,
+        Video.is_short,
+        Video.live_status,
+        func.coalesce(state.status, "new").label("status"),
+        func.coalesce(state.position_seconds, 0).label("position_seconds"),
+        _saved_expr(user),
+    ]
+
+
+def serialize(row) -> dict:
+    return {
+        "id": row.id,
+        "title": row.title,
+        "channel_id": row.channel_id,
+        "channel_title": row.channel_title,
+        "channel_thumbnail": row.channel_thumbnail,
+        "channel_url": _channel_url(row.channel_id, row.channel_handle),
+        "published_at": iso(row.published_at),
+        "thumbnail_url": row.thumbnail_url,
+        "duration_seconds": row.duration_seconds,
+        "view_count": row.view_count,
+        "is_short": row.is_short,
+        "live_status": row.live_status,
+        "status": row.status or "new",
+        "position_seconds": row.position_seconds or 0,
+        "saved": bool(getattr(row, "saved", False)),
+        "watch_url": f"https://www.youtube.com/watch?v={row.id}",
+    }
+
+
+def tags_by_category(db: Session, tag_ids: list[int]) -> dict[str, list[int]]:
+    """Group tag ids by their category (language/topic/other). The single source for the category split
+    shared by the feed's tag WHERE (filtered_query) and the facet/count summary (feed_summary), so the
+    two can't disagree on which selected tag belongs to which category."""
+    if not tag_ids:
+        return {}  # skip the pointless `WHERE id IN ()` round-trip on the no-tag-filter hot path
+    out: dict[str, list[int]] = {}
+    for tid, cat in db.execute(select(Tag.id, Tag.category).where(Tag.id.in_(tag_ids))).all():
+        out.setdefault(cat, []).append(tid)
+    return out
+
+
+def filtered_query(
+    db: Session,
+    user: User,
+    *,
+    tags: list[int],
+    tag_mode: str,
+    channel_ids: list[str],
+    q: str | None,
+    min_duration: int | None,
+    max_duration: int | None,
+    max_age_days: int | None,
+    published_after: date | None,
+    published_before: date | None,
+    show_normal: bool,
+    include_shorts: bool,
+    include_live: bool,
+    show: str,
+    scope: str = "my",
+    library_source: str = "organic",
+    exclude_tag_category: str | None = None,
+) -> tuple[Select, object]:
+    """Build the feed query (joins + all WHERE filters), shared by /feed and /feed/count.
+    Returns the column-bearing select plus the priority/relevance rank expression for sorting.
+
+    `scope="my"` (default) restricts the feed to the user's own non-hidden subscriptions.
+    `scope="all"` shows every video in the shared catalog (any user's ingested channels);
+    the subscription is then only LEFT-joined so per-channel priority still resolves for
+    channels the user happens to be subscribed to. Per-user watch state stays private in
+    either mode via the VideoState outer join."""
+    state = aliased(VideoState)
+    status_expr = func.coalesce(state.status, "new")
+
+    query = select(*feed_columns(user, state)).join(
+        Channel, Channel.id == Video.channel_id
+    )
+
+    if scope == "all":
+        # Whole shared catalog; subscription is optional (only for priority sort).
+        query = query.outerjoin(
+            Subscription,
+            and_(
+                Subscription.channel_id == Video.channel_id,
+                Subscription.user_id == user.id,
+            ),
+        )
+    else:
+        # "Mine": the user's own videos = their non-hidden subscriptions OR videos they
+        # surfaced via their own live YouTube search. Both are LEFT-joined so the Source
+        # filter below can include either or both, and the subscription row stays available
+        # for the priority sort.
+        query = query.outerjoin(
+            Subscription,
+            and_(
+                Subscription.channel_id == Video.channel_id,
+                Subscription.user_id == user.id,
+                Subscription.hidden.is_(False),
+            ),
+        ).outerjoin(
+            SearchFind,
+            and_(SearchFind.video_id == Video.id, SearchFind.user_id == user.id),
+        )
+
+    # The state-gated views (watched/hidden/in_progress) only ever return videos that HAVE a
+    # video_states row, so an INNER join lets the planner drive from the user's own small video_states
+    # set (~100 rows) instead of scanning all videos and outer-joining (PERF-16). status is NOT NULL on
+    # a present row (server_default 'new'), so the raw-column filters below match the coalesce form
+    # exactly. 'unwatched'/'all' include row-less 'new' videos, so they keep the outer join.
+    state_required = show in ("watched", "hidden", "in_progress")
+    join_state = query.join if state_required else query.outerjoin
+    query = join_state(
+        state, and_(state.video_id == Video.id, state.user_id == user.id)
+    )
+
+    # Hide videos the maintenance job has flagged as currently unplayable (deleted/private/
+    # abandoned). They're either deleted after a grace period or unhidden if they recover;
+    # either way they shouldn't show in any feed view meanwhile.
+    query = query.where(Video.unavailable_since.is_(None))
+
+    # Explored videos are PER-EXPLORER private: a via_explore video (ingested when someone
+    # opened an un-subscribed channel's page) is visible only to users who explored or
+    # subscribe to its channel, so one user's curiosity never leaks into everyone else's
+    # catalog. Applied in BOTH scopes; the channel page reaches its ephemeral videos by
+    # asking for scope=all + channel_ids (the channel is in this accessible set).
+    accessible_explore = (
+        select(Subscription.channel_id).where(Subscription.user_id == user.id)
+    ).union(
+        select(ExploredChannel.channel_id).where(ExploredChannel.user_id == user.id)
+    )
+    query = query.where(
+        or_(
+            Video.via_explore.is_(False),
+            Video.channel_id.in_(accessible_explore),
+        )
+    )
+
+    # Per-user channel blocklist: never show this user videos from a channel they blocked
+    # (applies to feed, Library, explore, and the channel page alike).
+    query = query.where(
+        Video.channel_id.notin_(
+            select(BlockedChannel.channel_id).where(BlockedChannel.user_id == user.id)
+        )
+    )
+
+    # Source filter. In the shared Library ("all" scope) it uses the GLOBAL via_search flag
+    # (search-discovered by anyone). In "my" scope it's the user's OWN provenance:
+    # "organic" = your subscriptions, "search" = videos you found via your own search,
+    # "all" = both. Default "organic" keeps the Mine feed = subscriptions only.
+    if scope == "all":
+        if library_source == "organic":
+            query = query.where(Video.via_search.is_(False))
+        elif library_source == "search":
+            query = query.where(Video.via_search.is_(True))
+        # "all" → both organic and search-discovered videos
+    else:
+        subscribed = Subscription.channel_id.isnot(None)
+        searched = SearchFind.video_id.isnot(None)
+        if library_source == "search":
+            query = query.where(searched)
+        elif library_source == "all":
+            query = query.where(or_(subscribed, searched))
+        else:  # "organic" (default): subscriptions only
+            query = query.where(subscribed)
+
+    if channel_ids:
+        # OR across the picked channels; every other filter still applies on top.
+        query = query.where(Video.channel_id.in_(channel_ids))
+    if min_duration is not None:
+        query = query.where(Video.duration_seconds >= min_duration)
+    if max_duration is not None:
+        query = query.where(Video.duration_seconds <= max_duration)
+    if max_age_days is not None:
+        cutoff = datetime.now(timezone.utc).timestamp() - max_age_days * 86400
+        query = query.where(
+            Video.published_at >= datetime.fromtimestamp(cutoff, tz=timezone.utc)
+        )
+    if published_after is not None:
+        start = datetime.combine(
+            published_after, datetime.min.time(), tzinfo=timezone.utc
+        )
+        query = query.where(Video.published_at >= start)
+    if published_before is not None:
+        end = datetime.combine(
+            published_before, datetime.min.time(), tzinfo=timezone.utc
+        ) + timedelta(days=1)
+        query = query.where(Video.published_at < end)
+    # Full-text relevance search over the weighted search document (title > creator keywords +
+    # the queries that surfaced the video > description; see Video.search_vector). YouTube-like
+    # "fuzzy" matching: word-order-independent, multi-word AND, prefix on the word being typed,
+    # accent-insensitive (unaccent_simple). The channel name still matches as a substring so
+    # channel searches work. `rank_expr` (weight-aware ts_rank) drives the "relevance" sort.
+    rank_expr = None
+    if q:
+        # Resolve the channels whose NAME matches up front (there are only a few hundred channels, so
+        # this is a tiny standalone scan) and match videos by channel_id. ORing an unindexed
+        # `unaccent(channels.title) ILIKE '%q%'` straight into the per-video predicate defeated the
+        # search_vector GIN — the planner detoasted every non-matching tsvector to test the `@@`
+        # (~2.6s/search on the prod-sized set); channel_id.in_(...) keeps the GIN as a BitmapOr branch
+        # (PERF-12). Empty match -> false() so the OR collapses to the text match alone.
+        like = func.unaccent(f"%{q}%")
+        matching_channel_ids = (
+            db.execute(select(Channel.id).where(func.unaccent(Channel.title).ilike(like)))
+            .scalars()
+            .all()
+        )
+        channel_match = (
+            Video.channel_id.in_(matching_channel_ids) if matching_channel_ids else false()
+        )
+        ts_str = to_tsquery_str(q)
+        if ts_str:
+            tsq = func.to_tsquery("public.unaccent_simple", ts_str)
+            query = query.where(or_(Video.search_vector.op("@@")(tsq), channel_match))
+            # Scale ts_rank (a float4) to an integer score so the keyset cursor compares it
+            # EXACTLY — a raw float4 vs the float8 cursor value mismatches on round-trip and
+            # breaks paging (the same page repeats). 1e6 granularity is ample; ties break on
+            # published_at then id.
+            rank_expr = cast(func.ts_rank(Video.search_vector, tsq) * 1000000, BigInteger)
+        else:
+            # No usable tokens (e.g. only punctuation): fall back to a plain substring match.
+            query = query.where(or_(func.unaccent(Video.title).ilike(like), channel_match))
+
+    if tags:
+        # AND across tag categories (e.g. language AND topic narrows), OR within a category; the any/all
+        # toggle controls multiple topic tags. ⚠️ feed_summary.passes() reimplements this exact rule in
+        # Python for the sidebar count/facets — keep the two in lockstep (equivalence-tested by
+        # test_feed_summary_matches_count_plus_facets).
+        by_category = tags_by_category(db, tags)
+        # Facet counting drops the category being counted so its own chips don't zero each
+        # other out (standard drill-down faceting: a category's count ignores its own
+        # selections but still honours the other categories' filters).
+        if exclude_tag_category:
+            by_category.pop(exclude_tag_category, None)
+        visible = or_(ChannelTag.user_id.is_(None), ChannelTag.user_id == user.id)
+        for category, ids in by_category.items():
+            if category == "topic" and tag_mode == "and" and len(ids) > 1:
+                sub = (
+                    select(ChannelTag.channel_id)
+                    .where(ChannelTag.tag_id.in_(ids), visible)
+                    .group_by(ChannelTag.channel_id)
+                    .having(func.count(func.distinct(ChannelTag.tag_id)) == len(set(ids)))
+                )
+            else:
+                sub = select(ChannelTag.channel_id).where(
+                    ChannelTag.tag_id.in_(ids), visible
+                )
+            query = query.where(Video.channel_id.in_(sub))
+
+    # Content type: Normal / Shorts / Live·Upcoming as a union of enabled types.
+    # Explicit Watched/Saved/Hidden views show every type so nothing goes missing.
+    explicit_view = show in ("watched", "hidden")
+    if not explicit_view:
+        type_clauses = []
+        if show_normal:
+            type_clauses.append(
+                and_(Video.is_short.is_(False), Video.live_status.notin_(LIVE_OR_UPCOMING))
+            )
+        if include_shorts:
+            type_clauses.append(Video.is_short.is_(True))
+        if include_live:
+            type_clauses.append(Video.live_status.in_(LIVE_OR_UPCOMING))
+        query = query.where(or_(*type_clauses) if type_clauses else false())
+
+    if show == "unwatched":
+        query = query.where(status_expr.notin_(("watched", "hidden")))
+    elif show == "in_progress":
+        # Started but not finished: a stored resume position, not yet watched/hidden. INNER-joined
+        # (state_required) so the raw state columns are safe and the planner can use video_states.
+        query = query.where(
+            and_(state.position_seconds > 0, state.status.notin_(("watched", "hidden")))
+        )
+    elif show == "watched":
+        query = query.where(state.status == "watched")
+    elif show == "hidden":
+        query = query.where(state.status == "hidden")
+    else:  # all
+        query = query.where(status_expr != "hidden")
+
+    return query, rank_expr
+
+
+def feed_summary(db: Session, user: User, **params) -> dict:
+    """Single-pass replacement for /feed/count + 3x /facets (PERF-13): the sidebar's total video count
+    and every tag's distinct-channel facet count, derived in Python from ONE grouped query instead of
+    four full passes over the subscribed set on every filter change.
+
+    The one query is the base filter with the TAG predicate removed, grouped by channel: it yields every
+    channel that has a matching video, with its video count. From that ~few-hundred-row map we compute:
+      - count  = sum of the video counts of the channels that pass the SELECTED tag filter;
+      - facets = per tag, the number of distinct channels that carry it AND pass the drill-down filter
+                 (the tag's own category dropped, unless it's a conjunctive topic-AND — mirroring the
+                 old /facets exclude_tag_category logic exactly).
+    Tag matching is channel-based, identical to filtered_query's tag block (AND across categories, OR
+    within, topic-AND requires ALL selected topics)."""
+    tag_mode = params.get("tag_mode", "or")
+
+    # ONE pass: per-channel video counts for the base filter, tags stripped so every candidate channel
+    # is present to facet over.
+    base, _rank = filtered_query(db, user, **{**params, "tags": []})
+    ch_col = base.with_only_columns(Video.channel_id).subquery()
+    channel_counts: dict[str, int] = dict(
+        db.execute(select(ch_col.c.channel_id, func.count()).group_by(ch_col.c.channel_id)).all()
+    )
+    if not channel_counts:
+        return {"count": 0, "facets": {}}
+
+    # channel -> its visible tag ids, plus each tag's category (for grouping the facet output).
+    visible = or_(ChannelTag.user_id.is_(None), ChannelTag.user_id == user.id)
+    channel_tags: dict[str, set[int]] = {}
+    tag_category: dict[int, str] = {}
+    for cid, tid, cat in db.execute(
+        select(ChannelTag.channel_id, ChannelTag.tag_id, Tag.category)
+        .join(Tag, Tag.id == ChannelTag.tag_id)
+        .where(visible, ChannelTag.channel_id.in_(channel_counts.keys()))
+    ).all():
+        channel_tags.setdefault(cid, set()).add(tid)
+        tag_category[tid] = cat
+
+    # Selected tags grouped by category (read from Tag via the shared helper, so a selected tag that no
+    # base channel carries still filters everything out for its category — matching the SQL `IN (empty)`
+    # behaviour).
+    selected_by_cat: dict[str, set[int]] = {
+        cat: set(ids) for cat, ids in tags_by_category(db, params.get("tags") or []).items()
+    }
+
+    def passes(ch_tags: set[int], exclude_cat: str | None) -> bool:
+        # The Python mirror of filtered_query's SQL tag block (AND across categories, OR within,
+        # topic-AND requires all selected) — keep in lockstep; see the ⚠️ note there.
+        for cat, sel in selected_by_cat.items():
+            if cat == exclude_cat:
+                continue
+            if cat == "topic" and tag_mode == "and" and len(sel) > 1:
+                if not sel <= ch_tags:  # conjunctive: channel must carry ALL selected topics
+                    return False
+            elif not (sel & ch_tags):  # disjunctive: channel must carry ANY selected tag
+                return False
+        return True
+
+    count = sum(
+        n for cid, n in channel_counts.items() if passes(channel_tags.get(cid, set()), None)
+    )
+
+    facets: dict[int, int] = {}
+    for category in ("language", "topic", "other"):
+        # Drop this category's own selections so its chips keep independent counts; a conjunctive
+        # topic-AND keeps them (each remaining chip narrows to channels that ALSO have the selected).
+        exclude = None if (category == "topic" and tag_mode == "and") else category
+        for cid, ch_tags in channel_tags.items():
+            if not passes(ch_tags, exclude):
+                continue
+            for tid in ch_tags:
+                if tag_category.get(tid) == category:
+                    facets[tid] = facets.get(tid, 0) + 1
+    return {"count": count, "facets": facets}
+
+
+# --- Keyset (cursor) pagination ---------------------------------------------
+#
+# Each sort is described as an ordered list of key columns (expression + direction
+# + whether it can be NULL + a JSON round-trip kind), always with Video.id as the
+# final, unique tiebreaker. This drives BOTH the ORDER BY and the keyset WHERE so
+# they can never drift apart — the prerequisite for correct cursor paging. Keyset
+# 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]:
+    pub = {"expr": Video.published_at, "asc": False, "nullable": False, "kind": "dt"}
+    table: dict[str, list[dict]] = {
+        "newest": [pub],
+        "oldest": [{**pub, "asc": True}],
+        "views": [{"expr": Video.view_count, "asc": False, "nullable": True, "kind": "num"}],
+        "views_asc": [{"expr": Video.view_count, "asc": True, "nullable": True, "kind": "num"}],
+        "duration_desc": [{"expr": Video.duration_seconds, "asc": False, "nullable": True, "kind": "num"}],
+        "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"}],
+        "subscribers": [{"expr": Channel.subscriber_count, "asc": False, "nullable": True, "kind": "num"}],
+        "subscribers_asc": [{"expr": Channel.subscriber_count, "asc": True, "nullable": True, "kind": "num"}],
+        # Your per-channel priority (set in the channel manager), newest first within a tier.
+        # coalesce keeps it null-safe in "all" scope where unsubscribed channels have no row.
+        "priority": [{"expr": func.coalesce(Subscription.priority, 0), "asc": False, "nullable": False, "kind": "num"}, pub],
+        "priority_asc": [{"expr": func.coalesce(Subscription.priority, 0), "asc": True, "nullable": False, "kind": "num"}, pub],
+        # Deterministic per-seed shuffle: the same seed yields the same total order, so
+        # the cursor stays valid across pages of one shuffled run.
+        "shuffle": [{"expr": func.md5(func.concat(Video.id, str(seed))), "asc": True, "nullable": False, "kind": "str"}],
+    }
+    # Relevance (search-result ranking) only exists when there's a query to rank against;
+    # without `rank_expr` it falls through to newest. Ties break by newest, then id.
+    if rank_expr is not None:
+        table["relevance"] = [
+            {"expr": rank_expr, "asc": False, "nullable": False, "kind": "num"},
+            pub,
+        ]
+    return table.get(sort) or table["newest"]
+
+
+def order_by(keys: list[dict]):
+    cols = []
+    for k in keys:
+        c = k["expr"].asc() if k["asc"] else k["expr"].desc()
+        cols.append(c.nulls_last() if k["nullable"] else c)
+    cols.append(Video.id.asc())  # unique final tiebreaker
+    return cols
+
+
+def keyset_predicate(keys: list[dict], cursor_id: str):
+    """WHERE clause selecting rows strictly AFTER the cursor in the sort order.
+
+    Lexicographic over the key columns then id, NULL-aware for `nulls_last`: a NULL
+    sorts after every non-NULL value, so a cursor sitting on a non-NULL value must
+    also pull in the NULL group, and equality treats NULL == NULL.
+
+    Built recursively so that for a NON-nullable leading key we can prepend a non-strict
+    range bound (`col <= v` for desc / `col >= v` for asc) as an AND conjunct — logically
+    a no-op over the OR of strict-after branches, but it lets the planner bound the index
+    scan instead of scanning from the top and filtering every earlier row (PERF-15: deep
+    `newest` pages went 51.8k -> ~0.5k buffers). A NULLABLE key can't take that bound (the
+    NULL group sorts after every value and `col <= v` would drop it), so it keeps the pure
+    NULL-aware OR form."""
+    def eq(k):
+        return k["expr"].is_(None) if k["value"] is None else k["expr"] == k["value"]
+
+    def after(k):
+        if k["value"] is None:
+            return false()  # nulls are last; nothing sorts strictly after them
+        cmp = k["expr"] > k["value"] if k["asc"] else k["expr"] < k["value"]
+        return or_(cmp, k["expr"].is_(None)) if k["nullable"] else cmp
+
+    def rec(i: int):
+        if i == len(keys):
+            return Video.id > cursor_id  # all keys tied -> break by the unique id
+        k = keys[i]
+        tail = or_(after(k), and_(eq(k), rec(i + 1)))
+        if not k["nullable"] and k["value"] is not None:
+            bound = k["expr"] >= k["value"] if k["asc"] else k["expr"] <= k["value"]
+            return and_(bound, tail)
+        return tail
+
+    return rec(0)
+
+
+def encode_cursor(keys: list[dict], row) -> str:
+    vals = []
+    for i, k in enumerate(keys):
+        v = getattr(row, f"_k{i}")
+        vals.append(v.isoformat() if (v is not None and k["kind"] == "dt") else v)
+    payload = json.dumps({"k": vals, "id": row.id})
+    return base64.urlsafe_b64encode(payload.encode()).decode()
+
+
+def decode_cursor(keys: list[dict], cursor: str) -> tuple[list, str]:
+    try:
+        payload = json.loads(base64.urlsafe_b64decode(cursor.encode()))
+        raw = payload["k"]
+        if len(raw) != len(keys):
+            raise ValueError("key arity mismatch")
+        vals = [
+            datetime.fromisoformat(v) if (v is not None and k["kind"] == "dt") else v
+            for k, v in zip(keys, raw)
+        ]
+        return vals, payload["id"]
+    except (binascii.Error, json.JSONDecodeError, KeyError, ValueError, TypeError) as exc:
+        # Framework-free: the route handler translates this into an HTTP 400 so the
+        # read-model stays web-layer-agnostic (see routes/feed.get_feed).
+        raise ValueError("Invalid feed cursor") from exc

backend/app/main.py

@@ -25,13 +25,14 @@ from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.middleware.sessions import SessionMiddleware
 
-from app import auth, state
+from app import state
 from app.config import settings
 from app.db import SessionLocal
 from app.plex import stream as plex_stream
 from app.routes import (
     admin,
     audit as audit_routes,
+    auth as auth_routes,
     channels,
     config as config_routes,
     downloads,
@@ -159,8 +160,34 @@ async def static_cache_headers(request, call_next):
     return response
 
 
+# Baseline security response headers (SEC-1). A minimal, safe set that needs no per-route tuning:
+# nosniff stops MIME-confusion, the Referrer-Policy keeps the (private) app URL from leaking to
+# external sites the user follows, `frame-ancestors 'none'` blocks click-jacking by refusing to be
+# iframed anywhere (we never embed our own pages; we embed OTHERS, which this does not affect), and
+# Permissions-Policy turns off powerful features the app never uses. `X-Frame-Options: DENY` duplicates
+# the frame-ancestors intent for legacy engines that never implemented CSP frame-ancestors (belt and
+# suspenders — modern browsers use the CSP directive and ignore the header). A full Content-Security-Policy
+# (script/style/connect sources) is deferred — the SPA's inline styles + the YouTube/Plex embeds make
+# it real work — and HSTS belongs on the TLS-terminating edge (the Caddy front door), not here.
+_SECURITY_HEADERS = {
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "Content-Security-Policy": "frame-ancestors 'none'",
+    "X-Frame-Options": "DENY",
+    "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+}
+
+
+@app.middleware("http")
+async def security_headers(request, call_next):
+    response = await call_next(request)
+    for name, value in _SECURITY_HEADERS.items():
+        response.headers.setdefault(name, value)
+    return response
+
+
 app.include_router(health.router)
-app.include_router(auth.router)
+app.include_router(auth_routes.router)
 app.include_router(sync.router)
 app.include_router(tags.router)
 app.include_router(feed.router)

backend/app/models.py

@@ -219,7 +219,7 @@ class Subscription(Base, TimestampMixin):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     user_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
+        ForeignKey("users.id", ondelete="CASCADE")
     )
     channel_id: Mapped[str] = mapped_column(
         ForeignKey("channels.id", ondelete="CASCADE"), index=True
@@ -251,14 +251,23 @@ class Video(Base, TimestampMixin):
     __tablename__ = "videos"
 
     id: Mapped[str] = mapped_column(String(16), primary_key=True)  # video id
+    # No standalone channel_id index: the composite `ix_videos_channel_pub_desc`
+    # (channel_id, published_at DESC NULLS LAST, id) from migration 0067 leads with channel_id, so it
+    # serves every channel_id lookup (FK cascade, sync upsert, channel-detail) AND the per-channel feed
+    # sort. Like the search_vector GIN, this composite is migration-defined, not an inline `index=True`.
     channel_id: Mapped[str] = mapped_column(
-        ForeignKey("channels.id", ondelete="CASCADE"), index=True
+        ForeignKey("channels.id", ondelete="CASCADE")
     )
     title: Mapped[str | None] = mapped_column(Text)  # normalized for display (see app.titles)
     original_title: Mapped[str | None] = mapped_column(Text)  # raw YouTube title, preserved
     description: Mapped[str | None] = mapped_column(Text)
-    published_at: Mapped[datetime | None] = mapped_column(
+    # NOT NULL (migration 0068): in reality every video carries a publish date, and a nullable key
-        DateTime(timezone=True), index=True
+    # forced the feed's keyset predicate into a non-sargable `... OR published_at IS NULL` disjunction
+    # that blocked the ix_videos_published_at_desc range (deep pages scanned from the top and filtered —
+    # PERF-15). server_default now() is the safety net for the rare date-less ingest (the enrich fills
+    # the real date); the ix_videos_published_at index stays for the `oldest` sort.
+    published_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), index=True, nullable=False, server_default=func.now()
     )
     thumbnail_url: Mapped[str | None] = mapped_column(String(1024))
     duration_seconds: Mapped[int | None] = mapped_column(Integer)
@@ -276,18 +285,22 @@ class Video(Base, TimestampMixin):
     # folds YouTube's own relevance judgement into the local search: a video YouTube returned
     # for "ti amo magyarul" becomes findable by that query locally even if its title lacks it.
     search_terms: Mapped[str | None] = mapped_column(Text)
+    # No btree here or on the flag columns below: migration 0069 (PERF-3) dropped the never-picked
+    # boolean btrees and replaced the useful ones with partial indexes over the target subset
+    # (via_search=true, NOT shorts_probed, unavailable_since IS NOT NULL) — migration-defined, like the
+    # search_vector GIN.
     is_short: Mapped[bool] = mapped_column(
-        Boolean, default=False, server_default="false", index=True
+        Boolean, default=False, server_default="false"
     )
     # Whether the youtube.com/shorts/<id> probe has run for this video.
     shorts_probed: Mapped[bool] = mapped_column(
-        Boolean, default=False, server_default="false", index=True
+        Boolean, default=False, server_default="false"
     )
     # True when this video first entered the catalog via a live YouTube search (not an
     # organic channel/playlist sync). Used to hide search-discovered "noise" from the
     # Library by default; left False by the organic ingest paths.
     via_search: Mapped[bool] = mapped_column(
-        Boolean, default=False, server_default="false", index=True
+        Boolean, default=False, server_default="false"
     )
     # True when this video entered the catalog because a user EXPLORED its (un-subscribed)
     # channel. Like via_search it's hidden from the shared Library by default, but it's
@@ -295,7 +308,7 @@ class Video(Base, TimestampMixin):
     # explored or subscribe to its channel (a gate in the feed query), so one user's
     # curiosity never floods everyone else's catalog. Left False by the organic ingest paths.
     via_explore: Mapped[bool] = mapped_column(
-        Boolean, default=False, server_default="false", index=True
+        Boolean, default=False, server_default="false"
     )
     # none | live | upcoming | premiere | was_live
     live_status: Mapped[str] = mapped_column(
@@ -311,11 +324,14 @@ class Video(Base, TimestampMixin):
     # (least-recently-checked first); unavailable_since marks a video as currently
     # unplayable (hidden from the feed immediately, hard-deleted after a grace period);
     # unavailable_reason records why (deleted|private|paywalled|abandoned|stuck_live).
+    # last_checked_at: no plain btree — migration 0069 (PERF-18) replaced it with the partial
+    # ix_videos_recheck_order (last_checked_at NULLS FIRST WHERE unavailable_since IS NULL) that the
+    # revalidate job's exact ORDER BY rides; unavailable_since is a partial WHERE IS NOT NULL (PERF-3).
     last_checked_at: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), index=True
+        DateTime(timezone=True)
     )
     unavailable_since: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), index=True
+        DateTime(timezone=True)
     )
     unavailable_reason: Mapped[str | None] = mapped_column(String(24))
 
@@ -388,7 +404,7 @@ class VideoState(Base, UpdatedAtMixin):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     user_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
+        ForeignKey("users.id", ondelete="CASCADE")
     )
     video_id: Mapped[str] = mapped_column(
         ForeignKey("videos.id", ondelete="CASCADE"), index=True
@@ -418,7 +434,7 @@ class SearchFind(Base, TimestampMixin):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     user_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
+        ForeignKey("users.id", ondelete="CASCADE")
     )
     video_id: Mapped[str] = mapped_column(
         ForeignKey("videos.id", ondelete="CASCADE"), index=True
@@ -443,7 +459,7 @@ class ExploredChannel(Base, TimestampMixin):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     user_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
+        ForeignKey("users.id", ondelete="CASCADE")
     )
     channel_id: Mapped[str] = mapped_column(
         ForeignKey("channels.id", ondelete="CASCADE"), index=True
@@ -462,7 +478,7 @@ class BlockedChannel(Base, TimestampMixin):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     user_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
+        ForeignKey("users.id", ondelete="CASCADE")
     )
     channel_id: Mapped[str] = mapped_column(
         ForeignKey("channels.id", ondelete="CASCADE"), index=True
@@ -531,9 +547,6 @@ class AppState(Base):
     sync_paused: Mapped[bool] = mapped_column(
         Boolean, default=False, server_default="false"
     )
-    # Admin override for the maintenance job's rolling re-validation batch (videos re-checked
-    # per run). NULL = use the config/env default (settings.maintenance_revalidate_batch).
-    maintenance_revalidate_batch: Mapped[int | None] = mapped_column(Integer)
     # First-run install wizard. `configured` is False on a fresh instance (the app runs in
     # setup mode: only the wizard works) and flipped True when the wizard finishes. While
     # unconfigured, a one-time setup token (only its SHA-256 hash stored) gates the wizard;
@@ -619,7 +632,7 @@ class PlaylistItem(Base):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     playlist_id: Mapped[int] = mapped_column(
-        ForeignKey("playlists.id", ondelete="CASCADE"), index=True
+        ForeignKey("playlists.id", ondelete="CASCADE")
     )
     video_id: Mapped[str] = mapped_column(
         ForeignKey("videos.id", ondelete="CASCADE"), index=True
@@ -644,7 +657,7 @@ class SavedView(Base, TimestampMixin, UpdatedAtMixin):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     user_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
+        ForeignKey("users.id", ondelete="CASCADE")
     )
     name: Mapped[str] = mapped_column(String(80))
     filters: Mapped[dict] = mapped_column(JSON)
@@ -893,7 +906,7 @@ class DownloadShare(Base, TimestampMixin):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     job_id: Mapped[int] = mapped_column(
-        ForeignKey("download_jobs.id", ondelete="CASCADE"), index=True
+        ForeignKey("download_jobs.id", ondelete="CASCADE")
     )
     from_user_id: Mapped[int] = mapped_column(
         ForeignKey("users.id", ondelete="CASCADE"), index=True
@@ -995,6 +1008,13 @@ class PlexLibrary(Base, TimestampMixin, UpdatedAtMixin):
     kind: Mapped[str] = mapped_column(String(16))  # "movie" | "show"
     enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default="true")
     synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    # HU-overlay support (E5 S5). `metadata_lang` tags the section's metadata language. An OVERLAY
+    # library (overlay_of set) is the Hungarian-metadata twin of another section: it is never browsable
+    # on its own — its titles' HU fields are written onto the matched EN rows (paired by `guid`).
+    metadata_lang: Mapped[str] = mapped_column(String(8), default="en", server_default="en")
+    overlay_of: Mapped[int | None] = mapped_column(
+        ForeignKey("plex_libraries.id", ondelete="SET NULL"), index=True
+    )
 
 
 class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
@@ -1007,6 +1027,7 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
         Index("ix_plex_shows_genres_gin", "genres", postgresql_using="gin"),
         Index("ix_plex_shows_directors_gin", "directors", postgresql_using="gin"),
         Index("ix_plex_shows_cast_gin", "cast_names", postgresql_using="gin"),
+        Index("ix_plex_shows_genres_hu_gin", "genres_hu", postgresql_using="gin"),
         # ix_plex_shows_collections_gin already created with collections (migration 0047).
     )
 
@@ -1015,6 +1036,9 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
     library_id: Mapped[int] = mapped_column(
         ForeignKey("plex_libraries.id", ondelete="CASCADE"), index=True
     )
+    # Canonical external id (e.g. "tmdb:12345") — the key that pairs this EN row with its HU-overlay
+    # twin during sync (E5 S5). Indexed for the guid->row overlay match.
+    guid: Mapped[str | None] = mapped_column(String(64), index=True)
     title: Mapped[str] = mapped_column(String(512))
     summary: Mapped[str | None] = mapped_column(Text)
     year: Mapped[int | None] = mapped_column(Integer)
@@ -1037,6 +1061,17 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
     people_text: Mapped[str | None] = mapped_column(Text)  # cast+directors, folded into search_vector
     # Set once the show's FULL cast has been rich-fetched by the backfill; NULL = still the listing top-3.
     people_enriched_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    # Rich-fetch-only detail fields, persisted by the same backfill that fills the full cast (E5 S5b) so
+    # the info page serves from this row instead of a live plex.metadata() call. NULL until enriched.
+    imdb_rating: Mapped[float | None] = mapped_column(Float)  # IMDb-specific score (vs `rating` = audienceRating)
+    imdb_id: Mapped[str | None] = mapped_column(String(16))  # tt… → the clickable IMDb link
+    tagline: Mapped[str | None] = mapped_column(Text)
+    full_cast: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))  # ordered [{name, role, thumb}]
+    # 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))
+    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(
         TSVECTOR,
         Computed(
@@ -1046,6 +1081,15 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
             persisted=True,
         ),
     )
+    search_vector_hu: Mapped[object | None] = mapped_column(
+        TSVECTOR,
+        Computed(
+            "setweight(to_tsvector('public.unaccent_simple', coalesce(title_hu, '')), 'A') || "
+            "setweight(to_tsvector('public.unaccent_simple', coalesce(people_text, '')), 'B') || "
+            "setweight(to_tsvector('public.unaccent_simple', left(coalesce(summary_hu, ''), 1000)), 'C')",
+            persisted=True,
+        ),
+    )
 
 
 class PlexSeason(Base, TimestampMixin, UpdatedAtMixin):
@@ -1077,6 +1121,7 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
         Index("ix_plex_items_directors_gin", "directors", postgresql_using="gin"),
         Index("ix_plex_items_cast_gin", "cast_names", postgresql_using="gin"),
         Index("ix_plex_items_collections_gin", "collection_keys", postgresql_using="gin"),
+        Index("ix_plex_items_genres_hu_gin", "genres_hu", postgresql_using="gin"),
     )
 
     id: Mapped[int] = mapped_column(primary_key=True)
@@ -1085,6 +1130,9 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
         ForeignKey("plex_libraries.id", ondelete="CASCADE"), index=True
     )
     kind: Mapped[str] = mapped_column(String(16), index=True)  # "movie" | "episode"
+    # Canonical external id (e.g. "tmdb:12345") — pairs a MOVIE row with its HU-overlay twin during
+    # sync (E5 S5); indexed for the guid->row match. Episodes carry it too but it's unused for them.
+    guid: Mapped[str | None] = mapped_column(String(64), index=True)
     show_id: Mapped[int | None] = mapped_column(
         ForeignKey("plex_shows.id", ondelete="CASCADE"), index=True
     )
@@ -1130,6 +1178,17 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     people_text: Mapped[str | None] = mapped_column(Text)
     # Set once the movie's FULL cast has been rich-fetched by the backfill; NULL = still the listing top-3.
     people_enriched_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    # Rich-fetch-only detail fields, persisted by the same backfill that fills the full cast (E5 S5b) so
+    # the info page serves from this row instead of a live plex.metadata() call. NULL until enriched.
+    imdb_rating: Mapped[float | None] = mapped_column(Float)  # IMDb-specific score (vs `rating` = audienceRating)
+    imdb_id: Mapped[str | None] = mapped_column(String(16))  # tt… → the clickable IMDb link
+    tagline: Mapped[str | None] = mapped_column(Text)
+    full_cast: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))  # ordered [{name, role, thumb}]
+    # 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))
+    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(
         TSVECTOR,
         Computed(
@@ -1139,6 +1198,15 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
             persisted=True,
         ),
     )
+    search_vector_hu: Mapped[object | None] = mapped_column(
+        TSVECTOR,
+        Computed(
+            "setweight(to_tsvector('public.unaccent_simple', coalesce(title_hu, '')), 'A') || "
+            "setweight(to_tsvector('public.unaccent_simple', coalesce(people_text, '')), 'B') || "
+            "setweight(to_tsvector('public.unaccent_simple', left(coalesce(summary_hu, ''), 1000)), 'C')",
+            persisted=True,
+        ),
+    )
 
 
 class PlexPerson(Base, TimestampMixin, UpdatedAtMixin):
@@ -1191,7 +1259,7 @@ class PlexState(Base, UpdatedAtMixin):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     user_id: Mapped[int] = mapped_column(
-        ForeignKey("users.id", ondelete="CASCADE"), index=True
+        ForeignKey("users.id", ondelete="CASCADE")
     )
     item_id: Mapped[int] = mapped_column(
         ForeignKey("plex_items.id", ondelete="CASCADE"), index=True
@@ -1260,7 +1328,7 @@ class PlexPlaylistItem(Base):
 
     id: Mapped[int] = mapped_column(primary_key=True)
     playlist_id: Mapped[int] = mapped_column(
-        ForeignKey("plex_playlists.id", ondelete="CASCADE"), index=True
+        ForeignKey("plex_playlists.id", ondelete="CASCADE")
     )
     item_id: Mapped[int] = mapped_column(
         ForeignKey("plex_items.id", ondelete="CASCADE"), index=True

backend/app/notifications.py

@@ -14,6 +14,14 @@ from app.models import Notification
 # rows are never pruned (the user hasn't seen them yet).
 READ_SOFT_CAP = 200
 
+# Hard limit of the Notification.title column, read straight from the model so the clamp
+# can never drift from the actual column width (a later migration is the single source of
+# truth). Titles are only an English fallback — the client renders the translated message
+# from `data` — so clamping an over-long one (e.g. a FB/IG reel whose "title" is the whole
+# caption, hundreds of chars) is harmless to the UI and prevents a StringDataRightTruncation
+# that would abort the caller's whole transaction (the batched download_gc run in particular).
+TITLE_MAX_LEN = Notification.__table__.c.title.type.length
+
 
 def create_notification(
     db: Session,
@@ -27,6 +35,8 @@ def create_notification(
 ) -> Notification:
     """Insert one notification for a user. Callers that batch many inserts in a single
     transaction can pass commit=False and commit once themselves."""
+    if title is not None and len(title) > TITLE_MAX_LEN:
+        title = title[: TITLE_MAX_LEN - 1] + "…"  # clamp to the column limit, add an ellipsis
     notif = Notification(
         user_id=user_id, type=type, title=title, body=body, data=data
     )

backend/app/plex/cache.py

@@ -0,0 +1,13 @@
+"""Shared on-disk cache root for proxied Plex assets.
+
+Both poster/art images (imgcache.py) and converted subtitle VTTs (subtitles.py) are cached here, so
+the directory belongs to neither module — it lives in this neutral home to avoid a cross-import.
+On-demand + bounded by the library size; no eviction (a few hundred MB at most for a big library —
+acceptable, matching the download disk trade-offs).
+"""
+
+from pathlib import Path
+
+from app.config import settings
+
+CACHE_DIR = Path(settings.download_root) / ".plex-img-cache"

backend/app/plex/cards.py

@@ -0,0 +1,65 @@
+"""Plex list/leaf card serializers: the small `model -> dict` projections the library grid,
+playlists, and detail views render. Extracted from routes/plex/browse.py so the row-shaping
+lives beside the other Plex read-model modules (detail.py, query.py) rather than inside the
+router. Pure functions — no DB, no request state."""
+
+from app.models import PlexItem, PlexShow, PlexState
+
+
+def movie_card(it: PlexItem, st: PlexState | None) -> dict:
+    return {
+        "id": it.rating_key,
+        "type": "movie",
+        "title": it.title,
+        "year": it.year,
+        "duration_seconds": it.duration_s,
+        "thumb": f"/api/plex/image/{it.rating_key}",
+        "playable": it.playable,
+        "status": st.status if st else "new",
+        "position_seconds": st.position_seconds if st else 0,
+    }
+
+
+def show_card(sh: PlexShow, status: str = "new") -> dict:
+    return {
+        "id": sh.rating_key,
+        "type": "show",
+        "title": sh.title,
+        "year": sh.year,
+        "thumb": f"/api/plex/image/{sh.rating_key}",
+        "season_count": sh.child_count,
+        # Aggregate watch-state across the show's episodes (new | in_progress | watched) → grid badge.
+        "status": status,
+    }
+
+
+def episode_card(e: PlexItem, st: PlexState | None) -> dict:
+    return {
+        "id": e.rating_key,
+        "type": "episode",
+        "title": e.title,
+        "summary": e.summary,
+        "season_number": e.season_number,
+        "episode_number": e.episode_number,
+        "duration_seconds": e.duration_s,
+        "thumb": f"/api/plex/image/{e.rating_key}",
+        "playable": e.playable,
+        "status": st.status if st else "new",
+        "position_seconds": st.position_seconds if st else 0,
+    }
+
+
+def leaf_card(
+    it: PlexItem,
+    st: PlexState | None,
+    show_title: str | None = None,
+    show_rk: str | None = None,
+) -> 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."""
+    if it.kind == "episode":
+        card = episode_card(it, st)
+        card["show_title"] = show_title
+        card["show_id"] = show_rk
+        return card
+    return movie_card(it, st)

backend/app/plex/client.py

@@ -85,6 +85,10 @@ class PlexClient:
             f"/library/sections/{key}/all",
             params={
                 "type": item_type,
+                # includeGuids=1 carries each item's Guid array (tmdb/imdb/tvdb ids) in the cheap
+                # listing, so the sync can capture the canonical guid without a per-item rich fetch —
+                # the pairing key for the HU overlay (E5 S5).
+                "includeGuids": 1,
                 "X-Plex-Container-Start": start,
                 "X-Plex-Container-Size": size,
             },

backend/app/plex/detail.py

@@ -0,0 +1,59 @@
+"""Parse the "info page" rich metadata out of a full Plex metadata dict, and persist the subset that
+the detail endpoints serve from the DB row (E5 S5b).
+
+Shared by the live info-page path (routes.plex.browse) and the background rich re-sync (plex.sync) so
+the two never diverge — the same one-parser rule that keeps `people.py`'s cast handling consistent.
+`rich_detail` is the pure parser; `apply_rich_detail` writes the rich-ONLY fields onto a movie/show row
+(genres/directors/studio/content_rating already land from the cheap listing at `_apply_facet_fields`)."""
+
+from app.plex import people
+
+
+def rich_detail(meta: dict) -> dict:
+    """Pull the info-page extras out of a full Plex metadata dict: an IMDb score + link, content
+    rating, genres, director(s), studio, tagline, and cast (name/role/photo). Best-effort — any
+    missing field is just omitted."""
+    # Rating: IMDb-ONLY — the explicit `imdb://` entry in the Rating array, or NULL. We deliberately do
+    # NOT fall back to audienceRating/rating here: that is a Plex audience score, not an IMDb score, and
+    # labelling it "imdb_rating" mislabels it. The audience score is served separately (item/show detail
+    # expose the `rating` column) so the UI can show it when there's no IMDb score.
+    imdb_rating = None
+    for r in meta.get("Rating") or []:
+        if str(r.get("image") or "").startswith("imdb://"):
+            try:
+                imdb_rating = round(float(r.get("value")), 1)
+            except (TypeError, ValueError):
+                pass
+            break
+    # IMDb id (tt…) from the Guid list → a clickable link.
+    imdb_id = None
+    for g in meta.get("Guid") or []:
+        gid = str(g.get("id") or "")
+        if gid.startswith("imdb://"):
+            imdb_id = gid.split("imdb://", 1)[1]
+            break
+    return {
+        "imdb_rating": imdb_rating,
+        "imdb_id": imdb_id,
+        "imdb_url": f"https://www.imdb.com/title/{imdb_id}/" if imdb_id else None,
+        "content_rating": meta.get("contentRating"),
+        "genres": [g.get("tag") for g in (meta.get("Genre") or []) if g.get("tag")][:8],
+        "directors": [
+            d.get("tag") for d in (meta.get("Director") or []) if d.get("tag")
+        ][:4],
+        "studio": meta.get("studio"),
+        "tagline": meta.get("tagline"),
+        "cast": people.cast_from_meta(meta),
+    }
+
+
+def apply_rich_detail(row, meta: dict) -> None:
+    """Persist the rich-ONLY detail fields onto a movie/show row so the info page serves them from the
+    DB instead of a live Plex call. Call wherever a rich metadata dict is fetched (the cast backfill +
+    the info-page lazy enrich). Empty cast persists as SQL NULL (none_as_null), so an EN fallback and
+    the `full_cast IS NULL` "not yet enriched" signal stay meaningful."""
+    d = rich_detail(meta)
+    row.imdb_rating = d["imdb_rating"]
+    row.imdb_id = d["imdb_id"]
+    row.tagline = d["tagline"]
+    row.full_cast = d["cast"] or None

backend/app/plex/imgcache.py

@@ -0,0 +1,68 @@
+"""Thin on-disk cache + proxy helpers for Plex poster/art images.
+
+Posters/art/cast-photos are proxied on demand; without a cache every scroll re-hits Plex over the
+LAN (janky). We cache the fetched bytes on local disk keyed by a stable id, so repeat views (and
+other users) serve instantly from disk. On-demand + bounded by the library size; no eviction (a
+few hundred MB at most for a big library — acceptable, matching the download disk trade-offs).
+
+The cache directory (``cache.CACHE_DIR``) is shared with the subtitle cache (see ``subtitles.py``).
+"""
+
+from fastapi import Response
+from sqlalchemy.orm import Session
+
+from app.models import PlexCollection, PlexItem, PlexSeason, PlexShow
+from app.plex.cache import CACHE_DIR
+from app.plex.lookups import by_rating_key
+
+_EXT_CT = [("jpg", "image/jpeg"), ("png", "image/png"), ("webp", "image/webp")]
+_CT_EXT = {ct: ext for ext, ct in _EXT_CT}
+# Target box per variant — Plex resizes to these server-side. Posters fill ≤176px cells (grid/info/
+# strips), so 400px covers 2× DPR; the faint backdrop art only needs ~1280px. Keeps images ~tens of KB.
+SIZES = {"thumb": (400, 600), "art": (1280, 720)}
+
+
+def key_for(db: Session, rating_key: str, variant: str) -> str | None:
+    """The stored Plex image path for a known rating_key (item/show/season). Only mirrored keys
+    are proxyable — this is not an open image proxy."""
+    it = by_rating_key(db, PlexItem, rating_key)
+    if it is not None:
+        return it.art_key if variant == "art" else it.thumb_key
+    sh = by_rating_key(db, PlexShow, rating_key)
+    if sh is not None:
+        return sh.art_key if variant == "art" else sh.thumb_key
+    se = by_rating_key(db, PlexSeason, rating_key)
+    if se is not None:
+        return se.thumb_key
+    col = by_rating_key(db, PlexCollection, rating_key)
+    if col is not None:
+        return col.thumb_key
+    return None
+
+
+def read(key: str) -> tuple[bytes, str] | None:
+    for ext, ct in _EXT_CT:
+        p = CACHE_DIR / f"{key}.{ext}"
+        try:
+            if p.exists() and p.stat().st_size > 0:
+                return p.read_bytes(), ct
+        except OSError:
+            pass
+    return None
+
+
+def write(key: str, data: bytes, ct: str) -> None:
+    ext = _CT_EXT.get((ct or "").split(";")[0].strip(), "jpg")
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        tmp = CACHE_DIR / f"{key}.{ext}.tmp"
+        tmp.write_bytes(data)
+        tmp.replace(CACHE_DIR / f"{key}.{ext}")  # atomic publish
+    except OSError:
+        pass  # cache is best-effort
+
+
+def response(data: bytes, ct: str) -> Response:
+    return Response(
+        content=data, media_type=ct, headers={"Cache-Control": "public, max-age=86400"}
+    )

backend/app/plex/lookups.py

@@ -0,0 +1,16 @@
+"""Small shared Plex row lookups, so the get-by-rating_key pattern lives in one place."""
+from typing import TypeVar
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+_M = TypeVar("_M")
+
+
+def by_rating_key(db: Session, model: type[_M], rating_key: str) -> _M | None:
+    """The mirrored row for a Plex rating_key, or None. `model` is any of the rating_key-keyed Plex
+    tables (PlexItem / PlexShow / PlexSeason / PlexCollection); the return type is that model, so call
+    sites keep their `Model | None` static type."""
+    return db.execute(
+        select(model).where(model.rating_key == str(rating_key))
+    ).scalars().first()

backend/app/plex/people.py

@@ -5,7 +5,7 @@ re-sync (plex.sync), so the two paths never diverge."""
 
 from urllib.parse import quote
 
-from sqlalchemy import text
+from sqlalchemy import select, text
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
@@ -55,7 +55,10 @@ def enrich_row_people(db: Session, row, cast: list[dict]) -> bool:
         dirty = True
     # Headshot cache: upsert name -> proxied thumb (a later fetch fills a prior NULL; names without a
     # whitelisted photo still get a row so a card can show a placeholder).
-    existing = {p.name: p for p in db.query(PlexPerson).filter(PlexPerson.name.in_(names))}
+    existing = {
+        p.name: p
+        for p in db.execute(select(PlexPerson).where(PlexPerson.name.in_(names))).scalars()
+    }
     missing: dict[str, str | None] = {}
     for c in cast:
         nm, th = c.get("name"), c.get("thumb")
@@ -74,7 +77,7 @@ def enrich_row_people(db: Session, row, cast: list[dict]) -> bool:
         # items in the same batch: SessionLocal is autoflush=False, so the ORM query above can't see a
         # same-batch pending insert, and this path also races the concurrent info-page enrichment. The
         # Core execute runs immediately (not deferred to the caller's commit), so a later row in the
-        # batch sees the row and skips it. Mirrors app/sync/videos.py:_insert_stubs.
+        # batch sees the row and skips it. Mirrors app/sync/videos.py:insert_stubs.
         db.execute(
             pg_insert(PlexPerson)
             .values([{"name": nm, "photo_thumb": th} for nm, th in missing.items()])

backend/app/plex/query.py

@@ -0,0 +1,250 @@
+"""Plex library query-shaping: the full-text field-scope rechecks and the sidebar metadata
+filters that /library and /facets share. Extracted from routes/plex/browse.py so the query
+builder has one home (and so the HU-overlay column selection lands here, not in the router).
+Pure query fragments — every function returns SQLAlchemy expressions or a params dict."""
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import and_, case, func, or_, type_coerce
+from sqlalchemy.dialects.postgresql import JSONB
+
+TS_CONFIG = "public.unaccent_simple"
+
+# --- Language-aware column pickers (E5 S6) ----------------------------------
+#
+# The HU-overlay twin (E5 S5) stores Hungarian metadata in `*_hu` columns on the SAME EN row. When
+# the app language is `hu` we serve those, falling back to the EN column where a row has no HU twin.
+# Two flavours of picker, on purpose:
+#   * DISPLAY / FILTER (`title_col`/`genres_col`): `coalesce(*_hu, *)` — an EN fallback so a row with
+#     no HU metadata still shows (and filters on) its English value. (The detail endpoints serve the
+#     HU summary directly off the loaded row, so no `summary_col` SQL helper is needed.)
+#   * SEARCH (`vector_col` + `field_recheck`): the raw `*_hu` column coalesced to '' — MIRRORING the
+#     generated `search_vector_hu` definition (which uses `coalesce(title_hu, '')`, NOT an EN
+#     fallback), so the field recheck stays a strict subset of the GIN vector prefilter (the S2
+#     invariant). `people_text` is language-neutral and shared by both vectors.
+
+
+def title_col(model, lang: str):
+    return func.coalesce(model.title_hu, model.title) if lang == "hu" else model.title
+
+
+def genres_col(model, lang: str):
+    # type_coerce so the JSONB comparator (`.contains` / `@>`, GIN-backed) survives the coalesce.
+    if lang == "hu":
+        return type_coerce(func.coalesce(model.genres_hu, model.genres), JSONB)
+    return model.genres
+
+
+def vector_col(model, lang: str):
+    # RANKING vector. In HU we rank by the Hungarian vector; a row matched only via its English vector
+    # (see `vector_match`) gets rank 0 and sorts last, which is the intended HU-first ordering.
+    return model.search_vector_hu if lang == "hu" else model.search_vector
+
+
+def vector_match(model, lang: str, tsq):
+    """The full-text WHERE clause. In HU, match EITHER vector so a row with no HU twin stays findable
+    by its English title (search_vector_hu has no title tokens for such a row); EN matches only the EN
+    vector. Ranking still uses `vector_col` (the HU vector in HU mode)."""
+    if lang == "hu":
+        return or_(
+            model.search_vector_hu.op("@@")(tsq), model.search_vector.op("@@")(tsq)
+        )
+    return model.search_vector.op("@@")(tsq)
+
+
+# Field-scoped search: the scope-pill in the header search box narrows a full-text query to ONE
+# facet of the row. `all` uses the GIN-indexed weighted `search_vector` untouched (byte-identical to
+# the pre-scope behaviour); a specific field keeps that GIN prefilter AND re-checks a per-column
+# tsvector, so the scoped hits are always a strict subset of Everywhere. The per-field expressions
+# mirror the `search_vector` Computed definition (same `TS_CONFIG`, same `left(summary, 1000)`
+# truncation) so scoping never surfaces a match the vector itself wouldn't. `episode` is handled
+# separately in the query body (it targets episode rows, not the movie/show grid).
+FIELD_COLUMNS = ("title", "people", "summary", "episode")
+
+
+def _title_tsv(col):
+    return func.to_tsvector(TS_CONFIG, func.coalesce(col, ""))
+
+
+def _summary_tsv(col):
+    return func.to_tsvector(TS_CONFIG, func.left(func.coalesce(col, ""), 1000))
+
+
+def field_recheck(model, field: str, tsq, lang: str = "en"):
+    """A per-field `to_tsvector(...) @@ tsq` clause for a non-`all`, non-`episode` scope, or None.
+    Each per-field tsvector mirrors the generated `search_vector[_hu]` definition (same TS_CONFIG,
+    same `left(summary, 1000)`). In HU, title/summary re-check BOTH the HU and EN columns so a scoped
+    hit stays a strict subset of `vector_match`'s HU union; `people` is language-neutral."""
+    hu = lang == "hu"
+    if field == "title":
+        cols = [model.title_hu, model.title] if hu else [model.title]
+        return or_(*[_title_tsv(c).op("@@")(tsq) for c in cols])
+    if field == "people":
+        return func.to_tsvector(TS_CONFIG, func.coalesce(model.people_text, "")).op("@@")(tsq)
+    if field == "summary":
+        cols = [model.summary_hu, model.summary] if hu else [model.summary]
+        return or_(*[_summary_tsv(c).op("@@")(tsq) for c in cols])
+    return None
+
+
+def split_csv(v: str | None) -> list[str]:
+    return [s.strip() for s in v.split(",") if s.strip()] if v else []
+
+
+_ADDED_WINDOWS = {"24h": 1, "1w": 7, "1m": 30, "6m": 182, "1y": 365}
+
+
+def added_cutoff(within: str | None) -> datetime | None:
+    days = _ADDED_WINDOWS.get(within or "")
+    return datetime.now(timezone.utc) - timedelta(days=days) if days else None
+
+
+def meta_filter_conds(model, p: dict, lang: str = "en") -> list:
+    """The shared metadata-filter conditions (identical column names on plex_items + plex_shows) for
+    `p` (the request's filter params). Duration is movie-only, handled by the caller. Returned as a
+    list so faceted search can apply all-but-one group. DRY for browse, unified, and /facets.
+    Genre chips are language-specific strings, so they filter the active-language genre column."""
+    conds: list = []
+    gsel = split_csv(p.get("genres"))
+    if gsel:
+        gcol = genres_col(model, lang)
+        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:
+        conds.append(model.content_rating.in_(crs))
+    if p.get("year_min") is not None:
+        conds.append(model.year >= p["year_min"])
+    if p.get("year_max") is not None:
+        conds.append(model.year <= p["year_max"])
+    if p.get("rating_min") is not None:
+        # Filter by the SAME score the UI shows on the badge (IMDb preferred, audience fallback), so a
+        # ratingMin picked from a displayed IMDb score narrows the right column instead of the raw
+        # audience `rating`. Both are 0–10, so coalesce is scale-consistent.
+        conds.append(func.coalesce(model.imdb_rating, model.rating) >= p["rating_min"])
+    cutoff = added_cutoff(p.get("added_within"))
+    if cutoff is not None:
+        conds.append(model.added_at >= cutoff)
+    for d in split_csv(p.get("directors")):  # AND
+        conds.append(model.directors.contains([d]))
+    alist = split_csv(p.get("actors"))
+    if alist:  # AND (all) or OR (any) — default OR, mirroring genre_mode
+        ac = [model.cast_names.contains([a]) for a in alist]
+        conds.append(and_(*ac) if p.get("actor_mode") == "all" else or_(*ac))
+    stds = split_csv(p.get("studios"))
+    if stds:  # OR
+        conds.append(model.studio.in_(stds))
+    if p.get("collection"):
+        conds.append(model.collection_keys.contains([p["collection"]]))
+    return conds
+
+
+def apply_meta_filters(q, model, p: dict, lang: str = "en"):
+    conds = meta_filter_conds(model, p, lang)
+    return q.where(*conds) if conds else q
+
+
+@dataclass
+class LibraryFilters:
+    """The shared sidebar filter query-params for /library + /facets, declared once and injected via
+    ``Depends()``. `as_dict()` yields the `p` dict the query builders read; `duration_*` is included
+    for /facets' wsq but ignored by `meta_filter_conds` (both callers apply duration separately)."""
+
+    genres: str | None = None
+    genre_mode: str = "any"
+    content_ratings: str | None = None
+    year_min: int | None = None
+    year_max: int | None = None
+    rating_min: float | None = None
+    duration_min: int | None = None
+    duration_max: int | None = None
+    added_within: str | None = None
+    directors: str | None = None
+    actors: str | None = None
+    actor_mode: str = (
+        "any"  # how multiple actors combine: any (OR, default) | all (AND)
+    )
+    studios: str | None = None
+    collection: str | None = None
+
+    def as_dict(self) -> dict:
+        return {
+            "genres": self.genres,
+            "genre_mode": self.genre_mode,
+            "content_ratings": self.content_ratings,
+            "year_min": self.year_min,
+            "year_max": self.year_max,
+            "rating_min": self.rating_min,
+            "duration_min": self.duration_min,
+            "duration_max": self.duration_max,
+            "added_within": self.added_within,
+            "directors": self.directors,
+            "actors": self.actors,
+            "actor_mode": self.actor_mode,
+            "studios": self.studios,
+            "collection": self.collection,
+        }
+
+
+def like_escape(s: str) -> str:
+    return s.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+
+# --- Watch-state scope (shared by the /library grid AND the /facets aggregation) ---------------
+#
+# The `show` scope (all | watched | in_progress | unwatched) filters the browse result by per-user
+# watch state. The SAME predicate has to be applied in two places — `unified_library` (the grid) and
+# `facets.wsq` (so the facet counts reflect exactly the visible set) — and they MUST stay identical:
+# a hidden movie kept out of the grid must not inflate the facets either. These helpers are the one
+# home for that predicate so the two call sites can't drift (E3 S1; pinned by test_plex_facets_grid_
+# parity). Callers pass the already-joined state expressions, so this module stays model-agnostic:
+#   * movies — `st` is an aliased PlexState outer-joined on (item_id, user_id).
+#   * shows  — `tot`/`wat`/`inp` are the coalesced totals from `rollup.agg_subquery`.
+
+
+def movie_status_case(st):
+    """The per-movie status label (new | in_progress | watched) from its PlexState alias `st`."""
+    return case(
+        (st.status == "watched", "watched"),
+        (
+            and_(st.position_seconds > 0, or_(st.status.is_(None), st.status != "watched")),
+            "in_progress",
+        ),
+        else_="new",
+    )
+
+
+def show_status_case(tot, wat, inp):
+    """The per-show status label rolled up from its episodes' totals (total/watched/in-progress)."""
+    return case(
+        (and_(tot > 0, wat >= tot), "watched"),
+        (or_(wat > 0, inp > 0), "in_progress"),
+        else_="new",
+    )
+
+
+def apply_movie_state_filter(query, st, show: str):
+    """Restrict a movie query to the `show` scope via its PlexState alias `st`. The default (`all`)
+    excludes hidden movies — the exclusion that must match between grid and facets."""
+    if show == "watched":
+        return query.where(st.status == "watched")
+    if show == "in_progress":
+        return query.where(
+            st.position_seconds > 0, or_(st.status.is_(None), st.status != "watched")
+        )
+    if show == "unwatched":
+        return query.where(or_(st.status.is_(None), st.status.notin_(["watched", "hidden"])))
+    return query.where(or_(st.status.is_(None), st.status != "hidden"))
+
+
+def apply_show_state_filter(query, tot, wat, inp, show: str):
+    """Restrict a show query to the `show` scope via its rollup totals. `all` is a no-op (shows have
+    no hidden concept); the caller only joins the rollup for the three non-`all` scopes."""
+    if show == "watched":
+        return query.where(tot > 0, wat >= tot)
+    if show == "in_progress":
+        return query.where(or_(wat > 0, inp > 0), wat < tot)
+    if show == "unwatched":
+        return query.where(wat == 0, inp == 0)
+    return query

backend/app/plex/rollup.py

@@ -0,0 +1,78 @@
+"""Roll a show's episodes up into a single watch-state (new | in_progress | watched) + on-deck.
+
+Drives the show/season grid badges and the Resume / Play-from-start / mark-all buttons.
+"""
+
+from sqlalchemy import and_, case, func, or_, select
+from sqlalchemy.orm import Session, aliased
+
+from app.models import PlexItem, PlexState
+
+
+def show_status(total: int, watched: int, inprog: int) -> str:
+    """Roll a show's episodes up into a single watch state: fully watched, partially started, or new."""
+    if total and watched >= total:
+        return "watched"
+    if (watched or 0) > 0 or (inprog or 0) > 0:
+        return "in_progress"
+    return "new"
+
+
+def rollup(cards: list[dict]) -> dict:
+    """From ORDERED episode cards → the aggregate watch status, the "on deck" episode to Resume (the
+    last in-progress one, else the first unwatched), the first episode (for Play from the start), and
+    the episode count. Drives the show/season Resume + Play + mark-all buttons."""
+    total = len(cards)
+    watched = sum(1 for c in cards if c.get("status") == "watched")
+    inprog = [
+        c
+        for c in cards
+        if (c.get("position_seconds") or 0) > 0 and c.get("status") != "watched"
+    ]
+    resume = None
+    if inprog:
+        resume = inprog[-1]  # continue the latest-started episode
+    else:
+        resume = next((c for c in cards if c.get("status") != "watched"), None)
+    return {
+        "status": show_status(total, watched, len(inprog)),
+        "resume": resume,
+        "first": cards[0] if cards else None,
+        "episode_count": total,
+    }
+
+
+def agg_subquery(db: Session, user_id: int):
+    """Per-show episode counts for a user: total, watched, in-progress. Reused to (a) filter the show
+    grid by aggregate watch-state and (b) compute each card's badge."""
+    ps = aliased(PlexState)
+    return (
+        select(
+            PlexItem.show_id.label("show_id"),
+            func.count(PlexItem.id).label("total"),
+            func.count(case((ps.status == "watched", 1))).label("watched"),
+            func.count(
+                case(
+                    (
+                        and_(
+                            ps.position_seconds > 0,
+                            or_(ps.status.is_(None), ps.status != "watched"),
+                        ),
+                        1,
+                    )
+                )
+            ).label("inprog"),
+        )
+        .outerjoin(ps, and_(ps.item_id == PlexItem.id, ps.user_id == user_id))
+        .where(PlexItem.kind == "episode", PlexItem.show_id.isnot(None))
+        .group_by(PlexItem.show_id)
+    )
+
+
+def state_map(db: Session, user_id: int, show_ids: list[int]) -> dict[int, str]:
+    if not show_ids:
+        return {}
+    rows = db.execute(
+        agg_subquery(db, user_id).where(PlexItem.show_id.in_(show_ids))
+    ).all()
+    return {r.show_id: show_status(r.total, r.watched, r.inprog) for r in rows}

backend/app/plex/subtitles.py

@@ -0,0 +1,138 @@
+"""WebVTT conversion, HLS-clock time-shift, and on-disk cache for Plex subtitle streams.
+
+Text subtitles (embedded or external) are turned into WebVTT so the browser <track> can render them;
+bitmap subtitles (Blu-ray/DVD) can't be (would need burn-in). Converted VTTs are cached on the shared
+Plex on-disk cache root (``cache.CACHE_DIR``).
+"""
+
+import re
+import subprocess
+
+from app.plex.cache import CACHE_DIR
+from app.plex.client import PlexError
+
+# Image-based subtitle codecs (Blu-ray/DVD) — can't be turned into text WebVTT (would need burn-in).
+BITMAP_SUBS = {
+    "pgs",
+    "hdmv_pgs_subtitle",
+    "dvd_subtitle",
+    "dvdsub",
+    "vobsub",
+    "dvbsub",
+    "dvb_subtitle",
+}
+
+
+def srt_to_vtt(text: str) -> str:
+    """Minimal SubRip→WebVTT: add the header and switch the ms separator (`,`→`.`). SRT cue-index
+    lines are valid in WebVTT, so they're left as-is."""
+    body = re.sub(
+        r"(\d\d:\d\d:\d\d),(\d\d\d)", r"\1.\2", text.replace("\r\n", "\n").lstrip("")
+    )
+    return "WEBVTT\n\n" + body.strip() + "\n"
+
+
+def _vtt_ts_to_s(ts: str) -> float:
+    parts = ts.split(":")
+    h = "0" if len(parts) == 2 else parts[0]
+    m, rest = parts[-2], parts[-1]
+    sec, _, ms = rest.partition(".")
+    return int(h) * 3600 + int(m) * 60 + int(sec) + int(ms or 0) / 1000.0
+
+
+def _vtt_s_to_ts(x: float) -> str:
+    x = max(0.0, x)
+    h = int(x // 3600)
+    x -= h * 3600
+    m = int(x // 60)
+    x -= m * 60
+    s = int(x)
+    ms = int(round((x - s) * 1000))
+    if ms >= 1000:
+        s += 1
+        ms -= 1000
+    return f"{h:02d}:{m:02d}:{s:02d}.{ms:03d}"
+
+
+def shift_vtt(vtt: str, offset: float) -> str:
+    """Subtract `offset` seconds from every cue's start/end. WebVTT cues carry ABSOLUTE content times,
+    but an HLS remux session's clock is zero-based at the real keyframe (see stream.py media_start_s),
+    so a subtitle overlaid on that session must be shifted by that offset to line up with speech.
+
+    Processes cue BLOCKS so a cue that shifts fully into the past (end <= 0) can be DROPPED entirely.
+    (Collapsing them to 00:00:00.000-->00:00:00.000 made EVERY past cue count as active at currentTime 0
+    — where a resume/seek lands — piling all of them on screen until playback advanced past 0.) A cue
+    straddling 0 is clamped to start at 0."""
+    if not offset:
+        return vtt
+    out_blocks: list[str] = []
+    for block in re.split(r"\n[ \t]*\n", vtt):
+        if "-->" not in block:
+            out_blocks.append(block)  # header / NOTE / STYLE — keep verbatim
+            continue
+        lines = block.split("\n")
+        keep = True
+        for i, ln in enumerate(lines):
+            if "-->" not in ln:
+                continue
+            left, _, right = ln.partition("-->")
+            rparts = right.strip().split(None, 1)
+            settings = (" " + rparts[1]) if len(rparts) > 1 else ""
+            try:
+                st = _vtt_ts_to_s(left.strip()) - offset
+                en = _vtt_ts_to_s(rparts[0]) - offset
+            except (ValueError, IndexError):
+                break  # unparseable timing → leave the block as-is
+            if en <= 0:
+                keep = False  # whole cue is before the session start → drop the block
+            else:
+                lines[i] = (
+                    f"{_vtt_s_to_ts(st)} --> {_vtt_s_to_ts(en)}{settings}"  # _vtt_s_to_ts clamps st>=0
+                )
+            break
+        if keep:
+            out_blocks.append("\n".join(lines))
+    return "\n\n".join(out_blocks)
+
+
+def ffmpeg_to_vtt(src: str, sub_ord: int | None) -> str:
+    """Convert one subtitle stream of a file to WebVTT via ffmpeg (for embedded subs, and non-SRT
+    external subs written to a temp file). `sub_ord` = ordinal among the file's subtitle streams."""
+    cmd = [
+        "ffmpeg",
+        "-nostdin",
+        "-loglevel",
+        "error",
+        "-i",
+        src,
+        "-map",
+        f"0:s:{sub_ord if sub_ord is not None else 0}",
+        "-f",
+        "webvtt",
+        "pipe:1",
+    ]
+    r = subprocess.run(cmd, capture_output=True)
+    if r.returncode != 0 or not r.stdout:
+        raise PlexError(
+            (r.stderr or b"").decode("utf-8", "replace")[:200]
+            or "ffmpeg subtitle convert failed"
+        )
+    return r.stdout.decode("utf-8", "replace")
+
+
+def cache_read(key: str) -> str | None:
+    try:
+        p = CACHE_DIR / f"{key}.vtt"
+        return p.read_text(encoding="utf-8") if p.exists() else None
+    except OSError:
+        return None
+
+
+def cache_write(key: str, vtt: str) -> None:
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        tmp = CACHE_DIR / f"{key}.vtt.tmp"
+        tmp.write_text(vtt, encoding="utf-8")
+        tmp.replace(CACHE_DIR / f"{key}.vtt")  # atomic publish
+    except OSError:
+        pass

backend/app/plex/sync.py

@@ -5,19 +5,26 @@ Playback is from the local physical file, so this only mirrors METADATA + the ph
 (no ffprobe needed) to classify each item's browser playability. Movies + episodes become playable
 LEAF rows (plex_items); shows/seasons are mirrored for the drill-down + episode ordering.
 
-The sync is a full reconcile of the enabled sections (upsert by rating_key). Pruning of items that
+The sync is a full reconcile of the enabled sections (upsert by rating_key) AND prunes rows for
-disappeared from Plex is intentionally left for later (a follow-up can diff rating_keys per library).
+titles that disappeared from Plex: each section diffs the rating_keys it just listed against the ones
-Cast + intro/credit markers are fetched lazily on the item-detail/player path (P2), not here.
+stored, and deletes the stale ones (their watch-state / playlist links cascade). The prune is guarded
+on a NON-empty listing — a section that returns zero items is left untouched, so a transient Plex
+glitch that yields an empty page can't wipe a library (the metadata is cheap to re-sync; an accidental
+mass-delete is the only real risk). Library-level reconcile (dropping a whole removed section, the
+dead `enabled` column) is a separate follow-up. Cast + intro/credit markers are fetched lazily on the
+item-detail/player path (P2), not here.
 """
 import logging
 from datetime import datetime, timezone
 
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app import sysconfig
 from app.models import PlexCollection, PlexItem, PlexLibrary, PlexSeason, PlexShow
-from app.plex import people
+from app.plex import detail, people
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+from app.plex.lookups import by_rating_key
 
 log = logging.getLogger("siftlode.plex")
 
@@ -80,6 +87,26 @@ def _rating(meta: dict) -> float | None:
         return None
 
 
+# Provider preference for the canonical guid (a stable id shared across a title's language twins).
+_GUID_PREFERENCE = ("tmdb", "imdb", "tvdb")
+
+
+def _canonical_guid(meta: dict) -> str | None:
+    """The canonical external id used to pair an EN title with its HU-overlay twin (E5 S5). Reads the
+    `Guid` array (present only with includeGuids=1 in the listing), preferring tmdb > imdb > tvdb,
+    normalised to '<provider>:<id>' (e.g. 'tmdb:12345'). None when no known provider id is present."""
+    found: dict[str, str] = {}
+    for g in meta.get("Guid") or []:
+        raw = str(g.get("id") or "")
+        for prov in _GUID_PREFERENCE:
+            if raw.startswith(f"{prov}://"):
+                found.setdefault(prov, f"{prov}:{raw.split('://', 1)[1]}")
+    for prov in _GUID_PREFERENCE:
+        if prov in found:
+            return found[prov]
+    return None
+
+
 def _media_facts(meta: dict) -> dict:
     media = meta.get("Media") or []
     if not media:
@@ -108,21 +135,48 @@ def _enabled_section_keys(db: Session) -> set[str] | None:
     return keys or None
 
 
+def _overlay_map(db: Session) -> dict[str, str]:
+    """The configured HU-overlay pairing: {huSectionKey: enSectionKey} from `plex_overlay_map`
+    ('huKey:enKey,...'). Each HU section is synced as a non-browsable overlay onto its EN twin.
+    Malformed pairs are skipped."""
+    raw = sysconfig.get_str(db, "plex_overlay_map")
+    out: dict[str, str] = {}
+    for pair in raw.split(","):
+        hu, sep, en = pair.partition(":")
+        hu, en = hu.strip(), en.strip()
+        if sep and hu and en:
+            out[hu] = en
+    return out
+
+
 def sync(db: Session) -> dict:
     """Full reconcile of the enabled movie/show sections. Returns a small stats dict."""
     if not sysconfig.get_bool(db, "plex_enabled"):
         return {"skipped": "disabled"}
-    stats = {"libraries": 0, "movies": 0, "shows": 0, "seasons": 0, "episodes": 0, "collections": 0}
+    stats = {
+        "libraries": 0, "movies": 0, "shows": 0, "seasons": 0, "episodes": 0,
+        "collections": 0, "overlaid": 0, "pruned": 0,
+    }
     wanted = _enabled_section_keys(db)
+    overlay_map = _overlay_map(db)  # {huKey: enKey}
+    overlay_keys = set(overlay_map)
     try:
         with PlexClient(db) as plex:
-            for s in plex.sections():
+            sections = {
-                if s.get("type") not in ("movie", "show"):
+                str(s.get("key")): s
+                for s in plex.sections()
+                if s.get("type") in ("movie", "show")
+            }
+            libs_by_key: dict[str, PlexLibrary] = {}
+            # Pass 1 — browsable (non-overlay) sections. HU-overlay sections are handled in pass 2 and
+            # are NEVER mirrored as browsable libraries of their own.
+            for key, s in sections.items():
+                if key in overlay_keys:
                     continue
-                key = str(s.get("key"))
                 if wanted is not None and key not in wanted:
                     continue
                 lib = _upsert_library(db, key, s.get("title") or key, s.get("type"))
+                libs_by_key[key] = lib
                 stats["libraries"] += 1
                 if s.get("type") == "movie":
                     _sync_movies(db, plex, lib, stats)
@@ -133,6 +187,24 @@ def sync(db: Session) -> dict:
                 # libraries already mirrored (idempotent — the next run reconciles the rest), instead
                 # of the old single end-of-loop commit that a late failure rolled back entirely.
                 db.commit()
+            # Pass 2 — HU overlays. The EN twins are now synced (with guids), so write each overlay
+            # section's Hungarian metadata onto the matched EN rows. Requires the EN section to have been
+            # synced in pass 1 (in the allowlist / all) and to share the overlay's kind.
+            for hu_key, en_key in overlay_map.items():
+                s = sections.get(hu_key)
+                en_lib = libs_by_key.get(en_key)
+                if s is None or en_lib is None or s.get("type") != en_lib.kind:
+                    log.warning(
+                        "Plex overlay skipped: hu=%s en=%s (missing section/EN lib or kind mismatch)",
+                        hu_key, en_key,
+                    )
+                    continue
+                lib = _upsert_library(db, hu_key, s.get("title") or hu_key, s.get("type"))
+                lib.metadata_lang = "hu"
+                lib.overlay_of = en_lib.id
+                db.flush()
+                _sync_overlay(db, plex, lib, en_lib.id, stats)
+                db.commit()
             # Rich-fetch a bounded batch of not-yet-enriched titles' FULL cast, so the whole library
             # becomes filterable over successive runs (the cheap listing above only stored the top ~3).
             try:
@@ -165,20 +237,20 @@ def _enrich_people_batch(db: Session, plex: PlexClient, limit: int = _ENRICH_BAT
     shared enrich_row_people). Oldest-id first, movies before shows. Stamps people_enriched_at only on
     a SUCCESSFUL fetch, so a transient per-item failure retries next run rather than being lost.
     Returns how many items were enriched this run."""
-    movies = (
+    movies = db.execute(
-        db.query(PlexItem)
+        select(PlexItem)
-        .filter(PlexItem.kind == "movie", PlexItem.people_enriched_at.is_(None))
+        .where(PlexItem.kind == "movie", PlexItem.people_enriched_at.is_(None))
         .order_by(PlexItem.id)
         .limit(limit)
-        .all()
+    ).scalars().all()
-    )
     remaining = limit - len(movies)
     shows = (
-        db.query(PlexShow)
+        db.execute(
-        .filter(PlexShow.people_enriched_at.is_(None))
+            select(PlexShow)
-        .order_by(PlexShow.id)
+            .where(PlexShow.people_enriched_at.is_(None))
-        .limit(remaining)
+            .order_by(PlexShow.id)
-        .all()
+            .limit(remaining)
+        ).scalars().all()
         if remaining > 0
         else []
     )
@@ -191,6 +263,7 @@ def _enrich_people_batch(db: Session, plex: PlexClient, limit: int = _ENRICH_BAT
             log.debug("Plex people enrich fetch failed for %s: %s", row.rating_key, e)
             continue  # leave people_enriched_at NULL so it's retried on a later run
         people.enrich_row_people(db, row, people.cast_from_meta(meta))
+        detail.apply_rich_detail(row, meta)  # imdb/tagline/full_cast → served from the row, not live
         row.people_enriched_at = now
         n += 1
     db.commit()
@@ -198,7 +271,9 @@ def _enrich_people_batch(db: Session, plex: PlexClient, limit: int = _ENRICH_BAT
 
 
 def _upsert_library(db: Session, key: str, title: str, kind: str) -> PlexLibrary:
-    lib = db.query(PlexLibrary).filter_by(plex_key=key).first()
+    lib = db.execute(
+        select(PlexLibrary).where(PlexLibrary.plex_key == key)
+    ).scalars().first()
     if lib is None:
         lib = PlexLibrary(plex_key=key)
         db.add(lib)
@@ -209,8 +284,14 @@ def _upsert_library(db: Session, key: str, title: str, kind: str) -> PlexLibrary
     return lib
 
 
-def _paginate(plex: PlexClient, key: str, item_type: int):
+def _paginate(plex: PlexClient, key: str, item_type: int, progress: dict | None = None):
+    """Yield a section's items page by page. If `progress` is given, set `progress["complete"]` True
+    ONLY when the walk reached the server's reported `total` — a truncated fetch (an empty/short page
+    mid-sequence, e.g. a transient Plex hiccup, before `total` is reached) leaves it False so the
+    caller can skip pruning. Pruning on a partial listing would delete rows the listing merely failed
+    to mention (the metadata is re-syncable, but that still cascades watch-state)."""
     start = 0
+    total = None
     while True:
         items, total = plex.section_items(key, item_type, start, _PAGE)
         if not items:
@@ -222,6 +303,15 @@ def _paginate(plex: PlexClient, key: str, item_type: int):
             break
         if len(items) < _PAGE:
             break
+    if progress is not None:
+        # A truthy `total` we reached = a trustworthy complete listing. `total` unknown/zero-with-rows
+        # (a Plex that doesn't report totalSize) is treated as NOT complete, so prune stays conservative.
+        progress["complete"] = bool(total) and start >= total
+
+
+# The section listing exposes at most the top ~20 cast (Plex's own cap); a stored cast longer than this
+# can only have come from the rich enrich, never the listing.
+_LISTING_CAST_CAP = 20
 
 
 def _apply_facet_fields(row, meta: dict) -> None:
@@ -234,7 +324,20 @@ def _apply_facet_fields(row, meta: dict) -> None:
     row.originally_available_at = _date(meta.get("originallyAvailableAt"))
     row.genres = _tags(meta, "Genre")
     row.directors = _tags(meta, "Director")
-    row.cast_names = _tags(meta, "Role", limit=20)
+    # The listing carries only the top ~20 cast, so re-applying it would DOWNGRADE an already-enriched
+    # full cast (up to 24, grown by the rich backfill/info-page enrich), silently breaking the
+    # person-page cast filter for names past the top ~20. The watermark gate below (`people_enriched_at
+    # is None`) normally protects this, but it is NOT enough on its own: a migration that resets the
+    # watermark re-opens the regression (0065 nulled it, which is exactly how the S5b fix got undone in
+    # prod). So guard STRUCTURALLY too, by LENGTH against the listing cap: a stored cast LONGER than the
+    # cap can only be an enriched fuller list, so keep it (robust to any watermark reset). A stored cast
+    # at or below the cap is itself listing-sourced, so take the fresh listing — which tracks Plex cast
+    # EDITS in EITHER direction (comparing against this listing's length instead would silently keep a
+    # stale longer cast when Plex TRIMS one).
+    if row.people_enriched_at is None:
+        listing_cast = _tags(meta, "Role", limit=_LISTING_CAST_CAP)
+        if len(row.cast_names or []) <= _LISTING_CAST_CAP:
+            row.cast_names = listing_cast
     people = list(dict.fromkeys((row.directors or []) + (row.cast_names or [])))
     row.people_text = " ".join(people) or None
 
@@ -242,6 +345,9 @@ def _apply_facet_fields(row, meta: dict) -> None:
 def _apply_item(row: PlexItem, lib_id: int, kind: str, meta: dict) -> None:
     row.library_id = lib_id
     row.kind = kind
+    # EN<->HU pairing key (movies; harmless/unused on episodes). Keep the prior guid if this listing
+    # carries none (a server ignoring includeGuids mustn't wipe the overlay's only match key).
+    row.guid = _canonical_guid(meta) or row.guid
     row.title = (meta.get("title") or "").strip() or "Untitled"
     row.summary = meta.get("summary")
     row.year = meta.get("year")
@@ -260,9 +366,34 @@ def _apply_item(row: PlexItem, lib_id: int, kind: str, meta: dict) -> None:
     row.playable = classify_playable(mf.get("codec_video"), mf.get("codec_audio"), mf.get("container"))
 
 
+def _prune_stale(
+    db: Session, existing: dict, seen: set[str], stats: dict, *, complete: bool
+) -> None:
+    """Delete stored rows whose rating_key is no longer in the freshly-listed `seen` set — the titles
+    that disappeared from Plex (their watch-state / playlist links cascade via the FKs). GUARDED on a
+    COMPLETE, non-empty listing: a truncated fetch (`complete` False — a mid-sequence empty/short page
+    before the server's total) or a zero-item listing prunes NOTHING, so a transient Plex hiccup can
+    never wipe a library over rows it merely failed to list. Callers pass the rating_key -> row map
+    they already built for the upsert."""
+    if not complete or not seen:
+        return
+    for rk, row in existing.items():
+        if rk not in seen:
+            db.delete(row)
+            stats["pruned"] = stats.get("pruned", 0) + 1
+    db.flush()
+
+
 def _sync_movies(db: Session, plex: PlexClient, lib: PlexLibrary, stats: dict) -> None:
-    existing = {r.rating_key: r for r in db.query(PlexItem).filter_by(library_id=lib.id, kind="movie")}
+    existing = {
-    for meta in _paginate(plex, lib.plex_key, _TYPE_MOVIE):
+        r.rating_key: r
+        for r in db.execute(
+            select(PlexItem).where(PlexItem.library_id == lib.id, PlexItem.kind == "movie")
+        ).scalars()
+    }
+    seen: set[str] = set()
+    progress: dict = {}
+    for meta in _paginate(plex, lib.plex_key, _TYPE_MOVIE, progress):
         rk = str(meta.get("ratingKey") or "")
         if not rk:
             continue
@@ -270,22 +401,33 @@ def _sync_movies(db: Session, plex: PlexClient, lib: PlexLibrary, stats: dict) -
         if row.id is None:
             db.add(row)
         _apply_item(row, lib.id, "movie", meta)
+        seen.add(rk)
         stats["movies"] += 1
     db.flush()
+    _prune_stale(db, existing, seen, stats, complete=progress.get("complete", False))
 
 
 def _sync_shows(db: Session, plex: PlexClient, lib: PlexLibrary, stats: dict) -> None:
     # 1) shows
-    shows = {r.rating_key: r for r in db.query(PlexShow).filter_by(library_id=lib.id)}
+    shows = {
-    for meta in _paginate(plex, lib.plex_key, _TYPE_SHOW):
+        r.rating_key: r
+        for r in db.execute(
+            select(PlexShow).where(PlexShow.library_id == lib.id)
+        ).scalars()
+    }
+    shows_seen: set[str] = set()
+    shows_progress: dict = {}
+    for meta in _paginate(plex, lib.plex_key, _TYPE_SHOW, shows_progress):
         rk = str(meta.get("ratingKey") or "")
         if not rk:
             continue
+        shows_seen.add(rk)
         sh = shows.get(rk) or PlexShow(rating_key=rk)
         if sh.id is None:
             db.add(sh)
             shows[rk] = sh
         sh.library_id = lib.id
+        sh.guid = _canonical_guid(meta) or sh.guid  # EN<->HU pairing key; keep prior if listing has none
         sh.title = (meta.get("title") or "").strip() or "Untitled"
         sh.summary = meta.get("summary")
         sh.year = meta.get("year")
@@ -299,12 +441,20 @@ def _sync_shows(db: Session, plex: PlexClient, lib: PlexLibrary, stats: dict) ->
     show_id = {rk: sh.id for rk, sh in shows.items()}
 
     # 2) seasons
-    seasons = {r.rating_key: r for r in db.query(PlexSeason).join(PlexShow).filter(PlexShow.library_id == lib.id)}
+    seasons = {
-    for meta in _paginate(plex, lib.plex_key, _TYPE_SEASON):
+        r.rating_key: r
+        for r in db.execute(
+            select(PlexSeason).join(PlexShow).where(PlexShow.library_id == lib.id)
+        ).scalars()
+    }
+    seasons_seen: set[str] = set()
+    seasons_progress: dict = {}
+    for meta in _paginate(plex, lib.plex_key, _TYPE_SEASON, seasons_progress):
         rk = str(meta.get("ratingKey") or "")
         sid = show_id.get(str(meta.get("parentRatingKey") or ""))
         if not rk or sid is None:
             continue
+        seasons_seen.add(rk)
         se = seasons.get(rk) or PlexSeason(rating_key=rk)
         if se.id is None:
             db.add(se)
@@ -318,11 +468,19 @@ def _sync_shows(db: Session, plex: PlexClient, lib: PlexLibrary, stats: dict) ->
     season_id = {rk: se.id for rk, se in seasons.items()}
 
     # 3) episodes (playable leaves)
-    episodes = {r.rating_key: r for r in db.query(PlexItem).filter_by(library_id=lib.id, kind="episode")}
+    episodes = {
-    for meta in _paginate(plex, lib.plex_key, _TYPE_EPISODE):
+        r.rating_key: r
+        for r in db.execute(
+            select(PlexItem).where(PlexItem.library_id == lib.id, PlexItem.kind == "episode")
+        ).scalars()
+    }
+    episodes_seen: set[str] = set()
+    episodes_progress: dict = {}
+    for meta in _paginate(plex, lib.plex_key, _TYPE_EPISODE, episodes_progress):
         rk = str(meta.get("ratingKey") or "")
         if not rk:
             continue
+        episodes_seen.add(rk)
         row = episodes.get(rk) or PlexItem(rating_key=rk)
         if row.id is None:
             db.add(row)
@@ -334,6 +492,66 @@ def _sync_shows(db: Session, plex: PlexClient, lib: PlexLibrary, stats: dict) ->
         stats["episodes"] += 1
     db.flush()
 
+    # Prune leaf-first (episodes -> seasons -> shows) so a stale row is deleted directly, before its
+    # parent's cascade would reach it — avoids deleting the same ORM object twice. Each level is
+    # independently guarded on a non-empty listing by _prune_stale.
+    _prune_stale(db, episodes, episodes_seen, stats, complete=episodes_progress.get("complete", False))
+    _prune_stale(db, seasons, seasons_seen, stats, complete=seasons_progress.get("complete", False))
+    _prune_stale(db, shows, shows_seen, stats, complete=shows_progress.get("complete", False))
+
+
+def _sync_overlay(
+    db: Session, plex: PlexClient, lib: PlexLibrary, en_lib_id: int, stats: dict
+) -> None:
+    """Write an overlay section's Hungarian metadata onto its EN twin's rows, matched by guid. Creates
+    NO browsable rows — an overlay library is never listed on its own. Only title/summary/genres differ
+    by language; the language-neutral people_text feeds both search vectors.
+
+    This is a full RECONCILE: every guid-bearing EN row's HU fields are cleared first, then the HU
+    section repopulates the matches — so an EN row whose HU twin vanished (or was re-guid'd) falls back
+    to EN instead of keeping stale Hungarian metadata. HU items with no EN match are skipped."""
+    if lib.kind == "movie":
+        rows = db.execute(
+            select(PlexItem).where(
+                PlexItem.library_id == en_lib_id,
+                PlexItem.kind == "movie",
+                PlexItem.guid.is_not(None),
+            )
+        ).scalars()
+        item_type = _TYPE_MOVIE
+    else:
+        rows = db.execute(
+            select(PlexShow).where(
+                PlexShow.library_id == en_lib_id, PlexShow.guid.is_not(None)
+            )
+        ).scalars()
+        item_type = _TYPE_SHOW
+    # guid -> the EN rows carrying it (a list: two editions of one film can share a guid; both overlay).
+    by_guid: dict[str, list] = {}
+    for r in rows:
+        by_guid.setdefault(r.guid, []).append(r)
+    # Reconcile step: clear HU fields on all guid-bearing rows. Only rows that actually held HU data
+    # become dirty (SQLAlchemy skips a no-net-change UPDATE), so this is cheap; matches are re-set below.
+    for group in by_guid.values():
+        for row in group:
+            row.title_hu = row.summary_hu = row.genres_hu = None
+    seen: set[str] = set()  # first HU entry for a guid wins; a dup HU item can't overwrite or double-count
+    for meta in _paginate(plex, lib.plex_key, item_type):
+        g = _canonical_guid(meta)
+        targets = by_guid.get(g) if g else None
+        if not targets or g in seen:
+            continue
+        seen.add(g)
+        title_hu = (meta.get("title") or "").strip() or None
+        summary_hu = meta.get("summary")
+        genres_hu = _tags(meta, "Genre")
+        for row in targets:
+            row.title_hu = title_hu
+            row.summary_hu = summary_hu
+            row.genres_hu = genres_hu
+        stats["overlaid"] = stats.get("overlaid", 0) + 1
+    db.flush()
+
 
 def _upsert_collection(
     db: Session, existing: PlexCollection | None, rk: str, lib_id: int, meta: dict
@@ -359,17 +577,21 @@ def resync_collection(db: Session, plex: PlexClient, lib: PlexLibrary, rk: str)
     collection's membership on the affected member rows."""
     meta = plex.metadata(rk) or {}
     col = _upsert_collection(
-        db, db.query(PlexCollection).filter_by(rating_key=rk).first(), rk, lib.id, meta
+        db, by_rating_key(db, PlexCollection, rk), rk, lib.id, meta
     )
     Model = PlexItem if lib.kind == "movie" else PlexShow
     new_members = {str(c.get("ratingKey")) for c in plex.collection_children(rk) if c.get("ratingKey")}
-    current = db.query(Model).filter(Model.collection_keys.contains([rk])).all()
+    current = db.execute(
+        select(Model).where(Model.collection_keys.contains([rk]))
+    ).scalars().all()
     for row in current:  # drop rk from rows that are no longer members
         if row.rating_key not in new_members:
             row.collection_keys = [k for k in (row.collection_keys or []) if k != rk] or None
     to_add = new_members - {r.rating_key for r in current}
     if to_add:
-        for row in db.query(Model).filter(Model.rating_key.in_(to_add)):
+        for row in db.execute(
+            select(Model).where(Model.rating_key.in_(to_add))
+        ).scalars():
             row.collection_keys = list(dict.fromkeys([*(row.collection_keys or []), rk]))
     db.flush()
     return col
@@ -378,9 +600,11 @@ def resync_collection(db: Session, plex: PlexClient, lib: PlexLibrary, rk: str)
 def delete_collection_local(db: Session, lib: PlexLibrary, rk: str) -> None:
     """Local cleanup after a collection is deleted from Plex: strip rk from members + drop the row."""
     Model = PlexItem if lib.kind == "movie" else PlexShow
-    for row in db.query(Model).filter(Model.collection_keys.contains([rk])):
+    for row in db.execute(
+        select(Model).where(Model.collection_keys.contains([rk]))
+    ).scalars():
         row.collection_keys = [k for k in (row.collection_keys or []) if k != rk] or None
-    col = db.query(PlexCollection).filter_by(rating_key=rk).first()
+    col = by_rating_key(db, PlexCollection, rk)
     if col is not None:
         db.delete(col)
     db.flush()
@@ -391,7 +615,12 @@ def _sync_collections(db: Session, plex: PlexClient, lib: PlexLibrary, stats: di
     written as `collection_keys` on member movies (plex_items) / shows (plex_shows). A full reconcile:
     collections gone from Plex are pruned, and each member row's keys are rebuilt from scratch."""
     cols = plex.collections(lib.plex_key)
-    existing = {c.rating_key: c for c in db.query(PlexCollection).filter_by(library_id=lib.id)}
+    existing = {
+        c.rating_key: c
+        for c in db.execute(
+            select(PlexCollection).where(PlexCollection.library_id == lib.id)
+        ).scalars()
+    }
     seen: set[str] = set()
     membership: dict[str, list[str]] = {}  # member rating_key -> [collection rating_key, ...]
     for meta in cols:
@@ -410,8 +639,8 @@ def _sync_collections(db: Session, plex: PlexClient, lib: PlexLibrary, stats: di
         if rk not in seen:
             db.delete(col)
     # Rebuild collection_keys on every member row of this library (clear + set).
-    for row in db.query(PlexItem).filter_by(library_id=lib.id):
+    for row in db.execute(select(PlexItem).where(PlexItem.library_id == lib.id)).scalars():
         row.collection_keys = membership.get(row.rating_key) or None
-    for row in db.query(PlexShow).filter_by(library_id=lib.id):
+    for row in db.execute(select(PlexShow).where(PlexShow.library_id == lib.id)).scalars():
         row.collection_keys = membership.get(row.rating_key) or None
     db.flush()

backend/app/plex/watch_sync.py

@@ -16,7 +16,7 @@ history + onDeck, last-write-wins) build on this and land in later ships.
 import logging
 from datetime import datetime, timedelta, timezone
 
-from sqlalchemy import func
+from sqlalchemy import func, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
@@ -61,7 +61,10 @@ def _plex_watch_to_state(
 
 def _rk_to_id(db: Session) -> dict[str, int]:
     """The rating_key → PlexItem.id lookup used to resolve a Plex leaf back to its mirrored row."""
-    return {rk: iid for rk, iid in db.query(PlexItem.rating_key, PlexItem.id)}
+    return {
+        rk: iid
+        for rk, iid in db.execute(select(PlexItem.rating_key, PlexItem.id)).all()
+    }
 
 
 def _scan_plex_states(
@@ -162,7 +165,9 @@ def link_for_push(db: Session, user_id: int) -> PlexLink | None:
     """The active owner watch-push link for this user, or None when push is off / not the owner.
     Push is gated on `initial_import_done` so we never push a half-known local state over Plex's
     authoritative one before the one-time "Plex is master" import has reconciled them."""
-    link = db.query(PlexLink).filter_by(user_id=user_id).first()
+    link = db.execute(
+        select(PlexLink).where(PlexLink.user_id == user_id)
+    ).scalars().first()
     if link and link.uses_admin and link.sync_enabled and link.initial_import_done:
         return link
     return None
@@ -217,7 +222,11 @@ def push_state_to_plex(
         # Flag the row synced — but an "unwatched" via status=new deletes the row, so there may be
         # nothing to flag; that's fine (unscrobble still happened). Skip the flag if the row was
         # re-edited since we captured `expect_ts` (leave it dirty for its own push / the reconcile).
-        st = db.query(PlexState).filter_by(user_id=user_id, item_id=item_id).first()
+        st = db.execute(
+            select(PlexState).where(
+                PlexState.user_id == user_id, PlexState.item_id == item_id
+            )
+        ).scalars().first()
         if st is not None and _row_matches(st, expect_ts):
             st.synced_to_plex = True
             db.commit()
@@ -272,9 +281,11 @@ def push_bulk_state_to_plex(user_id: int, changes: list[tuple[int, str, str]]) -
         # Flag every successfully-pushed row that still exists (an "unwatched" deletes the row, so
         # only the "watched" changes have a row to flag).
         if synced_ids:
-            db.query(PlexState).filter(
+            db.execute(
-                PlexState.user_id == user_id, PlexState.item_id.in_(synced_ids)
+                update(PlexState)
-            ).update({PlexState.synced_to_plex: True}, synchronize_session=False)
+                .where(PlexState.user_id == user_id, PlexState.item_id.in_(synced_ids))
+                .values(synced_to_plex=True)
+            )
             db.commit()
 
 
@@ -290,11 +301,13 @@ _LWW_TOLERANCE_S = 90
 def _active_sync_links(db: Session) -> list[PlexLink]:
     """Every link with two-way sync actually running (owner MVP = one row). Iterated uniformly so
     P5b friend links slot in later without touching this loop."""
-    return (
+    return db.execute(
-        db.query(PlexLink)
+        select(PlexLink).where(
-        .filter_by(uses_admin=True, sync_enabled=True, initial_import_done=True)
+            PlexLink.uses_admin.is_(True),
-        .all()
+            PlexLink.sync_enabled.is_(True),
-    )
+            PlexLink.initial_import_done.is_(True),
+        )
+    ).scalars().all()
 
 
 def _resolve_account_id(db: Session, plex: PlexClient, link: PlexLink) -> int:
@@ -340,7 +353,11 @@ def _pull_apply(
     """Bring one Plex-side positive signal into Siftlode under last-write-wins. Returns
     "watched"/"in_progress" if it changed the row, else None. Never clears a row (un-watch is the
     full reconcile's job) — this only pulls in watched/resume."""
-    st = db.query(PlexState).filter_by(user_id=user_id, item_id=item_id).first()
+    st = db.execute(
+        select(PlexState).where(
+            PlexState.user_id == user_id, PlexState.item_id == item_id
+        )
+    ).scalars().first()
     if _same_state(st, status, pos):
         if st is not None and not st.synced_to_plex:
             st.synced_to_plex = True  # already matches Plex → just settle the flag, no churn
@@ -368,17 +385,18 @@ def _repush_dirty(db: Session, plex: PlexClient, link: PlexLink) -> int:
     # re-push doesn't need an extra per-item plex.metadata() round-trip just to fill set_timeline's
     # duration argument.
     info_by_id: dict[int, tuple[str, int | None]] = {
-        iid: (rk, dur) for iid, rk, dur in db.query(PlexItem.id, PlexItem.rating_key, PlexItem.duration_s)
+        iid: (rk, dur)
+        for iid, rk, dur in db.execute(
+            select(PlexItem.id, PlexItem.rating_key, PlexItem.duration_s)
+        ).all()
     }
-    dirty = (
+    dirty = db.execute(
-        db.query(PlexState)
+        select(PlexState).where(
-        .filter(
             PlexState.user_id == link.user_id,
             PlexState.synced_to_plex.is_(False),
             PlexState.status != "hidden",
         )
-        .all()
+    ).scalars().all()
-    )
     n = 0
     for st in dirty:
         info = info_by_id.get(st.item_id)
@@ -477,7 +495,9 @@ def run_plex_watch_reconcile(db: Session) -> dict:
 
                 # Siftlode rows Plex no longer has a record for: clear the ones that were mirrored
                 # (Plex un-watched them); leave hidden + dirty (dirty gets re-pushed just below).
-                for st in db.query(PlexState).filter_by(user_id=link.user_id).all():
+                for st in db.execute(
+                    select(PlexState).where(PlexState.user_id == link.user_id)
+                ).scalars().all():
                     if st.item_id in plex_states or st.status == "hidden":
                         continue
                     if st.synced_to_plex:

backend/app/quota.py

@@ -118,6 +118,20 @@ def can_spend(db: Session, units: int) -> bool:
     return remaining_today(db) >= units
 
 
+def backfill_reserve_reached() -> bool:
+    """True when today's remaining budget is at or below the backfill reserve — the shared yield
+    condition for every backfill/explore path (recent, deep, immediate full-history, explore, and
+    rolling revalidation).
+
+    Reads in its OWN short-lived session (like record_usage / log_action), for two reasons: it
+    replaces the remaining/reserve comparison that was open-coded at every call site, and — critically
+    for the per-page guards in paging loops — a guard must not hold the caller's transaction open
+    across the network fetch that follows it. Quota is committed independently of any caller, so a
+    fresh session reads the same numbers."""
+    with SessionLocal() as qs:
+        return remaining_today(qs) <= sysconfig.get_int(qs, "backfill_quota_reserve")
+
+
 def log_action(user_id: int, action: str) -> None:
     """Record a zero-cost action event so per-user daily caps still count it.
 

backend/app/routes/admin.py

@@ -4,7 +4,7 @@ from datetime import datetime, timezone
 
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
 from pydantic import BaseModel
-from sqlalchemy import delete, func, select
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app import audit
@@ -18,16 +18,13 @@ from app.auth import (
     purge_user,
 )
 from app.db import get_db
+from app.demo import reset_demo_state
 from app.models import (
     DemoWhitelist,
     Invite,
-    Playlist,
-    PlaylistItem,
-    Subscription,
     User,
-    Video,
-    VideoState,
 )
+from app.routes.auth import revoke_preset_password_if_unverified
 from app.utils import iso, valid_email
 
 router = APIRouter(prefix="/api/admin", tags=["admin"])
@@ -66,6 +63,10 @@ def _activate_user_by_email(db: Session, email: str) -> None:
     it can sign in. No-op if no such user exists yet (a Google user is created at first login)."""
     user = db.execute(select(User).where(User.email == email.lower())).scalar_one_or_none()
     if user is not None and not user.is_active:
+        # SEC-10: same guard as the Google-adoption path — approving an account whose email was never
+        # verified must not hand a working login to a password set on it by whoever registered the
+        # address (a pre-emption). Shared single-source helper so the two paths can't drift.
+        revoke_preset_password_if_unverified(user)
         user.is_active = True
         db.commit()
 
@@ -74,6 +75,12 @@ def _decide(db: Session, invite_id: int, admin: User, approved: bool) -> Invite:
     inv = db.get(Invite, invite_id)
     if inv is None:
         raise HTTPException(status_code=404, detail="No such invite")
+    # Idempotency guard: only a still-pending invite can be decided. Without this a repeat/stale
+    # approve or deny re-runs its side effects — re-activating a user, or (now that deny emails)
+    # 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")
     inv.status = "approved" if approved else "denied"
     inv.decided_at = datetime.now(timezone.utc)
     inv.decided_by = admin.email
@@ -105,10 +112,15 @@ def approve_invite(
 @router.post("/invites/{invite_id}/deny")
 def deny_invite(
     invite_id: int,
+    background: BackgroundTasks,
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    return _serialize(_decide(db, invite_id, admin, approved=False))
+    # Symmetry with approve: the requester hears back either way, instead of a silent limbo. No
+    # account is activated, so this is an email only (the requester has no in-app inbox yet).
+    inv = _decide(db, invite_id, admin, approved=False)
+    background.add_task(email_mod.send_access_denied, inv.email)
+    return _serialize(inv)
 
 
 class AddInviteIn(BaseModel):
@@ -354,73 +366,6 @@ def remove_demo_whitelist(
     return {"deleted": entry_id}
 
 
-def _seed_demo_playlists(db: Session, demo: User) -> int:
-    """Seed a few sample playlists from the shared catalog so a freshly-reset demo isn't
-    empty — gives visitors something to play with. Best-effort: skips silently if the
-    catalog is too small."""
-    recent = (
-        db.execute(
-            select(Video.id)
-            .where(Video.is_short.is_(False), Video.live_status == "none")
-            .order_by(Video.published_at.desc().nullslast())
-            .limit(60)
-        )
-        .scalars()
-        .all()
-    )
-    if not recent:
-        return 0
-    samples = [
-        ("Fresh picks", recent[0:10]),
-        ("Quick watch", recent[10:18]),
-        ("Saved for later", recent[18:26]),
-    ]
-    created = 0
-    for pos, (name, vids) in enumerate(samples):
-        if not vids:
-            continue
-        pl = Playlist(user_id=demo.id, name=name, position=pos)
-        db.add(pl)
-        db.flush()
-        for ipos, vid in enumerate(vids):
-            db.add(PlaylistItem(playlist_id=pl.id, video_id=vid, position=ipos))
-        created += 1
-    return created
-
-
-def _seed_demo_subscriptions(db: Session, demo: User, n: int = 14) -> int:
-    """Seed the demo with a handful of catalog channels (the ones with the most videos) so its
-    Channel manager isn't empty — gives visitors something to explore and matches the landing-page
-    screenshot. Idempotent: clears the demo's subscriptions first, then re-adds the top N."""
-    db.execute(delete(Subscription).where(Subscription.user_id == demo.id))
-    top = db.execute(
-        select(Video.channel_id)
-        .where(Video.channel_id.is_not(None))
-        .group_by(Video.channel_id)
-        .order_by(func.count().desc())
-        .limit(n)
-    ).scalars().all()
-    for channel_id in top:
-        db.add(Subscription(user_id=demo.id, channel_id=channel_id))
-    return len(top)
-
-
-def reset_demo_state(db: Session, demo: User) -> int:
-    """Wipe the demo account's per-user state (watch/save/hide states, playlists, preferences)
-    back to a clean baseline and re-seed a few sample playlists + channel subscriptions. Returns
-    the seeded playlist count. Shared by the admin's manual reset button and the scheduled demo
-    reset (see scheduler)."""
-    db.execute(delete(VideoState).where(VideoState.user_id == demo.id))
-    # Playlist items cascade on playlist delete (ondelete="CASCADE").
-    db.execute(delete(Playlist).where(Playlist.user_id == demo.id))
-    demo.preferences = {"language": "en"}
-    db.commit()
-    seeded = _seed_demo_playlists(db, demo)
-    _seed_demo_subscriptions(db, demo)
-    db.commit()
-    return seeded
-
-
 @router.post("/demo/reset")
 def reset_demo(
     admin: User = Depends(admin_user), db: Session = Depends(get_db)

backend/app/routes/audit.py

@@ -9,9 +9,9 @@ from sqlalchemy.orm import Session
 
 from app import audit
 from app.audit import AuditAction
+from app.auth import admin_user
 from app.db import get_db
 from app.models import AuditLog, User
-from app.routes.admin import admin_user
 from app.utils import iso
 
 router = APIRouter(prefix="/api/admin/audit", tags=["admin"])

backend/app/routes/auth.py

@@ -0,0 +1,984 @@
+"""Auth HTTP endpoints (OAuth login/callback, register/verify, password, session mgmt).
+
+Split out of app/auth.py (R12 S2); the core auth surface (current_user, scopes, token
+helpers) stays in app/auth.py, imported below."""
+
+import ipaddress
+import secrets
+from datetime import datetime, timedelta, timezone
+
+from authlib.integrations.starlette_client import OAuth, OAuthError
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
+from fastapi.responses import JSONResponse, RedirectResponse
+from pydantic import BaseModel
+from sqlalchemy import select, update
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from app import email as email_mod
+from app import sysconfig
+from app.auth import (
+    _YOUTUBE_SCOPES,
+    BASE_SCOPES,
+    MAX_SESSION_ACCOUNTS,
+    PASSWORD_MIN_LEN,
+    READ_SCOPES,
+    WRITE_SCOPES,
+    current_user,
+    get_or_create_demo_user,
+    google_enabled,
+    is_allowed,
+    log,
+    operator_contact,
+    resolved_user_id,
+)
+from app.config import settings
+from app.db import SessionLocal, get_db
+from app.models import AuthToken, DemoWhitelist, Invite, OAuthToken, User
+from app.ratelimit import RateLimiter
+from app.security import encrypt, hash_password, hash_token, verify_password
+from app.utils import valid_email
+
+VERIFY_TTL = timedelta(hours=24)
+RESET_TTL = timedelta(hours=1)
+
+_DECOY_PASSWORD_HASH = hash_password(secrets.token_urlsafe(16))
+
+_register_limiter = RateLimiter(max_events=5, window_seconds=300)
+_login_limiter = RateLimiter(max_events=10, window_seconds=300)
+_reset_limiter = RateLimiter(max_events=5, window_seconds=300)
+_verify_resend_limiter = RateLimiter(max_events=5, window_seconds=300)
+_request_access_limiter = RateLimiter(max_events=5, window_seconds=300)
+_suspend_email_limiter = RateLimiter(max_events=1, window_seconds=3600)
+
+
+def _notify_suspended(background: BackgroundTasks, email: str) -> None:
+    """Schedule the one-per-hour 'account suspended' email to a user whose (otherwise valid)
+    sign-in was just blocked. Gated by verified credentials at the call site, so this can't be
+    triggered by someone who doesn't control the account."""
+    if _suspend_email_limiter.allow(email):
+        background.add_task(email_mod.send_account_suspended, email, operator_contact())
+
+
+_demo_limiter = RateLimiter(max_events=5, window_seconds=60)
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+_oauth = OAuth()
+
+_oauth_creds: tuple[str, str] | None = None
+
+
+def google_oauth(db: Session):
+    """The configured authlib Google client, or None when no credentials are set (Google sign-in
+    is then disabled — email+password still works)."""
+    global _oauth, _oauth_creds
+    cid = sysconfig.get_str(db, "google_client_id")
+    csec = sysconfig.get_str(db, "google_client_secret")
+    if not cid or not csec:
+        return None
+    if _oauth_creds != (cid, csec):
+        _oauth = OAuth()
+        _oauth.register(
+            name="google",
+            client_id=cid,
+            client_secret=csec,
+            server_metadata_url="https://accounts.google.com/.well-known/openid-configuration",
+            client_kwargs={"scope": BASE_SCOPES},
+        )
+        _oauth_creds = (cid, csec)
+    return _oauth.google
+
+
+def admin_notify_emails(db: Session) -> list[str]:
+    """Who to email about admin events (e.g. a new access request). The ACTUAL admins — every active,
+    non-suspended `role=admin` user — UNIONED with the env ADMIN_EMAILS bootstrap list. Using the DB
+    roles means an admin promoted through the UI is notified too (env alone would miss them, yet they
+    CAN approve requests — the approve UI is role-gated, so the notify set must match); the env union
+    keeps a freshly-seeded instance working before any DB admin exists."""
+    db_admins = db.execute(
+        select(User.email).where(
+            User.role == "admin", User.is_active.is_(True), User.is_suspended.is_(False)
+        )
+    ).scalars()
+    return sorted({e.lower() for e in db_admins if e} | settings.admin_email_set)
+
+
+def is_demo_allowed(db: Session, email: str) -> bool:
+    """Whether this email may enter the shared demo account (no Google sign-in)."""
+    if not email:
+        return False
+    return (
+        db.execute(
+            select(DemoWhitelist).where(DemoWhitelist.email == email.lower())
+        ).scalar_one_or_none()
+        is not None
+    )
+
+
+def _norm_ip(s: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
+    """Parse an IP for comparison, unwrapping IPv4-mapped IPv6 (`::ffff:10.0.0.1` → `10.0.0.1`) so a
+    plain-IPv4 allowlist still matches a peer that surfaces in mapped form. None for a non-IP string."""
+    try:
+        ip = ipaddress.ip_address(s.strip())
+    except ValueError:
+        return None
+    return ip.ipv4_mapped if getattr(ip, "ipv4_mapped", None) else ip
+
+
+def _client_ip(request: Request) -> str:
+    """Best-effort client IP for rate limiting. X-Forwarded-For is client-controlled, so we trust it
+    ONLY when the request actually arrived from a configured reverse proxy (settings.trusted_proxy_ips
+    — the address the proxy connects FROM, e.g. the VPS Caddy's WireGuard peer IP). Our proxy APPENDS
+    the client it saw to XFF, so the RIGHTMOST entry is the real client and can't be forged by a
+    client pre-seeding the header. Any other peer (someone hitting the app port directly, bypassing the
+    proxy) is untrusted — we use its real socket IP, so it can't spoof its rate-limit identity.
+
+    SAFETY: this relies on `request.client` being the TRUE socket peer. uvicorn is started WITHOUT
+    `--proxy-headers` (see entrypoint.sh) precisely so it never rewrites `request.client` from XFF —
+    do NOT add that flag, or the trust check below would compare against a forgeable value."""
+    peer = request.client.host if request.client else "unknown"
+    trusted = {_norm_ip(p) for p in settings.trusted_proxy_ip_set} - {None}
+    if _norm_ip(peer) in trusted:
+        xff = request.headers.get("x-forwarded-for")
+        parts = [p.strip() for p in (xff or "").split(",") if p.strip()]
+        if parts:
+            return parts[-1]
+    return peer
+
+
+def upsert_pending_invite(db: Session, email: str) -> Invite | None:
+    """Idempotently record an access request. Returns the Invite if a *new* pending row
+    was created (so the caller can notify admins), else None for already-known emails."""
+    email = (email or "").lower()
+    if not valid_email(email):
+        return None
+    inv = db.execute(select(Invite).where(Invite.email == email)).scalar_one_or_none()
+    if inv is not None:
+        # Let a previously-denied person ask again; don't disturb approved/pending rows.
+        if inv.status == "denied":
+            inv.status = "pending"
+            inv.requested_at = datetime.now(timezone.utc)
+            inv.decided_at = None
+            inv.decided_by = None
+            db.commit()
+            return inv
+        return None
+    inv = Invite(email=email, status="pending")
+    db.add(inv)
+    db.commit()
+    return inv
+
+
+_DEV_OAUTH_HOSTS = frozenset(
+    {"localhost:5173", "localhost:8080", "127.0.0.1:5173", "127.0.0.1:8080"}
+)
+
+
+def _oauth_redirect_uri(request: Request) -> str:
+    """The redirect_uri handed to Google. Production always uses the fixed configured URL and never
+    trusts the request Host (a forged Host header must not be able to redirect the OAuth code). In
+    local dev we honor the request's own origin when it is one of the known dev hosts, so a login
+    started on the Vite server (:5173) returns to :5173 and one on :8080 returns to :8080."""
+    if settings.session_https_only:  # https redirect URL == real deployment
+        return settings.oauth_redirect_url
+    host = (request.headers.get("host") or "").lower()
+    if host in _DEV_OAUTH_HOSTS:
+        return f"http://{host}/auth/callback"
+    return settings.oauth_redirect_url
+
+
+
+# --- Request bodies (typed contracts; B-core-6) ---------------------------------------------
+# Fields are `str | None` (not required) so the handlers keep their exact prior behaviour — a
+# missing/null field reads as None and the existing `(... or "")` coercions still apply — while
+# FastAPI now validates the body is a JSON object and publishes the schema.
+
+
+class EmailIn(BaseModel):
+    email: str | None = None
+
+
+class EmailPasswordIn(BaseModel):
+    email: str | None = None
+    password: str | None = None
+
+
+class TokenIn(BaseModel):
+    token: str | None = None
+
+
+class TokenPasswordIn(BaseModel):
+    token: str | None = None
+    password: str | None = None
+
+
+class SetPasswordIn(BaseModel):
+    password: str | None = None
+    current_password: str | None = None
+
+
+@router.get("/login")
+async def login(request: Request, db: Session = Depends(get_db)):
+    # access_type=offline ensures a refresh_token on first authorization. We avoid
+    # prompt=consent so returning users get a quick sign-in; the stored refresh token
+    # is kept when Google doesn't re-issue one (see the callback).
+    client = google_oauth(db)
+    if client is None:
+        # Google sign-in isn't configured on this instance — land back on the login page (the UI
+        # hides the button, so this is just a safety net for a stale/direct hit).
+        return RedirectResponse(url="/")
+    return await client.authorize_redirect(
+        request,
+        _oauth_redirect_uri(request),
+        access_type="offline",
+        prompt="select_account",
+        include_granted_scopes="true",
+        scope=BASE_SCOPES,
+    )
+
+
+@router.get("/callback")
+async def callback(
+    request: Request,
+    background: BackgroundTasks,
+    db: Session = Depends(get_db),
+):
+    client = google_oauth(db)
+    if client is None:
+        return RedirectResponse(url="/")
+    # Linking mode: an already-authenticated account is attaching this Google identity (a
+    # password account enabling YouTube or connecting SSO). The markers are set by /auth/link and
+    # /auth/upgrade; when present we attach to the current user instead of identifying by sub.
+    # Pop them BEFORE the token exchange: if the user aborts Google's consent screen the exchange
+    # throws below, and a marker left behind would silently turn the NEXT clean sign-in into a link
+    # attempt. Popping up front means an aborted link flow leaves no residue in the session.
+    link_uid = request.session.pop("oauth_link_uid", None)
+    link_explicit = request.session.pop("oauth_link_explicit", False)
+    try:
+        token = await client.authorize_access_token(request)
+    except OAuthError as exc:
+        # The user cancelled or denied consent at Google — land back with a friendly notice instead
+        # of a raw 400 JSON error page. An already-signed-in user (adding another account via
+        # /auth/login, or linking/upgrading via /auth/link|upgrade) never sees the pre-auth login
+        # banner, so surface a neutral toast via ?oauth=cancelled; a fresh sign-in cancel lands on
+        # the login page with the oauth_cancelled banner instead. Keyed on the live session, not on
+        # link_uid, so the add-account path (no marker) is covered too.
+        log.info("Google OAuth cancelled/failed: %s", exc.error)
+        if request.session.get("user_id") is not None:
+            return RedirectResponse(url="/?oauth=cancelled")
+        return RedirectResponse(url="/?login=oauth_cancelled")
+
+    userinfo = token.get("userinfo")
+    if not userinfo or not userinfo.get("sub"):
+        raise HTTPException(status_code=400, detail="No user info returned by Google")
+
+    sub = userinfo["sub"]
+    email = (userinfo.get("email") or "").lower()
+
+    if link_uid is not None:
+        return _complete_link(
+            request, db, link_uid, link_explicit, sub, userinfo, token
+        )
+
+    if not is_allowed(db, email):
+        log.warning("Login denied (not approved): %s", email or "<no email>")
+        # A denied Google login doubles as an access request: record it for the admin and
+        # land the user on a friendly "request received" screen instead of a raw 403.
+        if email:
+            inv = upsert_pending_invite(db, email)
+            admins = admin_notify_emails(db)
+            if inv is not None and admins:
+                background.add_task(email_mod.send_admin_new_request, admins, email)
+            return RedirectResponse(url="/?access=requested")
+        return RedirectResponse(url="/?access=denied")
+
+    user = db.query(User).filter(User.google_sub == sub).one_or_none()
+    if user is None:
+        # No account carries this Google identity yet. If one already exists for this email —
+        # e.g. an email+password registration — adopt the Google identity onto it instead of
+        # inserting a duplicate (which would collide on the unique email and 500). Google has
+        # verified the address, so this safely unifies password + Google sign-in on one account.
+        existing = db.query(User).filter(User.email == email).one_or_none()
+        if existing is not None:
+            if existing.google_sub is not None and existing.google_sub != sub:
+                # A different Google identity is already bound to this email — refuse rather than
+                # hijack it. (Near-impossible with real Google accounts: email↔sub is stable.)
+                log.warning("Google login email collision (different sub): %s", email)
+                return RedirectResponse(url="/?access=denied")
+            if not userinfo.get("email_verified", False):
+                # Adopting (and activating) a pre-existing password account requires Google to
+                # actually attest the address — otherwise an unverified Google email that merely
+                # collides with a pending registration could seize that account. Defense-in-depth.
+                log.warning(
+                    "Google login: unverified email, refusing to adopt account: %s",
+                    email,
+                )
+                return RedirectResponse(url="/?access=denied")
+            user = existing
+            user.google_sub = sub
+            # SEC-10: drop any password pre-set on this account while its email was still unverified,
+            # now that Google attests ownership (bumps the epoch to revoke any session it minted).
+            revoke_preset_password_if_unverified(user)
+            # Google verified the email and is_allowed granted access, so finish activating a
+            # previously pending password registration (otherwise current_user would bounce it).
+            user.email_verified = True
+            user.is_active = True
+        else:
+            user = User(google_sub=sub, email=email)
+            db.add(user)
+    # A suspended account can't sign in by any method. Block before establishing the session and
+    # tell the (verified) owner why — a successful Google auth proves they control this account.
+    if user.is_suspended:
+        log.info("Suspended account blocked at Google login: %s", email)
+        _notify_suspended(background, user.email)
+        return RedirectResponse(url="/?login=suspended")
+    # Keep the email in sync with Google, but never overwrite it with one another account already
+    # owns — that would hit the unique constraint and 500, wedging this user's sign-in (rare: a
+    # Google-side email change to a value that collides with a different local account).
+    if user.email != email:
+        clash = (
+            db.query(User).filter(User.email == email, User.id != user.id).one_or_none()
+        )
+        if clash is None:
+            user.email = email
+    user.display_name = 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
+    # routine login must NOT reset it (that would clobber a UI promotion/demotion). Only seed a
+    # default for a brand-new account (its role attribute is still unset before flush).
+    if email in settings.admin_email_set:
+        user.role = "admin"
+    elif not user.role:
+        user.role = "user"
+    # Google attests the email, so a Google sign-in implicitly verifies it. Setting this also lets
+    # a Google user who later adds a password sign in (password-login gates on email_verified).
+    if userinfo.get("email_verified", True):
+        user.email_verified = True
+    # Default UI language from the Google-reported locale on first login (if the user hasn't
+    # picked one yet); unsupported locales fall back to English.
+    prefs = dict(user.preferences or {})
+    if not prefs.get("language"):
+        loc = (userinfo.get("locale") or "").split("-")[0].lower()
+        prefs["language"] = loc if loc in {"en", "hu"} else "en"
+        user.preferences = prefs
+    db.flush()
+
+    _store_token(db, user, token)
+    db.commit()
+
+    # Multi-session: remember every account that has authenticated in this browser so the
+    # user can switch between them without going through Google again. Only accounts that
+    # actually completed OAuth here land in this list (it's the proof they may be switched to).
+    accounts = [a for a in (request.session.get("account_ids") or []) if a != user.id]
+    accounts.append(user.id)
+    request.session["account_ids"] = accounts[-MAX_SESSION_ACCOUNTS:]
+    request.session["user_id"] = user.id
+    _remember_epoch(request, user)
+    log.info("Login: %s (id=%s, role=%s)", email, user.id, user.role)
+    return RedirectResponse(url="/")
+
+
+def _store_token(db: Session, user: User, token: dict) -> None:
+    """Persist the OAuth grant on the user's single token row, creating it if absent. Google
+    only returns a refresh_token on (re)consent, so the previous one is kept otherwise.
+    include_granted_scopes=true means `scope` is the union of everything granted, so this
+    reflects read/write upgrades correctly."""
+    tok = user.token or OAuthToken(user=user)
+    old = set((tok.scopes or "").split())
+    new = set((token.get("scope") or "").split())
+    # A plain re-sign-in requests only BASE_SCOPES, and Google can hand back a FRESH base-only
+    # access+refresh token. Adopting it would DESTROY a previously-granted YouTube read/write grant —
+    # can_read/can_write flip to false and the feed demands a reconnect (the exact bug users hit on a
+    # logout→login). The OLD refresh token stays valid on Google's side, so when this exchange would
+    # NARROW our YouTube scopes, keep the WHOLE existing grant (refresh token, access token, scopes)
+    # untouched. The grant only shrinks on a full disconnect (purge_user deletes the token row); an
+    # externally-revoked scope surfaces later as a YouTube API 403 → reconnect, not through this write.
+    if (old & _YOUTUBE_SCOPES) - new:
+        db.add(tok)
+        return
+    if token.get("refresh_token"):
+        tok.refresh_token_enc = encrypt(token["refresh_token"])
+    # Encrypt the access token at rest too (it's a live ~1h bearer credential), matching the
+    # refresh token — a DB/backup/log leak otherwise hands out working Google API tokens.
+    tok.access_token = encrypt(token.get("access_token"))
+    expires_at = token.get("expires_at")
+    tok.expiry = (
+        datetime.fromtimestamp(expires_at, tz=timezone.utc) if expires_at else None
+    )
+    # Union (never narrow): a broader-or-equal exchange may still list only the newly-added scope.
+    tok.scopes = " ".join(sorted(old | new)) or BASE_SCOPES
+    db.add(tok)
+
+
+def _complete_link(
+    request: Request,
+    db: Session,
+    link_uid: int,
+    explicit: bool,
+    sub: str,
+    userinfo: dict,
+    token: dict,
+):
+    """Attach the just-authorized Google identity to the already-signed-in account that started
+    the link/upgrade. No is_allowed gate — they're already an active user. Refuses to hijack a
+    Google identity owned by another account, or to silently swap a different linked identity.
+    `explicit` (the popped oauth_link_explicit marker) distinguishes a "Connect Google" click from
+    a YouTube upgrade — the caller pops it up front so an aborted flow leaves nothing behind."""
+    # SEC-11: the marker must name an account signed into THIS browser — the session default OR any
+    # account in the wallet — not only the default. A tab acting as a secondary account links Google to
+    # ITSELF (the marker was set from current_user, which resolves the ?account= it navigated with), so
+    # accepting wallet membership stops the identity/token landing on the default account A instead of B.
+    accounts = request.session.get("account_ids") or []
+    if link_uid != request.session.get("user_id") and link_uid not in accounts:
+        return RedirectResponse(url="/?link=error")
+    user = db.get(User, link_uid)
+    if user is None or user.is_demo:
+        return RedirectResponse(url="/?link=error")
+    other = (
+        db.query(User).filter(User.google_sub == sub, User.id != user.id).one_or_none()
+    )
+    if other is not None:
+        return RedirectResponse(url="/?link=conflict")
+    if user.google_sub is not None and user.google_sub != sub:
+        return RedirectResponse(url="/?link=mismatch")
+    user.google_sub = sub
+    if not user.display_name:
+        user.display_name = userinfo.get("name")
+    if not user.avatar_url:
+        user.avatar_url = userinfo.get("picture")
+    _store_token(db, user, token)
+    db.commit()
+    log.info("Google linked: uid=%s scopes=%s", user.id, token.get("scope"))
+    # An explicit "Connect Google" lands on Settings with a confirmation; a YouTube upgrade
+    # (wizard / Settings access rows) returns to the app so the onboarding flow resumes as before.
+    return RedirectResponse(url="/?link=ok" if explicit else "/")
+
+
+@router.post("/logout")
+async def logout(request: Request):
+    """Sign the requesting tab's active account out of this browser (removing it from the wallet).
+    Per-tab aware: the account is taken from the X-Siftlode-Account header when present, so logging
+    out in one tab doesn't disturb another tab running a different account. If the account being
+    removed was the session default, promote the most recent remaining account (or clear the
+    session when none remain)."""
+    active, is_default = resolved_user_id(request)
+    remaining = [a for a in (request.session.get("account_ids") or []) if a != active]
+    request.session["account_ids"] = remaining
+    if is_default:
+        if remaining:
+            request.session["user_id"] = remaining[-1]
+            return JSONResponse({"ok": True, "switched": True})
+        request.session.clear()
+        return JSONResponse({"ok": True, "switched": False})
+    # A non-default (per-tab) account signed out: it's gone from the wallet and the session default
+    # is untouched. The tab drops its own override and falls back to the default on reload.
+    return JSONResponse({"ok": True, "switched": False})
+
+
+@router.post("/request-access")
+async def request_access(
+    body: EmailIn,
+    request: Request,
+    background: BackgroundTasks,
+    db: Session = Depends(get_db),
+) -> dict:
+    """Public: ask for access. Idempotent — repeat requests for the same email don't
+    duplicate or re-spam admins (upsert returns None for an already-pending row).
+
+    Answers a uniform ``"pending"`` for EVERY outcome — already-allowed, newly-pending,
+    already-pending, and rate-limited alike. The old ``"approved"`` reply for an allow-listed
+    address made this a public enumeration oracle for the allow-list (which the rest of the module
+    is careful to avoid, cf. demo_login); an already-allowed user can still just sign in with Google.
+    Rate-limited per client IP like register/login/reset, and a block returns "pending" too so the
+    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.")
+    if not _request_access_limiter.allow(_client_ip(request)):
+        return {"status": "pending"}
+    if is_allowed(db, email):
+        return {"status": "pending"}  # already allowed — don't reveal it
+    inv = upsert_pending_invite(db, email)
+    admins = admin_notify_emails(db)
+    if inv is not None and admins:
+        background.add_task(email_mod.send_admin_new_request, admins, email)
+    return {"status": "pending"}
+
+
+@router.post("/demo")
+def demo_login(body: EmailIn, request: Request, db: Session = Depends(get_db)) -> dict:
+    """Hidden demo entry: a whitelisted email logs straight into the shared demo account,
+    no Google OAuth. The login page fires this quietly (debounced) as the user types/pastes,
+    so there is no visible 'demo login' button. Rate-limited per IP; when blocked it answers
+    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_ip(request)):
+        return {"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)
+        # Isolate the demo: drop any real-account wallet on this tab first, so the demo session
+        # can't switch to / act as a previously signed-in account via the multi-account header.
+        request.session.clear()
+        request.session["user_id"] = demo.id
+        _remember_epoch(request, demo)
+        log.info("Demo login (key=%s, demo_id=%s)", email, demo.id)
+        return {"authenticated": True}
+    return {"authenticated": False}
+
+
+def _establish_session(request: Request, user: User) -> None:
+    """Sign `user` in for this browser session, mirroring the Google callback's multi-account
+    handling so password sign-in joins the same account switcher."""
+    accounts = [a for a in (request.session.get("account_ids") or []) if a != user.id]
+    accounts.append(user.id)
+    request.session["account_ids"] = accounts[-MAX_SESSION_ACCOUNTS:]
+    request.session["user_id"] = user.id
+    _remember_epoch(request, user)
+
+
+def _app_base() -> str:
+    """Public origin of the deployed app (OAUTH_REDIRECT_URL is .../auth/callback)."""
+    return settings.app_base
+
+
+def _issue_token(db: Session, user: User, kind: str, ttl: timedelta) -> str:
+    """Create a single-use token of `kind`; only its hash is stored. Returns the raw token
+    (goes only into the emailed link)."""
+    raw = secrets.token_urlsafe(32)
+    db.add(
+        AuthToken(
+            user_id=user.id,
+            kind=kind,
+            token_hash=hash_token(raw),
+            expires_at=datetime.now(timezone.utc) + ttl,
+        )
+    )
+    db.commit()
+    return raw
+
+
+def _consume_token(db: Session, raw: str | None, kind: str) -> User | None:
+    """Validate + burn a token atomically. Returns its user, or None if missing/expired/used/wrong
+    kind. The burn is a single conditional UPDATE (…WHERE used_at IS NULL…RETURNING) rather than a
+    read-check-write, so two concurrent requests can't both consume the same verify/reset token —
+    only the one whose UPDATE flips used_at gets a row back."""
+    if not raw:
+        return None
+    now = datetime.now(timezone.utc)
+    row = db.execute(
+        update(AuthToken)
+        .where(
+            AuthToken.token_hash == hash_token(raw),
+            AuthToken.kind == kind,
+            AuthToken.used_at.is_(None),
+            AuthToken.expires_at >= now,
+        )
+        .values(used_at=now)
+        .returning(AuthToken.user_id)
+    ).first()
+    db.commit()
+    if row is None:
+        return None
+    return db.get(User, row.user_id)
+
+
+@router.post("/register")
+def register(
+    body: EmailPasswordIn,
+    request: Request,
+    background: BackgroundTasks,
+    db: Session = Depends(get_db),
+) -> dict:
+    """Email+password registration. Creates a pending (inactive, unverified) account, sends a
+    verification link, and records an access request for admin approval. Two gates before
+    sign-in: verified email AND admin approval. Responses are uniform once input is valid, so
+    the endpoint can't be used to discover which emails are registered."""
+    email = (body.email or "").strip().lower()
+    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.")
+    if len(password) < PASSWORD_MIN_LEN:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Password must be at least {PASSWORD_MIN_LEN} characters.",
+        )
+    if not sysconfig.get_bool(db, "allow_registration"):
+        raise HTTPException(status_code=403, detail="Registration is currently closed.")
+    if not _register_limiter.allow(_client_ip(request)):
+        return {"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)
+    return {"status": "ok"}
+
+
+def _register_account(email: str, password: str) -> None:
+    """Background worker for /register: create the pending account (+ verification email + admin
+    notice) for a genuinely new email; no-op for an already-registered one. Runs after the response
+    with its own DB session, so the request's timing never reveals whether the email already exists."""
+    with SessionLocal() as db:
+        if (
+            db.execute(select(User).where(User.email == email)).scalar_one_or_none()
+            is not None
+        ):
+            return  # already registered — nothing to do (the uniform "ok" was already returned)
+        # Without working SMTP we can't deliver a verification link, so email ownership can't gate
+        # sign-in. Admin approval stays the real gate (is_active=False); mark the account verified so
+        # the flow still completes on a no-SMTP self-host. See email.email_enabled().
+        email_ok = email_mod.email_enabled()
+        user = User(
+            email=email,
+            password_hash=hash_password(password),
+            is_active=False,
+            email_verified=not email_ok,
+        )
+        db.add(user)
+        try:
+            db.flush()
+        except IntegrityError:
+            # A concurrent registration for the same new email won the race between the pre-check
+            # above and this flush (the unique-email constraint fires). Same already-registered
+            # no-op as the pre-check hit — roll back and stop.
+            db.rollback()
+            return
+        upsert_pending_invite(db, email)  # admin-approval gate (commits)
+        if email_ok:
+            raw = _issue_token(db, user, "verify", VERIFY_TTL)
+            # Fragment (#), not a query token: keeps the token out of proxy/access logs + Referer (SB3).
+            email_mod.send_verify_email(email, f"{_app_base()}/#verify={raw}")
+        admins = admin_notify_emails(db)
+        if admins:
+            email_mod.send_admin_new_request(admins, email)
+
+
+@router.post("/verify")
+def verify_email_confirm(body: TokenIn, db: Session = Depends(get_db)) -> dict:
+    """Confirm an email-verification token the SPA read from the URL fragment (SB3). Uniform 400
+    on any invalid/expired/used token."""
+    user = _consume_token(db, body.token, "verify")
+    if user is None:
+        raise HTTPException(
+            status_code=400, detail="This verification link is invalid or has expired."
+        )
+    user.email_verified = True
+    db.commit()
+    return {"ok": True}
+
+
+@router.post("/verify/resend")
+def verify_email_resend(
+    body: EmailIn,
+    request: Request,
+    background: BackgroundTasks,
+) -> dict:
+    """Re-issue an email-verification link. Needed because the original link expires (VERIFY_TTL)
+    and re-registering an already-registered email is a silent no-op, so a user who lost the first
+    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_ip(request)):
+        return {"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"}
+
+
+def _resend_verify_if_eligible(email: str) -> None:
+    """Background worker for verify/resend: issue a fresh verify token + email the link, but ONLY for
+    a real account that still needs verifying. Runs after the response with its own DB session, so the
+    request's timing never reveals whether the account exists. No-op when SMTP is disabled (accounts
+    are auto-verified on a no-SMTP instance, so there is nothing to resend). Token rides the URL
+    FRAGMENT (#) so it can't leak into proxy/access logs or a Referer (SB3)."""
+    if not email_mod.email_enabled():
+        return
+    with SessionLocal() as db:
+        user = db.execute(select(User).where(User.email == email)).scalar_one_or_none()
+        if user is not None and not user.email_verified and not user.is_demo:
+            raw = _issue_token(db, user, "verify", VERIFY_TTL)
+            email_mod.send_verify_email(email, f"{_app_base()}/#verify={raw}")
+
+
+@router.get("/verify")
+def verify_email(token: str, db: Session = Depends(get_db)):
+    """Legacy query-token verification link (pre-SB3 emails still in flight). New emails use the
+    fragment + POST flow above; this bounces to a friendly status for older links until they expire."""
+    user = _consume_token(db, token, "verify")
+    if user is None:
+        return RedirectResponse(url="/?verify=invalid")
+    user.email_verified = True
+    db.commit()
+    return RedirectResponse(url="/?verify=ok")
+
+
+@router.post("/password-login")
+def password_login(
+    body: EmailPasswordIn,
+    request: Request,
+    background: BackgroundTasks,
+    db: Session = Depends(get_db),
+) -> dict:
+    """Email+password sign-in. Wrong email/password give a single uniform 401 (no enumeration).
+    Once the password is proven correct, the owner gets a specific reason if their account is
+    still pending or suspended — that's not an enumeration leak (they already hold the password)."""
+    if not _login_limiter.allow(_client_ip(request)):
+        raise HTTPException(
+            status_code=429, detail="Too many attempts. Try again shortly."
+        )
+    email = (body.email or "").strip().lower()
+    password = body.password or ""
+    user = db.execute(select(User).where(User.email == email)).scalar_one_or_none()
+    # Always run the KDF (against a decoy hash for an unknown / passwordless / demo account) so the
+    # response time is the same whether or not the email exists — no timing-based enumeration.
+    candidate_hash = user.password_hash if (user and not user.is_demo) else None
+    password_ok = verify_password(password, candidate_hash or _DECOY_PASSWORD_HASH)
+    if user is None or user.is_demo or not password_ok:
+        raise HTTPException(status_code=401, detail="Invalid email or password.")
+    if user.is_suspended:
+        _notify_suspended(background, user.email)
+        op = operator_contact()
+        detail = "Your account has been suspended."
+        if op:
+            detail += f" If you have questions, contact the operator at {op}."
+        raise HTTPException(status_code=403, detail=detail)
+    if not user.email_verified:
+        raise HTTPException(
+            status_code=403, detail="Please verify your email first (check your inbox)."
+        )
+    if not user.is_active:
+        raise HTTPException(
+            status_code=403, detail="Your account is awaiting admin approval."
+        )
+    _establish_session(request, user)
+    log.info("Password login: %s (id=%s, role=%s)", email, user.id, user.role)
+    return {"ok": True}
+
+
+@router.post("/password-reset/request")
+def password_reset_request(
+    body: EmailIn,
+    request: Request,
+    background: BackgroundTasks,
+) -> dict:
+    """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_ip(request)):
+        return {"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"}
+
+
+def _send_reset_if_eligible(email: str) -> None:
+    """Background worker for password_reset_request: issue a reset token + email the link, but ONLY
+    for a real (non-demo) password account. Runs after the response with its own DB session, so the
+    request's timing never reveals whether the account exists. Token rides the URL FRAGMENT (#) so it
+    can't leak into proxy/access logs or a Referer (SB3)."""
+    with SessionLocal() as db:
+        user = db.execute(select(User).where(User.email == email)).scalar_one_or_none()
+        if user is not None and user.password_hash and not user.is_demo:
+            raw = _issue_token(db, user, "reset", RESET_TTL)
+            email_mod.send_password_reset(email, f"{_app_base()}/#reset={raw}")
+
+
+@router.post("/password-reset/confirm")
+def password_reset_confirm(body: TokenPasswordIn, db: Session = Depends(get_db)) -> dict:
+    """Set a new password from a valid reset token, then invalidate any other reset tokens."""
+    token = body.token
+    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.",
+        )
+    user = _consume_token(db, token, "reset")
+    if user is None:
+        raise HTTPException(
+            status_code=400, detail="This reset link is invalid or has expired."
+        )
+    user.password_hash = hash_password(new_password)
+    # A valid reset link proves control of the mailbox, so completing a reset also verifies the
+    # email — this rescues an account that registered but never clicked the verification link (it
+    # can then sign in). The separate admin-approval gate (is_active) is deliberately NOT touched
+    # here: a reset proves email ownership, not that an admin approved the account.
+    user.email_verified = True
+    bump_session_epoch(
+        user
+    )  # SA4: a reset (often a compromise response) kills all existing sessions.
+    # Burn any other outstanding reset tokens for this user.
+    for row in db.execute(
+        select(AuthToken).where(
+            AuthToken.user_id == user.id,
+            AuthToken.kind == "reset",
+            AuthToken.used_at.is_(None),
+        )
+    ).scalars():
+        row.used_at = datetime.now(timezone.utc)
+    db.commit()
+    return {"ok": True}
+
+
+def _remember_epoch(request: Request, user: User) -> None:
+    """Record this account's current `session_epoch` in the signed cookie (SA4), so `current_user`
+    can later reject the cookie if the account's epoch was bumped (password reset/change, or
+    "log out everywhere"). Per-account so one account's revocation doesn't evict the others."""
+    epochs = dict(request.session.get("epochs") or {})
+    epochs[str(user.id)] = user.session_epoch
+    request.session["epochs"] = epochs
+
+
+def bump_session_epoch(user: User) -> None:
+    """Invalidate every EXISTING signed cookie for this account by advancing its epoch (SA4). Cookies
+    minted before the bump carry a now-stale epoch and are rejected by `current_user`."""
+    user.session_epoch = (user.session_epoch or 0) + 1
+
+
+def revoke_preset_password_if_unverified(user: User) -> None:
+    """SEC-10 (account pre-emption): a password set on an account whose email was NEVER verified is
+    untrusted — whoever registered the address (to pre-empt the real owner) could have chosen it. When
+    ownership is finally attested (Google adoption, or admin approval), drop that password and bump the
+    epoch to revoke any session it minted; the owner re-sets one via password-reset. No-op for an
+    already-verified account, so a legit no-SMTP registration is unaffected. The single source for this
+    rule — both the Google-callback and admin-activation paths call it so they can't drift."""
+    if not user.email_verified:
+        user.password_hash = None
+        bump_session_epoch(user)
+
+
+@router.post("/logout-others")
+def logout_others(
+    request: Request, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
+    """SA4: sign every OTHER session for this account out — bump the epoch so all existing cookies
+    are rejected, then re-stamp THIS cookie so the caller stays signed in. For "I left myself logged
+    in somewhere" / a suspected session compromise. The demo account (shared) is excluded."""
+    if user.is_demo:
+        raise HTTPException(
+            status_code=403, detail="Not available in the demo account."
+        )
+    # Commit the bump BEFORE re-stamping this cookie, so a failed commit can't strand the current
+    # session at a newer epoch than the DB (see set_password).
+    bump_session_epoch(user)
+    db.commit()
+    _remember_epoch(request, user)
+    log.info("Logout-others: uid=%s (epoch=%s)", user.id, user.session_epoch)
+    return {"ok": True}
+
+
+@router.get("/link")
+async def link_google(
+    request: Request,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+):
+    """Start linking a Google account to the signed-in (e.g. password) account. Requests only
+    the identity scopes — YouTube access is granted separately via /auth/upgrade. The callback
+    sees `oauth_link_uid` and attaches the identity instead of creating a new account."""
+    if user.is_demo:
+        return RedirectResponse(url="/")
+    client = google_oauth(db)
+    if client is None:
+        return RedirectResponse(url="/?link=error")
+    request.session["oauth_link_uid"] = user.id
+    request.session["oauth_link_explicit"] = True
+    return await client.authorize_redirect(
+        request,
+        _oauth_redirect_uri(request),
+        access_type="offline",
+        prompt="select_account",
+        include_granted_scopes="true",
+        scope=BASE_SCOPES,
+    )
+
+
+@router.post("/set-password")
+def set_password(
+    body: SetPasswordIn,
+    request: Request,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Set or change the signed-in account's password. Setting a first password (Google-only
+    account) needs no current password — the session already proves identity. Changing an
+    existing one requires the current password, so a hijacked session can't silently rotate it."""
+    if user.is_demo:
+        raise HTTPException(
+            status_code=403, detail="Not available in the demo account."
+        )
+    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.",
+        )
+    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."
+            )
+    user.password_hash = hash_password(new_password)
+    # SA4: a password change logs out every OTHER session; re-stamp this cookie at the new epoch so
+    # the person making the change stays signed in here. Commit BEFORE re-stamping so a failed commit
+    # can't leave the cookie at a newer epoch than the DB (which would wrongly 401 THIS session).
+    bump_session_epoch(user)
+    db.commit()
+    _remember_epoch(request, user)
+    log.info("Password set/changed: uid=%s", user.id)
+    return {"ok": True}
+
+
+@router.get("/upgrade")
+async def upgrade(
+    request: Request,
+    access: str = "read",
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+):
+    """Incremental consent for the onboarding wizard. `access=read` grants YouTube
+    read-only (enough to build the feed); `access=write` additionally grants management
+    (unsubscribe). The shared callback stores whatever Google returns, so `can_read` /
+    `can_write` flip on once granted. Anything other than an explicit `write` defaults to
+    the least-privileged read scope."""
+    # This is the browser-facing redirect entry point, so the shared demo account is bounced
+    # straight home (no YouTube link is ever attached to it) rather than shown a raw 403.
+    if user.is_demo:
+        return RedirectResponse(url="/")
+    client = google_oauth(db)
+    if client is None:
+        return RedirectResponse(url="/")
+    # Attach the grant to THIS account in the callback. Without it a password account (no
+    # google_sub) would get a brand-new, separate Google user created instead of being linked.
+    request.session["oauth_link_uid"] = user.id
+    scope = WRITE_SCOPES if access == "write" else READ_SCOPES
+    return await client.authorize_redirect(
+        request,
+        _oauth_redirect_uri(request),
+        access_type="offline",
+        prompt="consent",
+        include_granted_scopes="true",
+        scope=scope,
+    )
+
+
+@router.get("/config")
+def auth_config(db: Session = Depends(get_db)) -> dict:
+    """Public: which sign-in options this instance offers, so the login page can hide what's off
+    (e.g. no Google button when Google OAuth isn't configured)."""
+    return {
+        "google_enabled": google_enabled(db),
+        "allow_registration": sysconfig.get_bool(db, "allow_registration"),
+        # Contact shown on the public legal pages (the operator's admin email), if configured.
+        "operator_contact": operator_contact(),
+    }

backend/app/routes/channels.py

@@ -1,16 +1,16 @@
 """Channel manager: the user's subscriptions with their personal overrides (priority,
-hidden, tags) and per-channel sync state. Read + local-write only — YouTube-side writes
+hidden, tags) and per-channel sync state. Local reads/writes plus YouTube-side writes
-(unsubscribe) live behind the optional write scope and are added in a later phase."""
+(subscribe / unsubscribe) that require the optional write scope."""
 import logging
 from datetime import datetime, timezone
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
 from pydantic import BaseModel
 from sqlalchemy import func, select, update
 from sqlalchemy.orm import Session
 
-from app import quota, sysconfig
+from app import quota
-from app.auth import current_user, require_human, require_write_scope
+from app.auth import admin_user, current_user, require_human, require_write_scope
 from app.db import get_db
 from app.models import (
     LIVE_OR_UPCOMING,
@@ -26,9 +26,8 @@ from app.models import (
     Video,
 )
 from app.routes._common import owned_or_404
-from app.routes.admin import admin_user
 from app.sync.explore import explore_ingest_page
-from app.sync.runner import run_recent_backfill
+from app.sync.runner import backfill_channel_now, run_recent_backfill
 from app.sync.subscriptions import apply_channel_details
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
@@ -50,20 +49,19 @@ def list_channels(
     ).all()
 
     # Per-channel aggregates over the shared catalog in ONE grouped pass: stored count, last
-    # upload, total duration, and a Normal/Shorts/Live breakdown. Cheap — a single grouped scan
+    # upload, total duration. Cheap — a single grouped scan, so computed on read rather than
-    # (~35 ms over the full 233k-row catalog on the dev DB), so computed on read rather than
     # denormalised (measure-first: reads aren't frequent/hot enough to warrant cached columns).
+    # (The Normal/Shorts/Live breakdown moved to the channel-detail page in R14, so it is no longer
+    # computed here — the manager table dropped its N/S/L column.)
     channel_ids = [c.id for _, c in rows]
     agg: dict[str, dict] = {}
     if channel_ids:
-        for cid, n, last_up, total_dur, shorts, live in db.execute(
+        for cid, n, last_up, total_dur in db.execute(
             select(
                 Video.channel_id,
                 func.count(Video.id),
                 func.max(Video.published_at),
                 func.coalesce(func.sum(Video.duration_seconds), 0),
-                func.count(Video.id).filter(Video.is_short.is_(True)),
-                func.count(Video.id).filter(Video.live_status.in_(LIVE_OR_UPCOMING)),
             )
             .where(Video.channel_id.in_(channel_ids))
             .group_by(Video.channel_id)
@@ -72,9 +70,6 @@ def list_channels(
                 "stored": n,
                 "last_video_at": iso(last_up),
                 "total_duration_seconds": int(total_dur or 0),
-                "count_short": int(shorts),
-                "count_live": int(live),
-                "count_normal": max(0, int(n) - int(shorts) - int(live)),
             }
 
     # Channels already in the *global* deep-backfill queue — i.e. at least one user (any
@@ -108,9 +103,6 @@ def list_channels(
             "stored_videos": (agg.get(ch.id) or {}).get("stored", 0),
             "last_video_at": (agg.get(ch.id) or {}).get("last_video_at"),
             "total_duration_seconds": (agg.get(ch.id) or {}).get("total_duration_seconds", 0),
-            "count_normal": (agg.get(ch.id) or {}).get("count_normal", 0),
-            "count_short": (agg.get(ch.id) or {}).get("count_short", 0),
-            "count_live": (agg.get(ch.id) or {}).get("count_live", 0),
             "priority": sub.priority,
             "hidden": sub.hidden,
             "deep_requested": sub.deep_requested,
@@ -229,7 +221,11 @@ def _channel_detail_dict(
     explored: bool,
     blocked: bool,
     stored: int,
+    count_normal: int,
+    count_short: int,
+    count_live: int,
     deep_requested: bool,
+    priority: int,
     tag_ids: list[int],
 ) -> dict:
     return {
@@ -252,9 +248,17 @@ def _channel_detail_dict(
         "explored": explored,
         "blocked": blocked,
         "stored_videos": stored,
+        # Per-type breakdown (Normal / Shorts / Live) — R14 moved it off the manager table onto the
+        # channel page. Same aggregation the manager list uses (count_normal = stored − shorts − live).
+        "count_normal": count_normal,
+        "count_short": count_short,
+        "count_live": count_live,
         # Deep-backfill state, so the channel page can offer "get full history" when the catalog
         # holds only the recent-backfill/RSS subset (video_count is YouTube's raw total).
         "deep_requested": deep_requested,
+        # This user's per-subscription feed priority (0 when not subscribed) so the channel page can
+        # offer the same priority stepper as the manager. Editable only while subscribed.
+        "priority": priority,
         "backfill_done": channel.backfill_done,
         "from_explore": channel.from_explore,
         "details_synced": channel.details_synced_at is not None,
@@ -300,7 +304,19 @@ def channel_detail(
         )
     ).first() is not None
     blocked = _is_blocked(db, user, channel_id)
-    stored = db.scalar(select(func.count(Video.id)).where(Video.channel_id == channel_id)) or 0
+    # Stored total + the Normal/Shorts/Live split in one grouped pass (same filters as the manager
+    # list), so the channel page can show the per-type breakdown R14 moved off the table.
+    n_all, n_short, n_live = db.execute(
+        select(
+            func.count(Video.id),
+            func.count(Video.id).filter(Video.is_short.is_(True)),
+            func.count(Video.id).filter(Video.live_status.in_(LIVE_OR_UPCOMING)),
+        ).where(Video.channel_id == channel_id)
+    ).one()
+    stored = int(n_all or 0)
+    count_short = int(n_short or 0)
+    count_live = int(n_live or 0)
+    count_normal = max(0, stored - count_short - count_live)
     tag_ids = list(
         db.scalars(
             select(ChannelTag.tag_id).where(
@@ -314,7 +330,11 @@ def channel_detail(
         explored=explored,
         blocked=blocked,
         stored=int(stored),
+        count_normal=count_normal,
+        count_short=count_short,
+        count_live=count_live,
         deep_requested=bool(sub.deep_requested) if sub else False,
+        priority=int(sub.priority) if sub else 0,
         tag_ids=tag_ids,
     )
 
@@ -337,7 +357,7 @@ def explore_channel(
         raise HTTPException(status_code=404, detail="Unknown channel")
     if _is_blocked(db, user, channel_id):
         raise HTTPException(status_code=403, detail="You've blocked this channel.")
-    if quota.remaining_today(db) <= sysconfig.get_int(db, "backfill_quota_reserve"):
+    if quota.backfill_reserve_reached():
         raise HTTPException(
             status_code=429,
             detail="The shared daily quota reserve is reached — try exploring later.",
@@ -421,6 +441,7 @@ class ChannelUpdateIn(BaseModel):
 def update_channel(
     channel_id: str,
     body: ChannelUpdateIn,
+    background: BackgroundTasks,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -445,12 +466,18 @@ def update_channel(
 
     # Opting a channel into full history should give an immediate feed: if we haven't even
     # fetched its recent uploads yet, do that one channel now (cheap) instead of waiting for
-    # the scheduler. Deep paging still follows on the scheduler's next run (recent-then-deep).
+    # the scheduler. (deep_turned_on is only ever True for a non-demo user — see the guard above.)
-    # (deep_turned_on is only ever True for a non-demo user — see the guard above.)
     if deep_turned_on and channel is not None and channel.recent_synced_at is None:
         with quota.attribute(user.id, quota.QuotaAction.VIDEOS_BACKFILL_RECENT):
             run_recent_backfill(db, [channel], max_channels=1)
 
+    # …and kick the FULL deep backfill for this one channel immediately in the background, so the
+    # whole catalogue lands in seconds instead of over the scheduler's paced 10-minute ticks. The
+    # request returns right away; the channel page's live poll shows the count climb. The scheduler
+    # still finishes a very large channel's tail on its normal runs (deep_requested stays set).
+    if deep_turned_on:
+        background.add_task(backfill_channel_now, channel_id, user.id)
+
     return {
         "id": channel_id,
         "priority": sub.priority,

backend/app/routes/config.py

@@ -11,9 +11,9 @@ from app import audit
 from app import email as email_mod
 from app import sysconfig
 from app.audit import AuditAction
+from app.auth import admin_user
 from app.db import get_db
 from app.models import User
-from app.routes.admin import admin_user
 
 router = APIRouter(prefix="/api/admin/config", tags=["admin"])
 

backend/app/routes/downloads.py

@@ -21,7 +21,7 @@ from app.config import settings
 from app.db import get_db
 from app.downloads import edit as editmod
 from app.downloads import links as linksmod
-from app.downloads import formats, quota, service, storage
+from app.downloads import quota, service, storage
 from app.models import (
     DownloadJob,
     DownloadLink,
@@ -40,6 +40,11 @@ admin_router = APIRouter(prefix="/api/admin/downloads", tags=["admin-downloads"]
 
 _VIDEO_ID = re.compile(r"^[A-Za-z0-9_-]{11}$")
 
+# Cap the per-user job listings so a heavy library can't return an unbounded result set. The
+# Download Center renders newest-first; 500 is far beyond any real manual-download history (and
+# matches the admin listing's own cap).
+_MAX_LIST = 500
+
 
 # --- source + serialization ----------------------------------------------------------------
 
@@ -334,6 +339,7 @@ def list_downloads(
             select(DownloadJob)
             .where(DownloadJob.user_id == user.id)
             .order_by(DownloadJob.created_at.desc(), DownloadJob.id.desc())
+            .limit(_MAX_LIST)
         )
         .scalars()
         .all()
@@ -379,7 +385,8 @@ def shared_with_me(
             select(DownloadJob)
             .join(DownloadShare, DownloadShare.job_id == DownloadJob.id)
             .where(DownloadShare.to_user_id == user.id)
-            .order_by(DownloadShare.created_at.desc())
+            .order_by(DownloadShare.created_at.desc(), DownloadJob.id.desc())
+            .limit(_MAX_LIST)
         )
         .scalars()
         .all()
@@ -446,18 +453,12 @@ def update_download_meta(
     return _serialize_job(db, job)
 
 
-def _set_status(db: Session, job: DownloadJob, status: str) -> None:
-    job.status = status
-    db.commit()
-
-
 @router.post("/{job_id}/pause")
 def pause_download(
     job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
     job = _own_job(db, user, job_id)
-    if job.status in ("queued", "running"):
+    service.pause(db, job)
-        _set_status(db, job, "paused")  # a running worker aborts cooperatively via the hook
     return _serialize_job(db, job)
 
 
@@ -466,19 +467,7 @@ def resume_download(
     job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
     job = _own_job(db, user, job_id)
-    if job.status in ("paused", "error"):
+    service.resume(db, job)
-        job.progress = 0
-        job.error = None
-        job.error_code = None
-        # If the shared asset itself failed, reset it to pending so the worker actually
-        # re-downloads — otherwise the requeued job would instantly re-inherit the asset's
-        # stale error (the worker short-circuits a job whose asset is already errored).
-        if job.asset_id:
-            asset = db.get(MediaAsset, job.asset_id)
-            if asset and asset.status == "error":
-                asset.status = "pending"
-                asset.error = None
-        _set_status(db, job, "queued")
     return _serialize_job(db, job)
 
 
@@ -502,33 +491,7 @@ def redownload_download(
         raise HTTPException(status_code=409, detail="Editor clips can't be re-downloaded.")
     if job.status in ("queued", "running", "paused"):
         raise HTTPException(status_code=409, detail="This download is still in progress.")
-
+    service.redownload(db, job)
-    # Resolve the fresh private asset FIRST (before touching any file). Salting with the current
-    # asset id makes it distinct from both the dedup pool and this job's current asset, so the
-    # insert never collides — no IntegrityError/rollback can strand us after a file was deleted.
-    spec = formats.normalize(job.profile_snapshot)
-    sig = formats.format_sig(spec, salt=f"{job.id}:{job.asset_id}")
-    asset = service.get_or_create_asset(db, job.source_kind, job.source_ref, sig)
-    service.populate_from_catalog(db, asset)
-
-    # Now drop the old hold — `_release_asset` deletes the old file + row only if this job was its
-    # last holder (a co-held asset is left intact for its other holders).
-    _release_asset(db, job)
-
-    asset.ref_count = (asset.ref_count or 0) + 1
-    job.asset_id = asset.id
-    job.status = "queued"
-    job.progress = 0
-    job.phase = None
-    job.error = None
-    job.speed_bps = None
-    job.eta_s = None
-    # Re-derive the display name (card title + Content-Disposition filename) from the freshly
-    # cleaned title — otherwise a name auto-set from an older, un-cleaned title (e.g. still carrying
-    # a "1.6M views · … |" social prefix) would survive the rebuild. The worker fills it on completion.
-    job.display_name = None
-    job.queue_pos = service.next_queue_pos(db)  # tail of the queue, not its stale original slot
-    db.commit()
     return _serialize_job(db, job)
 
 
@@ -537,10 +500,7 @@ def cancel_download(
     job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
     job = _own_job(db, user, job_id)
-    if job.status not in ("done", "canceled"):
+    service.cancel(db, job)
-        _release_asset(db, job)  # release while the job still counts as holding
-        job.status = "canceled"
-        db.commit()
     return _serialize_job(db, job)
 
 
@@ -549,39 +509,10 @@ def delete_download(
     job_id: int, user: User = Depends(require_human), db: Session = Depends(get_db)
 ) -> dict:
     job = _own_job(db, user, job_id)
-    _release_asset(db, job)
+    service.delete(db, job)
-    db.delete(job)
-    db.commit()
     return {"deleted": job_id}
 
 
-def _release_asset(db: Session, job: DownloadJob) -> None:
-    """Drop this job's hold on its asset when it leaves a holding state. Once NO job holds the
-    asset anymore, delete the file + row immediately — a deleted download should free its disk,
-    and the shared cache only needs to span *overlapping* holders (a later re-add just downloads
-    again). `error` counts as holding: enqueue always +1'd ref_count and the worker never
-    decrements on failure (ref_count is the route's job), so an errored job releases here on
-    delete — else its +1 leaks and a later resume→ready keeps the file pinned past its last holder.
-    Idempotent for the cancel path: cancel already released while the job was holding, then set it
-    `canceled` (∉ the set below), so delete-after-cancel is a no-op and never double-releases.
-
-    We DON'T delete an errored asset row here even at ref==0: another request may be concurrently
-    re-enqueuing the same (source,format) — get_or_create_asset would reset that row to `pending` and
-    +1 it, and deleting it under that would FK-null the new job's asset (a lost update on ref_count).
-    A ready asset is still freed at ref==0 (its file is the point); an orphaned errored row is cheap
-    (no file) and gets reused+reset by the next enqueue, or reclaimed by a later GC pass."""
-    if not job.asset_id or job.status not in ("queued", "running", "paused", "done", "error"):
-        return
-    asset = db.get(MediaAsset, job.asset_id)
-    if asset is None:
-        return
-    asset.ref_count = max(0, (asset.ref_count or 0) - 1)
-    if asset.ref_count == 0 and asset.status == "ready":
-        if asset.rel_path:
-            storage.delete_asset_files(settings.download_root, asset.rel_path)
-        db.delete(asset)
-
-
 # --- file download (range-aware, custom display name) --------------------------------------
 
 def _accessible_job(db: Session, user: User, job_id: int) -> DownloadJob:
@@ -908,7 +839,7 @@ def admin_list_downloads(
 ) -> list[dict]:
     jobs = (
         db.execute(
-            select(DownloadJob).order_by(DownloadJob.created_at.desc(), DownloadJob.id.desc()).limit(500)
+            select(DownloadJob).order_by(DownloadJob.created_at.desc(), DownloadJob.id.desc()).limit(_MAX_LIST)
         )
         .scalars()
         .all()

backend/app/routes/feed.py

@@ -1,29 +1,27 @@
-import base64
+from datetime import date, datetime, timezone
-import binascii
-import json
-import re
-from datetime import date, datetime, timedelta, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 from pydantic import BaseModel
-from sqlalchemy import BigInteger, Select, and_, cast, false, func, or_, select
+from sqlalchemy import and_, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
-from sqlalchemy.orm import Session, aliased
+from sqlalchemy.orm import Session
 from sqlalchemy.orm.exc import StaleDataError
 
 from app import quota
 from app.auth import current_user
 from app.db import get_db
+from app.feedquery import (
+    decode_cursor,
+    encode_cursor,
+    feed_summary,
+    filtered_query,
+    keyset_predicate,
+    order_by,
+    serialize,
+    sort_keys,
+)
 from app.models import (
-    LIVE_OR_UPCOMING,
-    BlockedChannel,
-    Channel,
     ChannelTag,
-    ExploredChannel,
-    Playlist,
-    PlaylistItem,
-    SearchFind,
-    Subscription,
     Tag,
     User,
     Video,
@@ -41,318 +39,12 @@ VALID_STATES = {"new", "watched", "hidden"}
 # Resume-position thresholds (mirror the client): positions below this are "didn't
 # really start" and within this of the end are "basically finished" — neither is worth
 # storing, so we clear the position instead (the video shows no progress bar).
+# NB: the Plex player intentionally uses a LARGER finish margin (30s) because it marks
+# long-form items watched, not just clears a resume bar — see routes/plex/playback.py.
 PROGRESS_MIN_SECONDS = 5
 FINISH_MARGIN_SECONDS = 10
 
 
-def _channel_url(channel_id: str, handle: str | None) -> str:
-    if handle and handle.startswith("@"):
-        return f"https://www.youtube.com/{handle}"
-    return f"https://www.youtube.com/channel/{channel_id}"
-
-
-def _saved_expr(user: User):
-    """A correlated EXISTS labelled `saved`: is this video in the user's Watch later list?
-    (Watch later is the built-in playlist that replaced the old per-video 'saved' status.)"""
-    return (
-        select(1)
-        .select_from(PlaylistItem)
-        .join(Playlist, Playlist.id == PlaylistItem.playlist_id)
-        .where(
-            Playlist.user_id == user.id,
-            Playlist.kind == "watch_later",
-            PlaylistItem.video_id == Video.id,
-        )
-        .exists()
-        .label("saved")
-    )
-
-
-def feed_columns(user: User, state) -> list:
-    """The shared feed-row projection (joined Channel fields + per-user watch state +
-    `saved`), consumed by both the feed query and the playlist-detail query so a new column
-    is added in exactly one place. `state` is the caller's aliased VideoState (outer-joined)."""
-    return [
-        Video.id,
-        Video.title,
-        Video.channel_id,
-        Channel.title.label("channel_title"),
-        Channel.thumbnail_url.label("channel_thumbnail"),
-        Channel.handle.label("channel_handle"),
-        Video.published_at,
-        Video.thumbnail_url,
-        Video.duration_seconds,
-        Video.view_count,
-        Video.is_short,
-        Video.live_status,
-        func.coalesce(state.status, "new").label("status"),
-        func.coalesce(state.position_seconds, 0).label("position_seconds"),
-        _saved_expr(user),
-    ]
-
-
-def _serialize(row) -> dict:
-    return {
-        "id": row.id,
-        "title": row.title,
-        "channel_id": row.channel_id,
-        "channel_title": row.channel_title,
-        "channel_thumbnail": row.channel_thumbnail,
-        "channel_url": _channel_url(row.channel_id, row.channel_handle),
-        "published_at": iso(row.published_at),
-        "thumbnail_url": row.thumbnail_url,
-        "duration_seconds": row.duration_seconds,
-        "view_count": row.view_count,
-        "is_short": row.is_short,
-        "live_status": row.live_status,
-        "status": row.status or "new",
-        "position_seconds": row.position_seconds or 0,
-        "saved": bool(getattr(row, "saved", False)),
-        "watch_url": f"https://www.youtube.com/watch?v={row.id}",
-    }
-
-
-def _filtered_query(
-    db: Session,
-    user: User,
-    *,
-    tags: list[int],
-    tag_mode: str,
-    channel_ids: list[str],
-    q: str | None,
-    min_duration: int | None,
-    max_duration: int | None,
-    max_age_days: int | None,
-    published_after: date | None,
-    published_before: date | None,
-    show_normal: bool,
-    include_shorts: bool,
-    include_live: bool,
-    show: str,
-    scope: str = "my",
-    library_source: str = "organic",
-    exclude_tag_category: str | None = None,
-) -> tuple[Select, object]:
-    """Build the feed query (joins + all WHERE filters), shared by /feed and /feed/count.
-    Returns the column-bearing select plus the priority/relevance rank expression for sorting.
-
-    `scope="my"` (default) restricts the feed to the user's own non-hidden subscriptions.
-    `scope="all"` shows every video in the shared catalog (any user's ingested channels);
-    the subscription is then only LEFT-joined so per-channel priority still resolves for
-    channels the user happens to be subscribed to. Per-user watch state stays private in
-    either mode via the VideoState outer join."""
-    state = aliased(VideoState)
-    status_expr = func.coalesce(state.status, "new")
-    position_expr = func.coalesce(state.position_seconds, 0)
-
-    query = select(*feed_columns(user, state)).join(
-        Channel, Channel.id == Video.channel_id
-    )
-
-    if scope == "all":
-        # Whole shared catalog; subscription is optional (only for priority sort).
-        query = query.outerjoin(
-            Subscription,
-            and_(
-                Subscription.channel_id == Video.channel_id,
-                Subscription.user_id == user.id,
-            ),
-        )
-    else:
-        # "Mine": the user's own videos = their non-hidden subscriptions OR videos they
-        # surfaced via their own live YouTube search. Both are LEFT-joined so the Source
-        # filter below can include either or both, and the subscription row stays available
-        # for the priority sort.
-        query = query.outerjoin(
-            Subscription,
-            and_(
-                Subscription.channel_id == Video.channel_id,
-                Subscription.user_id == user.id,
-                Subscription.hidden.is_(False),
-            ),
-        ).outerjoin(
-            SearchFind,
-            and_(SearchFind.video_id == Video.id, SearchFind.user_id == user.id),
-        )
-
-    query = query.outerjoin(
-        state, and_(state.video_id == Video.id, state.user_id == user.id)
-    )
-
-    # Hide videos the maintenance job has flagged as currently unplayable (deleted/private/
-    # abandoned). They're either deleted after a grace period or unhidden if they recover;
-    # either way they shouldn't show in any feed view meanwhile.
-    query = query.where(Video.unavailable_since.is_(None))
-
-    # Explored videos are PER-EXPLORER private: a via_explore video (ingested when someone
-    # opened an un-subscribed channel's page) is visible only to users who explored or
-    # subscribe to its channel, so one user's curiosity never leaks into everyone else's
-    # catalog. Applied in BOTH scopes; the channel page reaches its ephemeral videos by
-    # asking for scope=all + channel_ids (the channel is in this accessible set).
-    accessible_explore = (
-        select(Subscription.channel_id).where(Subscription.user_id == user.id)
-    ).union(
-        select(ExploredChannel.channel_id).where(ExploredChannel.user_id == user.id)
-    )
-    query = query.where(
-        or_(
-            Video.via_explore.is_(False),
-            Video.channel_id.in_(accessible_explore),
-        )
-    )
-
-    # Per-user channel blocklist: never show this user videos from a channel they blocked
-    # (applies to feed, Library, explore, and the channel page alike).
-    query = query.where(
-        Video.channel_id.notin_(
-            select(BlockedChannel.channel_id).where(BlockedChannel.user_id == user.id)
-        )
-    )
-
-    # Source filter. In the shared Library ("all" scope) it uses the GLOBAL via_search flag
-    # (search-discovered by anyone). In "my" scope it's the user's OWN provenance:
-    # "organic" = your subscriptions, "search" = videos you found via your own search,
-    # "all" = both. Default "organic" keeps the Mine feed = subscriptions only.
-    if scope == "all":
-        if library_source == "organic":
-            query = query.where(Video.via_search.is_(False))
-        elif library_source == "search":
-            query = query.where(Video.via_search.is_(True))
-        # "all" → both organic and search-discovered videos
-    else:
-        subscribed = Subscription.channel_id.isnot(None)
-        searched = SearchFind.video_id.isnot(None)
-        if library_source == "search":
-            query = query.where(searched)
-        elif library_source == "all":
-            query = query.where(or_(subscribed, searched))
-        else:  # "organic" (default): subscriptions only
-            query = query.where(subscribed)
-
-    if channel_ids:
-        # OR across the picked channels; every other filter still applies on top.
-        query = query.where(Video.channel_id.in_(channel_ids))
-    if min_duration is not None:
-        query = query.where(Video.duration_seconds >= min_duration)
-    if max_duration is not None:
-        query = query.where(Video.duration_seconds <= max_duration)
-    if max_age_days is not None:
-        cutoff = datetime.now(timezone.utc).timestamp() - max_age_days * 86400
-        query = query.where(
-            Video.published_at >= datetime.fromtimestamp(cutoff, tz=timezone.utc)
-        )
-    if published_after is not None:
-        start = datetime.combine(
-            published_after, datetime.min.time(), tzinfo=timezone.utc
-        )
-        query = query.where(Video.published_at >= start)
-    if published_before is not None:
-        end = datetime.combine(
-            published_before, datetime.min.time(), tzinfo=timezone.utc
-        ) + timedelta(days=1)
-        query = query.where(Video.published_at < end)
-    # Full-text relevance search over the weighted search document (title > creator keywords +
-    # the queries that surfaced the video > description; see Video.search_vector). YouTube-like
-    # "fuzzy" matching: word-order-independent, multi-word AND, prefix on the word being typed,
-    # accent-insensitive (unaccent_simple). The channel name still matches as a substring so
-    # channel searches work. `rank_expr` (weight-aware ts_rank) drives the "relevance" sort.
-    rank_expr = None
-    if q:
-        ts_str = _to_tsquery_str(q)
-        if ts_str:
-            tsq = func.to_tsquery("public.unaccent_simple", ts_str)
-            query = query.where(
-                or_(
-                    Video.search_vector.op("@@")(tsq),
-                    func.unaccent(Channel.title).ilike(func.unaccent(f"%{q}%")),
-                )
-            )
-            # Scale ts_rank (a float4) to an integer score so the keyset cursor compares it
-            # EXACTLY — a raw float4 vs the float8 cursor value mismatches on round-trip and
-            # breaks paging (the same page repeats). 1e6 granularity is ample; ties break on
-            # published_at then id.
-            rank_expr = cast(func.ts_rank(Video.search_vector, tsq) * 1000000, BigInteger)
-        else:
-            # No usable tokens (e.g. only punctuation): fall back to a plain substring match.
-            like = func.unaccent(f"%{q}%")
-            query = query.where(
-                or_(
-                    func.unaccent(Video.title).ilike(like),
-                    func.unaccent(Channel.title).ilike(like),
-                )
-            )
-
-    if tags:
-        # AND across tag categories (e.g. language AND topic narrows), OR within a
-        # category; the any/all toggle controls multiple topic tags.
-        cat_rows = db.execute(select(Tag.id, Tag.category).where(Tag.id.in_(tags))).all()
-        by_category: dict[str, list[int]] = {}
-        for tag_id, category in cat_rows:
-            by_category.setdefault(category, []).append(tag_id)
-        # Facet counting drops the category being counted so its own chips don't zero each
-        # other out (standard drill-down faceting: a category's count ignores its own
-        # selections but still honours the other categories' filters).
-        if exclude_tag_category:
-            by_category.pop(exclude_tag_category, None)
-        visible = or_(ChannelTag.user_id.is_(None), ChannelTag.user_id == user.id)
-        for category, ids in by_category.items():
-            if category == "topic" and tag_mode == "and" and len(ids) > 1:
-                sub = (
-                    select(ChannelTag.channel_id)
-                    .where(ChannelTag.tag_id.in_(ids), visible)
-                    .group_by(ChannelTag.channel_id)
-                    .having(func.count(func.distinct(ChannelTag.tag_id)) == len(set(ids)))
-                )
-            else:
-                sub = select(ChannelTag.channel_id).where(
-                    ChannelTag.tag_id.in_(ids), visible
-                )
-            query = query.where(Video.channel_id.in_(sub))
-
-    # Content type: Normal / Shorts / Live·Upcoming as a union of enabled types.
-    # Explicit Watched/Saved/Hidden views show every type so nothing goes missing.
-    explicit_view = show in ("watched", "hidden")
-    if not explicit_view:
-        type_clauses = []
-        if show_normal:
-            type_clauses.append(
-                and_(Video.is_short.is_(False), Video.live_status.notin_(LIVE_OR_UPCOMING))
-            )
-        if include_shorts:
-            type_clauses.append(Video.is_short.is_(True))
-        if include_live:
-            type_clauses.append(Video.live_status.in_(LIVE_OR_UPCOMING))
-        query = query.where(or_(*type_clauses) if type_clauses else false())
-
-    if show == "unwatched":
-        query = query.where(status_expr.notin_(("watched", "hidden")))
-    elif show == "in_progress":
-        # Started but not finished: a stored resume position, not yet watched/hidden.
-        query = query.where(
-            and_(position_expr > 0, status_expr.notin_(("watched", "hidden")))
-        )
-    elif show == "watched":
-        query = query.where(status_expr == "watched")
-    elif show == "hidden":
-        query = query.where(status_expr == "hidden")
-    else:  # all
-        query = query.where(status_expr != "hidden")
-
-    return query, rank_expr
-
-
-def _to_tsquery_str(q: str) -> str | None:
-    """Turn free-text into a to_tsquery() string: word runs ANDed together, the LAST word
-    prefix-matched (`:*`) for as-you-type search — e.g. "ti amo magyar" → "ti & amo & magyar:*".
-    Only `\\w` runs containing an alphanumeric are kept, so no tsquery operators can leak in
-    (the string is built from sanitised tokens, never the raw query)."""
-    tokens = [t for t in re.findall(r"\w+", q, flags=re.UNICODE) if any(c.isalnum() for c in t)]
-    if not tokens:
-        return None
-    tokens[-1] = tokens[-1] + ":*"
-    return " & ".join(tokens)
-
-
 # Shared query parameters for /feed and /feed/count.
 def _feed_params(
     tags: list[int] = Query(default=[]),
@@ -390,101 +82,6 @@ def _feed_params(
     }
 
 
-# --- Keyset (cursor) pagination ---------------------------------------------
-#
-# Each sort is described as an ordered list of key columns (expression + direction
-# + whether it can be NULL + a JSON round-trip kind), always with Video.id as the
-# final, unique tiebreaker. This drives BOTH the ORDER BY and the keyset WHERE so
-# they can never drift apart — the prerequisite for correct cursor paging. Keyset
-# 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]:
-    pub = {"expr": Video.published_at, "asc": False, "nullable": True, "kind": "dt"}
-    table: dict[str, list[dict]] = {
-        "newest": [pub],
-        "oldest": [{**pub, "asc": True}],
-        "views": [{"expr": Video.view_count, "asc": False, "nullable": True, "kind": "num"}],
-        "views_asc": [{"expr": Video.view_count, "asc": True, "nullable": True, "kind": "num"}],
-        "duration_desc": [{"expr": Video.duration_seconds, "asc": False, "nullable": True, "kind": "num"}],
-        "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"}],
-        "subscribers": [{"expr": Channel.subscriber_count, "asc": False, "nullable": True, "kind": "num"}],
-        "subscribers_asc": [{"expr": Channel.subscriber_count, "asc": True, "nullable": True, "kind": "num"}],
-        # Your per-channel priority (set in the channel manager), newest first within a tier.
-        # coalesce keeps it null-safe in "all" scope where unsubscribed channels have no row.
-        "priority": [{"expr": func.coalesce(Subscription.priority, 0), "asc": False, "nullable": False, "kind": "num"}, pub],
-        "priority_asc": [{"expr": func.coalesce(Subscription.priority, 0), "asc": True, "nullable": False, "kind": "num"}, pub],
-        # Deterministic per-seed shuffle: the same seed yields the same total order, so
-        # the cursor stays valid across pages of one shuffled run.
-        "shuffle": [{"expr": func.md5(func.concat(Video.id, str(seed))), "asc": True, "nullable": False, "kind": "str"}],
-    }
-    # Relevance (search-result ranking) only exists when there's a query to rank against;
-    # without `rank_expr` it falls through to newest. Ties break by newest, then id.
-    if rank_expr is not None:
-        table["relevance"] = [
-            {"expr": rank_expr, "asc": False, "nullable": False, "kind": "num"},
-            pub,
-        ]
-    return table.get(sort) or table["newest"]
-
-
-def _order_by(keys: list[dict]):
-    cols = []
-    for k in keys:
-        c = k["expr"].asc() if k["asc"] else k["expr"].desc()
-        cols.append(c.nulls_last() if k["nullable"] else c)
-    cols.append(Video.id.asc())  # unique final tiebreaker
-    return cols
-
-
-def _keyset_predicate(keys: list[dict], cursor_id: str):
-    """WHERE clause selecting rows strictly AFTER the cursor in the sort order.
-
-    Lexicographic over the key columns then id, NULL-aware for `nulls_last`: a NULL
-    sorts after every non-NULL value, so a cursor sitting on a non-NULL value must
-    also pull in the NULL group, and equality treats NULL == NULL."""
-    def eq(k):
-        return k["expr"].is_(None) if k["value"] is None else k["expr"] == k["value"]
-
-    def after(k):
-        if k["value"] is None:
-            return false()  # nulls are last; nothing sorts strictly after them
-        cmp = k["expr"] > k["value"] if k["asc"] else k["expr"] < k["value"]
-        return or_(cmp, k["expr"].is_(None)) if k["nullable"] else cmp
-
-    branches = []
-    for j in range(len(keys)):
-        branches.append(and_(*[eq(keys[i]) for i in range(j)], after(keys[j])))
-    branches.append(and_(*[eq(k) for k in keys], Video.id > cursor_id))
-    return or_(*branches)
-
-
-def _encode_cursor(keys: list[dict], row) -> str:
-    vals = []
-    for i, k in enumerate(keys):
-        v = getattr(row, f"_k{i}")
-        vals.append(v.isoformat() if (v is not None and k["kind"] == "dt") else v)
-    payload = json.dumps({"k": vals, "id": row.id})
-    return base64.urlsafe_b64encode(payload.encode()).decode()
-
-
-def _decode_cursor(keys: list[dict], cursor: str) -> tuple[list, str]:
-    try:
-        payload = json.loads(base64.urlsafe_b64decode(cursor.encode()))
-        raw = payload["k"]
-        if len(raw) != len(keys):
-            raise ValueError("key arity mismatch")
-        vals = [
-            datetime.fromisoformat(v) if (v is not None and k["kind"] == "dt") else v
-            for k, v in zip(keys, raw)
-        ]
-        return vals, payload["id"]
-    except (binascii.Error, json.JSONDecodeError, KeyError, ValueError, TypeError):
-        raise HTTPException(status_code=400, detail="Invalid feed cursor")
-
-
 @router.get("/feed")
 def get_feed(
     params: dict = Depends(_feed_params),
@@ -495,25 +92,31 @@ def get_feed(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    query, rank_expr = _filtered_query(db, user, **params)
+    query, rank_expr = filtered_query(db, user, **params)
-    keys = _sort_keys(sort, seed, rank_expr)
+    keys = sort_keys(sort, seed, rank_expr)
 
     # 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)])
-    query = query.order_by(*_order_by(keys))
+    query = query.order_by(*order_by(keys))
 
     if cursor:
-        vals, cursor_id = _decode_cursor(keys, cursor)
+        # The read-model raises a plain ValueError on a malformed cursor; translate it to the
+        # HTTP 400 here so feedquery stays web-framework-free.
+        try:
+            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
         for k, v in zip(keys, vals):
             k["value"] = v
-        query = query.where(_keyset_predicate(keys, cursor_id))
+        query = query.where(keyset_predicate(keys, cursor_id))
 
     rows = db.execute(query.limit(limit + 1)).all()
     has_more = len(rows) > limit
     page = rows[:limit]
     return {
-        "items": [_serialize(r) for r in page],
+        "items": [serialize(r) for r in page],
-        "next_cursor": _encode_cursor(keys, page[-1]) if (has_more and page) else None,
+        "next_cursor": encode_cursor(keys, page[-1]) if (has_more and page) else None,
         "has_more": has_more,
         "limit": limit,
     }
@@ -525,7 +128,10 @@ def get_feed_count(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    query, _rank = _filtered_query(db, user, **params)
+    # SUPERSEDED by /feed/summary (PERF-13) — the app no longer calls this. Kept as the reference
+    # oracle that test_feed_summary_matches_count_plus_facets asserts /feed/summary's `count` against;
+    # remove both together with that test if this endpoint is ever retired.
+    query, _rank = filtered_query(db, user, **params)
     total = db.scalar(select(func.count()).select_from(query.subquery()))
     return {"count": total or 0}
 
@@ -544,7 +150,11 @@ def get_facets(
 
     The count is the number of distinct channels that have at least one video in the current
     view, matching the existing channel-count chip semantics. JSON object keys are strings
-    (tag ids)."""
+    (tag ids).
+
+    SUPERSEDED by /feed/summary (PERF-13) — the app no longer calls this. Kept as the reference
+    oracle for test_feed_summary_matches_count_plus_facets (it asserts /feed/summary's `facets`
+    against these `counts`); retire the two together."""
     visible = or_(ChannelTag.user_id.is_(None), ChannelTag.user_id == user.id)
     counts: dict[int, int] = {}
     for category in ("language", "topic", "other"):
@@ -553,7 +163,7 @@ def get_facets(
         # keeps them applied, so each remaining chip narrows to channels that ALSO have all
         # already-selected topics — and tags that can't co-occur drop to zero (hidden).
         conjunctive = category == "topic" and params.get("tag_mode") == "and"
-        base, _rank = _filtered_query(
+        base, _rank = filtered_query(
             db,
             user,
             **{**params, "exclude_tag_category": None if conjunctive else category},
@@ -572,6 +182,19 @@ def get_facets(
     return {"counts": counts}
 
 
+@router.get("/feed/summary")
+def get_feed_summary(
+    params: dict = Depends(_feed_params),
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The sidebar's total video count + per-tag channel facet counts in ONE request and ONE grouped
+    query, replacing the separate /feed/count (1 pass) + /facets (3 passes) the FE fired on every filter
+    change (PERF-13). Response: {"count": <videos>, "facets": {<tag_id>: <channel_count>}} — the same
+    numbers /feed/count's `count` and /facets' `counts` return, so the two are interchangeable."""
+    return feed_summary(db, user, **params)
+
+
 class VideoStateIn(BaseModel):
     status: str
 

backend/app/routes/me.py

@@ -72,6 +72,18 @@ def switch_account(
         # Don't make a suspended account the active one — the next request's current_user would
         # see the suspension and clear the WHOLE wallet session, logging out every account here.
         raise HTTPException(status_code=403, detail="That account is suspended.")
+    # Same reasoning for a REVOKED session (a password reset/change or "log out everywhere" bumped the
+    # account's epoch): making it the session default would trip current_user's epoch check on the next
+    # request and clear the whole wallet. Mirror the suspend guard — drop the stale account from the
+    # switch list and refuse, rather than logging everyone out. (B-core-9)
+    epochs = request.session.get("epochs") or {}
+    if int(epochs.get(str(target), 0)) != (u.session_epoch or 0):
+        request.session["account_ids"] = [
+            a for a in (request.session.get("account_ids") or []) if a != target
+        ]
+        raise HTTPException(
+            status_code=403, detail="That account was signed out elsewhere — sign in again."
+        )
     request.session["user_id"] = target
     return {"ok": True, "user_id": target}
 

backend/app/routes/playlists.py

@@ -1,6 +1,7 @@
-"""Local playlists: per-user named, ordered collections of videos from the shared
+"""Playlists: per-user named, ordered collections of videos from the shared catalog. Local
-catalog. Foundation phase = local only (create / rename / delete, add / remove / reorder
+CRUD (create / rename / delete, add / remove / reorder items) plus YouTube two-way sync —
-items). YouTube two-way sync (mirror existing playlists, push edits) lands in later phases."""
+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 fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
 from sqlalchemy import func, select, and_
@@ -9,8 +10,8 @@ from sqlalchemy.orm import Session, aliased
 from app import quota
 from app.auth import current_user, has_read_scope, has_write_scope, require_write_scope
 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.routes.feed import _serialize, feed_columns
 from app.sync.playlists import (
     plan_push,
     push_playlist,
@@ -400,7 +401,7 @@ def get_playlist(
         "source": pl.source,
         "yt_playlist_id": pl.yt_playlist_id,
         "dirty": pl.dirty,
-        "items": [_serialize(r) for r in rows],
+        "items": [serialize(r) for r in rows],
     }
 
 

backend/app/routes/plex/__init__.py

@@ -0,0 +1,30 @@
+"""Plex route package — assembles the admin/browse/playback sub-routers.
+
+Read endpoints (libraries/browse/show/image) are available to ANY authenticated user (demo +
+pure-Siftlode included) — this is an access layer to the Plex library WITHOUT requiring a plex.tv
+account, and playback is a local file. Admin endpoints test the connection and run the catalog sync.
+
+Split out of the former single routes/plex.py (R12 S1). `router` keeps the same shape the app
+wiring expects (`plex_routes.router`), so main.py is unchanged.
+"""
+
+from fastapi import APIRouter
+
+from app.routes.plex import (
+    admin,
+    browse,
+    collections,
+    detail,
+    people,
+    playback,
+    playlists,
+)
+
+router = APIRouter()
+router.include_router(admin.router)
+router.include_router(browse.router)
+router.include_router(collections.router)
+router.include_router(detail.router)
+router.include_router(people.router)
+router.include_router(playback.router)
+router.include_router(playlists.router)

backend/app/routes/plex/_shared.py

@@ -0,0 +1,41 @@
+"""Shared helpers, serializers and constants for the plex route package."""
+
+import logging
+
+from fastapi import HTTPException
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.models import (
+    PlexItem,
+    PlexLibrary,
+)
+from app.plex.lookups import by_rating_key
+
+log = logging.getLogger("siftlode.plex")
+
+
+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")
+    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"
+
+
+def _content_libs(db: Session) -> tuple[list[int], list[int]]:
+    """The BROWSABLE content libraries, partitioned into (movie_lib_ids, show_lib_ids) — the single
+    source of the browse scope. Excludes HU overlay libraries (`overlay_of` set): those are never
+    browsed on their own, they only lend their Hungarian metadata to the EN twin's rows (E5 S5)."""
+    libs = db.execute(
+        select(PlexLibrary).where(
+            PlexLibrary.enabled.is_(True), PlexLibrary.overlay_of.is_(None)
+        )
+    ).scalars().all()
+    movie_lib_ids = [lb.id for lb in libs if lb.kind == "movie"]
+    show_lib_ids = [lb.id for lb in libs if lb.kind == "show"]
+    return movie_lib_ids, show_lib_ids

backend/app/routes/plex/admin.py

@@ -0,0 +1,171 @@
+"""Plex admin: connection test, catalog sync, and owner watch-link config."""
+
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app import sysconfig
+from app.auth import admin_user, current_user
+from app.db import get_db
+from app.models import (
+    PlexItem,
+    PlexLink,
+    User,
+)
+from app.plex import paths as plex_paths
+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
+
+router = APIRouter(prefix="/api/plex", tags=["plex"])
+
+
+@router.post("/test")
+def test_connection(
+    _: User = Depends(admin_user), db: Session = Depends(get_db)
+) -> dict:
+    """Admin: verify the configured Plex server URL + token, returning the server name and the
+    movie/show sections (for the config library-picker). Also probes ONE real media file through
+    the local mount, so a missing bind-mount / wrong path-map is caught here rather than only
+    surfacing as a dead player later."""
+    try:
+        with PlexClient(db) as plex:
+            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 PlexError as e:
+        raise HTTPException(status_code=422, detail=f"Plex connection failed: {e}")
+    return {
+        "ok": True,
+        "server_name": info.get("friendlyName") or info.get("title1") or "Plex",
+        "version": info.get("version"),
+        "sections": [
+            {
+                "key": str(s.get("key")),
+                "title": s.get("title"),
+                "type": s.get("type"),
+                "count": s.get("count"),
+            }
+            for s in sections
+            if s.get("type") in ("movie", "show")
+        ],
+        "media_check": media_check,
+    }
+
+
+def _sample_plex_path(
+    db: Session, plex: PlexClient, sections: list[dict]
+) -> str | None:
+    """A real Plex-side media file path to validate the mount + path-map against. Prefers the
+    already-mirrored catalog (cheap); before the first sync, pulls one movie leaf from an enabled
+    section straight from Plex."""
+    fp = db.scalar(select(PlexItem.file_path).where(PlexItem.file_path.isnot(None)))
+    if fp:
+        return fp
+    wanted = plex_sync._enabled_section_keys(db)
+    for s in sections:
+        if s.get("type") != "movie":
+            continue
+        key = str(s.get("key"))
+        if wanted is not None and key not in wanted:
+            continue
+        items, _ = plex.section_items(key, 1, 0, 1)
+        if items:
+            fp = plex_sync._media_facts(items[0]).get("file_path")
+            if fp:
+                return fp
+    return None
+
+
+def _media_check(db: Session, plex: PlexClient, sections: list[dict]) -> dict:
+    """Resolve a sample Plex file path to its local mount path and confirm it's readable, so the
+    admin sees at Test time whether the physical media is actually reachable (bind-mount +
+    path-map correct). ``checked=False`` when no sample is available (empty library)."""
+    plex_path = _sample_plex_path(db, plex, sections)
+    if not plex_path:
+        return {"checked": False}
+    local_path = plex_paths.map_path(db, plex_path)
+    ok = plex_paths.local_media_path(db, plex_path) is not None
+    return {"checked": True, "ok": ok, "plex_path": plex_path, "local_path": local_path}
+
+
+@router.post("/sync")
+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)
+
+
+def _link_dict(link: PlexLink | None) -> dict:
+    return {
+        "linked": link is not None,
+        "sync_enabled": bool(link and link.sync_enabled),
+        "uses_admin": bool(link and link.uses_admin),
+        "initial_import_done": bool(link and link.initial_import_done),
+        "last_watch_sync_at": iso(link.last_watch_sync_at) if link else None,
+    }
+
+
+@router.get("/watch/link")
+def watch_link_status(
+    user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
+    """This user's Plex watch-sync link status (drives the Settings toggle)."""
+    link = db.execute(
+        select(PlexLink).where(PlexLink.user_id == user.id)
+    ).scalars().first()
+    return _link_dict(link)
+
+
+class WatchLinkIn(BaseModel):
+    enabled: bool = False
+
+
+@router.post("/watch/link")
+def watch_link_set(
+    body: WatchLinkIn,
+    user: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Admin: turn two-way Plex watch-sync on/off for THIS (owner) account. The link uses the server
+    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.")
+    enabled = body.enabled
+    link = db.execute(
+        select(PlexLink).where(PlexLink.user_id == user.id)
+    ).scalars().first()
+    if link is None:
+        link = PlexLink(
+            user_id=user.id, uses_admin=True, linked_at=datetime.now(timezone.utc)
+        )
+        db.add(link)
+    link.sync_enabled = enabled
+    db.commit()
+
+    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}
+
+
+@router.post("/watch/import")
+def watch_import_now(
+    user: User = Depends(admin_user), db: Session = Depends(get_db)
+) -> dict:
+    """Admin: (re-)run the "Plex is master" import for this account — Plex re-wins on the
+    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.")
+    result = plex_watch.import_owner_watch_state(db, link)
+    return {**_link_dict(link), "import": result}

backend/app/routes/plex/browse.py

@@ -0,0 +1,469 @@
+"""Plex browse: the library list, the unified cross-library browse feed, and its faceted filters."""
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import (
+    Integer,
+    String,
+    and_,
+    cast,
+    func,
+    literal,
+    null,
+    select,
+)
+from sqlalchemy.orm import Session, aliased
+
+from app import sysconfig
+from app.auth import current_user
+from app.db import get_db
+from app.models import (
+    PlexItem,
+    PlexLibrary,
+    PlexShow,
+    PlexState,
+    User,
+)
+from app.plex import rollup
+from app.plex.cards import episode_card
+from app.plex.query import (
+    FIELD_COLUMNS,
+    TS_CONFIG,
+    LibraryFilters,
+    apply_meta_filters,
+    apply_movie_state_filter,
+    apply_show_state_filter,
+    field_recheck,
+    genres_col,
+    meta_filter_conds,
+    movie_status_case,
+    show_status_case,
+    split_csv,
+    title_col,
+    vector_col,
+    vector_match,
+)
+from app.routes.plex._shared import _content_libs, _norm_lang
+from app.utils import to_tsquery_str
+
+router = APIRouter(prefix="/api/plex", tags=["plex"])
+
+
+@router.get("/libraries")
+def list_libraries(
+    user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
+    """The mirrored libraries the user can browse (drives the Plex scope selector). HU overlay
+    libraries are excluded — they're not browsable, they only feed the EN twin's Hungarian metadata."""
+    libs = db.execute(
+        select(PlexLibrary)
+        .where(PlexLibrary.overlay_of.is_(None))
+        .order_by(PlexLibrary.kind.desc(), PlexLibrary.title)
+    ).scalars().all()
+    out = []
+    for lib in libs:
+        if lib.kind == "movie":
+            count = db.scalar(
+                select(func.count(PlexItem.id)).where(
+                    PlexItem.library_id == lib.id, PlexItem.kind == "movie"
+                )
+            )
+        else:
+            count = db.scalar(
+                select(func.count(PlexShow.id)).where(PlexShow.library_id == lib.id)
+            )
+        out.append(
+            {
+                "key": lib.plex_key,
+                "title": lib.title,
+                "kind": lib.kind,
+                "count": count or 0,
+            }
+        )
+    return {"enabled": sysconfig.get_bool(db, "plex_enabled"), "libraries": out}
+
+
+@router.get("/library")
+def unified_library(
+    scope: str = "both",
+    q: str | None = None,
+    field: str = "all",
+    sort: str = "added",
+    sort_dir: str = "desc",
+    show: str = "all",
+    lang: str = "en",
+    offset: int = 0,
+    limit: int = Query(default=40, ge=1, le=100),
+    f: LibraryFilters = Depends(),
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Unified cross-library browse: movies + shows in ONE mixed, paginated feed, scoped to
+    movie|show|both, with the shared filters/search/watch-state (a show's state is the aggregate of
+    its episodes). On a search that also matches episodes (and shows are in scope), the matching
+    episodes come back in a separate `episodes` list (grouped result — the 'Episodes' section)."""
+    offset = max(0, offset)
+    lang = _norm_lang(lang)
+    p = f.as_dict()
+    movie_lib_ids, show_lib_ids = _content_libs(db)
+    want_movies = scope in ("movie", "both") and bool(movie_lib_ids)
+    want_shows = scope in ("show", "both") and bool(show_lib_ids)
+
+    ts = to_tsquery_str(q) if q else None
+    tsq = func.to_tsquery(TS_CONFIG, ts) if ts else None
+    if field not in FIELD_COLUMNS and field != "all":
+        field = "all"
+    # `episode` scope targets episode rows only — the movie/show grid stays empty; the recheck for
+    # the specific title/people/summary fields is a strict narrowing on top of the GIN prefilter.
+    grid_field = field != "episode"
+    recheck = (
+        field_recheck if tsq is not None and field not in ("all", "episode") else None
+    )
+
+    selects = []
+    if want_movies and grid_field:
+        st = aliased(PlexState)
+        m_status = movie_status_case(st)
+        mq = (
+            select(
+                PlexItem.rating_key.label("rk"),
+                literal("movie").label("kind"),
+                title_col(PlexItem, lang).label("title"),
+                PlexItem.year.label("year"),
+                PlexItem.rating.label("rating"),
+                PlexItem.added_at.label("added_at"),
+                PlexItem.originally_available_at.label("rel"),
+                PlexItem.duration_s.label("duration_s"),
+                PlexItem.playable.label("playable"),
+                cast(null(), Integer).label("season_count"),
+                func.coalesce(st.position_seconds, 0).label("position_seconds"),
+                m_status.label("status"),
+                (
+                    func.ts_rank(vector_col(PlexItem, lang), tsq)
+                    if tsq is not None
+                    else literal(0.0)
+                ).label("rank"),
+            )
+            .outerjoin(st, and_(st.item_id == PlexItem.id, st.user_id == user.id))
+            .where(PlexItem.kind == "movie", PlexItem.library_id.in_(movie_lib_ids))
+        )
+        mq = apply_movie_state_filter(mq, st, show)
+        mq = apply_meta_filters(mq, PlexItem, p, lang)
+        if f.duration_min is not None:
+            mq = mq.where(PlexItem.duration_s >= f.duration_min)
+        if f.duration_max is not None:
+            mq = mq.where(PlexItem.duration_s <= f.duration_max)
+        if tsq is not None:
+            mq = mq.where(vector_match(PlexItem, lang, tsq))
+        if recheck is not None:
+            mq = mq.where(recheck(PlexItem, field, tsq, lang))
+        selects.append(mq)
+    if want_shows and grid_field:
+        agg = rollup.agg_subquery(db, user.id).subquery()
+        tot = func.coalesce(agg.c.total, 0)
+        wat = func.coalesce(agg.c.watched, 0)
+        inp = func.coalesce(agg.c.inprog, 0)
+        s_status = show_status_case(tot, wat, inp)
+        sq = (
+            select(
+                PlexShow.rating_key.label("rk"),
+                literal("show").label("kind"),
+                title_col(PlexShow, lang).label("title"),
+                PlexShow.year.label("year"),
+                PlexShow.rating.label("rating"),
+                PlexShow.added_at.label("added_at"),
+                PlexShow.originally_available_at.label("rel"),
+                cast(null(), Integer).label("duration_s"),
+                cast(null(), String).label("playable"),
+                PlexShow.child_count.label("season_count"),
+                literal(0).label("position_seconds"),
+                s_status.label("status"),
+                (
+                    func.ts_rank(vector_col(PlexShow, lang), tsq)
+                    if tsq is not None
+                    else literal(0.0)
+                ).label("rank"),
+            )
+            .outerjoin(agg, agg.c.show_id == PlexShow.id)
+            .where(PlexShow.library_id.in_(show_lib_ids))
+        )
+        sq = apply_show_state_filter(sq, tot, wat, inp, show)
+        sq = apply_meta_filters(sq, PlexShow, p, lang)
+        if tsq is not None:
+            sq = sq.where(vector_match(PlexShow, lang, tsq))
+        if recheck is not None:
+            sq = sq.where(recheck(PlexShow, field, tsq, lang))
+        selects.append(sq)
+
+    items = []
+    total = 0
+    if selects:
+        union = (
+            selects[0] if len(selects) == 1 else selects[0].union_all(*selects[1:])
+        )
+        u = union.subquery()
+        total = db.scalar(select(func.count()).select_from(u)) or 0
+
+        if tsq is not None:
+            order = [u.c.rank.desc()]
+        else:
+            col = {
+                "title": func.lower(u.c.title),
+                "year": u.c.year,
+                "rating": u.c.rating,
+                "duration": u.c.duration_s,
+                "release": u.c.rel,
+            }.get(sort, u.c.added_at)
+            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()
+
+        for r in rows:
+            if r.kind == "movie":
+                items.append(
+                    {
+                        "id": r.rk,
+                        "type": "movie",
+                        "title": r.title,
+                        "year": r.year,
+                        "duration_seconds": r.duration_s,
+                        "thumb": f"/api/plex/image/{r.rk}",
+                        "playable": r.playable,
+                        "status": r.status,
+                        "position_seconds": r.position_seconds,
+                    }
+                )
+            else:
+                items.append(
+                    {
+                        "id": r.rk,
+                        "type": "show",
+                        "title": r.title,
+                        "year": r.year,
+                        "thumb": f"/api/plex/image/{r.rk}",
+                        "season_count": r.season_count,
+                        "status": r.status,
+                    }
+                )
+
+    # Episode "grouped result" section: shown for Everywhere (full-vector match, today's behaviour)
+    # and for the Episode scope (title-only match, empty item grid). The title/people/summary scopes
+    # target the movie/show grid, so they suppress episodes.
+    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
+        )
+        eps = db.execute(
+            select(PlexItem, ep_st, PlexShow.title.label("show_title"))
+            .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),
+            )
+            .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
+            episodes.append(card)
+
+    return {
+        "scope": scope,
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+        "items": items,
+        "episodes": episodes,
+    }
+
+
+@router.get("/facets")
+def facets(
+    scope: str = "both",
+    show: str = "all",
+    lang: str = "en",
+    f: LibraryFilters = Depends(),
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Available filter values for the unified library (scope movie|show|both), ADAPTED to the active
+    filters (faceted search): each group's values/bounds are computed with all the OTHER active
+    filters applied but NOT its own — so selecting a filter narrows what the other groups offer, while
+    a multi-select group still lets you add more. Merged across the scope's libraries; duration is
+    movie-only. (Search text is not factored in — facets track the sidebar filters.)"""
+    empty = {
+        "genres": [],
+        "content_ratings": [],
+        "year_min": None,
+        "year_max": None,
+        "rating_max": None,
+        "duration_min": None,
+        "duration_max": None,
+    }
+    all_movie_ids, all_show_ids = _content_libs(db)
+    movie_ids = all_movie_ids if scope in ("movie", "both") else []
+    show_ids = all_show_ids if scope in ("show", "both") else []
+    if not movie_ids and not show_ids:
+        return empty
+    lang = _norm_lang(lang)
+    p = f.as_dict()
+
+    uid = user.id
+
+    def wsq(query, model, ids, pp, kind_movie, with_dur):
+        """Apply the (self-excluded) metadata filters + library scope + the per-user watch-state to a
+        facet aggregation query, so the facets reflect exactly the visible result set."""
+        query = query.where(model.library_id.in_(ids), *meta_filter_conds(model, pp, lang))
+        if kind_movie:
+            query = query.where(model.kind == "movie")
+            if with_dur and pp.get("duration_min") is not None:
+                query = query.where(model.duration_s >= pp["duration_min"])
+            if with_dur and pp.get("duration_max") is not None:
+                query = query.where(model.duration_s <= pp["duration_max"])
+            # Join watch-state and reuse the grid's exact movie state filter (unified_library) —
+            # hidden movies never appear in the grid, so they must not inflate facet counts/bounds either.
+            st = aliased(PlexState)
+            query = query.outerjoin(st, and_(st.item_id == model.id, st.user_id == uid))
+            query = apply_movie_state_filter(query, st, show)
+        else:
+            if show in ("watched", "in_progress", "unwatched"):
+                agg = rollup.agg_subquery(db, uid).subquery()
+                query = query.outerjoin(agg, agg.c.show_id == model.id)
+                tot = func.coalesce(agg.c.total, 0)
+                wat = func.coalesce(agg.c.watched, 0)
+                inp = func.coalesce(agg.c.inprog, 0)
+                query = apply_show_state_filter(query, tot, wat, inp, show)
+        return query
+
+    genre_counts: dict[str, int] = {}
+    cr_counts: dict[str, int] = {}
+    years: list[int] = []
+    ratings: list[float] = []
+    durs: list[int] = []
+
+    def per_table(model, ids, kind_movie: bool) -> None:
+        if not ids:
+            return
+        # Genres — in "any"/OR mode, exclude the genre filter itself so each offered genre is a valid
+        # OR-addition that only widens (keep adding). In "all"/AND mode, KEEP the filter applied so we
+        # offer only genres that CO-OCCUR on the current result set — a non-co-occurring genre would AND
+        # the result down to zero, i.e. a dead-end chip. (The already-selected genres still appear, since
+        # every matching title carries them, so they stay togglable.)
+        genre_pp = p if p.get("genre_mode") == "all" else {**p, "genres": None}
+        # Only rows whose `genres` is a JSON array can be unnested. A genre-less item stores JSON
+        # `null` (SQLAlchemy's JSONB persists a Python None as JSON null, not SQL NULL), and
+        # jsonb_array_elements_text() raises on a scalar ("cannot extract elements from a scalar") —
+        # so a single metadata-poor library (e.g. one bare Shows library with no genres) 500'd the
+        # whole facets endpoint. Mirror the exact guard people.py already applies to the same columns.
+        # In HU the vocabulary comes from the active-language genre column (coalesce(genres_hu, genres)).
+        gcol = genres_col(model, lang)
+        expanded = (
+            wsq(
+                select(func.jsonb_array_elements_text(gcol).label("g")),
+                model,
+                ids,
+                genre_pp,
+                kind_movie,
+                True,
+            )
+            .where(func.jsonb_typeof(gcol) == "array")
+            .subquery()
+        )
+        for g, c in db.execute(
+            select(expanded.c.g, func.count()).group_by(expanded.c.g)
+        ).all():
+            genre_counts[g] = genre_counts.get(g, 0) + c
+        # Content ratings — exclude its own.
+        crq = (
+            wsq(
+                select(model.content_rating, func.count()),
+                model,
+                ids,
+                {**p, "content_ratings": None},
+                kind_movie,
+                True,
+            )
+            .where(model.content_rating.isnot(None))
+            .group_by(model.content_rating)
+        )
+        for cr, c in db.execute(crq).all():
+            cr_counts[cr] = cr_counts.get(cr, 0) + c
+        # Year bounds — exclude the year filter.
+        by = db.execute(
+            wsq(
+                select(func.min(model.year), func.max(model.year)),
+                model,
+                ids,
+                {**p, "year_min": None, "year_max": None},
+                kind_movie,
+                True,
+            )
+        ).first()
+        if by[0] is not None:
+            years.append(by[0])
+        if by[1] is not None:
+            years.append(by[1])
+        # Rating max — exclude the rating filter. Coalesce(imdb, audience) to match the score the
+        # rating filter and the UI badge use (IMDb preferred, audience fallback).
+        br = db.scalar(
+            wsq(
+                select(func.max(func.coalesce(model.imdb_rating, model.rating))),
+                model,
+                ids,
+                {**p, "rating_min": None},
+                kind_movie,
+                True,
+            )
+        )
+        if br is not None:
+            ratings.append(float(br))
+        # Duration bounds (movies) — exclude the duration filter.
+        if kind_movie:
+            bd = db.execute(
+                wsq(
+                    select(func.min(model.duration_s), func.max(model.duration_s)),
+                    model,
+                    ids,
+                    p,
+                    kind_movie,
+                    False,
+                )
+            ).first()
+            if bd[0] is not None:
+                durs.append(bd[0])
+            if bd[1] is not None:
+                durs.append(bd[1])
+
+    per_table(PlexItem, movie_ids, True)
+    per_table(PlexShow, show_ids, False)
+    # Always surface the actively-selected genres (even a zero-match AND combo, where they'd otherwise
+    # be absent): the sidebar renders genres solely from this list and hides the whole genre section —
+    # chips AND the Any/All toggle — when it's empty, which would trap the user with no per-chip way to
+    # undo a zero-result selection. Count 0 is fine (genre chips don't display counts).
+    for g in split_csv(f.genres):
+        genre_counts.setdefault(g, 0)
+    return {
+        "genres": [
+            {"value": g, "count": c}
+            for g, c in sorted(genre_counts.items(), key=lambda kv: kv[0])
+        ],
+        "content_ratings": [
+            {"value": cr, "count": c}
+            for cr, c in sorted(cr_counts.items(), key=lambda kv: -kv[1])
+        ],
+        "year_min": min(years) if years else None,
+        "year_max": max(years) if years else None,
+        "rating_max": max(ratings) if ratings else None,
+        "duration_min": min(durs) if durs else None,
+        "duration_max": max(durs) if durs else None,
+    }

backend/app/routes/plex/collections.py

@@ -0,0 +1,253 @@
+"""Plex collections: browse mirrored collections + the admin manual-collection editor."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.auth import admin_user, current_user
+from app.db import get_db
+from app.models import (
+    PlexCollection,
+    PlexLibrary,
+    User,
+)
+from app.plex import sync as plex_sync
+from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+from app.plex.lookups import by_rating_key
+from app.plex.query import like_escape
+
+router = APIRouter(prefix="/api/plex", tags=["plex"])
+
+_STRIP_PROVIDERS = ("imdb", "tmdb", "tvdb", "trakt")
+
+
+def _collection_source(col: PlexCollection) -> str:
+    first = (col.title or "").strip().split(" ", 1)[0].lower()
+    if first in _STRIP_PROVIDERS:
+        return first
+    if col.smart:
+        return "smart"
+    return "collection"
+
+
+def _collection_editable(c: PlexCollection) -> bool:
+    """Effective editability: the admin marked it editable AND it's a plain manual collection — never
+    smart, never an external auto-list (IMDb/TMDb/…), which are managed outside Plex."""
+    return bool(c.editable) and not c.smart and _collection_source(c) == "collection"
+
+
+def _collection_card(c: PlexCollection) -> dict:
+    return {
+        "id": c.rating_key,
+        "title": c.title,
+        "summary": c.summary,
+        "thumb": f"/api/plex/image/{c.rating_key}" if c.thumb_key else None,
+        "child_count": c.child_count,
+        "smart": c.smart,
+        "source": _collection_source(c),
+        "editable": c.editable,
+        "can_edit": _collection_editable(
+            c
+        ),  # whether the edit controls should be offered (admin UI)
+    }
+
+
+@router.get("/collections")
+def collections(
+    library: str | None = None,
+    q: str | None = None,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Mirrored collections as cards (most-populated first), optionally name-filtered by `q`. With a
+    `library` plex_key → that one library's collections (used by the collection editor). WITHOUT one →
+    the UNION across all enabled libraries (the unified-scope sidebar picker, which has no single
+    library selected)."""
+    if library is not None:
+        lib = db.execute(
+            select(PlexLibrary).where(PlexLibrary.plex_key == str(library))
+        ).scalars().first()
+        if lib is None:
+            return {"collections": []}
+        query = select(PlexCollection).where(PlexCollection.library_id == lib.id)
+    else:
+        enabled_ids = list(
+            db.execute(
+                select(PlexLibrary.id).where(
+                    PlexLibrary.enabled.is_(True), PlexLibrary.overlay_of.is_(None)
+                )
+            ).scalars()
+        )
+        if not enabled_ids:
+            return {"collections": []}
+        query = select(PlexCollection).where(
+            PlexCollection.library_id.in_(enabled_ids)
+        )
+    term = (q or "").strip()
+    if term:
+        query = query.where(PlexCollection.title.ilike(f"%{like_escape(term)}%"))
+    rows = db.execute(
+        query.order_by(
+            PlexCollection.child_count.desc().nullslast(),
+            func.lower(PlexCollection.title),
+        )
+    ).scalars().all()
+    return {"collections": [_collection_card(c) for c in rows]}
+
+
+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")
+    if not _collection_editable(col):
+        raise HTTPException(status_code=403, detail="This collection is read-only")
+    return col
+
+
+class CreateCollectionIn(BaseModel):
+    library: str = ""
+    title: str = ""
+    item_rating_key: str = ""
+
+
+@router.post("/collections")
+def create_collection(
+    body: CreateCollectionIn,
+    _: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Create a manual collection (seeded with one item — Plex needs at least one). Editable by default."""
+    library = body.library
+    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"
+        )
+    lib = db.execute(
+        select(PlexLibrary).where(PlexLibrary.plex_key == library)
+    ).scalars().first()
+    if lib is None:
+        raise HTTPException(status_code=404, detail="Unknown library")
+    try:
+        with PlexClient(db) as plex:
+            new = plex.create_collection(lib.plex_key, title, seed)
+            col = plex_sync.resync_collection(db, plex, lib, str(new.get("ratingKey")))
+            col.editable = True
+        db.commit()
+    except (PlexError, PlexNotConfigured) as e:
+        db.rollback()
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
+    return _collection_card(col)
+
+
+@router.post("/collections/{rating_key}/items/{item_rating_key}")
+def collection_add_item(
+    rating_key: str,
+    item_rating_key: str,
+    _: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    col = _editable_collection_or_403(db, rating_key)
+    lib = db.get(PlexLibrary, col.library_id)
+    try:
+        with PlexClient(db) as plex:
+            plex.add_collection_item(rating_key, str(item_rating_key))
+            col = plex_sync.resync_collection(db, plex, lib, rating_key)
+        db.commit()
+    except (PlexError, PlexNotConfigured) as e:
+        db.rollback()
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
+    return _collection_card(col)
+
+
+@router.delete("/collections/{rating_key}/items/{item_rating_key}")
+def collection_remove_item(
+    rating_key: str,
+    item_rating_key: str,
+    _: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    col = _editable_collection_or_403(db, rating_key)
+    lib = db.get(PlexLibrary, col.library_id)
+    try:
+        with PlexClient(db) as plex:
+            plex.remove_collection_item(rating_key, str(item_rating_key))
+            col = plex_sync.resync_collection(db, plex, lib, rating_key)
+        db.commit()
+    except (PlexError, PlexNotConfigured) as e:
+        db.rollback()
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
+    return _collection_card(col)
+
+
+class CollectionRenameIn(BaseModel):
+    title: str = ""
+
+
+@router.patch("/collections/{rating_key}")
+def collection_rename(
+    rating_key: str,
+    body: CollectionRenameIn,
+    _: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    col = _editable_collection_or_403(db, rating_key)
+    title = body.title.strip()
+    if not title:
+        raise HTTPException(status_code=400, detail="title is required")
+    lib = db.get(PlexLibrary, col.library_id)
+    try:
+        with PlexClient(db) as plex:
+            plex.rename_collection(lib.plex_key, rating_key, title)
+            col = plex_sync.resync_collection(db, plex, lib, rating_key)
+        db.commit()
+    except (PlexError, PlexNotConfigured) as e:
+        db.rollback()
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
+    return _collection_card(col)
+
+
+@router.delete("/collections/{rating_key}")
+def collection_delete(
+    rating_key: str, _: User = Depends(admin_user), db: Session = Depends(get_db)
+) -> dict:
+    col = _editable_collection_or_403(db, rating_key)
+    lib = db.get(PlexLibrary, col.library_id)
+    try:
+        with PlexClient(db) as plex:
+            plex.delete_collection(rating_key)
+        plex_sync.delete_collection_local(db, lib, rating_key)
+        db.commit()
+    except (PlexError, PlexNotConfigured) as e:
+        db.rollback()
+        raise HTTPException(status_code=422, detail=f"Plex write failed: {e}")
+    return {"deleted": rating_key}
+
+
+class CollectionEditableIn(BaseModel):
+    editable: bool = False
+
+
+@router.post("/collections/{rating_key}/editable")
+def collection_set_editable(
+    rating_key: str,
+    body: CollectionEditableIn,
+    _: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Mark an existing Plex collection as 'mine to edit' (or unmark). Smart / auto-list collections
+    (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")
+    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",
+        )
+    col.editable = want
+    db.commit()
+    return _collection_card(col)

backend/app/routes/plex/detail.py

@@ -0,0 +1,438 @@
+"""Plex show/item detail: the show drill-down + the per-item player payload (markers, cast, nav)."""
+
+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 sqlalchemy.orm import Session
+
+from app.auth import current_user
+from app.db import get_db
+from app.models import (
+    PlexCollection,
+    PlexItem,
+    PlexLibrary,
+    PlexSeason,
+    PlexShow,
+    PlexState,
+    User,
+)
+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.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
+
+router = APIRouter(prefix="/api/plex", tags=["plex"])
+
+
+def _lib_key(db: Session, library_id: int | None) -> str | None:
+    """The Plex section key for a library id — the info/show page passes it to the admin collection
+    editor (in the unified cross-library view there's no single library prop otherwise)."""
+    if library_id is None:
+        return None
+    lib = db.get(PlexLibrary, library_id)
+    return lib.plex_key if lib else None
+
+
+_SHOW_ENRICH_TTL_S = 300
+
+_show_enrich_cache: dict[str, tuple[float, dict, list]] = {}
+
+_show_enrich_lock = threading.Lock()
+
+
+def _show_enrichment(db: Session, rating_key: str) -> tuple[dict, list]:
+    """(meta, related_raw) for a show's live Plex enrichment — served from the per-show TTL cache when
+    warm, otherwise fetched with the two Plex calls (metadata + related) run IN PARALLEL. Returns
+    ({}, []) when Plex is unavailable/unconfigured (not cached, so it retries on the next open)."""
+    now = time.monotonic()
+    with _show_enrich_lock:
+        hit = _show_enrich_cache.get(rating_key)
+        if hit is not None and hit[0] > now:
+            return hit[1], hit[2]
+    try:
+        with PlexClient(db) as plex:
+            with ThreadPoolExecutor(max_workers=2) as ex:
+                meta_f = ex.submit(plex.metadata, rating_key)
+                related_f = ex.submit(
+                    plex.related, rating_key
+                )  # swallows its own errors → []
+                meta = meta_f.result() or {}
+                related_raw = related_f.result()
+    except (PlexError, PlexNotConfigured):
+        return {}, []
+    # Don't cache an EMPTY related list: plex.related() swallows a transient failure as [] (same as a
+    # genuinely no-related show), so caching it would serve an empty "related" section for the whole TTL
+    # even after Plex recovers. Skip the cache in that case (retry next open, as before); shows that DO
+    # have related items — the payload worth caching — still get cached.
+    if related_raw:
+        with _show_enrich_lock:
+            _show_enrich_cache[rating_key] = (
+                now + _SHOW_ENRICH_TTL_S,
+                meta,
+                related_raw,
+            )
+    return meta, related_raw
+
+
+@router.get("/show/{rating_key}")
+def show_detail(
+    rating_key: str,
+    lang: str = "en",
+    user: User = Depends(current_user),
+    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"
+    sh = by_rating_key(db, PlexShow, rating_key)
+    if sh is None:
+        raise HTTPException(status_code=404, detail="Unknown Plex show")
+    seasons = db.execute(
+        select(PlexSeason)
+        .where(PlexSeason.show_id == sh.id)
+        .order_by(PlexSeason.season_number.asc().nullsfirst())
+    ).scalars().all()
+    eps = db.execute(
+        select(PlexItem)
+        .where(PlexItem.show_id == sh.id, PlexItem.kind == "episode")
+        .order_by(
+            PlexItem.season_number.asc().nullsfirst(),
+            PlexItem.episode_number.asc().nullsfirst(),
+        )
+    ).scalars().all()
+    states = {
+        s.item_id: s
+        for s in db.execute(
+            select(PlexState).where(
+                PlexState.user_id == user.id,
+                PlexState.item_id.in_([e.id for e in eps] or [0]),
+            )
+        ).scalars()
+    }
+    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))
+        by_season.setdefault(e.season_id, []).append(card)
+        all_cards.append(card)
+    show_roll = rollup.rollup(all_cards)
+
+    # Cast + IMDb + tagline are served from the DB row (persisted by the cast backfill, E5 S5b). The one
+    # remaining live call is `related` — a Plex recommendation hub we don't mirror — which also carries
+    # the metadata used to lazily fill a not-yet-enriched show. Any live failure just drops `related` and
+    # the lazy fill; the row-served detail below still renders (outage-resilient).
+    related: list[dict] = []
+    try:
+        meta, related_raw = _show_enrichment(db, sh.rating_key)
+        related = _relatedshow_cards(db, user.id, related_raw, exclude=sh.id)
+        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
+            sh.people_enriched_at = datetime.now(timezone.utc)
+            try:
+                db.commit()
+            except Exception:
+                db.rollback()
+    except Exception:
+        # Best-effort only — the local episode list is already assembled, so any live-Plex failure
+        # (not configured, HTTP/JSON shape) must degrade, not 500.
+        pass
+
+    imdb_id = sh.imdb_id
+    return {
+        "show": {
+            "id": sh.rating_key,
+            "title": (sh.title_hu or sh.title) if hu else sh.title,
+            "summary": (sh.summary_hu or sh.summary) if hu else sh.summary,
+            "year": sh.year,
+            "thumb": f"/api/plex/image/{sh.rating_key}",
+            "art": f"/api/plex/image/{sh.rating_key}?variant=art",
+            "library": _lib_key(db, sh.library_id),
+            "content_rating": sh.content_rating,
+            "rating": sh.rating,
+            "genres": (sh.genres_hu or sh.genres if hu else sh.genres) or [],
+            "studio": sh.studio,
+            "season_count": sh.child_count,
+            "imdb_rating": sh.imdb_rating,
+            "imdb_id": imdb_id,
+            "imdb_url": f"https://www.imdb.com/title/{imdb_id}/" if imdb_id else None,
+            "cast": sh.full_cast or [],
+            # Show-level rollup for the hero action buttons.
+            "status": show_roll["status"],
+            "resume": show_roll["resume"],
+            "first": show_roll["first"],
+            "episode_count": show_roll["episode_count"],
+            "collection_keys": sh.collection_keys or [],
+        },
+        "seasons": [_season_block(se, by_season.get(se.id, [])) for se in seasons],
+        "related": related,
+    }
+
+
+def _season_block(se: PlexSeason, cards: list[dict]) -> dict:
+    """A season's card for the show page (with its aggregate rollup) plus its episodes (used by the
+    season subpage, read from the same cached show-detail payload)."""
+    roll = rollup.rollup(cards)
+    return {
+        "id": se.rating_key,
+        "season_number": se.season_number,
+        "title": se.title
+        or (f"Season {se.season_number}" if se.season_number else "Season"),
+        "thumb": f"/api/plex/image/{se.rating_key}",
+        "episode_count": roll["episode_count"],
+        "status": roll["status"],
+        "resume": roll["resume"],
+        "first": roll["first"],
+        "episodes": cards,
+    }
+
+
+def _relatedshow_cards(
+    db: Session, user_id: int, related: list[dict], exclude: int
+) -> 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")]
+    if not rks:
+        return []
+    shows = {
+        s.rating_key: s
+        for s in db.execute(
+            select(PlexShow).where(
+                PlexShow.rating_key.in_(rks[:60]), PlexShow.id != exclude
+            )
+        ).scalars()
+    }
+    statuses = rollup.state_map(db, user_id, [s.id for s in shows.values()])
+    out: list[dict] = []
+    seen: set[str] = set()
+    for rk in rks:
+        sh = shows.get(rk)
+        if sh is None or rk in seen:
+            continue
+        seen.add(rk)
+        out.append(show_card(sh, statuses.get(sh.id, "new")))
+        if len(out) >= 20:
+            break
+    return out
+
+
+def _collection_strips(db: Session, it: PlexItem, user_id: int) -> 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 []
+    if not keys or it.kind != "movie":
+        return []
+    cols = {
+        c.rating_key: c
+        for c in db.execute(
+            select(PlexCollection).where(PlexCollection.rating_key.in_(keys))
+        ).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)
+    )
+    out = []
+    for col in ordered:
+        rk = col.rating_key
+        members = db.execute(
+            select(PlexItem)
+            .where(
+                PlexItem.library_id == it.library_id,
+                PlexItem.kind == "movie",
+                PlexItem.collection_keys.contains([rk]),
+            )
+            .order_by(PlexItem.year.asc().nullslast(), func.lower(PlexItem.title))
+            .limit(60)
+        ).scalars().all()
+        ids = [m.id for m in members]
+        states = {
+            s.item_id: s
+            for s in db.execute(
+                select(PlexState).where(
+                    PlexState.user_id == user_id, PlexState.item_id.in_(ids or [0])
+                )
+            ).scalars()
+        }
+        out.append(
+            {
+                "id": rk,
+                "title": col.title,
+                "source": _collection_source(col),
+                "items": [movie_card(m, states.get(m.id)) for m in members],
+            }
+        )
+    return out
+
+
+def _episode_nav(db: Session, it: PlexItem) -> tuple[str | None, str | None]:
+    if it.kind != "episode" or it.show_id is None:
+        return None, None
+    keys = list(
+        db.execute(
+            select(PlexItem.rating_key)
+            .where(PlexItem.show_id == it.show_id, PlexItem.kind == "episode")
+            .order_by(
+                PlexItem.season_number.asc().nullsfirst(),
+                PlexItem.episode_number.asc().nullsfirst(),
+            )
+        ).scalars()
+    )
+    try:
+        i = keys.index(it.rating_key)
+    except ValueError:
+        return None, None
+    return (keys[i - 1] if i > 0 else None), (
+        keys[i + 1] if i < len(keys) - 1 else None
+    )
+
+
+@router.get("/item/{rating_key}")
+def item_detail(
+    rating_key: str,
+    lang: str = "en",
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Everything the player needs: metadata, cast, intro/credit markers (from Plex), episode
+    prev/next, and the per-user resume position + watch status."""
+    lang = _norm_lang(lang)
+    it = item_or_404(db, rating_key)
+    st = db.execute(
+        select(PlexState).where(
+            PlexState.user_id == user.id, PlexState.item_id == it.id
+        )
+    ).scalars().first()
+
+    # Markers + audio/subtitle streams are file-specific, so they stay LIVE; the rich detail (cast/IMDb/
+    # tagline/genres) is served from the DB row for movies (persisted below / by the backfill) and only
+    # parsed from this live meta for episodes (never enriched — not in the grid, no HU overlay).
+    meta: dict = {}
+    markers: list[dict] = []
+    audio_streams: list[dict] = []
+    subtitle_streams: list[dict] = []
+    try:
+        with PlexClient(db) as plex:
+            meta = plex.metadata(it.rating_key, markers=True) or {}
+        for m in meta.get("Marker") or []:
+            if m.get("type") in ("intro", "credits"):
+                markers.append(
+                    {
+                        "type": m.get("type"),
+                        "start_s": round((m.get("startTimeOffset") or 0) / 1000, 1),
+                        "end_s": round((m.get("endTimeOffset") or 0) / 1000, 1),
+                    }
+                )
+        # Audio + subtitle tracks (ordinals among their stream type — used to -map the selection).
+        part = ((meta.get("Media") or [{}])[0].get("Part") or [{}])[0]
+        for s in part.get("Stream") or []:
+            if s.get("streamType") == 2:
+                audio_streams.append(
+                    {
+                        "ord": len(audio_streams),
+                        "label": s.get("displayTitle")
+                        or s.get("language")
+                        or f"Audio {len(audio_streams) + 1}",
+                        "language": s.get("languageTag") or s.get("language"),
+                        "default": bool(s.get("selected") or s.get("default")),
+                    }
+                )
+            elif s.get("streamType") == 3:
+                codec = (s.get("codec") or s.get("format") or "").lower()
+                subtitle_streams.append(
+                    {
+                        "ord": len(subtitle_streams),
+                        "label": s.get("displayTitle")
+                        or s.get("language")
+                        or f"Subtitle {len(subtitle_streams) + 1}",
+                        "language": s.get("languageTag") or s.get("language"),
+                        "codec": codec,
+                        # Text subs (srt/ass/…) can be served as WebVTT tracks; image subs (PGS/VobSub)
+                        # can't be turned into text, so the player hides them (burn-in is a later phase).
+                        "text": codec not in subtitles.BITMAP_SUBS,
+                    }
+                )
+    except Exception:
+        pass  # live extras (markers/streams) are best-effort; any live-Plex failure must degrade, not 500 — playback works without them
+
+    # Lazy enrichment (movies only): the live fetch above carries the FULL cast + rich detail (the sync
+    # only stored the listing's top ~3), so fill a not-yet-enriched movie — its cast becomes filterable
+    # and future views serve from the row. Episodes aren't enriched; a show's cast is filled from /show.
+    if it.kind == "movie" and it.people_enriched_at is None and meta:
+        cast = plex_people.cast_from_meta(meta)
+        if cast:
+            plex_people.enrich_row_people(db, it, cast)
+        plex_detail.apply_rich_detail(it, meta)
+        it.people_enriched_at = datetime.now(timezone.utc)
+        try:
+            db.commit()
+        except Exception:
+            db.rollback()
+
+    hu = lang == "hu"
+    # Movies serve rich detail from the DB row; episodes from the live meta just fetched.
+    if it.kind == "movie":
+        _imdb_id = it.imdb_id
+        rich = {
+            "cast": it.full_cast or [],
+            "imdb_rating": it.imdb_rating,
+            "imdb_id": _imdb_id,
+            "imdb_url": f"https://www.imdb.com/title/{_imdb_id}/" if _imdb_id else None,
+            "content_rating": it.content_rating,
+            "genres": (it.genres_hu or it.genres if hu else it.genres) or [],
+            "directors": it.directors or [],
+            "studio": it.studio,
+            "tagline": it.tagline,
+        }
+    else:
+        rich = plex_detail.rich_detail(meta)
+
+    prev_id, next_id = _episode_nav(db, it)
+    show = db.get(PlexShow, it.show_id) if it.kind == "episode" and it.show_id else None
+    return {
+        "id": it.rating_key,
+        "kind": it.kind,
+        "title": (it.title_hu or it.title) if hu else it.title,
+        "summary": (it.summary_hu or it.summary) if hu else it.summary,
+        "year": it.year,
+        "duration_seconds": it.duration_s,
+        "playable": it.playable,
+        "thumb": f"/api/plex/image/{it.rating_key}",
+        "art": f"/api/plex/image/{it.rating_key}?variant=art",
+        "library": _lib_key(db, it.library_id),
+        "cast": rich.get("cast", []),
+        "imdb_rating": rich.get("imdb_rating"),
+        "imdb_id": rich.get("imdb_id"),
+        "imdb_url": rich.get("imdb_url"),
+        # Audience score (Plex audienceRating) served alongside the IMDb score — the UI shows the
+        # IMDb badge when imdb_rating is present, else this. Episodes carry it on the row too.
+        "rating": it.rating,
+        "content_rating": rich.get("content_rating"),
+        "genres": rich.get("genres", []),
+        "directors": rich.get("directors", []),
+        "studio": rich.get("studio"),
+        "tagline": rich.get("tagline"),
+        "markers": markers,
+        "audio_streams": audio_streams,
+        "subtitle_streams": subtitle_streams,
+        "status": st.status if st else "new",
+        "position_seconds": st.position_seconds if st else 0,
+        "show_title": (
+            (show.title_hu or show.title if hu else show.title) if show else None
+        ),
+        "season_number": it.season_number,
+        "episode_number": it.episode_number,
+        "prev_id": prev_id,
+        "next_id": next_id,
+        "collections": _collection_strips(db, it, user.id),
+    }

backend/app/routes/plex/people.py

@@ -0,0 +1,139 @@
+"""Plex people: cast/crew filter-chip cards + a single person's filmography page."""
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import func, or_, select
+from sqlalchemy.orm import Session
+
+from app.auth import current_user
+from app.db import get_db
+from app.models import (
+    PlexItem,
+    PlexPerson,
+    PlexShow,
+    PlexState,
+    User,
+)
+from app.plex import rollup
+from app.plex.cards import movie_card, show_card
+from app.plex.query import split_csv
+from app.routes.plex._shared import _content_libs
+
+router = APIRouter(prefix="/api/plex", tags=["plex"])
+
+
+@router.get("/people/cards")
+def people_cards(
+    names: str,
+    scope: str = "both",
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Cards for the actor filter-chips currently applied: each name + its cached headshot + how many
+    movies/shows (in the given scope) feature them. Photos come from the plex_people cache (populated
+    as items are rich-fetched — info-page view + the rich re-sync); counts are live against cast_names.
+    A name with no cached photo yet still returns a card (the UI shows a placeholder)."""
+    wanted = split_csv(names)[:16]
+    if not wanted:
+        return {"people": []}
+    movie_lib_ids, show_lib_ids = _content_libs(db)
+    want_movies = scope in ("movie", "both") and bool(movie_lib_ids)
+    want_shows = scope in ("show", "both") and bool(show_lib_ids)
+    photos = {
+        p.name: p.photo_thumb
+        for p in db.execute(
+            select(PlexPerson).where(PlexPerson.name.in_(wanted))
+        ).scalars()
+    }
+    out = []
+    for nm in wanted:
+        count = 0
+        if want_movies:
+            count += (
+                db.scalar(
+                    select(func.count(PlexItem.id)).where(
+                        PlexItem.kind == "movie",
+                        PlexItem.library_id.in_(movie_lib_ids),
+                        PlexItem.cast_names.contains([nm]),
+                    )
+                )
+                or 0
+            )
+        if want_shows:
+            count += (
+                db.scalar(
+                    select(func.count(PlexShow.id)).where(
+                        PlexShow.library_id.in_(show_lib_ids),
+                        PlexShow.cast_names.contains([nm]),
+                    )
+                )
+                or 0
+            )
+        out.append({"name": nm, "photo": photos.get(nm), "count": count})
+    return {"people": out}
+
+
+# Cap each filmography section — a prolific person shouldn't return an unbounded list the client then
+# mounts a card per row for (the grid paginates at PAGE; this page renders all at once). Ample for a
+# personal library; the most-recent titles win via the year-desc order.
+_PERSON_SECTION_MAX = 200
+
+
+@router.get("/person/{name}")
+def person_detail(
+    name: str,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """One cast/crew member's filmography: their cached headshot + the movies and shows (in the enabled
+    libraries) whose cast OR directors include this name — the inverse of the cast-name → library-filter
+    link. The name string is the identity key (Plex cast carries no stable per-person id), so distinct
+    people who share a name share a page. Each section is capped at _PERSON_SECTION_MAX. An unknown name
+    simply returns empty sections."""
+    photo = db.scalar(select(PlexPerson.photo_thumb).where(PlexPerson.name == name))
+    movie_lib_ids, show_lib_ids = _content_libs(db)
+
+    movies: list[dict] = []
+    if movie_lib_ids:
+        items = db.execute(
+            select(PlexItem)
+            .where(
+                PlexItem.kind == "movie",
+                PlexItem.library_id.in_(movie_lib_ids),
+                or_(
+                    PlexItem.cast_names.contains([name]),
+                    PlexItem.directors.contains([name]),
+                ),
+            )
+            .order_by(PlexItem.year.desc().nullslast(), func.lower(PlexItem.title))
+            .limit(_PERSON_SECTION_MAX)
+        ).scalars().all()
+        item_ids = [it.id for it in items]
+        states = {
+            s.item_id: s
+            for s in db.execute(
+                select(PlexState).where(
+                    PlexState.user_id == user.id,
+                    PlexState.item_id.in_(item_ids or [0]),
+                )
+            ).scalars()
+        }
+        movies = [movie_card(it, states.get(it.id)) for it in items]
+
+    shows: list[dict] = []
+    if show_lib_ids:
+        show_rows = db.execute(
+            select(PlexShow)
+            .where(
+                PlexShow.library_id.in_(show_lib_ids),
+                or_(
+                    PlexShow.cast_names.contains([name]),
+                    PlexShow.directors.contains([name]),
+                ),
+            )
+            .order_by(PlexShow.year.desc().nullslast(), func.lower(PlexShow.title))
+            .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]
+
+    return {"name": name, "photo": photo, "movies": movies, "shows": shows}

backend/app/routes/plex/playback.py

@@ -0,0 +1,557 @@
+"""Plex playback: image/subtitle proxies, HLS streaming, and watch-state writes."""
+
+import hashlib
+import os
+import tempfile
+from datetime import datetime, timezone
+
+import httpx
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    Depends,
+    HTTPException,
+    Request,
+    Response,
+)
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.auth import current_user, resolved_user_id
+from app.db import SessionLocal, get_db
+from app.models import (
+    PlexItem,
+    PlexSeason,
+    PlexShow,
+    PlexState,
+    User,
+)
+from app.plex import imgcache, subtitles
+from app.plex import paths as plex_paths
+from app.plex.lookups import by_rating_key
+from app.plex import people as plex_people
+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
+
+router = APIRouter(prefix="/api/plex", tags=["plex"])
+
+
+def _require_session(request: Request) -> int:
+    """Lightweight auth for the high-fan-out image proxies: validate the signed session cookie WITHOUT
+    a DB user-load, so these endpoints never hold a pool connection for the auth. Poster images are
+    low-sensitivity; a valid session is enough."""
+    uid, _ = resolved_user_id(request)
+    if not uid:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    return uid
+
+
+@router.get("/image/{rating_key}")
+def image(rating_key: str, request: Request, variant: str = "thumb") -> Response:
+    """Proxy a Plex poster/art image (keeps the admin token server-side; no image duplication). A
+    thin on-disk cache serves repeat views without re-hitting Plex.
+
+    ⚠️ This endpoint is called in BURSTS (a collections page fires 100+ concurrent poster requests),
+    so it must NOT hold a DB connection during the slow Plex fetch — doing so exhausted the pool
+    (QueuePool timeout, broken images on prod). Warm path (cache hit) touches NO DB; cold path opens a
+    brief session only to resolve the image key + read the Plex config, then RELEASES it before the
+    fetch. Auth is the signed-session check (no DB user-load)."""
+    _require_session(request)
+    v = "art" if variant == "art" else "thumb"
+    w, h = imgcache.SIZES[v]
+    # Size is part of the cache key: Plex resizes server-side (see PlexClient.image_bytes), so we cache
+    # the small variant. The width tag also means changing a target size just re-caches, never serves a
+    # stale differently-sized file (old full-size files under the un-tagged key are simply orphaned).
+    cache_key = f"item_{rating_key}_{v}_{w}"
+    hit = imgcache.read(cache_key)
+    if hit:
+        return imgcache.response(*hit)
+    # Cold miss: short-lived session for the key + Plex client config, released before the slow fetch.
+    try:
+        with SessionLocal() as db:
+            key = imgcache.key_for(db, str(rating_key), v)
+            if not key:
+                raise HTTPException(status_code=404, detail="No 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))
+    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}")
+    imgcache.write(cache_key, data, ct)
+    return imgcache.response(data, ct)
+
+
+@router.get("/subtitle/{rating_key}/{sub_ord}")
+def subtitle(
+    rating_key: str, sub_ord: int, request: Request, offset: float = 0.0
+) -> Response:
+    """Serve the ord-th subtitle track as WebVTT for the browser's <track> — so choosing a subtitle
+    overlays it directly (no HLS re-mux / session restart). Handles EXTERNAL sidecar subs (fetched
+    from Plex via the stream `key` — the old `-map 0:s` broke on these since they're not in the file)
+    AND embedded text subs (extracted from the local file). Image subs (PGS/VobSub) → 415. Disk-cached."""
+    _require_session(request)
+    # Cache the ABSOLUTE-time VTT once (per rk+ord); the per-session cue-shift is applied on the way
+    # out, so a resume/seek to any offset reuses the same cached track (no cache-per-offset explosion).
+    cache_key = f"sub_{rating_key}_{sub_ord}"
+    hit = subtitles.cache_read(cache_key)
+    if hit is not None:
+        return Response(subtitles.shift_vtt(hit, offset), media_type="text/vtt")
+    try:
+        with SessionLocal() as db:
+            it = item_or_404(db, rating_key)
+            with PlexClient(db) as plex:
+                part = ((plex.metadata(it.rating_key) or {}).get("Media") or [{}])[
+                    0
+                ].get("Part") or [{}]
+                subs = [
+                    s for s in (part[0].get("Stream") or []) if s.get("streamType") == 3
+                ]
+                if sub_ord < 0 or sub_ord >= len(subs):
+                    raise HTTPException(status_code=404, detail="No such subtitle")
+                s = subs[sub_ord]
+                codec = (s.get("codec") or s.get("format") or "").lower()
+                if codec in subtitles.BITMAP_SUBS:
+                    raise HTTPException(
+                        status_code=415,
+                        detail="Image-based subtitle can't be shown as text",
+                    )
+                if s.get("key"):  # external sidecar → fetch from Plex, convert to VTT
+                    raw = plex.raw_get(s["key"])
+                    if codec in ("srt", "subrip", ""):
+                        vtt = subtitles.srt_to_vtt(raw.decode("utf-8", "replace"))
+                    else:
+                        fd, tmp = tempfile.mkstemp(suffix="." + (codec or "sub"))
+                        try:
+                            os.write(fd, raw)
+                            os.close(fd)
+                            vtt = subtitles.ffmpeg_to_vtt(tmp, None)
+                        finally:
+                            os.unlink(tmp)
+                elif (
+                    s.get("index") is not None
+                ):  # embedded → extract from the local file
+                    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"
+                        )
+                    emb_ord = sum(
+                        1 for x in subs[:sub_ord] if x.get("index") is not None
+                    )
+                    vtt = subtitles.ffmpeg_to_vtt(str(src), emb_ord)
+                else:
+                    raise HTTPException(
+                        status_code=404, detail="Subtitle not fetchable"
+                    )
+    except PlexNotConfigured as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except PlexError as e:
+        raise HTTPException(status_code=502, detail=f"Subtitle fetch failed: {e}")
+    subtitles.cache_write(cache_key, vtt)
+    return Response(subtitles.shift_vtt(vtt, offset), media_type="text/vtt")
+
+
+# Resume/watched thresholds. _PROGRESS_MIN_S matches the feed's PROGRESS_MIN_SECONDS (5), but
+# _FINISH_MARGIN_S is DELIBERATELY larger than the feed's FINISH_MARGIN_SECONDS (30 vs 10): this is
+# long-form content (movies/episodes with credits) and crossing it MARKS THE ITEM WATCHED, whereas
+# the feed's margin only clears a short video's resume bar — different domains, intentional divergence,
+# not drift. Keep them separate on purpose (see routes/feed.py).
+_PROGRESS_MIN_S = 5
+
+_FINISH_MARGIN_S = 30
+
+
+@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."""
+    _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 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)
+
+
+def _push_watch(
+    background: BackgroundTasks,
+    db: Session,
+    user_id: int,
+    item_id: int,
+    rating_key: str,
+    action: str,
+    time_ms: int = 0,
+    duration_ms: int = 0,
+) -> None:
+    """Schedule a best-effort Siftlode→Plex watch push, but only for a user whose owner link has
+    push enabled — non-owner users never touch Plex. Guarding here (with the request session) avoids
+    spinning up a throwaway background session on every state change for the common no-link case."""
+    if plex_watch.link_for_push(db, user_id) is None:
+        return
+    # Capture the row's freshest timestamp NOW so the background push can tell if a newer local edit
+    # lands before it settles synced_to_plex (which would otherwise strand that newer value).
+    st = db.execute(
+        select(PlexState).where(
+            PlexState.user_id == user_id, PlexState.item_id == item_id
+        )
+    ).scalars().first()
+    background.add_task(
+        plex_watch.push_state_to_plex,
+        user_id,
+        item_id,
+        rating_key,
+        action,
+        time_ms,
+        duration_ms,
+        plex_watch._state_marker(st),
+    )
+
+
+class ItemProgressIn(BaseModel):
+    # float, truncated in the handler — the player may post a raw currentTime (a float); a plain
+    # `int` field would 422 it on the periodic progress checkpoint (the old `int(...)` truncated).
+    position_seconds: float = 0
+    duration_seconds: float = 0
+    final: bool = False
+
+
+@router.post("/item/{rating_key}/progress")
+def item_progress(
+    rating_key: str,
+    body: ItemProgressIn,
+    background: BackgroundTasks,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Checkpoint the resume position while playing (near the end → mark watched + clear it).
+
+    `final` (sent on the pause/pagehide/unmount flush, not the periodic 10s checkpoint) is what
+    debounces the Plex resume push: we mirror the settled position to Plex only on a final flush, so
+    a single watch doesn't spray `/:/timeline` calls at the server every 10 seconds."""
+    it = item_or_404(db, rating_key)
+    position = max(0, int(body.position_seconds))
+    duration = int(body.duration_seconds)
+    final = body.final
+    now = datetime.now(timezone.utc)
+    st = db.execute(
+        select(PlexState).where(
+            PlexState.user_id == user.id, PlexState.item_id == it.id
+        )
+    ).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
+        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":
+            db.delete(st)
+        elif st is not None:
+            st.position_seconds = 0
+            st.progress_updated_at = now
+        db.commit()
+        return {"position_seconds": 0}
+
+    if st is None:
+        st = PlexState(user_id=user.id, item_id=it.id)
+        db.add(st)
+    st.position_seconds = position
+    st.progress_updated_at = now
+    if final:
+        st.synced_to_plex = False
+    db.commit()
+    if final:
+        _push_watch(
+            background,
+            db,
+            user.id,
+            it.id,
+            rating_key,
+            "resume",
+            position * 1000,
+            duration * 1000,
+        )
+    return {"position_seconds": position}
+
+
+class ItemStateIn(BaseModel):
+    status: str = ""
+
+
+@router.post("/item/{rating_key}/state")
+def item_state(
+    rating_key: str,
+    body: ItemStateIn,
+    background: BackgroundTasks,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Set the per-user watch status (new|watched|hidden). watched→scrobble / →new→unscrobble push
+    to a linked Plex account immediately; `hidden` is a Siftlode-only concept with no Plex analogue,
+    so it never touches Plex."""
+    it = item_or_404(db, rating_key)
+    status = body.status
+    if status not in ("new", "watched", "hidden"):
+        raise HTTPException(status_code=400, detail="Invalid status")
+    st = db.execute(
+        select(PlexState).where(
+            PlexState.user_id == user.id, PlexState.item_id == it.id
+        )
+    ).scalars().first()
+    prev_status = st.status if st is not None else "new"
+    if status == "new":
+        if st is not None:
+            db.delete(st)
+            db.commit()
+        if prev_status != "new":  # something → unwatched: mirror the un-mark to Plex
+            _push_watch(background, db, user.id, it.id, rating_key, "unwatched")
+        return {"status": "new"}
+    if st is None:
+        st = PlexState(user_id=user.id, item_id=it.id)
+        db.add(st)
+    st.status = status
+    if status == "watched":
+        st.watched_at = datetime.now(timezone.utc)
+        st.position_seconds = 0
+    st.synced_to_plex = False
+    db.commit()
+    if status == "watched" and prev_status != "watched":
+        _push_watch(background, db, user.id, it.id, rating_key, "watched")
+    return {"status": status}
+
+
+def _bulk_state(
+    background: BackgroundTasks,
+    db: Session,
+    user_id: int,
+    eps: list[PlexItem],
+    watched: bool,
+) -> int:
+    """Mark every episode in `eps` watched (or unwatched) for a user, mirroring each change to a
+    linked Plex account in the background (best-effort). Returns how many rows actually changed."""
+    now = datetime.now(timezone.utc)
+    existing = {
+        s.item_id: s
+        for s in db.execute(
+            select(PlexState).where(
+                PlexState.user_id == user_id,
+                PlexState.item_id.in_([e.id for e in eps] or [0]),
+            )
+        ).scalars()
+    }
+    pushable = plex_watch.link_for_push(db, user_id) is not None
+    to_push: list[tuple[int, str, str]] = []
+    for e in eps:
+        st = existing.get(e.id)
+        prev = st.status if st is not None else "new"
+        if watched:
+            if st is None:
+                st = PlexState(user_id=user_id, item_id=e.id)
+                db.add(st)
+            st.status = "watched"
+            st.watched_at = now
+            st.position_seconds = 0
+            st.synced_to_plex = False
+            if prev != "watched":
+                to_push.append((e.id, e.rating_key, "watched"))
+        else:  # → new: drop any state (but keep the user's private "hidden" marks)
+            if st is not None and prev != "hidden":
+                db.delete(st)
+                if prev != "new":
+                    to_push.append((e.id, e.rating_key, "unwatched"))
+    db.commit()
+    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.
+        background.add_task(plex_watch.push_bulk_state_to_plex, user_id, to_push)
+    return len(to_push)
+
+
+class WatchedIn(BaseModel):
+    watched: bool = False
+
+
+@router.post("/show/{rating_key}/state")
+def show_state(
+    rating_key: str,
+    body: WatchedIn,
+    background: BackgroundTasks,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """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")
+    watched = body.watched
+    eps = db.execute(
+        select(PlexItem).where(PlexItem.show_id == sh.id, PlexItem.kind == "episode")
+    ).scalars().all()
+    changed = _bulk_state(background, db, user.id, eps, watched)
+    return {"changed": changed, "watched": watched}
+
+
+@router.post("/season/{rating_key}/state")
+def season_state(
+    rating_key: str,
+    body: WatchedIn,
+    background: BackgroundTasks,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """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")
+    watched = body.watched
+    eps = db.execute(
+        select(PlexItem).where(PlexItem.season_id == se.id, PlexItem.kind == "episode")
+    ).scalars().all()
+    changed = _bulk_state(background, db, user.id, eps, watched)
+    return {"changed": changed, "watched": watched}
+
+
+@router.post("/stream/{rating_key}/session")
+def stream_session(
+    rating_key: str,
+    start: float = 0.0,
+    audio: int | None = None,
+    aoff: float = 0.0,
+    multi: bool = False,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Prepare playback from `start` seconds. Direct-playable files are served raw; remux files
+    (re)start an HLS session at the offset (seek-restart); transcode (HEVC/VP9) is P3. Selecting a
+    non-default audio track (`audio` = stream ordinal) forces the HLS path so the chosen audio can be
+    muxed in. Subtitles are independent WebVTT tracks (GET /subtitle) — no session restart."""
+    plex_stream.reap_idle()  # opportunistic cleanup of idle sessions on each new playback
+    it = item_or_404(db, rating_key)
+    if it.playable == "transcode":
+        raise HTTPException(
+            status_code=501, detail="This format needs transcoding (a later phase)."
+        )
+    # `multi` (item has ≥2 audio tracks) forces the HLS path so ALL audio tracks ship as renditions and
+    # 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 {
+            "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)
+    if s is None:
+        raise HTTPException(status_code=404, detail="Media file not found on disk")
+    # 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.
+    return {
+        "mode": "hls",
+        "start_s": s.media_start_s,
+        "url": f"/api/plex/stream/{it.rating_key}/hls/{s.entry}",
+    }
+
+
+@router.get("/stream/{rating_key}/file")
+def stream_file(
+    rating_key: str,
+    download: bool = False,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> FileResponse:
+    """Serve the raw local media file with HTTP range support. Used both for direct-play (inline)
+    and for the player's "download original" button (`?download=1` → attachment). The download is
+    the untouched physical file — no re-encode/repackage."""
+    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")
+    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 "")
+        base = (
+            "".join(
+                c for c in (it.title or "video") if c.isalnum() or c in " -_."
+            ).strip()
+            or "video"
+        )
+        return FileResponse(str(src), filename=f"{base}{ext}")
+    return FileResponse(str(src))  # Starlette honours the Range header (206)
+
+
+_HLS_CT = {
+    ".m3u8": "application/vnd.apple.mpegurl",
+    ".ts": "video/mp2t",
+    ".vtt": "text/vtt",
+}
+
+
+@router.get("/stream/{rating_key}/hls/{filename}")
+def stream_hls_file(
+    rating_key: str,
+    filename: str,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> Response:
+    """Serve a file (playlist / segment / subtitle) from the current HLS session directory. The
+    playlist references its segments/subtitles by relative name, all resolving back here."""
+    # Filename must be a plain hls artifact — no path separators, only the expected extensions.
+    ext = "." + filename.rsplit(".", 1)[-1] if "." in filename else ""
+    if ext not in _HLS_CT or "/" in filename or "\\" in filename or ".." in filename:
+        raise HTTPException(status_code=404, detail="Not found")
+    s = plex_stream.current_session(str(rating_key))
+    if s is None:
+        # No session yet (e.g. reaped): the ENTRY playlist may auto-start one at 0 — master.m3u8 for a
+        # multi-audio item, index.m3u8 for a single-audio remux item.
+        it = item_or_404(db, rating_key)
+        if filename == "master.m3u8":
+            s = plex_stream.start_session(db, it, 0.0, multi=True)
+        elif filename == "index.m3u8" and it.playable == "remux":
+            s = plex_stream.start_session(db, it, 0.0)
+        else:
+            raise HTTPException(status_code=404, detail="No active playback session")
+        if s is None:
+            raise HTTPException(status_code=404, detail="Media file not found on disk")
+    path = s.dir / filename
+    timeout = 30 if ext == ".m3u8" else 20
+    if not plex_stream.wait_for(path, timeout):
+        raise HTTPException(status_code=404, detail="Not available yet")
+    return Response(
+        content=path.read_bytes(),
+        media_type=_HLS_CT[ext],
+        headers={"Cache-Control": "no-store"},
+    )

backend/app/routes/plex/playlists.py

@@ -0,0 +1,405 @@
+"""Plex playlists: the current user's personal, orderable playlists of playable items."""
+
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import delete, func, select, update
+from sqlalchemy.orm import Session
+
+from app.auth import current_user
+from app.db import get_db
+from app.models import (
+    PlexItem,
+    PlexPlaylist,
+    PlexPlaylistItem,
+    PlexShow,
+    PlexState,
+    User,
+)
+from app.plex.cards import leaf_card
+from app.plex.lookups import by_rating_key
+from app.routes._common import owned_or_404
+
+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, detail="Playlist not found")
+
+
+def _playlist_card(pl: PlexPlaylist, count: int, thumb_rk: str | None) -> dict:
+    return {
+        "id": pl.id,
+        "title": pl.title,
+        "item_count": count,
+        "thumb": f"/api/plex/image/{thumb_rk}" if thumb_rk else None,
+    }
+
+
+def _playlist_item_query(pid: int):
+    return (
+        select(PlexPlaylistItem, PlexItem)
+        .join(PlexItem, PlexItem.id == PlexPlaylistItem.item_id)
+        .where(PlexPlaylistItem.playlist_id == pid)
+        .order_by(PlexPlaylistItem.position, PlexPlaylistItem.id)
+    )
+
+
+@router.get("/playlists")
+def playlists(
+    contains: str | None = None,
+    contains_group: str | None = None,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The current user's playlists (newest-touched first), each with an item count + a cover thumb.
+    `contains`=an item rating_key adds `has_item` per playlist (for the single 'add to playlist' dialog).
+    `contains_group`=a comma-separated list of rating_keys adds `group_in` per playlist (how many of the
+    group it already holds) + a top-level `group_size`, for the 'add a whole season/show' dialog."""
+    contains_id = None
+    if contains:
+        contains_id = db.scalar(
+            select(PlexItem.id).where(PlexItem.rating_key == str(contains))
+        )
+    group_ids: set[int] | None = None
+    if contains_group is not None:
+        rks = [s for s in (contains_group or "").split(",") if s]
+        group_ids = set(
+            db.execute(
+                select(PlexItem.id).where(PlexItem.rating_key.in_(rks or [""]))
+            ).scalars()
+        )
+    out = []
+    for pl in db.execute(
+        select(PlexPlaylist)
+        .where(PlexPlaylist.user_id == user.id)
+        .order_by(PlexPlaylist.updated_at.desc())
+    ).scalars():
+        count = (
+            db.scalar(
+                select(func.count(PlexPlaylistItem.id)).where(
+                    PlexPlaylistItem.playlist_id == pl.id
+                )
+            )
+            or 0
+        )
+        first = db.execute(_playlist_item_query(pl.id)).first()
+        card = _playlist_card(pl, count, first[1].rating_key if first else None)
+        if contains_id is not None:
+            card["has_item"] = (
+                db.execute(
+                    select(PlexPlaylistItem.id).where(
+                        PlexPlaylistItem.playlist_id == pl.id,
+                        PlexPlaylistItem.item_id == contains_id,
+                    )
+                ).first()
+                is not None
+            )
+        if group_ids is not None:
+            card["group_in"] = (
+                db.scalar(
+                    select(func.count(PlexPlaylistItem.id)).where(
+                        PlexPlaylistItem.playlist_id == pl.id,
+                        PlexPlaylistItem.item_id.in_(group_ids or [0]),
+                    )
+                )
+                or 0
+            )
+        out.append(card)
+    resp: dict = {"playlists": out}
+    if group_ids is not None:
+        resp["group_size"] = len(group_ids)
+    return resp
+
+
+class CreatePlexPlaylistIn(BaseModel):
+    title: str = ""
+    item_rating_key: str = ""
+
+
+@router.post("/playlists")
+def create_playlist(
+    body: CreatePlexPlaylistIn,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    title = body.title.strip()
+    if not title:
+        raise HTTPException(status_code=400, detail="title is required")
+    pl = PlexPlaylist(user_id=user.id, title=title)
+    db.add(pl)
+    db.flush()
+    seed = body.item_rating_key
+    count = 0
+    thumb_rk = None
+    if seed:
+        it = by_rating_key(db, PlexItem, seed)
+        if it is not None:
+            db.add(PlexPlaylistItem(playlist_id=pl.id, item_id=it.id, position=0))
+            count, thumb_rk = 1, it.rating_key
+    db.commit()
+    return _playlist_card(pl, count, thumb_rk)
+
+
+@router.get("/playlists/{pid}")
+def playlist_detail(
+    pid: int, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
+    pl = _own_playlist_or_404(db, pid, user)
+    rows = db.execute(_playlist_item_query(pid)).all()
+    items = [it for (_pi, it) in rows]
+    states = {
+        s.item_id: s
+        for s in db.execute(
+            select(PlexState).where(
+                PlexState.user_id == user.id,
+                PlexState.item_id.in_([it.id for it in items] or [0]),
+            )
+        ).scalars()
+    }
+    shows = {
+        sh.id: sh
+        for sh in db.execute(
+            select(PlexShow).where(
+                PlexShow.id.in_([it.show_id for it in items if it.show_id] or [0])
+            )
+        ).scalars()
+    }
+    cards = [
+        leaf_card(
+            it,
+            states.get(it.id),
+            shows[it.show_id].title if it.show_id in shows else None,
+            shows[it.show_id].rating_key if it.show_id in shows else None,
+        )
+        for it in items
+    ]
+    return {"id": pl.id, "title": pl.title, "items": cards}
+
+
+class RenamePlexPlaylistIn(BaseModel):
+    title: str = ""
+
+
+@router.patch("/playlists/{pid}")
+def rename_playlist(
+    pid: int,
+    body: RenamePlexPlaylistIn,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    pl = _own_playlist_or_404(db, pid, user)
+    title = body.title.strip()
+    if not title:
+        raise HTTPException(status_code=400, detail="title is required")
+    pl.title = title
+    db.commit()
+    count = (
+        db.scalar(
+            select(func.count(PlexPlaylistItem.id)).where(
+                PlexPlaylistItem.playlist_id == pl.id
+            )
+        )
+        or 0
+    )
+    first = db.execute(_playlist_item_query(pl.id)).first()
+    return _playlist_card(pl, count, first[1].rating_key if first else None)
+
+
+@router.delete("/playlists/{pid}")
+def delete_playlist(
+    pid: int, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> dict:
+    pl = _own_playlist_or_404(db, pid, user)
+    db.delete(pl)
+    db.commit()
+    return {"deleted": pid}
+
+
+class PlexItemRefIn(BaseModel):
+    item_rating_key: str = ""
+
+
+@router.post("/playlists/{pid}/items")
+def playlist_add_item(
+    pid: int,
+    body: PlexItemRefIn,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    pl = _own_playlist_or_404(db, pid, user)
+    it = by_rating_key(db, PlexItem, body.item_rating_key)
+    if it is None:
+        raise HTTPException(status_code=404, detail="Unknown item")
+    exists = db.execute(
+        select(PlexPlaylistItem).where(
+            PlexPlaylistItem.playlist_id == pid, PlexPlaylistItem.item_id == it.id
+        )
+    ).scalars().first()
+    if exists is None:
+        maxpos = db.scalar(
+            select(func.coalesce(func.max(PlexPlaylistItem.position), -1)).where(
+                PlexPlaylistItem.playlist_id == pid
+            )
+        )
+        db.add(
+            PlexPlaylistItem(playlist_id=pid, item_id=it.id, position=int(maxpos) + 1)
+        )
+        pl.updated_at = datetime.now(timezone.utc)
+    db.commit()
+    return {"ok": True}
+
+
+@router.delete("/playlists/{pid}/items/{item_rating_key}")
+def playlist_remove_item(
+    pid: int,
+    item_rating_key: str,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    pl = _own_playlist_or_404(db, pid, user)
+    it = by_rating_key(db, PlexItem, item_rating_key)
+    if it is not None:
+        db.execute(
+            delete(PlexPlaylistItem).where(
+                PlexPlaylistItem.playlist_id == pid, PlexPlaylistItem.item_id == it.id
+            )
+        )
+        pl.updated_at = datetime.now(timezone.utc)
+    db.commit()
+    return {"ok": True}
+
+
+class PlexItemKeysIn(BaseModel):
+    item_rating_keys: list[str] = []
+
+
+def _items_by_rks(db: Session, rks: list) -> list[PlexItem]:
+    """Resolve rating_keys to PlexItems, preserving the input order (drops unknown keys)."""
+    order = [str(k) for k in rks if str(k)]
+    if not order:
+        return []
+    by_rk = {
+        it.rating_key: it
+        for it in db.execute(
+            select(PlexItem).where(PlexItem.rating_key.in_(order))
+        ).scalars()
+    }
+    seen: set[str] = set()
+    out: list[PlexItem] = []
+    for rk in order:
+        it = by_rk.get(rk)
+        if it is not None and rk not in seen:
+            seen.add(rk)
+            out.append(it)
+    return out
+
+
+@router.post("/playlists/{pid}/items/bulk")
+def playlist_add_bulk(
+    pid: int,
+    body: PlexItemKeysIn,
+    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)
+    items = _items_by_rks(db, body.item_rating_keys)
+    existing = set(
+        db.execute(
+            select(PlexPlaylistItem.item_id).where(PlexPlaylistItem.playlist_id == pid)
+        ).scalars()
+    )
+    pos = int(
+        db.scalar(
+            select(func.coalesce(func.max(PlexPlaylistItem.position), -1)).where(
+                PlexPlaylistItem.playlist_id == pid
+            )
+        )
+    )
+    added = 0
+    for it in items:
+        if it.id in existing:
+            continue
+        pos += 1
+        db.add(PlexPlaylistItem(playlist_id=pid, item_id=it.id, position=pos))
+        existing.add(it.id)
+        added += 1
+    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 {"added": added, "item_count": total}
+
+
+@router.post("/playlists/{pid}/items/remove-bulk")
+def playlist_remove_bulk(
+    pid: int,
+    body: PlexItemKeysIn,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> 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)
+    ids = [it.id for it in _items_by_rks(db, body.item_rating_keys)]
+    removed = 0
+    if ids:
+        removed = db.execute(
+            delete(PlexPlaylistItem).where(
+                PlexPlaylistItem.playlist_id == pid, PlexPlaylistItem.item_id.in_(ids)
+            ),
+            execution_options={"synchronize_session": False},
+        ).rowcount
+        if removed:
+            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 {"removed": removed, "item_count": total}
+
+
+@router.put("/playlists/{pid}/order")
+def reorder_playlist(
+    pid: int,
+    body: PlexItemKeysIn,
+    user: User = Depends(current_user),
+    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)
+    order = body.item_rating_keys
+    id_by_rk = {
+        it.rating_key: it.id
+        for it in db.execute(
+            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)
+            )
+    pl.updated_at = datetime.now(timezone.utc)
+    db.commit()
+    return {"ok": True}

backend/app/routes/quota.py

@@ -10,10 +10,9 @@ from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
 from app import quota
-from app.auth import current_user
+from app.auth import admin_user, current_user
 from app.db import get_db
 from app.models import QuotaEvent, User
-from app.routes.admin import admin_user
 
 router = APIRouter(prefix="/api/quota", tags=["quota"])
 

backend/app/routes/scheduler.py

@@ -8,10 +8,10 @@ from sqlalchemy.orm import Session
 
 from app import audit, quota, state, sysconfig
 from app.audit import AuditAction
+from app.auth import admin_user
 from app.config import settings
 from app.db import get_db
 from app.models import Channel, Subscription, User, Video
-from app.routes.admin import admin_user
 from app.scheduler import (
     JOB_INTERVALS,
     MAX_INTERVAL,
@@ -90,17 +90,13 @@ def set_maintenance_settings(
     db: Session = Depends(get_db),
 ) -> dict:
     """Admin-tune the maintenance job's rolling re-validation batch (videos re-checked per
-    run). Persisted to app_state; the job reads it each run."""
+    run). Persisted via sysconfig; the job reads it each run."""
-    value = body.revalidate_batch
+    # set_value validates against the spec's min/max (one source of bounds), mirroring the config PATCH.
-    if not (state.MAINTENANCE_BATCH_MIN <= value <= state.MAINTENANCE_BATCH_MAX):
+    try:
-        raise HTTPException(
+        sysconfig.set_value(db, "maintenance_revalidate_batch", body.revalidate_batch)
-            status_code=400,
+    except (TypeError, ValueError) as exc:
-            detail=(
+        raise HTTPException(status_code=400, detail=str(exc) or "Invalid value")
-                f"revalidate_batch must be between {state.MAINTENANCE_BATCH_MIN} and "
+    new = sysconfig.get_int(db, "maintenance_revalidate_batch")
-                f"{state.MAINTENANCE_BATCH_MAX}"
-            ),
-        )
-    new = state.set_maintenance_batch(db, value)
     audit.record(db, admin.id, AuditAction.MAINTENANCE_TUNE, summary=f"revalidate batch = {new}", after={"revalidate_batch": new})
     db.commit()
     return {"revalidate_batch": new}
@@ -167,6 +163,7 @@ def get_scheduler(
         "daily_budget": sysconfig.get_int(db, "quota_daily_budget"),
         "backfill_reserve": sysconfig.get_int(db, "backfill_quota_reserve"),
     }
+    maint = sysconfig.spec("maintenance_revalidate_batch")
 
     return {
         **snap,
@@ -174,9 +171,9 @@ def get_scheduler(
         "queue": queue,
         "quota": quota_info,
         "maintenance": {
-            "revalidate_batch": state.get_maintenance_batch(db),
+            "revalidate_batch": sysconfig.get_int(db, "maintenance_revalidate_batch"),
             "revalidate_batch_default": settings.maintenance_revalidate_batch,
-            "min": state.MAINTENANCE_BATCH_MIN,
+            "min": maint.min,
-            "max": state.MAINTENANCE_BATCH_MAX,
+            "max": maint.max,
         },
     }

backend/app/routes/search.py

@@ -36,9 +36,9 @@ from app.models import (
     Video,
     VideoState,
 )
-from app.routes.feed import _serialize, feed_columns
+from app.feedquery import feed_columns, serialize
 from app.sync.subscriptions import apply_channel_details
-from app.sync.videos import _insert_stubs, apply_video_details, parse_dt
+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
@@ -102,7 +102,7 @@ def _serialize_ids(db: Session, user: User, ids: list[str]) -> list[dict]:
         .outerjoin(state, and_(state.video_id == Video.id, state.user_id == user.id))
         .where(Video.id.in_(ids))
     ).all()
-    by_id = {r.id: _serialize(r) for r in rows}
+    by_id = {r.id: serialize(r) for r in rows}
     return [by_id[i] for i in ids if i in by_id]
 
 
@@ -136,7 +136,7 @@ def _ingest_candidates(
 
     # 2) Video stubs, flagged via_search. Existing rows keep their flags (ON CONFLICT DO
     #    NOTHING), so an organically-synced video stays organic.
-    _insert_stubs(
+    insert_stubs(
         db,
         [
             {
@@ -268,7 +268,11 @@ def search_youtube(
             except (YouTubeError, search_scrape.ScrapeError) as exc:
                 if collected:
                     break  # keep what we already gathered
-                raise HTTPException(status_code=502, detail=f"YouTube search failed: {exc}")
+                # 422, not 502: this is a JSON endpoint, and the FE treats 502/503/504 as a gateway
+                # 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
 
             # Drop currently-live/upcoming, channel-less, and blocked-channel results.
             candidates = [

backend/app/routes/setup.py

@@ -3,7 +3,7 @@
 `GET /api/setup/status` is public (the SPA uses it to decide whether to show the wizard). Every
 mutating step goes through `require_setup`: it rejects once the instance is configured AND requires
 the one-time setup token (printed to the container logs at first boot, carried by the wizard as the
-X-Setup-Token header). The wizard steps themselves are added in epic 6c.
+X-Setup-Token header).
 """
 from typing import Any
 
@@ -96,6 +96,7 @@ def setup_config(settings_map: dict[str, Any], db: Session = Depends(require_set
         except (ValueError, RuntimeError) as exc:
             raise HTTPException(status_code=400, detail=str(exc))
         saved.append(key)
+    db.commit()  # sysconfig.set_value only flushes now — persist the wizard's config in one commit
     return {"saved": saved}
 
 

backend/app/routes/sync.py

@@ -7,30 +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.sync.runner import (
+from app.sync.runner import estimate_deep_backfill
-    estimate_deep_backfill,
-    run_enrich,
-    run_recent_backfill,
-    run_rss_poll,
-)
 from app.sync.subscriptions import import_subscriptions
 from app.scheduler import running_job_ids
 
 router = APIRouter(prefix="/api/sync", tags=["sync"])
 
 
-def _user_channels(db: Session, user: User) -> list[Channel]:
-    return (
-        db.execute(
-            select(Channel)
-            .join(Subscription, Subscription.channel_id == Channel.id)
-            .where(Subscription.user_id == user.id)
-        )
-        .scalars()
-        .all()
-    )
-
-
 @router.post("/subscriptions")
 def sync_subscriptions(
     user: User = Depends(require_human), db: Session = Depends(get_db)
@@ -48,38 +31,6 @@ def sync_subscriptions(
     return result
 
 
-@router.post("/rss")
-def sync_rss(
-    user: User = Depends(require_human), db: Session = Depends(get_db)
-) -> dict:
-    # A partial failure comes back in `failed_feeds` so a manual poll reports it instead of an
-    # innocent-looking "0 new"; a TOTAL outage raises out of run_rss_poll and surfaces as a 500,
-    # which is the honest answer for a poll that reached nothing.
-    result = run_rss_poll(db, _user_channels(db, user))
-    return {"new_videos": result["new"], "failed_feeds": result["failed"]}
-
-
-@router.post("/backfill")
-def sync_backfill(
-    user: User = Depends(require_human),
-    db: Session = Depends(get_db),
-    max_channels: int = 25,
-) -> dict:
-    with quota.measured(db, user.id, quota.QuotaAction.VIDEOS_BACKFILL_RECENT) as m:
-        result = run_recent_backfill(db, _user_channels(db, user), max_channels=max_channels)
-    result["quota_used_estimate"] = m.used
-    return result
-
-
-@router.post("/enrich")
-def sync_enrich(
-    user: User = Depends(require_human), db: Session = Depends(get_db)
-) -> dict:
-    with quota.measured(db, user.id, quota.QuotaAction.VIDEOS_ENRICH) as m:
-        enriched = run_enrich(db)
-    return {"enriched": enriched, "quota_used_estimate": m.used}
-
-
 @router.get("/status")
 def sync_status(
     user: User = Depends(current_user), db: Session = Depends(get_db)

backend/app/routes/tags.py

@@ -4,11 +4,10 @@ from sqlalchemy import func, or_, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
-from app.auth import admin_user, current_user
+from app.auth import current_user
 from app.db import get_db
 from app.models import ChannelTag, Tag, User
 from app.routes._common import owned_or_404
-from app.sync.autotag import run_autotag_all
 
 router = APIRouter(prefix="/api/tags", tags=["tags"])
 
@@ -113,12 +112,3 @@ def delete_tag(
     db.delete(tag)  # ChannelTag rows cascade on tag delete.
     db.commit()
     return {"deleted": tag_id}
-
-
-@router.post("/recompute")
-def recompute(
-    _: User = Depends(admin_user),
-    db: Session = Depends(get_db),
-    only_missing: bool = False,
-) -> dict:
-    return run_autotag_all(db, only_missing=only_missing)

backend/app/scheduler.py

@@ -13,8 +13,9 @@ from app import audit, progress, quota
 from app.audit import AuditAction
 from app.config import settings
 from app.db import SessionLocal
+from app.demo import reset_demo_state
 from app.downloads.gc import run_download_gc
-from app.models import SchedulerSetting
+from app.models import SchedulerSetting, User
 from app.plex.sync import sync as run_plex_sync
 from app.plex.watch_sync import run_plex_watch_reconcile, run_plex_watch_sync
 from app.notifications import create_notification
@@ -310,14 +311,11 @@ def _maintenance_job() -> None:
 
 
 def _demo_reset_job() -> None:
-    # Auto-clean the shared demo sandbox. No-op (and never creates one) if there's no demo
+    # Auto-clean the shared demo sandbox. No-op (and never creates one) if there's no demo account.
-    # account. Lazy import avoids a routes<->scheduler import cycle.
     def work(db):
-        from app.models import User
         demo = db.query(User).filter(User.is_demo.is_(True)).one_or_none()
         if demo is None:
             return {"skipped": "no demo account"}
-        from app.routes.admin import reset_demo_state
         return {"playlists_seeded": reset_demo_state(db, demo)}
 
     _job("demo_reset", work)

backend/app/state.py

@@ -4,16 +4,11 @@ import secrets
 
 from sqlalchemy.orm import Session
 
-from app.config import settings
 from app.models import AppState
 from app.security import hash_token
 
 log = logging.getLogger("siftlode.state")
 
-# Bounds for the admin-set maintenance re-validation batch (videos re-checked per run).
-MAINTENANCE_BATCH_MIN = 100
-MAINTENANCE_BATCH_MAX = 100_000
-
 # Once configuration completes in this process it never reverts, so cache it to skip the per-request
 # DB hit in the setup-mode gate (see main.setup_gate). Starts False; refreshed from the DB.
 _configured_cache = False
@@ -33,10 +28,12 @@ def is_sync_paused(db: Session) -> bool:
 
 
 def set_sync_paused(db: Session, paused: bool) -> None:
+    # Flushes, doesn't commit — the caller owns the transaction so the change lands with its audit
+    # row in one transaction (B-core-10).
     row = _row(db)
     row.sync_paused = paused
     db.add(row)
-    db.commit()
+    db.flush()
     log.info("Background sync %s", "paused" if paused else "resumed")
 
 
@@ -90,20 +87,3 @@ def check_setup_token(db: Session, raw: str | None) -> bool:
         return False
     stored = _row(db).setup_token_hash
     return stored is not None and secrets.compare_digest(stored, hash_token(raw))
-
-
-def get_maintenance_batch(db: Session) -> int:
-    """Effective maintenance re-validation batch: the admin override if set, else the
-    env/config default."""
-    return _row(db).maintenance_revalidate_batch or settings.maintenance_revalidate_batch
-
-
-def set_maintenance_batch(db: Session, value: int) -> int:
-    """Clamp and persist the maintenance batch override. Returns the applied value."""
-    value = max(MAINTENANCE_BATCH_MIN, min(MAINTENANCE_BATCH_MAX, int(value)))
-    row = _row(db)
-    row.maintenance_revalidate_batch = value
-    db.add(row)
-    db.commit()
-    log.info("Maintenance re-validation batch set to %s", value)
-    return value

backend/app/sync/explore.py

@@ -23,7 +23,7 @@ from app.models import (
     Video,
     VideoState,
 )
-from app.sync.videos import _insert_stubs, _stub_from_playlist_item, apply_video_details
+from app.sync.videos import insert_stubs, stub_from_playlist_item, apply_video_details
 from app.utils import now_utc as _now
 from app.youtube.client import YouTubeClient
 
@@ -71,11 +71,11 @@ def explore_ingest_page(
     data = yt.get_playlist_items(channel.uploads_playlist_id, page_token)
     stubs: list[dict] = []
     for item in data.get("items", []):
-        stub = _stub_from_playlist_item(item, channel.id)
+        stub = stub_from_playlist_item(item, channel.id)
         if stub is not None:
             stub["via_explore"] = True
             stubs.append(stub)
-    inserted = _insert_stubs(db, stubs)
+    inserted = insert_stubs(db, stubs)
     self_enriched = _enrich_new(db, yt, [s["id"] for s in stubs])
     log.info(
         "explore ingest channel=%s ingested=%s enriched=%s", channel.id, inserted, self_enriched

backend/app/sync/maintenance.py

@@ -29,7 +29,6 @@ from app import progress, quota, sysconfig
 from app.config import settings
 from app.models import Playlist, PlaylistItem, Video
 from app.notifications import create_notification
-from app.state import get_maintenance_batch
 from app.sync.runner import get_service_user
 from app.sync.videos import apply_video_details, parse_dt
 from app.utils import now_utc as _now
@@ -182,22 +181,22 @@ def _recheck_flagged(db: Session, yt: YouTubeClient) -> dict:
 def _revalidate_rolling(db: Session, yt: YouTubeClient) -> dict:
     """Phase 2: re-check the least-recently-checked currently-available videos and flag any
     that have become unplayable (hidden immediately; deleted later if they don't recover)."""
-    batch = get_maintenance_batch(db)  # admin override, else config default
+    batch = sysconfig.get_int(db, "maintenance_revalidate_batch")  # admin override, else config default
     flagged_new = 0
     checked = 0
     now = _now()
     # Process in videos.list-sized pages so we commit incrementally and stop on low quota.
     while checked < batch:
-        if quota.remaining_today(db) <= sysconfig.get_int(db, "backfill_quota_reserve"):
+        if quota.backfill_reserve_reached():
             break
         page = (
             db.execute(
                 select(Video)
                 .where(Video.unavailable_since.is_(None))
-                .order_by(
+                # NULLS FIRST = never-checked first, then least-recently-checked; equivalent to the old
-                    Video.last_checked_at.is_(None).desc(),  # never-checked first
+                # `(last_checked_at IS NULL) DESC, last_checked_at ASC` but in the exact shape of the
-                    Video.last_checked_at.asc(),
+                # partial ix_videos_recheck_order (migration 0069, PERF-18) so it rides that index.
-                )
+                .order_by(Video.last_checked_at.asc().nulls_first())
                 .limit(min(50, batch - checked))
             )
             .scalars()
@@ -228,7 +227,7 @@ def run_maintenance(db: Session) -> dict:
         phase1 = _recheck_flagged(db, yt)
         phase2 = (
             _revalidate_rolling(db, yt)
-            if quota.remaining_today(db) > sysconfig.get_int(db, "backfill_quota_reserve")
+            if not quota.backfill_reserve_reached()
             else {"checked": 0, "flagged": 0, "skipped": "low quota"}
         )
     return {

backend/app/sync/playlists.py

@@ -1,6 +1,6 @@
-"""Read-direction YouTube playlist sync: mirror each user's own YouTube playlists into
+"""YouTube playlist sync, both directions. Read: mirror each user's own YouTube playlists
-local `source='youtube'` playlists (kept fresh by the scheduler). One-way (YT -> local);
+into local `source='youtube'` playlists (kept fresh by the scheduler). Write-back: push local
-the write-back direction (local edits -> YouTube) is a later phase.
+edits out to YouTube (`plan_push` / `push_playlist`), behind the optional write scope.
 
 YouTube's special Watch Later / History playlists are not exposed by the Data API and are
 never synced. Videos in a playlist that aren't in our shared catalog yet are fetched and
@@ -90,7 +90,9 @@ def _ensure_videos(db: Session, yt: YouTubeClient, video_ids: list[str]) -> None
         if not vid or not cid or vid in seen:
             continue
         seen.add(vid)
-        v = Video(id=vid, channel_id=cid, published_at=parse_dt(sn.get("publishedAt")))
+        # published_at is NOT NULL (0068); apply_video_details re-fills a missing date, but seed a now()
+        # fallback here too so the constructor never carries an explicit NULL.
+        v = Video(id=vid, channel_id=cid, published_at=parse_dt(sn.get("publishedAt")) or now)
         apply_video_details(v, it)
         v.enriched_at = now
         db.add(v)

backend/app/sync/runner.py

@@ -5,6 +5,7 @@ user" (any user with a stored refresh token) unless a YOUTUBE_API_KEY is configu
 public reads.
 """
 import logging
+import threading
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
 from sqlalchemy import select
@@ -13,6 +14,7 @@ from sqlalchemy.orm import Session
 from app import progress, quota, sysconfig
 
 log = logging.getLogger("siftlode.sync")
+from app.db import SessionLocal
 from app.models import Channel, OAuthToken, Subscription, User
 from app.sync.subscriptions import import_subscriptions
 from app.sync.videos import (
@@ -181,7 +183,7 @@ def run_recent_backfill(
     videos_added = 0
     with YouTubeClient(db, user) as yt:
         for channel in channels:
-            if quota.remaining_today(db) <= sysconfig.get_int(db, "backfill_quota_reserve"):
+            if quota.backfill_reserve_reached():
                 break
             try:
                 videos_added += backfill_channel_recent(db, yt, channel)
@@ -227,8 +229,14 @@ def run_deep_backfill(db: Session, max_channels: int = 10, max_pages: int = 5) -
     videos_added = 0
     with YouTubeClient(db, user) as yt:
         for channel in channels:
-            if quota.remaining_today(db) <= sysconfig.get_int(db, "backfill_quota_reserve"):
+            if quota.backfill_reserve_reached():
                 break
+            # Claim the channel (or skip it if an interactive backfill already owns it) so the two
+            # never advance the same cursor concurrently — symmetric with backfill_channel_now.
+            with _backfill_lock:
+                if channel.id in _backfill_in_progress:
+                    continue
+                _backfill_in_progress.add(channel.id)
             try:
                 videos_added += backfill_channel_deep(db, yt, channel, max_pages)
                 processed += 1
@@ -236,6 +244,9 @@ def run_deep_backfill(db: Session, max_channels: int = 10, max_pages: int = 5) -
             except Exception:
                 db.rollback()
                 log.exception("Deep backfill failed for channel %s", channel.id)
+            finally:
+                with _backfill_lock:
+                    _backfill_in_progress.discard(channel.id)
     reconciled = reconcile_full_history(db)
     return {
         "channels_processed": processed,
@@ -244,6 +255,63 @@ def run_deep_backfill(db: Session, max_channels: int = 10, max_pages: int = 5) -
     }
 
 
+# Channels being deep-backfilled RIGHT NOW by EITHER path — the interactive backfill_channel_now (a
+# FastAPI BackgroundTasks threadpool thread) OR the scheduler's run_deep_backfill (its own thread).
+# BOTH register the channel they're paging (under the lock) so the other skips it: no two runs page
+# the same channel's `backfill_cursor` concurrently, whichever started first. `_immediate_running`
+# counts only the interactive path, capped so one user's burst can't drain the shared budget (the
+# scheduler is already quota-paced). Single uvicorn process → one shared module state, lock suffices.
+_backfill_in_progress: set[str] = set()
+_immediate_running = 0
+_backfill_lock = threading.Lock()
+_MAX_CONCURRENT_IMMEDIATE = 2
+
+
+def backfill_channel_now(channel_id: str, user_id: int, max_pages: int = 400) -> None:
+    """User-initiated "get full history": deep-backfill ONE channel to completion right now, in a
+    background task with its OWN session, so the full catalogue lands in seconds instead of over the
+    paced scheduler's 10-minute ticks (max_pages=5/channel/tick). max_pages is high enough to finish
+    any realistic channel in a single run (400 pages = 20 000 videos; e.g. BBC Earth's ~3400 = 69
+    pages — the old 60-page cap stopped one page short of large channels, so their tail dribbled in
+    over the scheduler's 10-minute ticks and looked stuck). backfill_channel_deep re-checks the shared
+    budget before each page and yields at the reserve, so a high cap still can't drain the day's quota.
+    Quota-guarded, capped to _MAX_CONCURRENT_IMMEDIATE interactive runs so one user can't drain the
+    shared backfill budget by opting many channels in at once (the overflow, and any channel too large
+    to finish under the reserve, is finished by the scheduler since deep_requested stays set), and
+    mutually excluded per-channel with the scheduler via _backfill_in_progress. Best-effort — logs and
+    swallows failures."""
+    global _immediate_running
+    with _backfill_lock:
+        if channel_id in _backfill_in_progress or _immediate_running >= _MAX_CONCURRENT_IMMEDIATE:
+            return  # already backfilling this channel, or too many interactive runs — leave it to the scheduler
+        _backfill_in_progress.add(channel_id)
+        _immediate_running += 1
+    try:
+        with SessionLocal() as db:
+            user = get_service_user(db)
+            if user is None:
+                return
+            channel = db.get(Channel, channel_id)
+            if channel is None or channel.backfill_done or not channel.uploads_playlist_id:
+                return
+            if quota.backfill_reserve_reached():
+                return
+            try:
+                # Attribute the spend to the requesting user under the full-backfill action, so it
+                # shows up correctly in the usage breakdown (not the default OTHER/system bucket).
+                with quota.attribute(user_id, quota.QuotaAction.VIDEOS_BACKFILL_FULL):
+                    with YouTubeClient(db, user) as yt:
+                        backfill_channel_deep(db, yt, channel, max_pages)
+                    reconcile_full_history(db)
+            except Exception:
+                db.rollback()
+                log.exception("Immediate backfill failed for channel %s", channel_id)
+    finally:
+        with _backfill_lock:
+            _backfill_in_progress.discard(channel_id)
+            _immediate_running -= 1
+
+
 def estimate_deep_backfill(db: Session, channels: list[Channel]) -> dict:
     """Rough ETA to finish full-history backfill of `channels`. Quota-bound: total
     estimated API units / the daily budget left for backfill. Deliberately approximate —

backend/app/sync/subscriptions.py

@@ -6,6 +6,7 @@ from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.models import Channel, Subscription, User
+from app.utils import normalize_description
 from app.youtube.client import YouTubeClient, best_thumbnail
 
 log = logging.getLogger("siftlode.sync")
@@ -55,7 +56,7 @@ def apply_channel_details(db: Session, items: list[dict]) -> None:
 
         channel.title = snippet.get("title") or channel.title
         channel.handle = snippet.get("customUrl")
-        channel.description = snippet.get("description")
+        channel.description = normalize_description(snippet.get("description"))
         channel.thumbnail_url = (
             best_thumbnail(snippet.get("thumbnails")) or channel.thumbnail_url
         )
@@ -104,7 +105,7 @@ def import_subscriptions(db: Session, user: User) -> dict:
                 channel = Channel(
                     id=cid,
                     title=sub.get("title"),
-                    description=sub.get("description"),
+                    description=normalize_description(sub.get("description")),
                     thumbnail_url=sub.get("thumbnail_url"),
                 )
                 db.add(channel)

backend/app/sync/videos.py

@@ -10,7 +10,7 @@ from sqlalchemy import and_, func, or_, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
-from app import progress, sysconfig
+from app import progress, quota, sysconfig
 from app.models import LIVE_OR_UPCOMING, Channel, Video
 from app.titles import normalize_title
 from app.youtube.client import YouTubeClient, best_thumbnail
@@ -44,7 +44,7 @@ def parse_dt(value: str | None) -> datetime | None:
         return None
 
 
-def _insert_stubs(db: Session, rows: list[dict]) -> int:
+def insert_stubs(db: Session, rows: list[dict]) -> int:
     """Idempotently insert video stubs; returns the number of newly inserted rows.
 
     Uses RETURNING so the count is exact (ON CONFLICT DO NOTHING leaves rowcount
@@ -76,7 +76,7 @@ def apply_rss_feed(db: Session, channel: Channel, entries: list[dict]) -> int:
     """Insert new video stubs from an already-fetched feed and stamp the channel's last RSS
     time. DB-only — must run on the session's own thread; the network fetch
     (fetch_channel_feed) is kept separate so callers like run_rss_poll can parallelise it."""
-    inserted = _insert_stubs(db, entries)
+    inserted = insert_stubs(db, entries)
     channel.last_rss_at = _now()
     db.add(channel)
     db.commit()
@@ -84,13 +84,16 @@ def apply_rss_feed(db: Session, channel: Channel, entries: list[dict]) -> int:
 
 
 # --- Backfill (uploads playlist; costs quota) ---
-def _stub_from_playlist_item(item: dict, channel_id: str) -> dict | None:
+def stub_from_playlist_item(item: dict, channel_id: str) -> dict | None:
     content = item.get("contentDetails", {})
     snippet = item.get("snippet", {})
     video_id = content.get("videoId")
     if not video_id:
         return None
-    published = parse_dt(content.get("videoPublishedAt") or snippet.get("publishedAt"))
+    # published_at is NOT NULL (migration 0068); fall back to now() for the rare item that carries no
+    # date at all, so the bulk stub insert never writes a NULL. The enrich pass replaces it if the
+    # video's own snippet later yields a real publish date.
+    published = parse_dt(content.get("videoPublishedAt") or snippet.get("publishedAt")) or _now()
     return {
         "id": video_id,
         "channel_id": channel_id,
@@ -120,7 +123,7 @@ def backfill_channel_recent(db: Session, yt: YouTubeClient, channel: Channel) ->
         data = yt.get_playlist_items(channel.uploads_playlist_id, page_token)
         stopped_mid_page = False
         for item in data.get("items", []):
-            stub = _stub_from_playlist_item(item, channel.id)
+            stub = stub_from_playlist_item(item, channel.id)
             if stub is None:
                 continue
             if stub["published_at"] and stub["published_at"] < cutoff:
@@ -147,7 +150,7 @@ def backfill_channel_recent(db: Session, yt: YouTubeClient, channel: Channel) ->
     channel.recent_synced_at = _now()
     channel.backfill_cursor = next_cursor
     channel.backfill_done = done
-    inserted = _insert_stubs(db, collected)
+    inserted = insert_stubs(db, collected)
     db.add(channel)
     db.commit()
     return inserted
@@ -156,28 +159,37 @@ def backfill_channel_recent(db: Session, yt: YouTubeClient, channel: Channel) ->
 def backfill_channel_deep(
     db: Session, yt: YouTubeClient, channel: Channel, max_pages: int = 5
 ) -> int:
-    """Continue paging older uploads from the stored cursor (bounded per run)."""
+    """Continue paging older uploads from the stored cursor (bounded per run).
+
+    Commits the advanced cursor after every page (not just at the end) so progress
+    is durable: a restart resumes from the last stored page instead of re-fetching —
+    and re-charging quota for — pages already ingested. Re-checks the shared budget
+    before each page and yields once it hits the backfill reserve, so a single large
+    channel can't drain the day's quota in one run even with a high max_pages; the
+    paced scheduler finishes the tail on later ticks (deep_requested stays set)."""
     if channel.backfill_done or not channel.uploads_playlist_id:
         return 0
     page_token = channel.backfill_cursor
     total = 0
     for _ in range(max_pages):
+        if quota.backfill_reserve_reached():
+            break
         data = yt.get_playlist_items(channel.uploads_playlist_id, page_token)
         rows = [
             s
             for s in (
-                _stub_from_playlist_item(it, channel.id) for it in data.get("items", [])
+                stub_from_playlist_item(it, channel.id) for it in data.get("items", [])
             )
             if s is not None
         ]
-        total += _insert_stubs(db, rows)
+        total += insert_stubs(db, rows)
         page_token = data.get("nextPageToken")
         channel.backfill_cursor = page_token
+        channel.backfill_done = not page_token
+        db.add(channel)
+        db.commit()
         if not page_token:
-            channel.backfill_done = True
             break
-    db.add(channel)
-    db.commit()
     return total
 
 
@@ -234,7 +246,8 @@ def apply_video_details(video: Video, item: dict) -> None:
         video.title = normalize_title(raw_title)
     video.description = snippet.get("description")
     if not video.published_at:
-        video.published_at = parse_dt(snippet.get("publishedAt"))
+        # NOT NULL (0068): a fresh insert with no date yet falls back to now() (enrich normally has one).
+        video.published_at = parse_dt(snippet.get("publishedAt")) or _now()
     video.thumbnail_url = best_thumbnail(snippet.get("thumbnails")) or video.thumbnail_url
     video.duration_seconds = parse_iso8601_duration(content.get("duration"))
     video.view_count = int(stats["viewCount"]) if stats.get("viewCount") else None

backend/app/sysconfig.py

@@ -7,6 +7,7 @@ bounds, and whether it's a secret. The resolver returns the DB override if one i
 stored Fernet-encrypted at rest (requires TOKEN_ENCRYPTION_KEY; without it, secrets can't be
 stored in the DB and stay env-only).
 """
+import logging
 from dataclasses import dataclass
 
 from sqlalchemy.orm import Session
@@ -15,6 +16,12 @@ from app import security
 from app.config import settings
 from app.models import SystemConfig
 
+log = logging.getLogger("siftlode.config")
+
+# Config keys whose stored ciphertext failed to decrypt — tracked so the warning is logged once per
+# key, not once per request (bounded by the number of secret config keys).
+_decrypt_warned: set[str] = set()
+
 
 @dataclass(frozen=True)
 class ConfigSpec:
@@ -52,6 +59,10 @@ SPECS: tuple[ConfigSpec, ...] = (
     # --- Batch sizes ---
     ConfigSpec("enrich_batch_size", "int", "batch", "enrich_batch_size", min=1, max=50),
     ConfigSpec("autotag_title_sample", "int", "batch", "autotag_title_sample", min=1, max=1_000),
+    # --- Maintenance (rolling re-validation of already-known videos) ---
+    # Videos re-checked per maintenance run. Folded here from app_state (B-core-11) so every admin
+    # knob lives in one store; read by sync/maintenance.py, tuned from the Scheduler dashboard.
+    ConfigSpec("maintenance_revalidate_batch", "int", "maintenance", "maintenance_revalidate_batch", min=100, max=100_000),
     # --- Discovery cleanup (search + explore ephemeral content) ---
     # Days an explored-but-unsubscribed channel is kept before the cleanup job purges it.
     ConfigSpec("explore_grace_days", "int", "explore", "explore_grace_days", min=0, max=3_650),
@@ -86,10 +97,11 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec("plex_server_token", "str", "plex", "plex_server_token", secret=True),
     ConfigSpec("plex_path_map", "str", "plex", "plex_path_map"),
     ConfigSpec("plex_libraries", "str", "plex", "plex_libraries"),
+    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),
-    # NOTE: plex_watch_sync_interval_min (config.py default) is surfaced here in Phase C, when the
+    # NOTE: plex_watch_sync_interval_min is a config.py default read by the watch-sync scheduler job
-    # incremental watch-sync scheduler job that reads it lands.
+    # (scheduler.py); it is intentionally NOT a runtime admin knob, so it stays out of SPECS.
 )
 
 _BY_KEY: dict[str, ConfigSpec] = {s.key: s for s in SPECS}
@@ -117,11 +129,30 @@ def _coerce(s: ConfigSpec, raw: str):
 
 
 def _raw_override(db: Session, key: str) -> str | None:
-    """Stored (decrypted) override string for `key`, or None if no override is set."""
+    """Stored (decrypted) override string for `key`, or None if no override is set.
+
+    A decrypt failure — a rotated or removed ``TOKEN_ENCRYPTION_KEY`` vs the key the value was written
+    with — must NOT crash the caller. `_raw_override` sits on hot paths (`/api/me` via `google_enabled`,
+    login, every YouTube scheduler job, account purge), so a raw ``InvalidToken`` here would 500 the
+    whole app and the SPA wouldn't even boot. Fall back to the env/config default instead, and warn once
+    per key so the operator gets a real signal without a per-request traceback. Recovery is documented in
+    docs/self-hosting.md: the key must never change once secrets are stored. (B-core-2)
+    """
     row = db.get(SystemConfig, key)
     if row is None or row.value is None:
         return None
-    return security.decrypt(row.value) if row.encrypted else row.value
+    if not row.encrypted:
+        return row.value
+    try:
+        return security.decrypt(row.value)
+    except Exception:  # noqa: BLE001 — Fernet InvalidToken / malformed ciphertext (key mismatch)
+        if key not in _decrypt_warned:
+            _decrypt_warned.add(key)
+            log.warning(
+                "config %r could not be decrypted (TOKEN_ENCRYPTION_KEY changed or missing?) — falling "
+                "back to the env/config default; the key must not change once secrets are stored", key,
+            )
+        return None
 
 
 def get(db: Session, key: str):
@@ -155,7 +186,9 @@ def get_bool(db: Session, key: str) -> bool:
 
 
 def set_value(db: Session, key: str, value) -> None:
-    """Validate, coerce, and persist a DB override for `key`. Secrets are encrypted."""
+    """Validate, coerce, and stage a DB override for `key` (secrets are encrypted). Flushes but does
+    NOT commit — the caller owns the transaction, so the change lands together with its audit row
+    (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)
@@ -181,15 +214,16 @@ def set_value(db: Session, key: str, value) -> None:
         db.add(row)
     row.value = stored
     row.encrypted = encrypted
-    db.commit()
+    db.flush()
 
 
 def reset(db: Session, key: str) -> None:
-    """Remove the DB override for `key` (fall back to the env/config default)."""
+    """Remove the DB override for `key` (fall back to the env/config default). Flushes but does NOT
+    commit — the caller owns the transaction (B-core-10)."""
     row = db.get(SystemConfig, key)
     if row is not None:
         db.delete(row)
-        db.commit()
+        db.flush()
 
 
 def describe(db: Session) -> dict:

backend/app/titles.py

@@ -34,7 +34,15 @@ _ENGAGEMENT_PREFIX = re.compile(
     re.IGNORECASE,
 )
 _LETTER_RUN = re.compile(r"[^\W\d_]+", re.UNICODE)
-_TRAILING_HASHTAGS = re.compile(r"(?:\s+#[^\s#]*[^\W\d\s_][^\s#]*)+\s*$", re.UNICODE)
+# Trailing SEO hashtag cluster: a run of whitespace-separated `#tags` at the very end, where each
+# tag contains at least one letter (a bare numeric "#3" episode marker is NOT a hashtag and
+# survives). The "has a letter" test is a zero-width lookahead and the tag body is matched
+# possessively (`*+`), so there is exactly ONE way to split each tag and nothing to backtrack over.
+# The previous form `[^\s#]*[letter][^\s#]*` had TWO overlapping unbounded quantifiers around the
+# required letter: on a long hashtag run that ends with trailing non-tag text (a Facebook
+# "… #a #b #c | Page" title), the `$` anchor fails and the engine backtracks catastrophically
+# (ReDoS) — it pinned a worker thread at 100% CPU forever inside the download progress hook.
+_TRAILING_HASHTAGS = re.compile(r"(?:\s+#(?=[^\s#]*[^\W\d\s_])[^\s#]*+)+\s*$", re.UNICODE)
 _REPEAT_PUNCT = re.compile(r"([!?.,\-])\1{1,}")
 
 # Short function words → lowercased when the title is de-shouted (proper title-case style).

backend/app/utils.py

@@ -23,3 +23,31 @@ def valid_email(value: str | None) -> bool:
 def now_utc() -> datetime:
     """Current time as a timezone-aware UTC datetime."""
     return datetime.now(timezone.utc)
+
+
+def to_tsquery_str(q: str) -> str | None:
+    """Turn free-text into a to_tsquery() string: word runs ANDed together, the LAST word
+    prefix-matched (`:*`) for as-you-type search — e.g. "ti amo magyar" → "ti & amo & magyar:*".
+    Only `\\w` runs containing an alphanumeric are kept, so no tsquery operators can leak in
+    (the string is built from sanitised tokens, never the raw query). Shared by the YouTube feed
+    search and the Plex library search, hence this neutral home rather than either domain module."""
+    tokens = [t for t in re.findall(r"\w+", q, flags=re.UNICODE) if any(c.isalnum() for c in t)]
+    if not tokens:
+        return None
+    tokens[-1] = tokens[-1] + ":*"
+    return " & ".join(tokens)
+
+
+def normalize_description(text: str | None) -> str | None:
+    """Strip whitespace-only lines from a CHANNEL description before storing. YouTube channel
+    descriptions pad their contact/link blocks with runs of blank lines; keeping them wastes storage,
+    bloats the About popover, and adds nothing to the search document. Drops purely-empty lines and
+    right-strips each kept line; `str.splitlines()` also folds CR / CRLF and Unicode line separators
+    to "\\n" (a benign line-ending normalization). None stays None; all-blank collapses to "".
+
+    Deliberately CHANNEL-only — video descriptions are left with their original formatting: they are
+    user-facing prose where paragraph breaks carry meaning, unlike a channel's metadata block."""
+    if text is None:
+        return None
+    kept = [line.rstrip() for line in text.splitlines() if line.strip()]
+    return "\n".join(kept)

backend/app/worker.py

@@ -16,83 +16,41 @@ Design:
   * Crash-safe: on startup, orphaned `running` jobs are requeued and `downloading` assets reset.
 """
 import logging
-import re
+import os
 import shutil
 import signal
+import subprocess
+import sys
 import threading
 import time
-from datetime import date, datetime, timedelta, timezone
+from datetime import datetime, timezone
-from pathlib import Path
 
-import yt_dlp
 from sqlalchemy import text
 
 from app import sysconfig
 from app.config import settings
 from app.db import SessionLocal
 from app.downloads import edit as editmod
-from app.downloads import errors as dlerrors
+from app.downloads import quota, service
-from app.downloads import formats, quota, service, storage
+from app.downloads.jobdb import (
+    _edit_staging_dir,
+    _requeue_if_running,
+    _reset_asset_pending,
+    _set_job,
+    _staging_dir,
+)
+from app.downloads.status import STOPPED_BY_ROUTE, JobStatus
 from app.models import DownloadJob, MediaAsset
-from app.titles import normalize_title
 
 log = logging.getLogger("siftlode.worker")
 
 _stop = threading.Event()
 
 
-class _Aborted(Exception):
-    """Raised inside the progress hook when the job was paused/canceled mid-download."""
-
-
 def _handle_signal(signum, frame):
     _stop.set()
 
 
-# --- small DB helpers (short-lived sessions; the download itself holds no transaction) -------
-
-def _set_job(job_id: int, **fields) -> None:
-    with SessionLocal() as db:
-        job = db.get(DownloadJob, job_id)
-        if job is None:
-            return
-        for k, v in fields.items():
-            setattr(job, k, v)
-        db.commit()
-
-
-def _job_status(job_id: int) -> str | None:
-    with SessionLocal() as db:
-        return db.execute(
-            text("SELECT status FROM download_jobs WHERE id = :id"), {"id": job_id}
-        ).scalar()
-
-
-def _requeue_if_running(job_id: int, phase: str) -> None:
-    """Put the job back to 'queued' for a later retry, but ONLY while it is still 'running'. The
-    route flips status to paused/cancelled to stop a job; a blind `status='queued'` here would
-    clobber that and silently revive a job the user just cancelled. The conditional WHERE makes the
-    requeue a no-op unless we still own a running job."""
-    with SessionLocal() as db:
-        db.execute(
-            text(
-                "UPDATE download_jobs SET status='queued', phase=:phase, updated_at=now() "
-                "WHERE id=:id AND status='running'"
-            ),
-            {"id": job_id, "phase": phase},
-        )
-        db.commit()
-
-
-def _parse_upload_date(raw) -> date | None:
-    if not raw:
-        return None
-    try:
-        return datetime.strptime(str(raw), "%Y%m%d").date()
-    except ValueError:
-        return None
-
-
 # --- claim + recovery -----------------------------------------------------------------------
 
 def _wait_for_schema(timeout: float = 300.0) -> bool:
@@ -133,21 +91,49 @@ def _recover_orphans() -> None:
 
 
 def _claim_job() -> int | None:
-    """Claim the oldest queued job whose user is under their per-user concurrency limit.
+    """Claim the oldest queued job whose user is under their per-user concurrency limit AND whose
+    shared asset isn't already being downloaded by another worker.
 
-    Fetches a window of locked candidates (FOR UPDATE SKIP LOCKED) and picks the first eligible
+    The asset exclusion (`NOT EXISTS … media_assets.status='downloading'`) stops the same-asset ping-
-    one, so one user flooding the queue can't starve others beyond their max_concurrent."""
+    pong (B-sub-3): without it, a second worker claims a queued job that shares an in-flight asset,
+    finds it busy, requeues it, and immediately re-claims it — burning a worker slot behind one
+    in-flight asset and starving everyone else. Excluded here, that job simply waits until its asset
+    settles, so `_process_job` no longer needs to sleep on the busy/lost-race paths.
+
+    Users already AT their concurrency limit are excluded IN THE SQL, so one user flooding the
+    queue can't monopolize the fetch window and starve everyone behind them. (The old fixed
+    LIMIT-50 window did exactly that: 50 queued jobs from a single capped user filled the window,
+    `chosen` came back None, and every other user's work — sitting past position 50 — was never
+    seen.) The per-user limit is the quota row's `max_concurrent` (else the sysconfig default);
+    `unlimited` users are never capped. A final Python `at_concurrency_limit` re-check still guards
+    the tiny race between the exclusion subquery and the claim (it can only ever reject, never
+    over-claim), so correctness never depends on the two observations agreeing."""
     with SessionLocal() as db:
+        default_mc = sysconfig.get_int(db, "download_default_max_concurrent")
         rows = db.execute(
             text(
                 """
                 SELECT id, user_id FROM download_jobs
                 WHERE status='queued'
+                  AND NOT EXISTS (
+                      SELECT 1 FROM media_assets a
+                      WHERE a.id = download_jobs.asset_id AND a.status = 'downloading'
+                  )
+                  AND user_id NOT IN (
+                      SELECT r.user_id
+                      FROM download_jobs r
+                      LEFT JOIN download_quotas q ON q.user_id = r.user_id
+                      WHERE r.status='running' AND r.user_id IS NOT NULL
+                      GROUP BY r.user_id, q.max_concurrent, q.unlimited
+                      HAVING COALESCE(q.unlimited, false) = false
+                         AND count(*) >= GREATEST(COALESCE(q.max_concurrent, :dmc), 1)
+                  )
                 ORDER BY queue_pos, id
                 FOR UPDATE SKIP LOCKED
                 LIMIT 50
                 """
-            )
+            ),
+            {"dmc": default_mc},
         ).fetchall()
         chosen = next(
             (jid for jid, uid in rows if not quota.at_concurrency_limit(db, uid)), None
@@ -180,19 +166,217 @@ def _claim_asset(asset_id: int) -> bool:
         return row is not None
 
 
+# --- supervised child execution + watchdog --------------------------------------------------
+# The heavy work runs in a child process so a wedged yt-dlp/ffmpeg is HARD-killable. A worker thread
+# can't be killed, a C-level spin (e.g. a catastrophic regex) can't even be cooperatively cancelled,
+# and one such thread starves the rest via the GIL — the incident that motivated this. The parent
+# thread supervises: it kills the child (and its process group, so ffmpeg grandchildren die too) on
+# a route pause/cancel, on a no-progress stall, or past an absolute wall-clock cap.
+#
+# POSIX-only: the kill path uses process groups (start_new_session / os.killpg / os.getpgid), so the
+# worker is Linux-container-only — never run `python -m app.worker` natively on Windows.
+# Edits ALSO carry a second, tighter watchdog inside run_ffmpeg (a per-ffmpeg stall timeout with a
+# cleaner "ffmpeg stalled" error); this process-level supervisor is the uniform backstop for both the
+# download and edit paths, and the last line of defence for anything run_ffmpeg can't see.
+
+_CHILD_OK = 0
+
+
+def _spawn_download_child(job_id: int) -> subprocess.Popen:
+    """Start the child that does the actual download/edit for `job_id`, in its OWN session/process
+    group so stopping it also stops any ffmpeg / helper processes yt-dlp spawned."""
+    return subprocess.Popen(
+        [sys.executable, "-m", "app.downloads.runner", str(job_id)],
+        start_new_session=True,
+    )
+
+
+def _job_liveness(job_id: int) -> tuple[str | None, float | None]:
+    """(status, seconds-since-last-row-update) for the job, computed with the DB clock so there is
+    no parent↔DB skew. A live download rewrites its row ~1/s; a stalled one never does. Returns
+    (None, None) if the row is gone."""
+    with SessionLocal() as db:
+        row = db.execute(
+            text(
+                "SELECT status, EXTRACT(EPOCH FROM (now() - updated_at)) "
+                "FROM download_jobs WHERE id = :id"
+            ),
+            {"id": job_id},
+        ).one_or_none()
+    if row is None:
+        return None, None
+    return row[0], (float(row[1]) if row[1] is not None else None)
+
+
+def _signal_group(proc: subprocess.Popen, pgid: int | None, sig: int) -> None:
+    """Signal the child's whole process group (falling back to the child alone), swallowing the race
+    where it has already exited."""
+    try:
+        if pgid is not None:
+            os.killpg(pgid, sig)
+        else:
+            proc.send_signal(sig)
+    except (ProcessLookupError, OSError):
+        pass
+
+
+def _stop_child(proc: subprocess.Popen, grace_s: float) -> None:
+    """SIGTERM the child's process GROUP, then SIGKILL if it outlives the grace period. Shares the
+    terminate→wait→kill escalation with run_ffmpeg (`editmod.escalate_kill`); the only difference is
+    that we signal the whole group so ffmpeg grandchildren die too. `escalate_kill` no-ops if the
+    child already exited, and `getpgid` yields None for a reaped pid, so no separate poll guard."""
+    try:
+        pgid: int | None = os.getpgid(proc.pid)
+    except OSError:
+        pgid = None
+    editmod.escalate_kill(
+        proc,
+        terminate=lambda: _signal_group(proc, pgid, signal.SIGTERM),
+        kill=lambda: _signal_group(proc, pgid, signal.SIGKILL),
+        grace_s=grace_s,
+        label="download child",
+    )
+
+
+def _stop_and_free(job_id: int, asset_id: int, proc: subprocess.Popen, grace_s: float) -> None:
+    """Kill the child, free its claimed asset, and clear its staging — the common tail of every path
+    that stops a child (a route pause/cancel, a shutdown, an over-cap abandon)."""
+    _stop_child(proc, grace_s)
+    _reset_asset_pending(asset_id)
+    _cleanup_staging(asset_id)
+
+
+def _fail_after_kill(
+    job_id: int, asset_id: int, proc: subprocess.Popen, grace_s: float, error: str, error_code: str
+) -> None:
+    """`_stop_and_free` + mark the job errored — for the watchdog's stall/timeout kills and the
+    supervisor-error fallback."""
+    _stop_and_free(job_id, asset_id, proc, grace_s)
+    _set_job(job_id, status="error", error=error, error_code=error_code, phase=None)
+
+
+def _run_supervised(job_id: int, asset_id: int) -> None:
+    """Run the heavy download/edit for an already-claimed asset in a child process and watchdog it.
+
+    A clean child exit means the child already wrote the terminal job/asset state (done/error, or a
+    cooperative pause via the in-child progress hook) — we leave it. We step in only when the child
+    can't finish or self-abort: a route paused/cancelled it (kill, free the asset, keep the route's
+    status), it made no progress for `stall_timeout` or ran past `wall_clock_max` (kill, fail the
+    job), the worker is shutting down (kill, requeue), or it crashed without setting state."""
+    poll_s = max(1, settings.download_supervisor_poll_seconds)
+    stall_s = settings.download_stall_timeout_seconds
+    wall_s = settings.download_wall_clock_max_seconds
+    grace_s = settings.download_kill_grace_seconds
+
+    try:
+        proc = _spawn_download_child(job_id)
+    except Exception:  # noqa: BLE001 — spawn failed; don't leave the asset stuck 'downloading'
+        log.exception("failed to spawn download child for job %s", job_id)
+        _reset_asset_pending(asset_id)
+        _requeue_if_running(job_id, None)
+        return
+
+    started = time.monotonic()
+    reason: str | None = None
+    try:
+        while True:
+            try:
+                proc.wait(timeout=poll_s)
+                break  # child finished on its own
+            except subprocess.TimeoutExpired:
+                pass
+            status, stale = _job_liveness(job_id)
+            if status is None or status in STOPPED_BY_ROUTE:
+                reason = "cancelled"  # a route stopped it (or the row vanished)
+                break
+            if status == "running":
+                if stale is not None and stale > stall_s:
+                    reason = "stalled"
+                    break
+                if _stop.is_set():
+                    reason = "shutdown"
+                    break
+            # Absolute wall-clock cap frees the worker slot even for a FINISHED child wedged in
+            # teardown. A still-running job over the cap is failed ("timeout"); a terminal one (already
+            # done/error) just gets its lingering child killed, its DB status left intact ("abandon").
+            if time.monotonic() - started > wall_s:
+                reason = "timeout" if status == "running" else "abandon"
+                break
+            # else: a terminal status under the cap (done/error, or a re-queued contended asset) means
+            # the child is exiting on its own — keep polling; NEVER kill a finishing child (that could
+            # drop its completion notice).
+    except Exception:  # noqa: BLE001 — a watchdog error must NEVER leave the child running unsupervised
+        log.exception("supervisor loop failed for job %s; stopping the child", job_id)
+        _fail_after_kill(
+            job_id, asset_id, proc, grace_s, "The download was stopped after a worker error.", "unknown"
+        )
+        return
+
+    if reason is None:
+        # Child exited. Reconcile the asset we claimed: free it if the child left it non-finalized —
+        # a crash/OOM, or an early return on a job deleted mid-flight — a no-op when it finalized
+        # normally. Then, if it died non-zero while the job is still 'running', fail the job so it is
+        # not left stuck. Guarded: the child is already dead, so a DB blip here must not propagate.
+        try:
+            _reset_asset_pending(asset_id)
+            if proc.returncode != _CHILD_OK:
+                status, _ = _job_liveness(job_id)
+                if status == "running":
+                    _cleanup_staging(asset_id)
+                    _set_job(
+                        job_id, status="error", error_code="unknown", phase=None,
+                        error=f"The download process exited unexpectedly (code {proc.returncode}).",
+                    )
+                    log.warning("job %s: child exited %s without finishing", job_id, proc.returncode)
+        except Exception:  # noqa: BLE001 — boot recovery is the backstop for a stuck 'running' job
+            log.exception("post-exit reconciliation failed for job %s", job_id)
+        return
+
+    if reason == "stalled":
+        _fail_after_kill(
+            job_id, asset_id, proc, grace_s,
+            f"The download stalled (no progress for {int(stall_s)}s) and was stopped.", "network",
+        )
+        return
+    if reason == "timeout":
+        _fail_after_kill(
+            job_id, asset_id, proc, grace_s,
+            f"The download exceeded the {int(wall_s)}s time limit and was stopped.", "network",
+        )
+        return
+    # cancelled / abandon / shutdown: stop + free the asset, but leave the job's own DB status.
+    _stop_and_free(job_id, asset_id, proc, grace_s)
+    if reason == "shutdown":
+        _requeue_if_running(job_id, None)  # resume on the next boot
+    elif reason == "abandon":
+        log.warning("job %s: killed a child wedged past the wall-clock; DB status left intact", job_id)
+    else:  # cancelled
+        log.info("job %s: child stopped (route pause/cancel)", job_id)
+
+
+def _cleanup_staging(asset_id: int) -> None:
+    """Best-effort removal of a killed child's leftover staging dirs (its own `finally` never ran).
+    The next attempt on this asset also wipes staging on start, so this is just tidiness/disk."""
+    for path in (_staging_dir(asset_id), _edit_staging_dir(asset_id)):
+        shutil.rmtree(path, ignore_errors=True)
+
+
 # --- processing -----------------------------------------------------------------------------
 
 def _process_job(job_id: int) -> None:
+    """Dispatch a claimed job. The trivial outcomes (cache hit, dead/contended asset) are handled
+    inline and cheaply; the actual heavy work (yt-dlp download / ffmpeg edit) is claimed here and
+    then run in a supervised CHILD PROCESS (`_run_supervised`) so a wedged yt-dlp/ffmpeg can be
+    hard-killed — a worker THREAD cannot be killed, nor (when it spins in a C call) even
+    cooperatively cancelled, and one such thread starves the others via the GIL."""
     with SessionLocal() as db:
         job = db.get(DownloadJob, job_id)
         if job is None:
             return
         asset = db.get(MediaAsset, job.asset_id) if job.asset_id else None
-        spec = dict(job.profile_snapshot or {})
-        source_kind, source_ref = job.source_kind, job.source_ref
-        job_kind = job.job_kind
         asset_id = asset.id if asset else None
         asset_status = asset.status if asset else None
+        asset_error = asset.error if asset else None
 
     if asset is None:
         _set_job(job_id, status="error", error="No media asset", phase=None)
@@ -202,24 +386,23 @@ def _process_job(job_id: int) -> None:
         _finish_from_cache(job_id, asset_id)
         return
     if asset_status == "error":
-        _set_job(job_id, status="error", error=asset.error or "Download failed", phase=None)
+        _set_job(job_id, status="error", error=asset_error or "Download failed", phase=None)
         return
     if asset_status == "downloading":
-        # Another worker owns this asset; wait and let the job be reclaimed later.
+        # Another worker won this asset between our claim and here (a narrow race — the claim SQL
+        # excludes downloading-asset jobs). Requeue and let it be reclaimed once the asset settles;
+        # no sleep — the claim exclusion keeps it out of the window until then, so no busy-loop.
         _requeue_if_running(job_id, "waiting")
-        time.sleep(2)
         return
 
     # asset_status == "pending": try to win the download / edit.
     if not _claim_asset(asset_id):
+        # Lost the pending->downloading race; requeue (same reasoning — the exclusion prevents a spin).
         _requeue_if_running(job_id, "waiting")
-        time.sleep(2)
         return
 
-    if job_kind == "edit":
+    # The asset is now ours ('downloading'): run the heavy work in a supervised child process.
-        _process_edit(job_id, asset_id)
+    _run_supervised(job_id, asset_id)
-    else:
-        _download(job_id, asset_id, source_kind, source_ref, spec)
 
 
 def _finish_from_cache(job_id: int, asset_id: int) -> None:
@@ -227,560 +410,17 @@ def _finish_from_cache(job_id: int, asset_id: int) -> None:
         job = db.get(DownloadJob, job_id)
         asset = db.get(MediaAsset, asset_id)
         if job and asset:
-            job.status = "done"
+            fields = {"status": JobStatus.DONE, "progress": 100, "phase": None}
-            job.progress = 100
+            if not job.display_name and asset.title:
-            job.phase = None
-            if not job.display_name:
                 # display_name is VARCHAR(255); a title can be longer (e.g. a recipe in the title).
-                job.display_name = asset.title[:255] if asset.title else None
+                fields["display_name"] = asset.title[:255]
             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).
+            service.finalize_if_running(db, job_id, **fields)
         db.commit()
 
 
-def _uploader_url(info: dict) -> str | None:
-    """The channel/uploader page URL for the auto-clickable channel line. YouTube gives a
-    `channel_url`/`uploader_url` directly; Facebook gives neither but exposes a numeric
-    `uploader_id` (the page id) that resolves at facebook.com/<id>. Returns None for sources with
-    no derivable channel page (e.g. reddit / a raw media URL)."""
-    url = info.get("channel_url") or info.get("uploader_url")
-    if url:
-        return url
-    uid = info.get("uploader_id")
-    tag = f"{info.get('extractor_key') or info.get('extractor') or ''} {info.get('webpage_url') or ''}".lower()
-    if uid and "facebook" in tag:
-        return f"https://www.facebook.com/{uid}"
-    return None
-
-
-def _fill_asset_meta_early(asset_id: int, info: dict) -> None:
-    """Populate an asset's display metadata from yt-dlp's info_dict the first time it's seen
-    (only if not already filled at enqueue from our catalog) — so an ad-hoc URL's row shows a
-    real title + thumbnail while it downloads, not just the URL. Zero extra network cost."""
-    with SessionLocal() as db:
-        asset = db.get(MediaAsset, asset_id)
-        if asset is None or asset.title:
-            return
-        # `or info.get("id")` avoids a blank card while downloading when the cleaned title is empty
-        # (e.g. a title that was only a social engagement prefix); the completion path later sets
-        # the final title with its own source_ref fallback.
-        asset.title = normalize_title(info.get("title")) or info.get("id")
-        asset.uploader = info.get("uploader") or info.get("channel")
-        asset.uploader_url = _uploader_url(info)
-        asset.thumbnail_url = info.get("thumbnail")
-        asset.duration_s = int(info["duration"]) if info.get("duration") else None
-        asset.upload_date = _parse_upload_date(info.get("upload_date"))
-        asset.source_webpage_url = info.get("webpage_url")
-        db.commit()
-
-
-def _make_progress_hook(job_id: int, asset_id: int):
-    state = {"meta_done": False}
-    cancelled = _cancel_poll(job_id)          # same policy as the ffmpeg path
-    allow_write = _rate_limiter(_DB_WRITE_INTERVAL_S)
-
-    def hook(d: dict) -> None:
-        # Cooperative pause/cancel: if the job is no longer 'running', abort the download.
-        if cancelled():
-            raise _Aborted
-        if not state["meta_done"] and d.get("info_dict"):
-            state["meta_done"] = True
-            try:
-                _fill_asset_meta_early(asset_id, d["info_dict"])
-            except Exception:  # noqa: BLE001 — metadata is best-effort, never fail a download
-                pass
-        if d.get("status") != "downloading":
-            return
-        if not allow_write():
-            return
-        # yt-dlp downloads the video and audio streams SEPARATELY (each 0→100%), then merges.
-        # Label the phase so the user understands the bar resetting between streams instead of
-        # seeing a mysterious 95%→5% jump.
-        info = d.get("info_dict") or {}
-        vcodec = info.get("vcodec") or "none"
-        acodec = info.get("acodec") or "none"
-        if vcodec != "none" and acodec == "none":
-            phase = "video"
-        elif acodec != "none" and vcodec == "none":
-            phase = "audio"
-        else:
-            phase = "media"
-        total = d.get("total_bytes") or d.get("total_bytes_estimate") or 0
-        done = d.get("downloaded_bytes") or 0
-        pct = int(done * 100 / total) if total else 0
-        _set_job(
-            job_id,
-            progress=min(pct, 99),
-            speed_bps=int(d["speed"]) if d.get("speed") else None,
-            eta_s=int(d["eta"]) if d.get("eta") else None,
-            phase=phase,
-        )
-
-    return hook
-
-
-# Both progress sources call back FAR faster than the database should be touched: yt-dlp fires its
-# hook per chunk, and ffmpeg's `-progress pipe:1` emits a block of ~12 lines every ~0.5s while
-# run_ffmpeg calls its callbacks once per LINE. Every callback here is a round-trip (`_job_status`
-# opens a session and SELECTs; `_set_job` opens one and UPDATE+COMMITs), so unthrottled they cost
-# ~10^5 queries on a long job. ONE interval, ONE implementation, used by both paths — three
-# hand-rolled copies is how the ffmpeg side ended up unthrottled while the download side was fine.
-_DB_WRITE_INTERVAL_S = 1.0
-_CANCEL_POLL_INTERVAL_S = 1.0
-
-
-def _rate_limiter(interval_s: float, *, now=time.monotonic):
-    """`should_run()` → True at most once per `interval_s` (the first call always passes).
-    `now` is injectable so tests drive a clock instead of patching the global one."""
-    # `None`, not 0.0: "never ran" has to be a VALUE, not a falsy timestamp. A truthiness test here
-    # reads a legitimate `now() == 0.0` as "never ran" and lets a second call straight through —
-    # unreachable with real `time.monotonic()`, but `now` exists to be injected, and a test clock
-    # starting at 0 is the obvious choice. That would let a throttle test encode the wrong
-    # behaviour and still pass.
-    state: dict[str, float | None] = {"at": None}
-
-    def should_run() -> bool:
-        t = now()
-        last = state["at"]
-        if last is not None and t - last < interval_s:
-            return False
-        state["at"] = t
-        return True
-
-    return should_run
-
-
-def _cancel_poll(job_id: int, interval_s: float = _CANCEL_POLL_INTERVAL_S, *, now=time.monotonic):
-    """Cooperative "has this job been paused/cancelled?" poll, rate-limited and sticky: once it
-    says yes it never queries again. Shared by the yt-dlp hook and run_ffmpeg so cancel latency is
-    one policy, not one per call site."""
-    allow = _rate_limiter(interval_s, now=now)
-    state = {"cancelled": False}
-
-    def cancelled() -> bool:
-        if not state["cancelled"] and allow():
-            state["cancelled"] = _job_status(job_id) not in ("running", None)
-        return state["cancelled"]
-
-    return cancelled
-
-
-def _ffmpeg_progress_writer(job_id: int, phase: str, *, now=time.monotonic):
-    """`on_progress` for run_ffmpeg: persist at most one row write per interval, and only when the
-    whole-percent value actually changed (the bar shows integers)."""
-    allow = _rate_limiter(_DB_WRITE_INTERVAL_S, now=now)
-    state = {"pct": -1}
-
-    def write(pct: float) -> None:
-        whole = int(pct)
-        if whole == state["pct"] or not allow():
-            return
-        state["pct"] = whole
-        _set_job(job_id, progress=whole, phase=phase)
-
-    return write
-
-
-def _pp_phase(pp: str) -> str:
-    """Map a yt-dlp postprocessor class name to a user-facing phase label. ffmpeg post-steps
-    aren't byte-progress operations (no %), so the UI shows the step name + an indeterminate
-    pulse — this makes the long merge/finalize legible instead of a silent 'Processing'."""
-    if "Merg" in pp:
-        return "merging"
-    if "ExtractAudio" in pp:
-        return "audio_extract"
-    if "Thumbnail" in pp:
-        return "thumbnail"
-    if "SponsorBlock" in pp or "ModifyChapters" in pp:
-        return "sponsorblock"
-    if "Metadata" in pp:
-        return "metadata"
-    return "processing"
-
-
-def _make_pp_hook(job_id: int):
-    """Postprocessor hook: surface the current ffmpeg step so the bar shows a concrete label
-    (Merging / Embedding thumbnail / …) instead of freezing at 100% after the streams finish."""
-
-    def hook(d: dict) -> None:
-        if d.get("status") in ("started", "processing"):
-            _set_job(job_id, phase=_pp_phase(d.get("postprocessor") or ""), speed_bps=None, eta_s=None)
-
-    return hook
-
-
-def _staging_dir(asset_id: int) -> Path:
-    return Path(settings.download_root) / ".staging" / f"asset-{asset_id}"
-
-
-_THUMB_SUFFIXES = (".jpg", ".jpeg", ".png", ".webp")
-# yt-dlp's working files in the staging dir. None of them is ever the finished media, but several
-# CAN be the biggest file there (a video-only per-format stream, an abandoned fragment run), so the
-# staging fallback must exclude them by name — picking one would store e.g. a silent video-only
-# stream as a ready asset.
-_YTDLP_TEMP_RE = re.compile(
-    r"\.part(-Frag\d+)?$"  # in-flight download / fragment
-    r"|\.ytdl$"  # resume state
-    r"|\.temp\.[^.]+$"  # merge/postprocess temp
-    r"|\.f\d+\.[^.]+$",  # per-format stream kept before the merge
-    re.IGNORECASE,
-)
-
-
-def _find_thumbnail(staging: Path, media: Path) -> Path | None:
-    for p in staging.iterdir():
-        if p != media and p.suffix.lower() in _THUMB_SUFFIXES:
-            return p
-    return None
-
-
-def _produced_file(info: dict, staging: Path) -> Path:
-    """The media file yt-dlp actually wrote.
-
-    `requested_downloads[0].filepath` is the authoritative answer on YouTube, but an arbitrary-URL
-    extractor may not fill it in at all — and `Path("")` is `Path(".")`, which *passes* `.exists()`,
-    so a missing value used to sail past the fallback and blow up two steps later (`with_name` on an
-    empty name: the BBC-news failure). Anything that isn't a real file counts as absent; then fall
-    back to the largest file left in staging that is neither a thumbnail nor one of yt-dlp's own
-    working files (see `_YTDLP_TEMP_RE`)."""
-    req = (info.get("requested_downloads") or [{}])[0]
-    fp = req.get("filepath") or req.get("_filename") or info.get("filepath") or info.get("_filename")
-    if fp:
-        produced = Path(str(fp))
-        if produced.is_file():
-            return produced
-    cands = [
-        p
-        for p in staging.iterdir()
-        if p.is_file()
-        and p.suffix.lower() not in _THUMB_SUFFIXES
-        and not _YTDLP_TEMP_RE.search(p.name)
-    ]
-    if not cands:
-        raise RuntimeError("yt-dlp produced no output file")
-    return max(cands, key=lambda p: p.stat().st_size)
-
-
-def _media_info(info: dict) -> dict:
-    """Unwrap a playlist/multi_video extraction to the entry that carries the download.
-
-    A single non-YouTube page (a news article's video, a multi-rendition embed) can extract as a
-    wrapper whose own dict has no `requested_downloads` — the media lives on an entry. Pick the
-    FIRST entry that actually downloaded something: on a page with a skipped teaser in front of the
-    real video, entries[0] carries no file, and taking it blindly would label the produced file
-    with the wrong id/title/duration."""
-    entries = [e for e in (info.get("entries") or []) if e]
-    if not entries or info.get("requested_downloads"):
-        return info
-    chosen = next((e for e in entries if e.get("requested_downloads")), entries[0])
-    return {**info, **chosen}
-
-
-# Errors worth retrying with a different player-client set (YouTube per-client flakiness).
-_RETRIABLE_MARKERS = (
-    "not a bot",
-    "DRM protected",
-    "Requested format is not available",
-    "Only images are available",
-    "Sign in to confirm",
-)
-
-
-def _extract_with_fallback(job_id: int, asset_id: int, url: str, spec: dict, staging: Path):
-    """Download via yt-dlp, trying the primary player clients then the POT-backed fallback set
-    on a bot/DRM/format failure. Returns the info dict of the successful attempt."""
-    client_sets = [
-        c for c in (settings.player_client_list, settings.player_client_fallback_list) if c
-    ] or [None]
-    outtmpl = str(staging / "%(id)s.%(ext)s")
-    last_exc: Exception | None = None
-    for i, clients in enumerate(client_sets):
-        opts = formats.build_ydl_opts(
-            spec, outtmpl, _make_progress_hook(job_id, asset_id),
-            settings.download_pot_base_url, clients,
-        )
-        opts["postprocessor_hooks"] = [_make_pp_hook(job_id)]
-        try:
-            with yt_dlp.YoutubeDL(opts) as ydl:
-                return ydl.extract_info(url, download=True)
-        except yt_dlp.utils.DownloadError as exc:
-            last_exc = exc
-            retriable = any(m in str(exc) for m in _RETRIABLE_MARKERS)
-            if i < len(client_sets) - 1 and retriable:
-                log.info("job %s: clients %s failed (%s); retrying with fallback", job_id, clients, str(exc)[:70])
-                for p in list(staging.iterdir()):  # drop partials before the retry
-                    try:
-                        p.unlink()
-                    except OSError:
-                        pass
-                _set_job(job_id, progress=0, phase="downloading")
-                continue
-            raise
-    raise last_exc  # unreachable (loop either returns or raises)
-
-
-def _download_settings() -> tuple[str, int]:
-    """Layout + retention days from the DB config (admin-overridable on the Configuration page),
-    falling back to the env defaults. Read here, not from `settings`, so an admin edit takes effect."""
-    with SessionLocal() as db:
-        return (
-            sysconfig.get_str(db, "download_layout"),
-            sysconfig.get_int(db, "download_retention_days"),
-        )
-
-
-def _ensure_browser_playable(job_id: int, produced: Path, spec: dict, info: dict) -> Path:
-    """Make an mp4-compat-profile download play in every browser: H.264 + AAC/MP3 in mp4. If the
-    download (whatever the source shipped) isn't already that, re-encode the offending stream(s) —
-    or just remux when the codecs are fine but the container isn't. **Scope:** only the mp4 compat
-    profile is normalized; an explicit `vcodec` or a non-mp4 custom profile is the user opting out
-    of the guarantee and is left as-is (so a `webm` profile can still ship VP9/Opus). Returns the
-    file to store (converted, or the original) and corrects `info`'s codec fields to match disk."""
-    if spec.get("container") != "mp4" or spec.get("vcodec"):
-        return produced
-    vcodec, acodec = editmod.probe_codecs(produced)
-    is_mp4 = produced.suffix.lower() == ".mp4"
-    needs, reenc_v, reenc_a = editmod.browser_transcode_flags(vcodec, acodec, is_mp4)
-    if not needs:
-        return produced
-
-    dest = produced.with_name(produced.stem + ".browser.mp4")
-    action = "re-encode" if (reenc_v or reenc_a) else "remux"
-    log.info("job %s: %s (v=%s a=%s mp4=%s) -> browser-safe mp4", job_id, action, vcodec, acodec, is_mp4)
-    _set_job(job_id, phase="processing", progress=0, speed_bps=None, eta_s=None)
-    # Prefer the info duration; probe the file when the extractor didn't provide one, so a long
-    # re-encode still shows real progress instead of a frozen 0%.
-    total_s = int(info["duration"]) if info.get("duration") else editmod.probe_duration(produced)
-    editmod.run_ffmpeg(
-        editmod.build_browser_safe_cmd(produced, dest, reenc_v, reenc_a),
-        total_s=total_s,
-        on_progress=_ffmpeg_progress_writer(job_id, "processing"),
-        should_cancel=_cancel_poll(job_id),
-    )
-    produced.unlink(missing_ok=True)
-    # Keep the stored asset metadata truthful about what's now on disk.
-    if reenc_v:
-        info["vcodec"] = "h264"
-    if reenc_a:
-        info["acodec"] = "aac"
-    return dest
-
-
-def _download(job_id: int, asset_id: int, source_kind: str, source_ref: str, spec: dict) -> None:
-    staging = _staging_dir(asset_id)
-    try:
-        if staging.exists():
-            shutil.rmtree(staging, ignore_errors=True)
-        staging.mkdir(parents=True, exist_ok=True)
-
-        _set_job(job_id, phase="downloading", progress=0)
-        url = service.source_url(source_kind, source_ref)
-        info = _media_info(_extract_with_fallback(job_id, asset_id, url, spec, staging))
-
-        produced = _produced_file(info, staging)
-        produced = _ensure_browser_playable(job_id, produced, spec, info)
-        ext = produced.suffix.lstrip(".").lower()
-        meta = storage.MediaMeta(
-            video_id=info.get("id") or source_ref,
-            title=normalize_title(info.get("title")) or source_ref,
-            uploader=info.get("uploader") or info.get("channel") or "Unknown Channel",
-            upload_date=_parse_upload_date(info.get("upload_date")),
-            duration_s=int(info["duration"]) if info.get("duration") else None,
-            description=info.get("description"),
-            thumbnail_url=info.get("thumbnail"),
-        )
-
-        layout, retention_days = _download_settings()
-        rel = storage.rel_path(meta, ext, layout, asset_id=asset_id)
-        thumb = _find_thumbnail(staging, produced)
-        storage.place_file(produced, settings.download_root, rel)
-        nfo_ok = storage.write_sidecars(settings.download_root, rel, meta, thumb)
-
-        final = storage.abs_path(settings.download_root, rel)
-        size = final.stat().st_size if final.exists() else None
-        expires = datetime.now(timezone.utc) + timedelta(days=retention_days)
-
-        with SessionLocal() as db:
-            asset = db.get(MediaAsset, asset_id)
-            if asset:
-                asset.status = "ready"
-                asset.rel_path = rel
-                asset.size_bytes = size
-                asset.duration_s = meta.duration_s
-                asset.width = int(info["width"]) if info.get("width") else None
-                asset.height = int(info["height"]) if info.get("height") else None
-                asset.container = ext
-                asset.vcodec = info.get("vcodec") if info.get("vcodec") not in (None, "none") else None
-                asset.acodec = info.get("acodec") if info.get("acodec") not in (None, "none") else None
-                asset.title = meta.title
-                asset.uploader = meta.uploader
-                asset.uploader_url = _uploader_url(info)
-                asset.upload_date = meta.upload_date
-                asset.thumbnail_url = meta.thumbnail_url
-                # Record a self-hosted poster for every download: it's the reliable link-preview
-                # (og:image) source — a remote thumbnail, esp. Facebook's signed CDN URL, expires
-                # and can't be relied on cross-origin. write_sidecars already wrote <base>.jpg from
-                # the thumbnail; ensure_poster returns that, or cuts a frame if there was none.
-                asset.poster_path = editmod.ensure_poster(asset, settings.download_root)
-                asset.source_webpage_url = info.get("webpage_url")
-                asset.nfo_written = nfo_ok
-                asset.error = None
-                asset.last_access_at = datetime.now(timezone.utc)
-                asset.expires_at = expires
-            job = db.get(DownloadJob, job_id)
-            if job:
-                job.status = "done"
-                job.progress = 100
-                job.phase = None
-                job.speed_bps = None
-                job.eta_s = None
-                if not job.display_name:
-                    # display_name is VARCHAR(255) — clip a long title (see _fill_asset_meta_early).
-                    job.display_name = meta.title[:255] if meta.title else None
-            db.commit()
-        log.info("job %s done: %s", job_id, rel)
-
-    except (_Aborted, editmod.EditAborted):
-        # Paused/canceled mid-download or mid-transcode: free the asset for a later retry; keep the
-        # job's status (the route set it to paused/canceled). ref_count is adjusted by the route.
-        _reset_asset_pending(asset_id)
-        log.info("job %s aborted (pause/cancel)", job_id)
-    except Exception as exc:  # noqa: BLE001 — surface any failure to the user, keep worker alive
-        msg = str(exc)[:500]
-        with SessionLocal() as db:
-            asset = db.get(MediaAsset, asset_id)
-            if asset:
-                asset.status = "error"
-                asset.error = msg
-            job = db.get(DownloadJob, job_id)
-            if job:
-                job.status = "error"
-                job.error = msg
-                job.error_code = dlerrors.classify(msg)
-                job.phase = None
-            db.commit()
-        log.warning("job %s failed: %s", job_id, msg)
-    finally:
-        shutil.rmtree(staging, ignore_errors=True)
-
-
-def _reset_asset_pending(asset_id: int) -> None:
-    with SessionLocal() as db:
-        asset = db.get(MediaAsset, asset_id)
-        if asset and asset.status == "downloading":
-            asset.status = "pending"
-            db.commit()
-
-
-# --- editor derivatives (phase 2: trim/crop via ffmpeg) -------------------------------------
-
-def _edit_staging_dir(asset_id: int) -> Path:
-    return Path(settings.download_root) / ".staging" / f"edit-{asset_id}"
-
-
-def _fail_edit(job_id: int, asset_id: int, msg: str) -> None:
-    with SessionLocal() as db:
-        asset = db.get(MediaAsset, asset_id)
-        if asset:
-            asset.status = "error"
-            asset.error = msg
-        job = db.get(DownloadJob, job_id)
-        if job:
-            job.status = "error"
-            job.error = msg
-            job.error_code = dlerrors.classify(msg)
-            job.phase = None
-        db.commit()
-    log.warning("edit job %s failed: %s", job_id, msg)
-
-
-def _process_edit(job_id: int, asset_id: int) -> None:
-    """Produce a per-user trim/crop clip from the source asset's downloaded file via ffmpeg."""
-    with SessionLocal() as db:
-        job = db.get(DownloadJob, job_id)
-        src = db.get(MediaAsset, job.source_asset_id) if job and job.source_asset_id else None
-        edit_spec = dict(job.edit_spec or {}) if job else {}
-        user_id = job.user_id if job else None
-        src_ready = src is not None and src.status == "ready" and bool(src.rel_path)
-        src_rel = src.rel_path if src else None
-        src_w, src_h, src_dur = (src.width, src.height, src.duration_s) if src else (None, None, None)
-
-    if not src_ready or not src_rel:
-        _fail_edit(job_id, asset_id, "The source download is no longer available.")
-        return
-    src_path = storage.abs_path(settings.download_root, src_rel)
-    if not src_path.exists():
-        _fail_edit(job_id, asset_id, "The source file is missing.")
-        return
-
-    src_ext = src_path.suffix.lstrip(".").lower() or "mp4"
-    crop = editmod.has_crop(edit_spec)
-    out_ext = "mp4" if editmod.needs_reencode(edit_spec) else src_ext
-    total_s = editmod.clip_duration(edit_spec, src_dur) or src_dur or 0
-    staging = _edit_staging_dir(asset_id)
-
-    try:
-        if staging.exists():
-            shutil.rmtree(staging, ignore_errors=True)
-        staging.mkdir(parents=True, exist_ok=True)
-        dest_staging = staging / f"out.{out_ext}"
-
-        _set_job(job_id, phase="editing", progress=0, speed_bps=None, eta_s=None)
-        if edit_spec.get("segments"):
-            cmd, prep = editmod.build_concat_plan(src_path, dest_staging, edit_spec, out_ext, staging)
-            for p, content in prep.items():
-                p.write_text(content, encoding="utf-8")
-        else:
-            cmd = editmod.build_edit_cmd(src_path, dest_staging, edit_spec, out_ext)
-        editmod.run_ffmpeg(
-            cmd,
-            total_s,
-            on_progress=_ffmpeg_progress_writer(job_id, "editing"),
-            should_cancel=_cancel_poll(job_id),
-        )
-        if not dest_staging.exists():
-            raise RuntimeError("ffmpeg produced no output file")
-
-        rel = storage.edit_rel_path(user_id, asset_id, out_ext)
-        storage.place_file(dest_staging, settings.download_root, rel)
-        final = storage.abs_path(settings.download_root, rel)
-        size = final.stat().st_size if final.exists() else None
-        _, retention_days = _download_settings()
-        expires = datetime.now(timezone.utc) + timedelta(days=retention_days)
-
-        with SessionLocal() as db:
-            asset = db.get(MediaAsset, asset_id)
-            if asset:
-                asset.status = "ready"
-                asset.rel_path = rel
-                asset.size_bytes = size
-                asset.container = out_ext
-                asset.duration_s = total_s or asset.duration_s
-                if crop:
-                    asset.width = edit_spec["crop"]["w"]
-                    asset.height = edit_spec["crop"]["h"]
-                else:
-                    asset.width, asset.height = src_w, src_h
-                asset.error = None
-                asset.last_access_at = datetime.now(timezone.utc)
-                asset.expires_at = expires
-            job = db.get(DownloadJob, job_id)
-            if job:
-                job.status = "done"
-                job.progress = 100
-                job.phase = None
-            db.commit()
-        log.info("edit job %s done: %s", job_id, rel)
-
-    except editmod.EditAborted:
-        # Paused/canceled mid-encode: free the asset for a later retry (ref_count is the route's job).
-        _reset_asset_pending(asset_id)
-        log.info("edit job %s aborted (pause/cancel)", job_id)
-    except Exception as exc:  # noqa: BLE001 — surface the failure, keep the worker alive
-        _fail_edit(job_id, asset_id, str(exc)[:500])
-    finally:
-        shutil.rmtree(staging, ignore_errors=True)
-
-
 # --- loop -----------------------------------------------------------------------------------
 
 def _worker_loop(idx: int) -> None:

backend/app/youtube/client.py

@@ -79,7 +79,12 @@ class YouTubeClient:
         cached = decrypt_optional(tok.access_token)
         if cached and tok.expiry and tok.expiry > now + timedelta(seconds=60):
             return cached
-        refresh = decrypt(tok.refresh_token_enc)
+        try:
+            refresh = decrypt(tok.refresh_token_enc)
+        except Exception as exc:  # noqa: BLE001 — Fernet InvalidToken (TOKEN_ENCRYPTION_KEY changed)
+            # A key mismatch must degrade like any other token problem (caller handles YouTubeError),
+            # not surface as a raw 500 on every scheduler job / connect check. (B-core-2)
+            raise YouTubeError("Stored OAuth token is unreadable — reconnect your account") from exc
         if not refresh:
             raise YouTubeError("No refresh token; user must re-authenticate")
         resp = self._send(

backend/docker-compose.test.yml

@@ -29,6 +29,9 @@ services:
         condition: service_healthy
     environment:
       DATABASE_URL: postgresql+psycopg://siftlode:siftlode@testdb:5432/siftlode_test
+      # This lane HAS a Postgres + ffmpeg, so the DB/ffmpeg tests must actually run here: conftest turns
+      # a would-be silent skip into a hard failure (SIFTLODE_TEST_REQUIRE_DB).
+      SIFTLODE_TEST_REQUIRE_DB: "1"
     volumes:
       - ./:/app
     working_dir: /app

backend/pytest.ini

@@ -1,6 +1,8 @@
 [pytest]
 # Run from backend/ (the image's /app). `pythonpath = .` puts the app package on sys.path so tests
-# import it as `app.*`, matching runtime. The suite is pure-logic only (no DB/network) — see tests/.
+# import it as `app.*`, matching runtime. Most of the suite is pure-logic; the DB-backed lane opts in
+# via the `db` fixture and runs in the compose test image. `-rs` reports skip REASONS so a silently
+# skipped lane is visible (the compose lane sets SIFTLODE_TEST_REQUIRE_DB=1 to make skips a hard error).
 testpaths = tests
 pythonpath = .
-addopts = -q
+addopts = -q -rs

backend/requirements.lock

@@ -0,0 +1,57 @@
+# Pinned dependency lock for reproducible builds (SEC-5). GENERATED — do not hand-edit.
+# Source of truth is requirements.txt (the floor ranges); regenerate after editing it with:
+#   docker run --rm -v "$PWD":/b python:3.12-slim sh -c 'pip install -q -r /b/requirements.txt && pip freeze --exclude pip --exclude setuptools --exclude wheel' | sort
+# The prod Dockerfile + Dockerfile.test + CI install THIS file; pip-audit scans it in CI.
+APScheduler==3.11.3
+Authlib==1.7.2
+Mako==1.4.1
+MarkupSafe==3.0.3
+PyYAML==6.0.3
+SQLAlchemy==2.0.52
+alembic==1.19.1
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.14.2
+argon2-cffi-bindings==25.1.0
+argon2-cffi==25.1.0
+bgutil-ytdlp-pot-provider==1.3.1
+brotli==1.2.0
+certifi==2026.7.22
+cffi==2.1.1
+charset-normalizer==3.5.1
+click==8.4.2
+cryptography==50.0.0
+fastapi==0.141.1
+feedparser-sgmllib==2.1.0
+feedparser==6.0.14
+greenlet==3.5.5
+h11==0.16.0
+httpcore==1.0.9
+httptools==0.8.0
+httpx==0.28.1
+idna==3.18
+itsdangerous==2.2.0
+joserfc==1.7.4
+mutagen==1.48.1
+numpy==2.5.2
+psycopg-binary==3.3.4
+psycopg==3.3.4
+py3langid==0.3.0
+pycparser==3.0
+pycryptodomex==3.23.0
+pydantic-settings==2.15.0
+pydantic==2.13.4
+pydantic_core==2.46.4
+python-dotenv==1.2.3
+requests==2.34.2
+starlette==1.6.0
+typing-inspection==0.4.4
+typing_extensions==4.16.0
+tzlocal==5.4.4
+urllib3==2.7.0
+uvicorn==0.52.3
+uvloop==0.22.1
+watchfiles==1.2.0
+websockets==17.0.1
+yt-dlp-ejs==0.8.0
+yt-dlp==2026.7.4

backend/requirements.txt

@@ -11,7 +11,7 @@ feedparser>=6.0,<7.0
 apscheduler>=3.10,<4.0
 py3langid>=0.3,<1.0
 itsdangerous>=2.1,<3.0
-cryptography>=46.0.7,<47
+cryptography>=50.0.0,<51
 argon2-cffi>=23.1,<26
 # Download center: yt-dlp does the extraction/download; ffmpeg (OS-level in the Dockerfile)
 # does the merge + postprocessing. The [default] extra pulls yt-dlp-ejs (the challenge-solver

backend/tests/conftest.py

@@ -12,14 +12,31 @@ config the videos.search_vector generated column needs). Building it via migrati
 that the migration chain applies cleanly. Each test then gets a clean database via TRUNCATE so
 tests that COMMIT (the whole point of this lane — transaction-ownership behaviour) don't leak.
 """
+import os
+import shutil
+
 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
 
 import app.models  # noqa: F401 — register every model on Base.metadata
+import app.state as app_state
+from app import security
+from app.auth import current_user
 from app.config import settings
-from app.db import Base, SessionLocal, engine
+from app.db import Base, SessionLocal, engine, get_db
+from app.main import app
+from app.models import User
+
+# Sentinel for "this dependency had no override before the fixture set one" (see override_dep).
+_MISSING = object()
+
+# The compose test lane sets this so a would-be silent skip (no DB, or no ffmpeg) becomes a hard error
+# — the gate must not print green while the DB-backed / ffmpeg tests were quietly not run.
+_REQUIRE_FULL = os.getenv("SIFTLODE_TEST_REQUIRE_DB") == "1"
 
 
 def _db_reachable() -> bool:
@@ -59,6 +76,23 @@ def _truncate_all():
         conn.execute(text(f"TRUNCATE {tables} RESTART IDENTITY CASCADE"))
 
 
+def pytest_configure(config):
+    """Fail the whole run — loudly, once — when SIFTLODE_TEST_REQUIRE_DB=1 but the environment can't
+    actually run the full suite. Without this, an unreachable DATABASE_URL or a missing ffmpeg turns
+    ~60 DB tests + the poster tests into silent skips and the gate still exits green."""
+    if not _REQUIRE_FULL:
+        return
+    if not _DB_REACHABLE:
+        raise pytest.UsageError(
+            "SIFTLODE_TEST_REQUIRE_DB=1 but no Postgres is reachable at the test DATABASE_URL — the "
+            "DB-backed lane would silently skip. Fix the DB wiring or unset the flag."
+        )
+    if shutil.which("ffmpeg") is None:
+        raise pytest.UsageError(
+            "SIFTLODE_TEST_REQUIRE_DB=1 but ffmpeg is missing — the thumbnail/poster tests would skip."
+        )
+
+
 @pytest.fixture
 def db(_schema):
     """A real session against the test Postgres, on a clean (empty) database. The code under test
@@ -70,3 +104,87 @@ def db(_schema):
     finally:
         session.rollback()
         session.close()
+
+
+@pytest.fixture
+def make_user(db):
+    """Factory: create + commit a User in the test DB. Defaults produce a login-ready account (email
+    verified, active, with a known password); override any of it via kwargs (e.g. `role="admin"`,
+    `is_suspended=True`, `password=None` for a Google-only account). Returns the User."""
+    seq = {"n": 0}
+
+    def _make(email: str | None = None, *, password: str | None = "correct horse battery", **kw):
+        seq["n"] += 1
+        kw.setdefault("email_verified", True)
+        user = User(
+            email=email or f"user{seq['n']}@example.com",
+            password_hash=security.hash_password(password) if password else None,
+            **kw,
+        )
+        db.add(user)
+        db.commit()
+        return user
+
+    return _make
+
+
+@pytest.fixture
+def override_dep():
+    """Set app.dependency_overrides for the duration of a test and restore the PRIOR value per key on
+    teardown — instead of a blanket `app.dependency_overrides.clear()`, which wipes every override and
+    stops fixtures composing (one fixture's teardown clobbering another's)."""
+    saved: dict = {}
+
+    def _set(dep, override):
+        if dep not in saved:  # remember the pre-fixture value the FIRST time we touch this key
+            saved[dep] = app.dependency_overrides.get(dep, _MISSING)
+        app.dependency_overrides[dep] = override
+
+    yield _set
+    for dep, prev in saved.items():
+        if prev is _MISSING:
+            app.dependency_overrides.pop(dep, None)
+        else:
+            app.dependency_overrides[dep] = prev
+
+
+@pytest.fixture
+def _configured(monkeypatch):
+    """The setup gate 503s /auth and /api until the wizard has run; the request-issuing fixtures below
+    are all post-setup. Baked into client/as_user so no individual test has to remember it."""
+    monkeypatch.setattr(app_state, "_configured_cache", True)
+
+
+@pytest.fixture
+def client(db, override_dep, _configured):
+    """A TestClient wired to the test DB that goes through the REAL auth/session stack — no
+    `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)
+    return TestClient(app)
+
+
+@pytest.fixture
+def as_user(db, override_dep, _configured):
+    """Factory -> a TestClient authenticated as a given User (bypassing login), for tests that need an
+    authed request but aren't exercising the login flow itself. Multiple users in ONE test are isolated:
+    the shared `current_user` override resolves the caller from an `x-test-user` header, and each
+    returned client tags its own requests with it — so `as_user(a)` and `as_user(b)` don't collide on
+    the process-global override the way a plain `lambda: user` would."""
+    registry: dict[int, User] = {}
+
+    def _resolver(request: Request) -> User:
+        raw = request.headers.get("x-test-user")
+        if raw is None or (uid := int(raw)) not in registry:
+            raise HTTPException(status_code=401, detail="Not authenticated")
+        return registry[uid]
+
+    override_dep(get_db, lambda: db)
+    override_dep(current_user, _resolver)
+
+    def _as(user: User) -> TestClient:
+        registry[user.id] = user
+        return TestClient(app, headers={"x-test-user": str(user.id)})
+
+    return _as

backend/tests/test_adapters.py

@@ -0,0 +1,115 @@
+"""Per-source adapter selection + the source-specific policy each one carries. These lock the
+behaviour that used to live inline in worker.build_uploader_url / backfill._should_refetch."""
+from app.downloads.adapters import (
+    FacebookAdapter,
+    RedditAdapter,
+    SourceAdapter,
+    YouTubeAdapter,
+    resolve_adapter,
+)
+
+
+def test_resolve_by_source_kind_and_host_and_info():
+    assert resolve_adapter("youtube", "abc123").key == "youtube"
+    assert resolve_adapter("url", "https://www.youtube.com/watch?v=x").key == "youtube"
+    assert resolve_adapter("url", "https://youtu.be/x").key == "youtube"
+    assert resolve_adapter("url", "https://www.facebook.com/reel/123/").key == "facebook"
+    assert resolve_adapter("url", "https://fb.watch/abc/").key == "facebook"
+    assert resolve_adapter("url", "https://www.reddit.com/r/x/comments/y/z").key == "reddit"
+    assert resolve_adapter("url", "https://example.com/video.mp4").key == "generic"
+    # After extraction the info dict's extractor decides even for a bare/redirected url.
+    assert resolve_adapter("url", None, {"extractor_key": "facebook"}).key == "facebook"
+    assert resolve_adapter("url", None, {"extractor_key": "Reddit"}).key == "reddit"
+
+
+def test_host_match_is_netloc_not_a_loose_substring():
+    # A path that merely CONTAINS "facebook.com" must not select the Facebook adapter.
+    assert resolve_adapter("url", "https://example.com/facebook.com-mirror").key == "generic"
+
+
+def test_info_match_is_extractor_key_not_the_webpage_url():
+    # The webpage_url path may carry a SIBLING source's name (a reddit slug about youtube); only the
+    # yt-dlp extractor_key identifies the source, so this must resolve reddit, not youtube.
+    info = {"extractor_key": "Reddit", "webpage_url": "https://reddit.com/r/x/comments/y/youtube_is_dead"}
+    assert resolve_adapter("url", None, info).key == "reddit"
+
+
+def test_youtube_nocookie_host_still_gets_the_youtube_adapter():
+    # An embed on youtube-nocookie.com is YouTube content and needs the POT/player-client strategy,
+    # even though its host does not contain the substring "youtube.com".
+    assert resolve_adapter("url", "https://www.youtube-nocookie.com/embed/abc123").key == "youtube"
+
+
+def test_lookalike_hosts_do_not_misresolve_but_subdomains_do():
+    # Netloc-scoped match: a look-alike host that merely CONTAINS the domain string is NOT the source.
+    assert resolve_adapter("url", "https://myyoutube.com/watch?v=x").key == "generic"
+    assert resolve_adapter("url", "https://youtube.com.evil.example/x").key == "generic"
+    assert resolve_adapter("url", "https://notreddit.com/r/x").key == "generic"
+    # …but real subdomains still resolve.
+    assert resolve_adapter("url", "https://m.youtube.com/watch?v=x").key == "youtube"
+    assert resolve_adapter("url", "https://music.youtube.com/watch?v=x").key == "youtube"
+
+
+def test_webpage_url_netloc_identifies_source_when_extractor_key_absent():
+    # The early-fill path passes info with no source_ref; the webpage_url netloc still resolves the
+    # source even if extractor_key is missing from the progress-hook info_dict.
+    assert resolve_adapter(None, None, {"webpage_url": "https://www.facebook.com/reel/123"}).key == "facebook"
+    # A sibling source's name in the webpage_url PATH must not misresolve (host, not substring).
+    info = {"extractor_key": "Reddit", "webpage_url": "https://www.reddit.com/r/x/comments/y/youtube"}
+    assert resolve_adapter(None, None, info).key == "reddit"
+
+
+def test_uploader_url_youtube_uses_channel_url():
+    a = YouTubeAdapter()
+    assert a.uploader_url({"channel_url": "https://youtube.com/@chan"}) == "https://youtube.com/@chan"
+    assert a.uploader_url({"uploader_url": "https://youtube.com/user/u"}) == "https://youtube.com/user/u"
+    assert a.uploader_url({}) is None
+
+
+def test_uploader_url_facebook_falls_back_to_uploader_id():
+    a = FacebookAdapter()
+    assert a.uploader_url({"uploader_id": "12345"}) == "https://www.facebook.com/12345"
+    # A direct channel_url still wins over the id fallback.
+    assert a.uploader_url({"channel_url": "https://facebook.com/pageX", "uploader_id": "9"}) == (
+        "https://facebook.com/pageX"
+    )
+    assert a.uploader_url({}) is None
+
+
+def test_uploader_url_reddit_and_generic_have_no_channel():
+    assert RedditAdapter().uploader_url({"uploader_id": "99"}) is None  # not facebook → no fallback
+    assert SourceAdapter().uploader_url({}) is None
+
+
+def test_generic_source_url_is_passthrough_youtube_reconstructs():
+    assert SourceAdapter().source_url("https://x/y") == "https://x/y"
+    assert YouTubeAdapter().source_url("VIDID12345_") == "https://www.youtube.com/watch?v=VIDID12345_"
+
+
+def test_client_sets_and_retriable_are_youtube_only():
+    # Generic sources make a single attempt and never retry on the YouTube per-client markers.
+    assert SourceAdapter().client_sets() == [None]
+    assert SourceAdapter().retriable("Sign in to confirm you're not a bot") is False
+    assert YouTubeAdapter().retriable("Sign in to confirm you're not a bot") is True
+    assert YouTubeAdapter().retriable("some unrelated network blip") is False
+
+
+def test_youtube_ydl_opts_extra_carries_player_client_and_pot():
+    ea = YouTubeAdapter().ydl_opts_extra(["android_vr"])["extractor_args"]
+    assert ea["youtube"]["player_client"] == ["android_vr"]
+    assert "youtubepot-bgutilhttp" in ea  # the bgutil PO-token base_url is wired
+    # A client-less attempt still wires POT but no player_client key.
+    assert "youtube" not in YouTubeAdapter().ydl_opts_extra(None)["extractor_args"]
+    assert SourceAdapter().ydl_opts_extra(["android_vr"]) == {}  # generic contributes nothing
+
+
+def test_wants_metadata_backfill_matches_old_should_refetch():
+    assert YouTubeAdapter().wants_metadata_backfill() is True
+    assert FacebookAdapter().wants_metadata_backfill() is True
+    assert RedditAdapter().wants_metadata_backfill() is False
+    assert SourceAdapter().wants_metadata_backfill() is False
+
+
+def test_nfo_uniqueid_type_is_the_adapter_key():
+    assert YouTubeAdapter().nfo_uniqueid_type() == "youtube"
+    assert SourceAdapter().nfo_uniqueid_type() == "generic"

backend/tests/test_auth_session.py

@@ -0,0 +1,121 @@
+"""Auth / session security core (TEST-1), DB-lane.
+
+The wallet impersonation gate, epoch-based session revocation, single-use tokens and the
+enumeration-safe uniform 401 are the security mag, and had zero tests (only `_oauth_redirect_uri` was
+covered). Starlette's SessionMiddleware round-trips the signed cookie under TestClient, so the whole
+browser-less flow is exercisable. Uses the real auth stack via the `client` fixture (NO current_user
+override) so login, the wallet gate and epoch revoke are the code under test.
+
+Note: `/api/me` is the bootstrap probe — it returns 200 `{authenticated: False}` when logged out, not a
+401. A revoked session is therefore checked on a PROTECTED endpoint (`/api/feed`), which does 401.
+"""
+from datetime import timedelta
+
+from fastapi.testclient import TestClient
+
+from app.auth import ACTIVE_ACCOUNT_HEADER
+from app.main import app
+
+_PW = "correct horse battery"
+
+# The `client`/`as_user` fixtures bake in the post-setup `_configured` state, so no per-test patch here.
+
+
+def _login(client, email, password):
+    return client.post("/auth/password-login", json={"email": email, "password": password})
+
+
+def test_password_login_then_me_is_authenticated(client, make_user):
+    make_user(email="alice@example.com", password=_PW)
+    assert _login(client, "alice@example.com", _PW).status_code == 200
+    me = client.get("/api/me")
+    assert me.status_code == 200
+    assert me.json()["authenticated"] is True
+    assert me.json()["email"] == "alice@example.com"
+
+
+def test_wrong_password_and_unknown_email_give_a_byte_identical_401(client, make_user):
+    make_user(email="bob@example.com", password=_PW)
+    wrong_pw = _login(client, "bob@example.com", "not the password")
+    unknown = _login(client, "nobody@example.com", _PW)
+    assert wrong_pw.status_code == 401 and unknown.status_code == 401
+    # Identical body: a wrong password and a non-existent account must be indistinguishable (no
+    # account-enumeration oracle).
+    assert wrong_pw.json() == unknown.json()
+
+
+def test_a_non_wallet_account_header_falls_back_to_the_default(client, make_user):
+    # The X-Siftlode-Account header may only re-target an account already signed into THIS browser
+    # (in the session wallet). A header naming someone else must be ignored, not honored — otherwise
+    # it's an impersonation gate hole.
+    make_user(email="alice2@example.com", password=_PW)
+    mallory = make_user(email="mallory@example.com", password=_PW)
+    assert _login(client, "alice2@example.com", _PW).status_code == 200
+    me = client.get("/api/me", headers={ACTIVE_ACCOUNT_HEADER: str(mallory.id)})
+    assert me.status_code == 200
+    assert me.json()["email"] == "alice2@example.com"  # still Alice, not Mallory
+
+
+def test_logout_others_revokes_the_other_session_but_keeps_the_caller(client, make_user):
+    # Two independent cookie jars (browsers) signed into the same account. `logout-others` from one
+    # bumps the account epoch so the OTHER's cookie is rejected on its next request, while the caller
+    # is re-stamped and stays in. Checked on /api/feed (a protected endpoint that 401s on revocation).
+    make_user(email="carol@example.com", password=_PW)
+    # A second, independent cookie jar; the `client` fixture already routed get_db to the test DB on
+    # the shared app, so this instance uses it too — it just has its own session cookie.
+    other = TestClient(app)
+    assert _login(client, "carol@example.com", _PW).status_code == 200
+    assert _login(other, "carol@example.com", _PW).status_code == 200
+    assert other.get("/api/feed").status_code == 200  # both valid to start
+
+    assert client.post("/auth/logout-others").status_code == 200
+    assert other.get("/api/feed").status_code == 401  # its epoch is now stale
+    assert client.get("/api/feed").status_code == 200  # the caller stays signed in
+
+
+def test_reset_confirm_is_single_use_and_kills_existing_sessions(client, make_user, db):
+    from app.routes.auth import _issue_token
+
+    user = make_user(email="dave@example.com", password=_PW)
+    assert _login(client, "dave@example.com", _PW).status_code == 200
+    assert client.get("/api/feed").status_code == 200  # session valid at the pre-reset epoch
+
+    raw = _issue_token(db, user, "reset", timedelta(hours=1))
+    db.commit()
+    ok = client.post("/auth/password-reset/confirm", json={"token": raw, "password": "brand new pw!"})
+    assert ok.status_code == 200
+
+    # A reset bumps the epoch (compromise response) -> the pre-reset cookie is now rejected.
+    assert client.get("/api/feed").status_code == 401
+    # The token is single-use: a replay is a clean 400, not a second reset.
+    replay = client.post("/auth/password-reset/confirm", json={"token": raw, "password": "another pw!!"})
+    assert replay.status_code == 400
+
+
+def test_activating_an_unverified_account_drops_its_preset_password(db, make_user):
+    # SEC-10 (account pre-emption): an attacker registers victim@x with a password before the approved
+    # owner arrives. The address was never verified, so admin approval must NOT hand that pre-set
+    # password a working login — it is dropped and any session it minted is revoked.
+    from app.routes.admin import _activate_user_by_email
+
+    victim = make_user(
+        email="victim@example.com", password="attacker-chosen", email_verified=False, is_active=False
+    )
+    epoch0 = victim.session_epoch or 0
+    _activate_user_by_email(db, "victim@example.com")
+    assert victim.is_active is True
+    assert victim.password_hash is None
+    assert (victim.session_epoch or 0) == epoch0 + 1
+
+
+def test_activating_a_verified_account_keeps_its_password(db, make_user):
+    # A legit account whose email IS verified (e.g. a no-SMTP registration) keeps its password on
+    # approval — the guard must not break the normal flow.
+    from app.routes.admin import _activate_user_by_email
+
+    user = make_user(
+        email="legit@example.com", password="my own password", email_verified=True, is_active=False
+    )
+    _activate_user_by_email(db, "legit@example.com")
+    assert user.is_active is True
+    assert user.password_hash is not None

backend/tests/test_channel_backfill.py

@@ -0,0 +1,318 @@
+"""R14 backend coverage: the channel-detail Normal/Shorts/Live counts (moved off the manager table),
+the update_channel -> immediate-backfill wiring (incl. the demo guard), and the interactive
+"get full history" guard that keeps it from racing the scheduler's cursor or draining the budget."""
+from datetime import datetime, timezone
+
+import pytest
+from fastapi.testclient import TestClient
+
+import app.routes.channels as channels_route
+import app.state as state
+from app.auth import current_user
+from app.db import get_db
+from app.main import app
+from app.models import Channel, Subscription, User, Video
+from app.sync import runner, videos
+
+_PUB = datetime(2020, 1, 1, tzinfo=timezone.utc)
+
+
+def test_channel_detail_returns_normal_shorts_live_counts(db, monkeypatch):
+    # published_at set so channel_detail skips the YouTube-enrich path (no quota / network in tests).
+    ch = Channel(id="UC_nsl", title="N/S/L Channel", published_at=_PUB)
+    db.add(ch)
+    me = User(email="nsl@example.com")
+    db.add(me)
+    db.flush()
+    # DISTINCT counts (2 shorts, 1 live) so a short<->live filter/field swap can't pass:
+    # stored 5, short 2, live 1, normal = 5 - 2 - 1 = 2.
+    db.add_all(
+        [
+            Video(id="v_norm1", channel_id=ch.id),
+            Video(id="v_norm2", channel_id=ch.id),
+            Video(id="v_short1", channel_id=ch.id, is_short=True),
+            Video(id="v_short2", channel_id=ch.id, is_short=True),
+            Video(id="v_live1", channel_id=ch.id, live_status="live"),
+        ]
+    )
+    db.commit()
+
+    # The request gate 503s an unconfigured instance; flip the process-level flag (auto-restored).
+    monkeypatch.setattr(state, "_configured_cache", True)
+    app.dependency_overrides[get_db] = lambda: db
+    app.dependency_overrides[current_user] = lambda: me
+    try:
+        resp = TestClient(app).get(f"/api/channels/{ch.id}")
+    finally:
+        app.dependency_overrides.clear()
+
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["stored_videos"] == 5
+    assert body["count_short"] == 2
+    assert body["count_live"] == 1
+    assert body["count_normal"] == 2
+
+
+def _setup_channel_and_sub(db, *, email, is_demo=False):
+    ch = Channel(
+        id="UC_wire",
+        title="Wire",
+        published_at=_PUB,
+        recent_synced_at=_PUB,  # so update_channel skips the in-request recent backfill (no network)
+        uploads_playlist_id="UU_wire",
+    )
+    db.add(ch)
+    user = User(email=email, is_demo=is_demo)
+    db.add(user)
+    db.flush()
+    db.add(Subscription(user_id=user.id, channel_id=ch.id, deep_requested=False))
+    db.commit()
+    return ch, user
+
+
+def _patch_deep_requested(db, monkeypatch, user):
+    calls: list[tuple] = []
+    # background.add_task runs after the response in TestClient; record what would be scheduled.
+    monkeypatch.setattr(channels_route, "backfill_channel_now", lambda *a, **k: calls.append(a))
+    monkeypatch.setattr(state, "_configured_cache", True)
+    app.dependency_overrides[get_db] = lambda: db
+    app.dependency_overrides[current_user] = lambda: user
+    try:
+        resp = TestClient(app).patch("/api/channels/UC_wire", json={"deep_requested": True})
+    finally:
+        app.dependency_overrides.clear()
+    return resp, calls
+
+
+def test_deep_request_schedules_immediate_backfill_for_non_demo(db, monkeypatch):
+    ch, me = _setup_channel_and_sub(db, email="wire@example.com")
+    resp, calls = _patch_deep_requested(db, monkeypatch, me)
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["deep_requested"] is True
+    # scheduled exactly once, with (channel_id, user_id) — the args backfill_channel_now needs.
+    assert calls == [(ch.id, me.id)]
+
+
+def test_deep_request_does_not_schedule_immediate_backfill_for_demo(db, monkeypatch):
+    # The SHARED demo account must not be able to kick immediate full backfills (budget drain).
+    _ch, demo = _setup_channel_and_sub(db, email="demo@example.com", is_demo=True)
+    resp, calls = _patch_deep_requested(db, monkeypatch, demo)
+    assert resp.status_code == 200, resp.text
+    assert calls == [], "demo must not schedule an immediate backfill"
+    # …and deep_requested is not persisted on the shared demo subscription either.
+    assert resp.json()["deep_requested"] is False
+
+
+class TestImmediateBackfillGuard:
+    """backfill_channel_now coordinates with the paced scheduler through _backfill_in_progress (per-
+    channel mutual exclusion, both directions) + _immediate_running (a cap on interactive runs so a
+    burst can't drain the shared budget)."""
+
+    def setup_method(self):
+        runner._backfill_in_progress.clear()
+        runner._immediate_running = 0
+
+    def teardown_method(self):
+        runner._backfill_in_progress.clear()
+        runner._immediate_running = 0
+
+    @staticmethod
+    def _boom_session():
+        # Reached only AFTER the guard admits the channel; if the guard short-circuits (as it must
+        # in these tests) this never runs, so raising proves the short-circuit.
+        raise AssertionError("guard must short-circuit before opening a session")
+
+    def test_a_second_call_for_an_in_flight_channel_is_a_noop(self, monkeypatch):
+        runner._backfill_in_progress.add("UC_busy")
+        monkeypatch.setattr(runner, "SessionLocal", self._boom_session)
+        runner.backfill_channel_now("UC_busy", 1)  # returns immediately; _boom_session never runs
+        assert runner._backfill_in_progress == {"UC_busy"}  # the in-flight entry is untouched
+
+    def test_over_the_concurrency_cap_falls_back_to_the_scheduler(self, monkeypatch):
+        runner._immediate_running = runner._MAX_CONCURRENT_IMMEDIATE
+        monkeypatch.setattr(runner, "SessionLocal", self._boom_session)
+        runner.backfill_channel_now("UC_new", 1)  # over the cap → no-op, scheduler will handle it
+        assert "UC_new" not in runner._backfill_in_progress
+
+    def test_scheduler_deep_pass_skips_an_in_flight_channel(self, db, monkeypatch):
+        # A channel the scheduler's query WOULD pick (deep-requested, recent-synced, not done)…
+        ch = Channel(
+            id="UC_inflight",
+            title="In-flight",
+            recent_synced_at=_PUB,
+            uploads_playlist_id="UU_inflight",
+            backfill_done=False,
+        )
+        db.add(ch)
+        me = User(email="svc@example.com")
+        db.add(me)
+        db.flush()
+        db.add(Subscription(user_id=me.id, channel_id=ch.id, deep_requested=True))
+        db.commit()
+
+        paged: list[str] = []
+        monkeypatch.setattr(runner, "get_service_user", lambda _db: me)
+        monkeypatch.setattr(runner.quota, "remaining_today", lambda _db: 10_000)
+        monkeypatch.setattr(runner, "YouTubeClient", lambda *a, **k: _NullYt())
+        monkeypatch.setattr(
+            runner, "backfill_channel_deep", lambda _db, _yt, channel, _mp: paged.append(channel.id) or 0
+        )
+        monkeypatch.setattr(runner, "reconcile_full_history", lambda _db: 0)
+
+        # …is skipped by run_deep_backfill while an interactive backfill owns it (no cursor race).
+        runner._backfill_in_progress.add(ch.id)
+        runner.run_deep_backfill(db)
+        assert paged == [], "the scheduler must not page a channel an immediate backfill is handling"
+
+        # …and IS paged once the interactive backfill releases it.
+        runner._backfill_in_progress.discard(ch.id)
+        runner.run_deep_backfill(db)
+        assert paged == [ch.id]
+
+
+class _NullYt:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def _playlist_page(ids, next_token=None):
+    """A playlistItems.list response shaped for stub_from_playlist_item."""
+    page = {
+        "items": [
+            {
+                "contentDetails": {"videoId": vid, "videoPublishedAt": "2020-01-01T00:00:00Z"},
+                "snippet": {"title": vid},
+            }
+            for vid in ids
+        ]
+    }
+    if next_token is not None:
+        page["nextPageToken"] = next_token
+    return page
+
+
+class _PagedYt:
+    """Serves a fixed page-token -> page map and records the tokens it was asked for, so a test can
+    assert exactly how many pages a deep-backfill run fetched (and where it resumed from)."""
+
+    def __init__(self, pages):
+        self.pages = pages
+        self.calls: list[str | None] = []
+
+    def get_playlist_items(self, playlist_id, page_token=None):
+        self.calls.append(page_token)
+        return self.pages[page_token]
+
+
+class _RaisingYt:
+    """Serves pages like _PagedYt but raises when asked for `raise_on_token`, to simulate a
+    network/API failure that lands BETWEEN pages of a deep backfill."""
+
+    def __init__(self, pages, raise_on_token):
+        self.pages = pages
+        self.raise_on_token = raise_on_token
+        self.calls: list[str | None] = []
+
+    def get_playlist_items(self, playlist_id, page_token=None):
+        self.calls.append(page_token)
+        if page_token == self.raise_on_token:
+            raise RuntimeError("simulated mid-backfill failure")
+        return self.pages[page_token]
+
+
+class TestDeepBackfillPaging:
+    """backfill_channel_deep must commit the advanced cursor after every page (durable resume, no
+    re-charging quota for pages already stored) and yield the moment the shared budget hits the
+    backfill reserve — the two properties that make a high immediate max_pages safe."""
+
+    @staticmethod
+    def _channel(db):
+        ch = Channel(
+            id="UC_deep",
+            title="Deep",
+            recent_synced_at=_PUB,
+            uploads_playlist_id="UU_deep",
+            backfill_done=False,
+            backfill_cursor=None,
+        )
+        db.add(ch)
+        db.commit()
+        return ch
+
+    def test_cursor_is_committed_each_page_and_a_later_run_resumes(self, db, monkeypatch):
+        monkeypatch.setattr(videos.quota, "backfill_reserve_reached", lambda: False)  # budget ok
+        ch = self._channel(db)
+        yt = _PagedYt(
+            {
+                None: _playlist_page(["a1", "a2"], next_token="t1"),
+                "t1": _playlist_page(["b1", "b2"], next_token="t2"),
+                "t2": _playlist_page(["c1"], next_token=None),  # last page: no nextPageToken
+            }
+        )
+
+        # First run is bounded to 2 pages: it must stop mid-catalogue with the cursor durably parked
+        # on the next unfetched page and backfill_done still False.
+        added = videos.backfill_channel_deep(db, yt, ch, max_pages=2)
+        assert added == 4
+        assert yt.calls == [None, "t1"]
+        assert ch.backfill_cursor == "t2"
+        assert ch.backfill_done is False
+        # Durably persisted (committed per page), not just set on the in-memory object.
+        db.expire(ch)
+        assert ch.backfill_cursor == "t2"
+        assert db.query(Video).filter(Video.channel_id == ch.id).count() == 4
+
+        # A later run resumes FROM the stored cursor (not from the start — no wasted re-fetch) and
+        # finishes: reaching the token-less last page flips backfill_done and clears the cursor.
+        added2 = videos.backfill_channel_deep(db, yt, ch, max_pages=5)
+        assert added2 == 1
+        assert yt.calls == [None, "t1", "t2"]  # resumed at "t2", did not re-fetch None/"t1"
+        assert ch.backfill_done is True
+        assert ch.backfill_cursor is None
+
+    def test_yields_when_the_shared_budget_hits_the_reserve(self, db, monkeypatch):
+        # Budget is fine for the first page, then hits the reserve — the guard is checked BEFORE each
+        # page, so the run fetches exactly one page and then yields, leaving the tail for the paced
+        # scheduler (cursor parked, backfill_done False).
+        reached = iter([False, True])
+        monkeypatch.setattr(videos.quota, "backfill_reserve_reached", lambda: next(reached))
+        ch = self._channel(db)
+        yt = _PagedYt(
+            {
+                None: _playlist_page(["a1", "a2"], next_token="t1"),
+                "t1": _playlist_page(["b1"], next_token="t2"),
+            }
+        )
+
+        added = videos.backfill_channel_deep(db, yt, ch, max_pages=50)
+        assert added == 2
+        assert yt.calls == [None]  # stopped before fetching the second page
+        assert ch.backfill_cursor == "t1"
+        assert ch.backfill_done is False
+
+    def test_a_mid_run_failure_leaves_the_prior_page_durably_committed(self, db, monkeypatch):
+        # The whole point of committing per page (vs one commit after the loop): if paging blows up
+        # mid-run, the pages already ingested stay durable, so the next run resumes from the stored
+        # cursor instead of re-fetching — and re-charging quota for — them. A single end-of-loop
+        # commit would lose the advanced cursor on the crash (it never reaches the post-loop commit),
+        # so this asserts the property the per-page commit actually buys.
+        monkeypatch.setattr(videos.quota, "backfill_reserve_reached", lambda: False)  # budget ok
+        ch = self._channel(db)
+        yt = _RaisingYt(
+            {None: _playlist_page(["a1", "a2"], next_token="t1")},
+            raise_on_token="t1",  # page 1 succeeds; fetching page 2 (token 't1') fails
+        )
+
+        with pytest.raises(RuntimeError):
+            videos.backfill_channel_deep(db, yt, ch, max_pages=5)
+
+        # Page 1's cursor AND rows were committed before the page-2 crash — re-read from the DB
+        # (expire) to prove it's persisted, not just set on the in-memory object.
+        db.expire(ch)
+        assert ch.backfill_cursor == "t1"
+        assert ch.backfill_done is False
+        assert db.query(Video).filter(Video.channel_id == ch.id).count() == 2

backend/tests/test_config_commit_ownership.py

@@ -0,0 +1,38 @@
+"""E3 S3 (B-core-10): the config/state mutators flush but do NOT self-commit, so the caller owns the
+transaction and a change lands together with its audit row. These lock that contract — a rollback
+before the caller commits discards the change (proving no hidden internal commit), while a same-session
+read still sees it (flush visibility). DB lane (`db` fixture) — skipped without Postgres.
+"""
+from app import state, sysconfig
+
+
+def test_set_value_flushes_but_leaves_the_commit_to_the_caller(db):
+    default = sysconfig.get_int(db, "quota_daily_budget")
+    new = default + 4321
+
+    sysconfig.set_value(db, "quota_daily_budget", new)
+    assert sysconfig.get_int(db, "quota_daily_budget") == new  # visible in-session (flushed)
+
+    db.rollback()  # the caller never committed
+    assert sysconfig.get_int(db, "quota_daily_budget") == default  # discarded — no hidden self-commit
+
+
+def test_reset_flushes_but_leaves_the_commit_to_the_caller(db):
+    default = sysconfig.get_int(db, "quota_daily_budget")
+    sysconfig.set_value(db, "quota_daily_budget", default + 10)
+    db.commit()  # a persisted override to reset
+
+    sysconfig.reset(db, "quota_daily_budget")
+    assert sysconfig.get_int(db, "quota_daily_budget") == default  # reset visible in-session
+    db.rollback()
+    assert sysconfig.get_int(db, "quota_daily_budget") == default + 10  # reset discarded until committed
+
+
+def test_set_sync_paused_flushes_but_leaves_the_commit_to_the_caller(db):
+    assert state.is_sync_paused(db) is False
+
+    state.set_sync_paused(db, True)
+    assert state.is_sync_paused(db) is True  # visible in-session
+
+    db.rollback()
+    assert state.is_sync_paused(db) is False  # discarded — the caller owns the commit

backend/tests/test_download_errors.py

@@ -12,6 +12,7 @@ def test_real_ytdlp_messages_map_to_categories():
         "ERROR: [youtube] abc: Sign in to confirm your age. This video may be inappropriate": "login_required",
         "ERROR: [youtube] abc: Sign in to confirm you're not a bot": "login_required",
         "ERROR: [youtube] abc: Join this channel to get access to members-only content": "login_required",
+        "ERROR: [Reddit] 1vi1x56: Account authentication is required.": "login_required",
         "ERROR: [youtube] abc: The uploader has not made this video available in your country": "geo_blocked",
         "ERROR: [youtube] abc: Requested format is not available": "format_unavailable",
         "ERROR: [youtube] abc: Only images are available for download": "format_unavailable",

backend/tests/test_download_limits.py

@@ -0,0 +1,164 @@
+"""DB-backed tests for R12 · S5 backend residue — the two download limits:
+
+- **#2 claim fairness** (`worker._claim_job`): users already AT their per-user concurrency limit
+  are excluded IN THE SQL, so one user flooding the queue past the fetch window can't starve
+  everyone behind them. The old fixed `LIMIT 50` window did exactly that.
+- **#3 list cap** (`routes.downloads.list_downloads` / `shared_with_me`): the per-user listings
+  are bounded so a heavy library can't return an unbounded result set.
+
+Uses the `db` fixture (real Postgres) — skipped when no database is reachable. `_claim_job` runs in
+its OWN session, so every test COMMITS its setup before calling it.
+"""
+from app.models import DownloadJob, DownloadQuota, MediaAsset, User
+from app.worker import _claim_job
+
+
+def _job(db, user_id, queue_pos, status="queued", asset_id=None):
+    j = DownloadJob(
+        user_id=user_id,
+        asset_id=asset_id,
+        source_kind="youtube",
+        source_ref="x" * 11,
+        status=status,
+        queue_pos=queue_pos,
+        profile_snapshot={},
+    )
+    db.add(j)
+    return j
+
+
+def _asset(db, status, ref):
+    a = MediaAsset(
+        source_kind="url", source_ref=ref, format_sig="s", status=status, ref_count=1
+    )
+    db.add(a)
+    db.flush()
+    return a
+
+
+def _quota(db, user_id, max_concurrent, unlimited=False):
+    db.add(
+        DownloadQuota(
+            user_id=user_id,
+            max_bytes=10**12,
+            max_concurrent=max_concurrent,
+            max_jobs=10**6,
+            unlimited=unlimited,
+        )
+    )
+
+
+# --- #2 · claim fairness --------------------------------------------------------------------
+
+def test_capped_user_flood_does_not_starve_users_behind_the_window(db):
+    a = User(email="flooder@example.com")
+    b = User(email="waiter@example.com")
+    db.add_all([a, b])
+    db.flush()
+    _quota(db, a.id, max_concurrent=1)  # A: 1 concurrent, already running one -> all A's queued are ineligible
+    _quota(db, b.id, max_concurrent=3)
+    _job(db, a.id, queue_pos=0, status="running")
+    for i in range(1, 61):  # A floods the FRONT with far more than the 50-row fetch window
+        _job(db, a.id, queue_pos=i)
+    bjob = _job(db, b.id, queue_pos=100)  # B sits behind the flood
+    db.commit()
+
+    assert _claim_job() == bjob.id  # B is served despite A's 60-job flood filling the old window
+    db.expire_all()
+    assert db.get(DownloadJob, bjob.id).status == "running"
+
+
+def test_eligible_user_claims_oldest_by_queue_pos(db):
+    u = User(email="solo@example.com")
+    db.add(u)
+    db.flush()
+    _quota(db, u.id, max_concurrent=2)
+    first = _job(db, u.id, queue_pos=1)
+    _job(db, u.id, queue_pos=2)
+    db.commit()
+    assert _claim_job() == first.id
+
+
+def test_all_candidates_capped_returns_none(db):
+    u = User(email="capped@example.com")
+    db.add(u)
+    db.flush()
+    _quota(db, u.id, max_concurrent=1)
+    _job(db, u.id, queue_pos=0, status="running")  # at the cap
+    _job(db, u.id, queue_pos=1)  # queued but ineligible
+    db.commit()
+    assert _claim_job() is None
+
+
+def test_stored_zero_concurrency_is_floored_not_starving(db):
+    # A stray max_concurrent=0 is only reachable by a direct DB edit (admin_set_quota floors at 1),
+    # but it must not wedge the claim loop. The effective limit floors to 1 on BOTH the read path
+    # (resolve -> at_concurrency_limit) and in the claim SQL (GREATEST(..., 1)), so the two "at
+    # limit" checks agree: the user's own first job is claimable and its flood never monopolizes
+    # the window with permanently-ineligible jobs. (Before the floor, _claim_job returned None here
+    # — the guard rejected all 60 of A's jobs — and any user behind them starved.)
+    a = User(email="zero@example.com")
+    b = User(email="behind@example.com")
+    db.add_all([a, b])
+    db.flush()
+    _quota(db, a.id, max_concurrent=0)  # nonsensical stored value
+    _quota(db, b.id, max_concurrent=2)
+    for i in range(60):
+        _job(db, a.id, queue_pos=i)
+    _job(db, b.id, queue_pos=100)
+    db.commit()
+
+    claimed = _claim_job()
+    assert claimed is not None  # the loop is not wedged
+    db.expire_all()
+    assert db.get(DownloadJob, claimed).user_id == a.id  # A's own first job runs (floored to 1)
+
+
+def test_job_whose_asset_is_already_downloading_is_skipped(db):
+    """B-sub-3: a queued job whose shared asset is ALREADY `downloading` (another worker owns it) must
+    not be claimed — otherwise a second worker claims it, finds the asset busy, requeues, and ping-
+    pongs on it, starving everyone behind. The claim SQL excludes it, so the job behind it (on a
+    different, free asset) is served instead."""
+    u = User(email="asset-excl@example.com")
+    db.add(u)
+    db.flush()
+    _quota(db, u.id, max_concurrent=5)  # high → the ASSET rule, not the per-user rule, does the excluding
+    busy = _asset(db, status="downloading", ref="busy")
+    free = _asset(db, status="pending", ref="free")
+    _job(db, u.id, queue_pos=1, status="running", asset_id=busy.id)  # the holder actually downloading it
+    competitor = _job(db, u.id, queue_pos=2, asset_id=busy.id)  # same asset — must be skipped
+    behind = _job(db, u.id, queue_pos=3, asset_id=free.id)  # different asset — should be served
+    db.commit()
+
+    assert _claim_job() == behind.id  # the competitor on the busy asset was skipped
+    db.expire_all()
+    assert db.get(DownloadJob, competitor.id).status == "queued"  # still queued, never claimed
+
+
+def test_unlimited_user_is_never_excluded(db):
+    u = User(email="unlimited@example.com")
+    db.add(u)
+    db.flush()
+    _quota(db, u.id, max_concurrent=1, unlimited=True)
+    for i in range(3):  # 3 running, well past max_concurrent — but unlimited bypasses the cap
+        _job(db, u.id, queue_pos=i, status="running")
+    q = _job(db, u.id, queue_pos=10)
+    db.commit()
+    assert _claim_job() == q.id
+
+
+# --- #3 · list cap --------------------------------------------------------------------------
+
+def test_list_downloads_is_capped(db, monkeypatch):
+    from app.routes import downloads as dl
+
+    u = User(email="heavy@example.com")
+    db.add(u)
+    db.flush()
+    for i in range(3):
+        _job(db, u.id, queue_pos=i, status="done")
+    db.commit()
+
+    monkeypatch.setattr(dl, "_MAX_LIST", 2)
+    rows = dl.list_downloads(user=u, db=db)
+    assert len(rows) == 2  # bounded by the cap, not the 3 rows on disk

backend/tests/test_download_output.py

@@ -6,7 +6,7 @@ with "PosixPath('.') has an empty name" instead of downloading."""
 import pytest
 
 from app.downloads.edit import _concat_quote, parse_probe_streams
-from app.worker import _media_info, _produced_file
+from app.downloads.pipeline import _media_info, _produced_file
 from pathlib import Path, PurePosixPath
 
 

backend/tests/test_download_ref_count.py

@@ -0,0 +1,116 @@
+"""E3 S2 characterization net — MediaAsset.ref_count enqueue/release accounting (B-sub-5).
+
+`ref_count` tracks how many DownloadJobs still hold a shared cache asset; when it hits zero a READY
+asset's file + row are freed. Enqueue +1's it and release_asset -1's it. Today those are Python
+read-modify-writes (`asset.ref_count = (asset.ref_count or 0) ± 1`), which lose an update under two
+concurrent enqueues/releases and can delete a file out from under a live holder. The fix makes the
+increment/decrement atomic at the DB; this net locks the OBSERVABLE single-threaded semantics so the
+conversion is provably behaviour-equivalent (concurrency itself can't be exercised in one session).
+
+DB lane (`db` fixture) — skipped without Postgres.
+"""
+from sqlalchemy import select, text
+
+from app.downloads import service
+from app.models import DownloadJob, MediaAsset, User
+
+
+def _user(db, email="ref@example.com"):
+    u = User(email=email)
+    db.add(u)
+    db.flush()
+    return u
+
+
+def _ref_count(db, asset_id) -> int | None:
+    # Read straight from the row — the atomic-UPDATE fix leaves the ORM copy stale on purpose.
+    return db.execute(
+        text("SELECT ref_count FROM media_assets WHERE id = :id"), {"id": asset_id}
+    ).scalar()
+
+
+def _holding_asset(db, *, status="ready", ref_count=1, rel_path=None) -> MediaAsset:
+    asset = MediaAsset(
+        source_kind="url", source_ref=f"r{ref_count}-{status}", format_sig="sig",
+        status=status, ref_count=ref_count, rel_path=rel_path,
+    )
+    db.add(asset)
+    db.flush()
+    return asset
+
+
+def _job(db, user_id, asset_id, status="done") -> DownloadJob:
+    j = DownloadJob(
+        user_id=user_id, asset_id=asset_id, source_kind="url", source_ref="r",
+        status=status, queue_pos=1, profile_snapshot={},
+    )
+    db.add(j)
+    db.flush()
+    return j
+
+
+def test_two_enqueues_share_one_asset_and_stack_ref_count(db):
+    u = _user(db)
+    j1 = service.enqueue(db, u.id, "url", "http://example.com/v", {})
+    j2 = service.enqueue(db, u.id, "url", "http://example.com/v", {})
+    # One shared cache asset, two jobs on it, ref_count == 2.
+    assert j1.asset_id == j2.asset_id
+    assets = db.execute(select(MediaAsset)).scalars().all()
+    assert len(assets) == 1
+    assert _ref_count(db, j1.asset_id) == 2
+
+
+def test_release_keeps_asset_until_last_holder_then_deletes_row(db):
+    u = _user(db)
+    asset = _holding_asset(db, status="ready", ref_count=2)
+    a = _job(db, u.id, asset.id, status="done")
+    b = _job(db, u.id, asset.id, status="done")
+    db.commit()
+
+    service.release_asset(db, a)
+    db.commit()
+    assert _ref_count(db, asset.id) == 1
+    assert db.get(MediaAsset, asset.id) is not None  # still held by b
+
+    service.release_asset(db, b)
+    db.commit()
+    # Last holder gone → the ready asset's row is freed (rel_path None, so no file to unlink).
+    assert db.execute(select(MediaAsset)).scalars().all() == []
+
+
+def test_release_is_a_noop_for_a_non_holding_job(db):
+    u = _user(db)
+    asset = _holding_asset(db, status="ready", ref_count=1)
+    canceled = _job(db, u.id, asset.id, status="canceled")  # canceled ∉ HOLDING
+    db.commit()
+
+    service.release_asset(db, canceled)
+    db.commit()
+    assert _ref_count(db, asset.id) == 1  # untouched — a canceled job already released while holding
+
+
+def test_release_never_drives_ref_count_negative(db):
+    u = _user(db)
+    # error-status asset (kept at zero, unlike ready) so we isolate the clamp from the delete branch.
+    asset = _holding_asset(db, status="error", ref_count=0)  # already at zero (defensive)
+    j = _job(db, u.id, asset.id, status="error")  # error ∈ HOLDING, so release runs
+    db.commit()
+
+    service.release_asset(db, j)
+    db.commit()
+    # The count clamps at 0 (never negative) even when released with nothing left to release.
+    assert _ref_count(db, asset.id) == 0
+    assert db.get(MediaAsset, asset.id) is not None
+
+
+def test_errored_asset_is_not_deleted_at_zero(db):
+    u = _user(db)
+    asset = _holding_asset(db, status="error", ref_count=1)
+    j = _job(db, u.id, asset.id, status="error")
+    db.commit()
+
+    service.release_asset(db, j)
+    db.commit()
+    # An errored row is cheap (no file) and may be re-enqueued → never deleted here, only ready is.
+    assert _ref_count(db, asset.id) == 0
+    assert db.get(MediaAsset, asset.id) is not None