fix(bypass): discard rejected DDoS-Guard cookies instead of replaying them (#1221 )

A cookie that has been rejected was kept and presented again on every later request, so a single bad clearance could re-arm the challenge indefinitely. Cookie storage: - Enforce expiry for every stored cookie, not just cf_clearance. DDoS-Guard domains have no cf_clearance, so the existing check never fired for them and expired cookies were replayed forever. - Stop storing the per-check cookies __ddg8_/__ddg9_/__ddg10_ and ddg_last_challenge. Captured live from Anna's Archive, these carry the client IP and the timestamp the check was issued (~40 min), versus ~1 year for the __ddg1_/__ddg2_/__ddgid_ clearance. Replaying an IP-bound token stops describing the caller as soon as the egress IP changes, which is routine behind a VPN. Failure handling — every path that is rejected while carrying cookies now purges them, not just the redirect loop: - 403 returned while presenting cookies. - Cached-cookie attempt rejected, whether by status or by redirect loop. - Factored the purge into _purge_clearance, guarded on a non-empty hostname since clear_cf_cookies("") means "every host" and would wipe clearance for sites that are working fine. Also fix the search warm-up switches shipped inert in v1.3.8: SEARCH_WARMUP_ENABLED and SEARCH_WARMUP_QUERY are not in the settings registry, and config.get only consults the environment for keys it knows, so both always returned their defaults — the warm-up could not be turned off or retargeted. Read os.environ first. Refs #1220. Deliberately not "Fixes": the reported failure could not be reproduced on v1.3.8 from a stable IP (the reporter's own queries all returned 200 on both the pre- and post-change builds), and the new purge paths did not fire in live testing because the failures arrive as redirect loops, which were already purged. These are correctness fixes with no measured effect on that issue. The underlying problem remains that Chrome-obtained cookies never satisfy DDoS-Guard when replayed by requests, so every search still re-solves. Verified: 2542 unit tests pass; ruff, basedpyright and vulture clean; e2e platform baseline (10), full (6) and bypasser-external (5) all pass; five sequential live searches against Anna's Archive all returned 200 with zero "Exceeded 30 redirects".
Fix log to debug DNS (#1219 )
2026-09-24 22:05:20 +01:00 · 2026-08-15 17:08:11 -04:00 · 2026-08-15 15:30:29 -04:00 · 2026-08-15 14:17:44 -04:00 · 2026-08-15 13:44:09 -04:00 · 2026-08-15 12:19:58 -04:00
139 changed files with 13218 additions and 1817 deletions
@@ -46,9 +46,7 @@ updates:
        # pre-release filter is bypassed for *grouped* updates
        # (dependabot-core#9496), so a grouped python update proposes pre-release
        # tags like python:3.15.0b2 as if they were a normal stable minor bump.
-        # Updated individually, python is filtered correctly: alpha/beta/rc tags
-        # are skipped and only stable releases (e.g. 3.15.0 once final) are
-        # proposed. node + uv stay grouped into a single digest PR.
+        # node + uv stay grouped into a single digest PR.
        patterns: ["*"]
        exclude-patterns: ["python"]
    ignore:
@@ -58,6 +56,24 @@ updates:
      - dependency-name: "node"
        update-types: ["version-update:semver-major"]

+      # Python: block minor/major bumps. Ungrouping python (above) is NOT enough
+      # to keep pre-releases out — dependabot-core#13815 rewrote the Docker
+      # pre-release heuristic to catch PEP 440 tags like 3.15.0a2 / 3.5.0b3, but
+      # the suffixed real tag still slipped through as PR #1169
+      # (python:3.14.6-slim -> python:3.15.0b3-slim). CPython spells
+      # pre-releases without a separator, so tag parsing reads 3.15.0b3 as an
+      # ordinary version that sorts above 3.14.6.
+      #
+      # A minor-version ignore blocks it regardless of spelling. Patch bumps
+      # (3.14.6 -> 3.14.7) and same-tag digest refreshes still land automatically.
+      # Moving the runtime to a new Python minor is a manual, deliberate change:
+      # bump the tag here and confirm C-extension wheels (greenlet/gevent) exist
+      # for it — a source build against a pre-release ABI boots an app that binds
+      # its port but never serves, which wedges e2e for the full 6h job limit.
+      - dependency-name: "python"
+        update-types:
+          ["version-update:semver-major", "version-update:semver-minor"]
+
  # GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
@@ -70,7 +70,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Log in to the Container registry
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
@@ -78,7 +78,7 @@ jobs:

      - name: Extract metadata for ${{ matrix.target }} image
        id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        env:
          # Annotate both the per-platform manifests and the multi-arch image
          # index. The index level is what manifest-list consumers (Renovate's
@@ -96,11 +96,11 @@ jobs:
            type=ref,event=tag

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0

      - name: Build and push ${{ matrix.target }} Docker image
        id: push
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          platforms: linux/amd64,linux/arm64
          context: .
@@ -115,7 +115,7 @@ jobs:

      - name: Generate artifact attestation for ${{ matrix.target }} image
        if: github.event_name != 'pull_request'
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}${{ matrix.image_name_suffix }}
          subject-digest: ${{ steps.push.outputs.digest }}
@@ -134,14 +134,14 @@ jobs:
      LEGACY_NAME: calibre-web-automated-book-downloader
    steps:
      - name: Log in to registry
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0

      - name: Create legacy aliases
        run: |
@@ -16,7 +16,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Install uv and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          version: "0.11.3"
          python-version: "3.14"
@@ -42,7 +42,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Install uv and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          version: "0.11.3"
          python-version: "3.14"
@@ -62,7 +62,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Install uv and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          version: "0.11.3"
          python-version: "3.14"
@@ -81,10 +81,10 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0

      - name: Build shelfmark-lite image
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          target: shelfmark-lite
@@ -102,7 +102,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 24
          cache: "npm"
@@ -125,7 +125,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 24
          cache: "npm"
@@ -145,7 +145,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Set up Node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 24
          cache: "npm"
@@ -25,14 +25,14 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Initialize CodeQL
-        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v3
+        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v3
        with:
          languages: ${{ matrix.language }}

      - name: Autobuild
-        uses: github/codeql-action/autobuild@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v3
+        uses: github/codeql-action/autobuild@5595ccaf912efad79be6eef63a5619ff05969be3 # v3

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v3
+        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v3
        with:
          category: "/language:${{ matrix.language }}"
@@ -30,7 +30,7 @@ jobs:
      relevant: ${{ steps.filter.outputs.relevant }}
    steps:
      - uses: actions/checkout@v7
-      - uses: dorny/paths-filter@v4.0.1
+      - uses: dorny/paths-filter@v4.0.3
        id: filter
        with:
          filters: |
@@ -60,6 +60,9 @@ jobs:
  e2e:
    needs: select-profiles
    runs-on: ubuntu-latest
+    # A wedged app under test must not burn GitHub's 6h max job limit. A healthy
+    # profile run finishes in ~3-5 min; anything past 25 is hung, not slow.
+    timeout-minutes: 25
    strategy:
      fail-fast: false
      matrix:
@@ -69,7 +72,7 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Install uv and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          python-version: "3.14"
          enable-cache: true
@@ -87,12 +90,14 @@ jobs:
    needs: changes
    if: needs.changes.outputs.relevant == 'true' || github.event_name != 'pull_request'
    runs-on: ubuntu-latest
+    # Real Chrome + qBittorrent is the slowest profile; still nowhere near 40 min.
+    timeout-minutes: 40
    name: e2e (full — real Chrome + qBittorrent)
    steps:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Install uv and Python
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          python-version: "3.14"
          enable-cache: true
@@ -4,7 +4,7 @@ ARG BUILDPLATFORM
 ARG BUILDARCH

 # Frontend build stage.
-FROM --platform=$BUILDPLATFORM node:24-alpine@sha256:a0b9bf06e4e6193cf7a0f58816cc935ff8c2a908f81e6f1a95432d679c54fbfd AS frontend-builder
+FROM --platform=$BUILDPLATFORM node:24-alpine@sha256:d32cdf619f63fe0471182d08996dd516c6275bb5fd31ae06e55a570bd9e1ad43 AS frontend-builder

 # Helpful debug output to see what platforms BuildKit thinks it's using
 RUN echo "BUILDPLATFORM=$BUILDPLATFORM BUILDARCH=$BUILDARCH TARGETPLATFORM=$TARGETPLATFORM TARGETARCH=$TARGETARCH"
@@ -24,10 +24,14 @@ COPY src/frontend/ ./
 # Build the frontend
 RUN npm run build

-# Use python-slim as the base image
-FROM python:3.14.6-slim@sha256:b877e50bd90de10af8d82c57a022fc2e0dc731c5320d762a27986facfc3355c1 AS base
+# uv is a build-time tool only, so it is mounted into the RUNs that need it rather
+# than copied into the image. A COPY here would land ~24 MB in a `base` layer that
+# every published image inherits, and a later `rm` cannot take it back out again --
+# a RUN adds a layer, it does not rewrite the one underneath.
+FROM ghcr.io/astral-sh/uv:0.11.3@sha256:90bbb3c16635e9627f49eec6539f956d70746c409209041800a0280b93152823 AS uv

-COPY --from=ghcr.io/astral-sh/uv:0.11.3@sha256:90bbb3c16635e9627f49eec6539f956d70746c409209041800a0280b93152823 /uv /uvx /bin/
+# Use python-slim as the base image
+FROM python:3.14.7-slim@sha256:ce40764625a4ff50df3548277632e7f96c4e77fe75fa848aae9885476e7df5a4 AS base

 # Add build argument for version
 ARG BUILD_VERSION
@@ -59,6 +63,11 @@ ENV FLASK_PORT=8084
 # Configure locale, timezone, and perform initial cleanup in a single layer
 RUN apt-get update && \
    apt-get install -y --no-install-recommends \
+    # For building C-extensions (cffi, gevent, etc.)
+    gcc \
+    g++ \
+    libffi-dev \
+    python3-dev \
    # For locale
    locales tzdata \
    # For healthcheck
@@ -106,6 +115,7 @@ WORKDIR /app
 # Install core Python dependencies first for better layer caching
 COPY pyproject.toml uv.lock ./
 RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=from=uv,source=/uv,target=/usr/local/bin/uv \
    uv sync --locked --no-default-groups

 # Runtime dependencies are installed into /app/.venv during the build. Remove the
@@ -194,6 +204,7 @@ RUN echo "deb [check-valid-until=no] https://snapshot.debian.org/archive/debian-

 # Install the browser automation stack used by the full image
 RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=from=uv,source=/uv,target=/usr/local/bin/uv \
    uv sync --locked --no-default-groups --extra browser

 # Deterministically resolve the Xlib namespace collision.
@@ -207,13 +218,11 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 # and force python-xlib 0.33 to own the namespace. pyautogui runs fine against
 # 0.33 (superset API).
 RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=from=uv,source=/uv,target=/usr/local/bin/uv \
    uv pip uninstall --python /app/.venv/bin/python python3-xlib && \
    uv pip install --python /app/.venv/bin/python --reinstall python-xlib==0.33 && \
    /app/.venv/bin/python -c "import Xlib.X; assert hasattr(Xlib.X, 'FamilyServerInterpreted'), 'Xlib.X.FamilyServerInterpreted missing after fix'; print('Xlib namespace OK:', Xlib.__version__)"

-# uv is only needed while building the image.
-RUN rm -f /usr/bin/uv /usr/bin/uvx
-
 # Keep SeleniumBase's bundled driver cache writable for the fixed non-root user.
 RUN SELENIUMBASE_DRIVERS_DIR=$(/app/.venv/bin/python -c "import pathlib, seleniumbase; print(pathlib.Path(seleniumbase.__file__).resolve().parent / 'drivers')") && \
    chown -R 1000:1000 "${SELENIUMBASE_DRIVERS_DIR}" && \
@@ -230,7 +239,4 @@ FROM base AS shelfmark-lite

 ENV USING_EXTERNAL_BYPASSER=true

-# uv is only needed while building the image.
-RUN rm -f /usr/bin/uv /usr/bin/uvx
-
 CMD ["/app/entrypoint.sh"]
@@ -1,72 +1,79 @@
 [
-    { "language": "English", "code": "en" },
-    { "language": "Chinese", "code": "zh" },
-    { "language": "Russian", "code": "ru" },
-    { "language": "Spanish", "code": "es" },
-    { "language": "French", "code": "fr" },
-    { "language": "German", "code": "de" },
-    { "language": "Italian", "code": "it" },
-    { "language": "Portuguese", "code": "pt" },
-    { "language": "Polish", "code": "pl" },
-    { "language": "Bulgarian", "code": "bg" },
-    { "language": "Dutch", "code": "nl" },
-    { "language": "Japanese", "code": "ja" },
-    { "language": "Arabic", "code": "ar" },
-    { "language": "Hebrew", "code": "he" },
-    { "language": "Turkish", "code": "tr" },
-    { "language": "Hungarian", "code": "hu" },
-    { "language": "Latin", "code": "la" },
-    { "language": "Czech", "code": "cs" },
-    { "language": "Korean", "code": "ko" },
-    { "language": "Ukrainian", "code": "uk" },
-    { "language": "Indonesian", "code": "id" },
-    { "language": "Romanian", "code": "ro" },
-    { "language": "Swedish", "code": "sv" },
-    { "language": "Greek", "code": "el" },
-    { "language": "Lithuanian", "code": "lt" },
-    { "language": "Bangla", "code": "bn" },
-    { "language": "Traditional Chinese", "code": "zh‑Hant" },
-    { "language": "Afrikaans", "code": "af" },
-    { "language": "Catalan", "code": "ca" },
-    { "language": "Danish", "code": "da" },
-    { "language": "Thai", "code": "th" },
-    { "language": "Hindi", "code": "hi" },
-    { "language": "Irish", "code": "ga" },
-    { "language": "Latvian", "code": "lv" },
+    { "language": "English", "code": "en", "aliases": ["eng"] },
+    { "language": "Chinese", "code": "zh", "aliases": ["chi", "zho"] },
+    { "language": "Russian", "code": "ru", "aliases": ["rus"] },
+    { "language": "Spanish", "code": "es", "aliases": ["spa"] },
+    { "language": "French", "code": "fr", "aliases": ["fra", "fre"] },
+    { "language": "German", "code": "de", "aliases": ["deu", "ger"] },
+    { "language": "Italian", "code": "it", "aliases": ["ita"] },
+    { "language": "Portuguese", "code": "pt", "aliases": ["por"] },
+    { "language": "Polish", "code": "pl", "aliases": ["pol"] },
+    { "language": "Bulgarian", "code": "bg", "aliases": ["bul"] },
+    { "language": "Dutch", "code": "nl", "aliases": ["dut", "nld"] },
+    { "language": "Japanese", "code": "ja", "aliases": ["jap", "jpn"] },
+    { "language": "Arabic", "code": "ar", "aliases": ["ara"] },
+    { "language": "Hebrew", "code": "he", "aliases": ["heb"] },
+    { "language": "Turkish", "code": "tr", "aliases": ["tur"] },
+    { "language": "Hungarian", "code": "hu", "aliases": ["hun"] },
+    { "language": "Latin", "code": "la", "aliases": ["lat"] },
+    { "language": "Czech", "code": "cs", "aliases": ["ces", "cze"] },
+    { "language": "Korean", "code": "ko", "aliases": ["kor"] },
+    { "language": "Ukrainian", "code": "uk", "aliases": ["ukr"] },
+    { "language": "Indonesian", "code": "id", "aliases": ["ind"] },
+    { "language": "Romanian", "code": "ro", "aliases": ["rom", "ron"] },
+    { "language": "Swedish", "code": "sv", "aliases": ["swe"] },
+    { "language": "Greek", "code": "el", "aliases": ["ell", "gre"] },
+    { "language": "Lithuanian", "code": "lt", "aliases": ["lit"] },
+    { "language": "Bangla", "code": "bn", "aliases": ["ben", "bengali"] },
+    { "language": "Traditional Chinese", "code": "zh-Hant", "aliases": ["zh‑Hant"] },
+    { "language": "Afrikaans", "code": "af", "aliases": ["afr"] },
+    { "language": "Catalan", "code": "ca", "aliases": ["cat"] },
+    { "language": "Danish", "code": "da", "aliases": ["dan"] },
+    { "language": "Thai", "code": "th", "aliases": ["tha"] },
+    { "language": "Hindi", "code": "hi", "aliases": ["hin"] },
+    { "language": "Irish", "code": "ga", "aliases": ["gle"] },
+    { "language": "Latvian", "code": "lv", "aliases": ["lav"] },
    { "language": "Tibetan", "code": "bo" },
-    { "language": "Kannada", "code": "kn" },
-    { "language": "Serbian", "code": "sr" },
-    { "language": "Persian", "code": "fa" },
-    { "language": "Croatian", "code": "hr" },
+    { "language": "Kannada", "code": "kn", "aliases": ["kan"] },
+    { "language": "Serbian", "code": "sr", "aliases": ["srp"] },
+    { "language": "Persian", "code": "fa", "aliases": ["farsi", "fas", "per"] },
+    { "language": "Croatian", "code": "hr", "aliases": ["hrv"] },
    { "language": "Slovak", "code": "sk" },
-    { "language": "Javanese", "code": "jv" },
-    { "language": "Vietnamese", "code": "vi" },
-    { "language": "Urdu", "code": "ur" },
-    { "language": "Finnish", "code": "fi" },
-    { "language": "Norwegian", "code": "no" },
+    { "language": "Javanese", "code": "jv", "aliases": ["jav"] },
+    { "language": "Vietnamese", "code": "vi", "aliases": ["vie"] },
+    { "language": "Urdu", "code": "ur", "aliases": ["urd"] },
+    { "language": "Finnish", "code": "fi", "aliases": ["fin"] },
+    { "language": "Norwegian", "code": "no", "aliases": ["nor"] },
    { "language": "Kinyarwanda", "code": "rw" },
-    { "language": "Tamil", "code": "ta" },
+    { "language": "Tamil", "code": "ta", "aliases": ["tam"] },
    { "language": "Belarusian", "code": "be" },
    { "language": "Kazakh", "code": "kk" },
    { "language": "Mongolian", "code": "mn" },
    { "language": "Georgian", "code": "ka" },
-    { "language": "Slovenian", "code": "sl" },
+    { "language": "Slovenian", "code": "sl", "aliases": ["slv"] },
    { "language": "Esperanto", "code": "eo" },
    { "language": "Galician", "code": "gl" },
-    { "language": "Marathi", "code": "mr" },
-    { "language": "Filipino", "code": "fil" },
-    { "language": "Gujarati", "code": "gu" },
-    { "language": "Malayalam", "code": "ml" },
+    { "language": "Marathi", "code": "mr", "aliases": ["mar"] },
+    { "language": "Filipino", "code": "fil", "aliases": ["tagalog", "tgl"] },
+    { "language": "Gujarati", "code": "gu", "aliases": ["guj"] },
+    { "language": "Malayalam", "code": "ml", "aliases": ["mal"] },
    { "language": "Kyrgyz", "code": "ky" },
    { "language": "Azerbaijani", "code": "az" },
    { "language": "Quechua", "code": "qu" },
    { "language": "Swahili", "code": "sw" },
    { "language": "Bashkir", "code": "ba" },
-    { "language": "Punjabi", "code": "pa" },
-    { "language": "Malay", "code": "ms" },
-    { "language": "Telugu", "code": "te" },
+    { "language": "Punjabi", "code": "pa", "aliases": ["pan"] },
+    { "language": "Malay", "code": "ms", "aliases": ["may", "msa"] },
+    { "language": "Telugu", "code": "te", "aliases": ["tel"] },
    { "language": "Albanian", "code": "sq" },
    { "language": "Uyghur", "code": "ug" },
    { "language": "Armenian", "code": "hy" },
-    { "language": "Shan", "code": "shn" }
+    { "language": "Shan", "code": "shn" },
+    { "language": "Bosnian", "code": "bs", "aliases": ["bos"] },
+    { "language": "Burmese", "code": "my", "aliases": ["bur", "mya"] },
+    { "language": "Estonian", "code": "et", "aliases": ["est"] },
+    { "language": "Icelandic", "code": "is", "aliases": ["ice", "isl"] },
+    { "language": "Manx", "code": "gv", "aliases": ["glv"] },
+    { "language": "Scottish Gaelic", "code": "gd", "aliases": ["gla"] },
+    { "language": "Sanskrit", "code": "sa", "aliases": ["san"] }
 ]
@@ -23,6 +23,7 @@ This document lists all configuration options that can be set via environment va
  - [Hardcover](#metadata-providers-hardcover)
  - [Open Library](#metadata-providers-open-library)
  - [Google Books](#metadata-providers-google-books)
+  - [Moly.hu](#metadata-providers-moly.hu)
 - [Direct Download](#direct-download)
  - [Download Sources](#direct-download-download-sources)
  - [Cloudflare Bypass](#direct-download-cloudflare-bypass)
@@ -246,7 +247,7 @@ Seconds since the last WireGuard handshake before the healthcheck bounces the tu
 | `CALIBRE_WEB_URL` | Adds a navigation button to your book library (Calibre-Web Automated, Grimmory, etc). | string | _none_ |
 | `AUDIOBOOK_LIBRARY_URL` | Adds a separate navigation button for your audiobook library (Audiobookshelf, Plex, etc). When both URLs are set, icons are shown instead of text. | string | _none_ |
 | `SUPPORTED_FORMATS` | Book formats to include in search results. ZIP/RAR archives are extracted automatically and book files are used if found. | string (comma-separated) | `epub,mobi,azw3,fb2,djvu,cbz,cbr` |
-| `SUPPORTED_AUDIOBOOK_FORMATS` | Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found. | string (comma-separated) | `m4b,mp3` |
+| `SUPPORTED_AUDIOBOOK_FORMATS` | Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found. | string (comma-separated) | `m4b,mp3,m4a,flac,ogg,wma,aac,wav,opus,zip,rar` |
 | `BOOK_LANGUAGE` | Default language filter for searches. | string (comma-separated) | `en` |

 <details>
@@ -295,7 +296,7 @@ Book formats to include in search results. ZIP/RAR archives are extracted automa
 Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found.

 - **Type:** string (comma-separated)
- **Default:** `m4b,mp3`
+- **Default:** `m4b,mp3,m4a,flac,ogg,wma,aac,wav,opus,zip,rar`

 #### `BOOK_LANGUAGE`

@@ -432,8 +433,8 @@ The release source tab to open by default in the release modal for audiobooks. U
 | `BOOKS_OUTPUT_MODE` | Choose where completed book files are sent. | string (choice) | `folder` |
 | `INGEST_DIR` | Directory where downloaded files are saved. Use {User} for per-user folders (e.g. /books/{User}). | string | `/books` |
 | `FILE_ORGANIZATION` | Choose how downloaded book files are named and organized. | string (choice) | `rename` |
-| `TEMPLATE_RENAME` | Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title} ({Year})` |
-| `TEMPLATE_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title} ({Year})` |
+| `TEMPLATE_RENAME` | Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title} ({Year})` |
+| `TEMPLATE_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title} ({Year})` |
 | `HARDLINK_TORRENTS` | Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. | boolean | `false` |
 | `BOOKLORE_HOST` | Base URL of your Grimmory instance | string | _none_ |
 | `BOOKLORE_USERNAME` | Grimmory account username | string | _none_ |
@@ -454,8 +455,8 @@ The release source tab to open by default in the release modal for audiobooks. U
 | `EMAIL_ALLOW_UNVERIFIED_TLS` | Disable TLS certificate verification (not recommended). | boolean | `false` |
 | `DESTINATION_AUDIOBOOK` | Directory where downloaded audiobook files are saved. Leave empty to use the Books destination. | string | _none_ |
 | `FILE_ORGANIZATION_AUDIOBOOK` | Choose how downloaded audiobook files are named and organized. | string (choice) | `rename` |
-| `TEMPLATE_AUDIOBOOK_RENAME` | Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title}` |
-| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title}/{Title}` |
+| `TEMPLATE_AUDIOBOOK_RENAME` | Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title}` |
+| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title}/{Title}` |
 | `HARDLINK_TORRENTS_AUDIOBOOK` | Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. | boolean | `true` |
 | `AUTO_OPEN_DOWNLOADS_SIDEBAR` | Automatically open the downloads sidebar when a new download is queued. | boolean | `false` |
 | `DOWNLOAD_TO_BROWSER_CONTENT_TYPES` | Automatically download completed files to your browser for the selected content types. | string (comma-separated) | _empty list_ |
@@ -499,7 +500,7 @@ Choose how downloaded book files are named and organized.

 **Naming Template**

-Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
+Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.

 - **Type:** string
 - **Default:** `{Author} - {Title} ({Year})`
@@ -508,7 +509,7 @@ Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename wi

 **Path Template**

-Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
+Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.

 - **Type:** string
 - **Default:** `{Author}/{Title} ({Year})`
@@ -709,7 +710,7 @@ Choose how downloaded audiobook files are named and organized.

 **Naming Template**

-Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.
+Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.

 - **Type:** string
 - **Default:** `{Author} - {Title}`
@@ -718,7 +719,7 @@ Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename wi

 **Path Template**

-Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.
+Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.

 - **Type:** string
 - **Default:** `{Author}/{Title}/{Title}`
@@ -1046,6 +1047,7 @@ Comma-separated hosts to bypass proxy (e.g., localhost,127.0.0.1,10.*,*.local)
 |----------|-------------|------|---------|
 | `URL_BASE` | Optional URL path prefix. Use a path like /shelfmark (no hostname). Leave blank for root. | string | _none_ |
 | `DEBUG` | Enable verbose logging to console and file. Not recommended for normal use. | boolean | `false` |
+| `LOG_LEVEL` | Lowest severity written to the console and log file. Ignored while Debug Mode is on, which forces Debug. | string (choice) | `INFO` |
 | `MAIN_LOOP_SLEEP_TIME` | How often the download queue is checked for new items. | number | `5` |
 | `DOWNLOAD_PROGRESS_UPDATE_INTERVAL` | How often download progress is broadcast to the UI. | number | `1` |
 | `CUSTOM_SCRIPT` | Path to a script to run after each successful download. Must be executable. | string | _none_ |
@@ -1082,6 +1084,17 @@ Enable verbose logging to console and file. Not recommended for normal use.
 - **Default:** `false`
 - **Requires restart:** Yes

+#### `LOG_LEVEL`
+
+**Log Level**
+
+Lowest severity written to the console and log file. Ignored while Debug Mode is on, which forces Debug.
+
+- **Type:** string (choice)
+- **Default:** `INFO`
+- **Requires restart:** Yes
+- **Options:** `DEBUG` (Debug), `INFO` (Info), `WARNING` (Warning), `ERROR` (Error), `CRITICAL` (Critical)
+
 #### `MAIN_LOOP_SLEEP_TIME`

 **Queue Check Interval (seconds)**
@@ -1211,6 +1224,7 @@ How long to cache individual book details. Default: 600 (10 minutes). Max: 60480
 | `PROWLARR_API_KEY` | Found in Prowlarr: Settings > General > API Key | string (secret) | _none_ |
 | `PROWLARR_INDEXERS` | Select which indexers to search. 📚 = has book categories. Leave empty to search all. | string (comma-separated) | _empty list_ |
 | `PROWLARR_AUTO_EXPAND` | Automatically retry search without category filtering if no results are found | boolean | `false` |
+| `PROWLARR_COLLAPSE_DUPLICATES` | Collapse a release that several indexer entries returned down to a single row, keeping the entry with the best Prowlarr priority. Turn this off to see every entry that carried it, which is what makes results from filter-specific entries (freeleech and the like) visible. | boolean | `true` |
 | `PROWLARR_USE_SEED_PREFERENCES` | Apply per-indexer seed time and ratio preferences from Prowlarr when sending torrents to the download client | boolean | `false` |

 <details>
@@ -1263,6 +1277,15 @@ Automatically retry search without category filtering if no results are found
 - **Type:** boolean
 - **Default:** `false`

+#### `PROWLARR_COLLAPSE_DUPLICATES`
+
+**Show one row per release**
+
+Collapse a release that several indexer entries returned down to a single row, keeping the entry with the best Prowlarr priority. Turn this off to see every entry that carried it, which is what makes results from filter-specific entries (freeleech and the like) visible.
+
+- **Type:** boolean
+- **Default:** `true`
+
 #### `PROWLARR_USE_SEED_PREFERENCES`

 **Use Prowlarr seed preferences**
@@ -1281,6 +1304,8 @@ Apply per-indexer seed time and ratio preferences from Prowlarr when sending tor
 | `NEWZNAB_ENABLED` | Enable searching for books via a Newznab-compatible indexer | boolean | `false` |
 | `NEWZNAB_URL` | Base URL of your Newznab indexer or aggregator | string | _none_ |
 | `NEWZNAB_API_KEY` | Your Newznab API key (leave blank if not required) | string (secret) | _none_ |
+| `NEWZNAB_EBOOK_CATEGORIES` | Newznab category IDs searched for ebooks. Most indexers use the standard 7000, but some use custom IDs. Leave empty to use 7000. | string (comma-separated) | `7000` |
+| `NEWZNAB_AUDIOBOOK_CATEGORIES` | Newznab category IDs searched for audiobooks. Most indexers use the standard 3030, but some use custom IDs. Leave empty to use 3030. | string (comma-separated) | `3030` |
 | `NEWZNAB_AUTO_EXPAND` | Automatically retry search without category filtering if no results are found | boolean | `false` |

 <details>
@@ -1314,6 +1339,24 @@ Your Newznab API key (leave blank if not required)
 - **Type:** string (secret)
 - **Default:** _none_

+#### `NEWZNAB_EBOOK_CATEGORIES`
+
+**Ebook Categories**
+
+Newznab category IDs searched for ebooks. Most indexers use the standard 7000, but some use custom IDs. Leave empty to use 7000.
+
+- **Type:** string (comma-separated)
+- **Default:** `7000`
+
+#### `NEWZNAB_AUDIOBOOK_CATEGORIES`
+
+**Audiobook Categories**
+
+Newznab category IDs searched for audiobooks. Most indexers use the standard 3030, but some use custom IDs. Leave empty to use 3030.
+
+- **Type:** string (comma-separated)
+- **Default:** `3030`
+
 #### `NEWZNAB_AUTO_EXPAND`

 **Auto-expand search on no results**
@@ -1395,9 +1438,11 @@ Delay between requests in seconds to avoid rate limiting (0-10).
 | `IRC_SERVER` | IRC server hostname | string | _none_ |
 | `IRC_PORT` | IRC server port (usually 6697 for TLS, 6667 for plain) | number | `6697` |
 | `IRC_USE_TLS` | Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't support TLS. | boolean | `true` |
-| `IRC_CHANNEL` | Channel name without the # prefix | string | _none_ |
+| `IRC_CHANNEL` | Channel name without the # prefix. Used for all searches unless a separate audiobook channel is configured below. | string | _none_ |
 | `IRC_NICK` | Your IRC nickname (required). Must be unique on the IRC network. | string | _none_ |
-| `IRC_SEARCH_BOT` | The search bot to address queries to (required). | string | _none_ |
+| `IRC_SEARCH_BOT` | The search bot to address queries to (required). Searches are sent as "@<bot> <query>". | string | _none_ |
+| `IRC_AUDIOBOOK_CHANNEL` | Optional. Channel name (without the # prefix) for networks that index audiobooks separately, such as Undernet's bookz. Leave blank (the usual setting) to search the main channel above for audiobooks too. | string | _none_ |
+| `IRC_AUDIOBOOK_SEARCH_BOT` | Optional. Search bot for the audiobook channel. Leave blank to reuse the main search bot above. Only used when an audiobook channel is set. | string | _none_ |
 | `IRC_CACHE_TTL` | How long to keep cached search results before they expire. | string (choice) | `2592000` |

 <details>
@@ -1435,7 +1480,7 @@ Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't

 **Channel**

-Channel name without the # prefix
+Channel name without the # prefix. Used for all searches unless a separate audiobook channel is configured below.

 - **Type:** string
 - **Default:** _none_
@@ -1455,12 +1500,30 @@ Your IRC nickname (required). Must be unique on the IRC network.

 **Search bot**

-The search bot to address queries to (required). Searches are sent as "@<bot> <query>". Without it, queries would be posted unaddressed to the channel.
+The search bot to address queries to (required). Searches are sent as "@<bot> <query>".

 - **Type:** string
 - **Default:** _none_
 - **Required:** Yes

+#### `IRC_AUDIOBOOK_CHANNEL`
+
+**Audiobook channel**
+
+Optional. Channel name (without the # prefix) for networks that index audiobooks separately, such as Undernet's bookz. Leave blank (the usual setting) to search the main channel above for audiobooks too.
+
+- **Type:** string
+- **Default:** _none_
+
+#### `IRC_AUDIOBOOK_SEARCH_BOT`
+
+**Audiobook search bot**
+
+Optional. Search bot for the audiobook channel. Leave blank to reuse the main search bot above. Only used when an audiobook channel is set.
+
+- **Type:** string
+- **Default:** _none_
+
 #### `IRC_CACHE_TTL`

 **Cache Duration**
@@ -1478,9 +1541,12 @@ How long to keep cached search results before they expire.
 | Variable | Description | Type | Default |
 |----------|-------------|------|---------|
 | `PROWLARR_TORRENT_CLIENT` | Choose which torrent client to use | string (choice) | _empty string_ |
+| `ALLDEBRID_API_KEY` | AllDebrid API Key (apiv4) from your AllDebrid account settings | string (secret) | _none_ |
+| `REALDEBRID_API_KEY` | Real-Debrid API Key (Secret Token) from your Real-Debrid account settings | string (secret) | _none_ |
 | `QBITTORRENT_URL` | Web UI URL of your qBittorrent instance | string | _none_ |
 | `QBITTORRENT_USERNAME` | qBittorrent Web UI username | string | _none_ |
 | `QBITTORRENT_PASSWORD` | qBittorrent Web UI password | string (secret) | _none_ |
+| `QBITTORRENT_API_KEY` | Found in qBittorrent: Options > Web UI > API Key (qBittorrent 5.2.0+). Used instead of the username and password when set. | string (secret) | _none_ |
 | `QBITTORRENT_CATEGORY` | Category to assign to book downloads in qBittorrent | string | `books` |
 | `QBITTORRENT_CATEGORY_AUDIOBOOK` | Category for audiobook downloads. Leave empty to use the book category. | string | _empty string_ |
 | `QBITTORRENT_DOWNLOAD_DIR` | Server-side directory where torrents are downloaded (optional, uses qBittorrent default if not specified) | string | _none_ |
@@ -1500,9 +1566,11 @@ How long to keep cached search results before they expire.
 | `RTORRENT_URL` | XML-RPC URL of your rTorrent instance | string | _none_ |
 | `RTORRENT_USERNAME` | HTTP Basic auth username (if authentication enabled) | string | _none_ |
 | `RTORRENT_PASSWORD` | HTTP Basic auth password | string (secret) | _none_ |
-| `RTORRENT_LABEL` | Label to assign to book downloads in rTorrent | string | `cwabd` |
+| `RTORRENT_LABEL` | Label to assign to ebook downloads in rTorrent | string | `cwabd` |
+| `RTORRENT_AUDIOBOOK_LABEL` | Label to assign to audiobook downloads in rTorrent (falls back to Book Label if not set) | string | _none_ |
 | `RTORRENT_DOWNLOAD_DIR` | Server-side directory where torrents are downloaded (optional, uses rTorrent default if not specified) | string | _none_ |
-| `PROWLARR_TORRENT_ACTION` | Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding | string (choice) | `keep` |
+| `PROWLARR_TORRENT_ACTION` | Choose whether to keep, remove, or move the torrent to another category or label after import | string (choice) | `keep` |
+| `PROWLARR_TORRENT_POST_IMPORT_CATEGORY` | Category or label to assign after a successful import | string | _empty string_ |
 | `PROWLARR_USENET_CLIENT` | Choose which usenet client to use | string (choice) | _empty string_ |
 | `NZBGET_URL` | URL of your NZBGet instance | string | _none_ |
 | `NZBGET_USERNAME` | NZBGet control username | string | `nzbget` |
@@ -1526,7 +1594,25 @@ Choose which torrent client to use

 - **Type:** string (choice)
 - **Default:** _empty string_
- **Options:** `""` (None), `qbittorrent` (qBittorrent), `transmission` (Transmission), `deluge` (Deluge), `rtorrent` (rTorrent)
+- **Options:** `""` (None), `alldebrid` (AllDebrid), `qbittorrent` (qBittorrent), `realdebrid` (Real-Debrid), `transmission` (Transmission), `deluge` (Deluge), `rtorrent` (rTorrent)
+
+#### `ALLDEBRID_API_KEY`
+
+**API Key**
+
+AllDebrid API Key (apiv4) from your AllDebrid account settings
+
+- **Type:** string (secret)
+- **Default:** _none_
+
+#### `REALDEBRID_API_KEY`
+
+**API Key**
+
+Real-Debrid API Key (Secret Token) from your Real-Debrid account settings
+
+- **Type:** string (secret)
+- **Default:** _none_

 #### `QBITTORRENT_URL`

@@ -1555,6 +1641,15 @@ qBittorrent Web UI password
 - **Type:** string (secret)
 - **Default:** _none_

+#### `QBITTORRENT_API_KEY`
+
+**API Key**
+
+Found in qBittorrent: Options > Web UI > API Key (qBittorrent 5.2.0+). Used instead of the username and password when set.
+
+- **Type:** string (secret)
+- **Default:** _none_
+
 #### `QBITTORRENT_CATEGORY`

 **Book Category**
@@ -1730,11 +1825,20 @@ HTTP Basic auth password

 **Book Label**

-Label to assign to book downloads in rTorrent
+Label to assign to ebook downloads in rTorrent

 - **Type:** string
 - **Default:** `cwabd`

+#### `RTORRENT_AUDIOBOOK_LABEL`
+
+**Audiobook Label**
+
+Label to assign to audiobook downloads in rTorrent (falls back to Book Label if not set)
+
+- **Type:** string
+- **Default:** _none_
+
 #### `RTORRENT_DOWNLOAD_DIR`

 **Download Directory**
@@ -1748,11 +1852,20 @@ Server-side directory where torrents are downloaded (optional, uses rTorrent def

 **Torrent Completion Action**

-Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding
+Choose whether to keep, remove, or move the torrent to another category or label after import

 - **Type:** string (choice)
 - **Default:** `keep`
- **Options:** `keep` (Keep), `remove` (Remove)
+- **Options:** `keep` (Keep), `remove` (Remove), `change_category` (Change Category)
+
+#### `PROWLARR_TORRENT_POST_IMPORT_CATEGORY`
+
+**Post-Import Category**
+
+Category or label to assign after a successful import
+
+- **Type:** string
+- **Default:** _empty string_

 #### `PROWLARR_USENET_CLIENT`

@@ -2004,6 +2117,26 @@ Default sort order for Google Books search results.

 </details>

+### Metadata Providers: Moly.hu
+
+| Variable | Description | Type | Default |
+|----------|-------------|------|---------|
+| `MOLY_ENABLED` | Enable Moly.hu as a metadata provider for book searches | boolean | `false` |
+
+<details>
+<summary>Detailed descriptions</summary>
+
+#### `MOLY_ENABLED`
+
+**Enable Moly.hu**
+
+Enable Moly.hu as a metadata provider for book searches
+
+- **Type:** boolean
+- **Default:** `false`
+
+</details>
+
 ## Direct Download

 ### Direct Download: Download Sources
@@ -2011,6 +2144,7 @@ Default sort order for Google Books search results.
 | Variable | Description | Type | Default |
 |----------|-------------|------|---------|
 | `DIRECT_DOWNLOAD_ENABLED` | Show Direct Download in release-source lists and allow Direct mode searches. Add your own mirror URLs in the Mirrors tab before using it. | boolean | `false` |
+| `DIRECT_DOWNLOAD_LANGUAGE_FROM_PATH` | When language metadata is missing or unknown, parse the distant path (file path shown in search results) for language tags like [BD FR] or [En]. Also enables local language filtering so lgli files without AA language metadata are not excluded before the distant path can be checked. | boolean | `false` |
 | `AA_DONATOR_KEY` | Enables fast download access on AA. Get this from your donator account page. | string (secret) | _none_ |
 | `FAST_SOURCES_DISPLAY` | Always tried first, no waiting or bypass required. | JSON array | _see UI for defaults_ |
 | `SOURCE_PRIORITY` | Fallback sources, may have waiting. Requires bypasser. Drag to reorder. | JSON array | _see UI for defaults_ |
@@ -2038,6 +2172,15 @@ Show Direct Download in release-source lists and allow Direct mode searches. Add
 - **Type:** boolean
 - **Default:** `false`

+#### `DIRECT_DOWNLOAD_LANGUAGE_FROM_PATH`
+
+**Detect Language From Distant Path**
+
+When language metadata is missing or unknown, parse the distant path (file path shown in search results) for language tags like [BD FR] or [En]. Also enables local language filtering so lgli files without AA language metadata are not excluded before the distant path can be checked.
+
+- **Type:** boolean
+- **Default:** `false`
+
 #### `AA_DONATOR_KEY`

 **Account Donator Key**
@@ -12,7 +12,7 @@ With a subpath (`URL_BASE=/shelfmark/`):
 https://<your-shelfmark-domain>/shelfmark/api/auth/oidc/callback
 ```

-The callback URL is constructed from the incoming request, so your reverse proxy must forward `X-Forwarded-Proto` and `X-Forwarded-Host` correctly. PKCE (S256) is used automatically.
+The callback URL is constructed from the incoming request, so your reverse proxy must forward `X-Forwarded-Proto` and `X-Forwarded-Host` correctly, including the external port when it is not the protocol default. PKCE (S256) is used automatically.

 ## Settings

@@ -30,7 +30,19 @@ Configure in **Settings → Security → Authentication Method → OIDC**.
 | Auto-Provision Users | Create accounts on first login | `true` |
 | Login Button Label | Custom text for the sign-in button | — |

-Use **Test Connection** to verify discovery and client configuration before attempting login.
+Use **Test Connection** to verify discovery, client configuration, and the provider's token signing keys (JWKS) before attempting login.
+
+> **Authentik users:** make sure your provider has a **Signing Key** selected (e.g. the default self-signed certificate). Without one, Authentik serves an empty JWKS document and every login fails with an OIDC callback error, even though the discovery document looks healthy.
+
+## Account Linking
+
+On login, Shelfmark matches the OIDC identity to a user account in this order:
+
+1. **OIDC subject** — a user who has logged in through this provider before.
+2. **Email** — a local account with the same (unique) email address. This only happens when the provider also asserts `email_verified: true` for the address; an unverified email would let anyone claim a local account by registering its address at the IdP.
+3. Otherwise, a new account is created when **Auto-Provision Users** is enabled (username conflicts get a numeric suffix), or the login is rejected with "Account not found" when it is disabled.
+
+If the `email_verified` claim is missing or `false`, email linking is silently skipped — a common surprise when the address was never verified at the identity provider (e.g. Keycloak's **Email verified** toggle on the user, or Authentik accounts created without email verification). Make sure the `email` scope is requested and the address is marked verified in your IdP.

 ## Environment Variables

@@ -46,6 +58,8 @@ If `DISABLE_LOCAL_AUTH` and `OIDC_AUTO_REDIRECT` are both enabled, users are red

 ## Troubleshooting

+- **No token signing keys (empty JWKS)** — The provider's JWKS endpoint returned no keys, so ID tokens can't be verified. In Authentik this happens when the provider has no **Signing Key** selected; pick one (e.g. the default self-signed certificate) and try again.
 - **Issuer validation failed** — The issuer in the token doesn't match the discovery document. Check your provider's external URL / issuer configuration.
 - **Callback URL mismatch** — Reverse proxy isn't forwarding `X-Forwarded-Proto` or `X-Forwarded-Host`, so the constructed callback URL doesn't match what's registered in the provider.
- **Account not found** — Auto-provision is disabled and the user hasn't been pre-created by an admin.
+- **Account not found** — Auto-provision is disabled and the user hasn't been pre-created by an admin. If you pre-created the account with a matching email, see [Account Linking](#account-linking): the provider must send `email_verified: true` for linking to happen.
+- **Login created a duplicate account instead of linking to my local one** — Email linking requires a verified email; see [Account Linking](#account-linking). With `DEBUG=true`, the log notes when linking is skipped because the address isn't verified.
@@ -23,10 +23,11 @@ server {
    location / {
        proxy_pass http://shelfmark:8084;
        proxy_http_version 1.1;
-        proxy_set_header Host $host;
+        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
@@ -56,11 +57,11 @@ All Shelfmark paths (UI, API, assets, Socket.IO) are served under the base path.
 location /shelfmark/ {
    proxy_pass http://shelfmark:8084/shelfmark/;
    proxy_http_version 1.1;
-    proxy_set_header Host $host;
+    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
-    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 86400;
@@ -136,11 +137,11 @@ location /shelfmark/ {

    proxy_pass http://shelfmark:8084/shelfmark/;
    proxy_http_version 1.1;
-    proxy_set_header Host $host;
+    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
-    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 86400;
@@ -158,6 +159,7 @@ If login, settings saves, or downloads appear to fail in the browser but the act
 - Do not force `Connection: upgrade` on every request. That can break normal `POST` and `PUT` responses while the backend still processes them.
 - If your proxy UI does not support conditional websocket headers, remove the forced websocket headers entirely and let Shelfmark fall back to polling.
 - Keep the standard forwarded headers: `Host`, `X-Forwarded-For`, `X-Forwarded-Proto`, and `X-Forwarded-Host` when using a subpath or OIDC.
+- Preserve the original port in `Host` and `X-Forwarded-Host` by using `$http_host` rather than `$host` when Shelfmark is exposed on a custom port.

 This is especially relevant for Nginx Proxy Manager or custom advanced config snippets that add websocket headers globally.

@@ -261,7 +261,12 @@ test_write() {
    fi

    FILE_CONTENT=$(cat "$test_file" 2>/dev/null || echo "")
-    rm -f "$test_file"
+    # A folder can be writable but not deletable (e.g. a Synology share without
+    # "Delete subfolders and files"). That is not a boot failure - the app writes
+    # files in place on such shares - so don't let a failed cleanup print an
+    # alarming error or fail the probe.
+    run_as_target_user rm -f "$test_file" 2>/dev/null || \
+        echo "Note: could not remove test file in $folder (folder is writable but not deletable)"
    [ "$FILE_CONTENT" = "0123456789_TEST" ]
    result=$?
    if [ $result -eq 0 ]; then
@@ -479,7 +484,18 @@ fi
 # Always run Gunicorn (even when DEBUG=true) to ensure Socket.IO WebSocket
 # upgrades work reliably on customer machines.
 # Map app LOG_LEVEL (often DEBUG/INFO/...) to gunicorn's --log-level (lowercase).
-gunicorn_loglevel=$([ "$DEBUG" = "true" ] && echo debug || echo "${LOG_LEVEL:-info}" | tr '[:upper:]' '[:lower:]')
+# Gunicorn rejects anything outside its own list, so normalize and fall back to
+# info rather than letting a typo stop the container from booting.
+if [ "$DEBUG" = "true" ]; then
+    gunicorn_loglevel=debug
+else
+    gunicorn_loglevel=$(echo "${LOG_LEVEL:-info}" | tr '[:upper:]' '[:lower:]')
+    [ "$gunicorn_loglevel" = "warn" ] && gunicorn_loglevel=warning
+    case "$gunicorn_loglevel" in
+        debug|info|warning|error|critical) ;;
+        *) gunicorn_loglevel=info ;;
+    esac
+fi
 command="${GUNICORN_BIN} --log-level ${gunicorn_loglevel} --access-logfile - --error-logfile - --worker-class geventwebsocket.gunicorn.workers.GeventWebSocketWorker --workers 1 -t 300 -b ${FLASK_HOST:-0.0.0.0}:${FLASK_PORT:-8084} shelfmark.main:app"

 # If DEBUG and not using an external bypass
@@ -19,17 +19,20 @@ dependencies = [
    "psutil",
    "emoji",
    "rarfile",
-    "qbittorrent-api",
+    "qbittorrent-api>=2026.8.0",
    "transmission-rpc",
    "authlib>=1.7.2,<1.8",
    "apprise>=1.12.0",
+    # HTTP/2 client for RFC 8484 DoH: quad9 rejects HTTP/1.1 outright (505), which
+    # requests cannot speak. See shelfmark/download/doh_wireformat.py.
+    "httpx[http2]>=0.27",
 ]

 [project.optional-dependencies]
 browser = [
    "pyvirtualdisplay",
    "pyautogui",
-    "seleniumbase==4.50.5",
+    "seleniumbase==4.51.12",
    "python-xlib",
 ]

@@ -40,7 +43,7 @@ dev = [
    "pytest",
    "pytest-cov",
    "pytest-xdist>=3.8.0",
-    "ruff==0.15.20",
+    "ruff==0.16.2",
    "vulture>=2.14",
 ]

@@ -44,6 +44,7 @@ Works great alongside the following library tools, with support for automatic im
 ### Prerequisites

 - Docker & Docker Compose
+- At least 2 GB of RAM available to the container when using the standard image — see [Memory Requirements](#memory-requirements)

 ### Installation

@@ -122,7 +123,7 @@ See the full [Environment Variables Reference](docs/environment-variables.md) fo
 Some of the additional options available in Settings:
 - **Prowlarr** - Configure indexers and download clients to download books and audiobooks
 - **Additional audiobook sources** - Configure additional sources for audiobook discovery
- **IRC** - Add details for IRC book sources and download directly from the UI
+- **IRC** - Add details for IRC book sources and download directly from the UI. Most networks serve audiobooks from the same channel as ebooks (on `irc.irchighway.net` that's `#ebooks`, while `#bookz` is effectively inactive), so leave the separate audiobook channel blank unless your network actually indexes one. IRC audiobooks usually arrive as ZIP/RAR archives — keep those enabled under Supported Audiobook Formats or the releases are filtered out of results
 - **Library Link** - Add a link to your Calibre-Web or Grimmory instance in the UI header
 - **File processing** - Customiseable download paths, file renaming and directory creation with template-based renaming
 - **Network Settings** - Custom proxy support (SOCKS5 + HTTP/S) and configurable DNS
@@ -138,6 +139,17 @@ docker compose up -d

 The full-featured image with all network capabilities included.

+#### Memory Requirements
+
+The standard image ships a real Chromium browser, which it launches to solve Cloudflare challenges for Direct Download. Chromium needs room to run:
+
+- **2 GB of RAM available to the container** is a safe minimum; 1 GB or less is where problems usually start
+- Only relevant if you use Direct Download. Prowlarr, IRC and audiobook sources don't start the browser
+
+When the container is starved of memory, Chromium fails to start and every Direct Download fails with unrelated-looking errors — repeated `403 detected; switching to bypasser` followed by `No download URL found`, and downloads that never complete. If you're seeing that, check the container's memory limit and the host's free memory before suspecting your ISP or DNS.
+
+If you can't spare the memory, use the [Lite](#lite) image with an external resolver (e.g. FlareSolverr) running elsewhere.
+
 #### Tor Routing
 Optional Tor support for network privacy:
 ```bash
@@ -175,6 +187,7 @@ A lighter image without the built-in browser automation. Ideal for:
 - **External services** - Already running FlareSolverr or similar for other applications
 - **Alternative sources** - Using Prowlarr, IRC, or other configured sources
 - **Audiobooks** - Using Shelfmark primarily for audiobooks
+- **Constrained hosts** - No bundled browser, so it runs comfortably below the standard image's [memory requirements](#memory-requirements)

 ```bash
 curl -O https://raw.githubusercontent.com/calibrain/shelfmark/main/compose/docker-compose.lite.yml
@@ -247,7 +260,10 @@ Logs are available via:
 - `docker logs <container-name>`
 - `/var/log/shelfmark/` inside the container (when `ENABLE_LOGGING=true`)

-Log level is configurable via Settings or `LOG_LEVEL` environment variable.
+Log level is configurable under Settings → Advanced or via the `LOG_LEVEL` environment
+variable (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`; case-insensitive, defaults to
+`INFO`). The environment variable wins over the setting, and `DEBUG=true` forces `DEBUG`
+regardless of either. Changes take effect on restart.

 ## Development

@@ -47,6 +47,22 @@ def _coerce_timeout_ms(value: object, default: int) -> int:
    return default


+def max_duration_seconds() -> float:
+    """Upper bound on how long get_bypassed_page() can take for one URL.
+
+    MAX_RETRY attempts at the configured read timeout, plus the exponential backoff waited
+    between them (jitter is < 1s per gap, counted as a full second to stay conservative).
+    Callers use this to declare a stall-detection grace; see shelfmark.download.activity.
+    """
+    bypasser_timeout = _coerce_timeout_ms(config.get("EXT_BYPASSER_TIMEOUT", 60000), 60000)
+    read_timeout = min((bypasser_timeout / 1000) + READ_TIMEOUT_BUFFER, MAX_READ_TIMEOUT)
+    backoff_total = sum(
+        min(BACKOFF_CAP, BACKOFF_BASE * (2 ** (attempt - 1))) + 1.0
+        for attempt in range(1, MAX_RETRY)
+    )
+    return MAX_RETRY * read_timeout + backoff_total
+
+
 def _fetch_via_bypasser(target_url: str) -> str | None:
    """Make a single request to the external bypasser service. Returns HTML or None."""
    raw_bypasser_url = _coerce_config_str(
@@ -50,6 +50,9 @@ _LOADING_BODY_LENGTH_MAX = 50
 _PAGE_BODY_PREVIEW_CHARS = 500
 _BROWSER_START_TIMEOUT_SECONDS = 45.0
 _BYPASS_SUBPROCESS_TIMEOUT_SECONDS = 420.0
+# Same budget as the Docker helper process, applied to the in-process CDP path so both
+# branches of get() are bounded the same way.
+_IN_PROCESS_BYPASS_TIMEOUT_SECONDS = _BYPASS_SUBPROCESS_TIMEOUT_SECONDS
 _BYPASS_CHILD_ENV = "SHELFMARK_INTERNAL_BYPASSER_CHILD"

 # Challenge detection indicators
@@ -217,7 +220,13 @@ class _CdpWorker:
            msg = "CDP worker loop not available"
            raise RuntimeError(msg)
        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
-        return future.result(timeout=timeout)
+        try:
+            return future.result(timeout=timeout)
+        except TimeoutError:
+            # Otherwise the coroutine keeps running in the worker loop after we stop
+            # waiting, holding the browser and racing the next bypass.
+            future.cancel()
+            raise


 _CDP_WORKER = _CdpWorker()
@@ -244,6 +253,26 @@ DDG_COOKIE_NAMES = {
    "ddg_last_challenge",
 }

+# DDoS-Guard cookies that describe *one* check rather than granting clearance, and so
+# must never be replayed on a later request. Observed live on Anna's Archive:
+#
+#   __ddg9_   the client IP address
+#   __ddg10_  the unix timestamp the check was issued
+#   __ddg8_   an opaque token issued with them, same ~40 minute expiry
+#
+# Clearance itself lives in __ddg1_/__ddg2_/__ddgid_ (roughly a year) and __ddg5_.
+# Replaying the trio is actively harmful: once the timestamp ages out - or the egress
+# IP changes, which happens routinely behind a VPN - the values no longer describe the
+# caller, DDoS-Guard re-arms its check and answers every request with a ?check=1
+# redirect. That is the redirect loop, and it is self-inflicted. Dropping them simply
+# lets DDoS-Guard issue a fresh set, exactly as it does for a browser.
+DDG_EPHEMERAL_COOKIE_NAMES = {
+    "__ddg8_",
+    "__ddg9_",
+    "__ddg10_",
+    "ddg_last_challenge",
+}
+

 def _get_base_domain(domain: str) -> str:
    """Extract base domain from hostname (e.g., 'www.example.com' -> 'example.com')."""
@@ -259,6 +288,10 @@ def _get_full_cookie_domains() -> set[str]:

 def _should_extract_cookie(name: str, *, extract_all: bool) -> bool:
    """Determine if a cookie should be extracted based on its name."""
+    # Checked before extract_all: a per-check token is wrong to replay for every
+    # domain, including the full-session ones.
+    if name in DDG_EPHEMERAL_COOKIE_NAMES:
+        return False
    if extract_all:
        return True
    is_cf = name in CF_COOKIE_NAMES or name.startswith("cf_")
@@ -333,6 +366,16 @@ async def _extract_cookies_from_cdp(driver: Any, page: Any, url: str) -> None:
        logger.debug("Failed to extract cookies: %s", e)


+def _is_cookie_expired(cookie: dict[str, Any]) -> bool:
+    """Whether a stored cookie's expiry has passed. Session cookies never expire here."""
+    expiry = cookie.get("expiry")
+    if expiry is None:
+        expiry = cookie.get("expires")
+    if not expiry or expiry <= 0:
+        return False
+    return time.time() > expiry
+
+
 def get_cf_cookies_for_domain(domain: str) -> dict[str, str]:
    """Get stored cookies for a domain. Returns empty dict if none available."""
    if not domain:
@@ -346,16 +389,25 @@ def get_cf_cookies_for_domain(domain: str) -> dict[str, str]:
            return {}

        cf_clearance = cookies.get("cf_clearance", {})
-        if cf_clearance:
-            expiry = cf_clearance.get("expiry")
-            if expiry is None:
-                expiry = cf_clearance.get("expires")
-            if expiry and expiry > 0 and time.time() > expiry:
-                logger.debug("CF cookies expired for %s", base_domain)
-                _cf_cookies.pop(base_domain, None)
-                return {}
+        if cf_clearance and _is_cookie_expired(cf_clearance):
+            logger.debug("CF cookies expired for %s", base_domain)
+            _cf_cookies.pop(base_domain, None)
+            return {}

-        return {name: c["value"] for name, c in cookies.items()}
+        # Expiry applies to every cookie, not just Cloudflare's. DDoS-Guard domains
+        # have no cf_clearance, so the check above never fired for them and dead
+        # cookies were replayed indefinitely - the server answers those with a
+        # challenge, which is indistinguishable from having sent nothing at all.
+        live = {name: c for name, c in cookies.items() if not _is_cookie_expired(c)}
+        if len(live) != len(cookies):
+            expired = sorted(set(cookies) - set(live))
+            logger.debug("Dropping expired cookies for %s: %s", base_domain, expired)
+            if live:
+                _cf_cookies[base_domain] = live
+            else:
+                _cf_cookies.pop(base_domain, None)
+
+        return {name: c["value"] for name, c in live.items()}


 def has_valid_cf_cookies(domain: str) -> bool:
@@ -896,7 +948,11 @@ def _run_bypass_in_current_process(url: str, retry: int, cancel_flag: Event | No

    if os.environ.get(_BYPASS_CHILD_ENV) == "1":
        return asyncio.run(_run_bypass())
-    return _CDP_WORKER.run(_run_bypass())
+    # Bound the wait: this path runs in-process (non-Docker installs), holds the module-wide
+    # LOCKED for its whole duration, and neither page.get() nor page.wait() has a timeout of
+    # its own. Without a deadline here a single wedged CDP session blocks every subsequent
+    # bypass in the process forever.
+    return _CDP_WORKER.run(_run_bypass(), timeout=_IN_PROCESS_BYPASS_TIMEOUT_SECONDS)


 def _store_child_bypass_state(payload: dict[str, Any]) -> None:
@@ -1250,12 +1306,36 @@ def _try_with_cached_cookies(url: str, hostname: str) -> str | None:
        if response.status_code == HTTPStatus.OK:
            logger.debug("Cached cookies worked, skipped Chrome bypass")
            return response.text
+        logger.debug(
+            "Cached cookies rejected (%s) for %s; discarding them",
+            response.status_code,
+            url,
+        )
    except _REQUEST_OPERATION_ERRORS as exc:
+        # A redirect loop lands here too: DDoS-Guard answers a dead clearance cookie
+        # with an endless ?check=1 bounce rather than a status we can read.
        logger.debug("Cached cookie retry failed for %s: %s", url, exc)

+    # Reached only when the cached cookies did not produce a page, so they are no
+    # longer clearance. Dropping them now means the imminent Chrome solve starts from
+    # a clean slate and later requests cannot re-present the same rejected cookie.
+    # Guarded because clear_cf_cookies("") means "every host", which would wipe
+    # clearance for sites that are working fine.
+    if hostname:
+        clear_cf_cookies(hostname)
    return None


+def max_duration_seconds() -> float:
+    """Upper bound on how long get_bypassed_page() can take for one URL.
+
+    Both branches of get() are capped at _BYPASS_SUBPROCESS_TIMEOUT_SECONDS, and
+    get_bypassed_page() may call it twice (once, then again after a mirror/DNS rotation).
+    Callers use this to declare a stall-detection grace; see shelfmark.download.activity.
+    """
+    return 2 * _BYPASS_SUBPROCESS_TIMEOUT_SECONDS
+
+
 def get_bypassed_page(
    url: str, selector: network.AAMirrorSelector | None = None, cancel_flag: Event | None = None
 ) -> str | None:
@@ -6,34 +6,78 @@ import shutil
 import tempfile
 from pathlib import Path

+LOG_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+

 def string_to_bool(s: str) -> bool:
    """Convert string to boolean."""
    return s.lower() in ["true", "yes", "1", "y"]


+def _read_advanced_config(key: str) -> object | None:
+    """Read a key from the advanced settings file (import-time safe)."""
+    config_dir = Path(os.getenv("CONFIG_DIR", "/config"))
+    config_file = config_dir / "plugins" / "advanced.json"
+
+    if config_file.exists():
+        try:
+            with config_file.open() as f:
+                config = json.load(f)
+                if key in config:
+                    return config[key]
+        except json.JSONDecodeError, OSError:
+            pass
+
+    return None
+
+
 def _read_debug_from_config() -> bool:
    """Read DEBUG from env var or config file (import-time safe)."""
    env_debug = os.environ.get("DEBUG")
    if env_debug is not None:
        return string_to_bool(env_debug)

-    # Try to read from config file
-    config_dir = Path(os.getenv("CONFIG_DIR", "/config"))
-    config_file = config_dir / "plugins" / "advanced.json"
-
-    if config_file.exists():
-        try:
-            with config_file.open() as f:
-                config = json.load(f)
-                if "DEBUG" in config:
-                    return bool(config["DEBUG"])
-        except json.JSONDecodeError, OSError:
-            pass
+    value = _read_advanced_config("DEBUG")
+    if value is not None:
+        return bool(value)

    return False


+def normalize_log_level(raw: str | None) -> str:
+    """Normalize a log level name, falling back to INFO when unrecognized."""
+    if raw is None:
+        return "INFO"
+
+    normalized = raw.strip().upper()
+    # "WARN" is a logging alias, but gunicorn only accepts "warning".
+    if normalized == "WARN":
+        normalized = "WARNING"
+
+    if normalized not in LOG_LEVELS:
+        return "INFO"
+
+    return normalized
+
+
+def _read_log_level_from_config(debug: bool) -> str:
+    """Resolve the app log level from DEBUG, env var, or config file.
+
+    DEBUG wins when enabled, mirroring how entrypoint.sh picks gunicorn's level.
+    Otherwise LOG_LEVEL is read from the env var, then the settings file, and
+    falls back to INFO when unset or unrecognized.
+    """
+    if debug:
+        return "DEBUG"
+
+    raw = os.environ.get("LOG_LEVEL")
+    if raw is None:
+        value = _read_advanced_config("LOG_LEVEL")
+        raw = value if isinstance(value, str) else None
+
+    return normalize_log_level(raw)
+
+
 def _is_sqlite_file(path: Path) -> bool:
    """Check if a file is a valid SQLite database by reading magic bytes."""
    try:
@@ -101,7 +145,7 @@ INGEST_DIR = Path(os.getenv("INGEST_DIR", "/books"))
 # =============================================================================

 DEBUG = _read_debug_from_config()
-LOG_LEVEL = "DEBUG" if DEBUG else "INFO"
+LOG_LEVEL = _read_log_level_from_config(DEBUG)
 ENABLE_LOGGING = string_to_bool(os.getenv("ENABLE_LOGGING", "true"))


@@ -7,7 +7,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Protocol

 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Callable, Sequence
    from os import PathLike

 _DEPRECATED_SETTINGS_RESTRICTION_KEYS = (
@@ -16,6 +16,13 @@ _DEPRECATED_SETTINGS_RESTRICTION_KEYS = (
    "RESTRICT_SETTINGS_TO_ADMIN",
 )

+# The audiobook format list shipped as the default until the format sets were unified.
+# It only covered m4b/mp3, so FLAC/OPUS/OGG/M4A releases were dropped from search results
+# and rejected after download - and the wider default alone would never reach existing
+# installs, because initialize_default_configs() only writes defaults when the config
+# file does not exist yet.
+_LEGACY_AUDIOBOOK_FORMATS_DEFAULT = ("m4b", "mp3")
+

 class MigrationLogger(Protocol):
    """Logger surface used by config migration helpers."""
@@ -57,6 +64,54 @@ def _pick_legacy_settings_restriction(config: dict[str, Any]) -> bool | None:
    return None


+def migrate_audiobook_formats(
+    *,
+    load_general_config: Callable[[], dict[str, Any]],
+    # `object` rather than `None`: the result is discarded, and savers that report
+    # success (settings_registry.save_config_file returns bool) are not assignable to a
+    # `-> None` callable.
+    save_general_config: Callable[[dict[str, Any]], object],
+    widened_formats: Sequence[str],
+    logger: MigrationLogger,
+) -> None:
+    """Widen an untouched audiobook format list to the current, fuller default.
+
+    Only a list that still matches the old default exactly is rewritten. Any other value
+    means someone chose it deliberately, and a migration that "helpfully" re-enabled
+    formats a user had turned off would be worse than leaving them on the narrow list.
+    """
+    try:
+        config = load_general_config()
+
+        if "SUPPORTED_AUDIOBOOK_FORMATS" not in config:
+            # Nothing persisted, so the field default already applies.
+            logger.debug("No persisted audiobook formats - the current default applies")
+            return
+
+        current = config.get("SUPPORTED_AUDIOBOOK_FORMATS")
+        if not isinstance(current, list):
+            return
+
+        normalized = {str(fmt).strip().lower() for fmt in current if str(fmt).strip()}
+        if normalized != set(_LEGACY_AUDIOBOOK_FORMATS_DEFAULT):
+            logger.debug(
+                "Audiobook formats were customized (%s) - left unchanged", sorted(normalized)
+            )
+            return
+
+        save_general_config({"SUPPORTED_AUDIOBOOK_FORMATS": list(widened_formats)})
+        logger.info(
+            "Widened audiobook formats from the legacy default %s to %s",
+            list(_LEGACY_AUDIOBOOK_FORMATS_DEFAULT),
+            list(widened_formats),
+        )
+
+    except FileNotFoundError:
+        logger.debug("No existing general config file found - nothing to migrate")
+    except Exception:
+        logger.exception("Failed to migrate audiobook formats")
+
+
 def migrate_security_settings(
    *,
    load_security_config: Callable[[], dict[str, Any]],
@@ -115,7 +115,7 @@ def check_oidc_connection(
        response.raise_for_status()
        document = response.json()

-        required_fields = ["issuer", "authorization_endpoint", "token_endpoint"]
+        required_fields = ["issuer", "authorization_endpoint", "token_endpoint", "jwks_uri"]
        missing_fields = [field for field in required_fields if field not in document]
        if missing_fields:
            return {
@@ -123,6 +123,24 @@ def check_oidc_connection(
                "message": f"Discovery document missing fields: {', '.join(missing_fields)}",
            }

+        # Logins verify the ID token against the provider's JWKS, so an empty key
+        # set (e.g. an Authentik provider with no Signing Key selected) means every
+        # login will fail even though discovery looks healthy.
+        jwks_uri = str(document["jwks_uri"])
+        jwks_response = requests.get(jwks_uri, timeout=10, verify=get_ssl_verify(jwks_uri))
+        jwks_response.raise_for_status()
+        jwks_document = jwks_response.json()
+        jwks_keys = jwks_document.get("keys") if isinstance(jwks_document, dict) else None
+        if not jwks_keys:
+            return {
+                "success": False,
+                "message": (
+                    "Discovery document is valid, but the provider returned no token "
+                    "signing keys (empty JWKS), so logins will fail. If you use "
+                    "Authentik, select a Signing Key in the provider settings."
+                ),
+            }
+
        return {"success": True, "message": f"Connected to {document['issuer']}"}
    except Exception as exc:
        logger.exception("OIDC connection test failed")
@@ -1,6 +1,5 @@
 """Core settings registration and derived configuration values."""

-import json
 from pathlib import Path
 from typing import Any

@@ -15,6 +14,8 @@ from shelfmark.config.download_settings_handlers import (
    check_books_destination,
 )
 from shelfmark.config.email_settings import check_email_connection
+from shelfmark.config.migrations import migrate_audiobook_formats
+from shelfmark.core.languages import supported_book_languages
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.settings_registry import (
    ActionButton,
@@ -35,6 +36,7 @@ from shelfmark.core.settings_registry import (
    register_on_save,
    register_settings,
 )
+from shelfmark.core.utils import ARCHIVE_FORMATS, AUDIOBOOK_FORMATS

 _DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT_DEFAULT = 60
 _DOWNLOAD_CLIENT_COMPLETED_PATH_TIMEOUT_MAX = 3600
@@ -134,6 +136,20 @@ def _on_save_advanced(values: dict[str, Any]) -> dict[str, Any]:


 logger = setup_logger(__name__)
+
+
+def migrate_audiobook_format_settings() -> None:
+    """Bring installs created before the audiobook format sets were unified up to date."""
+    from shelfmark.core.settings_registry import load_config_file, save_config_file
+
+    migrate_audiobook_formats(
+        load_general_config=lambda: load_config_file("general"),
+        save_general_config=lambda values: save_config_file("general", values),
+        widened_formats=[*AUDIOBOOK_FORMATS, *ARCHIVE_FORMATS],
+        logger=logger,
+    )
+
+
 _SMTP_PORT_MAX = 65535
 _EMAIL_ATTACHMENT_LIMIT_MB_MAX = 600

@@ -143,11 +159,8 @@ for key in ["CONFIG_DIR", "LOG_DIR", "TMP_DIR", "INGEST_DIR", "DEBUG", "DOCKERMO
    if hasattr(env, key):
        logger.debug("  %s: %s", key, getattr(env, key))

-# Load supported book languages from data file
-# Path is relative to the package root, not this file
-_DATA_DIR = Path(__file__).resolve().parent.parent.parent / "data"
-with (_DATA_DIR / "book-languages.json").open() as file:
-    _SUPPORTED_BOOK_LANGUAGE = json.load(file)
+# Selectable book languages, without the resolution aliases clients do not need.
+_SUPPORTED_BOOK_LANGUAGE = supported_book_languages()

 # Directory settings
 BASE_DIR = Path(__file__).resolve().parent.parent.parent
@@ -218,11 +231,7 @@ _FORMAT_OPTIONS = [
 ]

 _AUDIOBOOK_FORMAT_OPTIONS = [
-    {"value": "m4b", "label": "M4B"},
-    {"value": "mp3", "label": "MP3"},
-    {"value": "m4a", "label": "M4A"},
-    {"value": "zip", "label": "ZIP"},
-    {"value": "rar", "label": "RAR"},
+    {"value": fmt, "label": fmt.upper()} for fmt in (*AUDIOBOOK_FORMATS, *ARCHIVE_FORMATS)
 ]

 _DOWNLOAD_TO_BROWSER_CONTENT_TYPE_OPTIONS = [
@@ -419,7 +428,7 @@ def general_settings() -> list[SettingsField]:
            label="Supported Audiobook Formats",
            description="Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found.",
            options=_AUDIOBOOK_FORMAT_OPTIONS,
-            default=["m4b", "mp3"],
+            default=[*AUDIOBOOK_FORMATS, *ARCHIVE_FORMATS],
        ),
        MultiSelectField(
            key="BOOK_LANGUAGE",
@@ -1012,7 +1021,7 @@ def download_settings() -> list[SettingsField]:
            key="TEMPLATE_RENAME",
            label="Naming Template",
            description=(
-                "Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} "
+                "Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} "
                "(source filename without extension). Universal adds: {Series}, "
                "{SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: "
                "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. "
@@ -1031,7 +1040,7 @@ def download_settings() -> list[SettingsField]:
            key="TEMPLATE_ORGANIZE",
            label="Path Template",
            description=(
-                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, "
+                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, "
                "{OriginalName} (source filename without extension). Universal adds: {Series}, "
                "{SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: "
                "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty."
@@ -1294,7 +1303,7 @@ def download_settings() -> list[SettingsField]:
            key="TEMPLATE_AUDIOBOOK_RENAME",
            label="Naming Template",
            description=(
-                "Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} "
+                "Variables: {Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} "
                "(source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, "
                "{PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: "
                "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. "
@@ -1311,7 +1320,7 @@ def download_settings() -> list[SettingsField]:
            key="TEMPLATE_AUDIOBOOK_ORGANIZE",
            label="Path Template",
            description=(
-                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, "
+                "Use / to create folders. Variables: {Author}, {Title}, {Year}, {Language}, {User}, "
                "{OriginalName} (source filename without extension), {Series}, {SeriesPosition}, "
                "{Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: "
                "{Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty."
@@ -1764,6 +1773,23 @@ def advanced_settings() -> list[SettingsField]:
            default=False,
            requires_restart=True,
        ),
+        SelectField(
+            key="LOG_LEVEL",
+            label="Log Level",
+            description=(
+                "Lowest severity written to the console and log file. "
+                "Ignored while Debug Mode is on, which forces Debug."
+            ),
+            options=[
+                {"value": "DEBUG", "label": "Debug", "description": "Everything, very noisy."},
+                {"value": "INFO", "label": "Info", "description": "Normal activity (default)."},
+                {"value": "WARNING", "label": "Warning", "description": "Warnings and problems."},
+                {"value": "ERROR", "label": "Error", "description": "Failures only."},
+                {"value": "CRITICAL", "label": "Critical", "description": "Fatal errors only."},
+            ],
+            default="INFO",
+            requires_restart=True,
+        ),
        NumberField(
            key="MAIN_LOOP_SLEEP_TIME",
            label="Queue Check Interval (seconds)",
@@ -39,6 +39,7 @@ def upsert_cwa_user(
        email=normalized_email,
        role=role,
        allow_email_link=True,
+        sync_username=True,
        collision_strategy=collision_strategy,
        alias_suffix=_CWA_ALIAS_SUFFIX,
        context=context,
@@ -108,6 +108,7 @@ def _build_updates(
    auth_source: str,
    role: str,
    sync_role: bool,
+    username: str | object,
    email: str | None | object,
    display_name: str | None | object,
    subject_field: str | None,
@@ -116,6 +117,8 @@ def _build_updates(
    updates: dict[str, Any] = {"auth_source": auth_source}
    if sync_role:
        updates["role"] = _normalize_role(role)
+    if username is not UNSET:
+        updates["username"] = _normalize_username(username)
    if email is not UNSET:
        updates["email"] = _normalize_email(email)
    if display_name is not UNSET:
@@ -125,10 +128,17 @@ def _build_updates(
    return updates


-def _next_suffix_username(user_db: UserDB, base_username: str) -> str:
+def _next_suffix_username(
+    user_db: UserDB,
+    base_username: str,
+    *,
+    exclude_user_id: int | None = None,
+) -> str:
    candidate = base_username
    suffix = 1
-    while user_db.get_user(username=candidate):
+    while existing := user_db.get_user(username=candidate):
+        if exclude_user_id is not None and int(existing.get("id") or 0) == exclude_user_id:
+            return candidate
        candidate = f"{base_username}_{suffix}"
        suffix += 1
    return candidate
@@ -149,7 +159,7 @@ def _find_existing_alias_user(
    ]
    if not candidates:
        return None
-    return sorted(candidates, key=lambda user: int(user.get("id") or 0))[0]
+    return min(candidates, key=lambda user: int(user.get("id") or 0), default=None)


 def _resolve_create_username(
@@ -185,6 +195,38 @@ def _resolve_create_username(
    return _next_suffix_username(user_db, alias_base), None, "username_collision_alias"


+def _resolve_update_username(
+    user_db: UserDB,
+    *,
+    current_user: dict[str, Any],
+    requested_username: str,
+    strategy: CollisionStrategy,
+    alias_suffix: str,
+) -> str:
+    current_user_id = int(current_user["id"])
+    existing = user_db.get_user(username=requested_username)
+    if existing is None or int(existing.get("id") or 0) == current_user_id:
+        return requested_username
+
+    if strategy == "suffix":
+        return _next_suffix_username(
+            user_db,
+            requested_username,
+            exclude_user_id=current_user_id,
+        )
+    if strategy == "alias":
+        return _next_suffix_username(
+            user_db,
+            f"{requested_username}{alias_suffix}",
+            exclude_user_id=current_user_id,
+        )
+
+    # `takeover` can select an existing row during creation, but once an
+    # identity is already matched it must never replace a different username
+    # owner. Preserve the matched row's current collision-free name instead.
+    return str(current_user["username"])
+
+
 def upsert_external_user(
    user_db: UserDB,
    *,
@@ -197,6 +239,7 @@ def upsert_external_user(
    subject: str | None = None,
    allow_email_link: bool = False,
    sync_role: bool = True,
+    sync_username: bool = False,
    allow_create: bool = True,
    collision_strategy: CollisionStrategy = "takeover",
    alias_suffix: str | None = None,
@@ -229,10 +272,26 @@ def upsert_external_user(
        subject=subject,
        allow_email_link=allow_email_link,
    )
+    resolved_alias_suffix = alias_suffix or f"__{auth_source}"
+    update_username: str | object = UNSET
+    if (
+        matched is not None
+        and sync_username
+        and normalize_auth_source(matched.get("auth_source"), matched.get("oidc_subject"))
+        == auth_source
+    ):
+        update_username = _resolve_update_username(
+            user_db,
+            current_user=matched,
+            requested_username=normalized_username,
+            strategy=collision_strategy,
+            alias_suffix=resolved_alias_suffix,
+        )
    updates = _build_updates(
        auth_source=auth_source,
        role=normalized_role,
        sync_role=sync_role,
+        username=update_username,
        email=normalized_email if email is not UNSET else UNSET,
        display_name=normalized_display_name if display_name is not UNSET else UNSET,
        subject_field=subject_field,
@@ -261,7 +320,6 @@ def upsert_external_user(
        )
        return None, "not_found"

-    resolved_alias_suffix = alias_suffix or f"__{auth_source}"
    create_username, takeover_target, create_reason = _resolve_create_username(
        user_db,
        auth_source=auth_source,
@@ -0,0 +1,138 @@
+"""Canonical language resolution shared by every release source.
+
+Release sources report a language in whatever shape their upstream uses: a
+two-letter code, an ISO 639-2 three-letter code in either the bibliographic or
+terminological form, or an English name. They all need the same ISO 639-1 code
+out the other side, so the aliases live in one place (``data/book-languages.json``)
+and adding a language means editing one file.
+"""
+
+import json
+import threading
+import unicodedata
+from pathlib import Path
+
+from shelfmark.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+LANGUAGE_DATA_PATH = Path(__file__).resolve().parents[1].parent / "data" / "book-languages.json"
+
+# Values a source uses to mean "we could not tell".
+LANGUAGE_PLACEHOLDERS = frozenset({"", "-", "--", "unknown", "unk", "n/a", "na", "none", "null"})
+
+_ALIAS_TO_CODE: dict[str, str] | None = None
+_CODE_TO_NAME: dict[str, str] | None = None
+_LOCK = threading.Lock()
+
+
+# Separators that stand in for the hyphen in a subtag. The dashes turn up in
+# codes copied from web pages -- "zh‑Hant" used U+2011, which renders close
+# enough to both a hyphen and an underscore to go unnoticed -- and the
+# underscore is the spelling Direct Download accepted before this module existed.
+_SUBTAG_SEPARATORS = dict.fromkeys(map(ord, "‐‑‒–—―−﹘﹣－_"), "-")
+
+
+def _fold(value: str) -> str:
+    """Casefold, strip accents, and normalize subtag separators, so 'Español'
+    and 'espanol', or 'zh-Hant', 'zh‑Hant' and 'zh_Hant', all match."""
+    decomposed = unicodedata.normalize("NFKD", value).translate(_SUBTAG_SEPARATORS)
+    stripped = "".join(ch for ch in decomposed if not unicodedata.combining(ch))
+    return " ".join(stripped.split()).casefold()
+
+
+def _load() -> tuple[dict[str, str], dict[str, str]]:
+    global _ALIAS_TO_CODE, _CODE_TO_NAME
+
+    if _ALIAS_TO_CODE is not None and _CODE_TO_NAME is not None:
+        return _ALIAS_TO_CODE, _CODE_TO_NAME
+
+    with _LOCK:
+        if _ALIAS_TO_CODE is not None and _CODE_TO_NAME is not None:
+            return _ALIAS_TO_CODE, _CODE_TO_NAME
+
+        alias_to_code: dict[str, str] = {}
+        code_to_name: dict[str, str] = {}
+
+        try:
+            raw = json.loads(LANGUAGE_DATA_PATH.read_text(encoding="utf-8"))
+        except OSError, ValueError:
+            logger.exception("Failed to load language data from %s", LANGUAGE_DATA_PATH)
+            raw = []
+
+        if not isinstance(raw, list):
+            logger.warning("Language data at %s is not a list", LANGUAGE_DATA_PATH)
+            raw = []
+
+        for item in raw:
+            if not isinstance(item, dict):
+                continue
+            code = str(item.get("code") or "").strip()
+            name = str(item.get("language") or "").strip()
+            if not code:
+                continue
+
+            code_to_name.setdefault(code, name or code)
+
+            for candidate in (code, name, *(item.get("aliases") or [])):
+                folded = _fold(str(candidate))
+                if folded and folded not in LANGUAGE_PLACEHOLDERS:
+                    alias_to_code.setdefault(folded, code)
+
+        _ALIAS_TO_CODE = alias_to_code
+        _CODE_TO_NAME = code_to_name
+        return alias_to_code, code_to_name
+
+
+def normalize_language(value: object) -> str | None:
+    """Resolve any known spelling of a language to its ISO 639-1 code.
+
+    Accepts a two-letter code, an ISO 639-2 three-letter code in either the
+    bibliographic or terminological form, or an English name. Returns None for
+    anything unrecognised or for the placeholders a source uses to say it does
+    not know, so callers can treat "no language" uniformly.
+    """
+    if value is None:
+        return None
+
+    folded = _fold(str(value))
+    if not folded or folded in LANGUAGE_PLACEHOLDERS:
+        return None
+
+    alias_to_code, _ = _load()
+    return alias_to_code.get(folded)
+
+
+def language_name(code: str | None) -> str | None:
+    """Return the English name for a language code, or None if unknown."""
+    if not code:
+        return None
+
+    _, code_to_name = _load()
+    return code_to_name.get(str(code).strip())
+
+
+def language_alias_map() -> dict[str, str]:
+    """Every known alias mapped to its code, for callers doing their own matching.
+
+    Direct Download scans free-text paths and needs the whole alias set up front
+    to look for, rather than resolving one candidate at a time.
+    """
+    alias_to_code, _ = _load()
+    return dict(alias_to_code)
+
+
+def supported_book_languages() -> list[dict[str, str]]:
+    """The selectable languages, as ``{"language": ..., "code": ...}``.
+
+    Aliases are an implementation detail of resolution, so they are left out of
+    what the settings dropdown and the API hand to clients.
+    """
+    _, code_to_name = _load()
+    return [{"language": name, "code": code} for code, name in code_to_name.items()]
+
+
+def known_language_codes() -> frozenset[str]:
+    """Every ISO 639-1 code the bundled language data defines."""
+    _, code_to_name = _load()
+    return frozenset(code_to_name)
@@ -108,6 +108,9 @@ class DownloadTask:
    retry_expected_hash: str | None = None  # Optional torrent hash used to match client downloads
    retry_ratio_limit: float | None = None  # Optional post-download seeding ratio
    retry_seeding_time_limit_minutes: int | None = None  # Optional post-download seeding time limit
+    retry_source_context: dict[str, Any] = field(
+        default_factory=dict
+    )  # Source-private context for retry/re-resolution
    can_retry_without_staged_source: bool = (
        True  # Whether the source can restart without a preserved staged file
    )
@@ -116,6 +119,7 @@ class DownloadTask:
    series_name: str | None = None
    series_position: float | None = None  # Float for novellas (e.g., 1.5)
    subtitle: str | None = None  # Book subtitle for naming templates
+    language: str | None = None  # Release language code for the {Language} template variable

    # Hardlinking support
    original_download_path: str | None = None  # Path in download client (for hardlinking)
@@ -4,6 +4,7 @@ import re
 from pathlib import Path
 from typing import TYPE_CHECKING

+from shelfmark.core.languages import LANGUAGE_PLACEHOLDERS, normalize_language
 from shelfmark.core.logger import setup_logger

 if TYPE_CHECKING:
@@ -19,6 +20,7 @@ KNOWN_TOKENS = [
    "primarytitle",
    "originalname",
    "partnumber",
+    "language",
    "subtitle",
    "author",
    "series",
@@ -66,6 +68,33 @@ def format_series_position(position: str | float | None) -> str:
    return str(position)


+def normalize_language_code(language: str | None) -> str:
+    """Resolve a release language to the single spelling used in a path.
+
+    Sources report the same language in different shapes: "en", "eng", "English".
+    All of them have to collapse to one code, or the editions they identify end
+    up in separate folders, which is the collision this token exists to prevent.
+    Placeholder values render empty so `{ (Language)}` disappears entirely
+    rather than labelling a folder "(unknown)".
+
+    A language the bundled data does not know is kept, casefolded, rather than
+    dropped: it still separates editions, and it cannot collide with a resolved
+    code precisely because nothing resolves it.
+    """
+    if not language:
+        return ""
+
+    resolved = normalize_language(language)
+    if resolved is not None:
+        return resolved
+
+    normalized = " ".join(str(language).split()).strip().casefold()
+    if normalized in LANGUAGE_PLACEHOLDERS:
+        return ""
+
+    return normalized
+
+
 def derive_primary_title(title: str | None, subtitle: str | None) -> str:
    """Return the title without an explicit subtitle suffix when possible."""
    title_value = " ".join(str(title or "").split()).strip()
@@ -91,8 +120,7 @@ PAD_NUMBERS_PATTERN = re.compile(r"\d+")

 def natural_sort_key(path: str | Path) -> str:
    """Generate a sort key with padded numbers for natural sorting."""
-    filename = Path(path).name.lower()
-    return PAD_NUMBERS_PATTERN.sub(lambda m: m.group().zfill(9), filename)
+    return PAD_NUMBERS_PATTERN.sub(lambda m: m.group().zfill(9), str(path).lower())


 def assign_part_numbers(
@@ -33,6 +33,11 @@ logger = setup_logger(__name__)
 oauth = OAuth()
 _RETURN_TO_SESSION_KEY = "oidc_return_to"
 _OIDC_CLIENT_ERRORS = (OAuthError, OSError, RuntimeError, TypeError, ValueError)
+_EMPTY_JWKS_MESSAGE = (
+    "Authentication failed: the identity provider returned no token signing keys "
+    "(empty JWKS). If you use Authentik, select a Signing Key in the provider "
+    "settings and try again."
+)


 class _ClaimsMappingLike(Protocol):
@@ -121,6 +126,17 @@ def _normalize_return_to(raw_return_to: object) -> str | None:
    return urlunsplit(("", "", path, parsed.query, parsed.fragment))


+def _idp_jwks_has_no_keys(client: Any) -> bool:
+    """Return True when the IdP's JWKS document verifiably contains no signing keys."""
+    try:
+        jwk_set = client.fetch_jwk_set(force=True)
+    except (*_OIDC_CLIENT_ERRORS, KeyError):
+        return False
+    if not isinstance(jwk_set, Mapping):
+        return False
+    return not jwk_set.get("keys")
+
+
 def _get_pending_return_to(*, clear: bool = False) -> str | None:
    """Read the pending post-login target from the session."""
    raw_return_to = (
@@ -274,6 +290,17 @@ def register_oidc_routes(app: Flask, user_db: UserDB) -> None:
                return redirect(
                    _login_error_url(f"OIDC token claim validation failed: {claim_name}")
                )
+            except KeyError, ValueError:
+                # An IdP serving an empty JWKS document (e.g. an Authentik provider
+                # with no Signing Key selected) surfaces as KeyError('keys') while
+                # importing the key set. Test Connection only validates discovery,
+                # so this is the first place the misconfiguration becomes visible.
+                if _idp_jwks_has_no_keys(client):
+                    logger.exception(
+                        "OIDC callback failed: the IdP JWKS document contains no signing keys"
+                    )
+                    return redirect(_login_error_url(_EMPTY_JWKS_MESSAGE))
+                raise
            claims = _normalize_claims(token.get("userinfo"))

            # If userinfo is missing or claims are too sparse, request it explicitly.
@@ -306,6 +333,12 @@ def register_oidc_routes(app: Flask, user_db: UserDB) -> None:
                is_admin = admin_group in groups

            allow_email_link = bool(user_info.get("email")) and _is_email_verified(claims)
+            if user_info.get("email") and not allow_email_link:
+                logger.debug(
+                    "OIDC email %s is not marked verified by the IdP; skipping "
+                    "email-based account linking",
+                    user_info["email"],
+                )
            user = provision_oidc_user(
                user_db,
                user_info,
@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any

 from werkzeug.utils import secure_filename

+from shelfmark.config.env import normalize_log_level
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.request_helpers import coerce_bool, normalize_optional_text

@@ -898,6 +899,9 @@ def _get_env_value_for_field(field: FieldBase) -> tuple[bool, object | None]:
            "WELIB_MIRROR_URLS",
        } and isinstance(parsed, list):
            parsed = _normalize_mirror_env_urls(parsed)
+        if field.key == "LOG_LEVEL" and isinstance(parsed, str):
+            # LOG_LEVEL is commonly set lowercase; the field options are uppercase.
+            parsed = normalize_log_level(parsed)
        return True, parsed

    if field.key == "AA_MIRROR_URLS":
@@ -344,6 +344,7 @@ class UserDB:

    _ALLOWED_UPDATE_COLUMNS: ClassVar[frozenset[str]] = frozenset(
        {
+            "username",
            "email",
            "display_name",
            "password_hash",
@@ -353,6 +354,7 @@ class UserDB:
        }
    )
    _USER_UPDATE_STATEMENTS: ClassVar[dict[str, str]] = {
+        "username": "UPDATE users SET username = ? WHERE id = ?",
        "email": "UPDATE users SET email = ? WHERE id = ?",
        "display_name": "UPDATE users SET display_name = ? WHERE id = ?",
        "password_hash": "UPDATE users SET password_hash = ? WHERE id = ?",
@@ -115,6 +115,21 @@ def is_audiobook(content_type: str | None) -> bool:
    return bool(content_type and "audiobook" in content_type.lower())


+# Every audio format an audiobook can legitimately arrive in, and the single source of
+# truth for that list. The settings UI, release-source parsing, archive extraction and
+# post-download scanning all derive from it, so a format added here becomes selectable,
+# searchable AND downloadable at once. These used to be four hand-maintained copies that
+# had drifted apart: the settings UI only offered m4b/mp3/m4a, which meant a FLAC
+# audiobook could never be enabled, was silently dropped from every search result, and
+# was rejected after download as "format not supported".
+AUDIOBOOK_FORMATS = ("m4b", "mp3", "m4a", "flac", "ogg", "wma", "aac", "wav", "opus")
+
+# Multi-file audiobooks are almost always distributed as an archive. These are containers
+# rather than formats: they are what a *release* looks like, and the formats above are
+# what comes out of one after extraction.
+ARCHIVE_FORMATS = ("zip", "rar")
+
+
 CONTENT_TYPES = [
    "book (fiction)",
    "book (non-fiction)",
@@ -0,0 +1,81 @@
+"""Stall-detection grace signalling for long single-shot download operations.
+
+The orchestrator cancels a download after `STALL_TIMEOUT` seconds without activity, where
+"activity" means a *changed* status event or a *changed* progress value. That de-duplication
+is deliberate - a keep-alive that repeats the same payload on a timer proves nothing about
+whether the operation is still making progress, so letting it refresh the stall clock would
+make a genuinely wedged download immortal.
+
+Operations that legitimately take longer than `STALL_TIMEOUT` but cannot report incremental
+progress therefore declare an explicit upper bound up front instead:
+
+    request_activity_grace(status_callback, my_worst_case_seconds)
+    try:
+        ...one long blocking call...
+    finally:
+        release_activity_grace(status_callback)
+
+The grace is a single absolute deadline. It is never extended, so the operation still dies
+if it overruns its own declared budget - just at *its* bound rather than at a global 300s.
+
+The signal rides on the existing `status_callback` channel using a sentinel status, which
+avoids threading a new parameter through every handler, post-processor and output module.
+`shelfmark.download.orchestrator`'s per-task `status_callback` closure intercepts the
+sentinel and never forwards it to `update_download_status`.
+
+Adopters should be operations that yield to the gevent hub while blocking (`requests`,
+patched `subprocess`). An operation that blocks the hub outright - `shutil.copy2`, sqlite -
+will still be killed by the gunicorn worker timeout regardless of any grace, and must go
+through `shelfmark.download.fs.run_blocking_io` first.
+
+Current adopters: `shelfmark.download.http.html_get_page` (protection bypass).
+Candidates: `download.clients.base_handler._wait_for_completed_path`, archive extraction in
+`download.postprocess.scan`, large-file copies in `download.outputs.folder`, email/BookLore
+uploads, and the Anna's Archive countdown in `release_sources.direct_download` (which today
+refreshes the stall clock on every tick of a loop that proves nothing about the remote).
+"""
+
+from collections.abc import Callable
+
+# Not a QueueStatus value, so `update_download_status` would reject it anyway; the
+# orchestrator's status_callback intercepts it before that point.
+ACTIVITY_GRACE_STATUS = "__activity_grace__"
+
+StatusCallback = Callable[[str, str | None], None]
+
+# A status_callback is caller-supplied and may raise; a failed liveness hint must never
+# break the operation it was protecting. Mirrors http._STATUS_CALLBACK_ERRORS.
+_CALLBACK_ERRORS = (AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError)
+
+
+def request_activity_grace(status_callback: StatusCallback | None, seconds: float) -> None:
+    """Ask the orchestrator to suppress stall detection for up to `seconds` from now."""
+    _emit(status_callback, seconds)
+
+
+def release_activity_grace(status_callback: StatusCallback | None) -> None:
+    """Drop any outstanding grace and count now as activity."""
+    _emit(status_callback, 0)
+
+
+def parse_activity_grace(status: str, message: str | None) -> float | None:
+    """Return the requested grace in seconds, or None if this is not a grace event.
+
+    Never raises: a malformed sentinel is treated as "not a grace event" so a bad emitter
+    cannot take down the status pipeline.
+    """
+    if status != ACTIVITY_GRACE_STATUS:
+        return None
+    try:
+        return max(float(message or 0), 0.0)
+    except TypeError, ValueError:
+        return 0.0
+
+
+def _emit(status_callback: StatusCallback | None, seconds: float) -> None:
+    if status_callback is None:
+        return
+    try:
+        status_callback(ACTIVITY_GRACE_STATUS, str(float(seconds)))
+    except _CALLBACK_ERRORS:
+        return
@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, cast

 from shelfmark.core.logger import setup_logger
+from shelfmark.core.utils import AUDIOBOOK_FORMATS
 from shelfmark.core.utils import is_audiobook as check_audiobook
 from shelfmark.download.fs import atomic_move
 from shelfmark.download.postprocess.policy import (
@@ -98,7 +99,7 @@ ALL_EBOOK_EXTENSIONS = {
 }

 # All known audio extensions (superset of what user might enable for audiobooks)
-ALL_AUDIO_EXTENSIONS = {".m4b", ".mp3", ".m4a", ".aac", ".flac", ".ogg", ".wma", ".wav", ".opus"}
+ALL_AUDIO_EXTENSIONS = {f".{fmt}" for fmt in AUDIOBOOK_FORMATS}


 def _filter_files(
@@ -325,6 +325,19 @@ class DownloadClient(ABC):

        """

+    def set_category(self, download_id: str, category: str) -> bool:
+        """Update a download's category or label when supported by the client.
+
+        Args:
+            download_id: The client-specific download ID.
+            category: Category or label to assign.
+
+        Returns:
+            True if the category was updated, otherwise False.
+
+        """
+        return False
+
    @abstractmethod
    def get_download_path(self, download_id: str) -> str | None:
        """Get the path where files were downloaded.
@@ -359,10 +372,13 @@ class DownloadClient(ABC):

 # Client registry: protocol -> list of client classes
 _CLIENTS: dict[str, list[type[DownloadClient]]] = {}
+ClientType = TypeVar("ClientType", bound=DownloadClient)
 _BUILTIN_CLIENT_MODULES = (
+    "shelfmark.download.clients.alldebrid",
    "shelfmark.download.clients.deluge",
    "shelfmark.download.clients.nzbget",
    "shelfmark.download.clients.qbittorrent",
+    "shelfmark.download.clients.realdebrid",
    "shelfmark.download.clients.rtorrent",
    "shelfmark.download.clients.sabnzbd",
    "shelfmark.download.clients.transmission",
@@ -383,7 +399,7 @@ def _ensure_builtin_clients_registered() -> None:

 def register_client(
    protocol: str,
-) -> Callable[[type[DownloadClient]], type[DownloadClient]]:
+) -> Callable[[type[ClientType]], type[ClientType]]:
    """Register a download client for a protocol.

    Multiple clients can be registered for the same protocol.
@@ -399,7 +415,7 @@ def register_client(

    """

-    def decorator(cls: type[DownloadClient]) -> type[DownloadClient]:
+    def decorator(cls: type[ClientType]) -> type[ClientType]:
        if protocol not in _CLIENTS:
            _CLIENTS[protocol] = []
        _CLIENTS[protocol].append(cls)
@@ -0,0 +1,681 @@
+"""AllDebrid debrid service client for Shelfmark.
+
+Routes magnet links through the AllDebrid API (v4/v4.1) to download
+torrent content via AllDebrid's CDN infrastructure.
+"""
+
+from __future__ import annotations
+
+import shutil
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar, NoReturn
+from urllib.parse import quote
+
+import requests
+
+from shelfmark.config.env import TMP_DIR
+from shelfmark.core.config import config
+from shelfmark.core.logger import setup_logger
+from shelfmark.download.clients import (
+    DownloadClient,
+    DownloadState,
+    DownloadStatus,
+    register_client,
+)
+from shelfmark.download.clients._coercion import config_text
+from shelfmark.download.http import download_url
+from shelfmark.download.network import get_ssl_verify
+
+logger = setup_logger(__name__)
+
+_API_BASE = "https://api.alldebrid.com/v4"
+_AGENT = "shelfmark"
+
+_ALLDEBRID_CLIENT_ERRORS = (
+    AttributeError,
+    OSError,
+    requests.exceptions.RequestException,
+    RuntimeError,
+    TypeError,
+    ValueError,
+)
+
+# AllDebrid magnet status codes (from API v4.1 documentation).
+_STATUS_DOWNLOADING = frozenset({0, 1, 2, 3})
+_STATUS_READY = 4
+
+# Timeouts and retry limits for API calls.
+_API_TIMEOUT = 30
+_STATUS_TIMEOUT = 15
+_DELAYED_POLL_INTERVAL = 5
+_DELAYED_POLL_MAX_ATTEMPTS = 12
+
+# File extensions recognised as book or audiobook content.
+_BOOK_EXTENSIONS = (
+    ".aac",
+    ".azw",
+    ".azw3",
+    ".cbr",
+    ".cbz",
+    ".djvu",
+    ".doc",
+    ".docx",
+    ".epub",
+    ".fb2",
+    ".flac",
+    ".lit",
+    ".m4a",
+    ".m4b",
+    ".mobi",
+    ".mp3",
+    ".ogg",
+    ".opus",
+    ".pdf",
+    ".rtf",
+    ".txt",
+    ".wma",
+)
+
+
+def _flatten_magnet_files(
+    entries: list[dict[str, Any]],
+    prefix: str = "",
+) -> list[dict[str, Any]]:
+    """Flatten AllDebrid's nested file tree into a list of file dicts.
+
+    AllDebrid returns files with ``"n"`` (name), ``"s"`` (size),
+    ``"l"`` (link), and ``"e"`` (children) keys.  Directories use
+    ``"e"`` to nest their contents.
+
+    Returns:
+        List of ``{"filename": ..., "size": ..., "link": ...}`` dicts.
+
+    """
+    flat: list[dict[str, Any]] = []
+    for entry in entries:
+        name = entry.get("n", "")
+        if "e" in entry:
+            flat.extend(
+                _flatten_magnet_files(entry["e"], prefix=f"{prefix}{name}/"),
+            )
+        elif entry.get("l"):
+            flat.append(
+                {
+                    "filename": f"{prefix}{name}",
+                    "size": entry.get("s", 0),
+                    "link": entry["l"],
+                }
+            )
+    return flat
+
+
+def _raise_runtime_error(message: str) -> NoReturn:
+    raise RuntimeError(message)
+
+
+@dataclass
+class _DownloadState:
+    """Internal mutable state for an in-progress AllDebrid download."""
+
+    magnet_id: str
+    name: str
+    target_dir: Path
+    phase: str = "uploading"
+    error_message: str | None = None
+    progress: float = 0.0
+    download_thread: threading.Thread | None = None
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+@register_client("torrent")
+class AllDebridClient(DownloadClient):
+    """AllDebrid debrid service client.
+
+    Downloads torrent content by uploading magnet links to AllDebrid,
+    waiting for the torrent to complete on their servers, then fetching
+    the resulting files via direct HTTP download from AllDebrid's CDN.
+
+    API documentation: https://docs.alldebrid.com/
+    """
+
+    protocol = "torrent"
+    name = "alldebrid"
+
+    _downloads: ClassVar[dict[str, _DownloadState]] = {}
+    _downloads_lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._api_key = config_text(config.get("ALLDEBRID_API_KEY", ""))
+
+    def _auth_headers(self) -> dict[str, str]:
+        """Return Authorization header dict for API requests."""
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    # ------------------------------------------------------------------
+    # DownloadClient interface
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def is_configured() -> bool:
+        """Return True when AllDebrid is selected and an API key exists."""
+        client = config_text(config.get("PROWLARR_TORRENT_CLIENT", ""))
+        api_key = config_text(config.get("ALLDEBRID_API_KEY", ""))
+        return client == "alldebrid" and bool(api_key)
+
+    def test_connection(self) -> tuple[bool, str]:
+        """Validate the API key and check Premium subscription status."""
+        if not self._api_key:
+            return False, "AllDebrid API Key is required"
+        try:
+            url = f"{_API_BASE}/user"
+            resp = requests.get(
+                url,
+                headers=self._auth_headers(),
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(url),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            if data.get("status") != "success":
+                err = data.get("error", {}).get("message", "API error")
+                return False, f"AllDebrid error: {err}"
+            user = data.get("data", {}).get("user", {})
+            username = user.get("username", "Unknown")
+            if not user.get("isPremium", False):
+                return (
+                    False,
+                    f"AllDebrid user '{username}' does not have a Premium subscription",
+                )
+        except _ALLDEBRID_CLIENT_ERRORS as e:
+            return False, f"Connection failed: {e}"
+        else:
+            return True, f"Connected to AllDebrid as '{username}' (Premium)"
+
+    def add_download(
+        self,
+        url: str,
+        name: str,
+        category: str | None = None,
+        expected_hash: str | None = None,
+        **kwargs: object,
+    ) -> str:
+        """Upload a magnet link to AllDebrid and return the magnet ID."""
+        if not self._api_key:
+            msg = "AllDebrid API key is not configured"
+            raise RuntimeError(msg)
+
+        magnet_link = url
+        if not magnet_link.startswith("magnet:") and expected_hash:
+            magnet_link = f"magnet:?xt=urn:btih:{expected_hash}"
+
+        api_url = f"{_API_BASE}/magnet/upload"
+        try:
+            resp = requests.post(
+                api_url,
+                headers=self._auth_headers(),
+                data={"magnets[]": magnet_link},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(api_url),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            if data.get("status") != "success":
+                code = data.get("error", {}).get("code", "UNKNOWN")
+                msg = f"AllDebrid upload failed: {code}"
+                _raise_runtime_error(msg)
+
+            magnets = data.get("data", {}).get("magnets", [])
+            if not magnets:
+                msg = "No magnet returned from AllDebrid"
+                _raise_runtime_error(msg)
+
+            info = magnets[0]
+            if info.get("error"):
+                code = info["error"].get("code", "UNKNOWN")
+                msg = f"AllDebrid magnet error: {code}"
+                _raise_runtime_error(msg)
+
+            magnet_id = str(info.get("id", ""))
+            if not magnet_id:
+                msg = "No magnet ID returned from AllDebrid"
+                _raise_runtime_error(msg)
+
+            target_dir = TMP_DIR / f"alldebrid_{magnet_id}"
+            target_dir.mkdir(parents=True, exist_ok=True)
+
+            state = _DownloadState(
+                magnet_id=magnet_id,
+                name=name,
+                target_dir=target_dir,
+                phase="waiting_ad",
+            )
+            with self._downloads_lock:
+                self._downloads[magnet_id] = state
+
+            logger.info(
+                "Added torrent to AllDebrid: ID %s (%s)",
+                magnet_id,
+                name,
+            )
+
+        except Exception:
+            logger.exception("Failed to upload magnet to AllDebrid")
+            raise
+
+        else:
+            return magnet_id
+
+    def get_status(self, download_id: str) -> DownloadStatus:
+        """Poll AllDebrid for magnet status and drive the download."""
+        state = self._ensure_state(download_id)
+
+        # Return cached terminal / in-flight states immediately.
+        with state.lock:
+            if state.phase == "error":
+                return DownloadStatus.error(
+                    state.error_message or "AllDebrid error",
+                )
+            if state.phase == "complete":
+                return DownloadStatus(
+                    progress=100.0,
+                    state=DownloadState.COMPLETE,
+                    message="Complete",
+                    complete=True,
+                    file_path=str(state.target_dir),
+                )
+            if state.phase == "downloading_http":
+                return DownloadStatus(
+                    progress=state.progress,
+                    state=DownloadState.DOWNLOADING,
+                    message="Downloading files via HTTP...",
+                    complete=False,
+                    file_path=None,
+                )
+
+        # Ask AllDebrid for the current magnet status.
+        try:
+            status_url = f"{_API_BASE.replace('/v4', '/v4.1')}/magnet/status"
+            resp = requests.post(
+                status_url,
+                headers=self._auth_headers(),
+                data={"id": download_id},
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(status_url),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            if data.get("status") != "success":
+                err = data.get("error", {}).get("message", "Status failed")
+                return DownloadStatus.error(
+                    f"AllDebrid status error: {err}",
+                )
+
+            mag = self._extract_magnet_info(data)
+            return self._handle_magnet_status(mag, state)
+
+        except Exception as e:
+            logger.exception(
+                "Error checking AllDebrid status for %s",
+                download_id,
+            )
+            return DownloadStatus.error(str(e))
+
+    def remove(
+        self,
+        download_id: str,
+        *,
+        delete_files: bool = False,
+    ) -> bool:
+        """Delete the magnet from AllDebrid and clean up local files."""
+        try:
+            url = f"{_API_BASE}/magnet/delete"
+            requests.post(
+                url,
+                headers=self._auth_headers(),
+                data={"id": download_id},
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(url),
+            )
+        except _ALLDEBRID_CLIENT_ERRORS as e:
+            logger.warning("Failed to delete magnet from AllDebrid: %s", e)
+
+        with self._downloads_lock:
+            state = self._downloads.pop(download_id, None)
+
+        if state and state.target_dir.exists():
+            shutil.rmtree(state.target_dir, ignore_errors=True)
+        return True
+
+    def get_download_path(self, download_id: str) -> str | None:
+        """Return the local directory containing downloaded files."""
+        with self._downloads_lock:
+            state = self._downloads.get(download_id)
+        if state and state.phase == "complete":
+            return str(state.target_dir)
+        target_dir = TMP_DIR / f"alldebrid_{download_id}"
+        if target_dir.exists():
+            return str(target_dir)
+        return None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_state(self, download_id: str) -> _DownloadState:
+        """Get or create download state for the given magnet ID."""
+        with self._downloads_lock:
+            state = self._downloads.get(download_id)
+        if state:
+            return state
+
+        target_dir = TMP_DIR / f"alldebrid_{download_id}"
+        state = _DownloadState(
+            magnet_id=download_id,
+            name=f"Download {download_id}",
+            target_dir=target_dir,
+            phase="waiting_ad",
+        )
+        with self._downloads_lock:
+            self._downloads[download_id] = state
+        return state
+
+    @staticmethod
+    def _extract_magnet_info(data: dict[str, Any]) -> dict[str, Any]:
+        """Extract magnet info dict from a status API response."""
+        mag_data = data.get("data", {}).get("magnets", {})
+        if isinstance(mag_data, list) and mag_data:
+            return mag_data[0]
+        if isinstance(mag_data, dict):
+            return mag_data
+        return {}
+
+    def _handle_magnet_status(
+        self,
+        mag: dict[str, Any],
+        state: _DownloadState,
+    ) -> DownloadStatus:
+        """Map AllDebrid magnet status to a DownloadStatus."""
+        status_code = mag.get("statusCode")
+
+        if status_code in _STATUS_DOWNLOADING:
+            size = mag.get("size", 0)
+            downloaded = mag.get("downloaded", 0)
+            pct = (downloaded / size * 100.0) if size > 0 else 0.0
+            return DownloadStatus(
+                progress=pct * 0.5,
+                state=DownloadState.DOWNLOADING,
+                message=(f"AllDebrid downloading torrent ({mag.get('filename', state.name)})"),
+                complete=False,
+                file_path=None,
+                download_speed=mag.get("downloadSpeed", 0),
+            )
+
+        if status_code == _STATUS_READY or mag.get("ready", False):
+            self._maybe_start_download_thread(state)
+            return DownloadStatus(
+                progress=50.0,
+                state=DownloadState.DOWNLOADING,
+                message="AllDebrid ready, retrieving files...",
+                complete=False,
+                file_path=None,
+            )
+
+        # Terminal error from AllDebrid.
+        error_txt = mag.get("error", {}).get("message") or f"AllDebrid status code {status_code}"
+        with state.lock:
+            state.phase = "error"
+            state.error_message = error_txt
+        return DownloadStatus.error(error_txt)
+
+    def _maybe_start_download_thread(self, state: _DownloadState) -> None:
+        """Spawn a background thread to unlock and download files."""
+        with state.lock:
+            already_running = state.phase in (
+                "unlocking",
+                "downloading_http",
+                "complete",
+            )
+            thread_alive = state.download_thread is not None and state.download_thread.is_alive()
+            if already_running or thread_alive:
+                return
+            state.phase = "unlocking"
+            t = threading.Thread(
+                target=self._process_and_download,
+                args=(state,),
+                daemon=True,
+            )
+            state.download_thread = t
+            t.start()
+
+    # ------------------------------------------------------------------
+    # Link unlocking
+    # ------------------------------------------------------------------
+
+    def _unlock_file_link(self, link: str) -> str:
+        """Resolve an AllDebrid file link to a direct CDN download URL.
+
+        AllDebrid's ``/v4/magnet/files`` endpoint returns virtual links
+        (``alldebrid.com/f/...``) that must be converted to direct CDN
+        URLs via ``/v4/link/unlock``.
+
+        Strategy:
+            1. If the link is already a CDN URL (``/dl/``), return it.
+            2. ``POST /v4/link/unlock`` with Bearer auth (primary).
+            3. ``GET /v4/link/unlock`` with query parameters (fallback).
+            4. Append ``apikey=`` to ``alldebrid.com/f/`` links
+               (last-resort fallback for ghost-cached torrents).
+
+        """
+        # 1. Already a direct CDN link.
+        if "/dl/" in link:
+            return link
+
+        headers = self._auth_headers()
+        unlock_url = f"{_API_BASE}/link/unlock"
+        err_msg = "Unknown unlock error"
+
+        # 2. POST unlock (primary method).
+        try:
+            resp = requests.post(
+                unlock_url,
+                headers=headers,
+                data={"link": link},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(unlock_url),
+            )
+            if resp.status_code == 200:
+                body = resp.json()
+                if body.get("status") == "success":
+                    direct = self._resolve_unlock_data(
+                        body.get("data", {}),
+                        headers,
+                    )
+                    if direct:
+                        return direct
+                err_msg = body.get("error", {}).get(
+                    "message",
+                    "Unlock failed",
+                )
+        except _ALLDEBRID_CLIENT_ERRORS as e:
+            logger.debug("POST unlock exception: %s", e)
+
+        # 3. GET unlock fallback with URL-encoded link.
+        try:
+            encoded = quote(link, safe="")
+            get_url = (
+                f"{_API_BASE}/link/unlock?agent={_AGENT}&apikey={self._api_key}&link={encoded}"
+            )
+            resp = requests.get(
+                get_url,
+                headers=headers,
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(get_url),
+            )
+            if resp.status_code == 200:
+                body = resp.json()
+                if body.get("status") == "success":
+                    direct = body.get("data", {}).get("link")
+                    if direct:
+                        return direct
+                err_msg = body.get("error", {}).get("message", err_msg)
+        except _ALLDEBRID_CLIENT_ERRORS as e:
+            logger.debug("GET unlock exception: %s", e)
+
+        # 4. Last-resort: append apikey to alldebrid.com/f/ links.
+        if "alldebrid.com/f/" in link:
+            logger.info(
+                "Using apikey fallback for AllDebrid file link: %s",
+                link,
+            )
+            if "apikey=" not in link:
+                sep = "&" if "?" in link else "?"
+                return f"{link}{sep}apikey={self._api_key}"
+            return link
+
+        logger.error(
+            "AllDebrid unlock failed for '%s': %s",
+            link,
+            err_msg,
+        )
+        msg = f"AllDebrid unlock failed: {err_msg}"
+        raise RuntimeError(msg)
+
+    def _resolve_unlock_data(
+        self,
+        data: dict[str, Any],
+        headers: dict[str, str],
+    ) -> str | None:
+        """Extract the direct link from unlock response data.
+
+        Handles the *delayed link* flow where AllDebrid returns a
+        ``delayed`` ID instead of an immediate download link.
+        """
+        # Delayed link: poll until the CDN file is ready.
+        if "delayed" in data:
+            delayed_id = data["delayed"]
+            logger.info(
+                "AllDebrid link delayed (ID %s), polling...",
+                delayed_id,
+            )
+            delayed_url = f"{_API_BASE}/link/delayed"
+            for _ in range(_DELAYED_POLL_MAX_ATTEMPTS):
+                time.sleep(_DELAYED_POLL_INTERVAL)
+                try:
+                    resp = requests.post(
+                        delayed_url,
+                        headers=headers,
+                        data={"id": delayed_id},
+                        timeout=_STATUS_TIMEOUT,
+                        verify=get_ssl_verify(delayed_url),
+                    )
+                    if resp.status_code != 200:
+                        continue
+                    body = resp.json()
+                    d = body.get("data", {})
+                    if body.get("status") == "success" and d.get("status") == 2 and d.get("link"):
+                        return d["link"]
+                except _ALLDEBRID_CLIENT_ERRORS as e:
+                    logger.debug("Delayed poll exception: %s", e)
+
+        return data.get("link")
+
+    # ------------------------------------------------------------------
+    # File download pipeline
+    # ------------------------------------------------------------------
+
+    def _process_and_download(self, state: _DownloadState) -> None:
+        """Fetch the file list, unlock links, and download via HTTP.
+
+        Runs in a background thread spawned by ``_maybe_start_download_thread``.
+        """
+        try:
+            files = self._fetch_file_list(state.magnet_id)
+            relevant = [f for f in files if f["filename"].lower().endswith(_BOOK_EXTENSIONS)]
+            if not relevant:
+                relevant = files
+
+            with state.lock:
+                state.phase = "downloading_http"
+
+            total = len(relevant)
+            for idx, file_info in enumerate(relevant):
+                direct_link = self._unlock_file_link(file_info["link"])
+
+                rel_path = Path(file_info["filename"])
+                dest = state.target_dir / rel_path
+                dest.parent.mkdir(parents=True, exist_ok=True)
+
+                logger.info(
+                    "Downloading AllDebrid file %d/%d: %s",
+                    idx + 1,
+                    total,
+                    rel_path,
+                )
+
+                buf = download_url(
+                    direct_link,
+                    referer="https://alldebrid.com/",
+                )
+                if not buf:
+                    msg = f"Failed to download from {direct_link}"
+                    _raise_runtime_error(msg)
+
+                with dest.open("wb") as fh:
+                    fh.write(buf.getvalue())
+
+                with state.lock:
+                    state.progress = 50.0 + (idx + 1) / total * 50.0
+
+            with state.lock:
+                state.phase = "complete"
+                state.progress = 100.0
+
+            logger.info(
+                "AllDebrid download complete for ID %s at %s",
+                state.magnet_id,
+                state.target_dir,
+            )
+
+        except Exception:
+            logger.exception(
+                "Error in AllDebrid download for ID %s",
+                state.magnet_id,
+            )
+            with state.lock:
+                state.phase = "error"
+                state.error_message = str(
+                    state.error_message or "Download failed",
+                )
+
+    def _fetch_file_list(
+        self,
+        magnet_id: str,
+    ) -> list[dict[str, Any]]:
+        """Retrieve and flatten the file tree for a magnet."""
+        url = f"{_API_BASE}/magnet/files"
+        resp = requests.post(
+            url,
+            headers=self._auth_headers(),
+            data={"id[]": magnet_id},
+            timeout=_API_TIMEOUT,
+            verify=get_ssl_verify(url),
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if data.get("status") != "success":
+            msg = f"Failed to list magnet files: {data.get('error')}"
+            raise RuntimeError(msg)
+
+        magnets = data.get("data", {}).get("magnets", [])
+        if not magnets:
+            msg = "No magnet files returned"
+            raise RuntimeError(msg)
+
+        files = _flatten_magnet_files(magnets[0].get("files", []))
+        if not files:
+            msg = "No files found in torrent"
+            raise RuntimeError(msg)
+        return files
@@ -220,6 +220,17 @@ class ExternalClientHandler(DownloadHandler, ABC):
        configured = config.get(COMPLETED_PATH_TIMEOUT_SETTING, fallback)
        return _coerce_completed_path_timeout_seconds(configured, fallback)

+    def _refresh_download_request_after_add_failure(
+        self,
+        *,
+        task: DownloadTask,
+        request: DownloadRequest,
+        error: Exception,
+        status_callback: Callable[[str, str | None], None],
+    ) -> DownloadRequest | None:
+        """Give source handlers one chance to refresh stale resolved download data."""
+        return None
+
    def _get_category_for_task(self, client: DownloadClient, task: DownloadTask) -> str | None:
        """Get audiobook category if configured and applicable, else None for default."""
        if not is_audiobook(task.content_type):
@@ -273,17 +284,47 @@ class ExternalClientHandler(DownloadHandler, ABC):
                )

        elif protocol == "torrent":
-            if config.get("PROWLARR_TORRENT_ACTION", "keep") != "remove":
+            torrent_action = config.get("PROWLARR_TORRENT_ACTION", "keep")
+            if torrent_action == "remove":
+                try:
+                    client.remove(download_id, delete_files=False)
+                except _CLIENT_CLEANUP_ERRORS as e:
+                    logger.warning(
+                        "Failed to remove torrent %s from %s: %s",
+                        download_id,
+                        getattr(client, "name", "client"),
+                        e,
+                    )
                return
+
+            if torrent_action != "change_category":
+                return
+
+            post_import_category = normalize_optional_text(
+                config.get("PROWLARR_TORRENT_POST_IMPORT_CATEGORY", "")
+            )
+            if post_import_category is None:
+                return
+
            try:
-                client.remove(download_id, delete_files=False)
+                category_updated = client.set_category(download_id, post_import_category)
            except _CLIENT_CLEANUP_ERRORS as e:
                logger.warning(
-                    "Failed to remove torrent %s from %s: %s",
+                    "Failed to set post-import category for torrent %s in %s: %s",
                    download_id,
                    getattr(client, "name", "client"),
                    e,
                )
+                return
+
+            if not category_updated:
+                # Clients that cannot label torrents (debrid services) return False here,
+                # and the ones that can already log the specific failure themselves.
+                logger.debug(
+                    "Post-import category not applied to torrent %s in %s",
+                    download_id,
+                    getattr(client, "name", "client"),
+                )

    def _remove_usenet_download(
        self,
@@ -791,20 +832,38 @@ class ExternalClientHandler(DownloadHandler, ABC):
                status_callback("downloading", "Resuming existing download")
            else:
                # No existing download - add new
-                status_callback("resolving", f"Sending to {client.name}")
-                try:
-                    download_id = client.add_download(
-                        url=request.url,
-                        name=request.release_name,
-                        category=category,
-                        expected_hash=request.expected_hash,
-                        seeding_time_limit=request.seeding_time_limit,
-                        ratio_limit=request.ratio_limit,
-                    )
-                except Exception as e:
-                    logger.exception("Failed to add to %s", client.name)
-                    status_callback("error", f"Failed to add to {client.name}: {e}")
-                    return None
+                refresh_attempted = False
+                while True:
+                    status_callback("resolving", f"Sending to {client.name}")
+                    try:
+                        download_id = client.add_download(
+                            url=request.url,
+                            name=request.release_name,
+                            category=category,
+                            expected_hash=request.expected_hash,
+                            seeding_time_limit=request.seeding_time_limit,
+                            ratio_limit=request.ratio_limit,
+                        )
+                    except Exception as e:
+                        if not refresh_attempted:
+                            refresh_attempted = True
+                            refreshed_request = self._refresh_download_request_after_add_failure(
+                                task=task,
+                                request=request,
+                                error=e,
+                                status_callback=status_callback,
+                            )
+                            if (
+                                refreshed_request is not None
+                                and refreshed_request.protocol == request.protocol
+                            ):
+                                request = refreshed_request
+                                continue
+
+                        logger.exception("Failed to add to %s", client.name)
+                        status_callback("error", f"Failed to add to {client.name}: {e}")
+                        return None
+                    break

                logger.info(
                    "Added to %s: %s for '%s'", client.name, download_id, request.release_name
@@ -227,10 +227,10 @@ class DelugeClient(DownloadClient):

        return self._rpc_call("daemon.info")

-    def _try_set_label(self, torrent_id: str, label: str) -> None:
+    def _try_set_label(self, torrent_id: str, label: str) -> bool:
        """Best-effort label assignment (requires Deluge Label plugin)."""
        if not label:
-            return
+            return False

        try:
            # label.add will error if the plugin is unavailable or the label exists.
@@ -240,6 +240,9 @@ class DelugeClient(DownloadClient):
            self._rpc_call("label.set_torrent", torrent_id, label)
        except _DELUGE_CLIENT_ERRORS as e:
            logger.debug("Could not set Deluge label '%s' for %s: %s", label, torrent_id, e)
+            return False
+        else:
+            return True

    @staticmethod
    def is_configured() -> bool:
@@ -277,7 +280,10 @@ class DelugeClient(DownloadClient):

            torrent_info = extract_torrent_info(url, expected_hash=expected_hash)
            if not torrent_info.is_magnet and not torrent_info.torrent_data:
-                _raise_runtime_error("Failed to fetch torrent file")
+                message = "Failed to fetch torrent file"
+                if torrent_info.fetch_error:
+                    message = f"{message}: {torrent_info.fetch_error}"
+                _raise_runtime_error(message)

            options: dict[str, Any] = {}
            if self._download_dir:
@@ -419,6 +425,15 @@ class DelugeClient(DownloadClient):
        else:
            return False

+    def set_category(self, download_id: str, category: str) -> bool:
+        """Assign a label to a torrent using Deluge's Label plugin."""
+        try:
+            self._ensure_connected()
+            return self._try_set_label(download_id, category)
+        except _DELUGE_CLIENT_ERRORS as e:
+            self._log_error("set_category", e)
+            return False
+
    def get_download_path(self, download_id: str) -> str | None:
        """Return the resolved download path for a Deluge torrent."""
        try:
@@ -44,6 +44,7 @@ _HASH_LENGTH_40 = 40
 _HASH_LENGTH_ED2K = 32
 _HTTP_STATUS_FORBIDDEN = HTTPStatus.FORBIDDEN
 _HTTP_STATUS_NOT_FOUND = HTTPStatus.NOT_FOUND
+_METADATA_DOWNLOAD_STATES = {"forcedMetaDL", "metaDL"}
 _ONE_WEEK_IN_SECONDS = 604800


@@ -94,6 +95,25 @@ def _hashes_match(hash1: str, hash2: str) -> bool:
    return False


+def _torrent_matches_download_id(torrent: object, download_id: str) -> bool:
+    """Match an ID against every identity qBittorrent exposes.
+
+    For hybrid torrents, qBittorrent's primary `hash` can change from the v1
+    hash to the truncated v2 hash after metadata resolution. The full
+    `infohash_v1` and `infohash_v2` fields preserve the torrent's identities.
+    """
+    identifiers = (
+        getattr(torrent, "hash", None),
+        getattr(torrent, "infohash_v1", None),
+        getattr(torrent, "infohash_v2", None),
+    )
+
+    return any(
+        isinstance(identifier, str) and identifier and _hashes_match(identifier, download_id)
+        for identifier in identifiers
+    )
+
+
 def _raise_runtime_error(message: str) -> NoReturn:
    raise RuntimeError(message)

@@ -166,63 +186,6 @@ def _build_qbittorrent_child_path(base_path: object, child_path: object) -> str
 class QBittorrentClient(DownloadClient):
    """qBittorrent download client."""

-    def _is_torrent_loaded(self, torrent_hash: str) -> tuple[bool, str | None]:
-        """Check whether qBittorrent has registered a torrent yet.
-
-        Uses `/api/v2/torrents/properties?hash=<hash>`.
-
-        Returns:
-            (loaded, error_message)
-
-        Notes:
-            A false result with no error means "not loaded yet".
-
-        """
-        url = f"{self._base_url}/api/v2/torrents/properties"
-        params = {"hash": torrent_hash}
-
-        try:
-            self._client.auth_log_in()
-            response = self._client._session.get(url, params=params, timeout=10)
-
-            # Re-authenticate and retry once on 403
-            if response.status_code == _HTTP_STATUS_FORBIDDEN:
-                logger.debug(
-                    "qBittorrent returned 403 for properties; re-authenticating and retrying"
-                )
-                self._client.auth_log_in()
-                response = self._client._session.get(url, params=params, timeout=10)
-
-            if response.status_code == _HTTP_STATUS_FORBIDDEN:
-                return False, "qBittorrent authentication failed (HTTP 403)"
-
-            # qBittorrent returns 404/409-ish responses depending on version when missing.
-            if response.status_code == _HTTP_STATUS_NOT_FOUND:
-                return False, None
-
-            response.raise_for_status()
-        except requests.exceptions.HTTPError as e:
-            status = getattr(getattr(e, "response", None), "status_code", None)
-            if status == _HTTP_STATUS_NOT_FOUND:
-                return False, None
-            if status:
-                return False, f"qBittorrent API request failed (HTTP {status})"
-            return False, "qBittorrent API request failed"
-        except requests.exceptions.ConnectionError:
-            return False, f"Cannot connect to qBittorrent at {self._base_url}"
-        except requests.exceptions.Timeout:
-            return False, f"qBittorrent request timed out at {self._base_url}"
-        except requests.exceptions.InvalidSchema:
-            return (
-                False,
-                "qBittorrent URL is invalid (missing http:// or https://). "
-                f"Configured: {self._base_url}",
-            )
-        except _QBITTORRENT_CLIENT_ERRORS as e:
-            return False, f"qBittorrent API error: {type(e).__name__}: {e}"
-        else:
-            return True, None
-
    protocol = "torrent"
    name = "qbittorrent"

@@ -244,6 +207,7 @@ class QBittorrentClient(DownloadClient):

        username = config_text(config.get("QBITTORRENT_USERNAME", ""))
        password = config_text(config.get("QBITTORRENT_PASSWORD", ""))
+        self._api_key = config_text(config.get("QBITTORRENT_API_KEY", ""))

        # qbittorrent-api accepts either a full URL or host:port; prefer the normalized URL
        # for consistency.
@@ -251,44 +215,40 @@ class QBittorrentClient(DownloadClient):
            host=self._base_url,
            username=username,
            password=password,
+            api_key=self._api_key or None,
            VERIFY_WEBUI_CERTIFICATE=get_ssl_verify(self._base_url),
        )
        self._category = config_text(config.get("QBITTORRENT_CATEGORY", "books"))
        self._download_dir = config_text(config.get("QBITTORRENT_DOWNLOAD_DIR", ""))
        self._tags = _normalize_tags(config.get("QBITTORRENT_TAG", []))

-    def _get_torrents_info(
-        self, torrent_hash: str | None = None, category: str | None = None
-    ) -> tuple[list[SimpleNamespace], str | None]:
-        """Get torrent info using GET.
+    @property
+    def _can_reauthenticate(self) -> bool:
+        """Whether a 403 is worth retrying; a bearer token cannot be refreshed like a session."""
+        return not self._api_key

-        Behaviors:
-        - Retry once on HTTP 403 by re-authenticating.
-        - Keep "API/auth/connect" errors distinct from "torrent missing".
-        - If a hash-specific query returns empty, fall back to listing by category
-          and matching locally.
-        - Without a hash, `category` narrows the listing to that category.
-
-        Returns:
-            (torrents, error_message)
+    def _ensure_authenticated(self) -> None:
+        """Authenticate the underlying HTTP session before it is used directly.

+        API keys (qBittorrent 5.2.0+) are sent as a bearer header on every request and
+        have no login endpoint, so there is no session to establish up front.
        """
+        if self._api_key:
+            return
+        self._client.auth_log_in()
+
+    def _request_torrent_info_records(
+        self, params: dict[str, str]
+    ) -> tuple[list[SimpleNamespace], str | None]:
+        """Request torrent info records from qBittorrent."""
        url = f"{self._base_url}/api/v2/torrents/info"
-
-        def do_request(params: dict[str, str]) -> requests.Response:
-            # Ensure session is authenticated before using it directly
-            self._client.auth_log_in()
-            return self._client._session.get(url, params=params, timeout=10)
-
-        def parse_response(
-            response: requests.Response,
-            *,
-            request_params: dict[str, str],
-        ) -> tuple[list[SimpleNamespace], str | None]:
-            if response.status_code == _HTTP_STATUS_FORBIDDEN:
+        try:
+            self._ensure_authenticated()
+            response = self._client._session.get(url, params=params, timeout=10)
+            if response.status_code == _HTTP_STATUS_FORBIDDEN and self._can_reauthenticate:
                logger.debug("qBittorrent returned 403; re-authenticating and retrying")
-                self._client.auth_log_in()
-                response = self._client._session.get(url, params=request_params, timeout=10)
+                self._ensure_authenticated()
+                response = self._client._session.get(url, params=params, timeout=10)

            if response.status_code == _HTTP_STATUS_FORBIDDEN:
                logger.warning("qBittorrent authentication failed (HTTP 403)")
@@ -297,43 +257,6 @@ class QBittorrentClient(DownloadClient):
            response.raise_for_status()
            torrents = response.json()
            return [SimpleNamespace(**t) for t in torrents], None
-
-        try:
-            primary_params: dict[str, str] = {}
-            if torrent_hash:
-                primary_params["hashes"] = torrent_hash
-            elif category:
-                primary_params["category"] = category
-
-            response = do_request(primary_params)
-            torrents, error = parse_response(response, request_params=primary_params)
-            if error:
-                return [], error
-
-            if torrent_hash and not torrents:
-                # Fallback 1: list by configured category
-                category_params: dict[str, str] = {}
-                if self._category:
-                    category_params["category"] = self._category
-
-                category_response = do_request(category_params)
-                category_torrents, category_error = parse_response(
-                    category_response, request_params=category_params
-                )
-                if category_error:
-                    return [], category_error
-
-                if category_torrents:
-                    return category_torrents, None
-
-                # Fallback 2: list everything (handles per-task categories like audiobooks)
-                all_response = do_request({})
-                all_torrents, all_error = parse_response(all_response, request_params={})
-                if all_error:
-                    return [], all_error
-
-                return all_torrents, None
-
        except requests.exceptions.HTTPError as e:
            status = getattr(getattr(e, "response", None), "status_code", None)
            if status:
@@ -358,12 +281,66 @@ class QBittorrentClient(DownloadClient):
        except _QBITTORRENT_CLIENT_ERRORS as e:
            logger.debug("Failed to get torrents info: %s", e)
            return [], f"qBittorrent API error: {type(e).__name__}: {e}"
-        else:
-            return torrents, None
+
+    def _get_torrent_info(self, download_id: str) -> tuple[SimpleNamespace | None, str | None]:
+        """Get one torrent by its current qBittorrent hash."""
+        torrents, error = self._request_torrent_info_records({"hashes": download_id})
+        if error or not torrents:
+            return None, error
+        return (
+            next(
+                (
+                    torrent
+                    for torrent in torrents
+                    if isinstance(getattr(torrent, "hash", None), str)
+                    and _hashes_match(torrent.hash, download_id)
+                ),
+                None,
+            ),
+            None,
+        )
+
+    def _list_torrents_by_category(
+        self, category: str | None
+    ) -> tuple[list[SimpleNamespace], str | None]:
+        """List torrent records in a category, or all records when unset."""
+        params = {"category": category} if category else {}
+        return self._request_torrent_info_records(params)
+
+    def _resolve_torrent(
+        self, download_id: str, category: str | None = None
+    ) -> tuple[SimpleNamespace | None, str | None]:
+        """Resolve any known torrent identity to its current qBittorrent record."""
+        torrent, error = self._get_torrent_info(download_id)
+        if error or torrent:
+            return torrent, error
+
+        categories = [candidate for candidate in (category, self._category) if candidate]
+        for candidate in dict.fromkeys(categories):
+            torrents, error = self._list_torrents_by_category(candidate)
+            if error:
+                return None, error
+            torrent = next(
+                (item for item in torrents if _torrent_matches_download_id(item, download_id)),
+                None,
+            )
+            if torrent:
+                return torrent, None
+
+        torrents, error = self._list_torrents_by_category(None)
+        if error:
+            return None, error
+        return (
+            next(
+                (item for item in torrents if _torrent_matches_download_id(item, download_id)),
+                None,
+            ),
+            None,
+        )

    def _list_category_hashes(self, category: str | None) -> set[str] | None:
        """Snapshot the hashes qBittorrent currently reports for a category."""
-        torrents, error = self._get_torrents_info(category=category)
+        torrents, error = self._list_torrents_by_category(category)
        if error:
            logger.debug("Could not snapshot qBittorrent torrents: %s", error)
            return None
@@ -381,7 +358,7 @@ class QBittorrentClient(DownloadClient):
        torrent matching the requested rename can identify the new arrival.
        """
        for _ in range(20):
-            torrents, error = self._get_torrents_info(category=category)
+            torrents, error = self._list_torrents_by_category(category)
            if error:
                logger.debug("qBittorrent hash discovery: %s", error)
            else:
@@ -409,7 +386,7 @@ class QBittorrentClient(DownloadClient):
    def test_connection(self) -> tuple[bool, str]:
        """Test connection to qBittorrent."""
        try:
-            self._client.auth_log_in()
+            self._ensure_authenticated()
            api_version = self._client.app.web_api_version
        except _QBITTORRENT_CLIENT_ERRORS as e:
            return False, f"Connection failed: {e!s}"
@@ -513,23 +490,27 @@ class QBittorrentClient(DownloadClient):
                # watching for the new torrent to appear.
                expected_hash = self._discover_added_torrent_hash(name, category, known_hashes)
            if not expected_hash:
-                _raise_runtime_error("Could not determine torrent hash from URL")
+                message = "Could not determine torrent hash from URL"
+                if torrent_info.fetch_error:
+                    message = f"{message} (torrent file fetch failed: {torrent_info.fetch_error})"
+                _raise_runtime_error(message)

-            # Some qBittorrent-compatible clients return HTTP 200 with an empty body
-            # instead of qBittorrent's literal "Ok." response. Prefer verifying that
-            # the torrent becomes visible over trusting the response body alone.
-            for _ in range(10):
-                loaded, error = self._is_torrent_loaded(expected_hash)
+            # Wait until qBittorrent has resolved magnet metadata so the returned
+            # hash is its stable primary torrent ID, which may differ from the v1 hash.
+            for _ in range(20):
+                torrent, error = self._resolve_torrent(expected_hash, category)
                if error:
                    logger.debug("qBittorrent add_download: %s", error)
-                if loaded:
-                    logger.info("Added torrent: %s", expected_hash)
-                    return expected_hash.lower()
+                elif torrent and getattr(torrent, "state", None) not in _METADATA_DOWNLOAD_STATES:
+                    torrent_hash = getattr(torrent, "hash", None)
+                    if isinstance(torrent_hash, str) and torrent_hash:
+                        logger.info("Added torrent: %s", torrent_hash)
+                        return torrent_hash.lower()
                time.sleep(0.5)

-            logger.warning(
-                "Torrent add was not confirmed within the visibility grace period (response=%s), returning expected hash",
-                result_text,
+            _raise_runtime_error(
+                "Torrent metadata resolution was not confirmed within the visibility grace period "
+                f"(response={result_text})"
            )
        except _QBITTORRENT_CLIENT_ERRORS:
            logger.exception("qBittorrent add failed")
@@ -548,19 +529,9 @@ class QBittorrentClient(DownloadClient):

        """
        try:
-            torrents, error = self._get_torrents_info(download_id)
+            torrent, error = self._get_torrent_info(download_id)
            if error:
                return DownloadStatus.error(error)
-
-            torrent = next(
-                (
-                    t
-                    for t in torrents
-                    if isinstance(getattr(t, "hash", None), str)
-                    and _hashes_match(t.hash, download_id)
-                ),
-                None,
-            )
            if not torrent:
                return DownloadStatus.error("Torrent not found in qBittorrent")

@@ -654,6 +625,26 @@ class QBittorrentClient(DownloadClient):
        else:
            return True

+    def set_category(self, download_id: str, category: str) -> bool:
+        """Assign a category to a torrent in qBittorrent."""
+        try:
+            try:
+                self._client.torrents_create_category(name=category)
+            except _QBITTORRENT_CLIENT_ERRORS as e:
+                if "Conflict" not in type(e).__name__ and "409" not in str(e):
+                    logger.debug("Could not create category '%s': %s", category, e)
+
+            self._client.torrents_set_category(
+                torrent_hashes=download_id,
+                category=category,
+            )
+            logger.info("Set qBittorrent category for %s to '%s'", download_id, category)
+        except _QBITTORRENT_CLIENT_ERRORS as e:
+            self._log_error("set_category", e)
+            return False
+        else:
+            return True
+
    def get_download_path(self, download_id: str) -> str | None:
        """Get the path where torrent files are located.

@@ -666,20 +657,10 @@ class QBittorrentClient(DownloadClient):
        - join `save_path` with the torrent's top-level directory
        """
        try:
-            torrents, error = self._get_torrents_info(download_id)
+            torrent, error = self._get_torrent_info(download_id)
            if error:
                logger.debug("qBittorrent get_download_path: %s", error)
                return None
-
-            torrent = next(
-                (
-                    t
-                    for t in torrents
-                    if isinstance(getattr(t, "hash", None), str)
-                    and _hashes_match(t.hash, download_id)
-                ),
-                None,
-            )
            if not torrent:
                return None

@@ -725,11 +706,11 @@ class QBittorrentClient(DownloadClient):
        import os

        def get_with_auth(url: str, params: dict[str, str]) -> requests.Response:
-            self._client.auth_log_in()
+            self._ensure_authenticated()
            resp = self._client._session.get(url, params=params, timeout=10)
-            if resp.status_code == _HTTP_STATUS_FORBIDDEN:
+            if resp.status_code == _HTTP_STATUS_FORBIDDEN and self._can_reauthenticate:
                logger.debug("qBittorrent returned 403; re-authenticating and retrying")
-                self._client.auth_log_in()
+                self._ensure_authenticated()
                resp = self._client._session.get(url, params=params, timeout=10)
            return resp

@@ -786,23 +767,19 @@ class QBittorrentClient(DownloadClient):
            if not torrent_info.info_hash:
                return None

-            torrents, error = self._get_torrents_info(torrent_info.info_hash)
-            if error:
-                logger.debug("qBittorrent find_existing: %s", error)
-                return None
-
-            torrent = next(
-                (
-                    t
-                    for t in torrents
-                    if isinstance(getattr(t, "hash", None), str)
-                    and _hashes_match(t.hash, torrent_info.info_hash)
-                ),
-                None,
-            )
-            if torrent and isinstance(getattr(torrent, "hash", None), str):
-                torrent_hash = torrent.hash
-                return (torrent_hash.lower(), self.get_status(torrent_hash.lower()))
+            for _ in range(20):
+                torrent, error = self._resolve_torrent(torrent_info.info_hash, category)
+                if error:
+                    logger.debug("qBittorrent find_existing: %s", error)
+                    return None
+                if not torrent:
+                    return None
+                if getattr(torrent, "state", None) not in _METADATA_DOWNLOAD_STATES:
+                    torrent_hash = getattr(torrent, "hash", None)
+                    if isinstance(torrent_hash, str) and torrent_hash:
+                        torrent_hash = torrent_hash.lower()
+                        return (torrent_hash, self.get_status(torrent_hash))
+                time.sleep(0.5)
        except _QBITTORRENT_CLIENT_ERRORS as e:
            logger.debug("Error checking for existing torrent: %s", e)
            return None
@@ -0,0 +1,517 @@
+"""Real-Debrid debrid service client for Shelfmark.
+
+Routes magnet links through the Real-Debrid REST API (v1.0) to download
+torrent content via Real-Debrid's CDN infrastructure.
+"""
+
+from __future__ import annotations
+
+import shutil
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar, NoReturn
+
+import requests
+
+from shelfmark.config.env import TMP_DIR
+from shelfmark.core.config import config
+from shelfmark.core.logger import setup_logger
+from shelfmark.download.clients import (
+    DownloadClient,
+    DownloadState,
+    DownloadStatus,
+    register_client,
+)
+from shelfmark.download.clients._coercion import config_text
+from shelfmark.download.http import download_url
+from shelfmark.download.network import get_ssl_verify
+
+logger = setup_logger(__name__)
+
+_API_BASE = "https://api.real-debrid.com/rest/1.0"
+
+_REALDEBRID_CLIENT_ERRORS = (
+    AttributeError,
+    OSError,
+    requests.exceptions.RequestException,
+    RuntimeError,
+    TypeError,
+    ValueError,
+)
+
+# Real-Debrid torrent status values.
+_STATUS_DOWNLOADING = frozenset(
+    {
+        "magnet_conversion",
+        "waiting_files_selection",
+        "downloading",
+        "compressing",
+        "uploading",
+    }
+)
+_STATUS_READY = "downloaded"
+_STATUS_ERROR = frozenset({"error", "virus", "dead"})
+
+# Timeouts for API calls.
+_API_TIMEOUT = 30
+_STATUS_TIMEOUT = 15
+
+# File extensions recognised as book or audiobook content.
+_BOOK_EXTENSIONS = (
+    ".aac",
+    ".azw",
+    ".azw3",
+    ".cbr",
+    ".cbz",
+    ".djvu",
+    ".doc",
+    ".docx",
+    ".epub",
+    ".fb2",
+    ".flac",
+    ".lit",
+    ".m4a",
+    ".m4b",
+    ".mobi",
+    ".mp3",
+    ".ogg",
+    ".opus",
+    ".pdf",
+    ".rtf",
+    ".txt",
+    ".wma",
+)
+
+
+def _raise_runtime_error(message: str) -> NoReturn:
+    raise RuntimeError(message)
+
+
+@dataclass
+class _DownloadState:
+    """Internal mutable state for an in-progress Real-Debrid download."""
+
+    torrent_id: str
+    name: str
+    target_dir: Path
+    phase: str = "uploading"
+    error_message: str | None = None
+    progress: float = 0.0
+    download_thread: threading.Thread | None = None
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+
+@register_client("torrent")
+class RealDebridClient(DownloadClient):
+    """Real-Debrid debrid service client.
+
+    Downloads torrent content by uploading magnet links to Real-Debrid,
+    selecting all files for download on their servers, then unrestricting
+    and fetching the resulting files via direct HTTP download from
+    Real-Debrid's CDN.
+
+    API documentation: https://api.real-debrid.com/
+    """
+
+    protocol = "torrent"
+    name = "realdebrid"
+
+    _downloads: ClassVar[dict[str, _DownloadState]] = {}
+    _downloads_lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._api_key = config_text(config.get("REALDEBRID_API_KEY", ""))
+
+    def _auth_headers(self) -> dict[str, str]:
+        """Return Authorization header dict for API requests."""
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    # ------------------------------------------------------------------
+    # DownloadClient interface
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def is_configured() -> bool:
+        """Return True when Real-Debrid is selected and an API key exists."""
+        client = config_text(config.get("PROWLARR_TORRENT_CLIENT", ""))
+        api_key = config_text(config.get("REALDEBRID_API_KEY", ""))
+        return client == "realdebrid" and bool(api_key)
+
+    def test_connection(self) -> tuple[bool, str]:
+        """Validate the API key and check Premium subscription status."""
+        if not self._api_key:
+            return False, "Real-Debrid API Key is required"
+        try:
+            url = f"{_API_BASE}/user"
+            resp = requests.get(
+                url,
+                headers=self._auth_headers(),
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(url),
+            )
+            resp.raise_for_status()
+            user = resp.json()
+            username = user.get("username", "Unknown")
+            account_type = user.get("type", "free")
+            if account_type != "premium":
+                return (
+                    False,
+                    f"Real-Debrid user '{username}' does not have "
+                    f"a Premium subscription (type: {account_type})",
+                )
+        except _REALDEBRID_CLIENT_ERRORS as e:
+            return False, f"Connection failed: {e}"
+        else:
+            return True, f"Connected to Real-Debrid as '{username}' (Premium)"
+
+    def add_download(
+        self,
+        url: str,
+        name: str,
+        category: str | None = None,
+        expected_hash: str | None = None,
+        **kwargs: object,
+    ) -> str:
+        """Upload a magnet link to Real-Debrid and select all files."""
+        if not self._api_key:
+            msg = "Real-Debrid API key is not configured"
+            raise RuntimeError(msg)
+
+        magnet_link = url
+        if not magnet_link.startswith("magnet:") and expected_hash:
+            magnet_link = f"magnet:?xt=urn:btih:{expected_hash}"
+
+        add_url = f"{_API_BASE}/torrents/addMagnet"
+        try:
+            resp = requests.post(
+                add_url,
+                headers=self._auth_headers(),
+                data={"magnet": magnet_link},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(add_url),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+
+            torrent_id = str(data.get("id", ""))
+            if not torrent_id:
+                msg = "No torrent ID returned from Real-Debrid"
+                _raise_runtime_error(msg)
+
+            # Select all files so Real-Debrid starts downloading the torrent
+            select_url = f"{_API_BASE}/torrents/selectFiles/{torrent_id}"
+            sel_resp = requests.post(
+                select_url,
+                headers=self._auth_headers(),
+                data={"files": "all"},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(select_url),
+            )
+            sel_resp.raise_for_status()
+
+            target_dir = TMP_DIR / f"realdebrid_{torrent_id}"
+            target_dir.mkdir(parents=True, exist_ok=True)
+
+            state = _DownloadState(
+                torrent_id=torrent_id,
+                name=name,
+                target_dir=target_dir,
+                phase="waiting_rd",
+            )
+            with self._downloads_lock:
+                self._downloads[torrent_id] = state
+
+            logger.info(
+                "Added torrent to Real-Debrid: ID %s (%s)",
+                torrent_id,
+                name,
+            )
+
+        except Exception:
+            logger.exception("Failed to upload magnet to Real-Debrid")
+            raise
+
+        else:
+            return torrent_id
+
+    def get_status(self, download_id: str) -> DownloadStatus:
+        """Poll Real-Debrid for torrent status and drive the download."""
+        state = self._ensure_state(download_id)
+
+        # Return cached terminal / in-flight states immediately.
+        with state.lock:
+            if state.phase == "error":
+                return DownloadStatus.error(
+                    state.error_message or "Real-Debrid error",
+                )
+            if state.phase == "complete":
+                return DownloadStatus(
+                    progress=100.0,
+                    state=DownloadState.COMPLETE,
+                    message="Complete",
+                    complete=True,
+                    file_path=str(state.target_dir),
+                )
+            if state.phase == "downloading_http":
+                return DownloadStatus(
+                    progress=state.progress,
+                    state=DownloadState.DOWNLOADING,
+                    message="Downloading files via HTTP...",
+                    complete=False,
+                    file_path=None,
+                )
+
+        # Query Real-Debrid for torrent info.
+        try:
+            info_url = f"{_API_BASE}/torrents/info/{download_id}"
+            resp = requests.get(
+                info_url,
+                headers=self._auth_headers(),
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(info_url),
+            )
+            resp.raise_for_status()
+            info = resp.json()
+            return self._handle_torrent_info(info, state)
+
+        except Exception as e:
+            logger.exception(
+                "Error checking Real-Debrid status for %s",
+                download_id,
+            )
+            return DownloadStatus.error(str(e))
+
+    def remove(
+        self,
+        download_id: str,
+        *,
+        delete_files: bool = False,
+    ) -> bool:
+        """Delete the torrent from Real-Debrid and clean up local files."""
+        try:
+            url = f"{_API_BASE}/torrents/delete/{download_id}"
+            requests.delete(
+                url,
+                headers=self._auth_headers(),
+                timeout=_STATUS_TIMEOUT,
+                verify=get_ssl_verify(url),
+            )
+        except _REALDEBRID_CLIENT_ERRORS as e:
+            logger.warning("Failed to delete torrent from Real-Debrid: %s", e)
+
+        with self._downloads_lock:
+            state = self._downloads.pop(download_id, None)
+
+        if state and state.target_dir.exists():
+            shutil.rmtree(state.target_dir, ignore_errors=True)
+        return True
+
+    def get_download_path(self, download_id: str) -> str | None:
+        """Return the local directory containing downloaded files."""
+        with self._downloads_lock:
+            state = self._downloads.get(download_id)
+        if state and state.phase == "complete":
+            return str(state.target_dir)
+        target_dir = TMP_DIR / f"realdebrid_{download_id}"
+        if target_dir.exists():
+            return str(target_dir)
+        return None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_state(self, download_id: str) -> _DownloadState:
+        """Get or create download state for the given torrent ID."""
+        with self._downloads_lock:
+            state = self._downloads.get(download_id)
+        if state:
+            return state
+
+        target_dir = TMP_DIR / f"realdebrid_{download_id}"
+        state = _DownloadState(
+            torrent_id=download_id,
+            name=f"Download {download_id}",
+            target_dir=target_dir,
+            phase="waiting_rd",
+        )
+        with self._downloads_lock:
+            self._downloads[download_id] = state
+        return state
+
+    def _handle_torrent_info(
+        self,
+        info: dict[str, Any],
+        state: _DownloadState,
+    ) -> DownloadStatus:
+        """Map Real-Debrid torrent info to a DownloadStatus."""
+        status = info.get("status", "")
+
+        if status in _STATUS_DOWNLOADING:
+            progress = float(info.get("progress", 0.0))
+            speed = int(info.get("speed", 0))
+            filename = info.get("filename", state.name)
+            return DownloadStatus(
+                progress=progress * 0.5,
+                state=DownloadState.DOWNLOADING,
+                message=f"Real-Debrid downloading torrent ({filename})",
+                complete=False,
+                file_path=None,
+                download_speed=speed,
+            )
+
+        if status == _STATUS_READY:
+            links = info.get("links", [])
+            files = info.get("files", [])
+            self._maybe_start_download_thread(state, links, files)
+            return DownloadStatus(
+                progress=50.0,
+                state=DownloadState.DOWNLOADING,
+                message="Real-Debrid ready, retrieving files...",
+                complete=False,
+                file_path=None,
+            )
+
+        # Terminal error from Real-Debrid.
+        error_txt = f"Real-Debrid status error: {status}"
+        with state.lock:
+            state.phase = "error"
+            state.error_message = error_txt
+        return DownloadStatus.error(error_txt)
+
+    def _maybe_start_download_thread(
+        self,
+        state: _DownloadState,
+        links: list[str],
+        files: list[dict[str, Any]],
+    ) -> None:
+        """Spawn a background thread to unrestrict and download files."""
+        with state.lock:
+            already_running = state.phase in (
+                "unrestricting",
+                "downloading_http",
+                "complete",
+            )
+            thread_alive = state.download_thread is not None and state.download_thread.is_alive()
+            if already_running or thread_alive:
+                return
+            state.phase = "unrestricting"
+            t = threading.Thread(
+                target=self._process_and_download,
+                args=(state, links, files),
+                daemon=True,
+            )
+            state.download_thread = t
+            t.start()
+
+    # ------------------------------------------------------------------
+    # File download pipeline
+    # ------------------------------------------------------------------
+
+    def _process_and_download(
+        self,
+        state: _DownloadState,
+        links: list[str],
+        files: list[dict[str, Any]],
+    ) -> None:
+        """Unrestrict links and download files via HTTP.
+
+        Runs in a background thread spawned by ``_maybe_start_download_thread``.
+        """
+        try:
+            if not links:
+                msg = "No download links returned by Real-Debrid"
+                _raise_runtime_error(msg)
+
+            # Match selected files with links
+            selected_files = [f for f in files if f.get("selected") == 1]
+
+            # Filter relevant ebook / audiobook files
+            relevant_indices: list[int] = []
+            for i, f_info in enumerate(selected_files):
+                path_str = f_info.get("path", "").lower()
+                if path_str.endswith(_BOOK_EXTENSIONS):
+                    relevant_indices.append(i)
+
+            if not relevant_indices:
+                relevant_indices = list(range(len(links)))
+
+            with state.lock:
+                state.phase = "downloading_http"
+
+            total = len(relevant_indices)
+            for idx, rel_idx in enumerate(relevant_indices):
+                if rel_idx >= len(links):
+                    continue
+                link = links[rel_idx]
+
+                # Unrestrict the Real-Debrid link to get direct CDN download URL
+                unrestrict_url = f"{_API_BASE}/unrestrict/link"
+                unl_resp = requests.post(
+                    unrestrict_url,
+                    headers=self._auth_headers(),
+                    data={"link": link},
+                    timeout=_API_TIMEOUT,
+                    verify=get_ssl_verify(unrestrict_url),
+                )
+                unl_resp.raise_for_status()
+                unl_data = unl_resp.json()
+
+                direct_url = unl_data.get("download")
+                filename = unl_data.get("filename")
+                if not direct_url:
+                    msg = f"Failed to unrestrict Real-Debrid link: {link}"
+                    _raise_runtime_error(msg)
+
+                # Determine relative file path
+                if rel_idx < len(selected_files):
+                    rel_path_str = selected_files[rel_idx].get("path", "").lstrip("/")
+                    rel_path = Path(rel_path_str)
+                else:
+                    rel_path = Path(filename or f"file_{idx + 1}")
+
+                dest = state.target_dir / rel_path
+                dest.parent.mkdir(parents=True, exist_ok=True)
+
+                logger.info(
+                    "Downloading Real-Debrid file %d/%d: %s",
+                    idx + 1,
+                    total,
+                    rel_path,
+                )
+
+                buf = download_url(
+                    direct_url,
+                    referer="https://real-debrid.com/",
+                )
+                if not buf:
+                    msg = f"Failed to download from {direct_url}"
+                    _raise_runtime_error(msg)
+
+                with dest.open("wb") as fh:
+                    fh.write(buf.getvalue())
+
+                with state.lock:
+                    state.progress = 50.0 + (idx + 1) / total * 50.0
+
+            with state.lock:
+                state.phase = "complete"
+                state.progress = 100.0
+
+            logger.info(
+                "Real-Debrid download complete for ID %s at %s",
+                state.torrent_id,
+                state.target_dir,
+            )
+
+        except Exception:
+            logger.exception(
+                "Error in Real-Debrid download for ID %s",
+                state.torrent_id,
+            )
+            with state.lock:
+                state.phase = "error"
+                state.error_message = str(
+                    state.error_message or "Download failed",
+                )
@@ -47,7 +47,13 @@ class _RTorrentLoadProtocol(Protocol):
    def start(self, target: str, url: str, commands: str) -> object: ...


+class _RTorrentCustom1Protocol(Protocol):
+    def set(self, download_id: str, value: str) -> object: ...
+
+
 class _RTorrentDownloadProtocol(Protocol):
+    custom1: _RTorrentCustom1Protocol
+
    def multicall2(self, *args: object) -> list[list[Any]]: ...

    def delete_tied(self, download_id: str) -> object: ...
@@ -206,7 +212,10 @@ class RTorrentClient(DownloadClient):
                # watching for the new download to appear.
                torrent_hash = self._discover_added_torrent_hash(name, label, known_hashes)
            if not torrent_hash:
-                _raise_runtime_error("Could not determine torrent hash from URL")
+                message = "Could not determine torrent hash from URL"
+                if torrent_info.fetch_error:
+                    message = f"{message} (torrent file fetch failed: {torrent_info.fetch_error})"
+                _raise_runtime_error(message)

            logger.debug("Added torrent to rTorrent: %s", torrent_hash)

@@ -329,12 +338,14 @@ class RTorrentClient(DownloadClient):

        """
        try:
+            # rtorrent is somehow case sensitive and requires uppercase hashes for look
+            torrent_hash = download_id.upper()
            if delete_files:
-                self._rpc.d.delete_tied(download_id)
-                self._rpc.d.erase(download_id)
+                self._rpc.d.delete_tied(torrent_hash)
+                self._rpc.d.erase(torrent_hash)
            else:
-                self._rpc.d.stop(download_id)
-                self._rpc.d.erase(download_id)
+                self._rpc.d.stop(torrent_hash)
+                self._rpc.d.erase(torrent_hash)

            logger.info(
                "Removed torrent from rTorrent: %s%s",
@@ -348,6 +359,19 @@ class RTorrentClient(DownloadClient):
        else:
            return True

+    def set_category(self, download_id: str, category: str) -> bool:
+        """Assign a label to a torrent using rTorrent's custom1 field."""
+        try:
+            # rtorrent is somehow case sensitive and requires uppercase hashes for look
+            self._rpc.d.custom1.set(download_id.upper(), category)
+            logger.info("Set rTorrent label for %s to '%s'", download_id, category)
+        except _RTORRENT_CLIENT_ERRORS as e:
+            error_type = type(e).__name__
+            logger.exception("rTorrent set_category failed (%s)", error_type)
+            return False
+        else:
+            return True
+
    def get_download_path(self, download_id: str) -> str | None:
        """Get the path where torrent files are located.

@@ -159,6 +159,7 @@ def _test_qbittorrent_connection(current_values: dict[str, Any] | None = None) -
    raw_url = _resolve_string_setting(current_values, config.get, "QBITTORRENT_URL")
    username = _resolve_string_setting(current_values, config.get, "QBITTORRENT_USERNAME")
    password = _resolve_string_setting(current_values, config.get, "QBITTORRENT_PASSWORD")
+    api_key = _resolve_string_setting(current_values, config.get, "QBITTORRENT_API_KEY")

    if not raw_url:
        return {"success": False, "message": "qBittorrent URL is required"}
@@ -174,6 +175,7 @@ def _test_qbittorrent_connection(current_values: dict[str, Any] | None = None) -
            host=url,
            username=username,
            password=password,
+            api_key=api_key or None,
            VERIFY_WEBUI_CERTIFICATE=get_ssl_verify(url),
        )
        client.auth_log_in()
@@ -181,9 +183,18 @@ def _test_qbittorrent_connection(current_values: dict[str, Any] | None = None) -
    except ImportError:
        return {"success": False, "message": "qbittorrent-api package not installed"}
    except _QBITTORRENT_SETTINGS_ERRORS as e:
+        if isinstance(e, _QBittorrentLoginFailed):
+            # LoginFailed carries no message of its own, so name the rejected credential.
+            rejected = "API key" if api_key else "username or password"
+            return {"success": False, "message": f"qBittorrent rejected the {rejected}"}
        return {"success": False, "message": f"Connection failed: {e!s}"}
    else:
-        return {"success": True, "message": f"Connected to qBittorrent (API v{api_version})"}
+        # Both credentials can be set at once, so name the one that actually authenticated.
+        used = " using the API key" if api_key else ""
+        return {
+            "success": True,
+            "message": f"Connected to qBittorrent (API v{api_version}){used}",
+        }


 def _test_transmission_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
@@ -520,6 +531,40 @@ def _test_sabnzbd_connection(current_values: dict[str, Any] | None = None) -> di
        return {"success": True, "message": f"Connected to SABnzbd {version}"}


+def _test_alldebrid_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Test the AllDebrid API connection using current form values."""
+    from shelfmark.core.config import config
+    from shelfmark.download.clients.alldebrid import AllDebridClient
+
+    current_values = current_values or {}
+    api_key = _resolve_string_setting(current_values, config.get, "ALLDEBRID_API_KEY")
+
+    if not api_key:
+        return {"success": False, "message": "AllDebrid API Key is required"}
+
+    client = AllDebridClient()
+    client._api_key = api_key
+    success, message = client.test_connection()
+    return {"success": success, "message": message}
+
+
+def _test_realdebrid_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Test the Real-Debrid API connection using current form values."""
+    from shelfmark.core.config import config
+    from shelfmark.download.clients.realdebrid import RealDebridClient
+
+    current_values = current_values or {}
+    api_key = _resolve_string_setting(current_values, config.get, "REALDEBRID_API_KEY")
+
+    if not api_key:
+        return {"success": False, "message": "Real-Debrid API Key is required"}
+
+    client = RealDebridClient()
+    client._api_key = api_key
+    success, message = client.test_connection()
+    return {"success": success, "message": message}
+
+
 # ==================== Download Clients Tab ====================


@@ -544,13 +589,45 @@ def prowlarr_clients_settings() -> list[SettingsField]:
            description="Choose which torrent client to use",
            options=[
                {"value": "", "label": "None"},
+                {"value": "alldebrid", "label": "AllDebrid"},
                {"value": "qbittorrent", "label": "qBittorrent"},
+                {"value": "realdebrid", "label": "Real-Debrid"},
                {"value": "transmission", "label": "Transmission"},
                {"value": "deluge", "label": "Deluge"},
                {"value": "rtorrent", "label": "rTorrent"},
            ],
            default="",
        ),
+        # --- AllDebrid Settings ---
+        PasswordField(
+            key="ALLDEBRID_API_KEY",
+            label="API Key",
+            description="AllDebrid API Key (apiv4) from your AllDebrid account settings",
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "alldebrid"},
+        ),
+        ActionButton(
+            key="test_alldebrid",
+            label="Test Connection",
+            description="Verify your AllDebrid configuration",
+            style="primary",
+            callback=_test_alldebrid_connection,
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "alldebrid"},
+        ),
+        # --- Real-Debrid Settings ---
+        PasswordField(
+            key="REALDEBRID_API_KEY",
+            label="API Key",
+            description="Real-Debrid API Key (Secret Token) from your Real-Debrid account settings",
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "realdebrid"},
+        ),
+        ActionButton(
+            key="test_realdebrid",
+            label="Test Connection",
+            description="Verify your Real-Debrid configuration",
+            style="primary",
+            callback=_test_realdebrid_connection,
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "realdebrid"},
+        ),
        # --- qBittorrent Settings ---
        TextField(
            key="QBITTORRENT_URL",
@@ -572,6 +649,12 @@ def prowlarr_clients_settings() -> list[SettingsField]:
            description="qBittorrent Web UI password",
            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "qbittorrent"},
        ),
+        PasswordField(
+            key="QBITTORRENT_API_KEY",
+            label="API Key",
+            description="Found in qBittorrent: Options > Web UI > API Key (qBittorrent 5.2.0+). Used instead of the username and password when set.",
+            show_when={"field": "PROWLARR_TORRENT_CLIENT", "value": "qbittorrent"},
+        ),
        ActionButton(
            key="test_qbittorrent",
            label="Test Connection",
@@ -771,14 +854,23 @@ def prowlarr_clients_settings() -> list[SettingsField]:
        SelectField(
            key="PROWLARR_TORRENT_ACTION",
            label="Torrent Completion Action",
-            description="Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding",
+            description="Choose whether to keep, remove, or move the torrent to another category or label after import",
            options=[
                {"value": "keep", "label": "Keep"},
                {"value": "remove", "label": "Remove"},
+                {"value": "change_category", "label": "Change Category"},
            ],
            default="keep",
            show_when={"field": "PROWLARR_TORRENT_CLIENT", "notEmpty": True},
        ),
+        TextField(
+            key="PROWLARR_TORRENT_POST_IMPORT_CATEGORY",
+            label="Post-Import Category",
+            description="Category or label to assign after a successful import",
+            placeholder="imported",
+            default="",
+            show_when={"field": "PROWLARR_TORRENT_ACTION", "value": "change_category"},
+        ),
        # --- Usenet Client Selection ---
        HeadingField(
            key="usenet_heading",
@@ -5,8 +5,10 @@ from __future__ import annotations
 import base64
 import hashlib
 import re
+import time
 from binascii import Error as BinasciiError
 from dataclasses import dataclass
+from threading import Lock
 from urllib.parse import ParseResult, parse_qs, urljoin, urlparse

 import requests
@@ -36,6 +38,15 @@ _TORRENT_FETCH_ERRORS = (
 _TORRENT_PARSE_ERRORS = (IndexError, KeyError, TypeError, ValueError)
 _TRUSTED_TORRENT_FETCH_URL_CONFIG_KEYS = ("PROWLARR_URL", "NEWZNAB_URL")

+# Successful torrent fetches are reused for a short window so one add attempt
+# hits the download link only once. Tracker download links (e.g. private
+# trackers behind Prowlarr's proxy) can be slow, rate-limited, or single-use,
+# and both find_existing() and add_download() resolve the same URL (#1111).
+_TORRENT_FETCH_CACHE_TTL_SECONDS = 120.0
+_TORRENT_FETCH_CACHE_MAX_ENTRIES = 8
+_torrent_fetch_cache_lock = Lock()
+_torrent_fetch_cache: dict[str, tuple[float, TorrentInfo]] = {}
+
 type BencodeValue = dict[str | bytes, BencodeValue] | list[BencodeValue] | int | bytes | str


@@ -55,6 +66,9 @@ class TorrentInfo:
    magnet_url: str | None = None
    """The actual magnet URL, if available."""

+    fetch_error: str | None = None
+    """Why fetching the .torrent URL failed, or None if it succeeded/was skipped."""
+
    def with_info_hash(self, info_hash: str | None) -> TorrentInfo:
        """Return a copy with the info_hash replaced when provided."""
        if info_hash:
@@ -63,6 +77,7 @@ class TorrentInfo:
                torrent_data=self.torrent_data,
                is_magnet=self.is_magnet,
                magnet_url=self.magnet_url,
+                fetch_error=self.fetch_error,
            )
        return self

@@ -97,6 +112,48 @@ def extract_torrent_info(
    if not fetch_torrent:
        return TorrentInfo(info_hash=expected_hash, torrent_data=None, is_magnet=False)

+    info = _get_cached_torrent_fetch(url)
+    if info is None:
+        info = _fetch_torrent_info(url)
+        if info.fetch_error is None:
+            _store_cached_torrent_fetch(url, info)
+
+    return info.with_info_hash(info.info_hash or expected_hash)
+
+
+def _get_cached_torrent_fetch(url: str) -> TorrentInfo | None:
+    with _torrent_fetch_cache_lock:
+        entry = _torrent_fetch_cache.get(url)
+        if entry is None:
+            return None
+        fetched_at, info = entry
+        if time.monotonic() - fetched_at > _TORRENT_FETCH_CACHE_TTL_SECONDS:
+            del _torrent_fetch_cache[url]
+            return None
+    logger.debug("Reusing recently fetched torrent data for: %s...", url[:80])
+    return info
+
+
+def _store_cached_torrent_fetch(url: str, info: TorrentInfo) -> None:
+    with _torrent_fetch_cache_lock:
+        _torrent_fetch_cache[url] = (time.monotonic(), info)
+        while len(_torrent_fetch_cache) > _TORRENT_FETCH_CACHE_MAX_ENTRIES:
+            oldest_url = min(_torrent_fetch_cache, key=lambda key: _torrent_fetch_cache[key][0])
+            del _torrent_fetch_cache[oldest_url]
+
+
+def clear_torrent_fetch_cache() -> None:
+    """Drop all cached torrent fetches (used by tests)."""
+    with _torrent_fetch_cache_lock:
+        _torrent_fetch_cache.clear()
+
+
+def _fetch_torrent_info(url: str) -> TorrentInfo:
+    """Fetch a .torrent URL and parse out the info_hash and raw torrent data.
+
+    On failure, the returned TorrentInfo carries the reason in `fetch_error`
+    so callers can surface it instead of a generic hash error.
+    """
    # A release source can legitimately hand us a download URL on a different
    # origin than the configured Prowlarr/Newznab endpoint (e.g. a direct
    # tracker link, or Prowlarr reached through a separate proxy), and a trusted
@@ -145,18 +202,20 @@ def extract_torrent_info(
            redirect_url = resolve_url(current_url, resp.headers.get("Location", ""))
            if redirect_url.startswith("magnet:"):
                logger.debug("Download URL redirected to magnet link")
-                info_hash = extract_hash_from_magnet(redirect_url)
-                if not info_hash and expected_hash:
-                    info_hash = expected_hash
                return TorrentInfo(
-                    info_hash=info_hash,
+                    info_hash=extract_hash_from_magnet(redirect_url),
                    torrent_data=None,
                    is_magnet=True,
                    magnet_url=redirect_url,
                )
            if redirects_remaining <= 0:
-                logger.debug("Too many redirects fetching torrent file: %s...", url[:80])
-                return TorrentInfo(info_hash=expected_hash, torrent_data=None, is_magnet=False)
+                logger.warning("Too many redirects fetching torrent file: %s...", url[:80])
+                return TorrentInfo(
+                    info_hash=None,
+                    torrent_data=None,
+                    is_magnet=False,
+                    fetch_error="too many redirects",
+                )
            redirects_remaining -= 1
            logger.debug("Following redirect to: %s...", redirect_url[:80])
            current_url = redirect_url
@@ -170,25 +229,22 @@ def extract_torrent_info(
            text_content = torrent_data.decode("utf-8", errors="ignore").strip()
            if text_content.startswith("magnet:"):
                logger.debug("Download URL returned magnet link as response body")
-                info_hash = extract_hash_from_magnet(text_content)
-                if not info_hash and expected_hash:
-                    info_hash = expected_hash
                return TorrentInfo(
-                    info_hash=info_hash,
+                    info_hash=extract_hash_from_magnet(text_content),
                    torrent_data=None,
                    is_magnet=True,
                    magnet_url=text_content,
                )

-        info_hash = extract_info_hash_from_torrent(torrent_data) or expected_hash
+        info_hash = extract_info_hash_from_torrent(torrent_data)
        if info_hash:
            logger.debug("Extracted hash from torrent file: %s", info_hash)
        else:
            logger.warning("Could not extract hash from torrent file")
        return TorrentInfo(info_hash=info_hash, torrent_data=torrent_data, is_magnet=False)
    except _TORRENT_FETCH_ERRORS as e:
-        logger.debug("Could not fetch torrent file: %s", e)
-        return TorrentInfo(info_hash=expected_hash, torrent_data=None, is_magnet=False)
+        logger.warning("Could not fetch torrent file: %s", e)
+        return TorrentInfo(info_hash=None, torrent_data=None, is_magnet=False, fetch_error=str(e))


 def _is_trusted_torrent_fetch_url(url: str) -> bool:
@@ -390,6 +390,30 @@ class TransmissionClient(DownloadClient):
        else:
            return True

+    def _get_torrent_labels(self, download_id: str) -> list[str]:
+        """Return a torrent's current labels, preserving their order."""
+        torrent = self._client.get_torrent(download_id)
+        raw_labels = getattr(torrent, "labels", None) or []
+        return [str(label) for label in raw_labels if str(label)]
+
+    def set_category(self, download_id: str, category: str) -> bool:
+        """Add the post-import label to a torrent, keeping labels set elsewhere."""
+        try:
+            existing_labels = self._get_torrent_labels(download_id)
+            if category in existing_labels:
+                logger.debug(
+                    "Transmission torrent %s already has label '%s'", download_id, category
+                )
+                return True
+
+            self._client.change_torrent(ids=download_id, labels=[*existing_labels, category])
+            logger.info("Added Transmission label '%s' to %s", category, download_id)
+        except _TRANSMISSION_CLIENT_ERRORS as e:
+            self._log_error("set_category", e)
+            return False
+        else:
+            return True
+
    def get_download_path(self, download_id: str) -> str | None:
        """Get the path where torrent files are located.

@@ -0,0 +1,158 @@
+"""RFC 8484 DNS wireformat encoding/decoding for DoH providers.
+
+Providers split into two incompatible camps and the difference is not cosmetic:
+
+* **JSON** (Cloudflare, Google) - ``?name=<host>&type=A`` returning a JSON body. A
+  convention, not a standard, and the only one Shelfmark used to speak.
+* **Wireformat** (Quad9, OpenDNS) - RFC 8484 proper: a base64url-encoded DNS message
+  in ``?dns=``, answered with ``application/dns-message``. Quad9 additionally
+  *requires HTTP/2* per RFC 8484 section 5.2 and answers HTTP/1.1 with 505.
+
+This module carries the codec only; the transport choice lives in the resolver.
+Encoding a query is a handful of bytes, and parsing an answer needs message
+compression support (RFC 1035 section 4.1.4) because answer names are almost always
+pointers back into the question.
+"""
+
+from __future__ import annotations
+
+import base64
+import secrets
+import struct
+
+# Record types we resolve.
+TYPE_A = 1
+TYPE_AAAA = 28
+
+_CLASS_IN = 1
+_HEADER = struct.Struct(">HHHHHH")
+_RR_FIXED = struct.Struct(">HHIH")  # type, class, ttl, rdlength
+_FLAG_RECURSION_DESIRED = 0x0100
+_MAX_LABEL_JUMPS = 64  # cap pointer-following so a malicious answer cannot loop
+_MAX_NAME_LENGTH = 255
+
+
+class WireformatError(ValueError):
+    """Raised when a DNS wireformat message cannot be parsed."""
+
+
+def encode_query(hostname: str, record_type: int) -> bytes:
+    """Build a DNS query message for ``hostname``.
+
+    The ID is zero because RFC 8484 section 4.1 requires it for cacheability, but the
+    caller may randomise it when not using a cache.
+    """
+    if not hostname:
+        msg = "hostname must not be empty"
+        raise WireformatError(msg)
+
+    question = bytearray()
+    for label in hostname.rstrip(".").split("."):
+        encoded = label.encode("idna") if not label.isascii() else label.encode("ascii")
+        if not encoded or len(encoded) > 63:
+            msg = f"invalid DNS label in {hostname!r}"
+            raise WireformatError(msg)
+        question.append(len(encoded))
+        question.extend(encoded)
+    question.append(0)
+    question.extend(struct.pack(">HH", record_type, _CLASS_IN))
+
+    header = _HEADER.pack(0, _FLAG_RECURSION_DESIRED, 1, 0, 0, 0)
+    return header + bytes(question)
+
+
+def encode_query_param(hostname: str, record_type: int) -> str:
+    """Return the base64url ``dns=`` parameter value for a query (padding stripped)."""
+    return base64.urlsafe_b64encode(encode_query(hostname, record_type)).rstrip(b"=").decode()
+
+
+def _read_name(message: bytes, offset: int) -> int:
+    """Skip over a (possibly compressed) name, returning the offset after it."""
+    jumps = 0
+    length = 0
+    while True:
+        if offset >= len(message):
+            msg = "truncated DNS name"
+            raise WireformatError(msg)
+        label_len = message[offset]
+        if label_len == 0:
+            return offset + 1
+        if label_len & 0xC0 == 0xC0:
+            # A pointer ends this name; the rest of the record follows the 2 bytes.
+            if offset + 1 >= len(message):
+                msg = "truncated DNS name pointer"
+                raise WireformatError(msg)
+            return offset + 2
+        offset += 1 + label_len
+        length += 1 + label_len
+        jumps += 1
+        if jumps > _MAX_LABEL_JUMPS or length > _MAX_NAME_LENGTH:
+            msg = "malformed DNS name"
+            raise WireformatError(msg)
+
+
+def decode_answer(message: bytes, record_type: int) -> list[str]:
+    """Extract the IP addresses of ``record_type`` from a DNS response message.
+
+    Returns an empty list for a well-formed response that carries no matching record
+    (NXDOMAIN, or only CNAMEs), and raises WireformatError for a malformed one - the
+    caller treats those differently.
+    """
+    if len(message) < _HEADER.size:
+        msg = "DNS response shorter than its header"
+        raise WireformatError(msg)
+
+    _id, _flags, qdcount, ancount, _ns, _ar = _HEADER.unpack_from(message, 0)
+    offset = _HEADER.size
+
+    for _ in range(qdcount):
+        offset = _read_name(message, offset)
+        offset += 4  # QTYPE + QCLASS
+
+    results: list[str] = []
+    for _ in range(ancount):
+        offset = _read_name(message, offset)
+        if offset + _RR_FIXED.size > len(message):
+            msg = "truncated resource record"
+            raise WireformatError(msg)
+        rtype, rclass, _ttl, rdlength = _RR_FIXED.unpack_from(message, offset)
+        offset += _RR_FIXED.size
+        rdata = message[offset : offset + rdlength]
+        if len(rdata) != rdlength:
+            msg = "truncated record data"
+            raise WireformatError(msg)
+        offset += rdlength
+
+        if rclass != _CLASS_IN or rtype != record_type:
+            continue
+        if rtype == TYPE_A and rdlength == 4:
+            results.append(".".join(str(b) for b in rdata))
+        elif rtype == TYPE_AAAA and rdlength == 16:
+            groups = struct.unpack(">8H", rdata)
+            results.append(_compress_ipv6(groups))
+
+    return results
+
+
+def _compress_ipv6(groups: tuple[int, ...]) -> str:
+    """Render an IPv6 address with the longest zero run collapsed to '::'."""
+    best_start = best_len = -1
+    run_start = -1
+    for i, group in enumerate([*list(groups), 1]):  # sentinel closes a trailing run
+        if group == 0 and i < len(groups):
+            if run_start < 0:
+                run_start = i
+        elif run_start >= 0:
+            if i - run_start > best_len:
+                best_start, best_len = run_start, i - run_start
+            run_start = -1
+
+    parts = [format(g, "x") for g in groups]
+    if best_len > 1:
+        return ":".join(parts[:best_start]) + "::" + ":".join(parts[best_start + best_len :])
+    return ":".join(parts)
+
+
+def random_query_id() -> int:
+    """A random DNS message ID, for callers that do not want the RFC 8484 zero."""
+    return secrets.randbelow(0x10000)
@@ -4,6 +4,7 @@ These utilities handle file collisions atomically, avoiding TOCTOU race conditio
 when multiple workers may try to write to the same path simultaneously.
 """

+import contextlib
 import errno
 import os
 import shutil
@@ -104,6 +105,57 @@ _PUBLISH_VERIFY_RETRY_SECONDS = 0.25
 _TEMPFILE_PREFIX = ".shelfmark."
 _TEMPFILE_SUFFIX = ".tmp"

+# Destinations that accept writes but reject unlink/rename, e.g. a Synology share
+# with "Delete subfolders and files" unticked. Publishing a temp file into place
+# removes a directory entry, so those paths must be written in place instead.
+_DELETE_DENIED_DIRS: set[str] = set()
+
+
+class _PublishDeniedError(Exception):
+    """A fully-written temp file could not be renamed onto its final path."""
+
+
+def _is_delete_denied_error(error: Exception) -> bool:
+    return isinstance(error, OSError) and error.errno in {errno.EACCES, errno.EPERM}
+
+
+def mark_delete_denied(directory: Path) -> None:
+    """Record that `directory` rejects deletes so later writes skip the temp file."""
+    key = str(directory)
+    if key in _DELETE_DENIED_DIRS:
+        return
+    _DELETE_DENIED_DIRS.add(key)
+    logger.warning(
+        "Destination %s rejects delete/rename; writing files in place instead of "
+        "publishing atomically. Grant delete permission to restore atomic writes.",
+        directory,
+    )
+
+
+def clear_delete_denied(directory: Path) -> None:
+    """Forget recorded denials for `directory` and anything beneath it.
+
+    Subdirectories get marked independently (an `organize` layout publishes into
+    per-author folders), so clearing only the exact key would leave a fixed
+    destination writing in place until restart.
+    """
+    if not _DELETE_DENIED_DIRS:
+        return
+    key = str(directory)
+    prefix = f"{key}{os.sep}"
+    _DELETE_DENIED_DIRS.difference_update(
+        {marked for marked in _DELETE_DENIED_DIRS if marked == key or marked.startswith(prefix)}
+    )
+
+
+def is_delete_denied(directory: Path) -> bool:
+    """True if `directory` or one of its ancestors is known to reject deletes."""
+    if not _DELETE_DENIED_DIRS:
+        return False
+    if str(directory) in _DELETE_DENIED_DIRS:
+        return True
+    return any(str(parent) in _DELETE_DENIED_DIRS for parent in directory.parents)
+

 def _verify_transfer_size(
    dest: Path,
@@ -361,10 +413,40 @@ def _create_temp_path(dest_path: Path) -> Path:
    return Path(temp_path)


+def _discard_path(path: Path) -> None:
+    """Best-effort unlink that tolerates destinations which reject deletes."""
+    try:
+        run_blocking_io(path.unlink, missing_ok=True)
+    except OSError as exc:
+        logger.warning("Could not remove %s: %s", path, exc)
+
+
+def _copy_into_claimed(source_path: Path, dest_path: Path, expected_size: int) -> None:
+    """Copy content straight into an already-claimed destination path.
+
+    Used when the destination rejects rename/unlink: there is no temp file to
+    publish, so the final name is written in place. This is not atomic - a
+    watcher can observe a partial file - but it is the only way to deliver on
+    such a share. `copyfile` (not `copy2`) because metadata copying needs chmod,
+    which those shares also tend to refuse.
+    """
+    try:
+        run_blocking_io(shutil.copyfile, str(source_path), str(dest_path))
+        _verify_transfer_size(dest_path, expected_size, "copy")
+    except Exception:
+        with contextlib.suppress(OSError):
+            run_blocking_io(dest_path.unlink, missing_ok=True)
+        raise
+
+
 def _publish_temp_file(temp_path: Path, dest_path: Path) -> bool:
    """Publish a temp file to its final path without overwriting existing files.

    Returns True on success, False if the destination already exists.
+
+    Raises `_PublishDeniedError` when the rename is refused for lack of delete
+    permission. The claimed destination is left in place so the caller can write
+    into it directly instead.
    """
    claimed = _claim_destination(dest_path)
    if not claimed:
@@ -374,7 +456,19 @@ def _publish_temp_file(temp_path: Path, dest_path: Path) -> bool:
        # Publish by renaming the fully-written temp file into place. This gives
        # watchers an IN_MOVED_TO-style event on the final path instead of relying
        # on hardlink support in the destination filesystem.
-        run_blocking_io(os.replace, str(temp_path), str(dest_path))
+        try:
+            run_blocking_io(os.replace, str(temp_path), str(dest_path))
+        except OSError as e:
+            if _is_delete_denied_error(e):
+                log_transfer_permission_context(
+                    "publish_replace",
+                    source=temp_path,
+                    dest=dest_path,
+                    error=e,
+                )
+                mark_delete_denied(dest_path.parent)
+                raise _PublishDeniedError(str(e)) from e
+            raise

        # Best-effort nudge for watchers that only react to close-write on the
        # final filename rather than rename/move events.
@@ -383,6 +477,8 @@ def _publish_temp_file(temp_path: Path, dest_path: Path) -> bool:
            run_blocking_io(os.close, fd)
        except OSError:
            pass
+    except _PublishDeniedError:
+        raise
    except Exception as e:
        if _is_permission_error(e):
            log_transfer_permission_context(
@@ -391,12 +487,23 @@ def _publish_temp_file(temp_path: Path, dest_path: Path) -> bool:
                dest=dest_path,
                error=e,
            )
-        run_blocking_io(dest_path.unlink, missing_ok=True)
+        _discard_path(dest_path)
        raise
    else:
        return True


+def _move_via_copy(source_path: Path, dest_path: Path, max_attempts: int) -> Path:
+    """Deliver a move as copy + source unlink.
+
+    For destinations that reject rename. The source lives in TMP_DIR (which we
+    own and can delete), so only the destination-side semantics change.
+    """
+    final_path = atomic_copy(source_path, dest_path, max_attempts=max_attempts)
+    _discard_path(source_path)
+    return final_path
+
+
 def atomic_move(source_path: Path, dest_path: Path, max_attempts: int = 100) -> Path:
    """Move a file with collision detection.

@@ -423,6 +530,11 @@ def atomic_move(source_path: Path, dest_path: Path, max_attempts: int = 100) ->
    ext = dest_path.suffix
    parent = dest_path.parent

+    # rename() removes a directory entry, so a destination that refuses deletes
+    # cannot be moved into. Deliver it as copy + source unlink instead.
+    if is_delete_denied(parent):
+        return _move_via_copy(source_path, dest_path, max_attempts)
+
    for attempt in range(max_attempts):
        try_path = dest_path if attempt == 0 else parent / f"{base}_{attempt}{ext}"

@@ -449,6 +561,13 @@ def atomic_move(source_path: Path, dest_path: Path, max_attempts: int = 100) ->
                run_blocking_io(try_path.unlink, missing_ok=True)
            continue
        except OSError as e:
+            if _is_delete_denied_error(e):
+                # Destination refuses the rename; fall back to copy + unlink source.
+                mark_delete_denied(parent)
+                if claimed:
+                    _discard_path(try_path)
+                return _move_via_copy(source_path, dest_path, max_attempts)
+
            # Cross-filesystem - copy to temp and publish atomically.
            if e.errno != errno.EXDEV:
                if claimed:
@@ -497,7 +616,7 @@ def atomic_move(source_path: Path, dest_path: Path, max_attempts: int = 100) ->
                    try:
                        _verify_published_file(try_path, expected_size, "move")
                    except Exception:
-                        run_blocking_io(try_path.unlink, missing_ok=True)
+                        _discard_path(try_path)
                        raise

                    run_blocking_io(source_path.unlink)
@@ -508,9 +627,18 @@ def atomic_move(source_path: Path, dest_path: Path, max_attempts: int = 100) ->
                    if temp_path:
                        run_blocking_io(temp_path.unlink, missing_ok=True)
                    continue
+                except _PublishDeniedError:
+                    # Destination is claimed but unrenameable; write into it directly.
+                    _copy_into_claimed(source_path, try_path, expected_size)
+                    if temp_path:
+                        _discard_path(temp_path)
+                    _discard_path(source_path)
+                    if attempt > 0:
+                        logger.info("File collision resolved: %s", try_path.name)
+                    return try_path
                except Exception:
                    if temp_path:
-                        run_blocking_io(temp_path.unlink, missing_ok=True)
+                        _discard_path(temp_path)
                    raise
                else:
                    return try_path
@@ -629,6 +757,17 @@ def atomic_copy(source_path: Path, dest_path: Path, max_attempts: int = 100) ->
        try_path = dest_path if attempt == 0 else parent / f"{base}_{attempt}{ext}"
        if run_blocking_io(try_path.exists):
            continue
+
+        # Known-undeletable destination: skip the temp file entirely, otherwise
+        # every transfer would strand a `.shelfmark.*.tmp` we cannot clean up.
+        if is_delete_denied(parent):
+            if not _claim_destination(try_path):
+                continue
+            _copy_into_claimed(source_path, try_path, expected_size)
+            if attempt > 0:
+                logger.info("File collision resolved: %s", try_path.name)
+            return try_path
+
        temp_path: Path | None = None
        try:
            temp_path = _create_temp_path(try_path)
@@ -680,14 +819,22 @@ def atomic_copy(source_path: Path, dest_path: Path, max_attempts: int = 100) ->
            try:
                _verify_published_file(try_path, expected_size, "copy")
            except Exception:
-                run_blocking_io(try_path.unlink, missing_ok=True)
+                _discard_path(try_path)
                raise

            if attempt > 0:
                logger.info("File collision resolved: %s", try_path.name)
+        except _PublishDeniedError:
+            # The destination is claimed but unrenameable; write into it directly.
+            _copy_into_claimed(source_path, try_path, expected_size)
+            if temp_path:
+                _discard_path(temp_path)
+            if attempt > 0:
+                logger.info("File collision resolved: %s", try_path.name)
+            return try_path
        except Exception:
            if temp_path:
-                run_blocking_io(temp_path.unlink, missing_ok=True)
+                _discard_path(temp_path)
            raise
        else:
            return try_path
@@ -4,7 +4,6 @@ import random
 import time
 from http import HTTPStatus
 from io import BytesIO
-from threading import Event, Thread
 from typing import TYPE_CHECKING, NoReturn
 from urllib.parse import urljoin, urlparse

@@ -16,24 +15,34 @@ from shelfmark.core.config import config as app_config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.request_helpers import coerce_bool, normalize_positive_int
 from shelfmark.download import network
+from shelfmark.download.activity import release_activity_grace, request_activity_grace
 from shelfmark.download.network import get_proxies, get_ssl_verify

 if TYPE_CHECKING:
    from collections.abc import Callable
+    from threading import Event
    from types import ModuleType

 logger = setup_logger(__name__)
 _RNG = random.SystemRandom()

 _MAX_REDIRECTS = 5
+# Z-Library answers the first hit with a 503 whose only real payload is a Set-Cookie; echoing
+# that cookie back returns the 302 to the real page. Two attempts cover the handshake without
+# letting a server that keeps re-issuing cookies hold us in the loop.
+_MAX_COOKIE_HANDSHAKE_RETRIES = 2
 _HTTP_STATUS_FORBIDDEN = HTTPStatus.FORBIDDEN
 _HTTP_STATUS_NOT_FOUND = HTTPStatus.NOT_FOUND
 _HTTP_STATUS_RATE_LIMITED = HTTPStatus.TOO_MANY_REQUESTS
+_HTTP_STATUS_SERVICE_UNAVAILABLE = HTTPStatus.SERVICE_UNAVAILABLE
 _HTTP_STATUS_OK = HTTPStatus.OK
 _HTTP_STATUS_RANGE_NOT_SATISFIABLE = HTTPStatus.REQUESTED_RANGE_NOT_SATISFIABLE
 _HTTP_STATUS_PARTIAL_CONTENT = HTTPStatus.PARTIAL_CONTENT
 _HTTP_STATUS_NON_RETRYABLE = (_HTTP_STATUS_FORBIDDEN, _HTTP_STATUS_NOT_FOUND)
 _STATUS_CALLBACK_ERRORS = (AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError)
+# Added on top of the active bypasser's own budget so it reports its real failure before
+# stall detection cancels the download.
+_BYPASS_GRACE_SLACK_SECONDS = 30.0
 _BYPASSER_ERRORS = (
    AttributeError,
    BypassCancelledError,
@@ -54,6 +63,18 @@ def _raise_too_many_redirects(message: str) -> NoReturn:
    raise requests.exceptions.TooManyRedirects(message)


+def _new_cookies(response: requests.Response, already_sent: dict[str, str]) -> dict[str, str]:
+    """Cookies a response set that we were not already echoing back.
+
+    Returning only the *new* ones is what makes the retry terminate: a server that keeps
+    re-issuing the same cookie yields nothing here, so we stop instead of spinning.
+    """
+    jar = getattr(response, "cookies", None)
+    if not jar:
+        return {}
+    return {name: value for name, value in jar.items() if already_sent.get(name) != value}
+
+
 def _get_internal_bypasser() -> ModuleType:
    """Lazy import of internal bypasser module."""
    global _internal_bypasser
@@ -99,6 +120,19 @@ def _is_cf_bypass_enabled() -> bool:
    return coerce_bool(app_config.get("USE_CF_BYPASS", True))


+def _bypass_grace_seconds() -> float:
+    """How long a bypass may block before stall detection should give up on it.
+
+    Each bypasser knows its own retry/timeout budget, so ask the active one rather than
+    duplicating the arithmetic here. The slack keeps the bypasser's own deadline expiring
+    first, so the user sees its real error instead of a generic "Download stalled".
+    """
+    bypasser = (
+        _get_external_bypasser() if _is_using_external_bypasser() else _get_internal_bypasser()
+    )
+    return bypasser.max_duration_seconds() + _BYPASS_GRACE_SLACK_SECONDS
+
+
 def get_bypassed_page(
    url: str,
    selector: network.AAMirrorSelector | None = None,
@@ -200,13 +234,50 @@ def _is_retryable_error(e: Exception) -> bool:
    return status is not None and status in RETRYABLE_CODES


+# Statuses that mean the host is gone rather than busy: 410 Gone and 451 Unavailable
+# For Legal Reasons are what a seized domain answers with.
+_DEAD_MIRROR_CODES = (410, 451)
+
+
+def _fatal_mirror_reason(e: Exception) -> str | None:
+    """Return why ``e`` proves the mirror is unusable, or None if it may recover.
+
+    Hard evidence only - the name does not resolve, nothing is listening, or the host
+    says it is gone for good. A timeout, a 5xx or a challenge all mean the mirror is
+    alive, and rotating off it discards the bypass clearance held for that domain.
+    """
+    status = _get_status_code(e)
+    if status is not None and status in _DEAD_MIRROR_CODES:
+        return f"HTTP {status}"
+
+    # requests wraps the real cause; a read timeout subclasses ConnectionError for
+    # some adapters, so exclude timeouts explicitly before inspecting the message.
+    if isinstance(e, requests.exceptions.Timeout):
+        return None
+    if not isinstance(e, requests.exceptions.ConnectionError):
+        return None
+
+    text = str(e).lower()
+    if "nameresolutionerror" in text or "failed to resolve" in text or "name or service" in text:
+        return "DNS does not resolve"
+    if "connection refused" in text or "no route to host" in text:
+        return "connection refused"
+    return None
+
+
 def _try_rotation(
-    original_url: str, current_url: str, selector: network.AAMirrorSelector
+    original_url: str,
+    current_url: str,
+    selector: network.AAMirrorSelector,
+    *,
+    fatal_reason: str | None = None,
 ) -> str | None:
    """Try mirror/DNS rotation. Returns new URL or None."""
    aa_base_url = network.get_aa_base_url()
    if aa_base_url and current_url.startswith(aa_base_url):
-        new_base, action = selector.next_mirror_or_rotate_dns()
+        new_base, action = selector.next_mirror_or_rotate_dns(
+            fatal=fatal_reason is not None, reason=fatal_reason or ""
+        )
        if action in ("mirror", "dns") and new_base:
            new_url = selector.rewrite(original_url)
            logger.info("[%s] switching to: %s", action, new_url)
@@ -238,8 +309,11 @@ def html_get_page(
        selector: Mirror selector used for AA mirror and DNS rotation.
        cancel_flag: Optional event used to abort retries early.
        status_callback: Optional callback for UI status updates.
-        allow_bypasser_fallback: If False, 403 errors will trigger mirror rotation
-            instead of switching to the bypasser. Use for search operations.
+        allow_bypasser_fallback: Whether a challenge may be handed to the bypasser.
+            If False, a 403 triggers mirror rotation instead, and an AA redirect loop
+            gives up immediately rather than waiting on a browser solve. Use False for
+            best-effort fetches whose result is optional (e.g. the download count on
+            the details modal); search and detail pages pass True.
        use_bypasser: Whether to start with the bypasser instead of direct HTTP.
        include_response_url: If True, return `(html, final_url)` to expose the
            resolved response URL after redirects.
@@ -253,6 +327,73 @@ def html_get_page(
            return html, response_url
        return html

+    def _run_bypasser(bypass_url: str) -> str | tuple[str, str]:
+        """Run the active bypasser for one URL and return its result.
+
+        Factored out so the redirect-loop handoff below can invoke it directly. That
+        call site sits inside the inner redirect `while`, so it cannot reach the
+        retry-loop branch above with `continue`, and with MAX_RETRY=1 there is no
+        later attempt for that branch to run on either.
+        """
+        if status_callback:
+            status_callback("resolving", "Bypassing protection...")
+        try:
+            # A bypass is one long blocking call with no incremental progress, so
+            # tell the orchestrator up front how long it may legitimately take
+            # instead of trying to fake activity while it runs. Inside the try so a
+            # bypasser that fails to load is still reported as a bypasser error.
+            request_activity_grace(status_callback, _bypass_grace_seconds())
+            result = get_bypassed_page(bypass_url, selector, cancel_flag)
+            return _result(result or "", bypass_url)
+        except _BYPASSER_ERRORS as e:
+            logger.warning("Bypasser error: %s: %s", type(e).__name__, e)
+            # Surface the real reason. Without this the caller only sees an empty
+            # page and the download dies with a generic failure, hiding e.g. a
+            # FlareSolverr 500 behind a silent wait.
+            if status_callback and not isinstance(e, BypassCancelledError):
+                try:
+                    status_callback("error", f"Bypass failed: {type(e).__name__}: {e}")
+                except _STATUS_CALLBACK_ERRORS:
+                    logger.debug("Bypass error status callback failed", exc_info=True)
+            return _result("", bypass_url)
+        finally:
+            release_activity_grace(status_callback)
+
+    def _bypass_handoff_allowed() -> bool:
+        """Whether a challenge on the current URL may be handed to the bypasser.
+
+        allow_bypasser_fallback is honoured for the same reason the 403 path honours it:
+        callers such as the /dyn/md5/summary fetch behind the details modal pass False
+        precisely so a best-effort request fails fast instead of holding the UI open for
+        a minutes-long browser solve.
+        """
+        return allow_bypasser_fallback and _is_cf_bypass_enabled() and not use_bypasser_now
+
+    def _purge_clearance(target_url: str) -> None:
+        """Drop the host's stored clearance cookies.
+
+        Called whenever the protection answered a request that *carried* cookies:
+        being challenged while presenting them proves they no longer work, so keeping
+        them only guarantees the same rejection on every later request. Purging is
+        internal-bypasser only; with an external one get_cf_cookies_for_domain()
+        already returns {}.
+        """
+        hostname = urlparse(target_url).hostname or ""
+        # An empty domain means "clear every host" to the bypasser, so skip the purge
+        # rather than wipe clearance for sites that are working fine.
+        if hostname and not _is_using_external_bypasser():
+            _get_internal_bypasser().clear_cf_cookies(hostname)
+
+    def _redirect_loop_handoff(bypass_url: str) -> str | tuple[str, str]:
+        """Drop the host's stale clearance cookies, then bypass `bypass_url`.
+
+        A `?check=1` loop is how DDoS-Guard answers a clearance cookie that has gone
+        stale, so the dead cookie has to go before the solve — otherwise it is merged
+        back over the fresh one on the next request and the loop simply resumes.
+        """
+        _purge_clearance(bypass_url)
+        return _run_bypasser(bypass_url)
+
    configured_retry = normalize_positive_int(app_config.MAX_RETRY)
    retry_limit = (
        retry if retry is not None else (configured_retry if configured_retry is not None else 1)
@@ -261,6 +402,9 @@ def html_get_page(
    original_url = url
    current_url = selector.rewrite(original_url)
    use_bypasser_now = use_bypasser
+    # Survives across attempts so a cookie won once is still presented on later retries.
+    handshake_cookies: dict[str, str] = {}
+    handshake_retries = 0

    for attempt in range(1, retry_limit + 1):
        # Check for cancellation before each attempt
@@ -271,36 +415,7 @@ def html_get_page(
        cookies: dict[str, str] = {}
        try:
            if use_bypasser_now and _is_cf_bypass_enabled():
-                if status_callback:
-                    status_callback("resolving", "Bypassing protection...")
-                heartbeat_stop = Event()
-                heartbeat_thread: Thread | None = None
-                if status_callback:
-
-                    def _heartbeat() -> None:
-                        # Keep the download "alive" during long bypass operations so the orchestrator
-                        # doesn't flag it as stalled.
-                        if cancel_flag and cancel_flag.is_set():
-                            return
-                        try:
-                            status_callback("resolving", "Bypassing protection...")
-                        except _STATUS_CALLBACK_ERRORS:
-                            return
-
-                    heartbeat_thread = Thread(
-                        target=_heartbeat, daemon=True, name="BypassHeartbeat"
-                    )
-                    heartbeat_thread.start()
-                try:
-                    result = get_bypassed_page(current_url, selector, cancel_flag)
-                    return _result(result or "", current_url)
-                except _BYPASSER_ERRORS as e:
-                    logger.warning("Bypasser error: %s: %s", type(e).__name__, e)
-                    return _result("", current_url)
-                finally:
-                    heartbeat_stop.set()
-                    if heartbeat_thread:
-                        heartbeat_thread.join(timeout=1)
+                return _run_bypasser(current_url)

            logger.debug("GET: %s", current_url)

@@ -322,12 +437,31 @@ def html_get_page(
                    current_url,
                    proxies=get_proxies(current_url),
                    timeout=REQUEST_TIMEOUT,
-                    cookies=cookies,
+                    # Bypasser-derived cookies win: they came from a real solved challenge.
+                    cookies={**handshake_cookies, **cookies},
                    headers=headers,
                    allow_redirects=allow_redirects,
                    verify=get_ssl_verify(current_url),
                )

+                # Z-Library gates the first hit with a 503 that carries nothing but a
+                # Set-Cookie; echoing it back yields the 302 to the real page. Without this
+                # the cookie is dropped and every retry re-runs the same rejected request.
+                if (
+                    response.status_code == _HTTP_STATUS_SERVICE_UNAVAILABLE
+                    and handshake_retries < _MAX_COOKIE_HANDSHAKE_RETRIES
+                ):
+                    issued = _new_cookies(response, handshake_cookies)
+                    if issued:
+                        handshake_cookies.update(issued)
+                        handshake_retries += 1
+                        logger.debug(
+                            "503 set %s cookie(s); retrying with them: %s",
+                            len(issued),
+                            current_url,
+                        )
+                        continue
+
                if is_aa_url and response.is_redirect:
                    location = response.headers.get("Location", "")
                    if not location:
@@ -356,6 +490,7 @@ def html_get_page(
                            current_url = new_url
                            # Reset per-request state for the new host.
                            headers = {"User-Agent": DOWNLOAD_HEADERS["User-Agent"]}
+                            handshake_cookies.clear()
                            is_aa_url = network.should_rotate_dns_for_url(current_url)
                            allow_redirects = not is_aa_url
                            redirects_followed = 0
@@ -370,9 +505,35 @@ def html_get_page(
                        return _result("", current_url)

                    # Same-host redirect (relative or absolute) - follow manually.
+                    # DDoS-Guard gates AA /search behind a cookie probe: the 302 to
+                    # ?check=1 carries Set-Cookie (__ddg*) which must be echoed back on
+                    # the next hop, or the server just re-issues the redirect forever.
+                    issued = _new_cookies(response, handshake_cookies)
+                    if issued:
+                        handshake_cookies.update(issued)
                    redirects_followed += 1
                    if redirects_followed > _MAX_REDIRECTS:
-                        _raise_too_many_redirects(f"Too many redirects for {current_url}")
+                        # A same-host redirect loop on AA is not a network fault — it is
+                        # how DDoS-Guard presents a handshake that is unsolved, or whose
+                        # clearance cookie has gone stale: /search redirects to
+                        # /search&check=1, which redirects back, indefinitely. Hand it
+                        # straight to the bypasser rather than raising, which would send it
+                        # down the retry path to re-run the whole loop on every attempt
+                        # (10 x 6 = ~60 requests to AA) without ever offering the URL to the
+                        # bypasser. `continue` is no use here either — it would target this
+                        # inner redirect loop rather than the retry branch below.
+                        if _bypass_handoff_allowed():
+                            logger.info(
+                                "Redirect loop detected; switching to bypasser: %s", current_url
+                            )
+                            return _redirect_loop_handoff(current_url)
+                        # No bypasser to hand it to. Every AA mirror shares the challenge,
+                        # so rotating only collects another loop — give up now instead of
+                        # raising and burning the same ~60 requests over the retry budget.
+                        logger.warning(
+                            "Redirect loop and no bypasser available, giving up: %s", current_url
+                        )
+                        return _result("", current_url)
                    current_url = redirect_url
                    continue

@@ -384,6 +545,21 @@ def html_get_page(
        except Exception as e:
            status = _get_status_code(e)

+            # The same DDoS-Guard rescue, for the loops the manual AA follower above hands
+            # back rather than resolving inline — an AA redirect missing its Location
+            # header. TooManyRedirects carries no status, so the 403 rescue below never
+            # fires and every retry would re-send the dead cookies. Scoped to the hosts
+            # whose redirects we follow manually: elsewhere `requests` follows them itself,
+            # and a loop there is an ordinary misconfiguration that a cookie purge and a
+            # minutes-long browser solve would be the wrong answer to.
+            if (
+                isinstance(e, requests.exceptions.TooManyRedirects)
+                and network.should_rotate_dns_for_url(current_url)
+                and _bypass_handoff_allowed()
+            ):
+                logger.info("Redirect loop detected; switching to bypasser: %s", current_url)
+                return _redirect_loop_handoff(current_url)
+
            # 403 = Cloudflare/DDoS-Guard protection
            if status == _HTTP_STATUS_FORBIDDEN:
                # If bypasser fallback is disabled, try mirrors instead
@@ -407,11 +583,21 @@ def html_get_page(
                            current_url,
                        )
                        continue
+                    if cookies:
+                        # Challenged *while presenting* clearance: those cookies are
+                        # dead. Without this they survive the solve and get merged back
+                        # over the fresh ones, so every later request re-presents a
+                        # known-rejected cookie and is challenged again - the stale
+                        # retry that never ends.
+                        logger.debug("403 with cookies presented; purging: %s", current_url)
+                        _purge_clearance(current_url)
                    logger.info("403 detected; switching to bypasser: %s", current_url)
-                    if status_callback:
-                        status_callback("resolving", "Bypassing protection...")
-                    use_bypasser_now = True
-                    continue
+                    # Invoke it here rather than setting use_bypasser_now and continuing.
+                    # The branch that acts on that flag runs at the top of the *next* retry
+                    # attempt, so under the supported MAX_RETRY=1 there is no next attempt
+                    # and the bypasser was never reached — a 403 simply ended the search.
+                    # Same reasoning as the redirect-loop handoffs.
+                    return _run_bypasser(current_url)
                logger.warning("403 error, giving up: %s", current_url)
                return _result("", current_url)

@@ -420,11 +606,17 @@ def html_get_page(
                logger.warning("404 error: %s", current_url)
                return _result("", current_url)

-            # Try mirror/DNS rotation on retryable errors
-            if _is_retryable_error(e):
-                new_url = _try_rotation(original_url, current_url, selector)
+            # Try mirror/DNS rotation on retryable errors. A failure that proves the
+            # mirror is unusable also drops it from this process's rotation, so the
+            # next search does not pay for it again.
+            fatal_reason = _fatal_mirror_reason(e)
+            if fatal_reason or _is_retryable_error(e):
+                new_url = _try_rotation(
+                    original_url, current_url, selector, fatal_reason=fatal_reason
+                )
                if new_url:
                    current_url = new_url
+                    handshake_cookies.clear()
                    continue

            # Retry with backoff
@@ -11,6 +11,7 @@ from socket import AddressFamily, SocketKind
 from typing import TYPE_CHECKING, Any, cast

 import dns.resolver
+import httpx
 import requests
 from dns.exception import DNSException

@@ -277,6 +278,14 @@ _current_aa_url_index = 0
 _aa_urls: list[str] = []  # Initialized lazily in _initialize_aa_state()
 _aa_base_url: str = ""  # Current active AA URL

+# Mirrors quarantined for this process: domains that are not a working AA mirror at
+# all (NXDOMAIN, refused, or a 200 that isn't AA - seized/parked/for-sale domains all
+# land here). Kept separate from ordinary failures: a 403 challenge or a 5xx means the
+# mirror is alive and rotating away from it only discards the DDoS-Guard clearance we
+# hold for it. Deliberately in-memory only, so a restart re-probes everything.
+_dead_aa_urls: set[str] = set()
+_dead_aa_urls_lock = _RLock()
+

 def _ensure_initialized() -> None:
    """Lazy guard so runtime setup happens once and late calls still work."""
@@ -298,6 +307,24 @@ DNS_PROVIDERS = [
    ("opendns", ["208.67.222.222", "208.67.220.220"], "https://doh.opendns.com/dns-query"),
 ]

+# httpx raises its own hierarchy, which shares no base class with requests', so a
+# wireformat failure would escape a requests-only except clause.
+_DOH_REQUEST_ERRORS = (OSError, ValueError, requests.RequestException, httpx.HTTPError)
+
+
+def _first_proxy(proxies: dict[str, str] | None) -> str | None:
+    """Pick a single proxy URL from a requests-style mapping, for httpx."""
+    if not proxies:
+        return None
+    return proxies.get("https") or proxies.get("http") or None
+
+
+# DoH providers that speak RFC 8484 wireformat rather than the (non-standard) JSON API
+# Cloudflare and Google popularised. Verified against the live services: both reject a
+# ?name=&type= query outright - Quad9 with 505 (it also mandates HTTP/2 per RFC 8484
+# section 5.2, which requests cannot speak), OpenDNS with 400 "No valid query received".
+_DOH_WIREFORMAT_HOSTS = frozenset({"dns.quad9.net", "doh.opendns.com"})
+
 # Domain patterns that should trigger DNS rotation on failure
 DNS_ROTATION_DOMAINS = [
    "annas-archive",
@@ -462,8 +489,16 @@ class DoHResolver:
        # DNS cache: {(hostname, record_type): (ip_list, timestamp)}
        self._cache: dict[tuple[str, str], tuple[list[str], datetime]] = {}

-        # Different headers based on provider
-        if "google" in self.base_url:
+        # RFC 8484 providers get a separate transport: they need wireformat, and Quad9
+        # additionally refuses HTTP/1.1, which requests has no way to upgrade from.
+        self.use_wireformat = urllib.parse.urlparse(self.base_url).hostname in (
+            _DOH_WIREFORMAT_HOSTS
+        )
+        self._http2_client: Any | None = None
+
+        if self.use_wireformat:
+            self.session.headers.update({"Accept": "application/dns-message"})
+        elif "google" in self.base_url:
            self.session.headers.update(
                {
                    "Accept": "application/json",
@@ -476,6 +511,35 @@ class DoHResolver:
                }
            )

+    def _get_http2_client(self) -> Any:
+        """Lazily build the HTTP/2 client used for RFC 8484 providers.
+
+        Built on first use so a resolver pointed at a JSON provider never opens an
+        HTTP/2 connection pool it will not use.
+        """
+        if self._http2_client is None:
+            self._http2_client = httpx.Client(
+                http2=True,
+                timeout=10,
+                verify=get_ssl_verify(self.base_url),
+                proxy=_first_proxy(get_proxies(self.base_url)),
+            )
+        return self._http2_client
+
+    def _resolve_wireformat(self, hostname: str, record_type: str) -> list[str]:
+        """Resolve via RFC 8484: base64url query in, DNS message out."""
+        from shelfmark.download import doh_wireformat
+
+        qtype = doh_wireformat.TYPE_AAAA if record_type == "AAAA" else doh_wireformat.TYPE_A
+        param = doh_wireformat.encode_query_param(hostname, qtype)
+        response = self._get_http2_client().get(
+            self.base_url,
+            params={"dns": param},
+            headers={"Accept": "application/dns-message"},
+        )
+        response.raise_for_status()
+        return doh_wireformat.decode_answer(response.content, qtype)
+
    def _get_cached(self, hostname: str, record_type: str) -> list[str] | None:
        """Get cached DNS result if still valid."""
        key = (hostname, record_type)
@@ -525,34 +589,37 @@ class DoHResolver:
            return cached

        try:
-            params = {"name": hostname, "type": "AAAA" if record_type == "AAAA" else "A"}
+            if self.use_wireformat:
+                answers = self._resolve_wireformat(hostname, record_type)
+            else:
+                params = {"name": hostname, "type": "AAAA" if record_type == "AAAA" else "A"}

-            response = self.session.get(
-                self.base_url,
-                params=params,
-                proxies=get_proxies(self.base_url),
-                timeout=10,  # Increased from 5s to handle slow network conditions
-                verify=get_ssl_verify(self.base_url),
-            )
-            response.raise_for_status()
+                response = self.session.get(
+                    self.base_url,
+                    params=params,
+                    proxies=get_proxies(self.base_url),
+                    timeout=10,  # Increased from 5s to handle slow network conditions
+                    verify=get_ssl_verify(self.base_url),
+                )
+                response.raise_for_status()

-            data = response.json()
-            if "Answer" not in data:
-                logger.warning("DoH resolution failed for %s: %s", hostname, data)
-                return []
+                data = response.json()
+                if "Answer" not in data:
+                    logger.warning("DoH resolution failed for %s: %s", hostname, data)
+                    return []

-            # Extract IP addresses from the response
-            answers = [
-                answer["data"]
-                for answer in data["Answer"]
-                if answer.get("type") == (28 if record_type == "AAAA" else 1)
-            ]
+                # Extract IP addresses from the response
+                answers = [
+                    answer["data"]
+                    for answer in data["Answer"]
+                    if answer.get("type") == (28 if record_type == "AAAA" else 1)
+                ]

            # Cache the result
            self._set_cached(hostname, record_type, answers)

            # Don't log here - the caller (custom_getaddrinfo) will log the final result
-        except (OSError, ValueError, requests.RequestException) as e:
+        except _DOH_REQUEST_ERRORS as e:
            logger.warning("DoH resolution failed for %s: %s", hostname, e)
            return []
        else:
@@ -616,8 +683,6 @@ def create_custom_getaddrinfo(
            source: str,
            provider_label: str,
            res: Sequence[tuple[AddressFamily, SocketKind, int, str, tuple[Any, ...]]],
-            *,
-            is_bypass: bool = False,
        ) -> None:
            """Emit a unified resolver log with the IPs returned.

@@ -625,7 +690,6 @@ def create_custom_getaddrinfo(
                source: Description of resolver source
                provider_label: Label for the DNS provider
                res: Resolution results
-                is_bypass: If True, log at DEBUG level (for local/IP addresses)

            """
            # Skip logging entirely for localhost to reduce noise
@@ -641,11 +705,7 @@ def create_custom_getaddrinfo(
                ip = sockaddr[0]
                if isinstance(ip, str):
                    ips.append(ip)
-            msg = f"Resolved {host_str} via {source} [{provider_label}]: {ips}"
-            if is_bypass:
-                logger.debug(msg)
-            else:
-                logger.info(msg)
+            logger.debug("Resolved %s via %s [%s]: %s", host_str, source, provider_label, ips)

        # Skip custom resolution for IP addresses, local addresses, or if skip check passes
        if (
@@ -655,7 +715,7 @@ def create_custom_getaddrinfo(
        ):
            # Quietly bypass custom resolution for IP/local targets
            res = original_getaddrinfo(host, port, family, socket_type, proto, flags)
-            _log_results("system resolver (bypass)", "system", res, is_bypass=True)
+            _log_results("system resolver (bypass)", "system", res)
            return res

        results: list[tuple[AddressFamily, SocketKind, int, str, tuple[Any, ...]]] = []
@@ -1015,14 +1075,18 @@ def rotate_dns_and_reset_aa() -> bool:
    configured_url = _get_configured_aa_url()

    if configured_url == "auto":
-        # Auto mode always resets to the first mirror to restart the cascade
-        _current_aa_url_index = 0
-        if _aa_urls:
-            _aa_base_url = _aa_urls[0]
+        # Auto mode always resets to the first mirror to restart the cascade. Skip any
+        # quarantined ones: a new DNS provider cannot revive a parked or seized domain.
+        with _dead_aa_urls_lock:
+            restart_urls = [url for url in _aa_urls if url not in _dead_aa_urls] or _aa_urls
+        if restart_urls:
+            _aa_base_url = restart_urls[0]
+            _current_aa_url_index = _aa_urls.index(_aa_base_url)
            logger.info("After DNS switch, resetting AA URL to: %s", _aa_base_url)
            _save_state(aa_url=_aa_base_url)
        else:
            _aa_base_url = ""
+            _current_aa_url_index = 0
            logger.info("After DNS switch, AA URL remains unconfigured")
    else:
        # Keep the user's configured primary mirror (if it exists in the list),
@@ -1192,8 +1256,17 @@ def _initialize_aa_state() -> None:
    global _aa_base_url, _current_aa_url_index, _aa_urls

    # Build URL list from config
+    previous_urls = _aa_urls
    _aa_urls = _build_aa_urls()

+    # Drop quarantine decisions only when the mirror list itself changed - they were
+    # made about a list that no longer applies. This runs on every re-init (settings
+    # sync, DNS rotation, helper subprocess startup), and clearing unconditionally
+    # would resurrect a parked mirror mid-session.
+    if previous_urls != _aa_urls:
+        with _dead_aa_urls_lock:
+            _dead_aa_urls.clear()
+
    # Get configured base URL from config
    configured_url = _get_configured_aa_url()

@@ -1209,26 +1282,34 @@ def _initialize_aa_state() -> None:
        return

    if configured_url == "auto":
-        if state.get("aa_base_url") and state["aa_base_url"] in _aa_urls:
-            _current_aa_url_index = _aa_urls.index(state["aa_base_url"])
-            _aa_base_url = state["aa_base_url"]
+        # Never restore or probe a mirror quarantined this session: re-init happens
+        # often, and re-electing a parked domain costs a wasted request every time
+        # (its parking page answers 200, so the probe would happily pick it).
+        with _dead_aa_urls_lock:
+            candidates = [url for url in _aa_urls if url not in _dead_aa_urls]
+        restored = state.get("aa_base_url")
+        if restored and restored in candidates:
+            _current_aa_url_index = _aa_urls.index(restored)
+            _aa_base_url = restored
        else:
-            logger.debug("AA_BASE_URL: auto, checking available urls %s", _aa_urls)
-            for i, url in enumerate(_aa_urls):
+            logger.debug("AA_BASE_URL: auto, checking available urls %s", candidates)
+            for url in candidates:
                try:
                    response = requests.get(
                        url, proxies=get_proxies(url), timeout=3, verify=get_ssl_verify(url)
                    )
                    if response.status_code == HTTPStatus.OK:
-                        _current_aa_url_index = i
+                        _current_aa_url_index = _aa_urls.index(url)
                        _aa_base_url = url
                        _save_state(aa_url=_aa_base_url)
                        break
                except (OSError, requests.RequestException) as exc:
                    logger.debug("Could not reach AA mirror candidate %s: %s", url, exc)
-            if not _aa_base_url or _aa_base_url == "auto":
-                _aa_base_url = _aa_urls[0]
-                _current_aa_url_index = 0
+            # Also covers the case where every probe failed and the previous base is
+            # itself quarantined - keeping it would aim the next search at a dead host.
+            if not _aa_base_url or _aa_base_url == "auto" or _aa_base_url not in candidates:
+                _aa_base_url = (candidates or _aa_urls)[0]
+                _current_aa_url_index = _aa_urls.index(_aa_base_url)
    elif configured_url not in _aa_urls:
        logger.info("AA_BASE_URL set to custom value %s; skipping auto-switch", configured_url)
        _aa_base_url = configured_url
@@ -1326,24 +1407,77 @@ def is_aa_auto_mode() -> bool:


 def get_available_aa_urls() -> list[str]:
-    """Get list of configured AA URLs (copy)."""
+    """Get configured AA URLs (copy), minus any quarantined this process.
+
+    Falls back to the full list when every mirror has been quarantined: a wrong
+    classification must not leave the app with nowhere to search.
+    """
    _ensure_initialized()
-    return _aa_urls.copy()
+    with _dead_aa_urls_lock:
+        alive = [url for url in _aa_urls if url not in _dead_aa_urls]
+        if not alive and _aa_urls:
+            logger.warning("All AA mirrors quarantined; retrying the full list")
+            _dead_aa_urls.clear()
+            return _aa_urls.copy()
+    return alive


-def set_aa_url_index(new_index: int) -> bool:
-    """Set AA base URL by index in available list; returns True if applied."""
+def _aa_base_for_url(url: str) -> str:
+    """Return the configured mirror base that ``url`` belongs to, if any."""
+    for base in _aa_urls:
+        if base and url.startswith(base):
+            return base
+    return ""
+
+
+def mark_aa_url_dead(url: str, reason: str) -> bool:
+    """Quarantine an AA mirror for the rest of this process.
+
+    Only for hard evidence that the host is not a working AA mirror. Transient
+    failures (403 challenge, 429, 5xx, timeouts) must never come through here -
+    quarantining a live mirror throws away its bypass clearance.
+    """
+    _ensure_initialized()
+    base = _aa_base_for_url(url) or url
+    with _dead_aa_urls_lock:
+        if base not in _aa_urls or base in _dead_aa_urls:
+            return False
+        # Keep at least one mirror in play, even if it is the failing one.
+        if len([u for u in _aa_urls if u not in _dead_aa_urls]) <= 1:
+            logger.warning("Not quarantining last remaining AA mirror %s (%s)", base, reason)
+            return False
+        _dead_aa_urls.add(base)
+    logger.warning("Quarantined AA mirror %s for this session: %s", base, reason)
+    return True
+
+
+def get_dead_aa_urls() -> set[str]:
+    """Return the mirrors quarantined this process (copy)."""
+    with _dead_aa_urls_lock:
+        return set(_dead_aa_urls)
+
+
+def set_aa_url(url: str) -> bool:
+    """Set the active AA base URL; returns True if applied."""
    _ensure_initialized()
    global _aa_base_url, _current_aa_url_index
-    if new_index < 0 or new_index >= len(_aa_urls):
+    if url not in _aa_urls:
        return False
-    _current_aa_url_index = new_index
-    _aa_base_url = _aa_urls[_current_aa_url_index]
+    _current_aa_url_index = _aa_urls.index(url)
+    _aa_base_url = url
    logger.info("Set AA URL to: %s", _aa_base_url)
    _save_state(aa_url=_aa_base_url)
    return True


+def set_aa_url_index(new_index: int) -> bool:
+    """Set AA base URL by index in the full configured list; True if applied."""
+    _ensure_initialized()
+    if new_index < 0 or new_index >= len(_aa_urls):
+        return False
+    return set_aa_url(_aa_urls[new_index])
+
+
 class AAMirrorSelector:
    """Keep AA mirror switching consistent across call sites.

@@ -1357,6 +1491,10 @@ class AAMirrorSelector:
    def _ensure_fresh_state(self, *, reset_attempts: bool = False) -> None:
        _ensure_initialized()
        self.aa_urls = get_available_aa_urls()
+        # Rotation walks the live mirrors, but rewriting has to recognise every
+        # configured base: a URL built before a mirror was quarantined still points at
+        # it, and failing to rewrite would send the retry back to the dead host.
+        self.all_aa_urls = _aa_urls.copy()
        self._index = self._safe_index(get_aa_base_url())
        self.current_base = self.aa_urls[self._index] if self.aa_urls else ""
        if reset_attempts:
@@ -1369,16 +1507,41 @@ class AAMirrorSelector:

    def rewrite(self, url: str) -> str:
        """Replace any known AA base in url with current_base."""
-        for base in self.aa_urls:
+        for base in self.all_aa_urls:
            if url.startswith(base):
                return url.replace(base, self.current_base, 1)
        return url

-    def next_mirror_or_rotate_dns(self, *, allow_dns: bool = True) -> tuple[str | None, str]:
+    def quarantine_current(self, reason: str) -> bool:
+        """Quarantine the mirror this selector is on (hard failures only)."""
+        if not self.current_base:
+            return False
+        dropped = mark_aa_url_dead(self.current_base, reason)
+        if dropped:
+            # Rebuild from the surviving mirrors so the dead one is out of the cycle.
+            self._ensure_fresh_state(reset_attempts=False)
+        return dropped
+
+    def next_mirror_or_rotate_dns(
+        self, *, allow_dns: bool = True, fatal: bool = False, reason: str = ""
+    ) -> tuple[str | None, str]:
        """Advance to the next mirror or rotate DNS if needed.

+        ``fatal`` marks the current mirror as not-an-AA-mirror (NXDOMAIN, refused, a
+        200 that isn't AA) and drops it from this process's rotation. Leave it False
+        for anything the mirror can recover from - a challenge or a 5xx means the host
+        is alive, and quarantining it would discard its bypass clearance.
+
        Returns (new_base, action) where action is 'mirror', 'dns', or 'exhausted'.
        """
+        if fatal and self.quarantine_current(reason or "unusable mirror"):
+            # Quarantining rebuilt the state onto a surviving mirror, so that mirror is
+            # the next one to try - advancing again here would skip straight past it.
+            self.attempts_this_dns += 1
+            if self.current_base and is_aa_auto_mode():
+                set_aa_url(self.current_base)
+                return self.current_base, "mirror"
+
        self.attempts_this_dns += 1
        max_attempts = len(self.aa_urls) if is_aa_auto_mode() else 1
        if self.attempts_this_dns >= max_attempts:
@@ -1391,8 +1554,11 @@ class AAMirrorSelector:
            # Mirror is explicitly configured; do not fail over to other mirrors.
            return None, "exhausted"

+        if not self.aa_urls:
+            return None, "exhausted"
+
        next_index = (self._index + 1) % len(self.aa_urls)
-        set_aa_url_index(next_index)
+        set_aa_url(self.aa_urls[next_index])
        self._ensure_fresh_state(reset_attempts=False)
        return self.current_base, "mirror"

@@ -12,7 +12,7 @@ from concurrent.futures import Future, ThreadPoolExecutor
 from email.utils import parseaddr
 from pathlib import Path
 from threading import Event, Lock
-from typing import Any
+from typing import TYPE_CHECKING, Any

 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
@@ -24,6 +24,7 @@ from shelfmark.core.request_helpers import (
 )
 from shelfmark.core.utils import is_audiobook as check_audiobook
 from shelfmark.core.utils import transform_cover_url
+from shelfmark.download.activity import parse_activity_grace
 from shelfmark.download.fs import run_blocking_io
 from shelfmark.download.postprocess.pipeline import is_torrent_source, safe_cleanup_path
 from shelfmark.download.postprocess.router import post_process_download
@@ -33,6 +34,9 @@ from shelfmark.release_sources import (
    get_source_display_name,
 )

+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
 logger = setup_logger(__name__)
 _RNG = random.SystemRandom()

@@ -65,7 +69,16 @@ _last_progress_value: dict[str, float] = {}
 # De-duplicate status updates (keep-alive updates shouldn't spam clients)
 _last_status_event: dict[str, tuple[str, str | None]] = {}
 STALL_TIMEOUT = 300  # 5 minutes without progress/status update = stalled
+# Absolute deadlines (time.time()) until which stall detection is suppressed for a task.
+# Long single-shot operations (protection bypass, etc.) declare their own upper bound via
+# `shelfmark.download.activity` instead of faking progress. See set_activity_grace().
+_activity_grace: dict[str, float] = {}
+# A caller cannot buy immortality: the largest grace any operation may request. Must stay
+# above the largest budget any caller can declare (see http._bypass_grace_seconds).
+_MAX_ACTIVITY_GRACE_SECONDS = 960.0
 COORDINATOR_LOOP_ERROR_RETRY_DELAY = 1.0
+# Ceiling for the exponential backoff applied to repeated coordinator loop failures.
+_COORDINATOR_LOOP_ERROR_MAX_DELAY = 30.0
 _PROGRESS_BROADCAST_START_PERCENT = 1
 _PROGRESS_BROADCAST_COMPLETE_PERCENT = 99
 _PROGRESS_BROADCAST_MIN_DELTA = 10
@@ -170,16 +183,19 @@ def _build_retry_resolution_fields(
    retry_download_url = normalize_optional_text(release_data.get("download_url"))
    protocol = normalize_optional_text(release_data.get("protocol"))
    source = normalize_optional_text(release_data.get("source"))
+    retry_source_context: dict[str, Any] = {}
    if source is not None:
        handler = get_handler(source)
        source_retry_fields = handler.build_retry_resolution_fields(release_data)
-        retry_download_url = (
-            normalize_optional_text(source_retry_fields.get("retry_download_url"))
-            or retry_download_url
-        )
-        protocol = (
-            normalize_optional_text(source_retry_fields.get("retry_download_protocol")) or protocol
-        )
+        if "retry_download_url" in source_retry_fields:
+            retry_download_url = normalize_optional_text(
+                source_retry_fields.get("retry_download_url")
+            )
+        if "retry_download_protocol" in source_retry_fields:
+            protocol = normalize_optional_text(source_retry_fields.get("retry_download_protocol"))
+        raw_retry_source_context = source_retry_fields.get("retry_source_context")
+        if isinstance(raw_retry_source_context, dict):
+            retry_source_context = dict(raw_retry_source_context)

    ratio_limit = _optional_number(release_data.get("ratio_limit"))
    if ratio_limit is None and config.get("PROWLARR_USE_SEED_PREFERENCES", False):
@@ -202,6 +218,7 @@ def _build_retry_resolution_fields(
        ),
        "retry_ratio_limit": ratio_limit,
        "retry_seeding_time_limit_minutes": seeding_time_limit_minutes,
+        "retry_source_context": retry_source_context,
        "can_retry_without_staged_source": True,
    }

@@ -247,6 +264,7 @@ def queue_release(
        series_name = release_data.get("series_name") or extra.get("series_name")
        series_position = release_data.get("series_position") or extra.get("series_position")
        subtitle = release_data.get("subtitle") or extra.get("subtitle")
+        language = release_data.get("language") or extra.get("language")

        books_output_mode = (
            str(config.get("BOOKS_OUTPUT_MODE", "folder", user_id=user_id) or "folder")
@@ -281,6 +299,7 @@ def queue_release(
            series_name=series_name,
            series_position=series_position,
            subtitle=subtitle,
+            language=language,
            search_mode=search_mode,
            output_mode=output_mode,
            output_args=output_args,
@@ -400,6 +419,7 @@ def serialize_task_for_retry(task: DownloadTask) -> dict[str, Any]:
        search_mode = normalized_search_mode or None

    raw_output_args = getattr(task, "output_args", None)
+    raw_retry_source_context = getattr(task, "retry_source_context", None)

    return {
        "task_id": getattr(task, "task_id", None),
@@ -415,6 +435,7 @@ def serialize_task_for_retry(task: DownloadTask) -> dict[str, Any]:
        "series_name": getattr(task, "series_name", None),
        "series_position": getattr(task, "series_position", None),
        "subtitle": getattr(task, "subtitle", None),
+        "language": getattr(task, "language", None),
        "search_mode": search_mode,
        "output_mode": getattr(task, "output_mode", None),
        "output_args": dict(raw_output_args) if isinstance(raw_output_args, dict) else {},
@@ -428,6 +449,9 @@ def serialize_task_for_retry(task: DownloadTask) -> dict[str, Any]:
        "retry_expected_hash": getattr(task, "retry_expected_hash", None),
        "retry_ratio_limit": getattr(task, "retry_ratio_limit", None),
        "retry_seeding_time_limit_minutes": getattr(task, "retry_seeding_time_limit_minutes", None),
+        "retry_source_context": (
+            dict(raw_retry_source_context) if isinstance(raw_retry_source_context, dict) else {}
+        ),
        "can_retry_without_staged_source": bool(
            getattr(task, "can_retry_without_staged_source", True)
        ),
@@ -453,6 +477,7 @@ def _restore_task_from_retry_payload(payload: object) -> DownloadTask | None:
            search_mode = None

    output_args = payload.get("output_args")
+    retry_source_context = payload.get("retry_source_context")

    return DownloadTask(
        task_id=task_id,
@@ -468,6 +493,7 @@ def _restore_task_from_retry_payload(payload: object) -> DownloadTask | None:
        series_name=normalize_optional_text(payload.get("series_name")),
        series_position=_optional_number(payload.get("series_position")),
        subtitle=normalize_optional_text(payload.get("subtitle")),
+        language=normalize_optional_text(payload.get("language")),
        search_mode=search_mode,
        output_mode=normalize_optional_text(payload.get("output_mode")),
        output_args=dict(output_args) if isinstance(output_args, dict) else {},
@@ -483,6 +509,9 @@ def _restore_task_from_retry_payload(payload: object) -> DownloadTask | None:
        retry_seeding_time_limit_minutes=_optional_positive_int(
            payload.get("retry_seeding_time_limit_minutes")
        ),
+        retry_source_context=(
+            dict(retry_source_context) if isinstance(retry_source_context, dict) else {}
+        ),
        can_retry_without_staged_source=bool(payload.get("can_retry_without_staged_source", True)),
    )

@@ -633,6 +662,17 @@ def _download_task(task_id: str, cancel_flag: Event) -> str | None:
        update_download_progress(task_id, progress)

    def status_callback(status: str, message: str | None = None) -> None:
+        # Liveness hint from a long single-shot operation, not a user-visible status.
+        # Handled here so it never reaches update_download_status (which dedupes status
+        # transitions on purpose). See shelfmark.download.activity.
+        grace = parse_activity_grace(status, message)
+        if grace is not None:
+            if grace > 0:
+                set_activity_grace(task_id, grace)
+            else:
+                clear_activity_grace(task_id)
+            return
+
        status_key = status.lower()
        if status_key == "error":
            _capture_task_error(
@@ -870,6 +910,7 @@ def _cleanup_progress_tracking(task_id: str) -> None:
        _last_activity.pop(task_id, None)
        _last_progress_value.pop(task_id, None)
        _last_status_event.pop(task_id, None)
+        _activity_grace.pop(task_id, None)


 def _finalize_download_failure(task_id: str) -> None:
@@ -917,6 +958,66 @@ def _process_single_download(task_id: str, cancel_flag: Event) -> None:
        ws_manager.broadcast_status_update(queue_status())


+def set_activity_grace(book_id: str, seconds: float) -> None:
+    """Suppress stall detection for `book_id` for up to `seconds` from now.
+
+    For long single-shot operations that cannot report incremental progress (protection
+    bypass being the motivating case). The grace is a single absolute deadline computed
+    once, so it cannot be extended into immortality by a keep-alive that carries no real
+    liveness information - an operation that hangs forever is still cancelled once its
+    declared budget expires.
+
+    Deliberately touches neither the queue nor the WebSocket: this is a liveness
+    assertion, not a user-visible status transition.
+    """
+    grace = _config_float(seconds, 0.0)
+    grace = min(max(grace, 0.0), _MAX_ACTIVITY_GRACE_SECONDS)
+    with _progress_lock:
+        _activity_grace[book_id] = time.time() + grace
+
+
+def clear_activity_grace(book_id: str) -> None:
+    """Drop any activity grace for `book_id` and count this moment as activity.
+
+    Resetting `_last_activity` means a nested or abandoned grace degrades to a fresh
+    full STALL_TIMEOUT window rather than an immediate stall.
+    """
+    with _progress_lock:
+        _activity_grace.pop(book_id, None)
+        _last_activity[book_id] = time.time()
+
+
+def _find_stalled_tasks(task_ids: Iterable[str], now: float) -> list[str]:
+    """Return the task ids with no activity inside STALL_TIMEOUT and no active grace.
+
+    Holds `_progress_lock` for dict reads only - never call into `book_queue` from here,
+    see _cancel_stalled_task().
+    """
+    stalled: list[str] = []
+    with _progress_lock:
+        for task_id in task_ids:
+            last_active = _last_activity.get(task_id, now)
+            deadline = max(last_active + STALL_TIMEOUT, _activity_grace.get(task_id, 0.0))
+            if now > deadline:
+                stalled.append(task_id)
+    return stalled
+
+
+def _cancel_stalled_task(task_id: str) -> None:
+    """Cancel a stalled download.
+
+    Must be called WITHOUT `_progress_lock` held. `book_queue.cancel_download` runs the
+    terminal-status hooks, which reach a sqlite write that gevent does not patch; holding
+    the progress lock across that blocks the hub and every other download worker.
+    """
+    logger.warning("Download stalled for %s, cancelling", task_id)
+    book_queue.cancel_download(task_id)
+    book_queue.update_status_message(
+        task_id,
+        f"Download stalled (no activity for {STALL_TIMEOUT}s)",
+    )
+
+
 def concurrent_download_loop() -> None:
    """Run the main concurrent download coordinator."""
    max_workers = normalize_positive_int(config.MAX_CONCURRENT_DOWNLOADS) or 1
@@ -926,6 +1027,7 @@ def concurrent_download_loop() -> None:
    with ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="Download") as executor:
        active_futures: dict[Future, tuple[str, Event]] = {}  # Track active download futures
        stalled_tasks: set[str] = set()  # Track tasks already cancelled due to stall
+        consecutive_errors = 0

        while True:
            try:
@@ -976,19 +1078,14 @@ def concurrent_download_loop() -> None:

                # Check for stalled downloads (no activity in STALL_TIMEOUT seconds)
                current_time = time.time()
-                with _progress_lock:
-                    for _future, (task_id, _cancel_flag) in list(active_futures.items()):
-                        if task_id in stalled_tasks:
-                            continue
-                        last_active = _last_activity.get(task_id, current_time)
-                        if current_time - last_active > STALL_TIMEOUT:
-                            logger.warning("Download stalled for %s, cancelling", task_id)
-                            book_queue.cancel_download(task_id)
-                            book_queue.update_status_message(
-                                task_id,
-                                f"Download stalled (no activity for {STALL_TIMEOUT}s)",
-                            )
-                            stalled_tasks.add(task_id)
+                candidates = [
+                    task_id
+                    for _future, (task_id, _cancel_flag) in list(active_futures.items())
+                    if task_id not in stalled_tasks
+                ]
+                for task_id in _find_stalled_tasks(candidates, current_time):
+                    _cancel_stalled_task(task_id)
+                    stalled_tasks.add(task_id)

                # Start new downloads if we have capacity
                while len(active_futures) < max_workers:
@@ -1011,9 +1108,24 @@ def concurrent_download_loop() -> None:

                # Brief sleep to prevent busy waiting
                time.sleep(main_loop_sleep_time)
-            except (AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError) as e:
+                consecutive_errors = 0
+            # This loop is the only thing driving the download queue; if it exits, nothing
+            # is ever picked up again and the app looks healthy while doing nothing (#823,
+            # #1166). A narrow exception list let gevent's LoopExit and friends through, so
+            # catch everything short of BaseException - GreenletExit and gevent.Timeout must
+            # still propagate, and the tests' loop-stopping sentinels derive from
+            # BaseException for exactly this reason.
+            except Exception as e:  # noqa: BLE001 - coordinator loop must never die
+                consecutive_errors += 1
                logger.error_trace("Download coordinator loop error: %s", e)
-                time.sleep(COORDINATOR_LOOP_ERROR_RETRY_DELAY)
+                # Back off when the failure is persistent so we don't spin at 1Hz forever,
+                # but keep the first delay unchanged for a normal transient blip.
+                time.sleep(
+                    min(
+                        COORDINATOR_LOOP_ERROR_RETRY_DELAY * 2 ** min(consecutive_errors - 1, 5),
+                        _COORDINATOR_LOOP_ERROR_MAX_DELAY,
+                    )
+                )


 # Download coordinator thread (started explicitly via start())
@@ -229,6 +229,7 @@ def _build_custom_script_payload(
            "series_name": context.task.series_name,
            "series_position": context.task.series_position,
            "subtitle": context.task.subtitle,
+            "language": context.task.language,
            "original_download_path": context.task.original_download_path,
        },
        "output": {
@@ -3,7 +3,6 @@
 from __future__ import annotations

 import contextlib
-import uuid
 from typing import TYPE_CHECKING

 from shelfmark.core.logger import setup_logger
@@ -13,7 +12,11 @@ from shelfmark.core.utils import (
 from shelfmark.core.utils import (
    is_audiobook as check_audiobook,
 )
-from shelfmark.download.fs import run_blocking_io
+from shelfmark.download.fs import (
+    clear_delete_denied,
+    mark_delete_denied,
+    run_blocking_io,
+)
 from shelfmark.download.permissions_debug import log_path_permission_context
 from shelfmark.release_sources import get_source

@@ -25,6 +28,8 @@ if TYPE_CHECKING:

 logger = setup_logger("shelfmark.download.postprocess.pipeline")

+_WRITE_PROBE_NAME = ".shelfmark_write_test.tmp"
+

 def validate_destination(
    destination: Path, status_callback: Callable[[str, str | None], None]
@@ -52,7 +57,9 @@ def validate_destination(
            status_callback("error", f"Cannot create destination: {destination} ({exc})")
            return False

-    test_path = destination / f".shelfmark_write_test_{uuid.uuid4().hex}.tmp"
+    # Stable name: on shares that refuse deletes the probe file cannot be cleaned
+    # up, so reusing one name bounds the leftovers at a single hidden file.
+    test_path = destination / _WRITE_PROBE_NAME

    try:
        test_content = (
@@ -60,7 +67,6 @@ def validate_destination(
            "It should've been automatically deleted. Feel free to delete it.\n"
        )
        run_blocking_io(test_path.write_text, test_content)
-        run_blocking_io(test_path.unlink, missing_ok=True)
    except OSError as exc:
        logger.debug("Destination write probe path: %s", test_path)
        log_path_permission_context("destination_write_probe", destination)
@@ -71,6 +77,23 @@ def validate_destination(
                run_blocking_io(destination.rmdir)
        return False

+    try:
+        run_blocking_io(test_path.unlink, missing_ok=True)
+    except OSError as exc:
+        # Writable but not deletable, e.g. a Synology share with "Delete
+        # subfolders and files" unticked. Not fatal: record it so transfers write
+        # files in place instead of publishing a temp file via rename.
+        mark_delete_denied(destination)
+        logger.warning(
+            "Destination %s is writable but refuses deletes (%s); leaving probe file %s "
+            "behind and writing files in place",
+            destination,
+            exc,
+            test_path.name,
+        )
+    else:
+        clear_delete_denied(destination)
+
    return True


@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING

 from shelfmark.core.logger import setup_logger
+from shelfmark.core.utils import AUDIOBOOK_FORMATS
 from shelfmark.core.utils import is_audiobook as check_audiobook
 from shelfmark.download.archive import ArchiveExtractionError, extract_archive, is_archive
 from shelfmark.download.fs import run_blocking_io
@@ -142,7 +143,7 @@ def scan_directory_tree(

    is_audiobook = check_audiobook(content_type)
    if is_audiobook:
-        trackable_exts = {".m4b", ".mp3", ".m4a", ".flac", ".ogg", ".wma", ".aac", ".wav"}
+        trackable_exts = {f".{fmt}" for fmt in AUDIOBOOK_FORMATS}
    else:
        trackable_exts = {
            ".pdf",
@@ -367,7 +368,7 @@ def collect_staged_files(

    is_audiobook = check_audiobook(task.content_type)
    if is_audiobook:
-        trackable_exts = {".m4b", ".mp3", ".m4a", ".flac", ".ogg", ".wma", ".aac", ".wav"}
+        trackable_exts = {f".{fmt}" for fmt in AUDIOBOOK_FORMATS}
    else:
        trackable_exts = {
            ".pdf",
@@ -12,6 +12,7 @@ from shelfmark.core.naming import (
    assign_part_numbers,
    build_library_path,
    derive_primary_title,
+    normalize_language_code,
    parse_naming_template,
    sanitize_filename,
 )
@@ -63,6 +64,7 @@ def build_metadata_dict(task: DownloadTask) -> dict:
        "Year": task.year,
        "Series": task.series_name,
        "SeriesPosition": task.series_position,
+        "Language": normalize_language_code(task.language),
        "User": task.username,
    }

@@ -0,0 +1,134 @@
+"""Boot-time warm-up of the direct-download source.
+
+The first AA search after a cold start pays for the whole cold path at once: DNS
+resolution, electing a live mirror, spinning up headless Chrome and solving the
+DDoS-Guard challenge. That is tens of seconds with the user sat at the search box.
+
+Running one throwaway search shortly after boot moves that cost off the user's first
+search. It primes the DNS cache, elects (and quarantines) mirrors, and leaves the
+clearance cookie in the bypasser's per-domain cache, so the first real search reuses
+it instead of solving from scratch.
+
+Runs on a daemon thread and swallows every failure: this is an optimisation, and a
+source that is down at boot must not affect startup or health.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+
+from shelfmark.core.config import config
+from shelfmark.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+# Delay before the warm-up fires. Long enough that it does not compete with the rest
+# of startup (and with a container's own health probe) for the first request.
+_DEFAULT_DELAY_SECONDS = 15.0
+
+_DEFAULT_QUERY = "The Great Gatsby"
+
+_warmup_thread: threading.Thread | None = None
+_warmup_lock = threading.Lock()
+
+
+def _as_bool(value: object, *, default: bool) -> bool:
+    """Coerce a config value that may arrive as a string, bool or None."""
+    if value is None:
+        return default
+    if isinstance(value, str):
+        from shelfmark.config.env import string_to_bool
+
+        return string_to_bool(value)
+    return bool(value)
+
+
+def _setting(key: str, default: object) -> object:
+    """Read a warm-up setting, preferring the deployment environment.
+
+    These keys are not in the settings registry, and ``config.get`` only consults the
+    environment for keys it knows about - so reading config alone silently ignored
+    SEARCH_WARMUP_ENABLED and always returned the default. Check os.environ first so
+    the documented switches actually work.
+    """
+    raw = os.environ.get(key)
+    if raw is not None and raw.strip():
+        return raw
+    return config.get(key, default)
+
+
+def is_enabled() -> bool:
+    """Whether the boot-time warm-up search should run."""
+    if not _as_bool(_setting("SEARCH_WARMUP_ENABLED", True), default=True):
+        return False
+    # Nothing to warm if the source is off, and no challenge to pre-solve without
+    # the bypasser - a plain search is fast enough not to need this.
+    if not _as_bool(_setting("DIRECT_DOWNLOAD_ENABLED", True), default=True):
+        logger.debug("Search warm-up skipped: direct download disabled")
+        return False
+    return True
+
+
+def warmup_query() -> str:
+    """The query used to warm the source."""
+    raw = _setting("SEARCH_WARMUP_QUERY", _DEFAULT_QUERY)
+    query = str(raw).strip() if raw else ""
+    return query or _DEFAULT_QUERY
+
+
+def run_warmup() -> bool:
+    """Run one warm-up search. Returns True if it produced results.
+
+    Never raises: every failure mode here is one the next real search would hit
+    anyway, and reporting it is the search path's job, not the warm-up's.
+    """
+    from shelfmark.core.mirrors import has_aa_mirror_configuration
+
+    if not has_aa_mirror_configuration():
+        logger.debug("Search warm-up skipped: no Anna's Archive mirrors configured")
+        return False
+
+    query = warmup_query()
+    logger.info("Warming up direct download search (%r)", query)
+    try:
+        from shelfmark.core.models import SearchFilters
+        from shelfmark.release_sources.direct_download import search_books
+
+        results = search_books(query, SearchFilters())
+    except Exception:
+        # Broad by design: a warm-up must never take the app down, and the source
+        # raises everything from network errors to parse failures.
+        logger.warning("Search warm-up did not complete; first user search may be slow")
+        logger.debug("Search warm-up failure detail", exc_info=True)
+        return False
+
+    if results:
+        logger.info("Search warm-up complete: %s results, source is ready", len(results))
+        return True
+    logger.info("Search warm-up returned no results; source reachable but empty")
+    return False
+
+
+def start(delay_seconds: float = _DEFAULT_DELAY_SECONDS) -> bool:
+    """Schedule the warm-up on a daemon thread. Safe to call multiple times."""
+    global _warmup_thread
+
+    if not is_enabled():
+        return False
+
+    with _warmup_lock:
+        if _warmup_thread is not None and _warmup_thread.is_alive():
+            logger.debug("Search warm-up already scheduled")
+            return False
+
+        def _run() -> None:
+            run_warmup()
+
+        _warmup_thread = threading.Timer(delay_seconds, _run)
+        _warmup_thread.daemon = True
+        _warmup_thread.name = "SearchWarmup"
+        _warmup_thread.start()
+
+    logger.debug("Search warm-up scheduled in %ss", delay_seconds)
+    return True
@@ -38,7 +38,10 @@ from shelfmark.config.env import (
    string_to_bool,
 )
 from shelfmark.config.security import _migrate_security_settings
-from shelfmark.config.settings import _SUPPORTED_BOOK_LANGUAGE
+from shelfmark.config.settings import (
+    _SUPPORTED_BOOK_LANGUAGE,
+    migrate_audiobook_format_settings,
+)
 from shelfmark.core.activity_view_state_service import ActivityViewStateService
 from shelfmark.core.auth_modes import (
    get_auth_check_admin_status,
@@ -80,8 +83,9 @@ from shelfmark.core.requests_service import (
    sync_delivery_states_from_queue_status,
 )
 from shelfmark.core.user_db import UserDB
-from shelfmark.core.utils import normalize_base_path
+from shelfmark.core.utils import AUDIOBOOK_FORMATS, normalize_base_path
 from shelfmark.download import orchestrator as backend
+from shelfmark.download import warmup
 from shelfmark.release_sources import (
    BrowseRecord,
    Release,
@@ -118,7 +122,7 @@ BASE_PATH = normalize_base_path(normalize_optional_text(app_config.get("URL_BASE
 app = Flask(__name__)
 app.config["SEND_FILE_MAX_AGE_DEFAULT"] = 0  # Disable caching
 app.config["APPLICATION_ROOT"] = BASE_PATH or "/"
-wsgi_app = cast(Any, ProxyFix(app.wsgi_app))
+wsgi_app = cast(Any, ProxyFix(app.wsgi_app, x_host=1, x_port=1))
 if BASE_PATH:
    wsgi_app = cast(Any, PrefixMiddleware(wsgi_app, BASE_PATH, bypass_paths={"/api/health"}))
 app.wsgi_app = wsgi_app
@@ -168,6 +172,9 @@ except ImportError as e:
 # Migrate legacy security settings if needed
 _migrate_security_settings()

+# Widen audiobook formats for installs that still carry the old m4b/mp3-only default
+migrate_audiobook_format_settings()
+
 # Initialize user database and register multi-user routes
 # If CONFIG_DIR doesn't exist or is read-only, multi-user features will be disabled
 _user_db_path = str(Path(os.environ.get("CONFIG_DIR", "/config")) / "users.db")
@@ -200,6 +207,10 @@ except (sqlite3.OperationalError, OSError) as e:
 # Start download coordinator
 backend.start()

+# Pre-solve the direct-download source's protection challenge in the background so the
+# first user search does not pay for a cold Chrome bypass. Never blocks startup.
+warmup.start()
+
 # Rate limiting for login attempts
 # Map usernames to their failed-attempt counters and lockout timestamps.
 failed_login_attempts: dict[str, dict[str, Any]] = {}
@@ -319,19 +330,7 @@ def get_auth_mode() -> str:


 _AUDIOBOOK_CATEGORY_RANGE = (3030, 3049)
-_AUDIOBOOK_FORMAT_HINTS = frozenset(
-    {
-        "m4b",
-        "mp3",
-        "m4a",
-        "flac",
-        "ogg",
-        "wma",
-        "aac",
-        "wav",
-        "opus",
-    }
-)
+_AUDIOBOOK_FORMAT_HINTS = frozenset(AUDIOBOOK_FORMATS)


 def _contains_audiobook_format_hint(value: Any) -> bool:
@@ -24,12 +24,12 @@ Dataclass representing a book from a metadata provider:
 ```python
@dataclass
 class BookMetadata:
-    provider: str                    # Internal provider name (e.g., "hardcover")
-    provider_id: str                 # ID in that provider's system
+    provider: str  # Internal provider name (e.g., "hardcover")
+    provider_id: str  # ID in that provider's system
    title: str

    # Optional fields
-    provider_display_name: str       # Human-readable name (e.g., "Hardcover")
+    provider_display_name: str  # Human-readable name (e.g., "Hardcover")
    authors: List[str]
    isbn_10: str
    isbn_13: str
@@ -39,7 +39,7 @@ class BookMetadata:
    publish_year: int
    language: str
    genres: List[str]
-    source_url: str                  # Link to book on provider's site
+    source_url: str  # Link to book on provider's site
    display_fields: List[DisplayField]  # Provider-specific display data
 ```

@@ -50,9 +50,9 @@ Provider-specific metadata for UI cards (ratings, page counts, reader counts, et
 ```python
@dataclass
 class DisplayField:
-    label: str       # e.g., "Rating", "Pages", "Readers"
-    value: str       # e.g., "4.5", "496", "8,041"
-    icon: str        # Icon name: "star", "book", "users", "editions"
+    label: str  # e.g., "Rating", "Pages", "Readers"
+    value: str  # e.g., "4.5", "496", "8,041"
+    icon: str  # Icon name: "star", "book", "users", "editions"
 ```

 ### MetadataSearchOptions
@@ -64,7 +64,7 @@ Unified search options that work across all providers:
 class MetadataSearchOptions:
    query: str
    search_type: SearchType = SearchType.GENERAL  # GENERAL, TITLE, AUTHOR, ISBN
-    language: str = None                          # ISO 639-1 code (e.g., "en")
+    language: str = None  # ISO 639-1 code (e.g., "en")
    sort: SortOrder = SortOrder.RELEVANCE
    limit: int = 40
    page: int = 1
@@ -88,10 +88,10 @@ All providers must implement this interface:

 ```python
 class MetadataProvider(ABC):
-    name: str                        # Internal identifier
-    display_name: str                # Human-readable name
-    requires_auth: bool              # True if API key required
-    supported_sorts: List[SortOrder] # Supported sort options
+    name: str  # Internal identifier
+    display_name: str  # Human-readable name
+    requires_auth: bool  # True if API key required
+    supported_sorts: List[SortOrder]  # Supported sort options

    @abstractmethod
    def search(self, options: MetadataSearchOptions) -> List[BookMetadata]:
@@ -121,9 +121,9 @@ class MetadataProvider(ABC):
 ```python
 from shelfmark.metadata_providers import register_provider

+
@register_provider("my_provider")
-class MyProvider(MetadataProvider):
-    ...
+class MyProvider(MetadataProvider): ...
 ```

 ### Getting Providers
@@ -281,11 +281,13 @@ from shelfmark.config.env import (
    METADATA_CACHE_BOOK_TTL,
 )

+
@cacheable(ttl=METADATA_CACHE_SEARCH_TTL, key_prefix="myprovider:search")
 def _search_cached(self, cache_key: str, options: MetadataSearchOptions):
    # Cached search implementation
    pass

+
@cacheable(ttl=METADATA_CACHE_BOOK_TTL, key_prefix="myprovider:book")
 def get_book(self, book_id: str):
    # Cached book lookup
@@ -302,6 +304,7 @@ from shelfmark.metadata_providers.openlibrary import RateLimiter
 # 90 requests per 60 seconds
 rate_limiter = RateLimiter(max_requests=90, window_seconds=60)

+
 def make_request(self):
    rate_limiter.wait_if_needed()  # Blocks if rate limited
    # ... make request
@@ -709,3 +709,6 @@ with suppress(ImportError):

 with suppress(ImportError):
    from shelfmark.metadata_providers import googlebooks as googlebooks
+
+with suppress(ImportError):
+    from shelfmark.metadata_providers import moly as moly
@@ -1,6 +1,7 @@
 """Hardcover.app metadata provider. Requires API key."""

 import re
+import time
 from contextlib import suppress
 from dataclasses import dataclass
 from datetime import UTC, datetime
@@ -553,6 +554,31 @@ TITLE_SUGGESTION_FIELDS = "title,alternative_titles"
 TITLE_SUGGESTION_WEIGHTS = "5,2"
 TITLE_SUGGESTION_SORT = "_text_match:desc,users_count:desc"

+# Hardcover forwards `sort` to Typesense's `sort_by` and rejects the whole search
+# if it does not like the value -- an unknown field, a bare field name with no
+# direction, more than three keys. A rejected search comes back as HTTP 200 with
+# no GraphQL errors and a null `results` body, which is otherwise indistinguishable
+# from "nothing matched". An empty sort is always accepted, so fall back to it and
+# keep the fallback sticky for a while rather than paying for a doomed request on
+# every search.
+SORT_FALLBACK = ""
+SORT_FALLBACK_TTL = 900.0
+_sort_fallback_until = 0.0
+
+
+def _search_payload_rejected(result: dict[str, Any] | None) -> bool:
+    """Report whether Hardcover answered a search with a null results body.
+
+    A search that genuinely matched nothing still returns a results object with
+    ``found: 0``; only a rejected search nulls it out entirely.
+    """
+    if not isinstance(result, dict):
+        return False
+    root = result.get("search", result)
+    if not isinstance(root, dict) or "results" not in root:
+        return False
+    return root["results"] is None
+

 def _combine_headline_description(headline: str | None, description: str | None) -> str | None:
    """Combine headline (tagline) and description into a single description."""
@@ -1200,7 +1226,7 @@ class HardcoverProvider(MetadataProvider):
        if not self.api_key or len(normalized_query) < HARDCOVER_MIN_TYPEAHEAD_QUERY_LENGTH:
            return []

-        result = self._execute_query(
+        result = self._execute_search_query(
            SEARCH_FIELD_OPTIONS_QUERY,
            {
                "query": normalized_query,
@@ -1431,7 +1457,7 @@ class HardcoverProvider(MetadataProvider):
                logger.debug("Invalid Hardcover series id field value: %s", normalized_value)
                return None

-        result = self._execute_query(
+        result = self._execute_search_query(
            SEARCH_FIELD_OPTIONS_QUERY,
            {
                "query": normalized_value,
@@ -2386,7 +2412,7 @@ class HardcoverProvider(MetadataProvider):
            variables["weights"] = search_weights

        try:
-            result = self._execute_query(graphql_query, variables)
+            result = self._execute_search_query(graphql_query, variables)
            if not result:
                logger.debug("Hardcover search: No result from API")
                return SearchResult(books=[], page=options.page, total_found=0, has_more=False)
@@ -2654,6 +2680,45 @@ class HardcoverProvider(MetadataProvider):
                raise RuntimeError(msg) from e
            return None

+    def _execute_search_query(self, query: str, variables: dict[str, Any]) -> dict | None:
+        """Execute a search query, retrying without ``sort`` if Hardcover rejects it.
+
+        Returns None when the search was rejected, so callers report an empty
+        result rather than silently treating a failure as "nothing matched".
+        """
+        global _sort_fallback_until
+
+        sort = variables.get("sort")
+        if sort and time.monotonic() < _sort_fallback_until:
+            variables = {**variables, "sort": SORT_FALLBACK}
+            sort = None
+
+        result = self._execute_query(query, variables)
+        if not _search_payload_rejected(result):
+            return result
+
+        if not sort:
+            logger.error(
+                "Hardcover rejected this search (query_type=%s, fields=%s) and returned "
+                "no result body",
+                variables.get("queryType", "Book"),
+                variables.get("fields"),
+            )
+            return None
+
+        logger.warning(
+            "Hardcover rejected sort '%s'; retrying searches without a sort order for %ss",
+            sort,
+            int(SORT_FALLBACK_TTL),
+        )
+        _sort_fallback_until = time.monotonic() + SORT_FALLBACK_TTL
+
+        retry = self._execute_query(query, {**variables, "sort": SORT_FALLBACK})
+        if _search_payload_rejected(retry):
+            logger.error("Hardcover rejected this search even without a sort order")
+            return None
+        return retry
+
    def _parse_search_result(self, item: dict) -> BookMetadata | None:
        """Parse a search result item into BookMetadata."""
        try:
@@ -0,0 +1,493 @@
+"""Moly.hu metadata provider. Hungarian book catalog, no API key required.
+
+Scraping approach (search URL, book-page structure, language mapping) adapted
+from the Calibre Moly_hu plugin by Hoffer Csaba, Kloon, otapi, Dezso, Hokutya,
+seeder and contributors (GPL v3, mobileread.com).
+"""
+
+import re
+import threading
+import time
+import unicodedata
+from collections import deque
+from typing import Any, ClassVar
+from urllib.parse import quote
+
+import requests
+from bs4 import BeautifulSoup, Tag
+
+from shelfmark.core.cache import cacheable
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.settings_registry import (
+    ActionButton,
+    CheckboxField,
+    HeadingField,
+    SettingsField,
+    register_settings,
+)
+from shelfmark.download.network import get_ssl_verify
+from shelfmark.metadata_providers import (
+    BookMetadata,
+    DisplayField,
+    MetadataProvider,
+    MetadataSearchOptions,
+    SearchField,
+    SearchType,
+    SortOrder,
+    TextSearchField,
+    register_provider,
+)
+
+logger = setup_logger(__name__)
+
+MOLY_BASE_URL = "https://moly.hu"
+MOLY_BOOK_URL = f"{MOLY_BASE_URL}/konyvek/"
+MOLY_SEARCH_URL = f"{MOLY_BASE_URL}/kereses?query="
+
+# Be polite: moly.hu is a small community site
+RATE_LIMIT_REQUESTS = 30
+RATE_LIMIT_WINDOW_SECONDS = 60
+
+REQUEST_HEADERS = {
+    "User-Agent": ("Mozilla/5.0 (X11; Linux x86_64; rv:128.0) Gecko/20100101 Firefox/128.0"),
+    "Accept-Language": "hu,en;q=0.7",
+}
+
+ISBN_13_LENGTH = 13
+
+# Moly tags its foreign-language editions; everything else is Hungarian.
+# Mapping from the Calibre Moly_hu plugin.
+_LANGUAGE_TAG_MAP = {
+    "angol nyelvű": "en",
+    "n\xe9met nyelvű": "de",
+    "francia nyelvű": "fr",
+    "olasz nyelvű": "it",
+    "spanyol nyelvű": "es",
+    "orosz nyelvű": "ru",
+    "t\xf6r\xf6k nyelvű": "tr",
+    "g\xf6r\xf6g nyelvű": "el",
+    "k\xednai nyelvű": "zh",
+    "jap\xe1n nyelvű": "ja",
+}
+
+
+class RateLimiter:
+    """Simple sliding window rate limiter."""
+
+    def __init__(self, max_requests: int, window_seconds: int) -> None:
+        """Initialize rate limiter with max requests per time window."""
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.timestamps: deque[float] = deque()
+        self.lock = threading.Lock()
+
+    def wait_if_needed(self) -> None:
+        """Block until a request is allowed (thread-safe)."""
+        wait_time = 0.0
+
+        with self.lock:
+            now = time.time()
+            cutoff = now - self.window_seconds
+            while self.timestamps and self.timestamps[0] < cutoff:
+                self.timestamps.popleft()
+            if len(self.timestamps) >= self.max_requests:
+                wait_time = self.timestamps[0] + self.window_seconds - now
+
+        if wait_time > 0:
+            logger.debug("Rate limited, waiting %0.2fs", wait_time)
+            time.sleep(wait_time)
+
+        with self.lock:
+            now = time.time()
+            cutoff = now - self.window_seconds
+            while self.timestamps and self.timestamps[0] < cutoff:
+                self.timestamps.popleft()
+            self.timestamps.append(time.time())
+
+
+_rate_limiter = RateLimiter(RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW_SECONDS)
+
+
+def _clean_text(value: str | None) -> str | None:
+    """Strip zero-width characters and collapse whitespace."""
+    if value is None:
+        return None
+    value = value.replace("", "").replace("", "")
+    return " ".join(value.split())
+
+
+def _normalize_for_match(value: str | None) -> str:
+    """Accent-insensitive, punctuation-insensitive comparison form."""
+    if not value:
+        return ""
+    value = unicodedata.normalize("NFKD", value)
+    value = "".join(char for char in value if not unicodedata.combining(char))
+    value = "".join(char if char.isalnum() else " " for char in value)
+    return " ".join(value.lower().split())
+
+
+def _absolute_url(url: str | None) -> str | None:
+    if not url:
+        return None
+    if url.startswith(("http://", "https://")):
+        return url
+    return MOLY_BASE_URL + url
+
+
+def _valid_isbn(candidate: str) -> str | None:
+    """Return a normalized ISBN-10/13 (digits, with optional X check digit), else None."""
+    digits = candidate.replace("-", "").strip()
+    if len(digits) == ISBN_13_LENGTH and digits.isdigit():
+        return digits
+    if len(digits) == 10 and re.fullmatch(r"\d{9}[\dXx]", digits):
+        return digits.upper()
+    return None
+
+
+@register_provider("moly")
+class MolyProvider(MetadataProvider):
+    """Moly.hu metadata provider (HTML scraping, Hungarian catalog)."""
+
+    name = "moly"
+    display_name = "Moly.hu"
+    requires_auth = False
+    supported_sorts: ClassVar[tuple[SortOrder, ...]] = (SortOrder.RELEVANCE,)
+    search_fields: ClassVar[tuple[SearchField, ...]] = (
+        TextSearchField(
+            key="author",
+            label="Author",
+            description="Search by author name",
+        ),
+        TextSearchField(
+            key="title",
+            label="Title",
+            description="Search by book title",
+        ),
+    )
+
+    def __init__(self) -> None:
+        """Initialize provider."""
+        self.session = requests.Session()
+        self.session.headers.update(REQUEST_HEADERS)
+
+    def is_available(self) -> bool:
+        """Moly.hu needs no authentication."""
+        return True
+
+    def _fetch(self, url: str, timeout: int = 15) -> str | None:
+        _rate_limiter.wait_if_needed()
+        try:
+            response = self.session.get(url, timeout=timeout, verify=get_ssl_verify(MOLY_BASE_URL))
+            response.raise_for_status()
+        except requests.Timeout:
+            logger.warning("Moly.hu request timed out: %s", url)
+            return None
+        except requests.RequestException:
+            logger.exception("Moly.hu request failed: %s", url)
+            return None
+        return response.text
+
+    def search(self, options: MetadataSearchOptions) -> list[BookMetadata]:
+        """Search moly.hu's site search."""
+        if options.search_type == SearchType.ISBN:
+            result = self.search_by_isbn(options.query)
+            return [result] if result else []
+
+        # Moly's search is a single ranked page; no server-side pagination.
+        if options.page > 1:
+            return []
+
+        author_value = (options.fields.get("author") or "").strip()
+        title_value = (options.fields.get("title") or "").strip()
+        terms = " ".join(t for t in (author_value, title_value) if t)
+        query = terms or options.query.strip()
+        if not query:
+            return []
+
+        fields_key = ":".join(f"{k}={v}" for k, v in sorted(options.fields.items()))
+        cache_key = f"{query}:{options.search_type.value}:{options.limit}:{fields_key}"
+        return self._search_cached(cache_key, query, options.limit) or []
+
+    @cacheable(ttl_key="METADATA_CACHE_SEARCH_TTL", ttl_default=300, key_prefix="moly:search")
+    def _search_cached(self, cache_key: str, query: str, limit: int) -> list[BookMetadata] | None:
+        # Return None (not []) on fetch failure so the failure is not cached.
+        html = self._fetch(MOLY_SEARCH_URL + quote(query.encode("utf-8")))
+        if html is None:
+            return None
+
+        soup = BeautifulSoup(html, "html.parser")
+        books: list[BookMetadata] = []
+        seen: set[str] = set()
+
+        for anchor in soup.select("#content div.search_area a.book_selector"):
+            href = anchor.get("href") or ""
+            match = re.search(r"/konyvek/([^/?#]+)", str(href))
+            if not match:
+                continue
+            slug = match.group(1)
+            if slug in seen:
+                continue
+
+            # No separator: moly wraps matched search terms in <strong> even
+            # mid-word ("Lis<strong>a</strong> Jewell"), so inserting one
+            # would split words at highlight boundaries.
+            text = _clean_text(anchor.get_text()) or ""
+            author, _, title = text.partition(":")
+            if not title:
+                # Result rows are "Author: Title"; skip anything else.
+                continue
+            author = author.strip()
+            title = title.strip()
+
+            seen.add(slug)
+            books.append(
+                BookMetadata(
+                    provider=self.name,
+                    provider_id=slug,
+                    provider_display_name=self.display_name,
+                    title=title,
+                    authors=[author] if author else [],
+                    cover_url=self._cover_for_result(soup, text),
+                    source_url=MOLY_BOOK_URL + slug,
+                    language="hu",
+                    search_title=title,
+                    search_author=author or None,
+                    display_fields=self._result_display_fields(anchor),
+                )
+            )
+            if len(books) >= limit:
+                break
+
+        logger.info("Moly.hu search '%s' returned %s results", query, len(books))
+        return books
+
+    def _cover_for_result(self, soup: BeautifulSoup, result_text: str) -> str | None:
+        """Find the search-result thumbnail whose alt matches 'Author: Title'."""
+        target = _normalize_for_match(result_text)
+        if not target:
+            return None
+        for img in soup.select("#content img.tooltip[alt]"):
+            if _normalize_for_match(str(img.get("alt") or "")) == target:
+                return _absolute_url(str(img.get("src") or "")) or None
+        return None
+
+    def _result_display_fields(self, anchor: Tag) -> list[DisplayField]:
+        fields: list[DisplayField] = []
+        parent = anchor.parent
+        if parent is None:
+            return fields
+        like = parent.select_one("span.like_count")
+        if like:
+            fields.append(
+                DisplayField(label="Rating", value=like.get_text(strip=True), icon="star")
+            )
+        series = parent.select_one('a[href*="/sorozatok/"]')
+        if series:
+            fields.append(
+                DisplayField(
+                    label="Series",
+                    value=series.get_text(strip=True).strip("()"),
+                    icon="editions",
+                )
+            )
+        return fields
+
+    @cacheable(ttl_key="METADATA_CACHE_BOOK_TTL", ttl_default=600, key_prefix="moly:book")
+    def get_book(self, book_id: str) -> BookMetadata | None:
+        """Get book details by moly.hu slug (e.g. 'mocsidzuki-mai-a-telihold-kavezo')."""
+        html = self._fetch(MOLY_BOOK_URL + quote(book_id))
+        if html is None:
+            return None
+
+        soup = BeautifulSoup(html, "html.parser")
+
+        title = self._parse_title(soup)
+        authors = [_clean_text(a.get_text()) or "" for a in soup.select("#content div.authors a")]
+        authors = [a for a in authors if a]
+        if not title or not authors:
+            logger.warning("Moly.hu book page missing title/authors: %s", book_id)
+            return None
+
+        isbn_13, isbn_10 = self._parse_isbns(soup)
+        series = self._parse_series(soup)
+        tags = [_clean_text(t.get_text()) or "" for t in soup.select("#book_tags a.tag")]
+        tags = [t for t in tags if t]
+
+        display_fields: list[DisplayField] = []
+        rating = soup.select_one("#content .rating .like_count")
+        if rating:
+            display_fields.append(
+                DisplayField(label="Rating", value=rating.get_text(strip=True), icon="star")
+            )
+        if series:
+            display_fields.append(DisplayField(label="Series", value=series, icon="editions"))
+
+        return BookMetadata(
+            provider=self.name,
+            provider_id=book_id,
+            provider_display_name=self.display_name,
+            title=title,
+            authors=authors,
+            isbn_13=isbn_13,
+            isbn_10=isbn_10,
+            cover_url=self._parse_cover(soup),
+            description=self._parse_description(soup),
+            publisher=self._parse_publisher(soup),
+            publish_year=self._parse_publish_year(soup),
+            language=self._parse_language(tags),
+            genres=tags,
+            source_url=MOLY_BOOK_URL + book_id,
+            search_title=title,
+            search_author=authors[0],
+            display_fields=display_fields,
+        )
+
+    @cacheable(ttl_key="METADATA_CACHE_BOOK_TTL", ttl_default=600, key_prefix="moly:isbn")
+    def search_by_isbn(self, isbn: str) -> BookMetadata | None:
+        """Moly's site search resolves ISBN queries directly."""
+        isbn = isbn.replace("-", "").strip()
+        if not isbn:
+            return None
+        html = self._fetch(MOLY_SEARCH_URL + quote(isbn))
+        if html is None:
+            return None
+        soup = BeautifulSoup(html, "html.parser")
+        anchor = soup.select_one("#content div.search_area a.book_selector[href]")
+        if not anchor:
+            return None
+        match = re.search(r"/konyvek/([^/?#]+)", str(anchor.get("href")))
+        if not match:
+            return None
+        return self.get_book(match.group(1))
+
+    def _parse_title(self, soup: BeautifulSoup) -> str | None:
+        node = soup.select_one("#content .head_title h1 span.item")
+        if node:
+            # The series link is nested inside this span; only direct text
+            # belongs to the book title.
+            direct = "".join(node.find_all(string=True, recursive=False))
+            title = _clean_text(direct)
+            if title:
+                return title
+        node = soup.select_one("#content .book > span")
+        if node:
+            return _clean_text(node.get_text())
+        return None
+
+    def _parse_series(self, soup: BeautifulSoup) -> str | None:
+        node = soup.select_one('#content h1 a[href*="/sorozatok/"]')
+        if not node:
+            return None
+        return (_clean_text(node.get_text()) or "").strip("()") or None
+
+    def _parse_isbns(self, soup: BeautifulSoup) -> tuple[str | None, str | None]:
+        isbn_13 = isbn_10 = None
+        editions = soup.select("#content .items .edition") or soup.select("#content .items > div")
+        for edition in editions:
+            text = edition.get_text(" ")
+            for candidate in re.findall(r"(?<!\d)[\d-]{10,17}(?!\d)", text):
+                isbn = _valid_isbn(candidate)
+                if not isbn:
+                    continue
+                if len(isbn) == ISBN_13_LENGTH and not isbn_13:
+                    isbn_13 = isbn
+                elif len(isbn) != ISBN_13_LENGTH and not isbn_10:
+                    isbn_10 = isbn
+            if isbn_13:
+                break
+        return isbn_13, isbn_10
+
+    def _parse_cover(self, soup: BeautifulSoup) -> str | None:
+        node = soup.select_one("#content .coverbox a.zoom[href]")
+        if node:
+            return _absolute_url(str(node.get("href")))
+        img = soup.select_one("#content .coverbox img[src]")
+        if img:
+            return _absolute_url(str(img.get("src")))
+        return None
+
+    def _parse_description(self, soup: BeautifulSoup) -> str | None:
+        node = soup.select_one("#content #full_description")
+        if node is None:
+            node = soup.select_one("#content div.text")
+        if node is None:
+            return None
+        spoiler_warning = "Vigyázat! Cselekményleírást tartalmaz."
+        parts = []
+        for text in node.stripped_strings:
+            cleaned = _clean_text(text) or ""
+            if cleaned.startswith(spoiler_warning):
+                cleaned = cleaned[len(spoiler_warning) :].strip()
+            if cleaned:
+                parts.append(cleaned)
+        return "\n".join(parts) or None
+
+    def _parse_publisher(self, soup: BeautifulSoup) -> str | None:
+        node = soup.select_one('#content .items .edition a[href*="/kiadok/"]')
+        if node:
+            return _clean_text(node.get_text())
+        return None
+
+    def _parse_publish_year(self, soup: BeautifulSoup) -> int | None:
+        editions = soup.select("#content .items .edition") or soup.select("#content .items > div")
+        for edition in editions:
+            match = re.search(r"\b(\d{4})\b", edition.get_text(" "))
+            if match:
+                return int(match.group(1))
+        return None
+
+    def _parse_language(self, tags: list[str]) -> str:
+        for tag in tags:
+            code = _LANGUAGE_TAG_MAP.get(tag.lower().strip())
+            if code:
+                return code
+        return "hu"
+
+
+def _test_moly_connection() -> dict[str, Any]:
+    """Test connectivity to moly.hu."""
+    try:
+        provider = MolyProvider()
+        response = provider.session.get(
+            MOLY_SEARCH_URL + quote("teszt"),
+            timeout=10,
+            verify=get_ssl_verify(MOLY_BASE_URL),
+        )
+        response.raise_for_status()
+    except requests.Timeout:
+        return {"success": False, "message": "Connection timed out"}
+    except requests.RequestException as e:
+        return {"success": False, "message": f"Connection failed: {e}"}
+    if "moly" in response.text.lower():
+        return {"success": True, "message": "Successfully connected to moly.hu"}
+    return {"success": False, "message": "Unexpected response from moly.hu"}
+
+
+@register_settings("moly", "Moly.hu", icon="library", order=54, group="metadata_providers")
+def moly_settings() -> list[SettingsField]:
+    """Moly.hu metadata provider settings."""
+    return [
+        HeadingField(
+            key="moly_heading",
+            title="Moly.hu",
+            description=(
+                "Hungarian community book catalog with excellent coverage of "
+                "Hungarian editions and translations. No API key required."
+            ),
+            link_url="https://moly.hu",
+            link_text="moly.hu",
+        ),
+        CheckboxField(
+            key="MOLY_ENABLED",
+            label="Enable Moly.hu",
+            description="Enable Moly.hu as a metadata provider for book searches",
+            default=False,
+        ),
+        ActionButton(
+            key="test_connection",
+            label="Test Connection",
+            description="Verify moly.hu is accessible",
+            style="primary",
+            callback=_test_moly_connection,
+        ),
+    ]
@@ -163,6 +163,7 @@ class SortOption:

    label: str  # Display label in the sort dropdown
    sort_key: str  # Field to sort by on the Release object
+    default_direction: Literal["asc", "desc"] = "desc"  # Which way "best first" runs


@dataclass
@@ -261,7 +262,12 @@ def serialize_column_config(config: ReleaseColumnConfig) -> dict[str, Any]:
    # Include extra sort options (sort entries not tied to a column)
    if config.extra_sort_options:
        result["extra_sort_options"] = [
-            {"label": opt.label, "sort_key": opt.sort_key} for opt in config.extra_sort_options
+            {
+                "label": opt.label,
+                "sort_key": opt.sort_key,
+                "default_direction": opt.default_direction,
+            }
+            for opt in config.extra_sort_options
        ]

    # Include action button if specified (replaces default expand search)
@@ -9,6 +9,7 @@ if TYPE_CHECKING:
    from shelfmark.metadata_providers import BookMetadata

 from shelfmark.core.config import config
+from shelfmark.core.languages import normalize_language
 from shelfmark.core.logger import setup_logger
 from shelfmark.release_sources import (
    ColumnAlign,
@@ -43,41 +44,6 @@ def _coerce_positive_int(value: object, default: int) -> int:


 # Map language names to ISO 639-1 codes (matching frontend color maps)
-LANGUAGE_MAP = {
-    "english": "en",
-    "spanish": "es",
-    "french": "fr",
-    "german": "de",
-    "italian": "it",
-    "portuguese": "pt",
-    "russian": "ru",
-    "japanese": "ja",
-    "chinese": "zh",
-    "dutch": "nl",
-    "swedish": "sv",
-    "norwegian": "no",
-    "danish": "da",
-    "finnish": "fi",
-    "polish": "pl",
-    "czech": "cs",
-    "hungarian": "hu",
-    "korean": "ko",
-    "arabic": "ar",
-    "hebrew": "he",
-    "turkish": "tr",
-    "greek": "el",
-    "hindi": "hi",
-    "thai": "th",
-    "vietnamese": "vi",
-    "indonesian": "id",
-    "ukrainian": "uk",
-    "romanian": "ro",
-    "bulgarian": "bg",
-    "catalan": "ca",
-    "croatian": "hr",
-    "slovenian": "sl",
-    "serbian": "sr",
-}


 def _split_title_and_author(raw_title: str) -> tuple[str, str | None]:
@@ -119,8 +85,9 @@ def _map_language(language: str) -> str | None:
    if not language:
        return None

-    lang_lower = language.lower().strip()
-    return LANGUAGE_MAP.get(lang_lower, lang_lower)
+    # Fall back to the raw value so an unrecognised language is still shown
+    # rather than silently dropped from the release row.
+    return normalize_language(language) or language.lower().strip()


 def _parse_bitrate_to_kbps(bitrate: str | None) -> int | None:
@@ -18,6 +18,7 @@ from bs4.element import NavigableString

 from shelfmark.config.env import DEBUG_SKIP_SOURCES, TMP_DIR
 from shelfmark.core.config import config
+from shelfmark.core.languages import language_alias_map
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.models import DownloadTask, SearchFilters, build_filename
 from shelfmark.core.utils import CONTENT_TYPES, get_aa_content_type_dir
@@ -267,7 +268,7 @@ def _fold_text(value: str) -> str:


 def _language_alias_to_code() -> dict[str, str]:
-    """Build alias→code map from bundled language metadata (lazy, cached)."""
+    """Alias to code map, delegating to the shared language data."""
    global _LANGUAGE_ALIAS_TO_CODE
    cached = _LANGUAGE_ALIAS_TO_CODE
    if cached is not None:
@@ -278,35 +279,7 @@ def _language_alias_to_code() -> dict[str, str]:
        if cached is not None:
            return cached

-        mapping: dict[str, str] = {}
-        data_path = Path(__file__).resolve().parents[2] / "data" / "book-languages.json"
-
-        try:
-            raw = json.loads(data_path.read_text(encoding="utf-8"))
-        except OSError, ValueError, TypeError:
-            _LANGUAGE_ALIAS_TO_CODE = {}
-            return _LANGUAGE_ALIAS_TO_CODE
-
-        if not isinstance(raw, list):
-            _LANGUAGE_ALIAS_TO_CODE = {}
-            return _LANGUAGE_ALIAS_TO_CODE
-
-        for item in raw:
-            if not isinstance(item, dict):
-                continue
-            code = _normalize_language_token(str(item.get("code", "")))
-            name = _normalize_language_token(str(item.get("language", "")))
-            if not code:
-                continue
-            mapping.setdefault(code, code)
-            mapping.setdefault(code.replace("-", "_"), code)
-            mapping.setdefault(code.split("-")[0], code)
-            mapping.setdefault(_fold_text(code), code)
-            if name:
-                mapping.setdefault(name, code)
-                mapping.setdefault(_fold_text(name), code)
-
-        _LANGUAGE_ALIAS_TO_CODE = mapping
+        _LANGUAGE_ALIAS_TO_CODE = language_alias_map()
        return _LANGUAGE_ALIAS_TO_CODE


@@ -566,6 +539,79 @@ class SearchUnavailableError(SourceUnavailableError):
    """Raised when Anna's Archive cannot be reached via any mirror/DNS."""


+# Markers that prove a 200 really came from Anna's Archive, and markers that mean we
+# are looking at a protection interstitial rather than the site. A page with neither
+# is a domain that answers but is not AA - seized, parked or for sale.
+#
+# Deliberately structural rather than the domain name: a parking page's whole job is
+# to display the domain it is squatting on, so "annas-archive" matches the very pages
+# this is meant to catch. These paths only exist on the real site.
+_AA_PAGE_MARKERS = (
+    "/md5/",
+    "aarecord",
+    "anna's archive",
+    "/dyn/",
+    "/datasets",
+    "/fast_download",
+    "/slow_download",
+)
+_CHALLENGE_MARKERS = (
+    "ddos-guard",
+    "just a moment",
+    "cloudflare",
+    "checking your browser",
+    "cf-browser-verification",
+)
+
+
+def _looks_like_aa_page(html: str) -> bool:
+    """Whether ``html`` is recognisably Anna's Archive, or a challenge in front of it."""
+    lowered = html.lower()
+    return any(marker in lowered for marker in (*_AA_PAGE_MARKERS, *_CHALLENGE_MARKERS))
+
+
+def _fetch_search_table(url: str, selector: network.AAMirrorSelector) -> tuple[str, Tag | None]:
+    """Fetch the AA search page, retrying past mirrors that are not actually AA.
+
+    A parked or seized domain answers 200 with a page that has no results table and no
+    "No files found." - indistinguishable from a broken search unless we check whether
+    the response looks like AA at all. Those mirrors are quarantined for the session so
+    later searches skip them instead of paying the timeout again.
+    """
+    attempt_url = url
+    for _ in range(len(network.get_available_aa_urls()) or 1):
+        response = downloader.html_get_page(
+            attempt_url, selector=selector, allow_bypasser_fallback=True
+        )
+        if not response:
+            # Network/mirror exhaustion path bubbles up so API can notify clients
+            msg = "Unable to reach download source. Network restricted or mirrors are blocked."
+            raise SearchUnavailableError(msg)
+
+        html = _html_response_text(response)
+        soup = BeautifulSoup(html, "html.parser")
+        table = soup.find("table")
+        if isinstance(table, Tag):
+            return html, table
+        if table is not None:
+            msg = f"Expected results table tag, got {type(table).__name__}"
+            raise TypeError(msg)
+        if "No files found." in html or _looks_like_aa_page(html):
+            # A real AA response - either genuinely empty, or a shape the caller
+            # should report as drift. Not the mirror's fault.
+            return html, None
+
+        new_base, action = selector.next_mirror_or_rotate_dns(
+            fatal=True, reason="responded without an Anna's Archive page"
+        )
+        if action not in ("mirror", "dns") or not new_base:
+            return html, None
+        attempt_url = selector.rewrite(url)
+        logger.info("Retrying search on %s", new_base)
+
+    return "", None
+
+
 def search_books(query: str, filters: SearchFilters) -> list[BrowseRecord]:
    """Search for books matching the query.

@@ -628,15 +674,9 @@ def search_books(query: str, filters: SearchFilters) -> list[BrowseRecord]:
        f"{filters_query}"
    )

-    html = downloader.html_get_page(url, selector=selector, allow_bypasser_fallback=False)
-    if not html:
-        # Network/mirror exhaustion path bubbles up so API can notify clients
-        msg = "Unable to reach download source. Network restricted or mirrors are blocked."
-        raise SearchUnavailableError(msg)
-
-    soup = BeautifulSoup(_html_response_text(html), "html.parser")
-    tbody = soup.find("table")
-
+    # AA gates /search behind a DDoS-Guard JS challenge, which every mirror shares. Rotating
+    # to another mirror only collects another 403, so let the bypasser solve it.
+    html, tbody = _fetch_search_table(url, selector)
    if tbody is None:
        if "No files found." in html:
            logger.info("No books found for query: %s", query)
@@ -684,7 +724,8 @@ def get_book_info(book_id: str, *, fetch_download_count: bool = True) -> BrowseR
    """
    url = f"{network.get_aa_base_url()}/md5/{book_id}"
    selector = network.AAMirrorSelector()
-    html = downloader.html_get_page(url, selector=selector, allow_bypasser_fallback=False)
+    # Same challenge as search: the detail page is gated on every mirror, so bypass it.
+    html = downloader.html_get_page(url, selector=selector, allow_bypasser_fallback=True)

    if not html:
        msg = "Unable to reach download source. Network restricted or mirrors are blocked."
@@ -912,6 +953,9 @@ def _parse_book_info_page(
    if fetch_download_count:
        try:
            summary_url = f"{network.get_aa_base_url()}/dyn/md5/summary/{book_id}"
+            # Unlike search and the detail page above, this one stays off the bypasser: a
+            # download count is decoration on the details modal, not worth holding the
+            # modal open for a browser solve. If it is gated, drop it and move on.
            summary_response = downloader.html_get_page(
                summary_url, selector=network.AAMirrorSelector(), allow_bypasser_fallback=False
            )
@@ -25,6 +25,8 @@ logger = setup_logger(__name__)
 # Timing
 SOCKET_TIMEOUT = 300.0  # 5 minutes - long because we wait for DCC offers
 RECV_BUFFER = 4096
+# How often a deadline-bound read wakes up to re-check the clock
+POLL_INTERVAL = 2.0

 # IRC channel user prefixes that indicate elevated status (ops, voice, etc.)
 # These are the download bots/servers
@@ -248,11 +250,22 @@ class IRCClient:

                        # 366 = RPL_ENDOFNAMES - channel join is complete
                        if msg.command == "366":
-                            logger.info(
-                                "Joined #%s - %s servers online",
-                                channel,
-                                len(self.online_servers),
-                            )
+                            if not self.online_servers:
+                                # Joining a channel that doesn't exist on this network
+                                # silently creates an empty one, so an empty name list is
+                                # the only hint that the channel name is wrong.
+                                logger.warning(
+                                    "Joined #%s but no servers are online - the channel may "
+                                    "be empty or not exist on %s",
+                                    channel,
+                                    self.server,
+                                )
+                            else:
+                                logger.info(
+                                    "Joined #%s - %s servers online",
+                                    channel,
+                                    len(self.online_servers),
+                                )
                            return

                        # Check for errors (e.g., banned, channel doesn't exist)
@@ -296,27 +309,47 @@ class IRCClient:
        data = f"{message}\r\n".encode()
        self._socket.sendall(data)

-    def _recv_lines(self) -> Iterator[str]:
-        """Receive and yield complete CRLF-delimited IRC lines."""
-        sock = self._require_socket()
-        while True:
-            # Check if we have a complete line in buffer
-            while "\r\n" in self._buffer:
-                line, self._buffer = self._buffer.split("\r\n", 1)
-                if line:
-                    yield line
+    def _recv_lines(self, deadline: float | None = None) -> Iterator[str]:
+        """Receive and yield complete CRLF-delimited IRC lines.

-            # Read more data
-            try:
-                data = sock.recv(RECV_BUFFER)
-                if not data:
-                    return  # Connection closed
-                self._buffer += data.decode("utf-8", errors="replace")
-            except TimeoutError:
-                continue  # Keep waiting
-            except OSError as e:
-                logger.warning("Socket error: %s", e)
-                return  # Connection error
+        A deadline stops the read once it passes, even if nothing ever arrives.
+        Callers time out by watching the messages they receive, so on a channel
+        with no traffic at all there is nothing to watch: the recv would just
+        keep blocking for SOCKET_TIMEOUT and retrying forever.
+        """
+        sock = self._require_socket()
+        original_timeout = sock.gettimeout()
+
+        try:
+            while True:
+                # Check if we have a complete line in buffer
+                while "\r\n" in self._buffer:
+                    line, self._buffer = self._buffer.split("\r\n", 1)
+                    if line:
+                        yield line
+
+                if deadline is not None:
+                    remaining = deadline - time.time()
+                    if remaining <= 0:
+                        return
+                    # Wake up often enough to notice the deadline pass
+                    sock.settimeout(min(remaining, POLL_INTERVAL))
+
+                # Read more data
+                try:
+                    data = sock.recv(RECV_BUFFER)
+                    if not data:
+                        return  # Connection closed
+                    self._buffer += data.decode("utf-8", errors="replace")
+                except TimeoutError:
+                    continue  # Keep waiting (the deadline is re-checked above)
+                except OSError as e:
+                    logger.warning("Socket error: %s", e)
+                    return  # Connection error
+        finally:
+            if deadline is not None:
+                with suppress(OSError):
+                    sock.settimeout(original_timeout)

    def _parse_message(self, line: str) -> IRCMessage:
        """Parse an IRC message line into components.
@@ -427,9 +460,14 @@ class IRCClient:
            return False
        return True

-    def read_messages(self, *, auto_handle: bool = True) -> Iterator[IRCMessage]:
+    def read_messages(
+        self,
+        *,
+        auto_handle: bool = True,
+        deadline: float | None = None,
+    ) -> Iterator[IRCMessage]:
        """Read and yield IRC messages, optionally auto-handling PING/VERSION."""
-        for line in self._recv_lines():
+        for line in self._recv_lines(deadline):
            msg = self._parse_message(line)

            # Auto-handle certain events
@@ -453,13 +491,9 @@ class IRCClient:
    ) -> DCCOffer | None:
        """Wait for a DCC SEND offer. Returns None on timeout or no results."""
        target_event = IRCEvent.SEARCH_RESULT if result_type else IRCEvent.BOOK_RESULT
-        start = time.time()
-
-        for msg in self.read_messages():
-            if time.time() - start > timeout:
-                logger.warning("Timeout waiting for DCC offer")
-                return None
+        deadline = time.time() + timeout

+        for msg in self.read_messages(deadline=deadline):
            if msg.event == target_event:
                if not self._is_allowed_dcc_sender(msg, expected_senders):
                    continue
@@ -491,6 +525,8 @@ class IRCClient:
                    count = match.group(1)
                    logger.info("Found %s matches", count)

+        if time.time() >= deadline:
+            logger.warning("Timeout waiting for DCC offer")
        return None

    @property
@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING

 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
+from shelfmark.core.utils import ARCHIVE_FORMATS, AUDIOBOOK_FORMATS
 from shelfmark.core.utils import is_audiobook as check_audiobook

 if TYPE_CHECKING:
@@ -18,11 +19,8 @@ if TYPE_CHECKING:

 logger = setup_logger(__name__)

-# All recognized formats for parsing IRC result lines.
-# This comprehensive list is used to identify file extensions in results.
-# User-configured formats are used separately for filtering.
-ALL_RECOGNIZED_FORMATS = {
-    # Ebook formats
+# Ebook formats recognized in IRC result lines.
+EBOOK_FORMATS = (
    "epub",
    "mobi",
    "azw3",
@@ -41,19 +39,17 @@ ALL_RECOGNIZED_FORMATS = {
    "cbz",
    "cdr",
    "jpg",
-    "rar",
-    "zip",
-    # Audiobook formats
-    "m4b",
-    "mp3",
-    "m4a",
-    "flac",
-    "ogg",
-    "wma",
-    "aac",
-    "wav",
-    "opus",
-}
+)
+
+# All recognized formats for parsing IRC result lines.
+# This comprehensive list is used to identify file extensions in results.
+# User-configured formats are used separately for filtering.
+# Ordered longest-first so that scanning a line matches "azw3" before "azw" and "docx"
+# before "doc". It used to be a set, which made the winning format for a line naming more
+# than one extension depend on set iteration order, and therefore vary between restarts.
+ALL_RECOGNIZED_FORMATS = tuple(
+    sorted({*EBOOK_FORMATS, *ARCHIVE_FORMATS, *AUDIOBOOK_FORMATS}, key=len, reverse=True)
+)


 def _normalize_config_formats(raw_formats: object) -> set[str]:
@@ -84,13 +80,22 @@ def _get_supported_formats(content_type: str | None = None) -> set[str]:

 # Regex to parse result lines
 # Format: !Server Author - Title.format ::INFO:: size
+#
+# The extension is matched against the known formats rather than a bare \w+. A bare \w+
+# happily matched the decimal point in the size, so a line with no file extension parsed
+# as format="5mb" out of "::INFO:: 620.5MB" - taking the title and size down with it, and
+# leaving the result to be discarded by every format filter downstream. Restricting the
+# alternation makes such a line fall through to SIMPLE_RESULT_REGEX and come back as
+# "unknown", which is what the rest of the parser already expects.
+_FORMAT_ALTERNATION = "|".join(re.escape(fmt) for fmt in ALL_RECOGNIZED_FORMATS)
 RESULT_LINE_REGEX = re.compile(
    r"^!(\S+)\s+"  # !ServerName
    r"(.+?)\s+-\s+"  # Author Name -
-    r"(.+?)\.(\w+)"  # Title.format
+    rf"(.+?)\.({_FORMAT_ALTERNATION})\b"  # Title.format
    r"(?:\s+::INFO::\s*(.+?))?"  # Optional ::INFO:: metadata
    r"(?:\s+::HASH::\s*(\S+))?"  # Optional ::HASH::
-    r"\s*$"
+    r"\s*$",
+    re.IGNORECASE,
 )

 # Simpler fallback pattern
@@ -187,18 +192,54 @@ def parse_result_line(line: str) -> SearchResult | None:
    return None


+# Words that mark an archive as holding an audiobook rather than an ebook. Multi-file
+# audiobooks ship as .rar/.zip, so for those the extension says nothing about the content
+# and the release name is the only evidence there is.
+_AUDIOBOOK_MARKER_REGEX = re.compile(
+    r"\b(?:audio ?books?|unabridged|abridged|narrat(?:ed|or)|audible|\d+ ?kbps|"
+    + "|".join(re.escape(fmt) for fmt in AUDIOBOOK_FORMATS)
+    + r")\b",
+    re.IGNORECASE,
+)
+
+_AUDIOBOOK_FORMAT_SET = frozenset(AUDIOBOOK_FORMATS)
+_EBOOK_FORMAT_SET = frozenset(EBOOK_FORMATS)
+
+
+def detect_content_type(result: SearchResult) -> str:
+    """Classify a parsed result as an audiobook or an ebook.
+
+    Extension alone is not enough. It settles the plain cases, but the common audiobook
+    release is a .rar or .zip of MP3s, which is indistinguishable by extension from an
+    ebook archive - so for containers (and for lines with no usable extension) the
+    release name decides.
+    """
+    if result.format in _AUDIOBOOK_FORMAT_SET:
+        return "audiobook"
+    if result.format in _EBOOK_FORMAT_SET:
+        return "ebook"
+    return "audiobook" if _AUDIOBOOK_MARKER_REGEX.search(result.full_line) else "ebook"
+
+
 def parse_results_file(content: str, content_type: str | None = None) -> list[SearchResult]:
    """Parse a search results file into SearchResult objects."""
    results = []
    supported = _get_supported_formats(content_type)
+    requested = "audiobook" if check_audiobook(content_type) else "ebook"

    for line in content.splitlines():
        result = parse_result_line(line)
-        if result and (result.format in supported or result.format == "unknown"):
-            # Filter to user's configured formats
+        if not result:
+            continue
+        # Classify first, then apply the user's format filter within that bucket. Doing it
+        # the other way round is what lost audiobooks entirely: an audiobook .rar matched
+        # neither the ebook nor the audiobook format list, so it fell out of both.
+        if detect_content_type(result) != requested:
+            continue
+        if result.format in supported or result.format == "unknown":
            results.append(result)

-    logger.info("Parsed %s results from search file", len(results))
+    logger.info("Parsed %s %s results from search file", len(results), requested)
    return results


@@ -72,7 +72,10 @@ def irc_settings() -> list[SettingsField]:
            key="IRC_CHANNEL",
            label="Channel",
            placeholder="e.g. ebooks",
-            description="Channel name without the # prefix",
+            description=(
+                "Channel name without the # prefix. Used for all searches unless a "
+                "separate audiobook channel is configured below."
+            ),
            required=True,
            env_supported=True,
        ),
@@ -95,6 +98,42 @@ def irc_settings() -> list[SettingsField]:
            required=True,
            env_supported=True,
        ),
+        HeadingField(
+            key="audiobook_heading",
+            title="Audiobooks",
+            description=(
+                "Most networks index audiobooks in the same channel as ebooks, so leaving "
+                "these blank is the right setting for almost everyone. On irc.irchighway.net "
+                "the audiobooks are in #ebooks and #bookz is effectively inactive — pointing "
+                "this at an empty channel just returns no results. Only fill these in when "
+                "your network really does index audiobooks elsewhere (Undernet's #bookz, for "
+                "example). Audiobooks are usually posted as archives, so keep ZIP and RAR "
+                "enabled under Supported Audiobook Formats or the releases are filtered out."
+            ),
+        ),
+        TextField(
+            key="IRC_AUDIOBOOK_CHANNEL",
+            label="Audiobook channel",
+            placeholder="e.g. bookz",
+            description=(
+                "Optional. Channel name (without the # prefix) for networks that index "
+                "audiobooks separately, such as Undernet's bookz. Leave blank (the usual "
+                "setting) to search the main channel above for audiobooks too."
+            ),
+            required=False,
+            env_supported=True,
+        ),
+        TextField(
+            key="IRC_AUDIOBOOK_SEARCH_BOT",
+            label="Audiobook search bot",
+            placeholder="e.g. search",
+            description=(
+                "Optional. Search bot for the audiobook channel. Leave blank to reuse "
+                "the main search bot above. Only used when an audiobook channel is set."
+            ),
+            required=False,
+            env_supported=True,
+        ),
        HeadingField(
            key="cache_heading",
            title="Search Cache",
@@ -240,6 +240,19 @@ class IRCReleaseSource(ReleaseSource):
        nick = _config_text("IRC_NICK")
        search_bot = _config_text("IRC_SEARCH_BOT")

+        # A few networks index audiobooks in a separate channel from ebooks (Undernet's
+        # #bookz, say). When an audiobook channel is configured and an audiobook was
+        # requested, route the search there (with its own search bot if set). Otherwise
+        # fall back to the main channel/bot — that is the common case, since most networks
+        # (irchighway included) serve both formats from the one channel.
+        if is_audiobook(content_type):
+            audiobook_channel = _config_text("IRC_AUDIOBOOK_CHANNEL")
+            if audiobook_channel:
+                channel = audiobook_channel
+                audiobook_search_bot = _config_text("IRC_AUDIOBOOK_SEARCH_BOT")
+                if audiobook_search_bot:
+                    search_bot = audiobook_search_bot
+
        # Never post an unaddressed query to the channel. A bare book title looks like
        # spam to everyone else in the channel and gets the nick banned. Searches must
        # be addressed to a search bot ("@<bot> <query>").
@@ -14,10 +14,6 @@ from shelfmark.release_sources.prowlarr.torznab import parse_torznab_xml

 logger = setup_logger(__name__)

-# Newznab standard book category IDs
-NEWZNAB_BOOKS = 7000
-NEWZNAB_AUDIOBOOKS = 3030
-

 class NewznabClient:
    """Client for any Newznab-compatible indexer API."""
@@ -8,6 +8,7 @@ from shelfmark.core.settings_registry import (
    HeadingField,
    PasswordField,
    SettingsField,
+    TagListField,
    TextField,
    register_settings,
 )
@@ -86,6 +87,30 @@ def newznab_config_settings() -> list[SettingsField]:
            callback=_test_newznab_connection,
            show_when={"field": "NEWZNAB_ENABLED", "value": True},
        ),
+        TagListField(
+            key="NEWZNAB_EBOOK_CATEGORIES",
+            label="Ebook Categories",
+            description=(
+                "Newznab category IDs searched for ebooks. Most indexers use the standard 7000, "
+                "but some use custom IDs. Leave empty to use 7000."
+            ),
+            placeholder="7000",
+            default=["7000"],
+            normalize_urls=False,
+            show_when={"field": "NEWZNAB_ENABLED", "value": True},
+        ),
+        TagListField(
+            key="NEWZNAB_AUDIOBOOK_CATEGORIES",
+            label="Audiobook Categories",
+            description=(
+                "Newznab category IDs searched for audiobooks. Most indexers use the standard "
+                "3030, but some use custom IDs. Leave empty to use 3030."
+            ),
+            placeholder="3030",
+            default=["3030"],
+            normalize_urls=False,
+            show_when={"field": "NEWZNAB_ENABLED", "value": True},
+        ),
        CheckboxField(
            key="NEWZNAB_AUTO_EXPAND",
            label="Auto-expand search on no results",
@@ -2,6 +2,7 @@

 from __future__ import annotations

+import re
 import time
 from typing import TYPE_CHECKING, ClassVar

@@ -39,15 +40,93 @@ from shelfmark.release_sources.prowlarr.source import (

 logger = setup_logger(__name__)

-# Newznab category IDs
-_AUDIOBOOK_CATS = [3030]
-_BOOK_CATS = [7000]
+# Standard Newznab category IDs, used when the indexer's categories aren't configured.
+_DEFAULT_AUDIOBOOK_CATS = [3030]
+_DEFAULT_BOOK_CATS = [7000]

 # Reuse the same timeout constant as Prowlarr.
 NEWZNAB_SEARCH_TIMEOUT_SECONDS = _SEARCH_TIMEOUT


-def _newznab_result_to_release(result: dict, content_type: str = "ebook") -> Release:
+def _parse_category_ids(raw: object) -> list[int]:
+    """Parse a configured category setting into Newznab category IDs.
+
+    Accepts a list of values or a comma/whitespace separated string. Entries that
+    aren't positive integers are skipped, and duplicates are dropped.
+    """
+    if raw is None:
+        return []
+
+    values = list(raw) if isinstance(raw, (list, tuple)) else [raw]
+
+    category_ids: list[int] = []
+    for value in values:
+        for token in re.split(r"[,\s]+", str(value).strip()):
+            if not token:
+                continue
+            try:
+                category_id = int(token)
+            except ValueError:
+                logger.warning("Newznab: ignoring invalid category ID '%s'", token)
+                continue
+            if category_id > 0 and category_id not in category_ids:
+                category_ids.append(category_id)
+
+    return category_ids
+
+
+def _configured_categories(content_type: str) -> list[int]:
+    """Return the categories to search for a content type, falling back to defaults."""
+    if content_type == "audiobook":
+        key, defaults = "NEWZNAB_AUDIOBOOK_CATEGORIES", _DEFAULT_AUDIOBOOK_CATS
+    else:
+        key, defaults = "NEWZNAB_EBOOK_CATEGORIES", _DEFAULT_BOOK_CATS
+
+    return _parse_category_ids(config.get(key, None)) or list(defaults)
+
+
+def _result_category_ids(categories: object) -> set[int]:
+    """Extract numeric category IDs from a result's categories field."""
+    if not isinstance(categories, (list, tuple)):
+        return set()
+
+    category_ids: set[int] = set()
+    for cat in categories:
+        raw = cat.get("id") if isinstance(cat, dict) else cat
+        try:
+            category_ids.add(int(raw))  # type: ignore[arg-type]
+        except TypeError, ValueError:
+            continue
+    return category_ids
+
+
+def _resolve_content_type(
+    categories: object,
+    content_type: str,
+    searched_categories: list[int] | None,
+) -> str:
+    """Resolve a result's content type, honouring custom indexer categories.
+
+    Indexers using non-standard IDs (e.g. 7100 for ebooks) fall outside the standard
+    ranges, so trust the searched content type when the result carries a category we
+    explicitly asked for.
+    """
+    category_list = list(categories) if isinstance(categories, (list, tuple)) else []
+    detected = _detect_content_type_from_categories(category_list, content_type)
+    if (
+        detected == "other"
+        and searched_categories
+        and _result_category_ids(category_list) & set(searched_categories)
+    ):
+        return "audiobook" if content_type == "audiobook" else "book"
+    return detected
+
+
+def _newznab_result_to_release(
+    result: dict,
+    content_type: str = "ebook",
+    searched_categories: list[int] | None = None,
+) -> Release:
    """Convert a parsed Newznab XML result dict to a Release object."""
    raw_title = result.get("title", "Unknown")
    size_bytes = result.get("size")
@@ -125,7 +204,7 @@ def _newznab_result_to_release(result: dict, content_type: str = "ebook") -> Rel
        indexer=indexer,
        seeders=seeders if is_torrent else None,
        peers=peers_display,
-        content_type=_detect_content_type_from_categories(categories, content_type),
+        content_type=_resolve_content_type(categories, content_type, searched_categories),
        extra={
            "publish_date": result.get("publishDate"),
            "categories": categories,
@@ -230,12 +309,7 @@ class NewznabSource(ReleaseSource):
            return []

        # Category selection — omit categories when expanding search
-        if expand_search:
-            categories = None
-        elif content_type == "audiobook":
-            categories = [3030]
-        else:
-            categories = [7000]
+        categories = None if expand_search else _configured_categories(content_type)

        auto_expand = config.get("NEWZNAB_AUTO_EXPAND", False)
        deadline = time.monotonic() + NEWZNAB_SEARCH_TIMEOUT_SECONDS
@@ -283,7 +357,7 @@ class NewznabSource(ReleaseSource):
            logger.exception("Newznab search failed")
            return []

-        results = [_newznab_result_to_release(r, content_type) for r in all_results]
+        results = [_newznab_result_to_release(r, content_type, categories) for r in all_results]

        if results:
            nzb_count = sum(1 for r in results if r.protocol == ReleaseProtocol.NZB)
@@ -158,36 +158,55 @@ class ProwlarrClient:
            logger.info("Prowlarr connection successful: version %s", version)
            return True, f"Connected to Prowlarr {version}"

-    def get_indexers(self) -> list[dict[str, Any]]:
-        """Get all configured indexers."""
+    def get_indexers(self, *, raise_on_error: bool = False) -> list[dict[str, Any]]:
+        """Get all configured indexers.
+
+        Args:
+            raise_on_error: When True, propagate API failures instead of
+                returning an empty list. Callers that must distinguish
+                "no indexers" from "the request failed" should set this.
+
+        """
        try:
            return _normalize_json_object_list(
                self._request("GET", "/api/v1/indexer"),
                context="Prowlarr indexer list",
            )
        except _PROWLARR_CLIENT_ERRORS:
+            if raise_on_error:
+                raise
            logger.exception("Failed to get indexers")
            return []

-    def get_enabled_indexers_detailed(self) -> list[dict[str, Any]]:
+    def get_enabled_indexers_detailed(
+        self, *, raise_on_error: bool = False
+    ) -> list[dict[str, Any]]:
        """Get enabled indexers, including implementation metadata.

        Note: Prowlarr indexer "name" is user-configurable; prefer
        "implementation"/"implementationName" for stable identification.
        """
-        indexers = self.get_indexers()
+        indexers = self.get_indexers(raise_on_error=raise_on_error)
        return [idx for idx in indexers if idx.get("enable", False)]

-    def get_enriched_indexer_ids(self, *, restrict_to: list[int] | None = None) -> list[int]:
+    def get_enriched_indexer_ids(
+        self,
+        *,
+        restrict_to: list[int] | None = None,
+        indexers: list[dict[str, Any]] | None = None,
+    ) -> list[int]:
        """Return enabled indexer IDs that benefit from extra Torznab handling.

        Args:
            restrict_to: Optional list of candidate indexer IDs to consider.
+            indexers: Optional already-fetched enabled indexer list, so callers
+                that need the full records for other reasons can avoid a second
+                round trip.

        """
        enriched_ids: list[int] = []

-        for idx in self.get_enabled_indexers_detailed():
+        for idx in indexers if indexers is not None else self.get_enabled_indexers_detailed():
            idx_id_int = coerce_int_like(idx.get("id"))
            if idx_id_int is None:
                continue
@@ -214,10 +233,17 @@ class ProwlarrClient:

        Prowlarr exposes seedTime in minutes, which is also the unit expected by
        torrent clients.
+
+        Raises:
+            requests.exceptions.RequestException (and other client errors) when
+            the indexer list cannot be fetched. An empty dict strictly means
+            "no share limits are configured", never "the request failed" -
+            callers rely on this to avoid silently dropping seed limits.
+
        """
        settings_by_indexer: dict[int, IndexerSeedSettings] = {}

-        for idx in self.get_enabled_indexers_detailed():
+        for idx in self.get_enabled_indexers_detailed(raise_on_error=True):
            idx_id_int = coerce_int_like(idx.get("id"))
            if idx_id_int is None:
                continue
@@ -1,10 +1,15 @@
 """Prowlarr download handler - resolves releases and delegates lifecycle to shared clients."""

 from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+import requests

 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.request_helpers import normalize_optional_text
+from shelfmark.core.search_plan import build_release_search_plan
+from shelfmark.core.utils import normalize_http_url
 from shelfmark.download.clients import (
    DownloadClient,
    get_client,
@@ -23,9 +28,13 @@ from shelfmark.download.clients.base_handler import (
    DownloadRequest,
    ExternalClientHandler,
 )
+from shelfmark.metadata_providers import BookMetadata
 from shelfmark.release_sources import register_handler
-from shelfmark.release_sources.prowlarr.cache import get_release, remove_release
+from shelfmark.release_sources.prowlarr.api import IndexerSeedSettings, ProwlarrClient
+from shelfmark.release_sources.prowlarr.cache import cache_release, get_release, remove_release
+from shelfmark.release_sources.prowlarr.source import ProwlarrSource
 from shelfmark.release_sources.prowlarr.utils import (
+    build_source_id,
    coerce_int_like,
    get_preferred_download_url,
    get_protocol,
@@ -37,6 +46,16 @@ if TYPE_CHECKING:
    from shelfmark.core.models import DownloadTask

 logger = setup_logger(__name__)
+
+# Errors that ProwlarrClient can raise when fetching indexer settings.
+_SEED_SETTINGS_FALLBACK_ERRORS = (
+    requests.exceptions.RequestException,
+    OSError,
+    RuntimeError,
+    TypeError,
+    ValueError,
+)
+
 __all__ = [
    "ProwlarrHandler",
    "POLL_INTERVAL",
@@ -49,6 +68,11 @@ __all__ = [
 POLL_INTERVAL = _DEFAULT_POLL_INTERVAL
 COMPLETED_PATH_RETRY_INTERVAL = _DEFAULT_COMPLETED_PATH_RETRY_INTERVAL
 COMPLETED_PATH_MAX_ATTEMPTS = _DEFAULT_COMPLETED_PATH_MAX_ATTEMPTS
+EXPIRED_LINK_REFRESH_ERROR = (
+    "The indexer download link expired and the release could not be refreshed. "
+    "Search again for a fresh result."
+)
+HASH_DETECTION_ERROR = "Could not determine torrent hash from URL"


 def _coerce_positive_minutes(raw_minutes: object) -> int | None:
@@ -62,6 +86,47 @@ def _coerce_positive_minutes(raw_minutes: object) -> int | None:
 class ProwlarrHandler(ExternalClientHandler):
    """Handler for Prowlarr downloads via configured torrent or usenet client."""

+    @staticmethod
+    def _build_prowlarr_client() -> ProwlarrClient | None:
+        """Build a ProwlarrClient from config, or None if not configured."""
+        raw_url = config.get("PROWLARR_URL", "")
+        raw_api_key = config.get("PROWLARR_API_KEY", "")
+        url = normalize_optional_text(raw_url) if isinstance(raw_url, str) else None
+        api_key = normalize_optional_text(raw_api_key) if isinstance(raw_api_key, str) else None
+        if not url or not api_key:
+            return None
+        normalized_url = normalize_http_url(url)
+        if not normalized_url:
+            return None
+        return ProwlarrClient(normalized_url, api_key)
+
+    def _fetch_seed_settings_fallback(self, raw_indexer_id: object) -> IndexerSeedSettings | None:
+        """Fetch share limits for one indexer directly from Prowlarr.
+
+        Used when the cached release is missing its search-time seed-limit
+        enrichment so that transient failures during search cannot cause a
+        torrent to be added without its configured share limits.
+        """
+        indexer_id = coerce_int_like(raw_indexer_id)
+        if indexer_id is None:
+            return None
+
+        client = self._build_prowlarr_client()
+        if client is None:
+            return None
+
+        try:
+            settings = client.get_indexer_seed_settings(restrict_to=[indexer_id])
+        except _SEED_SETTINGS_FALLBACK_ERRORS:
+            logger.warning(
+                "Grab-time seed settings fallback failed for indexerId=%s",
+                indexer_id,
+                exc_info=True,
+            )
+            return None
+
+        return settings.get(indexer_id)
+
    def _get_client(self, protocol: str) -> DownloadClient | None:
        """Compatibility shim so module-level patching still works in tests."""
        return get_client(protocol)
@@ -81,18 +146,30 @@ class ProwlarrHandler(ExternalClientHandler):

    def build_retry_resolution_fields(self, release_data: dict[str, Any]) -> dict[str, Any]:
        source_id = normalize_optional_text(release_data.get("source_id"))
-        if source_id is None:
-            return {}
+        extra = release_data.get("extra")
+        if not isinstance(extra, dict):
+            extra = {}

-        prowlarr_result = get_release(source_id)
-        if prowlarr_result is None:
-            return {}
+        retry_source_context: dict[str, Any] = {}
+        indexer_id = release_data.get("indexer_id") or extra.get("indexer_id")
+        if indexer_id is not None:
+            retry_source_context["indexer_id"] = indexer_id
+
+        indexer = normalize_optional_text(release_data.get("indexer") or extra.get("indexer"))
+        if indexer is not None and indexer.lower() != "unknown":
+            retry_source_context["indexer"] = indexer
+
+        info_url = normalize_optional_text(release_data.get("info_url") or extra.get("info_url"))
+        if info_url is not None:
+            retry_source_context["info_url"] = info_url
+
+        if source_id is not None:
+            retry_source_context["source_id"] = source_id

        return {
-            "retry_download_url": normalize_optional_text(
-                get_preferred_download_url(prowlarr_result)
-            ),
-            "retry_download_protocol": normalize_optional_text(get_protocol(prowlarr_result)),
+            "retry_download_url": None,
+            "retry_download_protocol": None,
+            "retry_source_context": retry_source_context,
        }

    @classmethod
@@ -139,13 +216,12 @@ class ProwlarrHandler(ExternalClientHandler):
        # Look up the cached release
        prowlarr_result = get_release(task.task_id)
        if not prowlarr_result:
-            restored_request = self._restore_download_request_from_task(task)
-            if restored_request is None:
-                logger.warning("Release cache miss: %s", task.task_id)
-                status_callback("error", "Release not found in cache (may have expired)")
+            logger.info("Prowlarr release cache miss, refreshing: %s", task.task_id)
+            prowlarr_result = self._refresh_release(task)
+            if prowlarr_result is None:
+                logger.warning("Prowlarr release refresh failed: %s", task.task_id)
+                status_callback("error", EXPIRED_LINK_REFRESH_ERROR)
                return None
-            logger.info("Restored Prowlarr download request for retry: %s", task.task_id)
-            return restored_request

        # Extract download URL
        download_url = get_preferred_download_url(prowlarr_result)
@@ -171,6 +247,28 @@ class ProwlarrHandler(ExternalClientHandler):
            seeding_time_limit = _coerce_positive_minutes(raw_configured_seed_time)
            ratio_limit = float(raw_configured_ratio) if raw_configured_ratio is not None else None

+            # Fallback: search-time enrichment can be missing when the indexer
+            # settings fetch transiently failed during the search (#795).
+            # Re-resolve the limits from Prowlarr at grab time so torrents are
+            # never sent to the client without their configured share limits.
+            if seeding_time_limit is None and ratio_limit is None and protocol == "torrent":
+                fallback = self._fetch_seed_settings_fallback(prowlarr_result.get("indexerId"))
+                if fallback:
+                    seeding_time_limit = _coerce_positive_minutes(
+                        fallback.get("seeding_time_limit_minutes")
+                    )
+                    raw_ratio = fallback.get("ratio_limit")
+                    ratio_limit = float(raw_ratio) if raw_ratio is not None else None
+
+            if seeding_time_limit is None and ratio_limit is None and protocol == "torrent":
+                logger.warning(
+                    "Prowlarr seed preferences are enabled but no share limits "
+                    "could be resolved for release '%s' (indexerId=%s); the "
+                    "torrent will use the client's global limits",
+                    release_name,
+                    prowlarr_result.get("indexerId"),
+                )
+
        return DownloadRequest(
            url=download_url,
            protocol=protocol,
@@ -180,6 +278,92 @@ class ProwlarrHandler(ExternalClientHandler):
            ratio_limit=ratio_limit,
        )

+    def _refresh_release(self, task: DownloadTask) -> dict[str, Any] | None:
+        """Re-query Prowlarr and cache the exact original release if it still exists."""
+        title = normalize_optional_text(task.title)
+        if title is None:
+            return None
+
+        context = getattr(task, "retry_source_context", None)
+        if not isinstance(context, dict):
+            context = {}
+
+        indexer = normalize_optional_text(context.get("indexer"))
+        book = BookMetadata(
+            provider="shelfmark",
+            provider_id=task.task_id,
+            title=title,
+            authors=[task.author] if task.author else [],
+            search_title=title,
+            search_author=task.author,
+        )
+        plan = build_release_search_plan(
+            book,
+            indexers=[indexer] if indexer is not None else None,
+        )
+
+        source = ProwlarrSource()
+        results = source.search(book, plan, content_type=task.content_type or "ebook")
+        for release in results:
+            raw_release = get_release(release.source_id)
+            if raw_release is None:
+                continue
+            if not self._raw_release_matches_task(raw_release, task.task_id):
+                continue
+
+            cache_release(task.task_id, raw_release)
+            logger.info("Refreshed Prowlarr release: %s", task.task_id)
+            return raw_release
+
+        return None
+
+    @staticmethod
+    def _raw_release_matches_task(raw_release: dict[str, Any], task_id: str) -> bool:
+        wanted = normalize_optional_text(task_id)
+        if wanted is None:
+            return False
+
+        bare = [
+            identity
+            for identity in (
+                normalize_optional_text(raw_release.get("guid")),
+                normalize_optional_text(raw_release.get("infoUrl")),
+            )
+            if identity is not None
+        ]
+
+        identities = [*bare, build_source_id(raw_release)]
+        indexer_id = coerce_int_like(raw_release.get("indexerId"))
+        if indexer_id is not None:
+            identities.extend(f"{indexer_id}:{identity}" for identity in bare)
+
+        return wanted in identities
+
+    def _refresh_download_request_after_add_failure(
+        self,
+        *,
+        task: DownloadTask,
+        request: DownloadRequest,
+        error: Exception,
+        status_callback: Callable[[str, str | None], None],
+    ) -> DownloadRequest | None:
+        """Refresh once when a cached Prowlarr torrent proxy URL has expired."""
+        if request.protocol != "torrent":
+            return None
+        if HASH_DETECTION_ERROR not in str(error):
+            return None
+
+        parsed = urlparse(request.url)
+        if parsed.scheme.lower() not in {"http", "https"}:
+            return None
+
+        logger.info("Refreshing stale Prowlarr torrent URL for %s", task.task_id)
+        remove_release(task.task_id)
+        refreshed_request = self._resolve_download(task, status_callback)
+        if refreshed_request is None:
+            raise RuntimeError(EXPIRED_LINK_REFRESH_ERROR) from error
+        return refreshed_request
+
    def _on_download_complete(self, task: DownloadTask) -> None:
        """Remove completed release from the Prowlarr cache."""
        remove_release(task.task_id)
@@ -190,6 +190,18 @@ def prowlarr_config_settings() -> list[SettingsField]:
            description="Automatically retry search without category filtering if no results are found",
            show_when={"field": "PROWLARR_ENABLED", "value": True},
        ),
+        CheckboxField(
+            key="PROWLARR_COLLAPSE_DUPLICATES",
+            label="Show one row per release",
+            default=True,
+            description=(
+                "Collapse a release that several indexer entries returned down to a single row, "
+                "keeping the entry with the best Prowlarr priority. Turn this off to see every "
+                "entry that carried it, which is what makes results from filter-specific entries "
+                "(freeleech and the like) visible."
+            ),
+            show_when={"field": "PROWLARR_ENABLED", "value": True},
+        ),
        CheckboxField(
            key="PROWLARR_USE_SEED_PREFERENCES",
            label="Use Prowlarr seed preferences",
@@ -2,16 +2,21 @@

 import re
 import time
+from threading import Lock
 from typing import TYPE_CHECKING, ClassVar, NoReturn

+import requests
+
 if TYPE_CHECKING:
    from shelfmark.core.search_plan import ReleaseSearchPlan
    from shelfmark.metadata_providers import BookMetadata

 from shelfmark.core.config import config
+from shelfmark.core.languages import normalize_language
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.request_helpers import normalize_optional_text
 from shelfmark.core.search_plan import ReleaseSearchVariant
+from shelfmark.core.utils import AUDIOBOOK_FORMATS as CORE_AUDIOBOOK_FORMATS
 from shelfmark.core.utils import normalize_http_url
 from shelfmark.release_sources import (
    ColumnAlign,
@@ -30,6 +35,7 @@ from shelfmark.release_sources import (
 from shelfmark.release_sources.prowlarr.api import IndexerSeedSettings, ProwlarrClient
 from shelfmark.release_sources.prowlarr.cache import cache_release
 from shelfmark.release_sources.prowlarr.utils import (
+    build_source_id,
    coerce_float_like,
    coerce_int_like,
    get_protocol,
@@ -41,6 +47,14 @@ _SIZE_UNIT_BASE = 1024
 _TWO_FORMATS = 2
 _PROWLARR_SOURCE_ERRORS = (AttributeError, OSError, RuntimeError, TypeError, ValueError)

+# Prowlarr indexer priority is 1-50 and lower is preferred; unknown sorts last.
+_UNRANKED_INDEXER_RANK = 51
+
+# Errors that can surface from ProwlarrClient.get_indexer_seed_settings(). The
+# client raises requests exceptions (subclasses of OSError via IOError lineage
+# is not guaranteed), so include RequestException explicitly.
+_PROWLARR_SEED_SETTINGS_ERRORS = (*_PROWLARR_SOURCE_ERRORS, requests.exceptions.RequestException)
+

 def _raise_timeout_error(message: str) -> NoReturn:
    raise TimeoutError(message)
@@ -61,6 +75,118 @@ def _coerce_indexer_id(value: object) -> int | None:
    return coerce_int_like(value)


+def _identity_text(value: object) -> str | None:
+    """Trimmed text for an identity field, or None when there is nothing usable."""
+    if isinstance(value, str):
+        return value.strip() or None
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return str(value)
+    return None
+
+
+def _release_identity(result: dict) -> str | None:
+    """Identify the underlying release, independent of which indexer surfaced it.
+
+    Strong identifiers only. Title is deliberately excluded because matching on
+    it here would merge two genuinely different releases that happen to share a
+    name, and every caller of this either drops or overwrites a row on a match.
+    Returns None when nothing identifies the result.
+    """
+    for field in ("guid", "downloadUrl", "magnetUrl", "infoUrl"):
+        identity = _identity_text(result.get(field))
+        if identity is not None:
+            return identity
+    return None
+
+
+def _result_dedup_key(result: dict) -> tuple[int | None, str] | None:
+    """Dedup key for a raw Prowlarr result, or None if it cannot be identified.
+
+    One tracker is often configured in Prowlarr as several indexer entries that
+    differ only by a server-side search filter, say a "freeleech only" entry
+    alongside an unfiltered one. Those entries return the same guid for the same
+    torrent, so keying on the guid alone throws away the filtered entry's copy
+    and with it the only signal that the release matched the filter. Including
+    the indexer id keeps the entries distinct.
+
+    Title is an acceptable last resort here, unlike in _release_identity, because
+    the indexer id is part of the key: it only ever collapses a literal repeat
+    from one indexer, never two rows from different entries.
+    """
+    identity = _release_identity(result) or _identity_text(result.get("title"))
+    if identity is None:
+        return None
+    return (_coerce_indexer_id(result.get("indexerId")), identity)
+
+
+def _build_indexer_priority(indexers: list[dict]) -> dict[int, int]:
+    """Map indexer id to the priority configured in Prowlarr. Lower is preferred.
+
+    Users already rank their indexers in Prowlarr, and on trackers configured as
+    several entries that ranking is usually the meaningful one: a "freeleech
+    only" entry is typically given a better priority than the unfiltered entry
+    beside it. Reusing it avoids asking for the same ordering a second time.
+    """
+    priority: dict[int, int] = {}
+    for indexer in indexers:
+        indexer_id = _coerce_indexer_id(indexer.get("id"))
+        if indexer_id is None:
+            continue
+        rank = coerce_int_like(indexer.get("priority"))
+        if rank is not None:
+            priority[indexer_id] = rank
+
+    return priority
+
+
+def _rank_for_indexer_id(indexer_id: object, priority: dict[int, int]) -> int:
+    """Preference rank for an indexer id. Lower wins, unknown ranks last."""
+    coerced = _coerce_indexer_id(indexer_id)
+    if coerced is None:
+        return _UNRANKED_INDEXER_RANK
+    return priority.get(coerced, _UNRANKED_INDEXER_RANK)
+
+
+def _indexer_rank(result: dict, priority: dict[int, int]) -> int:
+    """Preference rank of the indexer that surfaced a raw result."""
+    return _rank_for_indexer_id(result.get("indexerId"), priority)
+
+
+def _release_indexer_rank(release: Release, priority: dict[int, int]) -> int:
+    """Preference rank of the indexer that surfaced a converted release."""
+    return _rank_for_indexer_id(release.extra.get("indexer_id"), priority)
+
+
+def _collapse_duplicate_indexer_results(
+    results: list[dict], priority: dict[int, int]
+) -> list[dict]:
+    """Reduce a release to a single row, keeping the preferred indexer entry.
+
+    Opt-in behaviour for users who want one row per torrent. Ties keep the
+    result that was queried first, and the winner holds the loser's position so
+    the overall result order stays stable.
+    """
+    position_by_identity: dict[str, int] = {}
+    kept: list[dict] = []
+
+    for result in results:
+        identity = _release_identity(result)
+        if identity is None:
+            kept.append(result)
+            continue
+
+        existing_position = position_by_identity.get(identity)
+        if existing_position is None:
+            position_by_identity[identity] = len(kept)
+            kept.append(result)
+            continue
+
+        if _indexer_rank(result, priority) < _indexer_rank(kept[existing_position], priority):
+            kept[existing_position] = result
+
+    return kept
+
+
 def _parse_size(size_bytes: int | None) -> str | None:
    """Convert bytes to human-readable size string."""
    if size_bytes is None or size_bytes <= 0:
@@ -97,55 +223,11 @@ EBOOK_FORMATS = [
 ]

 # Common audiobook formats
-AUDIOBOOK_FORMATS = ["m4b", "mp3", "m4a", "flac", "ogg", "wma", "aac", "wav", "opus"]
+AUDIOBOOK_FORMATS = list(CORE_AUDIOBOOK_FORMATS)

 # Combined list for format detection (audiobook formats first for priority)
 ALL_BOOK_FORMATS = AUDIOBOOK_FORMATS + EBOOK_FORMATS

-# Map 3-char MAM language codes to 2-char ISO codes used by frontend color maps
-MAM_LANGUAGE_MAP = {
-    "eng": "en",
-    "ita": "it",
-    "spa": "es",
-    "fra": "fr",
-    "fre": "fr",
-    "ger": "de",
-    "deu": "de",
-    "por": "pt",
-    "rus": "ru",
-    "jpn": "ja",
-    "jap": "ja",
-    "chi": "zh",
-    "zho": "zh",
-    "dut": "nl",
-    "nld": "nl",
-    "swe": "sv",
-    "nor": "no",
-    "dan": "da",
-    "fin": "fi",
-    "pol": "pl",
-    "cze": "cs",
-    "ces": "cs",
-    "hun": "hu",
-    "kor": "ko",
-    "ara": "ar",
-    "heb": "he",
-    "tur": "tr",
-    "gre": "el",
-    "ell": "el",
-    "hin": "hi",
-    "tha": "th",
-    "vie": "vi",
-    "ind": "id",
-    "ukr": "uk",
-    "rom": "ro",
-    "ron": "ro",
-    "bul": "bg",
-    "cat": "ca",
-    "hrv": "hr",
-    "slv": "sl",
-    "srp": "sr",
-}

 # Backend safeguard: cap total Prowlarr search time per request.
 PROWLARR_SEARCH_TIMEOUT_SECONDS = 120.0
@@ -193,8 +275,9 @@ def _extract_mam_language(raw_title: str) -> str | None:

        for token in tokens:
            lang_code = token.lower()
-            if lang_code in MAM_LANGUAGE_MAP:
-                return MAM_LANGUAGE_MAP[lang_code]
+            resolved = normalize_language(lang_code)
+            if resolved is not None:
+                return resolved

    return None

@@ -379,8 +462,7 @@ def _prowlarr_result_to_release(
        formats_display = _formats_display(formats)
        language_detected = _extract_mam_language(str(raw_title or ""))

-    # Build the source_id from GUID or generate from indexer + title
-    source_id = result.get("guid") or f"{indexer}:{hash(raw_title)}"
+    source_id = build_source_id(result)

    # Cache the raw Prowlarr result so handler can look it up by source_id
    cache_release(source_id, result)
@@ -443,6 +525,36 @@ def _prowlarr_result_to_release(
    )


+# Last successfully fetched per-indexer share limits. Used as a fallback when
+# a transient Prowlarr API failure prevents fetching fresh settings during a
+# search, so results are never silently cached without seed limits (#795).
+_seed_settings_lock = Lock()
+_last_known_seed_settings: dict[int, IndexerSeedSettings] = {}
+
+
+def _fetch_indexer_seed_settings(
+    client: ProwlarrClient,
+    indexer_ids: list[int] | None,
+) -> dict[int, IndexerSeedSettings]:
+    """Fetch per-indexer share limits, falling back to last-known-good on failure."""
+    try:
+        fetched = client.get_indexer_seed_settings(restrict_to=indexer_ids)
+    except _PROWLARR_SEED_SETTINGS_ERRORS:
+        with _seed_settings_lock:
+            fallback = dict(_last_known_seed_settings)
+        logger.warning(
+            "Failed to fetch Prowlarr indexer seed settings; "
+            "falling back to last known settings for %s indexer(s)",
+            len(fallback),
+            exc_info=True,
+        )
+        return fallback
+
+    with _seed_settings_lock:
+        _last_known_seed_settings.update(fetched)
+    return fetched
+
+
 def _apply_indexer_seed_settings(
    result: dict,
    indexer_seed_settings: dict[int, IndexerSeedSettings],
@@ -574,6 +686,11 @@ class ProwlarrSource(ReleaseSource):
            ],
            extra_sort_options=[
                SortOption(label="Peers", sort_key="seeders"),
+                SortOption(
+                    label="Indexer priority",
+                    sort_key="extra.indexer_priority",
+                    default_direction="asc",
+                ),
            ],
            grid_template="minmax(0,2fr) minmax(140px,1fr) 50px 50px 90px 80px",
            leading_cell=LeadingCellConfig(
@@ -779,11 +896,15 @@ class ProwlarrSource(ReleaseSource):
        try:
            auto_expand_enabled = config.get("PROWLARR_AUTO_EXPAND", False)
            deadline = time.monotonic() + PROWLARR_SEARCH_TIMEOUT_SECONDS
+            enabled_indexers = client.get_enabled_indexers_detailed()
+            indexer_priority = _build_indexer_priority(enabled_indexers)
            # Some indexers benefit from title+author queries and extra format detection.
-            enriched_indexer_ids = client.get_enriched_indexer_ids(restrict_to=indexer_ids)
+            enriched_indexer_ids = client.get_enriched_indexer_ids(
+                restrict_to=indexer_ids, indexers=enabled_indexers
+            )
            enriched_indexer_ids_set = set(enriched_indexer_ids)
            indexer_seed_settings = (
-                client.get_indexer_seed_settings(restrict_to=indexer_ids)
+                _fetch_indexer_seed_settings(client, indexer_ids)
                if config.get("PROWLARR_USE_SEED_PREFERENCES", False)
                else {}
            )
@@ -821,7 +942,7 @@ class ProwlarrSource(ReleaseSource):

                return results

-            seen_keys: set[str] = set()
+            seen_keys: set[tuple[int | None, str]] = set()
            all_results: list[dict] = []

            for idx, variant in enumerate(variants, start=1):
@@ -849,18 +970,22 @@ class ProwlarrSource(ReleaseSource):
                    self.last_search_type = "expanded"

                for r in raw_results:
-                    key = (
-                        r.get("guid")
-                        or r.get("downloadUrl")
-                        or r.get("magnetUrl")
-                        or r.get("infoUrl")
-                        or f"{r.get('indexerId')}:{r.get('title')}"
-                    )
-                    if key in seen_keys:
-                        continue
-                    seen_keys.add(key)
+                    key = _result_dedup_key(r)
+                    if key is not None:
+                        if key in seen_keys:
+                            continue
+                        seen_keys.add(key)
                    all_results.append(r)

+            if config.get("PROWLARR_COLLAPSE_DUPLICATES", True):
+                before_collapse = len(all_results)
+                all_results = _collapse_duplicate_indexer_results(all_results, indexer_priority)
+                if len(all_results) != before_collapse:
+                    logger.debug(
+                        "Prowlarr: collapsed %s duplicate result(s) across indexer entries",
+                        before_collapse - len(all_results),
+                    )
+
            results: list[Release] = []
            enriched_source_ids: set[str] = set()

@@ -879,13 +1004,19 @@ class ProwlarrSource(ReleaseSource):
                    content_type,
                    enable_format_detection=is_enriched,
                )
+                if idx_id_int is not None and idx_id_int in indexer_priority:
+                    release.extra["indexer_priority"] = indexer_priority[idx_id_int]
                results.append(release)

                if is_enriched:
                    enriched_source_ids.add(release.source_id)

-            # Sort results: enriched indexers first, then others
-            results.sort(key=lambda r: 0 if r.source_id in enriched_source_ids else 1)
+            results.sort(
+                key=lambda r: (
+                    _release_indexer_rank(r, indexer_priority),
+                    0 if r.source_id in enriched_source_ids else 1,
+                )
+            )

            if results:
                torrent_count = sum(1 for r in results if r.protocol == ReleaseProtocol.TORRENT)
@@ -32,6 +32,28 @@ def coerce_int_like(value: object) -> int | None:
    return int(normalized)


+def build_source_id(result: dict) -> str:
+    """Build the Release.source_id for a raw Prowlarr result.
+
+    Qualified by the indexer id because one tracker is often configured in
+    Prowlarr as several indexer entries that differ only by a server-side search
+    filter, and those entries return the same guid for the same torrent. Without
+    the qualifier the entries collide in the release cache and a grab routes
+    through whichever entry happened to cache last.
+    """
+    guid = result.get("guid")
+    if guid:
+        base = str(guid)
+    else:
+        indexer = result.get("indexer", "Unknown")
+        base = f"{indexer}:{hash(result.get('title', 'Unknown'))}"
+
+    indexer_id = coerce_int_like(result.get("indexerId"))
+    if indexer_id is None:
+        return base
+    return f"{indexer_id}:{base}"
+
+
 def coerce_float_like(value: object) -> float | None:
    """Return a float for float-like config/API values, else None."""
    if isinstance(value, bool):
@@ -17,24 +17,24 @@
    "test:unit": "vitest run"
  },
  "dependencies": {
-    "@tailwindcss/vite": "^4.3.2",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "react-router-dom": "^7.18.1",
+    "@tailwindcss/vite": "^4.3.3",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router-dom": "^7.18.2",
    "socket.io-client": "^4.7.5"
  },
  "devDependencies": {
-    "@types/node": "^26.0.1",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.3",
-    "knip": "^6.23.0",
-    "oxfmt": "^0.57.0",
-    "oxlint": "^1.72.0",
-    "oxlint-tsgolint": "^0.23.0",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
+    "knip": "^6.32.1",
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "oxlint-tsgolint": "^7.0.2001",
    "tailwindcss": "^4.2.2",
-    "typescript": "^6.0.3",
-    "vite": "^8.1.0",
-    "vitest": "^4.1.9"
+    "typescript": "^7.0.2",
+    "vite": "^8.2.1",
+    "vitest": "^4.1.10"
  }
 }
@@ -1098,6 +1098,9 @@ function App() {
        series_name: book.series_name,
        series_position: book.series_position,
        subtitle: book.subtitle,
+        // From the release, never the book: book.language is the provider's
+        // canonical edition, which would mislabel a translated release.
+        language: release.language ?? undefined,
      };
    },
    [],
@@ -382,7 +382,11 @@ export const ReleaseCell = ({
          className={`flex items-center ${alignClass} gap-1.5 truncate text-xs text-gray-600 dark:text-gray-300`}
        >
          <span className={`h-2 w-2 shrink-0 rounded-full ${dotColor}`} title={protocolLabel} />
-          <span className="truncate">{displayValue}</span>
+          {/* Titled because one tracker can appear as several indexer entries whose
+              names share a prefix, and truncation would make the rows look identical */}
+          <span className="truncate" title={displayValue}>
+            {displayValue}
+          </span>
          {peers && <span className="shrink-0 text-gray-400 dark:text-gray-500">{peers}</span>}
        </div>
      );
@@ -956,7 +956,7 @@ const ReleaseModalSession = ({
    const fromExtra = (columnConfig.extra_sort_options || []).map((opt) => ({
      label: opt.label,
      sortKey: opt.sort_key,
-      defaultDirection: 'desc' as const, // Extra sort options are typically numeric (e.g., peers)
+      defaultDirection: opt.default_direction ?? ('desc' as const),
    }));
    return [...fromColumns, ...fromExtra];
  }, [sortableColumns, columnConfig.extra_sort_options]);
@@ -21,7 +21,6 @@ import {
  normalizeUserOverrideSections,
  UserOverridesSections,
 } from './users';
-import type { PerUserSettings } from './users/types';
 import { UserAccountCardContent, UserEditActions, UserIdentityHeader } from './users/UserCard';
 import { useUserOverridesState } from './users/useUserOverridesState';

@@ -153,7 +152,7 @@ const SelfSettingsModalSession = ({
        normalizeUserOverrideSections(context.visibleUserSettingsSections, 'self'),
      );
      applyUserOverridesContext({
-        settings: (context.user.settings || {}) as PerUserSettings,
+        settings: context.user.settings || {},
        userOverridableKeys: context.userOverridableKeys || [],
      });
      setEditPassword('');
@@ -146,7 +146,7 @@ export const useUsersFetch = ({ onShowToast }: UseUsersFetchParams) => {
    if (fullUser.settings) {
      userSettings = {
        ...fullUser.settings,
-      } as PerUserSettings;
+      };
    }
    const userOverridableSettings = new Set<string>();

@@ -162,7 +162,7 @@ export const useUsersFetch = ({ onShowToast }: UseUsersFetchParams) => {
        userSettings = {
          ...userSettings,
          ...deliveryResult.value.userOverrides,
-        } as PerUserSettings;
+        };
      }
      deliveryResult.value.keys.forEach((key) => userOverridableSettings.add(key));
    }
@@ -173,7 +173,7 @@ export const useUsersFetch = ({ onShowToast }: UseUsersFetchParams) => {
        userSettings = {
          ...userSettings,
          ...searchResult.value.userOverrides,
-        } as PerUserSettings;
+        };
      }
      searchResult.value.keys.forEach((key) => userOverridableSettings.add(key));
    }
@@ -184,7 +184,7 @@ export const useUsersFetch = ({ onShowToast }: UseUsersFetchParams) => {
        userSettings = {
          ...userSettings,
          ...notificationResult.value.userOverrides,
-        } as PerUserSettings;
+        };
      }
      notificationResult.value.keys.forEach((key) => userOverridableSettings.add(key));
    }
@@ -144,6 +144,11 @@ const mapApiErrorToActionResult = (error: unknown): ActionResult | null => {
 // Default request timeout in milliseconds (30 seconds)
 const DEFAULT_TIMEOUT_MS = 30000;

+// Release searches can be long-running: a source behind Cloudflare/DDoS-Guard has
+// to spin up the bypasser and solve the challenge before any results come back,
+// which routinely takes well over the default timeout.
+const SEARCH_TIMEOUT_MS = 180000;
+
 // Utility function for JSON fetch with credentials and timeout
 async function fetchJSON<T>(
  url: string,
@@ -235,6 +240,8 @@ export const searchBooks = async (query: string): Promise<Book[]> => {
  if (!query) return [];
  const response = await fetchJSON<ReleasesResponse>(
    `${API_BASE}/releases?source=direct_download&${query}`,
+    {},
+    SEARCH_TIMEOUT_MS,
  );
  return response.releases.map(transformReleaseToDirectBook);
 };
@@ -500,6 +507,7 @@ export type DownloadReleasePayload = {
  series_name?: string;
  series_position?: number;
  subtitle?: string;
+  language?: string; // Release language code, for the {Language} naming variable
  search_author?: string;
  search_mode?: 'direct' | 'universal';
 };
@@ -48,4 +48,47 @@ describe('namingTemplatePreview', () => {
    expect(preview.unknownTokens).toEqual(['NotAThing']);
    expect(preview.value).toBe('Arthur Conan Doyle');
  });
+
+  it('offers Language as a core variable for both content types', () => {
+    const language = NAMING_TEMPLATE_TOKENS.find((token) => token.token === 'Language');
+
+    expect(language?.group).toBe('Core');
+    expect(language?.audiobookOnly).toBeFalsy();
+  });
+
+  it('separates translated editions into their own folder', () => {
+    const template = '{Author}/{Title}{ (Language)}';
+
+    const swedish = renderNamingTemplate(
+      template,
+      {
+        ...SAMPLE_NAMING_METADATA,
+        Author: 'Andy Weir',
+        Title: 'Project Hail Mary',
+        Language: 'sv',
+      },
+      { allowPathSeparators: true },
+    );
+    const english = renderNamingTemplate(
+      template,
+      { ...SAMPLE_NAMING_METADATA, Author: 'Andy Weir', Title: 'Project Hail Mary', Language: '' },
+      { allowPathSeparators: true },
+    );
+
+    expect(swedish.value).toBe('Andy Weir/Project Hail Mary (sv)');
+    expect(english.value).toBe('Andy Weir/Project Hail Mary');
+    expect(swedish.value).not.toBe(english.value);
+  });
+
+  it('keeps the picker and the known-token list in lockstep', () => {
+    // KNOWN_TOKENS is a hand-maintained duplicate of the Python list. A token
+    // added to the picker but not to it would render as an unknown variable.
+    for (const token of NAMING_TEMPLATE_TOKENS) {
+      const preview = renderNamingTemplate(`{${token.token}}`, SAMPLE_NAMING_METADATA, {
+        allowPathSeparators: true,
+      });
+
+      expect(preview.unknownTokens, `${token.token} is missing from KNOWN_TOKENS`).toEqual([]);
+    }
+  });
 });
@@ -138,4 +138,29 @@ describe('requestPayload utilities', () => {
    );
    expect(getRequestSuccessMessage(payloadUntitled)).toBe('Request submitted: Untitled');
  });
+
+  it('takes the language from the release, not the book', () => {
+    // book.language is the metadata provider's canonical edition. Using it would
+    // label a Swedish release "en" and put both editions back in one folder.
+    const data = buildReleaseDataFromMetadataRelease(
+      { ...baseBook, language: 'en' },
+      { ...baseRelease, language: 'sv' },
+      'ebook',
+    );
+
+    expect(data.language).toBe('sv');
+  });
+
+  it('leaves language undefined when the release has none', () => {
+    const data = buildReleaseDataFromMetadataRelease(baseBook, baseRelease, 'ebook');
+
+    expect(data.language).toBeUndefined();
+  });
+
+  it('uses the book language when browsing a source directly', () => {
+    // In direct mode the book record IS the release record.
+    const data = buildReleaseDataFromDirectBook({ ...baseBook, language: 'de' });
+
+    expect(data.language).toBe('de');
+  });
 });
@@ -414,6 +414,7 @@ export interface LeadingCellConfig {
 export interface ExtraSortOption {
  label: string; // Display label in the sort dropdown
  sort_key: string; // Field to sort by on the Release object
+  default_direction?: 'asc' | 'desc'; // Which way "best first" runs (defaults to desc)
 }

 export interface SourceActionButton {
@@ -48,6 +48,13 @@ export const NAMING_TEMPLATE_TOKENS: NamingTemplateToken[] = [
    value: '1902',
    group: 'Core',
  },
+  {
+    token: 'Language',
+    label: 'Language',
+    description: 'Release language code, so translations do not share a folder',
+    value: 'en',
+    group: 'Core',
+  },
  {
    token: 'User',
    label: 'User',
@@ -98,6 +105,7 @@ const KNOWN_TOKENS = [
  'primarytitle',
  'originalname',
  'partnumber',
+  'language',
  'subtitle',
  'author',
  'series',
@@ -90,6 +90,7 @@ export const buildReleaseDataFromMetadataRelease = (
    series_position: book.series_position,
    series_count: book.series_count,
    subtitle: book.subtitle,
+    language: release.language,
    ...(isSourceBackedReleaseContext ? { search_mode: 'direct' as const } : {}),
  };
 };
@@ -106,6 +107,8 @@ export const buildReleaseDataFromDirectBook = (book: Book) => {
    size: book.size,
    preview: book.preview,
    content_type: 'ebook' as const,
+    // Browsing a source directly means the book record IS the release record.
+    language: book.language,
    search_mode: 'direct' as const,
  };
 };
@@ -169,6 +169,7 @@ uv run pytest tests/ --cov=shelfmark -m "not integration"
 ```python
 from unittest.mock import MagicMock, patch

+
 class TestMyFeature:
    def test_something(self, monkeypatch):
        # Mock config values
@@ -188,6 +189,7 @@ class TestMyFeature:
 import pytest
 from .conftest import APIClient, DownloadTracker

+
@pytest.mark.e2e
 class TestMyEndpoint:
    def test_endpoint_works(self, protected_api_client: APIClient):
@@ -0,0 +1,221 @@
+"""DDoS-Guard cookie reuse between requests.
+
+Anna's Archive issues nine cookies after a solve, and they are not equivalent:
+
+    __ddg1_/__ddg2_/__ddgid_   ~1 year   clearance
+    __ddgmark_                 ~1 day
+    __ddg5_                    session
+    __ddg8_/__ddg9_/__ddg10_   ~40 min   one check: token, CLIENT IP, TIMESTAMP
+
+Replaying the last three is what produces the ?check=1 redirect loop. They describe a
+single check, so once the timestamp ages out - or the egress IP changes, routine
+behind a VPN - DDoS-Guard stops recognising the caller and re-arms the challenge on
+every request. Storing an expired cookie and sending it forever has the same effect.
+"""
+
+import time
+
+import pytest
+
+import shelfmark.bypass.internal_bypasser as ib
+
+
+@pytest.fixture(autouse=True)
+def _clean_cookie_store(monkeypatch):
+    monkeypatch.setattr(ib, "_cf_cookies", {})
+    monkeypatch.setattr(ib, "_cf_user_agents", {})
+
+
+class _Cookie:
+    """Stand-in for the CDP cookie objects the bypasser extracts."""
+
+    def __init__(self, name, value="v", expires=None, domain="annas-archive.gl"):
+        self.name = name
+        self.value = value
+        self.expires = expires
+        self.domain = domain
+        self.path = "/"
+        self.secure = True
+
+
+def _store(cookies, url="https://annas-archive.gl/search"):
+    ib._store_extracted_cookies(url=url, cookies=cookies, user_agent="UA/1.0")
+
+
+# --------------------------------------------------------------------------- #
+# Per-check cookies must not be persisted for replay
+# --------------------------------------------------------------------------- #
+def test_per_check_cookies_are_not_stored():
+    """The IP/timestamp trio describes one check and must not outlive it."""
+    _store(
+        [
+            _Cookie("__ddg1_", "clearance"),
+            _Cookie("__ddg2_", "clearance2"),
+            _Cookie("__ddg8_", "opaque"),
+            _Cookie("__ddg9_", "203.0.113.7"),
+            _Cookie("__ddg10_", "1786826304"),
+            _Cookie("ddg_last_challenge", "1786826304"),
+        ]
+    )
+
+    stored = ib.get_cf_cookies_for_domain("annas-archive.gl")
+
+    assert set(stored) == {"__ddg1_", "__ddg2_"}
+    for ephemeral in ("__ddg8_", "__ddg9_", "__ddg10_", "ddg_last_challenge"):
+        assert ephemeral not in stored
+
+
+def test_clearance_cookies_survive():
+    _store([_Cookie("__ddg1_", "a"), _Cookie("__ddg2_", "b"), _Cookie("__ddgid_", "c")])
+
+    stored = ib.get_cf_cookies_for_domain("annas-archive.gl")
+
+    assert stored == {"__ddg1_": "a", "__ddg2_": "b", "__ddgid_": "c"}
+
+
+def test_cloudflare_cookies_are_unaffected():
+    _store([_Cookie("cf_clearance", "token"), _Cookie("__cf_bm", "bm")])
+
+    stored = ib.get_cf_cookies_for_domain("annas-archive.gl")
+
+    assert stored == {"cf_clearance": "token", "__cf_bm": "bm"}
+
+
+def test_per_check_cookies_are_excluded_even_for_full_session_domains(monkeypatch):
+    """extract_all exists for Z-Library sessions; it must not resurrect the trio."""
+    monkeypatch.setattr(ib, "_get_full_cookie_domains", lambda: {"annas-archive.gl"})
+    _store([_Cookie("sessionid", "s"), _Cookie("__ddg9_", "203.0.113.7")])
+
+    stored = ib.get_cf_cookies_for_domain("annas-archive.gl")
+
+    assert "sessionid" in stored
+    assert "__ddg9_" not in stored
+
+
+# --------------------------------------------------------------------------- #
+# Expiry must be honoured for every cookie, not only cf_clearance
+# --------------------------------------------------------------------------- #
+def test_expired_ddg_cookies_are_dropped():
+    """The old code only expiry-checked cf_clearance, so DDoS-Guard domains - which
+    have none - replayed dead cookies forever."""
+    past = int(time.time()) - 60
+    _store([_Cookie("__ddg1_", "live"), _Cookie("__ddgmark_", "dead", expires=past)])
+
+    stored = ib.get_cf_cookies_for_domain("annas-archive.gl")
+
+    assert stored == {"__ddg1_": "live"}
+
+
+def test_all_cookies_expired_returns_empty_so_caller_re_solves():
+    past = int(time.time()) - 60
+    _store([_Cookie("__ddg1_", "dead", expires=past)])
+
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") == {}
+    assert ib.has_valid_cf_cookies("annas-archive.gl") is False
+
+
+def test_unexpired_cookies_are_kept():
+    future = int(time.time()) + 3600
+    _store([_Cookie("__ddg1_", "live", expires=future)])
+
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") == {"__ddg1_": "live"}
+
+
+def test_session_cookies_never_expire():
+    """expires<=0 means a session cookie, not an already-expired one."""
+    _store([_Cookie("__ddg5_", "s", expires=0), _Cookie("__ddg1_", "a", expires=None)])
+
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") == {"__ddg5_": "s", "__ddg1_": "a"}
+
+
+def test_expired_cf_clearance_still_drops_the_whole_domain():
+    """Pre-existing Cloudflare behaviour must not regress."""
+    past = int(time.time()) - 60
+    _store([_Cookie("cf_clearance", "dead", expires=past), _Cookie("__cf_bm", "bm")])
+
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") == {}
+
+
+def test_expired_cookies_are_pruned_from_the_store():
+    """A dropped cookie must not linger and be re-evaluated on every request."""
+    past = int(time.time()) - 60
+    _store([_Cookie("__ddg1_", "live"), _Cookie("__ddgmark_", "dead", expires=past)])
+
+    ib.get_cf_cookies_for_domain("annas-archive.gl")
+
+    assert set(ib._cf_cookies["annas-archive.gl"]) == {"__ddg1_"}
+
+
+def test_solve_that_yields_only_per_check_cookies_stores_nothing():
+    """No clearance means no reuse - the caller must go back to the bypasser rather
+    than believe it holds a valid session."""
+    _store([_Cookie("__ddg9_", "203.0.113.7"), _Cookie("__ddg10_", "1786826304")])
+
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") == {}
+
+
+# --------------------------------------------------------------------------- #
+# Rejected cookies are discarded, never retried forever
+# --------------------------------------------------------------------------- #
+class _Resp:
+    def __init__(self, status_code, text="page"):
+        self.status_code = status_code
+        self.text = text
+
+
+def _seed(monkeypatch):
+    _store([_Cookie("__ddg1_", "clearance"), _Cookie("__ddg2_", "c2")])
+    monkeypatch.setattr(ib, "get_proxies", lambda _url: None)
+    monkeypatch.setattr(ib, "get_ssl_verify", lambda _url: True)
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl")
+
+
+def test_rejected_cached_cookies_are_discarded(monkeypatch):
+    """A 403 while presenting cookies proves they are dead - keep them and every
+    later request re-presents a known-rejected cookie."""
+    _seed(monkeypatch)
+    monkeypatch.setattr(ib.requests, "get", lambda *a, **k: _Resp(403))
+
+    assert (
+        ib._try_with_cached_cookies("https://annas-archive.gl/search", "annas-archive.gl") is None
+    )
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") == {}
+
+
+def test_redirect_loop_on_cached_cookies_discards_them(monkeypatch):
+    """DDoS-Guard answers dead clearance with an endless ?check=1 bounce, which
+    surfaces as an exception rather than a status code."""
+    _seed(monkeypatch)
+
+    def boom(*_a, **_k):
+        raise ib.requests.exceptions.TooManyRedirects("Exceeded 30 redirects")
+
+    monkeypatch.setattr(ib.requests, "get", boom)
+
+    assert (
+        ib._try_with_cached_cookies("https://annas-archive.gl/search", "annas-archive.gl") is None
+    )
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") == {}
+
+
+def test_working_cookies_are_kept(monkeypatch):
+    _seed(monkeypatch)
+    monkeypatch.setattr(ib.requests, "get", lambda *a, **k: _Resp(200, "the page"))
+
+    result = ib._try_with_cached_cookies("https://annas-archive.gl/search", "annas-archive.gl")
+
+    assert result == "the page"
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") != {}
+
+
+def test_failure_only_clears_the_failing_host(monkeypatch):
+    """clear_cf_cookies('') means every host - a blank hostname must not wipe
+    clearance for sites that are working fine."""
+    _seed(monkeypatch)
+    _store([_Cookie("__ddg1_", "other")], url="https://other-site.test/x")
+    monkeypatch.setattr(ib.requests, "get", lambda *a, **k: _Resp(403))
+
+    ib._try_with_cached_cookies("https://annas-archive.gl/search", "annas-archive.gl")
+
+    assert ib.get_cf_cookies_for_domain("annas-archive.gl") == {}
+    assert ib.get_cf_cookies_for_domain("other-site.test") == {"__ddg1_": "other"}
@@ -101,3 +101,36 @@ def test_get_bypassed_page_retries_and_rotates_selector_between_attempts(monkeyp
    ]
    assert selector.rotate_calls == 1
    assert sleeps == [1.0]
+
+
+def _stub_ext_bypasser_timeout(monkeypatch, external_bypasser, value: int) -> None:
+    """Override only EXT_BYPASSER_TIMEOUT on the shared config singleton."""
+    real_get = external_bypasser.config.get
+    monkeypatch.setattr(
+        external_bypasser.config,
+        "get",
+        lambda key, default="": value if key == "EXT_BYPASSER_TIMEOUT" else real_get(key, default),
+    )
+
+
+def test_max_duration_seconds_covers_every_attempt_and_backoff(monkeypatch):
+    """The declared budget must not undercut what get_bypassed_page() can actually take."""
+    import shelfmark.bypass.external_bypasser as external_bypasser
+
+    _stub_ext_bypasser_timeout(monkeypatch, external_bypasser, 60000)
+
+    budget = external_bypasser.max_duration_seconds()
+
+    # 5 attempts at min(60 + 15, 120) = 75s, plus the 1+2+4+8 backoff and its jitter.
+    assert budget == 5 * 75.0 + (1 + 1) + (2 + 1) + (4 + 1) + (8 + 1)
+
+
+def test_max_duration_seconds_respects_the_read_timeout_ceiling(monkeypatch):
+    import shelfmark.bypass.external_bypasser as external_bypasser
+
+    _stub_ext_bypasser_timeout(monkeypatch, external_bypasser, 300000)
+
+    budget = external_bypasser.max_duration_seconds()
+
+    # 300s + 15s buffer is clamped to MAX_READ_TIMEOUT, not used raw.
+    assert budget == 5 * external_bypasser.MAX_READ_TIMEOUT + 19.0
@@ -1,4 +1,5 @@
 import asyncio
+import threading

 import pytest

@@ -430,3 +431,54 @@ def test_get_bypassed_page_retries_next_mirror_after_runtime_error(monkeypatch):
        "https://mirror-one.example/book",
        "https://mirror-two.example/book",
    ]
+
+
+def test_max_duration_seconds_allows_for_a_mirror_rotation_retry():
+    """get_bypassed_page() may call get() twice, so the budget must cover both."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    assert internal_bypasser.max_duration_seconds() == (
+        2 * internal_bypasser._BYPASS_SUBPROCESS_TIMEOUT_SECONDS
+    )
+
+
+def test_cdp_worker_run_times_out_and_cancels_the_orphaned_coroutine(monkeypatch):
+    """A wedged in-process bypass must not block forever holding LOCKED.
+
+    Regression guard: _CDP_WORKER.run() used to wait with timeout=None, so one hung CDP
+    session blocked every subsequent bypass in the process indefinitely.
+    """
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    started = threading.Event()
+
+    async def _never_finish():
+        started.set()
+        await asyncio.Event().wait()
+
+    coro = _never_finish()
+    with pytest.raises(TimeoutError):
+        internal_bypasser._CDP_WORKER.run(coro, timeout=0.05)
+
+    assert started.is_set(), "coroutine should have been scheduled before timing out"
+
+
+def test_run_bypass_in_current_process_bounds_its_wait(monkeypatch):
+    """The in-process path passes a deadline rather than waiting forever."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    observed: dict[str, float | None] = {}
+
+    class _FakeWorker:
+        def run(self, coro, timeout=None):
+            observed["timeout"] = timeout
+            coro.close()
+            return "html"
+
+    monkeypatch.setattr(internal_bypasser, "_CDP_WORKER", _FakeWorker())
+    monkeypatch.delenv("SHELFMARK_INTERNAL_BYPASSER_CHILD", raising=False)
+
+    result = internal_bypasser._run_bypass_in_current_process("https://example.com", 1)
+
+    assert result == "html"
+    assert observed["timeout"] == internal_bypasser._IN_PROCESS_BYPASS_TIMEOUT_SECONDS
@@ -0,0 +1,91 @@
+"""Tests for widening the audiobook format list on existing installs.
+
+`initialize_default_configs()` only writes field defaults when a tab has no config file
+yet, so widening the default alone would have reached fresh installs only - exactly not
+the installs already carrying the narrow m4b/mp3 list that loses FLAC/OPUS releases.
+"""
+
+import logging
+
+import pytest
+
+from shelfmark.config.migrations import migrate_audiobook_formats
+from shelfmark.core.utils import ARCHIVE_FORMATS, AUDIOBOOK_FORMATS
+
+WIDENED = [*AUDIOBOOK_FORMATS, *ARCHIVE_FORMATS]
+
+
+@pytest.fixture
+def migrate():
+    """Run the migration over an in-memory config, returning the resulting config."""
+
+    def run(config: dict | None) -> dict:
+        stored = {} if config is None else dict(config)
+        saved: dict = {}
+
+        def save(values: dict) -> None:
+            saved.update(values)
+            stored.update(values)
+
+        migrate_audiobook_formats(
+            load_general_config=lambda: stored,
+            save_general_config=save,
+            widened_formats=WIDENED,
+            logger=logging.getLogger("test"),
+        )
+        return stored
+
+    return run
+
+
+def test_legacy_default_is_widened(migrate):
+    result = migrate({"SUPPORTED_AUDIOBOOK_FORMATS": ["m4b", "mp3"]})
+
+    assert result["SUPPORTED_AUDIOBOOK_FORMATS"] == WIDENED
+
+
+def test_legacy_default_is_widened_regardless_of_order_or_case(migrate):
+    result = migrate({"SUPPORTED_AUDIOBOOK_FORMATS": ["MP3", " m4b "]})
+
+    assert result["SUPPORTED_AUDIOBOOK_FORMATS"] == WIDENED
+
+
+def test_other_settings_are_preserved(migrate):
+    result = migrate({"SUPPORTED_AUDIOBOOK_FORMATS": ["m4b", "mp3"], "SUPPORTED_FORMATS": ["epub"]})
+
+    assert result["SUPPORTED_FORMATS"] == ["epub"]
+
+
+@pytest.mark.parametrize(
+    "customized",
+    [
+        ["m4b"],  # deliberately narrowed - re-enabling formats would override the choice
+        ["mp3", "flac"],
+        ["m4b", "mp3", "zip"],
+        [],
+    ],
+)
+def test_customized_lists_are_left_alone(migrate, customized):
+    result = migrate({"SUPPORTED_AUDIOBOOK_FORMATS": customized})
+
+    assert result["SUPPORTED_AUDIOBOOK_FORMATS"] == customized
+
+
+def test_absent_key_is_left_alone(migrate):
+    """Nothing persisted means the field default already applies - don't write one."""
+    result = migrate({"SUPPORTED_FORMATS": ["epub"]})
+
+    assert "SUPPORTED_AUDIOBOOK_FORMATS" not in result
+
+
+def test_unexpected_type_is_left_alone(migrate):
+    result = migrate({"SUPPORTED_AUDIOBOOK_FORMATS": "m4b,mp3"})
+
+    assert result["SUPPORTED_AUDIOBOOK_FORMATS"] == "m4b,mp3"
+
+
+def test_migration_is_idempotent(migrate):
+    once = migrate({"SUPPORTED_AUDIOBOOK_FORMATS": ["m4b", "mp3"]})
+    twice = migrate(once)
+
+    assert twice["SUPPORTED_AUDIOBOOK_FORMATS"] == WIDENED
@@ -8,6 +8,7 @@ Run with: uv run pytest tests/config/test_environment.py -v
 """

 import importlib
+import json
 import os
 import tempfile
 from pathlib import Path
@@ -15,6 +16,15 @@ from unittest.mock import patch

 import pytest

+
+def _restore_env(monkeypatch, name: str, value: str | None) -> None:
+    """Restore an env var to its pre-test value."""
+    if value is None:
+        monkeypatch.delenv(name, raising=False)
+    else:
+        monkeypatch.setenv(name, value)
+
+
 # =============================================================================
 # Directory Setup Tests
 # =============================================================================
@@ -436,6 +446,7 @@ class TestDebugConfiguration:
        original_debug = os.environ.get("DEBUG")

        try:
+            monkeypatch.delenv("LOG_LEVEL", raising=False)
            monkeypatch.setenv("DEBUG", "true")
            importlib.reload(env_module)
            assert env_module.DEBUG is True
@@ -452,6 +463,76 @@ class TestDebugConfiguration:
                monkeypatch.setenv("DEBUG", original_debug)
            importlib.reload(env_module)

+    @pytest.mark.parametrize(
+        ("raw", "expected"),
+        [
+            ("error", "ERROR"),
+            ("ERROR", "ERROR"),
+            ("  Warning  ", "WARNING"),
+            ("warn", "WARNING"),
+            ("critical", "CRITICAL"),
+            ("nonsense", "INFO"),
+            ("", "INFO"),
+            (None, "INFO"),
+        ],
+    )
+    def test_normalize_log_level(self, raw, expected):
+        """Log level names are case-insensitive and fall back to INFO."""
+        from shelfmark.config.env import normalize_log_level
+
+        assert normalize_log_level(raw) == expected
+
+    def test_log_level_from_env_var(self, monkeypatch):
+        """LOG_LEVEL env var should set the app log level when DEBUG is off."""
+        import shelfmark.config.env as env_module
+
+        original_debug = os.environ.get("DEBUG")
+        original_level = os.environ.get("LOG_LEVEL")
+
+        try:
+            monkeypatch.setenv("DEBUG", "false")
+            monkeypatch.setenv("LOG_LEVEL", "error")
+            importlib.reload(env_module)
+            assert env_module.LOG_LEVEL == "ERROR"
+
+            # DEBUG wins over LOG_LEVEL, matching entrypoint.sh.
+            monkeypatch.setenv("DEBUG", "true")
+            importlib.reload(env_module)
+            assert env_module.LOG_LEVEL == "DEBUG"
+        finally:
+            _restore_env(monkeypatch, "DEBUG", original_debug)
+            _restore_env(monkeypatch, "LOG_LEVEL", original_level)
+            importlib.reload(env_module)
+
+    def test_log_level_from_config_file(self, monkeypatch, tmp_path):
+        """LOG_LEVEL should fall back to the advanced settings file."""
+        import shelfmark.config.env as env_module
+
+        original_debug = os.environ.get("DEBUG")
+        original_level = os.environ.get("LOG_LEVEL")
+        original_config_dir = os.environ.get("CONFIG_DIR")
+
+        advanced = tmp_path / "plugins" / "advanced.json"
+        advanced.parent.mkdir(parents=True)
+        advanced.write_text(json.dumps({"LOG_LEVEL": "WARNING"}))
+
+        try:
+            monkeypatch.setenv("DEBUG", "false")
+            monkeypatch.delenv("LOG_LEVEL", raising=False)
+            monkeypatch.setenv("CONFIG_DIR", str(tmp_path))
+            importlib.reload(env_module)
+            assert env_module.LOG_LEVEL == "WARNING"
+
+            # Env var takes precedence over the stored setting.
+            monkeypatch.setenv("LOG_LEVEL", "critical")
+            importlib.reload(env_module)
+            assert env_module.LOG_LEVEL == "CRITICAL"
+        finally:
+            _restore_env(monkeypatch, "DEBUG", original_debug)
+            _restore_env(monkeypatch, "LOG_LEVEL", original_level)
+            _restore_env(monkeypatch, "CONFIG_DIR", original_config_dir)
+            importlib.reload(env_module)
+

 # =============================================================================
 # Proxy and Network Configuration Tests
@@ -53,7 +53,7 @@ def test_generated_env_docs_include_custom_component_value_fields() -> None:

    assert (
        "| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: "
-        "{Author}, {Title}, {Year}, {User}, {OriginalName} "
+        "{Author}, {Title}, {Year}, {Language}, {User}, {OriginalName} "
        "(source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, "
        "{PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix:"
    ) in docs
@@ -0,0 +1,82 @@
+"""Tests for the OIDC Test Connection handler."""
+
+from unittest.mock import MagicMock, patch
+
+from shelfmark.config.security_handlers import check_oidc_connection
+
+DISCOVERY_URL = "https://auth.example.com/.well-known/openid-configuration"
+
+DISCOVERY_DOCUMENT = {
+    "issuer": "https://auth.example.com",
+    "authorization_endpoint": "https://auth.example.com/authorize",
+    "token_endpoint": "https://auth.example.com/token",
+    "jwks_uri": "https://auth.example.com/jwks",
+}
+
+
+def _mock_response(payload):
+    response = MagicMock()
+    response.json.return_value = payload
+    response.raise_for_status.return_value = None
+    return response
+
+
+def _run_check(responses):
+    """Run check_oidc_connection with requests.get returning the given responses."""
+    with (
+        patch("requests.get", side_effect=responses) as mock_get,
+        patch("shelfmark.config.security_handlers.get_ssl_verify", return_value=True),
+    ):
+        result = check_oidc_connection(
+            load_security_config=lambda: {"OIDC_DISCOVERY_URL": DISCOVERY_URL},
+            current_values={},
+            logger=MagicMock(),
+        )
+    return result, mock_get
+
+
+class TestCheckOIDCConnection:
+    def test_succeeds_when_discovery_and_jwks_are_valid(self):
+        responses = [
+            _mock_response(DISCOVERY_DOCUMENT),
+            _mock_response({"keys": [{"kty": "RSA", "kid": "abc"}]}),
+        ]
+        result, mock_get = _run_check(responses)
+        assert result["success"] is True
+        assert "Connected to" in result["message"]
+        jwks_call = mock_get.call_args_list[1]
+        assert jwks_call.args[0] == DISCOVERY_DOCUMENT["jwks_uri"]
+
+    def test_fails_with_signing_key_guidance_when_jwks_is_empty(self):
+        responses = [
+            _mock_response(DISCOVERY_DOCUMENT),
+            _mock_response({}),
+        ]
+        result, _ = _run_check(responses)
+        assert result["success"] is False
+        assert "no token signing keys" in result["message"]
+        assert "Signing Key" in result["message"]
+
+    def test_fails_with_signing_key_guidance_when_jwks_keys_list_is_empty(self):
+        responses = [
+            _mock_response(DISCOVERY_DOCUMENT),
+            _mock_response({"keys": []}),
+        ]
+        result, _ = _run_check(responses)
+        assert result["success"] is False
+        assert "no token signing keys" in result["message"]
+
+    def test_fails_when_discovery_document_missing_jwks_uri(self):
+        document = {k: v for k, v in DISCOVERY_DOCUMENT.items() if k != "jwks_uri"}
+        responses = [_mock_response(document)]
+        result, _ = _run_check(responses)
+        assert result["success"] is False
+        assert "jwks_uri" in result["message"]
+
+    def test_fails_when_jwks_request_errors(self):
+        jwks_response = MagicMock()
+        jwks_response.raise_for_status.side_effect = RuntimeError("boom")
+        responses = [_mock_response(DISCOVERY_DOCUMENT), jwks_response]
+        result, _ = _run_check(responses)
+        assert result["success"] is False
+        assert "Connection failed" in result["message"]
@@ -1,9 +1,20 @@
 from __future__ import annotations

+import os
+import shutil
+import signal
+import socket
+import subprocess
+from contextlib import suppress
 from pathlib import Path

+import pytest
+
 TOR_SCRIPT_PATH = Path(__file__).resolve().parents[2] / "tor.sh"

+IPTABLES_BLOCK_START = 'echo "[*] Setting up iptables rules..."'
+IPTABLES_BLOCK_END = 'echo "[✓] Transparent Tor routing enabled."'
+

 def _generated_tor_healthcheck_script() -> str:
    script = TOR_SCRIPT_PATH.read_text()
@@ -14,17 +25,208 @@ def _generated_tor_healthcheck_script() -> str:


 def _tor_script_rule_lines() -> list[str]:
-    return [
-        line.strip()
-        for line in TOR_SCRIPT_PATH.read_text().splitlines()
-        if line.strip().startswith("iptables ")
-    ]
+    """Return the iptables invocations in tor.sh, in file order.
+
+    Rules that are applied on a best-effort basis are written as
+    ``if iptables ...; then``, so the shell wrapper is stripped to keep the
+    ordering assertions below comparing rules rather than syntax.
+    """
+    lines = []
+    for raw_line in TOR_SCRIPT_PATH.read_text().splitlines():
+        line = raw_line.strip().removeprefix("if ")
+        if line.startswith("iptables "):
+            lines.append(line)
+    return lines


 def _line_index(lines: list[str], needle: str) -> int:
    return next(index for index, line in enumerate(lines) if needle in line)


+def _tor_iptables_block() -> str:
+    """Extract the firewall setup section of tor.sh so it can be executed."""
+    script = TOR_SCRIPT_PATH.read_text()
+    start = script.index(IPTABLES_BLOCK_START)
+    end = script.index(IPTABLES_BLOCK_END)
+    return script[start:end]
+
+
+# Verbatim stderr of an iptables build whose kernel lacks the xt_owner module,
+# as reported from Synology DSM in issue #1150.
+MISSING_XT_OWNER_STDERR = (
+    "Warning: Extension owner revision 0 not supported, missing kernel module?\n"
+    "iptables: No chain/target/match by that name.\n"
+)
+
+IPTABLES_STUB = f"""#!/bin/bash
+if [ "$FAKE_OWNER_MATCH_SUPPORTED" != "1" ]; then
+    case "$*" in
+        *--uid-owner*)
+            printf '%s' {MISSING_XT_OWNER_STDERR!r} >&2
+            exit 1
+            ;;
+    esac
+fi
+echo "$*" >> "$FAKE_IPTABLES_LOG"
+exit 0
+"""
+
+# tor.sh resolves the Tor uid with `id -u debian-tor`; that account only exists
+# inside the image, so stub it out with the uid the Debian tor package uses.
+ID_STUB = """#!/bin/bash
+echo 107
+"""
+
+
+def _run_tor_iptables_block(tmp_path: Path, *, owner_match_supported: bool):
+    """Run tor.sh's firewall block against a fake iptables.
+
+    Returns the completed process plus the rules the fake iptables accepted.
+    """
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    for name, source in (("iptables", IPTABLES_STUB), ("id", ID_STUB)):
+        stub = bin_dir / name
+        stub.write_text(source)
+        stub.chmod(0o755)
+
+    applied_rules_log = tmp_path / "applied-rules.log"
+    # tor.sh runs under `set -e`, which is what turns a rejected rule into a
+    # container restart loop, so reproduce that here.
+    result = subprocess.run(
+        ["bash", "-c", "set -e\n" + _tor_iptables_block()],
+        capture_output=True,
+        text=True,
+        env={
+            "PATH": f"{bin_dir}:/usr/bin:/bin",
+            "FAKE_IPTABLES_LOG": str(applied_rules_log),
+            "FAKE_OWNER_MATCH_SUPPORTED": "1" if owner_match_supported else "0",
+        },
+    )
+    applied_rules = applied_rules_log.read_text().splitlines() if applied_rules_log.exists() else []
+    return result, applied_rules
+
+
+requires_bash = pytest.mark.skipif(
+    shutil.which("bash") is None, reason="bash is required to execute tor.sh"
+)
+
+# The watchdog shells out to `timeout`, which is not present on stock macOS.
+requires_timeout = pytest.mark.skipif(
+    shutil.which("timeout") is None, reason="coreutils timeout is required"
+)
+
+SUPERVISORCTL_STUB = """#!/bin/bash
+# Emulates `supervisorctl status tor`. Normally reports FAKE_TOR_STATE, but when
+# FAKE_TOR_FAIL_FIRST is set the first call reports a transient failure so the
+# watchdog's retry behaviour can be exercised.
+if [ -n "$FAKE_TOR_FAIL_FIRST" ] && [ ! -f "$FAKE_TOR_CALL_MARKER" ]; then
+    touch "$FAKE_TOR_CALL_MARKER"
+    echo "tor    FATAL     Exited too quickly"
+    exit 3
+fi
+echo "tor    $FAKE_TOR_STATE   pid 42, uptime 0:01:00"
+"""
+
+
+def _watchdog_path_env(bin_dir: Path) -> str:
+    """PATH exposing the stubs plus the real bash/timeout the watchdog calls."""
+    parts = [str(bin_dir)]
+    for tool in ("bash", "timeout"):
+        resolved = shutil.which(tool)
+        if resolved:
+            parts.append(str(Path(resolved).parent))
+    parts += ["/usr/bin", "/bin"]
+    return ":".join(parts)
+
+
+def _run_tor_watchdog(
+    tmp_path: Path,
+    *,
+    tor_state: str = "RUNNING",
+    bootstrapped: bool = True,
+    trans_port_open: bool = True,
+    fail_first: bool = False,
+    run_for: float = 2.0,
+):
+    """Run tor.sh's watchdog against a fake Tor and see if it resets the container.
+
+    Returns ``(reset_signal, stdout)`` where ``reset_signal`` is the signal the
+    stand-in for PID 1 received, or ``None`` if it was left alone.
+    """
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    supervisorctl = bin_dir / "supervisorctl"
+    supervisorctl.write_text(SUPERVISORCTL_STUB)
+    supervisorctl.chmod(0o755)
+
+    notices_log = tmp_path / "notices.log"
+    notices_log.write_text(
+        "Bootstrapped 100%: Done\n" if bootstrapped else "Bootstrapped 45%: Loading\n"
+    )
+
+    script = tmp_path / "tor_healthcheck.sh"
+    script.write_text(_generated_tor_healthcheck_script())
+    script.chmod(0o755)
+
+    listener = socket.socket()
+    listener.bind(("127.0.0.1", 0))
+    trans_port = listener.getsockname()[1]
+    if trans_port_open:
+        listener.listen(5)
+    else:
+        # Closing it leaves a port nothing is listening on, which is what a dead
+        # or wedged Tor looks like from the outside.
+        listener.close()
+
+    # Stands in for PID 1: the watchdog signals it instead of dumb-init.
+    container_process = subprocess.Popen(
+        ["sleep", "120"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+    )
+
+    env = {
+        "PATH": _watchdog_path_env(bin_dir),
+        "TOR_CHECK_INTERVAL": "0.2",
+        "TOR_NOTICES_LOG": str(notices_log),
+        "TOR_TRANS_PORT": str(trans_port),
+        "TOR_CONTAINER_PID": str(container_process.pid),
+        "FAKE_TOR_STATE": tor_state,
+        "FAKE_TOR_CALL_MARKER": str(tmp_path / "supervisorctl.called"),
+    }
+    if fail_first:
+        env["FAKE_TOR_FAIL_FIRST"] = "1"
+
+    watchdog = subprocess.Popen(
+        ["bash", str(script)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        env=env,
+        start_new_session=True,
+    )
+    try:
+        try:
+            container_process.wait(timeout=run_for)
+        except subprocess.TimeoutExpired:
+            pass
+        reset_signal = (
+            -container_process.returncode if container_process.poll() is not None else None
+        )
+    finally:
+        # Only the watchdog gets its own session; signalling the group is how we
+        # reap the `sleep` and `timeout` children it spawns.
+        with suppress(ProcessLookupError, PermissionError):
+            os.killpg(os.getpgid(watchdog.pid), signal.SIGKILL)
+        with suppress(ProcessLookupError):
+            container_process.kill()
+        with suppress(OSError):
+            listener.close()
+        container_process.wait()
+        stdout = watchdog.communicate()[0] or ""
+
+    return reset_signal, stdout
+
+
 def test_tor_nat_rules_bypass_private_networks_before_tcp_redirect():
    lines = _tor_script_rule_lines()
    tcp_redirect_index = _line_index(lines, "--syn -j REDIRECT --to-ports 9040")
@@ -63,3 +265,119 @@ def test_tor_healthcheck_uses_local_tor_state_without_clear_net_probe():
    assert "curl " not in healthcheck_script
    assert "supervisorctl status tor" in healthcheck_script
    assert "Bootstrapped 100%" in healthcheck_script
+
+
+@requires_bash
+def test_tor_iptables_setup_survives_kernel_without_owner_match(tmp_path):
+    """Regression test for issue #1150.
+
+    Synology (and other NAS/embedded) kernels ship without xt_owner. The owner
+    exemption is a best-effort optimisation, so a kernel that rejects it must
+    not abort tor.sh and put the container into a restart loop.
+    """
+    result, _ = _run_tor_iptables_block(tmp_path, owner_match_supported=False)
+
+    assert result.returncode == 0, (
+        "tor.sh aborted on a kernel without xt_owner:\n"
+        f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"
+    )
+
+
+@requires_bash
+def test_tor_routing_still_applied_when_owner_match_unsupported(tmp_path):
+    """Degrading past the owner rule must not skip the rules that torify traffic."""
+    _, applied_rules = _run_tor_iptables_block(tmp_path, owner_match_supported=False)
+
+    assert any("--syn -j REDIRECT --to-ports 9040" in rule for rule in applied_rules)
+    for cidr in ("127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"):
+        assert any(f"-d {cidr} -j RETURN" in rule for rule in applied_rules)
+    for protocol in ("udp", "tcp"):
+        assert any(f"-p {protocol} --dport 53" in rule for rule in applied_rules)
+
+
+@requires_bash
+def test_tor_warns_when_owner_match_unsupported(tmp_path):
+    """The degraded path has to be visible in the logs, not silent."""
+    result, _ = _run_tor_iptables_block(tmp_path, owner_match_supported=False)
+
+    assert "owner" in result.stdout.lower()
+    assert "[!]" in result.stdout
+
+
+@requires_bash
+def test_tor_exempts_own_traffic_when_owner_match_supported(tmp_path):
+    """On a normal kernel the exemption must still be installed."""
+    result, applied_rules = _run_tor_iptables_block(tmp_path, owner_match_supported=True)
+
+    assert result.returncode == 0, result.stderr
+    owner_rules = [rule for rule in applied_rules if "--uid-owner" in rule]
+    assert len(owner_rules) == 1
+    assert "-j RETURN" in owner_rules[0]
+
+    owner_index = applied_rules.index(owner_rules[0])
+    redirect_index = next(
+        index for index, rule in enumerate(applied_rules) if "--syn -j REDIRECT" in rule
+    )
+    assert owner_index < redirect_index
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_resets_container_when_tor_dies(tmp_path):
+    """A Tor that is no longer running must take the container down with it."""
+    reset_signal, stdout = _run_tor_watchdog(tmp_path, tor_state="STOPPED")
+
+    assert reset_signal == signal.SIGTERM, f"container was not reset:\n{stdout}"
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_resets_container_when_tor_stops_accepting_connections(tmp_path):
+    """Tor can be 'running' yet unusable; the container must still be reset."""
+    reset_signal, stdout = _run_tor_watchdog(tmp_path, tor_state="RUNNING", trans_port_open=False)
+
+    assert reset_signal == signal.SIGTERM, f"container was not reset:\n{stdout}"
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_leaves_healthy_tor_alone(tmp_path):
+    """A healthy Tor must never be reset, no matter how many cycles run."""
+    reset_signal, stdout = _run_tor_watchdog(tmp_path)
+
+    assert reset_signal is None, f"healthy Tor was reset:\n{stdout}"
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_retries_once_before_resetting(tmp_path):
+    """A single transient failure is retried, not escalated to a reset."""
+    reset_signal, stdout = _run_tor_watchdog(tmp_path, fail_first=True)
+
+    assert reset_signal is None, f"transient failure caused a reset:\n{stdout}"
+    assert "Healthcheck failed (1/2)" in stdout
+    assert "Tor recovered." in stdout
+
+
+@requires_bash
+@requires_timeout
+def test_tor_watchdog_waits_for_first_bootstrap_before_policing(tmp_path):
+    """A slow first bootstrap must not be mistaken for a failure.
+
+    Otherwise every user on a slow link would be reset into a restart loop
+    before Tor ever had a chance to come up.
+    """
+    reset_signal, stdout = _run_tor_watchdog(
+        tmp_path, tor_state="STOPPED", bootstrapped=False, trans_port_open=False
+    )
+
+    assert reset_signal is None, f"reset during initial bootstrap:\n{stdout}"
+    assert "Waiting for initial Tor bootstrap" in stdout
+
+
+def test_tor_watchdog_escalates_to_container_reset_not_in_place_restart():
+    """The watchdog must signal PID 1 rather than bounce Tor under supervisor."""
+    healthcheck_script = _generated_tor_healthcheck_script()
+
+    assert "kill -TERM" in healthcheck_script
+    assert "supervisorctl restart" not in healthcheck_script
@@ -29,6 +29,16 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 import pytest


+@pytest.fixture(autouse=True)
+def _clear_torrent_fetch_cache():
+    """Keep the shared torrent fetch cache from leaking between tests."""
+    from shelfmark.download.clients.torrent_utils import clear_torrent_fetch_cache
+
+    clear_torrent_fetch_cache()
+    yield
+    clear_torrent_fetch_cache()
+
+
@pytest.fixture
 def sample_prowlarr_result():
    """Sample Prowlarr API search result."""
@@ -0,0 +1,280 @@
+{
+  "_comment": "Frozen snapshot of the per-source language handling as it was before consolidation into shelfmark.core.languages. prowlarr_three_letter and audiobookbay_names were explicit maps; direct_download_derived is what its loader built from the data file, including the underscore spelling of a hyphenated code. Every alias here must still resolve to the same code. The one deliberate change: Traditional Chinese was canonically 'zh‑Hant' with a U+2011 non-breaking hyphen and is now the ASCII 'zh-Hant', so expectations for it name the new code while the old spelling remains a resolvable alias.",
+  "audiobookbay_names": {
+    "afrikaans": "af",
+    "arabic": "ar",
+    "bangla": "bn",
+    "bengali": "bn",
+    "bosnian": "bs",
+    "bulgarian": "bg",
+    "burmese": "my",
+    "catalan": "ca",
+    "chinese": "zh",
+    "croatian": "hr",
+    "czech": "cs",
+    "danish": "da",
+    "dutch": "nl",
+    "english": "en",
+    "estonian": "et",
+    "farsi": "fa",
+    "filipino": "fil",
+    "finnish": "fi",
+    "french": "fr",
+    "german": "de",
+    "greek": "el",
+    "gujarati": "gu",
+    "hebrew": "he",
+    "hindi": "hi",
+    "hungarian": "hu",
+    "icelandic": "is",
+    "indonesian": "id",
+    "irish": "ga",
+    "italian": "it",
+    "japanese": "ja",
+    "javanese": "jv",
+    "kannada": "kn",
+    "korean": "ko",
+    "latin": "la",
+    "latvian": "lv",
+    "lithuanian": "lt",
+    "malay": "ms",
+    "malayalam": "ml",
+    "manx": "gv",
+    "marathi": "mr",
+    "norwegian": "no",
+    "persian": "fa",
+    "polish": "pl",
+    "portuguese": "pt",
+    "punjabi": "pa",
+    "romanian": "ro",
+    "russian": "ru",
+    "sanskrit": "sa",
+    "scottish gaelic": "gd",
+    "serbian": "sr",
+    "slovenian": "sl",
+    "spanish": "es",
+    "swedish": "sv",
+    "tagalog": "fil",
+    "tamil": "ta",
+    "telugu": "te",
+    "thai": "th",
+    "turkish": "tr",
+    "ukrainian": "uk",
+    "urdu": "ur",
+    "vietnamese": "vi"
+  },
+  "direct_download_derived": {
+    "af": "af",
+    "afrikaans": "af",
+    "albanian": "sq",
+    "ar": "ar",
+    "arabic": "ar",
+    "armenian": "hy",
+    "az": "az",
+    "azerbaijani": "az",
+    "ba": "ba",
+    "bangla": "bn",
+    "bashkir": "ba",
+    "be": "be",
+    "belarusian": "be",
+    "bg": "bg",
+    "bn": "bn",
+    "bo": "bo",
+    "bulgarian": "bg",
+    "ca": "ca",
+    "catalan": "ca",
+    "chinese": "zh",
+    "croatian": "hr",
+    "cs": "cs",
+    "czech": "cs",
+    "da": "da",
+    "danish": "da",
+    "de": "de",
+    "dutch": "nl",
+    "el": "el",
+    "en": "en",
+    "english": "en",
+    "eo": "eo",
+    "es": "es",
+    "esperanto": "eo",
+    "fa": "fa",
+    "fi": "fi",
+    "fil": "fil",
+    "filipino": "fil",
+    "finnish": "fi",
+    "fr": "fr",
+    "french": "fr",
+    "ga": "ga",
+    "galician": "gl",
+    "georgian": "ka",
+    "german": "de",
+    "gl": "gl",
+    "greek": "el",
+    "gu": "gu",
+    "gujarati": "gu",
+    "he": "he",
+    "hebrew": "he",
+    "hi": "hi",
+    "hindi": "hi",
+    "hr": "hr",
+    "hu": "hu",
+    "hungarian": "hu",
+    "hy": "hy",
+    "id": "id",
+    "indonesian": "id",
+    "irish": "ga",
+    "it": "it",
+    "italian": "it",
+    "ja": "ja",
+    "japanese": "ja",
+    "javanese": "jv",
+    "jv": "jv",
+    "ka": "ka",
+    "kannada": "kn",
+    "kazakh": "kk",
+    "kinyarwanda": "rw",
+    "kk": "kk",
+    "kn": "kn",
+    "ko": "ko",
+    "korean": "ko",
+    "ky": "ky",
+    "kyrgyz": "ky",
+    "la": "la",
+    "latin": "la",
+    "latvian": "lv",
+    "lithuanian": "lt",
+    "lt": "lt",
+    "lv": "lv",
+    "malay": "ms",
+    "malayalam": "ml",
+    "marathi": "mr",
+    "ml": "ml",
+    "mn": "mn",
+    "mongolian": "mn",
+    "mr": "mr",
+    "ms": "ms",
+    "nl": "nl",
+    "no": "no",
+    "norwegian": "no",
+    "pa": "pa",
+    "persian": "fa",
+    "pl": "pl",
+    "polish": "pl",
+    "portuguese": "pt",
+    "pt": "pt",
+    "punjabi": "pa",
+    "qu": "qu",
+    "quechua": "qu",
+    "ro": "ro",
+    "romanian": "ro",
+    "ru": "ru",
+    "russian": "ru",
+    "rw": "rw",
+    "serbian": "sr",
+    "shan": "shn",
+    "shn": "shn",
+    "sk": "sk",
+    "sl": "sl",
+    "slovak": "sk",
+    "slovenian": "sl",
+    "spanish": "es",
+    "sq": "sq",
+    "sr": "sr",
+    "sv": "sv",
+    "sw": "sw",
+    "swahili": "sw",
+    "swedish": "sv",
+    "ta": "ta",
+    "tamil": "ta",
+    "te": "te",
+    "telugu": "te",
+    "th": "th",
+    "thai": "th",
+    "tibetan": "bo",
+    "tr": "tr",
+    "traditional chinese": "zh-Hant",
+    "turkish": "tr",
+    "ug": "ug",
+    "uk": "uk",
+    "ukrainian": "uk",
+    "ur": "ur",
+    "urdu": "ur",
+    "uyghur": "ug",
+    "vi": "vi",
+    "vietnamese": "vi",
+    "zh": "zh",
+    "zh‑hant": "zh-Hant"
+  },
+  "prowlarr_three_letter": {
+    "afr": "af",
+    "ara": "ar",
+    "ben": "bn",
+    "bos": "bs",
+    "bul": "bg",
+    "bur": "my",
+    "cat": "ca",
+    "ces": "cs",
+    "chi": "zh",
+    "cze": "cs",
+    "dan": "da",
+    "deu": "de",
+    "dut": "nl",
+    "ell": "el",
+    "eng": "en",
+    "est": "et",
+    "fas": "fa",
+    "fin": "fi",
+    "fra": "fr",
+    "fre": "fr",
+    "ger": "de",
+    "gla": "gd",
+    "gle": "ga",
+    "glv": "gv",
+    "gre": "el",
+    "guj": "gu",
+    "heb": "he",
+    "hin": "hi",
+    "hrv": "hr",
+    "hun": "hu",
+    "ice": "is",
+    "ind": "id",
+    "isl": "is",
+    "ita": "it",
+    "jap": "ja",
+    "jav": "jv",
+    "jpn": "ja",
+    "kan": "kn",
+    "kor": "ko",
+    "lat": "la",
+    "lav": "lv",
+    "lit": "lt",
+    "mal": "ml",
+    "mar": "mr",
+    "may": "ms",
+    "msa": "ms",
+    "mya": "my",
+    "nld": "nl",
+    "nor": "no",
+    "pan": "pa",
+    "per": "fa",
+    "pol": "pl",
+    "por": "pt",
+    "rom": "ro",
+    "ron": "ro",
+    "rus": "ru",
+    "san": "sa",
+    "slv": "sl",
+    "spa": "es",
+    "srp": "sr",
+    "swe": "sv",
+    "tam": "ta",
+    "tel": "te",
+    "tgl": "fil",
+    "tha": "th",
+    "tur": "tr",
+    "ukr": "uk",
+    "urd": "ur",
+    "vie": "vi",
+    "zho": "zh"
+  }
+}
@@ -0,0 +1,38 @@
+"""The audiobook format list must stay in agreement across every layer that gates on it.
+
+These lists were maintained by hand in four places and drifted: the settings UI offered
+only m4b/mp3/m4a, so FLAC/OPUS/OGG could never be enabled even though the parsers
+recognized them, the sorter ranked them, and archive extraction knew them. The result was
+a FLAC audiobook that was invisible in search and rejected after download. They now all
+derive from `shelfmark.core.utils.AUDIOBOOK_FORMATS`; this test fails if one drifts again.
+"""
+
+from shelfmark.config.settings import _AUDIOBOOK_FORMAT_OPTIONS
+from shelfmark.core.utils import ARCHIVE_FORMATS, AUDIOBOOK_FORMATS
+from shelfmark.download.archive import ALL_AUDIO_EXTENSIONS
+from shelfmark.release_sources.irc import parser
+from shelfmark.release_sources.prowlarr.source import AUDIOBOOK_FORMATS as PROWLARR_FORMATS
+
+
+def test_archive_extraction_knows_every_audiobook_format():
+    assert ALL_AUDIO_EXTENSIONS == {f".{fmt}" for fmt in AUDIOBOOK_FORMATS}
+
+
+def test_prowlarr_knows_every_audiobook_format():
+    assert PROWLARR_FORMATS == list(AUDIOBOOK_FORMATS)
+
+
+def test_irc_parser_knows_every_audiobook_format():
+    assert set(AUDIOBOOK_FORMATS) <= set(parser.ALL_RECOGNIZED_FORMATS)
+
+
+def test_every_audiobook_format_is_selectable_in_settings():
+    """The settings list is the only one a user's config can be built from."""
+    selectable = {option["value"] for option in _AUDIOBOOK_FORMAT_OPTIONS}
+
+    assert selectable == {*AUDIOBOOK_FORMATS, *ARCHIVE_FORMATS}
+
+
+def test_audiobook_and_ebook_formats_do_not_overlap():
+    """Overlap would make content-type classification by extension ambiguous."""
+    assert not set(AUDIOBOOK_FORMATS) & set(parser.EBOOK_FORMATS)
@@ -28,6 +28,9 @@ _BOOTSTRAP_ENV_ACCESS_ALLOWLIST = {
 }
 _BOOTSTRAP_ENV_ACCESS_KEY_ALLOWLIST = {
    (Path("shelfmark/config/settings.py"), "USING_TOR"),
+    # Loggers are configured while settings_registry itself is still importing,
+    # so the level has to come from the bootstrap env module.
+    (Path("shelfmark/core/logger.py"), "LOG_LEVEL"),
 }
 _RAW_CONFIG_READ_ALLOWLIST = {
    Path("shelfmark/config/notifications_settings.py"),
@@ -205,7 +208,10 @@ class ConfigAccessVisitor(ast.NodeVisitor):
                return
            for alias in node.names:
                imported_name = alias.name
-                if imported_name in self.registered_keys:
+                if (
+                    imported_name in self.registered_keys
+                    and imported_name not in self._bootstrap_env_key_allowlist
+                ):
                    self._record_violation(
                        node,
                        "direct env-module import",
@@ -131,3 +131,46 @@ def test_frontend_dist_resolves_from_repo_root(main_module):

    assert main_module.PROJECT_ROOT == expected_project_root
    assert main_module.FRONTEND_DIST == expected_project_root / "frontend-dist"
+
+
+def test_config_endpoint_serves_languages_without_resolution_aliases(main_module, client):
+    """book_languages is a client contract, not a dump of the language data file.
+
+    data/book-languages.json also carries the aliases used to resolve a source's
+    spelling of a language to a code. Those are server-side only: the frontend
+    Language type is {code, language}, and shipping the aliases inflated every
+    config response by around 40%.
+    """
+    _set_session(client, user_id="reader-1", db_user_id=1, is_admin=False)
+
+    with (
+        patch("shelfmark.config.env._is_config_dir_writable", return_value=True),
+        patch("shelfmark.core.onboarding.is_onboarding_complete", return_value=True),
+    ):
+        resp = client.get("/api/config")
+
+    assert resp.status_code == 200
+    languages = resp.get_json()["book_languages"]
+
+    assert languages, "no languages served"
+    offending = [entry for entry in languages if set(entry) != {"code", "language"}]
+    assert offending == [], f"unexpected keys leaked to clients: {offending[:3]}"
+
+
+def test_language_data_file_is_only_read_by_the_shared_module(main_module):
+    """Reading data/book-languages.json anywhere else reintroduces the drift the
+    shared module exists to prevent, and bypasses the alias handling."""
+    del main_module
+
+    repo_root = Path(__file__).resolve().parents[2]
+    allowed = {Path("shelfmark/core/languages.py")}
+
+    offenders = []
+    for path in (repo_root / "shelfmark").rglob("*.py"):
+        relative = path.relative_to(repo_root)
+        if relative in allowed:
+            continue
+        if "book-languages" in path.read_text(encoding="utf-8"):
+            offenders.append(str(relative))
+
+    assert offenders == [], f"should use shelfmark.core.languages instead: {offenders}"
@@ -95,6 +95,64 @@ def test_upsert_updates_existing_cwa_user_by_username_before_email(user_db):
    assert user["role"] == "admin"


+def test_upsert_renames_existing_cwa_user_matched_by_email(user_db):
+    cwa_user = user_db.create_user(
+        username="old_reader",
+        email="reader@example.com",
+        role="user",
+        auth_source="cwa",
+    )
+
+    user, action = upsert_cwa_user(
+        user_db,
+        cwa_username="renamed_reader",
+        cwa_email="reader@example.com",
+        role="user",
+    )
+
+    assert action == "updated"
+    assert user["id"] == cwa_user["id"]
+    assert user["username"] == "renamed_reader"
+    assert user_db.get_user(username="old_reader") is None
+
+
+def test_upsert_uses_stable_alias_when_renamed_cwa_username_is_taken(user_db):
+    cwa_user = user_db.create_user(
+        username="old_reader",
+        email="reader@example.com",
+        role="user",
+        auth_source="cwa",
+    )
+    local_user = user_db.create_user(
+        username="renamed_reader",
+        email="local@example.com",
+        role="user",
+        auth_source="builtin",
+    )
+
+    first, first_action = upsert_cwa_user(
+        user_db,
+        cwa_username="renamed_reader",
+        cwa_email="reader@example.com",
+        role="admin",
+    )
+    second, second_action = upsert_cwa_user(
+        user_db,
+        cwa_username="renamed_reader",
+        cwa_email="reader@example.com",
+        role="admin",
+    )
+
+    assert first_action == second_action == "updated"
+    assert first["id"] == second["id"] == cwa_user["id"]
+    assert first["username"] == second["username"] == "renamed_reader__cwa"
+    assert first["role"] == second["role"] == "admin"
+    local_after = user_db.get_user(user_id=local_user["id"])
+    assert local_after is not None
+    assert local_after["username"] == "renamed_reader"
+    assert local_after["email"] == "local@example.com"
+
+
 def test_sync_prunes_cwa_users_missing_from_source(user_db):
    active_cwa = user_db.create_user(
        username="active_cwa",
@@ -0,0 +1,196 @@
+"""Tests for the {Language} template variable.
+
+Different-language editions of one book resolve to the same title, so without a
+language token they render to the same path and land in one folder. Audiobookshelf
+treats a folder as exactly one library item, so the two editions become a single
+book with both files as tracks (calibrain/shelfmark#1138).
+"""
+
+import pytest
+
+from shelfmark.core.models import DownloadTask
+from shelfmark.core.naming import (
+    KNOWN_TOKENS,
+    normalize_language_code,
+    parse_naming_template,
+)
+from shelfmark.download.orchestrator import (
+    _restore_task_from_retry_payload,
+    serialize_task_for_retry,
+)
+from shelfmark.download.postprocess.transfer import build_metadata_dict
+
+
+class TestLanguageInKnownTokens:
+    def test_language_in_known_tokens(self):
+        assert "language" in KNOWN_TOKENS
+
+    def test_language_token_parsed(self):
+        assert parse_naming_template("{Language}", {"Language": "sv"}) == "sv"
+
+    def test_language_token_case_insensitive(self):
+        assert parse_naming_template("{language}", {"Language": "sv"}) == "sv"
+
+
+class TestKnownTokensOrdering:
+    """find_placeholder() does a substring find over KNOWN_TOKENS in list order.
+
+    Nothing else guards this contract, so a future token added in the wrong
+    position would silently shadow an existing one.
+    """
+
+    def test_tokens_are_ordered_longest_first(self):
+        lengths = [len(token) for token in KNOWN_TOKENS]
+        assert lengths == sorted(lengths, reverse=True)
+
+    def test_no_token_is_shadowed_by_an_earlier_substring(self):
+        for shorter_index, shorter in enumerate(KNOWN_TOKENS):
+            for longer_index, longer in enumerate(KNOWN_TOKENS):
+                if shorter is longer or shorter not in longer:
+                    continue
+                assert shorter_index > longer_index, (
+                    f"{shorter!r} precedes {longer!r} and would shadow it"
+                )
+
+
+class TestLanguageTemplateSubstitution:
+    """The acceptance cases from the issue."""
+
+    TEMPLATE = "{Author}/{Title}{ (Language)}/{Author} - {Title}"
+    BASE = {"Author": "Andy Weir", "Title": "Project Hail Mary"}
+
+    def test_translated_edition_gets_its_own_folder(self):
+        result = parse_naming_template(
+            self.TEMPLATE, {**self.BASE, "Language": "sv"}, allow_path_separators=True
+        )
+        assert result == "Andy Weir/Project Hail Mary (sv)/Andy Weir - Project Hail Mary"
+
+    def test_untagged_edition_is_unchanged(self):
+        result = parse_naming_template(
+            self.TEMPLATE, {**self.BASE, "Language": None}, allow_path_separators=True
+        )
+        assert result == "Andy Weir/Project Hail Mary/Andy Weir - Project Hail Mary"
+
+    def test_the_two_editions_do_not_collide(self):
+        english = parse_naming_template(
+            self.TEMPLATE, {**self.BASE, "Language": None}, allow_path_separators=True
+        )
+        swedish = parse_naming_template(
+            self.TEMPLATE, {**self.BASE, "Language": "sv"}, allow_path_separators=True
+        )
+        assert english != swedish
+
+    def test_language_as_a_leading_folder(self):
+        result = parse_naming_template(
+            "{Language/}{Author}/{Title}",
+            {**self.BASE, "Language": "sv"},
+            allow_path_separators=True,
+        )
+        assert result == "sv/Andy Weir/Project Hail Mary"
+
+    def test_language_in_a_filename_template(self):
+        result = parse_naming_template(
+            "{Author} - {Title}{ (Language)}", {**self.BASE, "Language": "sv"}
+        )
+        assert result == "Andy Weir - Project Hail Mary (sv)"
+
+    def test_language_is_sanitized(self):
+        result = parse_naming_template("{Title}{ (Language)}", {"Title": "Book", "Language": "s/v"})
+        assert "/" not in result
+
+
+class TestNormalizeLanguageCode:
+    def test_lowercases(self):
+        assert normalize_language_code("EN") == "en"
+        assert normalize_language_code("Sv") == "sv"
+
+    def test_strips_whitespace(self):
+        assert normalize_language_code("  sv  ") == "sv"
+
+    def test_placeholders_render_empty(self):
+        for placeholder in ("unknown", "unk", "n/a", "na", "-", "--", "none", "null", ""):
+            assert normalize_language_code(placeholder) == "", placeholder
+
+    def test_placeholders_are_matched_case_insensitively(self):
+        assert normalize_language_code("Unknown") == ""
+
+    def test_none_renders_empty(self):
+        assert normalize_language_code(None) == ""
+
+
+class TestBuildMetadataWithLanguage:
+    def test_language_reaches_the_template_metadata(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book", language="sv")
+        assert build_metadata_dict(task)["Language"] == "sv"
+
+    def test_language_is_normalized_on_the_way_out(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book", language="SV")
+        assert build_metadata_dict(task)["Language"] == "sv"
+
+    def test_placeholder_language_does_not_reach_the_path(self):
+        # Anna's Archive reports the literal string "unknown" when it cannot tell.
+        task = DownloadTask(task_id="t", source="direct", title="Book", language="unknown")
+        assert build_metadata_dict(task)["Language"] == ""
+
+    def test_missing_language_renders_empty(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book")
+        assert build_metadata_dict(task)["Language"] == ""
+
+
+class TestLanguageSurvivesRetry:
+    """DownloadTask is not rebuilt from dataclasses.fields(), so each of the
+    three orchestrator sites has to carry the field explicitly."""
+
+    def test_roundtrip_preserves_language(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book", language="sv")
+        restored = _restore_task_from_retry_payload(serialize_task_for_retry(task))
+        assert restored is not None
+        assert restored.language == "sv"
+
+    def test_legacy_payload_without_language_restores_cleanly(self):
+        task = DownloadTask(task_id="t", source="prowlarr", title="Book", language="sv")
+        payload = serialize_task_for_retry(task)
+        del payload["language"]
+
+        restored = _restore_task_from_retry_payload(payload)
+
+        assert restored is not None
+        assert restored.language is None
+
+
+class TestEverySpellingCollapsesToOneFolder:
+    """Sources report the same language differently; if the token rendered each
+    spelling verbatim they would land in separate folders, which is the exact
+    collision this token exists to prevent (reported on PR #1142)."""
+
+    TEMPLATE = "{Author}/{Title}{ (Language)}/{Title}"
+
+    def _folder(self, language):
+        task = DownloadTask(
+            task_id="t", source="prowlarr", title="Dune", author="Frank Herbert", language=language
+        )
+        return parse_naming_template(
+            self.TEMPLATE, build_metadata_dict(task), allow_path_separators=True
+        )
+
+    @pytest.mark.parametrize(
+        "spellings",
+        [
+            ("en", "eng", "English", "english", "ENG", "  Eng  "),
+            ("sv", "swe", "Swedish"),
+            ("de", "ger", "deu", "German"),
+            ("ml", "mal", "Malayalam"),
+            ("fa", "per", "fas", "Farsi", "Persian"),
+        ],
+    )
+    def test_all_spellings_of_a_language_share_one_folder(self, spellings):
+        rendered = {self._folder(spelling) for spelling in spellings}
+        assert len(rendered) == 1, f"{spellings} produced {sorted(rendered)}"
+
+    def test_a_language_we_cannot_resolve_is_kept_rather_than_dropped(self):
+        # It still separates editions, and cannot collide with a resolved code
+        # precisely because nothing resolves to it.
+        assert "klingon" in self._folder("Klingon")
+
+    def test_different_languages_still_get_different_folders(self):
+        assert self._folder("English") != self._folder("Swedish")
@@ -0,0 +1,256 @@
+"""Tests for the shared language resolution used by every release source."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from shelfmark.core.languages import (
+    LANGUAGE_DATA_PATH,
+    known_language_codes,
+    language_alias_map,
+    language_name,
+    normalize_language,
+    supported_book_languages,
+)
+
+BASELINE = json.loads(
+    (Path(__file__).parent / "fixtures" / "language_alias_baseline.json").read_text(
+        encoding="utf-8"
+    )
+)
+
+
+class TestBaselineEquivalence:
+    """Every alias the per-source maps used to handle must still resolve the same.
+
+    These maps lived in prowlarr/source.py and audiobookbay/source.py before they
+    were consolidated here. The fixture is a frozen snapshot taken before the
+    move, so a regression shows up as a concrete alias rather than a vague
+    behaviour change.
+    """
+
+    @pytest.mark.parametrize(
+        ("alias", "expected"), sorted(BASELINE["prowlarr_three_letter"].items())
+    )
+    def test_prowlarr_three_letter_aliases_unchanged(self, alias, expected):
+        assert normalize_language(alias) == expected
+
+    @pytest.mark.parametrize(("alias", "expected"), sorted(BASELINE["audiobookbay_names"].items()))
+    def test_audiobookbay_names_unchanged(self, alias, expected):
+        assert normalize_language(alias) == expected
+
+    @pytest.mark.parametrize(
+        ("alias", "expected"), sorted(BASELINE["direct_download_derived"].items())
+    )
+    def test_direct_download_derived_aliases_unchanged(self, alias, expected):
+        # Direct Download built its aliases from the data file rather than a
+        # literal map, so consolidating silently dropped the spellings it
+        # derived -- notably the underscore form of a hyphenated code.
+        assert normalize_language(alias) == expected
+
+
+class TestNormalizeLanguage:
+    def test_accepts_two_letter_codes(self):
+        assert normalize_language("en") == "en"
+        assert normalize_language("sv") == "sv"
+
+    def test_accepts_three_letter_codes_in_both_iso_639_2_forms(self):
+        # Bibliographic and terminological forms differ for these.
+        assert normalize_language("ger") == normalize_language("deu") == "de"
+        assert normalize_language("fre") == normalize_language("fra") == "fr"
+        assert normalize_language("per") == normalize_language("fas") == "fa"
+        assert normalize_language("ice") == normalize_language("isl") == "is"
+        assert normalize_language("may") == normalize_language("msa") == "ms"
+
+    def test_accepts_english_names(self):
+        assert normalize_language("Swedish") == "sv"
+        assert normalize_language("Scottish Gaelic") == "gd"
+
+    def test_is_case_and_whitespace_insensitive(self):
+        assert normalize_language("  ENG  ") == "en"
+        assert normalize_language("sWeDiSh") == "sv"
+
+    def test_returns_none_for_placeholders(self):
+        for placeholder in ("unknown", "unk", "n/a", "na", "-", "--", "none", "null", "", "   "):
+            assert normalize_language(placeholder) is None, placeholder
+
+    def test_returns_none_for_unknown_values(self):
+        assert normalize_language("xyz") is None
+        assert normalize_language("Klingon") is None
+
+    def test_returns_none_for_none(self):
+        assert normalize_language(None) is None
+
+
+class TestLanguageData:
+    def test_every_alias_resolves_to_a_known_code(self):
+        codes = known_language_codes()
+        assert set(language_alias_map().values()) <= codes
+
+    def test_codes_are_ascii(self):
+        # "zh-Hant" once used a U+2011 non-breaking hyphen, which silently
+        # defeats any comparison against the normal spelling.
+        entries = json.loads(LANGUAGE_DATA_PATH.read_text(encoding="utf-8"))
+        assert [e["code"] for e in entries if not e["code"].isascii()] == []
+
+    def test_codes_are_unique(self):
+        entries = json.loads(LANGUAGE_DATA_PATH.read_text(encoding="utf-8"))
+        codes = [e["code"] for e in entries]
+        assert len(codes) == len(set(codes))
+
+    def test_language_name_round_trips(self):
+        assert language_name("sv") == "Swedish"
+        assert language_name("ml") == "Malayalam"
+        assert language_name("zzz") is None
+        assert language_name(None) is None
+
+
+class TestMyAnonamouseCoverage:
+    """MyAnonamouse offers 62 languages and Prowlarr passes its code through
+    untransformed, so every one has to resolve here or the language is lost."""
+
+    # Observed in live MyAnonamouse data via Prowlarr.
+    OBSERVED = {"ENG": "en", "SWE": "sv", "MAL": "ml"}
+
+    @pytest.mark.parametrize(("tag", "expected"), sorted(OBSERVED.items()))
+    def test_observed_tags_resolve(self, tag, expected):
+        assert normalize_language(tag) == expected
+
+    def test_every_offered_language_resolves(self):
+        # Names as MyAnonamouse's own searchLanguages selector lists them.
+        offered = [
+            "English",
+            "Afrikaans",
+            "Arabic",
+            "Bengali",
+            "Bosnian",
+            "Bulgarian",
+            "Burmese",
+            "Catalan",
+            "Chinese",
+            "Croatian",
+            "Czech",
+            "Danish",
+            "Dutch",
+            "Estonian",
+            "Farsi",
+            "Finnish",
+            "French",
+            "German",
+            "Greek",
+            "Gujarati",
+            "Hebrew",
+            "Hindi",
+            "Hungarian",
+            "Icelandic",
+            "Indonesian",
+            "Irish",
+            "Italian",
+            "Japanese",
+            "Javanese",
+            "Kannada",
+            "Korean",
+            "Lithuanian",
+            "Latin",
+            "Latvian",
+            "Malay",
+            "Malayalam",
+            "Manx",
+            "Marathi",
+            "Norwegian",
+            "Polish",
+            "Portuguese",
+            "Punjabi",
+            "Romanian",
+            "Russian",
+            "Scottish Gaelic",
+            "Sanskrit",
+            "Serbian",
+            "Slovenian",
+            "Spanish",
+            "Swedish",
+            "Tagalog",
+            "Tamil",
+            "Telugu",
+            "Thai",
+            "Turkish",
+            "Ukrainian",
+            "Urdu",
+            "Vietnamese",
+        ]
+        unresolved = [name for name in offered if normalize_language(name) is None]
+        assert unresolved == []
+
+
+class TestSupportedBookLanguages:
+    """What the settings dropdown and /api/config expose to clients."""
+
+    def test_exposes_only_the_fields_clients_declare(self):
+        # The frontend Language type is {code, language}. Aliases are an
+        # implementation detail and would bloat every /api/config response.
+        entries = supported_book_languages()
+        assert entries
+        assert all(set(e) == {"code", "language"} for e in entries)
+
+    def test_covers_every_known_code(self):
+        assert {e["code"] for e in supported_book_languages()} == set(known_language_codes())
+
+
+class TestLegacyTraditionalChineseCode:
+    """Traditional Chinese was stored with a U+2011 non-breaking hyphen.
+
+    The canonical code is now the ASCII spelling, but anything persisted
+    earlier still carries U+2011, so both have to resolve to the same language
+    or those users lose their selection (reported on PR #1142).
+    """
+
+    LEGACY = "zh\u2011Hant"
+    CANONICAL = "zh-Hant"
+
+    def test_the_legacy_spelling_still_resolves(self):
+        assert normalize_language(self.LEGACY) == self.CANONICAL
+
+    def test_both_spellings_are_the_same_language(self):
+        assert normalize_language(self.LEGACY) == normalize_language(self.CANONICAL)
+
+    def test_the_legacy_spelling_really_does_use_a_different_character(self):
+        # Guards the test itself: if this ever became a plain hyphen the two
+        # cases above would pass for the wrong reason.
+        assert self.LEGACY != self.CANONICAL
+        assert not self.LEGACY.isascii()
+
+    @pytest.mark.parametrize("dash", ["-", "\u2010", "\u2011", "\u2012", "\u2013", "\u2014"])
+    def test_any_dash_variant_resolves(self, dash):
+        assert normalize_language(f"zh{dash}Hant") == self.CANONICAL
+
+
+class TestCodesDoNotShadowEachOther:
+    """A code must never resolve to a different language than itself.
+
+    'zh' and 'zh-Hant' are distinct entries; registering the base of a
+    hyphenated code as an alias made 'zh' resolve correctly only because
+    Chinese happens to appear first in the data file.
+    """
+
+    def test_chinese_does_not_resolve_to_traditional_chinese(self):
+        assert normalize_language("zh") == "zh"
+        assert normalize_language("zh-Hant") == "zh-Hant"
+
+    def test_every_code_resolves_to_itself(self):
+        for code in known_language_codes():
+            assert normalize_language(code) == code, f"{code} resolved elsewhere"
+
+
+class TestSubtagSeparators:
+    """The U+2011 in the old Traditional Chinese code renders close enough to
+    both a hyphen and an underscore that either is a plausible thing to type."""
+
+    @pytest.mark.parametrize("separator", ["-", "_", "‐", "‑", "–", "—"])
+    def test_any_separator_spelling_resolves(self, separator):
+        assert normalize_language(f"zh{separator}Hant") == "zh-Hant"
+
+    def test_separators_do_not_merge_unrelated_codes(self):
+        # Folding a separator must not make one language answer to another.
+        assert normalize_language("zh") == "zh"
+        assert normalize_language("en_GB") is None
--- a/Show More
+++ b/Show More