fix(search): let manual search switch media type under forced combined search (#1262 )

Manual search browses release sources directly, one media type at a time, so the combined (both) flow never applied to it — yet FORCE_COMBINED_SEARCH locked the content-type selector onto both, pinning manual search to ebook sources with no way to reach audiobook sources (no Audiobay tab). Treat a manual search target as combined-exempt in the search bar: present a plain, switchable Books/Audiobooks selector (unlocked, no combined toggle), even when combined search is forced on for metadata targets. Metadata search behavior is unchanged. Fixes #1256
build(deps-dev): bump knip from 6.32.1 to 6.32.2 in /src/frontend in the npm-deps group (#1246 )
2026-09-24 22:05:20 +01:00 · 2026-08-24 01:57:42 -04:00 · 2026-08-24 01:57:08 -04:00 · 2026-08-24 01:57:00 -04:00 · 2026-08-24 01:56:52 -04:00 · 2026-08-24 01:56:46 -04:00
149 changed files with 16071 additions and 2089 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@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
@@ -96,7 +96,7 @@ jobs:
            type=ref,event=tag

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

      - name: Build and push ${{ matrix.target }} Docker image
        id: push
@@ -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@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.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@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.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@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        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@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        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@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          version: "0.11.3"
          python-version: "3.14"
@@ -81,7 +81,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

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

      - name: Build shelfmark-lite image
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
@@ -25,14 +25,14 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Initialize CodeQL
-        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v3
+        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v3
        with:
          languages: ${{ matrix.language }}

      - name: Autobuild
-        uses: github/codeql-action/autobuild@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v3
+        uses: github/codeql-action/autobuild@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v3

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v3
+        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # 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.2
+      - 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@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        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@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        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:d3400aa122fa42cf0af0dbe8ec3091b047eac5c8f7e3539f7135e86d855dc015 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.12.5@sha256:e85be844203885286c60ffad8a858d48afb6c5a5c237ca0e67f12e74b8f174b1 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
@@ -142,9 +152,14 @@ RUN mkdir -p \
 EXPOSE ${FLASK_PORT}

 # Add healthcheck for container status
-# Uses /api/health which doesn't require authentication
-HEALTHCHECK --interval=60s --timeout=60s --start-period=60s --retries=3 \
-    CMD curl -s http://localhost:${FLASK_PORT}/api/health > /dev/null || exit 1
+# Uses /api/health which doesn't require authentication.
+# curl needs -f so an HTTP error status fails the probe instead of passing it:
+# plain `curl -s` exits 0 on a 500, which reported a broken app as healthy.
+# timeout stays well under interval so a hung probe cannot occupy a whole cycle.
+# --start-interval matches the daemon default (5s), made explicit so startup
+# probing does not depend on that default staying put.
+HEALTHCHECK --interval=30s --timeout=10s --start-period=90s --start-interval=5s --retries=3 \
+    CMD curl -fsS http://localhost:${FLASK_PORT}/api/health > /dev/null || exit 1

 # Use dumb-init as the entrypoint to handle signals properly
 ENTRYPOINT ["/usr/bin/dumb-init", "--"]
@@ -194,6 +209,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 +223,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 +244,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})`
@@ -703,13 +704,13 @@ Choose how downloaded audiobook files are named and organized.

 - **Type:** string (choice)
 - **Default:** `rename`
- **Options:** `none` (None), `rename` (Rename Only), `organize` (Rename and Organize)
+- **Options:** `none` (None), `rename` (Rename Only), `organize` (Rename and Organize), `rename_and_group` (Rename and Group)

 #### `TEMPLATE_AUDIOBOOK_RENAME`

 **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)**
@@ -1210,7 +1223,9 @@ How long to cache individual book details. Default: 600 (10 minutes). Max: 60480
 | `PROWLARR_URL` | Base URL of your Prowlarr instance | string | _none_ |
 | `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_INDEXER_TIMEOUT` | How long to wait for a single indexer to answer a search. Indexers behind FlareSolverr can need 90 seconds or more while a cold Cloudflare challenge is solved; raise this if searches come back empty and the Prowlarr log shows the search still running. | number | `90` |
 | `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>
@@ -1254,6 +1269,16 @@ Select which indexers to search. 📚 = has book categories. Leave empty to sear
 - **Type:** string (comma-separated)
 - **Default:** _empty list_

+#### `PROWLARR_INDEXER_TIMEOUT`
+
+**Indexer Search Timeout (seconds)**
+
+How long to wait for a single indexer to answer a search. Indexers behind FlareSolverr can need 90 seconds or more while a cold Cloudflare challenge is solved; raise this if searches come back empty and the Prowlarr log shows the search still running.
+
+- **Type:** number
+- **Default:** `90`
+- **Constraints:** min: 5, max: 300
+
 #### `PROWLARR_AUTO_EXPAND`

 **Auto-expand search on no results**
@@ -1263,6 +1288,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 +1315,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 +1350,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 +1449,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 +1491,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 +1511,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 +1552,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 +1577,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 +1605,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 +1652,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 +1836,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 +1863,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`

@@ -1864,7 +1988,7 @@ Move deletes the job from your usenet client after import; Copy keeps it in the
 | Variable | Description | Type | Default |
 |----------|-------------|------|---------|
 | `HARDCOVER_ENABLED` | Enable Hardcover as a metadata provider for book searches | boolean | `false` |
-| `HARDCOVER_API_KEY` | Get your API key from hardcover.app/account/api | string (secret) | _none_ |
+| `HARDCOVER_API_KEY` | Get your API key from hardcover.app/account/api (starts with hc_pat_) | string (secret) | _none_ |
 | `HARDCOVER_DEFAULT_SORT` | Default sort order for Hardcover search results. | string (choice) | `relevance` |
 | `HARDCOVER_EXCLUDE_COMPILATIONS` | Filter out compilations, anthologies, and omnibus editions from search results | boolean | `false` |
 | `HARDCOVER_EXCLUDE_UNRELEASED` | Filter out books with a release year in the future | boolean | `false` |
@@ -1886,7 +2010,7 @@ Enable Hardcover as a metadata provider for book searches

 **API Key**

-Get your API key from hardcover.app/account/api
+Get your API key from hardcover.app/account/api (starts with hc_pat_)

 - **Type:** string (secret)
 - **Default:** _none_
@@ -2004,6 +2128,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 +2155,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 +2183,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**
@@ -2161,6 +2315,7 @@ Override destination based on content type metadata.
 | `EXT_BYPASSER_URL` | URL of the external bypasser service (e.g., FlareSolverr). | string | `http://flaresolverr:8191` |
 | `EXT_BYPASSER_PATH` | API path for the external bypasser. | string | `/v1` |
 | `EXT_BYPASSER_TIMEOUT` | Timeout for external bypasser requests in milliseconds. | number | `60000` |
+| `BYPASS_BROWSER_IDLE_TIMEOUT` | How long the bypass helper process may sit unused before it is shut down. Higher keeps more searches fast, lower frees memory sooner. | number | `180` |

 <details>
 <summary>Detailed descriptions</summary>
@@ -2216,6 +2371,17 @@ Timeout for external bypasser requests in milliseconds.
 - **Requires restart:** Yes
 - **Constraints:** min: 10000, max: 300000

+#### `BYPASS_BROWSER_IDLE_TIMEOUT`
+
+**Bypasser Idle Timeout (seconds)**
+
+How long the bypass helper process may sit unused before it is shut down. Higher keeps more searches fast, lower frees memory sooner.
+
+- **Type:** number
+- **Default:** `180`
+- **Requires restart:** Yes
+- **Constraints:** min: 30, max: 3600
+
 </details>

 ### Direct Download: Mirrors
@@ -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

@@ -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,28 +19,31 @@ dependencies = [
    "psutil",
    "emoji",
    "rarfile",
-    "qbittorrent-api",
+    "qbittorrent-api>=2026.8.1",
    "transmission-rpc",
    "authlib>=1.7.2,<1.8",
-    "apprise>=1.12.0",
+    "apprise>=1.13.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.28.1",
 ]

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

 [dependency-groups]
 dev = [
-    "basedpyright>=1.39.9",
+    "basedpyright>=1.39.10",
    "prek",
    "pytest",
    "pytest-cov",
    "pytest-xdist>=3.8.0",
-    "ruff==0.15.22",
+    "ruff==0.16.4",
    "vulture>=2.14",
 ]

@@ -3,7 +3,7 @@
 <img src="src/frontend/public/logo.png" alt="Shelfmark" width="200">

 > [!NOTE]
-> This project is in a stable state as of May 2026 but is not under active maintenance. 
+> Shelfmark is feature stable and maintained on a best-effort basis. Bug fixes, security updates, and small quality-of-life improvements are still shipped, and pull requests are reviewed — including new features. There is no roadmap for new features for now.

 Shelfmark is a self-hosted web interface for searching and requesting books and audiobooks across multiple sources. Bring your own sources, metadata providers, and download clients to build a single hub for your digital library. Supports multiple users with a built-in request system, so you can share your instance with others and let them browse and request books on their own.

@@ -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

@@ -94,6 +95,30 @@ volumes:
 - Aggregates releases from multiple configured sources
 - Full audiobook support

+### Hardcover API Key
+
+Hardcover powers metadata search in Universal mode. Create a token at
+[hardcover.app/account/api](https://hardcover.app/account/api) — current keys start with `hc_pat_`
+and are far shorter than the JWTs Hardcover issued before August 2026.
+
+Tick these seven scopes on the token screen:
+
+| Scope | Used for |
+|-------|----------|
+| `read:catalog` | Metadata search, plus book, edition, author and series lookups |
+| `read:library` | Your reading status and shelf counts |
+| `read:lists` | Your lists and the books on them |
+| `read:me:content` | Test Connection and the "Connected as" label |
+| `read:users` | Usernames shown alongside lists |
+| `write:library` | Setting a book's reading status from Shelfmark |
+| `write:lists` | Adding and removing books from lists, including auto-remove on download |
+
+The two `write:` scopes matter only if you set reading status from Shelfmark or leave
+**Auto-Remove from List on Download** enabled (it is on by default) — without them those actions
+fail silently. Everything else Hardcover offers (journal, goals, reviews, prompts, notifications,
+account) can stay unticked. The `all` scope works too, but it grants full account access including
+deletion, so prefer the list above.
+
 ### Environment Variables

 Environment variables work for initial setup and Docker deployments. They serve as defaults that can be overridden in the web interface.
@@ -122,7 +147,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 +163,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 +211,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
@@ -225,9 +262,11 @@ These are non-goals, not missing features.

 ## Contributing

-Shelfmark's core feature set is complete. Development focuses on stability, bug fixes, quality-of-life improvements, and refining the search experience. Contributions in these areas are welcome, please file issues or submit pull requests on GitHub.
+Shelfmark's core feature set is complete.

-Feature requests that fall outside the project scope (library integration, automation, collection management) will be closed. If you're unsure whether something fits, open a discussion first.
+Pull requests are welcome and all of them get reviewed, new features included. If you want a feature, the fastest path is to send a PR for it rather than to file a request.
+
+Feature requests that fall outside the project scope (library integration, automation, collection management) will be closed, and PRs implementing them won't be merged. If you're unsure whether something fits, open a discussion first.

 ## Health Monitoring

@@ -247,7 +286,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

@@ -0,0 +1,52 @@
+"""Challenge-page detection shared by the bypassers and the HTTP retry path.
+
+Kept out of `internal_bypasser` so the HTTP layer can recognise an interstitial
+without importing SeleniumBase: that module is imported lazily precisely because its
+browser dependencies are optional, and external-bypasser setups run without them.
+"""
+
+# Matched against lowercased text, so every entry must be lowercase.
+CLOUDFLARE_INDICATORS = [
+    "just a moment",
+    "verify you are human",
+    "verifying you are human",
+    "cloudflare.com/products/turnstile",
+]
+
+DDOS_GUARD_INDICATORS = [
+    "ddos-guard",
+    "ddos guard",
+    "checking your browser before accessing",
+    "complete the manual check to continue",
+    "could not verify your browser automatically",
+]
+
+# Markers that exist only in raw markup: the bypassers scan rendered innerText, where
+# a script src or a <title> never appears. The title match is scoped to the tag on
+# purpose - hosts word the rest of that sentence differently, and matching "checking
+# your browser" as free text would trip on any page that merely discusses a challenge.
+_RAW_HTML_MARKERS = (
+    "<title>checking your browser",
+    "/cdn-cgi/challenge-platform",
+    "/.well-known/ddos-guard/",
+)
+
+# An interstitial is a few KB of markup. Past that it is a real page that happens to
+# mention a marker - a protected site links its own DDoS-Guard endpoints on every page.
+MAX_CHALLENGE_HTML_CHARS = 64 * 1024
+
+
+def challenge_marker(html: str) -> str | None:
+    """Return the marker proving `html` is an unsolved challenge page, or None.
+
+    Only meaningful for a response that already carries a challenge status: the
+    markers appear on protected sites' real pages too, so the status is what
+    separates "blocked" from "served".
+    """
+    if not html or len(html) > MAX_CHALLENGE_HTML_CHARS:
+        return None
+    lowered = html.lower()
+    for marker in (*_RAW_HTML_MARKERS, *DDOS_GUARD_INDICATORS, *CLOUDFLARE_INDICATORS):
+        if marker in lowered:
+            return marker
+    return None
@@ -0,0 +1,260 @@
+"""Clearance cookies won by a bypass, shared by every bypasser implementation.
+
+Kept in its own module rather than inside a bypasser because both of them feed it and
+both read from it. The internal bypasser cannot host it: it imports seleniumbase at
+module scope, which is exactly the dependency an external-bypasser deployment is
+entitled not to have installed.
+"""
+
+import threading
+import time
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import urlparse
+
+from shelfmark.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+# Cookie storage - shared with requests library for Cloudflare bypass
+# Nested mapping of domain to cookie name to cookie metadata.
+_cf_cookies: dict[str, dict] = {}
+_cf_cookies_lock = threading.Lock()
+
+# User-Agent storage - Cloudflare ties cf_clearance to the UA that solved the challenge
+_cf_user_agents: dict[str, str] = {}
+
+# Protection cookie names we care about (Cloudflare and DDoS-Guard)
+CF_COOKIE_NAMES = {"cf_clearance", "__cf_bm", "cf_chl_2", "cf_chl_prog"}
+DDG_COOKIE_NAMES = {
+    "__ddg1_",
+    "__ddg2_",
+    "__ddg5_",
+    "__ddg8_",
+    "__ddg9_",
+    "__ddg10_",
+    "__ddgid_",
+    "__ddgmark_",
+    "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')."""
+    return ".".join(domain.split(".")[-2:]) if "." in domain else domain
+
+
+def _get_full_cookie_domains() -> set[str]:
+    """Return mirror domains that need full-session cookie extraction."""
+    from shelfmark.core.mirrors import get_zlib_cookie_domains
+
+    return {_get_base_domain(domain) for domain in get_zlib_cookie_domains()}
+
+
+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_")
+    is_ddg = name in DDG_COOKIE_NAMES or name.startswith("__ddg")
+    return is_cf or is_ddg
+
+
+def _cookie_field(cookie: Any, name: str) -> Any:
+    """Read one field from a cookie in either shape we are handed.
+
+    The internal bypasser extracts CDP cookie objects; an external bypasser returns
+    the same fields as JSON objects, so the difference is attribute versus key access.
+    """
+    if isinstance(cookie, Mapping):
+        return cookie.get(name)
+    return getattr(cookie, name, None)
+
+
+def _cookie_expiry(cookie: Any) -> float | None:
+    """A cookie's absolute expiry, or None when it is a session cookie.
+
+    The two spellings are not interchangeable and both reach this store. CDP and
+    Playwright cookies carry `expires`; the WebDriver cookie object - what a
+    Selenium-based solver such as FlareSolverr returns - carries `expiry`. Reading
+    only one silently turns every cookie from the other into a never-expiring one,
+    which is exactly how dead clearance ends up replayed forever (see
+    get_cf_cookies_for_domain).
+
+    The value is coerced rather than trusted: it arrives as JSON from a service we
+    do not control, and a string here used to raise straight out of the store.
+    """
+    for field in ("expires", "expiry"):
+        raw = _cookie_field(cookie, field)
+        if raw is None:
+            continue
+        try:
+            expiry = float(raw)
+        except TypeError, ValueError:
+            logger.debug("Unreadable cookie expiry %r; treating as a session cookie", raw)
+            return None
+        # <= 0 is how both shapes spell "session cookie", not "expired in 1970".
+        return expiry if expiry > 0 else None
+    return None
+
+
+def store_extracted_cookies(
+    *,
+    url: str,
+    cookies: list[Any],
+    user_agent: str | None = None,
+) -> None:
+    """Store filtered bypass cookies (and optional UA) for a URL domain."""
+    parsed = urlparse(url)
+    domain = parsed.hostname or ""
+    if not domain:
+        return
+
+    base_domain = _get_base_domain(domain)
+    extract_all = base_domain in _get_full_cookie_domains()
+
+    cookies_found: dict[str, dict[str, Any]] = {}
+    for cookie in cookies:
+        name = _cookie_field(cookie, "name") or ""
+        if not _should_extract_cookie(name, extract_all=extract_all):
+            continue
+        secure = _cookie_field(cookie, "secure")
+        cookies_found[name] = {
+            "value": _cookie_field(cookie, "value") or "",
+            "domain": _cookie_field(cookie, "domain") or domain,
+            "path": _cookie_field(cookie, "path") or "/",
+            "expiry": _cookie_expiry(cookie),
+            "secure": True if secure is None else bool(secure),
+            "httpOnly": True,
+        }
+
+    if not cookies_found:
+        return
+
+    with _cf_cookies_lock:
+        _cf_cookies[base_domain] = cookies_found
+        if user_agent:
+            _cf_user_agents[base_domain] = user_agent
+            logger.debug("Stored UA for %s: %s...", base_domain, str(user_agent)[:60])
+        else:
+            logger.debug("No UA captured for %s", base_domain)
+
+    cookie_type = "all" if extract_all else "protection"
+    logger.debug("Extracted %s %s cookies for %s", len(cookies_found), cookie_type, base_domain)
+
+
+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:
+        return {}
+
+    base_domain = _get_base_domain(domain)
+
+    with _cf_cookies_lock:
+        cookies = _cf_cookies.get(base_domain, {})
+        if not cookies:
+            return {}
+
+        cf_clearance = cookies.get("cf_clearance", {})
+        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 {}
+
+        # 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:
+    """Check if we have valid Cloudflare cookies for a domain."""
+    return bool(get_cf_cookies_for_domain(domain))
+
+
+def get_cf_user_agent_for_domain(domain: str) -> str | None:
+    """Get the User-Agent that was used during bypass for a domain."""
+    if not domain:
+        return None
+    with _cf_cookies_lock:
+        return _cf_user_agents.get(_get_base_domain(domain))
+
+
+def export_store() -> tuple[dict[str, dict], dict[str, str]]:
+    """Snapshot the whole store, for handing to another process.
+
+    The internal bypasser's Docker helper solves in a subprocess, so the clearance it
+    wins has to be serialized back to the parent or the solve is lost with the child.
+    """
+    with _cf_cookies_lock:
+        return (
+            {domain: dict(cookies) for domain, cookies in _cf_cookies.items()},
+            dict(_cf_user_agents),
+        )
+
+
+def import_store(cookies: object, user_agents: object) -> None:
+    """Merge a snapshot produced by :func:`export_store` into this process's store."""
+    with _cf_cookies_lock:
+        if isinstance(cookies, dict):
+            _cf_cookies.update(cookies)
+        if isinstance(user_agents, dict):
+            _cf_user_agents.update(
+                {str(domain): str(agent) for domain, agent in user_agents.items()}
+            )
+
+
+def clear_cf_cookies(domain: str | None = None) -> None:
+    """Clear stored Cloudflare cookies and User-Agent. If domain is None, clear all."""
+    with _cf_cookies_lock:
+        if domain:
+            base_domain = _get_base_domain(domain)
+            _cf_cookies.pop(base_domain, None)
+            _cf_user_agents.pop(base_domain, None)
+        else:
+            _cf_cookies.clear()
+            _cf_user_agents.clear()
@@ -2,17 +2,19 @@

 import random
 import time
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any

 import requests

 from shelfmark.bypass import BypassCancelledError
+from shelfmark.bypass.cookie_store import store_extracted_cookies
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.utils import normalize_http_url
 from shelfmark.download.network import get_ssl_verify

 if TYPE_CHECKING:
+    from collections.abc import Mapping
    from threading import Event

    from shelfmark.download import network
@@ -47,6 +49,47 @@ 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 _store_solution_clearance(target_url: str, solution: Mapping[str, Any]) -> None:
+    """Keep the clearance the solver won, so later requests do not re-solve.
+
+    A solve is the expensive part of an external bypass - tens of seconds of real
+    browser - and FlareSolverr-compatible services hand back the cookies and the
+    User-Agent that earned it. Dropping them meant every single request paid a 403
+    plus a full solve, and a file download (which the solver cannot proxy, being
+    binary) never presented clearance at all.
+
+    The UA matters as much as the cookies: Cloudflare ties cf_clearance to the UA
+    that solved the challenge, so replaying the cookie under our own UA is rejected.
+    """
+    cookies = solution.get("cookies") or []
+    if not isinstance(cookies, list):
+        logger.debug("External bypasser returned no usable cookie list for '%s'", target_url)
+        return
+
+    user_agent = solution.get("userAgent")
+    store_extracted_cookies(
+        url=target_url,
+        cookies=cookies,
+        user_agent=user_agent if isinstance(user_agent, str) else None,
+    )
+
+
 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(
@@ -100,6 +143,15 @@ def _fetch_via_bypasser(target_url: str) -> str | None:
            logger.warning("External bypasser returned empty response for '%s'", target_url)
            return None

+        try:
+            _store_solution_clearance(target_url, solution)
+        except AttributeError, KeyError, TypeError, ValueError:
+            # Storing clearance is an optimisation; the page is the product. The
+            # solution JSON comes from a service we do not control, so a surprise in
+            # its cookie shape must not discard HTML that already cost a ~30s solve
+            # and send the caller round for up to MAX_RETRY more of them.
+            logger.debug("Could not store bypass clearance for '%s'", target_url, exc_info=True)
+
    except requests.exceptions.Timeout:
        logger.warning(
            "External bypasser timed out for '%s' (connect: %ss, read: %.0fs)",
@@ -5,7 +5,6 @@ import asyncio
 import json
 import os
 import random
-import shutil
 import signal
 import socket
 import stat
@@ -28,6 +27,15 @@ from seleniumbase import cdp_driver
 from seleniumbase.undetected.cdp_driver.connection import ProtocolException

 from shelfmark.bypass import BypassCancelledError
+from shelfmark.bypass.challenge import CLOUDFLARE_INDICATORS, DDOS_GUARD_INDICATORS
+from shelfmark.bypass.cookie_store import (
+    clear_cf_cookies,
+    export_store,
+    get_cf_cookies_for_domain,
+    get_cf_user_agent_for_domain,
+    import_store,
+    store_extracted_cookies,
+)
 from shelfmark.bypass.fingerprint import get_screen_size
 from shelfmark.config import env
 from shelfmark.config.env import LOG_DIR
@@ -50,23 +58,31 @@ _LOADING_BODY_LENGTH_MAX = 50
 _PAGE_BODY_PREVIEW_CHARS = 500
 _BROWSER_START_TIMEOUT_SECONDS = 45.0
 _BYPASS_SUBPROCESS_TIMEOUT_SECONDS = 420.0
+# How long a cancelled bypass may take to close its browser before the calling thread
+# stops waiting for it. Counted on top of the bypass deadline, so every budget below is
+# set to leave room for it.
+_CDP_UNWIND_GRACE_SECONDS = 15.0
+# Same wall-clock budget as the Docker helper process, applied to the in-process CDP path
+# so both branches of get() are bounded the same way: the deadline plus the unwind grace
+# comes to _BYPASS_SUBPROCESS_TIMEOUT_SECONDS either way.
+_IN_PROCESS_BYPASS_TIMEOUT_SECONDS = _BYPASS_SUBPROCESS_TIMEOUT_SECONDS - _CDP_UNWIND_GRACE_SECONDS
 _BYPASS_CHILD_ENV = "SHELFMARK_INTERNAL_BYPASSER_CHILD"
-
-# Challenge detection indicators
-CLOUDFLARE_INDICATORS = [
-    "just a moment",
-    "verify you are human",
-    "verifying you are human",
-    "cloudflare.com/products/turnstile",
-]
-
-DDOS_GUARD_INDICATORS = [
-    "ddos-guard",
-    "ddos guard",
-    "checking your browser before accessing",
-    "complete the manual check to continue",
-    "could not verify your browser automatically",
-]
+# The helper bounds each bypass below the parent's deadline, so it is the side that gives
+# up first: it still gets to report the timeout and close its browser, and stays available
+# for the next request. A parent that hit its deadline first could only kill the helper,
+# throwing away a process the next request would have to start again. The 30s covers the
+# unwind grace as well, so a helper that times out and closes its browser as slowly as it
+# is allowed to still answers with 15s to spare.
+_CHILD_BYPASS_TIMEOUT_SECONDS = _BYPASS_SUBPROCESS_TIMEOUT_SECONDS - 30.0
+# The helper publishes its answer by writing the result file the request named, so the
+# parent waits by watching for that file rather than by reading a stream it would have to
+# demultiplex from the helper's log output.
+_HELPER_RESULT_POLL_SECONDS = 0.05
+# Closing the helper's stdin asks it to shut down; this is how long it may take to finish
+# what it is doing and exit before its session is killed instead.
+_HELPER_SHUTDOWN_GRACE_SECONDS = 15.0
+_HELPER_IDLE_TIMEOUT_DEFAULT = 180.0
+_PARENT_WATCHDOG_INTERVAL_SECONDS = 5.0


 class _DisplayState(TypedDict):
@@ -87,8 +103,8 @@ DISPLAY: _DisplayState = {
    "ffmpeg_output": None,
 }
 LOCKED = threading.Lock()
-_PGREP_PATH = shutil.which("pgrep")
-_PKILL_PATH = shutil.which("pkill")
+_PROC_ROOT = Path("/proc")
+_BROWSER_PROCESS_PATTERNS = ("chrome", "chromium", "Xvfb", "ffmpeg")
 _RNG = random.SystemRandom()

 _CDP_OPERATION_ERRORS = (
@@ -211,107 +227,42 @@ class _CdpWorker:
            msg = "CDP worker loop failed to start"
            raise RuntimeError(msg)

+    @staticmethod
+    async def _bounded(coro: Any, timeout: float | None) -> Any:
+        """Run the coroutine under its deadline, on the loop that owns it.
+
+        The deadline has to be enforced from inside the loop rather than by the calling
+        thread: asyncio.wait_for() cancels the bypass and then *waits for it to unwind*,
+        so `finally: await _close_cdp_driver(driver)` has finished by the time this
+        raises. Cancelling from outside returns the moment the cancellation is scheduled,
+        which in a helper serving many requests let the abandoned bypass close its browser
+        while the next one was already opening its own - on the same loop, sharing the
+        DISPLAY globals and one process group.
+        """
+        if timeout is None:
+            return await coro
+        return await asyncio.wait_for(coro, timeout)
+
    def run(self, coro: Any, timeout: float | None = None) -> Any:
        self.start()
        if not self._loop or self._loop.is_closed():
            msg = "CDP worker loop not available"
            raise RuntimeError(msg)
-        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
-        return future.result(timeout=timeout)
+        future = asyncio.run_coroutine_threadsafe(self._bounded(coro, timeout), self._loop)
+        # Backstop for an unwind that wedges too: _close_cdp_driver awaits websockets that
+        # a dead browser may never answer, and _bounded cannot outlive its own cleanup.
+        wait_for = None if timeout is None else timeout + _CDP_UNWIND_GRACE_SECONDS
+        try:
+            return future.result(timeout=wait_for)
+        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()

-# Cookie storage - shared with requests library for Cloudflare bypass
-# Nested mapping of domain to cookie name to cookie metadata.
-_cf_cookies: dict[str, dict] = {}
-_cf_cookies_lock = threading.Lock()
-
-# User-Agent storage - Cloudflare ties cf_clearance to the UA that solved the challenge
-_cf_user_agents: dict[str, str] = {}
-
-# Protection cookie names we care about (Cloudflare and DDoS-Guard)
-CF_COOKIE_NAMES = {"cf_clearance", "__cf_bm", "cf_chl_2", "cf_chl_prog"}
-DDG_COOKIE_NAMES = {
-    "__ddg1_",
-    "__ddg2_",
-    "__ddg5_",
-    "__ddg8_",
-    "__ddg9_",
-    "__ddg10_",
-    "__ddgid_",
-    "__ddgmark_",
-    "ddg_last_challenge",
-}
-
-
-def _get_base_domain(domain: str) -> str:
-    """Extract base domain from hostname (e.g., 'www.example.com' -> 'example.com')."""
-    return ".".join(domain.split(".")[-2:]) if "." in domain else domain
-
-
-def _get_full_cookie_domains() -> set[str]:
-    """Return mirror domains that need full-session cookie extraction."""
-    from shelfmark.core.mirrors import get_zlib_cookie_domains
-
-    return {_get_base_domain(domain) for domain in get_zlib_cookie_domains()}
-
-
-def _should_extract_cookie(name: str, *, extract_all: bool) -> bool:
-    """Determine if a cookie should be extracted based on its name."""
-    if extract_all:
-        return True
-    is_cf = name in CF_COOKIE_NAMES or name.startswith("cf_")
-    is_ddg = name in DDG_COOKIE_NAMES or name.startswith("__ddg")
-    return is_cf or is_ddg
-
-
-def _store_extracted_cookies(
-    *,
-    url: str,
-    cookies: list[Any],
-    user_agent: str | None = None,
-) -> None:
-    """Store filtered bypass cookies (and optional UA) for a URL domain."""
-    parsed = urlparse(url)
-    domain = parsed.hostname or ""
-    if not domain:
-        return
-
-    base_domain = _get_base_domain(domain)
-    extract_all = base_domain in _get_full_cookie_domains()
-
-    cookies_found: dict[str, dict[str, Any]] = {}
-    for cookie in cookies:
-        name = getattr(cookie, "name", "") or ""
-        if not _should_extract_cookie(name, extract_all=extract_all):
-            continue
-        expires = getattr(cookie, "expires", None)
-        if expires is not None and expires <= 0:
-            expires = None
-        cookies_found[name] = {
-            "value": getattr(cookie, "value", ""),
-            "domain": getattr(cookie, "domain", None) or domain,
-            "path": getattr(cookie, "path", None) or "/",
-            "expiry": expires,
-            "secure": bool(getattr(cookie, "secure", True)),
-            "httpOnly": True,
-        }
-
-    if not cookies_found:
-        return
-
-    with _cf_cookies_lock:
-        _cf_cookies[base_domain] = cookies_found
-        if user_agent:
-            _cf_user_agents[base_domain] = user_agent
-            logger.debug("Stored UA for %s: %s...", base_domain, str(user_agent)[:60])
-        else:
-            logger.debug("No UA captured for %s", base_domain)
-
-    cookie_type = "all" if extract_all else "protection"
-    logger.debug("Extracted %s %s cookies for %s", len(cookies_found), cookie_type, base_domain)
-

 async def _extract_cookies_from_cdp(driver: Any, page: Any, url: str) -> None:
    """Extract cookies from a CDP browser after successful bypass."""
@@ -327,117 +278,116 @@ async def _extract_cookies_from_cdp(driver: Any, page: Any, url: str) -> None:
        except _CDP_OPERATION_ERRORS:
            user_agent = None

-        _store_extracted_cookies(url=url, cookies=all_cookies, user_agent=user_agent)
+        store_extracted_cookies(url=url, cookies=all_cookies, user_agent=user_agent)

    except _CDP_OPERATION_ERRORS as e:
        logger.debug("Failed to extract cookies: %s", e)


-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:
-        return {}
-
-    base_domain = _get_base_domain(domain)
-
-    with _cf_cookies_lock:
-        cookies = _cf_cookies.get(base_domain, {})
-        if not cookies:
-            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 {}
-
-        return {name: c["value"] for name, c in cookies.items()}
+def _read_process_cmdline(proc_dir: Path) -> str:
+    """Return a process's full command line, or "" when it cannot be read."""
+    try:
+        raw = (proc_dir / "cmdline").read_bytes()
+    except OSError:
+        return ""
+    return raw.replace(b"\x00", b" ").decode("utf-8", "replace").strip()


-def has_valid_cf_cookies(domain: str) -> bool:
-    """Check if we have valid Cloudflare cookies for a domain."""
-    return bool(get_cf_cookies_for_domain(domain))
-
-
-def get_cf_user_agent_for_domain(domain: str) -> str | None:
-    """Get the User-Agent that was used during bypass for a domain."""
-    if not domain:
+def _read_process_pgid(proc_dir: Path) -> int | None:
+    """Return a process's group id from /proc/<pid>/stat, or None when unreadable."""
+    try:
+        stat_line = (proc_dir / "stat").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    # Field 2 (comm) is parenthesised and may itself contain spaces and parens, so the
+    # fields are only unambiguous after the last ')': state, ppid, pgrp, ...
+    fields = stat_line.rpartition(")")[2].split()
+    pgrp_index = 2
+    if len(fields) <= pgrp_index:
+        return None
+    try:
+        return int(fields[pgrp_index])
+    except ValueError:
        return None
-    with _cf_cookies_lock:
-        return _cf_user_agents.get(_get_base_domain(domain))


-def clear_cf_cookies(domain: str | None = None) -> None:
-    """Clear stored Cloudflare cookies and User-Agent. If domain is None, clear all."""
-    with _cf_cookies_lock:
-        if domain:
-            base_domain = _get_base_domain(domain)
-            _cf_cookies.pop(base_domain, None)
-            _cf_user_agents.pop(base_domain, None)
-        else:
-            _cf_cookies.clear()
-            _cf_user_agents.clear()
+def _find_browser_processes() -> list[tuple[int, int, str]]:
+    """Return (pid, pgid, cmdline) for every browser-ish process visible in /proc."""
+    found: list[tuple[int, int, str]] = []
+    try:
+        entries = list(_PROC_ROOT.iterdir())
+    except OSError as e:
+        logger.debug("Could not list %s: %s", _PROC_ROOT, e)
+        return found
+
+    for entry in entries:
+        if not entry.name.isdigit():
+            continue
+        cmdline = _read_process_cmdline(entry)
+        if not cmdline or not any(name in cmdline for name in _BROWSER_PROCESS_PATTERNS):
+            continue
+        pgid = _read_process_pgid(entry)
+        if pgid is None:
+            continue
+        found.append((int(entry.name), pgid, cmdline))
+    return found
+
+
+def _kill_process(pid: int, cmdline: str) -> bool:
+    """SIGKILL one process, reporting whether it was actually signalled."""
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except ProcessLookupError:
+        return False
+    except OSError as e:
+        logger.warning("Failed to kill pid %s: %s", pid, e)
+        return False
+    logger.debug("Killed leftover process %s: %s", pid, cmdline[:120])
+    return True


 def _cleanup_orphan_processes() -> int:
-    """Kill orphan Chrome/Xvfb/ffmpeg processes. Only runs in Docker mode."""
+    """Kill leftover Chrome/Xvfb/ffmpeg processes. Only runs in Docker mode.
+
+    Scoped to this bypass session's process group plus groups whose leader has died.
+    A container-wide sweep (the old `pkill -9 -f chrome`) also matched the browsers a
+    concurrently running bypass was still driving, so with MAX_CONCURRENT_DOWNLOADS > 1
+    every worker that started a solve killed the others' browsers (#1231).
+    """
    if not env.DOCKERMODE:
        return 0

    _stop_ffmpeg_recording()

-    processes_to_kill = ["chrome", "chromium", "Xvfb", "ffmpeg"]
-    total_killed = 0
-
-    logger.debug("Checking for orphan processes...")
+    logger.debug("Checking for leftover browser processes...")
    logger.log_resource_usage()

-    if _PGREP_PATH is None or _PKILL_PATH is None:
-        logger.warning("Skipping orphan-process cleanup because pgrep/pkill are unavailable")
+    if not _PROC_ROOT.is_dir():
+        logger.warning("Skipping browser-process cleanup because %s is unavailable", _PROC_ROOT)
        return 0

-    for proc_name in processes_to_kill:
-        try:
-            result = subprocess.run(
-                [_PGREP_PATH, "-f", proc_name],
-                capture_output=True,
-                check=False,
-                text=True,
-                timeout=5,
-            )
-            if result.returncode != 0 or not result.stdout.strip():
-                continue
+    own_pid = os.getpid()
+    own_pgid = os.getpgrp()
+    total_killed = 0

-            pids = result.stdout.strip().split("\n")
-            count = len(pids)
-            logger.info("Found %s orphan %s process(es), killing...", count, proc_name)
-
-            kill_result = subprocess.run(
-                [_PKILL_PATH, "-9", "-f", proc_name],
-                capture_output=True,
-                check=False,
-                timeout=5,
-            )
-            if kill_result.returncode == 0:
-                total_killed += count
-            else:
-                logger.warning("pkill for %s returned %s", proc_name, kill_result.returncode)
-
-        except subprocess.TimeoutExpired:
-            logger.warning("Timeout while checking for %s processes", proc_name)
-        except _SUBPROCESS_OPERATION_ERRORS as e:
-            logger.debug("Error checking for %s processes: %s", proc_name, e)
+    for pid, pgid, cmdline in _find_browser_processes():
+        if pid == own_pid:
+            continue
+        # Another live process group means another bypass session: its browsers are in
+        # use, not orphans. Only our own group and groups whose leader is gone (a helper
+        # that died or was killed, leaving its browser behind) are ours to clean up.
+        if pgid != own_pgid and (_PROC_ROOT / str(pgid)).exists():
+            logger.debug("Leaving pid %s to its live bypass session (pgid %s)", pid, pgid)
+            continue
+        if _kill_process(pid, cmdline):
+            total_killed += 1

    if total_killed > 0:
        time.sleep(1)
-        logger.info("Cleaned up %s orphan process(es)", total_killed)
+        logger.info("Cleaned up %s leftover browser process(es)", total_killed)
        logger.log_resource_usage()
    else:
-        logger.debug("No orphan processes found")
+        logger.debug("No leftover browser processes found")

    return total_killed

@@ -894,23 +844,25 @@ def _run_bypass_in_current_process(url: str, retry: int, cancel_flag: Event | No
            if driver:
                await _close_cdp_driver(driver)

-    if os.environ.get(_BYPASS_CHILD_ENV) == "1":
-        return asyncio.run(_run_bypass())
-    return _CDP_WORKER.run(_run_bypass())
+    # Bound the wait: this 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.
+    #
+    # The helper goes through the worker too, rather than asyncio.run: that owns a loop for
+    # one call and closes it on the way out, so a helper serving many requests would build
+    # and tear down a loop per bypass and would carry no deadline of its own. The worker's
+    # loop lives in a thread, outlives any single bypass, and cancels the coroutine when the
+    # deadline passes.
+    timeout = (
+        _CHILD_BYPASS_TIMEOUT_SECONDS
+        if os.environ.get(_BYPASS_CHILD_ENV) == "1"
+        else _IN_PROCESS_BYPASS_TIMEOUT_SECONDS
+    )
+    return _CDP_WORKER.run(_run_bypass(), timeout=timeout)


 def _store_child_bypass_state(payload: dict[str, Any]) -> None:
-    cookies = payload.get("cookies")
-    if isinstance(cookies, dict):
-        with _cf_cookies_lock:
-            _cf_cookies.update(cookies)
-
-    user_agents = payload.get("user_agents")
-    if isinstance(user_agents, dict):
-        with _cf_cookies_lock:
-            _cf_user_agents.update(
-                {str(domain): str(agent) for domain, agent in user_agents.items()}
-            )
+    import_store(payload.get("cookies"), payload.get("user_agents"))


 def _prepare_child_browser_env(env_vars: dict[str, str]) -> dict[str, str]:
@@ -933,6 +885,228 @@ def _prepare_child_browser_env(env_vars: dict[str, str]) -> dict[str, str]:
    return env_vars


+def _terminate_helper_session(proc: subprocess.Popen[str]) -> None:
+    """Kill the bypass helper and every process it spawned.
+
+    start_new_session makes the helper a session leader, so its pid doubles as the
+    process-group id of the browser tree underneath it and one killpg reaches all of it.
+    """
+    if hasattr(os, "killpg"):
+        with suppress(OSError):
+            os.killpg(proc.pid, signal.SIGKILL)
+    with suppress(OSError):
+        proc.kill()
+    with suppress(OSError, subprocess.SubprocessError):
+        proc.wait(timeout=5)
+
+
+def _part_path(result_path: Path) -> Path:
+    """Where the helper stages a result before renaming it into place."""
+    return result_path.with_name(result_path.name + ".part")
+
+
+class _BypassHelper:
+    """The helper subprocess that runs the bypasses, kept alive across them.
+
+    Spawning it costs about 4.5 seconds of interpreter start and imports before any work
+    begins, paid on every protected request - and a single search issues several. What it
+    keeps is the process, not the browser: each bypass still starts and closes its own
+    Chrome, so nothing accumulates between requests.
+
+    Protocol: one JSON request per line on stdin, answered by writing the result file that
+    request named. stdout and stderr stay attached to the parent's, so helper logs keep
+    showing up in `docker logs` as before.
+
+    Only one request is ever in flight - get() serializes every bypass behind LOCKED. The
+    lock here is for the idle reaper, which runs on a timer thread.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._proc: subprocess.Popen[str] | None = None
+        self._last_used = 0.0
+        self._idle_timer: threading.Timer | None = None
+
+    def _idle_timeout(self) -> float:
+        return _coerce_non_negative_float(
+            app_config.get("BYPASS_BROWSER_IDLE_TIMEOUT", _HELPER_IDLE_TIMEOUT_DEFAULT),
+            _HELPER_IDLE_TIMEOUT_DEFAULT,
+        )
+
+    def _spawn(self) -> subprocess.Popen[str]:
+        env_vars = os.environ.copy()
+        env_vars[_BYPASS_CHILD_ENV] = "1"
+        env_vars = _prepare_child_browser_env(env_vars)
+        return subprocess.Popen(
+            [sys.executable, "-m", "shelfmark.bypass.internal_bypasser"],
+            stdin=subprocess.PIPE,
+            text=True,
+            env=env_vars,
+            # Give the helper its own session: Chrome, Xvfb and ffmpeg inherit its process
+            # group, which is what lets the cleanup sweep tell this helper's browsers apart
+            # from a concurrent worker's (#1231) and lets us kill the whole tree below.
+            start_new_session=True,
+        )
+
+    def _running(self) -> subprocess.Popen[str] | None:
+        proc = self._proc
+        if proc is None:
+            return None
+        if proc.poll() is not None or proc.stdin is None or proc.stdin.closed:
+            return None
+        return proc
+
+    def _ensure_running(self) -> subprocess.Popen[str]:
+        proc = self._running()
+        if proc is not None:
+            return proc
+        if self._proc is not None:
+            logger.info("Bypass helper exited (code %s), starting a new one", self._proc.returncode)
+            self._discard()
+        self._proc = self._spawn()
+        return self._proc
+
+    def _discard(self, *, wait_for_exit: bool = True) -> None:
+        """Stop the helper and forget it.
+
+        `wait_for_exit` belongs to a helper that could still act on the closed pipe: an
+        idle one is sitting in its stdin read, notices EOF and exits on its own. A helper
+        dropped mid-bypass is blocked inside the solve and will not return to that read,
+        so the grace cannot end in anything but the kill below - and the caller waiting it
+        out is a user cancelling a download, holding LOCKED while every other bypass in
+        the worker queues behind them.
+        """
+        proc = self._proc
+        self._proc = None
+        if proc is None:
+            return
+
+        # Closing stdin ends the helper's request loop, so an idle helper gets to exit on
+        # its own. One mid-bypass cannot answer, and is killed below.
+        with suppress(OSError):
+            if proc.stdin is not None and not proc.stdin.closed:
+                proc.stdin.close()
+        if wait_for_exit:
+            try:
+                proc.wait(timeout=_HELPER_SHUTDOWN_GRACE_SECONDS)
+            except subprocess.TimeoutExpired:
+                logger.warning("Bypass helper did not exit on request, killing its session")
+
+        # Tear the session down either way: a helper killed mid-bypass leaves its Chrome
+        # and Xvfb running, and those leftovers are what made the next worker's browser
+        # fail to start. Harmless once it has already exited.
+        _terminate_helper_session(proc)
+
+    def _cancel_idle_timer(self) -> None:
+        if self._idle_timer is not None:
+            self._idle_timer.cancel()
+            self._idle_timer = None
+
+    def _arm_idle_timer(self) -> None:
+        self._cancel_idle_timer()
+        timeout = self._idle_timeout()
+        if self._proc is None or timeout <= 0:
+            return
+        timer = threading.Timer(timeout, self._reap_if_idle)
+        timer.daemon = True
+        self._idle_timer = timer
+        timer.start()
+
+    def _reap_if_idle(self) -> None:
+        with self._lock:
+            if self._proc is None:
+                return
+            idle_for = time.monotonic() - self._last_used
+            timeout = self._idle_timeout()
+            if idle_for < timeout:
+                # A bypass started while this timer was waiting for the lock.
+                self._arm_idle_timer()
+                return
+            logger.info("Closing idle bypass helper after %.0fs without work", idle_for)
+            self._discard()
+
+    def run(
+        self,
+        payload: dict[str, Any],
+        timeout: float,
+        cancel_flag: Event | None,
+    ) -> dict[str, Any]:
+        with self._lock:
+            self._cancel_idle_timer()
+            try:
+                return self._exchange(payload, timeout, cancel_flag)
+            finally:
+                self._last_used = time.monotonic()
+                self._arm_idle_timer()
+
+    def _exchange(
+        self,
+        payload: dict[str, Any],
+        timeout: float,
+        cancel_flag: Event | None,
+    ) -> dict[str, Any]:
+        request_line = json.dumps(payload) + "\n"
+        proc = self._ensure_running()
+        try:
+            self._write(proc, request_line)
+        except OSError as exc:
+            # A live helper can die between the liveness check and the write, so one retry
+            # on a fresh process. A fresh one failing here is a real failure.
+            logger.info("Bypass helper closed its pipe (%s), retrying on a new one", exc)
+            # Nothing to ask of a helper we cannot write to: its read end is already gone.
+            self._discard(wait_for_exit=False)
+            proc = self._ensure_running()
+            self._write(proc, request_line)
+
+        return self._await_result(proc, Path(str(payload["result_path"])), timeout, cancel_flag)
+
+    def _write(self, proc: subprocess.Popen[str], request_line: str) -> None:
+        if proc.stdin is None:
+            msg = "Bypass helper has no stdin pipe"
+            raise OSError(msg)
+        proc.stdin.write(request_line)
+        proc.stdin.flush()
+
+    def _await_result(
+        self,
+        proc: subprocess.Popen[str],
+        result_path: Path,
+        timeout: float,
+        cancel_flag: Event | None,
+    ) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        try:
+            while not result_path.exists():
+                if proc.poll() is not None:
+                    returncode = proc.returncode
+                    self._discard(wait_for_exit=False)
+                    msg = f"Internal bypasser helper exited without a result (code {returncode})"
+                    raise RuntimeError(msg)
+                if cancel_flag is not None and cancel_flag.is_set():
+                    # The helper is mid-bypass and cannot be told to stop, so it goes.
+                    self._discard(wait_for_exit=False)
+                    _check_cancellation(cancel_flag, "Bypass cancelled while waiting for helper")
+                if time.monotonic() >= deadline:
+                    self._discard(wait_for_exit=False)
+                    msg = "Internal bypasser helper process timed out"
+                    raise TimeoutError(msg)
+                time.sleep(_HELPER_RESULT_POLL_SECONDS)
+
+            return json.loads(result_path.read_text(encoding="utf-8"))
+        finally:
+            # Every way out of here is final for this request: either the answer has been
+            # read, or the helper that would have written it has just been killed. Nothing
+            # will write these paths afterwards and nothing will come looking for them, so
+            # they are cleaned on the failure paths too - otherwise every cancelled
+            # download and every wedged solve leaves one behind for the container's life.
+            for path in (result_path, _part_path(result_path)):
+                with suppress(OSError):
+                    path.unlink()
+
+
+_BYPASS_HELPER = _BypassHelper()
+
+
 def _get_via_subprocess(url: str, retry: int, cancel_flag: Event | None = None) -> str:
    """Run the browser bypass in a helper process isolated from gunicorn/gevent."""
    _check_cancellation(cancel_flag, "Bypass cancelled before helper process")
@@ -943,39 +1117,15 @@ def _get_via_subprocess(url: str, retry: int, cancel_flag: Event | None = None)
    # freshly spawned helper would otherwise pre-resolve AA hostnames against the system
    # resolver - which may be blocked or hijacked by the user's ISP. Pass the parent's
    # active DNS config so the helper mirrors it (e.g. DoH) when building Chrome's host
-    # resolver rules.
+    # resolver rules. Sent with every request, not just at spawn, because a helper outlives
+    # changes the parent makes to its DNS provider.
    payload = {
        "url": url,
        "retry": retry,
        "result_path": str(result_path),
        "dns_config": network.get_dns_config(),
    }
-    env_vars = os.environ.copy()
-    env_vars[_BYPASS_CHILD_ENV] = "1"
-    env_vars = _prepare_child_browser_env(env_vars)
-
-    proc = subprocess.Popen(
-        [sys.executable, "-m", "shelfmark.bypass.internal_bypasser"],
-        stdin=subprocess.PIPE,
-        text=True,
-        env=env_vars,
-    )
-    try:
-        proc.communicate(json.dumps(payload), timeout=_BYPASS_SUBPROCESS_TIMEOUT_SECONDS)
-    except subprocess.TimeoutExpired:
-        proc.kill()
-        proc.wait()
-        msg = "Internal bypasser helper process timed out"
-        raise TimeoutError(msg) from None
-
-    try:
-        result = json.loads(result_path.read_text())
-    except FileNotFoundError as exc:
-        msg = f"Internal bypasser helper exited without a result (code {proc.returncode})"
-        raise RuntimeError(msg) from exc
-    finally:
-        with suppress(OSError):
-            result_path.unlink()
+    result = _BYPASS_HELPER.run(payload, _BYPASS_SUBPROCESS_TIMEOUT_SECONDS, cancel_flag)

    if not isinstance(result, dict):
        msg = "Internal bypasser helper returned an invalid result"
@@ -1250,12 +1400,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:
@@ -1288,33 +1462,88 @@ def get_bypassed_page(
    return response_html


+def _dns_fingerprint(dns_config: dict[str, Any]) -> tuple[str, tuple[str, ...], bool]:
+    """Reduce a DNS config to what has to match for two of them to be the same one."""
+    provider = str(dns_config.get("provider") or "").strip().lower()
+    servers = dns_config.get("servers") if provider == "manual" else None
+    server_list = tuple(str(server) for server in servers) if isinstance(servers, list) else ()
+    return (provider, server_list, bool(dns_config.get("doh_enabled")))
+
+
 def _apply_parent_dns_config(dns_config: dict[str, Any]) -> None:
    """Mirror the parent process's active DNS provider in this helper subprocess.

-    DNS state is in-memory only, so a fresh helper defaults to system DNS and would
-    pre-resolve AA hostnames (for Chrome's --host-resolver-rules) against a resolver
-    that may be blocked/hijacked. Re-applying the parent's provider keeps the helper on
-    the same DoH/custom resolver the parent already validated.
+    DNS state is in-memory only, so a helper left to itself would pre-resolve AA hostnames
+    (for Chrome's --host-resolver-rules) against a resolver that may be blocked or
+    hijacked. Re-applying the parent's provider keeps the helper on the same DoH/custom
+    resolver the parent already validated.
+
+    Compared against what this process is *actually* resolving through, rather than
+    against the last config it happened to be handed. The helper now outlives the request,
+    so it has to be able to travel back to auto as well as away from it - which a user
+    flipping CUSTOM_DNS in settings does live, without a restart - and asking the network
+    module what it is doing beats keeping a second, drifting copy of that answer here.
    """
-    provider = str(dns_config.get("provider") or "").strip().lower()
-    # "auto" means the parent has not rotated off system DNS yet, so the helper's own
-    # default initialization already matches it - nothing to override.
-    if not provider or provider == "auto":
+    wanted = _dns_fingerprint(dns_config)
+    provider, servers, use_doh = wanted
+    if not provider:
        return
-    manual_servers = dns_config.get("servers") if provider == "manual" else None
+    # set_dns_provider() rebuilds the resolvers, so it is worth doing only on a real change.
+    if wanted == _dns_fingerprint(network.get_dns_config()):
+        return
+
    try:
-        network.set_dns_provider(
-            provider,
-            manual_servers,
-            use_doh=bool(dns_config.get("doh_enabled")),
-        )
+        network.set_dns_provider(provider, list(servers) or None, use_doh=use_doh)
    except (OSError, RuntimeError, ValueError) as exc:
        logger.warning("Could not apply parent DNS config (%s): %s", provider, exc)


-def _run_child_process() -> int:
-    """CLI entrypoint used by the Docker helper subprocess."""
-    request = json.loads(sys.stdin.read() or "{}")
+def _terminate_own_session() -> None:
+    """SIGKILL this process and every process it spawned, browser included."""
+    if hasattr(os, "killpg") and os.getpgrp() == os.getpid():
+        with suppress(OSError):
+            os.killpg(os.getpgrp(), signal.SIGKILL)
+    # A thread cannot end the process any other way; sys.exit would only end itself.
+    os._exit(1)
+
+
+def _watch_parent_process(original_ppid: int, interval: float) -> None:
+    """Take the browser down with us once the app process that spawned us is gone.
+
+    Cleanup only reclaims process groups whose leader has died, so a helper that outlives
+    its parent (worker restart, OOM kill) would sit there holding a browser that no later
+    bypass is allowed to touch.
+    """
+    while os.getppid() == original_ppid:
+        time.sleep(interval)
+    logger.warning("Bypass helper lost its parent process; taking the browser down")
+    _terminate_own_session()
+
+
+def _start_parent_watchdog() -> None:
+    """Watch the spawning process in the background for the life of this helper."""
+    threading.Thread(
+        target=_watch_parent_process,
+        args=(os.getppid(), _PARENT_WATCHDOG_INTERVAL_SECONDS),
+        daemon=True,
+        name="BypassParentWatchdog",
+    ).start()
+
+
+def _publish_result(result_path: Path, payload: dict[str, Any]) -> None:
+    """Write the result file atomically.
+
+    The parent decides the request is answered the moment this path exists, so it must
+    never observe a half-written file. Rename within the same directory is atomic.
+    """
+    tmp_path = _part_path(result_path)
+    tmp_path.write_text(json.dumps(payload), encoding="utf-8")
+    tmp_path.replace(result_path)
+
+
+def _handle_child_request(request_line: str) -> int:
+    """Answer one request from the parent."""
+    request = json.loads(request_line or "{}")
    result_path = Path(str(request["result_path"]))
    url = str(request["url"])
    retry = _coerce_positive_int(
@@ -1325,15 +1554,25 @@ def _run_child_process() -> int:
    if isinstance(dns_config, dict):
        _apply_parent_dns_config(dns_config)

+    # The parent owns the cookie store; this process only solves. Starting each request
+    # from an empty store is what a helper spawned per request gave for free, and losing
+    # it is what let clearance the parent had deliberately purged for some *other* host
+    # survive here and get merged back over the parent's copy by the export below - the
+    # dead-cookie resurrection that http.py's _redirect_loop_handoff purges to avoid.
+    # Nothing is lost by dropping it: get() below re-checks cached cookies, and the
+    # parent already ran that same check against a store that is a superset of this one.
+    clear_cf_cookies()
+
    try:
        html = get(url, retry=retry)
+        cookies, user_agents = export_store()
        payload = {
            "ok": True,
            "html": html,
-            "cookies": _cf_cookies,
-            "user_agents": _cf_user_agents,
+            "cookies": cookies,
+            "user_agents": user_agents,
        }
-        result_path.write_text(json.dumps(payload), encoding="utf-8")
+        _publish_result(result_path, payload)
    except Exception as exc:  # noqa: BLE001 - helper boundary must serialize failures.
        payload = {
            "ok": False,
@@ -1341,10 +1580,30 @@ def _run_child_process() -> int:
            "error": str(exc),
            "traceback": traceback.format_exc(),
        }
-        result_path.write_text(json.dumps(payload), encoding="utf-8")
+        _publish_result(result_path, payload)
        return 1
    return 0


+def _run_child_process() -> int:
+    """CLI entrypoint used by the Docker helper subprocess.
+
+    Serves one request per line of stdin until the parent closes the pipe, so a burst of
+    protected requests - a single search is several - pays the interpreter start and imports
+    once instead of per request. Each bypass still gets its own browser, closed before the
+    answer is published.
+    """
+    exit_code = 0
+    for line in sys.stdin:
+        request_line = line.strip()
+        if not request_line:
+            continue
+        exit_code = _handle_child_request(request_line)
+    return exit_code
+
+
 if __name__ == "__main__":
+    # Started here rather than in _run_child_process() so it only ever watches a real
+    # spawned helper, never a test or an embedded call.
+    _start_parent_watchdog()
    raise SystemExit(_run_child_process())
@@ -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]],
@@ -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",
@@ -757,7 +766,10 @@ def _on_save_downloads(values: dict[str, Any]) -> dict[str, Any]:
            }

    # Audiobooks are always folder output.
-    if effective.get("FILE_ORGANIZATION_AUDIOBOOK", "rename") == "rename":
+    if effective.get("FILE_ORGANIZATION_AUDIOBOOK", "rename") in {
+        "rename",
+        "rename_and_group",
+    }:
        template = effective.get("TEMPLATE_AUDIOBOOK_RENAME", "")
        if _contains_path_separators(template):
            return {
@@ -1012,7 +1024,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 +1043,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."
@@ -1285,6 +1297,11 @@ def download_settings() -> list[SettingsField]:
                    "label": "Rename and Organize",
                    "description": "Create folders and rename files using a template. Recommended for Audiobookshelf. Do not use with ingest folders.",
                },
+                {
+                    "value": "rename_and_group",
+                    "label": "Rename and Group",
+                    "description": "Rename single-file downloads; keep multi-file downloads grouped in their source folder. Do not use with ingest folders.",
+                },
            ],
            default="rename",
            universal_only=True,
@@ -1294,7 +1311,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. "
@@ -1303,7 +1320,10 @@ def download_settings() -> list[SettingsField]:
            ),
            default="{Author} - {Title}",
            placeholder="{Author} - {Title}{ - Part }{PartNumber}",
-            show_when={"field": "FILE_ORGANIZATION_AUDIOBOOK", "value": "rename"},
+            show_when={
+                "field": "FILE_ORGANIZATION_AUDIOBOOK",
+                "value": ["rename", "rename_and_group"],
+            },
            universal_only=True,
        ),
        # Organize mode template - folders allowed
@@ -1311,7 +1331,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."
@@ -1646,6 +1666,19 @@ def cloudflare_bypass_settings() -> list[SettingsField]:
            requires_restart=True,
            show_when={"field": "USING_EXTERNAL_BYPASSER", "value": True},
        ),
+        NumberField(
+            key="BYPASS_BROWSER_IDLE_TIMEOUT",
+            label="Bypasser Idle Timeout (seconds)",
+            description=(
+                "How long the bypass helper process may sit unused before it is shut down. "
+                "Higher keeps more searches fast, lower frees memory sooner."
+            ),
+            default=180,
+            min_value=30,
+            max_value=3600,
+            requires_restart=True,
+            show_when={"field": "USING_EXTERNAL_BYPASSER", "value": False},
+        ),
    ]


@@ -1764,6 +1797,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)
@@ -119,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()
@@ -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,717 @@
+"""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.clients.torrent_utils import (
+    DebridMagnet,
+    DebridUpload,
+    resolve_debrid_upload,
+)
+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:
+        """Send a torrent to AllDebrid and return the magnet ID.
+
+        Accepts a magnet link, a .torrent URL, or an indexer proxy URL; anything
+        that is not already a magnet is resolved first, since an HTTP URL posted
+        as a magnet is rejected rather than downloaded (#1250).
+        """
+        if not self._api_key:
+            msg = "AllDebrid API key is not configured"
+            raise RuntimeError(msg)
+
+        try:
+            upload = resolve_debrid_upload(url, expected_hash=expected_hash)
+            info = self._send_torrent(upload)
+
+            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 add torrent to AllDebrid")
+            raise
+
+        else:
+            return magnet_id
+
+    def _send_torrent(self, upload: DebridUpload) -> dict[str, Any]:
+        """Hand the torrent to AllDebrid, as a magnet or as a file upload.
+
+        Both endpoints answer with the same envelope and the same per-entry
+        error shape, differing only in which key holds the entries.
+        """
+        if isinstance(upload, DebridMagnet):
+            api_url = f"{_API_BASE}/magnet/upload"
+            entries_key = "magnets"
+            resp = requests.post(
+                api_url,
+                headers=self._auth_headers(),
+                data={"magnets[]": upload.magnet_url},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(api_url),
+            )
+        else:
+            api_url = f"{_API_BASE}/magnet/upload/file"
+            entries_key = "files"
+            resp = requests.post(
+                api_url,
+                headers=self._auth_headers(),
+                files={
+                    "files[]": (
+                        "release.torrent",
+                        upload.torrent_data,
+                        "application/x-bittorrent",
+                    )
+                },
+                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)
+
+        entries = data.get("data", {}).get(entries_key, [])
+        if not entries:
+            msg = "AllDebrid accepted the upload but returned no torrent"
+            _raise_runtime_error(msg)
+
+        info = entries[0]
+        if info.get("error"):
+            code = info["error"].get("code", "UNKNOWN")
+            msg = f"AllDebrid rejected the torrent: {code}"
+            _raise_runtime_error(msg)
+
+        return info
+
+    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
@@ -284,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,
@@ -813,6 +843,9 @@ class ExternalClientHandler(DownloadHandler, ABC):
                            expected_hash=request.expected_hash,
                            seeding_time_limit=request.seeding_time_limit,
                            ratio_limit=request.ratio_limit,
+                            # rTorrent has no category concept, so its audiobook label
+                            # can only be chosen from the content type (#1235).
+                            content_type=task.content_type,
                        )
                    except Exception as e:
                        if not refresh_attempted:
@@ -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:
@@ -422,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}"
@@ -518,21 +495,22 @@ class QBittorrentClient(DownloadClient):
                    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")
@@ -551,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")

@@ -657,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.

@@ -669,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

@@ -728,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

@@ -789,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,544 @@
+"""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.clients.torrent_utils import (
+    DebridMagnet,
+    DebridUpload,
+    resolve_debrid_upload,
+)
+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:
+        """Send a torrent to Real-Debrid and select all files.
+
+        Accepts a magnet link, a .torrent URL, or an indexer proxy URL; anything
+        that is not already a magnet is resolved first, because Real-Debrid
+        answers a non-magnet body on addMagnet with a bare 404 (#1250).
+        """
+        if not self._api_key:
+            msg = "Real-Debrid API key is not configured"
+            raise RuntimeError(msg)
+
+        try:
+            upload = resolve_debrid_upload(url, expected_hash=expected_hash)
+            data = self._send_torrent(upload)
+
+            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 add torrent to Real-Debrid")
+            raise
+
+        else:
+            return torrent_id
+
+    def _send_torrent(self, upload: DebridUpload) -> dict[str, Any]:
+        """Hand the torrent to Real-Debrid, as a magnet or as a file upload."""
+        if isinstance(upload, DebridMagnet):
+            add_url = f"{_API_BASE}/torrents/addMagnet"
+            resp = requests.post(
+                add_url,
+                headers=self._auth_headers(),
+                data={"magnet": upload.magnet_url},
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(add_url),
+            )
+        else:
+            # addTorrent is a PUT that takes the raw file as the request body,
+            # not a form field: https://api.real-debrid.com/
+            add_url = f"{_API_BASE}/torrents/addTorrent"
+            resp = requests.put(
+                add_url,
+                headers={
+                    **self._auth_headers(),
+                    "Content-Type": "application/x-bittorrent",
+                },
+                data=upload.torrent_data,
+                timeout=_API_TIMEOUT,
+                verify=get_ssl_verify(add_url),
+            )
+
+        resp.raise_for_status()
+        return resp.json()
+
+    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",
+                )
@@ -11,7 +11,12 @@ from urllib.parse import urlparse

 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
-from shelfmark.core.utils import get_hardened_xmlrpc_client
+from shelfmark.core.utils import (
+    get_hardened_xmlrpc_client,
+)
+from shelfmark.core.utils import (
+    is_audiobook as check_audiobook,
+)
 from shelfmark.download.clients import (
    DownloadClient,
    DownloadStatus,
@@ -47,7 +52,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: ...
@@ -167,7 +178,8 @@ class RTorrentClient(DownloadClient):

            commands = []

-            is_audiobook = kwargs.get("content_type") == "audiobook"
+            content_type = kwargs.get("content_type")
+            is_audiobook = check_audiobook(content_type if isinstance(content_type, str) else None)
            default_label = (
                self._audiobook_label if is_audiobook and self._audiobook_label else self._label
            )
@@ -332,12 +344,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",
@@ -351,6 +365,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",
@@ -82,6 +82,60 @@ class TorrentInfo:
        return self


+@dataclass
+class DebridMagnet:
+    """A magnet link, ready to hand to a debrid service as-is."""
+
+    magnet_url: str
+
+
+@dataclass
+class DebridTorrentFile:
+    """Raw .torrent bytes, for a debrid service's file-upload endpoint."""
+
+    torrent_data: bytes
+
+
+# A debrid service takes one or the other, never an indexer page or a proxy URL.
+type DebridUpload = DebridMagnet | DebridTorrentFile
+
+
+def resolve_debrid_upload(url: str, *, expected_hash: str | None = None) -> DebridUpload:
+    """Resolve a release download URL into a magnet link or .torrent bytes.
+
+    Prowlarr hands out a proxy URL, with no magnetUrl and no infoHash, for any
+    indexer that only publishes torrent files - 1337x among them. Posting that
+    URL to a debrid service as if it were a magnet is what produced a bare 404
+    from the service instead of a download (#1250).
+
+    The torrent file is preferred over a synthesized `urn:btih:` magnet because
+    it carries the tracker list, which is how the service finds a swarm that is
+    not already cached. Fetches are shared with the rest of the add path through
+    the torrent fetch cache, so resolving here costs at most one request.
+
+    Raises:
+        ValueError: The URL resolved to neither form, so there is nothing to send.
+
+    """
+    if url.startswith("magnet:"):
+        return DebridMagnet(magnet_url=url)
+
+    info = extract_torrent_info(url, expected_hash=expected_hash)
+
+    if info.is_magnet and info.magnet_url:
+        # The download URL redirected to, or returned, a magnet link.
+        return DebridMagnet(magnet_url=info.magnet_url)
+    if info.torrent_data:
+        return DebridTorrentFile(torrent_data=info.torrent_data)
+    if info.info_hash:
+        # No file to upload, but the hash alone still identifies the torrent.
+        return DebridMagnet(magnet_url=f"magnet:?xt=urn:btih:{info.info_hash}")
+
+    reason = info.fetch_error or "no magnet link, info hash, or torrent file was available"
+    msg = f"Could not resolve a torrent to send from {url[:120]} ({reason})"
+    raise ValueError(msg)
+
+
 def extract_torrent_info(
    url: str,
    *,
@@ -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,36 +4,46 @@ 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

 import requests
 from tqdm import tqdm

-from shelfmark.bypass import BypassCancelledError
+from shelfmark.bypass import BypassCancelledError, cookie_store
+from shelfmark.bypass.challenge import challenge_marker
 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 +64,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 +121,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,
@@ -111,19 +146,13 @@ def get_bypassed_page(


 def get_cf_cookies_for_domain(domain: str) -> dict[str, str]:
-    """Get CF cookies - only available with internal bypasser."""
-    if _is_using_external_bypasser():
-        logger.debug("External bypasser in use, CF cookies not available for %s", domain)
-        return {}
-    return _get_internal_bypasser().get_cf_cookies_for_domain(domain)
+    """Get the clearance cookies won by whichever bypasser solved this domain."""
+    return cookie_store.get_cf_cookies_for_domain(domain)


 def get_cf_user_agent_for_domain(domain: str) -> str | None:
-    """Get CF user agent - only available with internal bypasser."""
-    if _is_using_external_bypasser():
-        logger.debug("External bypasser in use, CF user agent not available for %s", domain)
-        return None
-    return _get_internal_bypasser().get_cf_user_agent_for_domain(domain)
+    """Get the User-Agent that solved this domain's challenge, if one is stored."""
+    return cookie_store.get_cf_user_agent_for_domain(domain)


 def _apply_cf_bypass(url: str, headers: dict) -> dict:
@@ -200,13 +229,66 @@ 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 _response_challenge_marker(response: requests.Response) -> str | None:
+    """The challenge marker in a response body, or None if it carries no challenge.
+
+    Content type is checked first so a JSON or octet-stream error body is never
+    decoded just to be scanned; a missing header is scanned anyway, since an
+    interstitial served without one is still an interstitial.
+    """
+    content_type = response.headers.get("Content-Type", "")
+    if content_type and "html" not in content_type.lower():
+        return None
+    try:
+        return challenge_marker(response.text)
+    except UnicodeDecodeError, ValueError:
+        return None
+
+
+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 +320,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.
@@ -248,59 +333,124 @@ def html_get_page(

    """

+    # Normalise before the closures below capture it: they touch selector.last_failure,
+    # so it must be a concrete selector, not the Optional parameter.
+    selector = selector or network.AAMirrorSelector()
+
    def _result(html: str, response_url: str) -> str | tuple[str, str]:
        if include_response_url:
            return html, response_url
        return html

+    def _fail(reason: str, response_url: str) -> str | tuple[str, str]:
+        """Record why the fetch is giving up, then return the empty result.
+
+        Every give-up path returns an empty page, which is all the caller used to
+        see. Stashing the concrete reason on the shared selector lets the caller
+        surface it (see release_sources.direct_download) rather than reporting the
+        same generic "network restricted or mirrors blocked" for every cause.
+        """
+        selector.last_failure = reason
+        return _result("", response_url)
+
+    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)
+            if result:
+                return _result(result, bypass_url)
+            return _fail(
+                "The protection bypasser returned an empty page — the challenge was "
+                "not solved. Check that FlareSolverr/the CF bypasser is reachable.",
+                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)
+            if isinstance(e, BypassCancelledError):
+                return _fail("The protection bypass was cancelled.", bypass_url)
+            return _fail(f"The protection bypasser failed: {type(e).__name__}: {e}", 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. Applies to
+        either bypasser, since both fill the same store.
+        """
+        hostname = urlparse(target_url).hostname or ""
+        # An empty domain means "clear every host" to the store, so skip the purge
+        # rather than wipe clearance for sites that are working fine.
+        if hostname:
+            cookie_store.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)
    )
-    selector = selector or network.AAMirrorSelector()
    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
+    # Last transport error seen, so the exhausted-retries path can name the real
+    # cause (timeout, connection refused, DNS, ...) instead of a generic message.
+    last_error: Exception | None = None

    for attempt in range(1, retry_limit + 1):
        # Check for cancellation before each attempt
        if cancel_flag and cancel_flag.is_set():
            logger.info("html_get_page cancelled before attempt %s", attempt)
-            return _result("", current_url)
+            return _fail("The request was cancelled.", current_url)

        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 +472,60 @@ 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
+
+                # A 503 still serving a challenge is protection, not a busy origin. The
+                # handshake above has nothing left to echo back, and 503 is in
+                # RETRYABLE_CODES, so without this the request spends every attempt on
+                # the same wall: the bypasser is only ever reached from the 403 branch
+                # and the AA redirect rescues. Gate on the body, not the status, so a
+                # genuine overloaded-origin 503 keeps its retry path.
+                if response.status_code == _HTTP_STATUS_SERVICE_UNAVAILABLE:
+                    marker = _response_challenge_marker(response)
+                    if marker and _bypass_handoff_allowed():
+                        if cookies:
+                            # Challenged while presenting clearance means those cookies
+                            # are dead; same reasoning as the 403 branch below.
+                            logger.debug(
+                                "503 challenge with cookies presented; purging: %s", current_url
+                            )
+                            _purge_clearance(current_url)
+                        logger.info(
+                            "503 challenge detected (%s); switching to bypasser: %s",
+                            marker,
+                            current_url,
+                        )
+                        return _run_bypasser(current_url)
+                    if marker:
+                        logger.debug(
+                            "503 challenge (%s) but no bypasser handoff available: %s",
+                            marker,
+                            current_url,
+                        )
+
                if is_aa_url and response.is_redirect:
                    location = response.headers.get("Location", "")
                    if not location:
@@ -349,13 +547,19 @@ def html_get_page(
                                redirect_host,
                                current_url,
                            )
-                            return _result("", current_url)
+                            return _fail(
+                                f"The configured mirror {current_host} redirected to "
+                                f"{redirect_host}; it may be down or seized. Point MIRROR at "
+                                "a working host or switch to auto mode.",
+                                current_url,
+                            )

                        new_url = _try_rotation(original_url, current_url, selector)
                        if new_url:
                            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
@@ -367,12 +571,47 @@ def html_get_page(
                            redirect_host,
                            current_url,
                        )
-                        return _result("", current_url)
+                        return _fail(
+                            "Every Anna's Archive mirror redirected away to a dead host — "
+                            "all configured mirrors are unreachable.",
+                            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 _fail(
+                            "Anna's Archive is behind a protection challenge (endless "
+                            "redirect loop) and no bypasser is enabled to solve it. Enable "
+                            "FlareSolverr/the CF bypasser.",
+                            current_url,
+                        )
                    current_url = redirect_url
                    continue

@@ -382,8 +621,24 @@ def html_get_page(
                return _result(response.text, response.url)

        except Exception as e:
+            last_error = 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
@@ -393,38 +648,67 @@ def html_get_page(
                        current_url = new_url
                        continue
                    logger.warning("403 error, mirrors exhausted: %s", current_url)
-                    return _result("", current_url)
+                    return _fail(
+                        "Anna's Archive returned 403 (blocked) and all mirrors are exhausted.",
+                        current_url,
+                    )

                if _is_cf_bypass_enabled() and not use_bypasser_now:
                    # Before switching to bypasser, check if cookies have become available
                    # (another concurrent download may have completed bypass and extracted cookies)
                    parsed = urlparse(current_url)
                    fresh_cookies = get_cf_cookies_for_domain(parsed.hostname or "")
-                    if fresh_cookies and not cookies:
-                        # Cookies are now available - retry with cookies before using bypasser
+                    if fresh_cookies and not cookies and attempt < retry_limit:
+                        # Cookies are now available - retry with cookies before using bypasser.
+                        # Guarded on there being a next attempt: `continue` on the last one
+                        # ends the retry loop and abandons the request without ever offering
+                        # the URL to the bypasser, and MAX_RETRY=1 is the supported setting.
+                        # Same reasoning as the bypasser invocation below.
                        logger.debug(
                            "403 but cookies now available - retrying with cookies: %s",
                            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)
+                return _fail(
+                    "Anna's Archive returned 403 (blocked) and no bypasser is enabled "
+                    "to solve the protection challenge.",
+                    current_url,
+                )

            # 404 = Not found
            if status == _HTTP_STATUS_NOT_FOUND:
                logger.warning("404 error: %s", current_url)
-                return _result("", current_url)
+                return _fail(
+                    f"Anna's Archive returned 404 Not Found for {current_url}.", 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
@@ -441,7 +725,16 @@ def html_get_page(
            else:
                logger.exception("Giving up after %s attempts: %s", retry_limit, current_url)

-    return _result("", current_url)
+    if last_error is not None:
+        return _fail(
+            f"Could not reach Anna's Archive after {retry_limit} attempt(s): "
+            f"{type(last_error).__name__}: {last_error}",
+            current_url,
+        )
+    return _fail(
+        "Could not reach Anna's Archive — all mirrors were exhausted without a usable response.",
+        current_url,
+    )


 def download_url(
@@ -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.

@@ -1352,11 +1486,20 @@ class AAMirrorSelector:

    def __init__(self) -> None:
        """Initialize mirror state from the current AA configuration."""
+        # Set by html_get_page at each give-up path so a caller that only sees the
+        # returned empty page can still report *why* the fetch produced nothing
+        # (403, 404, redirect loop, bypasser error, mirrors exhausted, ...) instead
+        # of a blanket "network restricted" guess. None means "no failure recorded".
+        self.last_failure: str | None = None
        self._ensure_fresh_state(reset_attempts=True)

    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 +1512,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 +1559,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
@@ -251,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")
@@ -285,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,
@@ -420,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 {},
@@ -477,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 {},
@@ -645,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(
@@ -882,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:
@@ -929,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
@@ -938,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:
@@ -988,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:
@@ -1023,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())
@@ -205,6 +205,7 @@ def process_folder_output(
        is_torrent=is_torrent,
        preserve_source=preserve_source,
        organization_mode=plan.organization_mode,
+        source_root=source_path,
    )

    if error:
@@ -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


@@ -52,7 +52,7 @@ def get_file_organization(*, is_audiobook: bool) -> str:
    """Get the file organization mode for the content type."""
    key = "FILE_ORGANIZATION_AUDIOBOOK" if is_audiobook else "FILE_ORGANIZATION"
    mode = _config_text(core_config.config.get(key, "rename")).strip().lower()
-    return mode if mode in ("none", "rename", "organize") else "rename"
+    return mode if mode in ("none", "rename", "rename_and_group", "organize") else "rename"


 def get_template(*, is_audiobook: bool, organization_mode: str) -> str:
@@ -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,10 +12,12 @@ from shelfmark.core.naming import (
    assign_part_numbers,
    build_library_path,
    derive_primary_title,
+    normalize_language_code,
    parse_naming_template,
    sanitize_filename,
 )
 from shelfmark.core.utils import is_audiobook as check_audiobook
+from shelfmark.download.archive import is_archive
 from shelfmark.download.fs import (
    atomic_copy,
    atomic_hardlink,
@@ -63,6 +65,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,
    }

@@ -158,6 +161,24 @@ def _transfer_single_file(
    return atomic_move(source_path, dest_path, max_attempts=max_attempts), "move"


+def _group_folder_name(source_root: Path | None) -> str:
+    """Name the folder a grouped multi-file audiobook is transferred into.
+
+    A directory names the group directly. A file cannot hold several book files
+    on its own, so a non-directory source that produced more than one means
+    `collect_staged_files` extracted an archive: the stem is the release name and
+    the suffix is packaging, which is why `Book.zip` groups into `Book/` rather
+    than `Book.zip/` or, worse, not at all.
+    """
+    if source_root is None:
+        return ""
+    if run_blocking_io(source_root.is_dir):
+        return sanitize_filename(source_root.name)
+    if is_archive(source_root):
+        return sanitize_filename(source_root.stem)
+    return ""
+
+
 def transfer_book_files(
    book_files: list[Path],
    destination: Path,
@@ -167,6 +188,7 @@ def transfer_book_files(
    is_torrent: bool,
    preserve_source: bool = False,
    organization_mode: str | None = None,
+    source_root: Path | None = None,
 ) -> tuple[list[Path], str | None, dict[str, int]]:
    """Transfer discovered book files into their final destination layout."""
    if not book_files:
@@ -236,6 +258,13 @@ def transfer_book_files(

        return final_paths, None, op_counts

+    transfer_destination = destination
+    if is_audiobook and len(book_files) > 1 and organization_mode == "rename_and_group":
+        source_folder = _group_folder_name(source_root)
+        if source_folder:
+            transfer_destination = destination / source_folder
+            run_blocking_io(transfer_destination.mkdir, parents=True, exist_ok=True)
+
    for book_file in book_files:
        if len(book_files) == 1 and organization_mode != "none":
            if not task.format:
@@ -254,7 +283,7 @@ def transfer_book_files(
        else:
            filename = book_file.name

-        dest_path = destination / filename
+        dest_path = transfer_destination / filename
        final_path, op = _transfer_single_file(
            book_file,
            dest_path,
@@ -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
@@ -47,6 +48,10 @@ HARDCOVER_PAGE_SIZE = 25  # Hardcover API returns max 25 results per page
 HARDCOVER_MIN_AUTHOR_PARTS = 2
 HARDCOVER_MIN_TYPEAHEAD_QUERY_LENGTH = 2
 HARDCOVER_MAX_SERIES_OPTIONS = 7
+# Hardcover hands out short opaque tokens now ("hc_pat_...") instead of the ~500 char
+# JWTs it used to, so the length floor only applies to keys without that prefix.
+HARDCOVER_API_KEY_PREFIX = "hc_pat_"
+HARDCOVER_BEARER_PREFIX_PATTERN = re.compile(r"^bearer\s+", re.IGNORECASE)
 HARDCOVER_API_KEY_MIN_LENGTH = 100
 HARDCOVER_LIST_URL_PATTERN = re.compile(
    r"^/(?:@([\w.-]+)/)?lists?/([\w-]+)/?$",
@@ -317,6 +322,7 @@ query SearchFieldOptions(
        fields: $fields,
        weights: $weights
    ) {
+        error
        results
    }
 }
@@ -535,13 +541,19 @@ SORT_MAPPING: dict[SortOrder, str] = {
    SortOrder.OLDEST: "release_year:asc",
 }

-# Mapping from abstract search type to Hardcover fields parameter
-SEARCH_TYPE_FIELDS: dict[SearchType, str] = {
-    SearchType.GENERAL: "title,isbns,series_names,author_names,alternative_titles",
-    SearchType.TITLE: "title,alternative_titles",
-    SearchType.AUTHOR: "author_names",
-    # ISBN is handled separately via search_by_isbn()
-}
+# `fields` becomes Typesense's `query_by`, but Hardcover keeps `num_typos` and
+# `query_by_weights` as fixed-length presets per query_type. Passing a different
+# number of fields than the preset expects makes Typesense reject the whole search,
+# complaining that the number of num_typos values does not match the number of
+# query_by fields. So a Book search may only ever narrow to *these five* names --
+# a shorter list is rejected outright rather than searched, and any weights sent
+# alongside must match one-for-one.
+# Weights only bias ranking: a field weighted 0 still matches, so `fields` can no
+# longer restrict which fields a Book query looks at.
+BOOK_SEARCH_FIELDS = "title,alternative_titles,author_names,series_names,isbns"
+BOOK_SEARCH_FIELD_COUNT = 5
+BOOK_TITLE_WEIGHTS = "5,1,0,0,0"
+BOOK_TITLE_AUTHOR_WEIGHTS = "5,1,3,0,0"

 SERIES_SEARCH_FIELDS = "name,books,author_name"
 SERIES_SEARCH_WEIGHTS = "2,1,1"
@@ -549,10 +561,52 @@ SERIES_SEARCH_SORT = "_text_match:desc,readers_count:desc"
 AUTHOR_SUGGESTION_FIELDS = "name,name_personal,alternate_names"
 AUTHOR_SUGGESTION_WEIGHTS = "4,3,2"
 AUTHOR_SUGGESTION_SORT = "_text_match:desc,books_count:desc"
-TITLE_SUGGESTION_FIELDS = "title,alternative_titles"
-TITLE_SUGGESTION_WEIGHTS = "5,2"
+TITLE_SUGGESTION_FIELDS = BOOK_SEARCH_FIELDS
+TITLE_SUGGESTION_WEIGHTS = "5,2,0,0,0"
 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"; the reason only shows up in the sibling `error` field,
+# so every search asks for it. Dropping `sort` from the request is the one shape
+# Hardcover always accepts -- an empty string is a value like any other and has
+# been rejected too -- so retry that way and keep the fallback sticky for a while
+# rather than paying for a doomed request on every search.
+SORT_FALLBACK_TTL = 900.0
+_sort_fallback_until = 0.0
+
+
+def _without_sort(variables: dict[str, Any]) -> dict[str, Any]:
+    """Drop `sort` entirely so Hardcover applies its own default ordering."""
+    return {key: value for key, value in variables.items() if key != "sort"}
+
+
+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 _search_rejection_reason(result: dict[str, Any] | None) -> str:
+    """Return Hardcover's explanation for a rejected search, if it sent one."""
+    if not isinstance(result, dict):
+        return ""
+    root = result.get("search", result)
+    if not isinstance(root, dict):
+        return ""
+    error = root.get("error")
+    return error.strip() if isinstance(error, str) else ""
+

 def _combine_headline_description(headline: str | None, description: str | None) -> str | None:
    """Combine headline (tagline) and description into a single description."""
@@ -620,7 +674,7 @@ def _normalize_series_position(value: Any) -> float | None:
 def _normalize_hardcover_api_key(value: object) -> str:
    """Normalize Hardcover API keys, stripping copied auth-header prefixes."""
    normalized_value = normalize_optional_text(value) or ""
-    return normalized_value.removeprefix("Bearer ").strip()
+    return HARDCOVER_BEARER_PREFIX_PATTERN.sub("", normalized_value.strip()).strip()


 def _normalize_search_text(value: str) -> str:
@@ -986,13 +1040,15 @@ class HardcoverProvider(MetadataProvider):
        """Build search query, fields, and weights based on provided values.

        Returns (query, fields, weights) tuple. Fields/weights are None for general search.
+        A narrowed search still sends all of BOOK_SEARCH_FIELDS -- Hardcover rejects a
+        shorter list outright -- and leans on the weights to rank the wanted field first.
        """
        if author and not title and not series:
            return author, None, None
        if title and not author and not series:
-            return title, "title,alternative_titles", "5,1"
+            return title, BOOK_SEARCH_FIELDS, BOOK_TITLE_WEIGHTS
        if author and title and not series:
-            return f"{title} {author}", "title,alternative_titles,author_names", "5,1,3"
+            return f"{title} {author}", BOOK_SEARCH_FIELDS, BOOK_TITLE_AUTHOR_WEIGHTS
        return default_query, None, None

    def _detect_list_url(self, query: str) -> tuple[str | None, str] | None:
@@ -1200,7 +1256,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 +1487,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,
@@ -2358,6 +2414,7 @@ class HardcoverProvider(MetadataProvider):
            graphql_query = """
            query SearchBooks($query: String!, $limit: Int!, $page: Int!, $sort: String, $fields: String, $weights: String) {
                search(query: $query, query_type: "Book", per_page: $limit, page: $page, sort: $sort, fields: $fields, weights: $weights) {
+                    error
                    results
                }
            }
@@ -2366,6 +2423,7 @@ class HardcoverProvider(MetadataProvider):
            graphql_query = """
            query SearchBooks($query: String!, $limit: Int!, $page: Int!, $sort: String) {
                search(query: $query, query_type: "Book", per_page: $limit, page: $page, sort: $sort) {
+                    error
                    results
                }
            }
@@ -2386,7 +2444,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 +2712,54 @@ 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 = _without_sort(variables)
+            sort = None
+
+        result = self._execute_query(query, variables)
+        if not _search_payload_rejected(result):
+            return result
+
+        reason = _search_rejection_reason(result)
+        if not sort:
+            logger.error(
+                "Hardcover rejected this search (query_type=%s, fields=%s): %s",
+                variables.get("queryType", "Book"),
+                variables.get("fields"),
+                reason or "no error message",
+            )
+            return None
+
+        retry = self._execute_query(query, _without_sort(variables))
+        if _search_payload_rejected(retry):
+            # The sort was not the culprit, so leave sorting alone for other searches.
+            logger.error(
+                "Hardcover rejected this search (query_type=%s, fields=%s) with and without "
+                "a sort order: %s",
+                variables.get("queryType", "Book"),
+                variables.get("fields"),
+                _search_rejection_reason(retry) or reason or "no error message",
+            )
+            return None
+
+        logger.warning(
+            "Hardcover rejected sort '%s' (%s); dropping the sort order from searches for %ss",
+            sort,
+            reason or "no error message",
+            int(SORT_FALLBACK_TTL),
+        )
+        _sort_fallback_until = time.monotonic() + SORT_FALLBACK_TTL
+        return retry
+
    def _parse_search_result(self, item: dict) -> BookMetadata | None:
        """Parse a search result item into BookMetadata."""
        try:
@@ -2917,12 +3023,13 @@ def _test_hardcover_connection(current_values: dict[str, Any] | None = None) ->
        _save_connected_user(None, None)
        return {"success": False, "message": "API key is required"}

-    if key_len < HARDCOVER_API_KEY_MIN_LENGTH:
+    is_prefixed_key = api_key.startswith(HARDCOVER_API_KEY_PREFIX)
+    if not is_prefixed_key and key_len < HARDCOVER_API_KEY_MIN_LENGTH:
        return {
            "success": False,
            "message": (
-                f"API key seems too short ({key_len} chars). "
-                f"Expected {HARDCOVER_API_KEY_MIN_LENGTH}+ chars."
+                f"API key seems too short ({key_len} chars). Expected a key starting "
+                f"with {HARDCOVER_API_KEY_PREFIX} or {HARDCOVER_API_KEY_MIN_LENGTH}+ chars."
            ),
        }

@@ -3029,7 +3136,7 @@ def hardcover_settings() -> list[SettingsField]:
        PasswordField(
            key="HARDCOVER_API_KEY",
            label="API Key",
-            description="Get your API key from hardcover.app/account/api",
+            description="Get your API key from hardcover.app/account/api (starts with hc_pat_)",
            required=True,
        ),
        ActionButton(
@@ -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)
@@ -2,7 +2,7 @@

 import re
 import time
-from urllib.parse import quote
+from urllib.parse import quote, quote_plus

 import requests
 from bs4 import BeautifulSoup
@@ -10,6 +10,7 @@ from bs4 import BeautifulSoup
 from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.download import http as downloader
+from shelfmark.release_sources.audiobookbay.utils import normalize_search_punctuation

 logger = setup_logger(__name__)

@@ -98,8 +99,10 @@ def _encode_search_query(query: str, *, exact_phrase: bool) -> str:
        and not (search_query.startswith('"') and search_query.endswith('"'))
    ):
        search_query = f'"{search_query}"'
-    # Keep ABB-friendly encoding style (spaces as '+') while percent-encoding quotes.
-    return search_query.replace('"', "%22").replace(" ", "+")
+    # Keep ABB's space-as-'+' style, but percent-encode everything else: a bare
+    # '&' would otherwise start a new query parameter, '%' would open an invalid
+    # escape, and a literal '+' would arrive as a space.
+    return quote_plus(search_query)


 def _normalize_result_url(url: str, hostname: str) -> str:
@@ -153,6 +156,9 @@ def search_audiobookbay(

    """
    results = []
+    # ABB matches the stored, untexturized title, so a curly apostrophe reaching
+    # the search returns nothing at all rather than merely ranking worse.
+    query = normalize_search_punctuation(query)
    rate_limit_delay = _coerce_non_negative_float(config.get("ABB_RATE_LIMIT_DELAY", 1.0), 1.0)
    session = requests.Session()

@@ -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,
@@ -22,7 +23,11 @@ from shelfmark.release_sources import (
    register_source,
 )
 from shelfmark.release_sources.audiobookbay import scraper
-from shelfmark.release_sources.audiobookbay.utils import normalize_hostname, parse_size
+from shelfmark.release_sources.audiobookbay.utils import (
+    normalize_hostname,
+    normalize_search_punctuation,
+    parse_size,
+)

 logger = setup_logger(__name__)
 MIN_RELEVANCE_QUERY_WORD_LENGTH = 2
@@ -43,41 +48,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 +89,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:
@@ -260,10 +231,12 @@ class AudiobookBaySource(ReleaseSource):
                        deduped_queries[index + 1].lower(),
                    )

-            # Extract query words for relevance checking
+            # Extract query words for relevance checking. Both sides of the
+            # comparison are punctuation-normalized: scraped titles carry the
+            # typographic forms WordPress renders, queries carry the ASCII ones.
            query_words = {
                word.lower()
-                for word in query_lower.split()
+                for word in normalize_search_punctuation(query_lower).split()
                if len(word) > MIN_RELEVANCE_QUERY_WORD_LENGTH
            }

@@ -272,7 +245,7 @@ class AudiobookBaySource(ReleaseSource):
                try:
                    raw_title = result["title"]
                    title, author = _split_title_and_author(raw_title)
-                    title_for_filter = raw_title.lower()
+                    title_for_filter = normalize_search_punctuation(raw_title).lower()

                    # Basic relevance check: ensure title contains at least one query word
                    # This filters out homepage "Latest" feed items that may leak through
@@ -2,6 +2,63 @@

 import re

+# WordPress texturizes punctuation on output only: a post stored as "The
+# Stranger's Wife" is rendered as "The Stranger’s Wife". ABB's search matches the
+# stored value, so a query carrying the typographic form matches nothing -- and
+# because ABB ANDs its search terms, one such term empties the entire result set.
+# Book metadata and phone keyboards both hand us the typographic forms, so map
+# them back before they reach a search or a title comparison.
+_ASCII_PUNCTUATION = str.maketrans(
+    {
+        # Single quotes
+        "‘": "'",  # left single quotation mark
+        "’": "'",  # right single quotation mark
+        "‚": "'",  # single low-9 quotation mark
+        "‛": "'",  # single high-reversed-9 quotation mark
+        "′": "'",  # prime
+        "´": "'",  # acute accent
+        "`": "'",  # grave accent
+        # Double quotes
+        "“": '"',  # left double quotation mark
+        "”": '"',  # right double quotation mark
+        "„": '"',  # double low-9 quotation mark
+        "‟": '"',  # double high-reversed-9 quotation mark
+        "″": '"',  # double prime
+        # Dashes
+        "‐": "-",  # hyphen
+        "‑": "-",  # non-breaking hyphen
+        "‒": "-",  # figure dash
+        "–": "-",  # en dash
+        "—": "-",  # em dash
+        "―": "-",  # horizontal bar
+        "−": "-",  # minus sign
+        "﹘": "-",  # small em dash
+        "﹣": "-",  # small hyphen-minus
+        "－": "-",  # fullwidth hyphen-minus
+        # Ellipsis
+        "…": "...",  # horizontal ellipsis
+    }
+)
+
+
+def normalize_search_punctuation(text: str) -> str:
+    """Replace typographic punctuation with the ASCII forms ABB stores.
+
+    Each character is mapped individually rather than collapsing runs, so an
+    ASCII "--" is left alone: only characters ABB cannot have stored are
+    rewritten.
+
+    Args:
+        text: A search query, or a scraped title being compared against one.
+
+    Returns:
+        The text with curly quotes, dashes and ellipses mapped to ASCII.
+
+    """
+    if not text:
+        return text
+    return text.translate(_ASCII_PUNCTUATION)
+

 def normalize_hostname(raw: str | None) -> str:
    """Normalize a user-supplied hostname for URL construction.
@@ -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,102 @@ 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 itself."""
+    lowered = html.lower()
+    return any(marker in lowered for marker in _AA_PAGE_MARKERS)
+
+
+def _looks_like_challenge_page(html: str) -> bool:
+    """Whether ``html`` is a protection interstitial rather than the site behind it."""
+    lowered = html.lower()
+    return any(marker in lowered for marker in _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.
+            # html_get_page records the concrete give-up reason on the selector; fall
+            # back to the generic line only if nothing was recorded.
+            detail = getattr(selector, "last_failure", None) or (
+                "Network restricted or mirrors are blocked."
+            )
+            raise SearchUnavailableError(f"Unable to reach download source. {detail}")
+
+        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:
+            # A real, genuinely empty answer from a healthy mirror.
+            return html, None
+        if _looks_like_challenge_page(html):
+            # The bypass did not actually clear the protection - the interstitial is
+            # what came back. Rotating is pointless (every mirror shares the same
+            # protection) and reporting it as an empty result is worse: the user is
+            # told their query found nothing when the search never ran.
+            msg = (
+                "Anna's Archive answered with an unsolved protection challenge. "
+                "Check that the bypasser is reachable and working."
+            )
+            raise SearchUnavailableError(msg)
+        if _looks_like_aa_page(html):
+            # A real AA response in 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 +697,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,11 +747,14 @@ 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."
-        raise SearchUnavailableError(msg)
+        detail = getattr(selector, "last_failure", None) or (
+            "Network restricted or mirrors are blocked."
+        )
+        raise SearchUnavailableError(f"Unable to reach download source. {detail}")

    soup = BeautifulSoup(_html_response_text(html), "html.parser")

@@ -912,6 +978,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)
@@ -7,6 +7,7 @@ from typing import Any, TypedDict

 import requests

+from shelfmark.core.config import config
 from shelfmark.core.logger import setup_logger
 from shelfmark.core.utils import normalize_http_url
 from shelfmark.download.network import get_ssl_verify
@@ -18,6 +19,19 @@ logger = setup_logger(__name__)
 _HTTP_STATUS_UNAUTHORIZED = HTTPStatus.UNAUTHORIZED
 _BOOK_CATEGORY_RANGE_START = 7000
 _BOOK_CATEGORY_RANGE_END = 8000
+
+# Prowlarr's own JSON endpoints (status, indexer list) read local state and answer
+# in milliseconds, so they keep a short timeout. A Torznab search is different: it
+# is Prowlarr proxying a live request to the tracker, which for a Cloudflare-fronted
+# indexer means waiting on FlareSolverr to solve a challenge. A cold challenge
+# routinely runs past a minute, so indexer searches get their own, longer budget.
+DEFAULT_INDEXER_TIMEOUT_SECONDS = 90
+MIN_INDEXER_TIMEOUT_SECONDS = 5
+MAX_INDEXER_TIMEOUT_SECONDS = 300
+
+# Connecting to Prowlarr itself is a LAN hop; only the read is allowed to be slow.
+_CONNECT_TIMEOUT_SECONDS = 10.0
+
 _PROWLARR_CLIENT_ERRORS = (
    requests.exceptions.RequestException,
    OSError,
@@ -27,6 +41,37 @@ _PROWLARR_CLIENT_ERRORS = (
 )


+class ProwlarrSearchError(RuntimeError):
+    """A Torznab search could not be completed.
+
+    Deliberately distinct from an empty result list. Reporting a failed search as
+    "this indexer has nothing" is what turns a slow FlareSolverr challenge into
+    "No releases found for this book" in the UI (#1249), and it also makes the
+    auto-expand retry fire a second request on top of the one still running.
+    """
+
+
+def resolve_indexer_timeout(timeout: object = None) -> int:
+    """Resolve the per-indexer search timeout, falling back to config.
+
+    Out-of-range and unparsable values are clamped rather than rejected: this
+    feeds an HTTP timeout, and a bad setting should not take searching down.
+    """
+    if timeout is None:
+        timeout = config.get("PROWLARR_INDEXER_TIMEOUT", DEFAULT_INDEXER_TIMEOUT_SECONDS)
+
+    resolved = coerce_int_like(timeout)
+    if resolved is None:
+        logger.warning(
+            "Invalid PROWLARR_INDEXER_TIMEOUT %r - using %ss",
+            timeout,
+            DEFAULT_INDEXER_TIMEOUT_SECONDS,
+        )
+        return DEFAULT_INDEXER_TIMEOUT_SECONDS
+
+    return max(MIN_INDEXER_TIMEOUT_SECONDS, min(MAX_INDEXER_TIMEOUT_SECONDS, resolved))
+
+
 class IndexerSeedSettings(TypedDict, total=False):
    ratio_limit: float
    seeding_time_limit_minutes: int
@@ -77,11 +122,23 @@ def _get_field_value(fields: object, name: str) -> object | None:
 class ProwlarrClient:
    """Client for interacting with the Prowlarr API."""

-    def __init__(self, url: str, api_key: str, timeout: int = 30) -> None:
-        """Initialize the API client with base URL, key, and timeout."""
+    def __init__(
+        self, url: str, api_key: str, timeout: int = 30, indexer_timeout: int | None = None
+    ) -> None:
+        """Initialize the API client with base URL, key, and timeouts.
+
+        Args:
+            url: Prowlarr base URL.
+            api_key: Prowlarr API key.
+            timeout: Timeout for Prowlarr's own JSON endpoints.
+            indexer_timeout: Timeout for Torznab searches, which Prowlarr proxies
+                out to the tracker. Defaults to PROWLARR_INDEXER_TIMEOUT.
+
+        """
        self.base_url = normalize_http_url(url)
        self.api_key = api_key
        self.timeout = timeout
+        self.indexer_timeout = resolve_indexer_timeout(indexer_timeout)
        self._session = requests.Session()
        self._session.headers.update(
            {
@@ -189,16 +246,24 @@ class ProwlarrClient:
        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
@@ -299,6 +364,12 @@ class ProwlarrClient:

        This returns richer fields (e.g., author/booktitle, torznab tags like
        FreeLeech) than the JSON /api/v1/search endpoint.
+
+        Raises:
+            ProwlarrSearchError: The search could not be completed. An empty list
+                strictly means the indexer answered with no matches, never that
+                the request timed out or errored.
+
        """
        if not query:
            return []
@@ -321,7 +392,7 @@ class ProwlarrClient:
            response = self._session.get(
                url=url,
                params=params,
-                timeout=self.timeout,
+                timeout=(_CONNECT_TIMEOUT_SECONDS, self.indexer_timeout),
                headers={
                    # Override the session default JSON accept header.
                    "Accept": "application/rss+xml, application/xml;q=0.9, */*;q=0.8"
@@ -339,9 +410,20 @@ class ProwlarrClient:
            for r in results:
                if r.get("indexerId") is None:
                    r["indexerId"] = int(indexer_id)
-        except Exception:
+        except requests.exceptions.Timeout as e:
+            logger.warning(
+                "Prowlarr Torznab search for indexer %s timed out after %ss. An indexer "
+                "behind FlareSolverr can need far longer than that on a cold Cloudflare "
+                "challenge - raise PROWLARR_INDEXER_TIMEOUT if this keeps happening.",
+                indexer_id,
+                self.indexer_timeout,
+            )
+            msg = f"indexer {indexer_id} did not respond within {self.indexer_timeout}s"
+            raise ProwlarrSearchError(msg) from e
+        except Exception as e:
            logger.exception("Prowlarr Torznab search failed for indexer %s", indexer_id)
-            return []
+            msg = f"indexer {indexer_id} search failed: {e}"
+            raise ProwlarrSearchError(msg) from e
        else:
            return results

@@ -34,6 +34,7 @@ from shelfmark.release_sources.prowlarr.api import IndexerSeedSettings, Prowlarr
 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,
@@ -318,11 +319,25 @@ class ProwlarrHandler(ExternalClientHandler):

    @staticmethod
    def _raw_release_matches_task(raw_release: dict[str, Any], task_id: str) -> bool:
-        identities = (
-            normalize_optional_text(raw_release.get("guid")),
-            normalize_optional_text(raw_release.get("infoUrl")),
-        )
-        return any(identity == task_id for identity in identities)
+        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,
@@ -10,12 +10,18 @@ from shelfmark.core.settings_registry import (
    CheckboxField,
    HeadingField,
    MultiSelectField,
+    NumberField,
    PasswordField,
    SettingsField,
    TextField,
    register_settings,
 )
 from shelfmark.core.utils import normalize_http_url
+from shelfmark.release_sources.prowlarr.api import (
+    DEFAULT_INDEXER_TIMEOUT_SECONDS,
+    MAX_INDEXER_TIMEOUT_SECONDS,
+    MIN_INDEXER_TIMEOUT_SECONDS,
+)

 # ==================== Dynamic Options Loaders ====================

@@ -183,6 +189,20 @@ def prowlarr_config_settings() -> list[SettingsField]:
            default=[],
            show_when={"field": "PROWLARR_ENABLED", "value": True},
        ),
+        NumberField(
+            key="PROWLARR_INDEXER_TIMEOUT",
+            label="Indexer Search Timeout (seconds)",
+            description=(
+                "How long to wait for a single indexer to answer a search. Indexers behind "
+                "FlareSolverr can need 90 seconds or more while a cold Cloudflare challenge "
+                "is solved; raise this if searches come back empty and the Prowlarr log "
+                "shows the search still running."
+            ),
+            default=DEFAULT_INDEXER_TIMEOUT_SECONDS,
+            min_value=MIN_INDEXER_TIMEOUT_SECONDS,
+            max_value=MAX_INDEXER_TIMEOUT_SECONDS,
+            show_when={"field": "PROWLARR_ENABLED", "value": True},
+        ),
        CheckboxField(
            key="PROWLARR_AUTO_EXPAND",
            label="Auto-expand search on no results",
@@ -190,6 +210,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,6 +2,7 @@

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

@@ -12,9 +13,11 @@ 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.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,
@@ -28,11 +31,17 @@ from shelfmark.release_sources import (
    ReleaseProtocol,
    ReleaseSource,
    SortOption,
+    SourceUnavailableError,
    register_source,
 )
-from shelfmark.release_sources.prowlarr.api import IndexerSeedSettings, ProwlarrClient
+from shelfmark.release_sources.prowlarr.api import (
+    IndexerSeedSettings,
+    ProwlarrClient,
+    ProwlarrSearchError,
+)
 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,
@@ -44,10 +53,13 @@ _SIZE_UNIT_BASE = 1024
 _TWO_FORMATS = 2
 _PROWLARR_SOURCE_ERRORS = (AttributeError, OSError, RuntimeError, TypeError, ValueError)

-# Errors that can surface from ProwlarrClient.get_indexer_seed_settings(). The
+# Prowlarr indexer priority is 1-50 and lower is preferred; unknown sorts last.
+_UNRANKED_INDEXER_RANK = 51
+
+# Errors that can surface from a ProwlarrClient call that talks to Prowlarr. 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)
+_PROWLARR_REQUEST_ERRORS = (*_PROWLARR_SOURCE_ERRORS, requests.exceptions.RequestException)


 def _raise_timeout_error(message: str) -> NoReturn:
@@ -69,6 +81,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:
@@ -105,59 +229,44 @@ 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

+# The overall budget has to leave room for at least a couple of indexers to spend
+# their full per-indexer timeout, otherwise raising PROWLARR_INDEXER_TIMEOUT for a
+# Cloudflare-fronted tracker just moves the cutoff here. Capped short of the
+# gunicorn worker timeout (300s) so the worker is never the thing that gives up.
+_MAX_SEARCH_BUDGET_SECONDS = 240.0
+
+
+def _search_budget_seconds(indexer_timeout: int) -> float:
+    """Total time one Prowlarr search may spend, scaled to the per-indexer timeout."""
+    return min(
+        _MAX_SEARCH_BUDGET_SECONDS,
+        max(PROWLARR_SEARCH_TIMEOUT_SECONDS, indexer_timeout * 2.0),
+    )
+
+
+@dataclass
+class _IndexerSearchOutcome:
+    """What one pass over the target indexers produced.
+
+    Separates "every indexer answered, none had this book" from "the indexers
+    never answered", which the caller has to tell apart before it decides to
+    auto-expand or to report the search as failed.
+    """
+
+    results: list[dict]
+    attempted: int = 0
+    failed: int = 0
+    last_error: str | None = None
+

 def _extract_format(title: str) -> str | None:
    """Extract ebook/audiobook format from release title (extension, bracketed, or standalone)."""
@@ -201,8 +310,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

@@ -387,8 +497,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)
@@ -465,7 +574,7 @@ def _fetch_indexer_seed_settings(
    """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:
+    except _PROWLARR_REQUEST_ERRORS:
        with _seed_settings_lock:
            fallback = dict(_last_known_seed_settings)
        logger.warning(
@@ -612,6 +721,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(
@@ -816,9 +930,21 @@ class ProwlarrSource(ReleaseSource):

        try:
            auto_expand_enabled = config.get("PROWLARR_AUTO_EXPAND", False)
-            deadline = time.monotonic() + PROWLARR_SEARCH_TIMEOUT_SECONDS
+            search_budget = _search_budget_seconds(client.indexer_timeout)
+            deadline = time.monotonic() + search_budget
+            try:
+                enabled_indexers = client.get_enabled_indexers_detailed(raise_on_error=True)
+            except _PROWLARR_REQUEST_ERRORS as e:
+                # Prowlarr itself is unreachable. Swallowing this leaves the search
+                # with no indexers to query, which the UI renders as "No releases
+                # found for this book" - the same lie as a swallowed timeout (#1249).
+                msg = f"could not reach Prowlarr: {e}"
+                raise SourceUnavailableError(msg) from e
+            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 = (
                _fetch_indexer_seed_settings(client, indexer_ids)
@@ -828,18 +954,16 @@ class ProwlarrSource(ReleaseSource):

            def _check_timeout() -> None:
                if time.monotonic() > deadline:
-                    _raise_timeout_error(
-                        f"Prowlarr search timed out after {int(PROWLARR_SEARCH_TIMEOUT_SECONDS)}s"
-                    )
+                    _raise_timeout_error(f"Prowlarr search timed out after {int(search_budget)}s")

            def search_indexers(
                query: str, cats: list[int] | None, *, enriched_query: str | None = None
-            ) -> list[dict]:
+            ) -> _IndexerSearchOutcome:
                """Search indexers with given categories via Torznab/Newznab."""
-                results: list[dict] = []
+                outcome = _IndexerSearchOutcome(results=[])
                target_indexer_ids = self._get_search_indexer_ids(client, indexer_ids, cats)
                if not target_indexer_ids:
-                    return results
+                    return outcome

                for indexer_id in target_indexer_ids:
                    _check_timeout()
@@ -848,19 +972,31 @@ class ProwlarrSource(ReleaseSource):
                        if indexer_id in enriched_indexer_ids_set and enriched_query
                        else query
                    )
-                    raw = client.torznab_search(
-                        indexer_id=indexer_id,
-                        query=indexer_query,
-                        categories=cats,
-                        search_type="book",
-                    )
+                    outcome.attempted += 1
+                    try:
+                        raw = client.torznab_search(
+                            indexer_id=indexer_id,
+                            query=indexer_query,
+                            categories=cats,
+                            search_type="book",
+                        )
+                    except ProwlarrSearchError as e:
+                        # One unreachable indexer must not sink the others, but it
+                        # is not "no results" either - record it so the caller can
+                        # report a failed search instead of an empty one.
+                        outcome.failed += 1
+                        outcome.last_error = str(e)
+                        continue
                    if raw:
-                        results.extend(raw)
+                        outcome.results.extend(raw)

-                return results
+                return outcome

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

            for idx, variant in enumerate(variants, start=1):
                _check_timeout()
@@ -870,35 +1006,63 @@ class ProwlarrSource(ReleaseSource):
                if len(variants) > 1:
                    logger.debug("Prowlarr query %s/%s: '%s'", idx, len(variants), query)

-                raw_results = search_indexers(
+                outcome = search_indexers(
                    query=query, cats=categories, enriched_query=enriched_query
                )

-                # Auto-expand: if no results with categories and auto-expand enabled, retry without
-                if not raw_results and categories and auto_expand_enabled:
+                # Auto-expand: if no results with categories and auto-expand enabled, retry without.
+                # Only when every indexer actually answered: a failed search says nothing about
+                # whether the category filter is what hid the book, and retrying it stacks a second
+                # request on an indexer that is still busy solving a Cloudflare challenge (#1249).
+                if (
+                    not outcome.results
+                    and not outcome.failed
+                    and categories
+                    and auto_expand_enabled
+                ):
                    _check_timeout()
                    logger.info(
                        "Prowlarr: no results for query '%s' with category filter, auto-expanding search",
                        query,
                    )
-                    raw_results = search_indexers(
+                    expanded = search_indexers(
                        query=query, cats=None, enriched_query=enriched_query
                    )
+                    outcome.results = expanded.results
+                    outcome.attempted += expanded.attempted
+                    outcome.failed += expanded.failed
+                    outcome.last_error = expanded.last_error or outcome.last_error
                    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)
+                attempted_searches += outcome.attempted
+                failed_searches += outcome.failed
+                last_search_error = outcome.last_error or last_search_error
+
+                for r in outcome.results:
+                    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 failed_searches:
+                logger.warning(
+                    "Prowlarr: %s of %s indexer searches failed (%s)",
+                    failed_searches,
+                    attempted_searches,
+                    last_search_error,
+                )
+
+            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()

@@ -917,13 +1081,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)
@@ -940,6 +1110,10 @@ class ProwlarrSource(ReleaseSource):
            else:
                logger.debug("Prowlarr: no results found")

+        except SourceUnavailableError:
+            # Already carries its own message for the caller to surface; the blanket
+            # handler below would turn it back into a silent empty result.
+            raise
        except TimeoutError as e:
            logger.warning("Prowlarr search timed out: %s", e)
            raise
@@ -947,6 +1121,15 @@ class ProwlarrSource(ReleaseSource):
            logger.exception("Prowlarr search failed")
            return []
        else:
+            # An empty list is the UI's "No releases found for this book", so it has
+            # to mean the indexers answered and had nothing. When they failed instead,
+            # say so rather than blaming the book (#1249).
+            if not results and failed_searches:
+                msg = (
+                    f"{failed_searches} of {attempted_searches} indexer searches failed "
+                    f"({last_search_error})"
+                )
+                raise SourceUnavailableError(msg)
            return results

    def is_available(self) -> bool:
@@ -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.1.1",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.3",
-    "knip": "^6.26.0",
-    "oxfmt": "^0.58.0",
-    "oxlint": "^1.73.0",
-    "oxlint-tsgolint": "^0.24.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.2",
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "oxlint-tsgolint": "^7.0.2001",
    "tailwindcss": "^4.2.2",
-    "typescript": "^6.0.3",
-    "vite": "^8.1.4",
+    "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]);
@@ -223,6 +223,14 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
    );
    const showActiveTargetLabel = queryTargets.length > 0 && activeTarget.source !== 'general';

+    // Manual search browses release sources directly, one media type at a time — the
+    // combined ("both") flow doesn't apply. Present a plain, switchable Books/Audiobooks
+    // choice for it, even when combined search is forced on for metadata targets.
+    const isManualTarget = activeTarget?.source === 'manual';
+    const combinedSelectionActive = combinedMode && !isManualTarget;
+    const combinedSelectorLocked = combinedModeLocked && !isManualTarget;
+    const combinedToggleAvailable = !!onCombinedModeChange && !isManualTarget;
+
    useDismiss(isSelectorOpen, [selectorRef], () => setIsSelectorOpen(false));
    useDismiss(isSelectOpen, [selectPanelRef, selectTriggerRef], () => setIsSelectOpen(false));
    useDismiss(isAutocompleteOpen, [autocompletePanelRef, inputRef], () =>
@@ -356,7 +364,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
      contentType,
      activeTarget,
      placeholder,
-      combinedMode,
+      combinedSelectionActive,
    );
    const effectiveInputAriaLabel = activeTarget
      ? `${inputAriaLabel}: ${activeTarget.label}`
@@ -537,7 +545,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(

    let selectorContentTypeLabel = 'audiobooks';
    let selectorIcon = <AudiobookIcon />;
-    if (combinedMode) {
+    if (combinedSelectionActive) {
      selectorContentTypeLabel = 'books and audiobooks';
      selectorIcon = <BothIcon />;
    } else if (contentType === 'ebook') {
@@ -665,7 +673,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                  <div className="max-h-[min(24rem,calc(100vh-8rem))] overflow-y-auto p-3">
                    {showContentTypeSelector && (
                      <div
-                        className={`border-b ${onCombinedModeChange ? 'pb-0' : 'pb-3'}`}
+                        className={`border-b ${combinedToggleAvailable ? 'pb-0' : 'pb-3'}`}
                        style={{ borderColor: 'var(--border-muted)' }}
                      >
                        <div className="flex items-center justify-between px-1 pb-2">
@@ -712,34 +720,38 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                            type="button"
                            onClick={() => handleContentTypeSelect('ebook')}
                            className={`flex items-center gap-2 rounded-xl border px-3 py-2 text-sm font-medium transition-colors ${
-                              contentType === 'ebook' || combinedMode
+                              contentType === 'ebook' || combinedSelectionActive
                                ? 'bg-emerald-600 text-white'
                                : 'hover-surface'
                            }`}
                            style={
-                              contentType === 'ebook' || combinedMode
+                              contentType === 'ebook' || combinedSelectionActive
                                ? { borderColor: 'rgb(16 185 129 / 0.7)' }
                                : { color: 'var(--text)', borderColor: 'var(--border-muted)' }
                            }
                          >
-                            {contentType === 'ebook' || combinedMode ? <CheckIcon /> : <BookIcon />}
+                            {contentType === 'ebook' || combinedSelectionActive ? (
+                              <CheckIcon />
+                            ) : (
+                              <BookIcon />
+                            )}
                            <span>Books</span>
                          </button>
                          <button
                            type="button"
                            onClick={() => handleContentTypeSelect('audiobook')}
                            className={`flex items-center gap-2 rounded-xl border px-3 py-2 text-sm font-medium transition-colors ${
-                              contentType === 'audiobook' || combinedMode
+                              contentType === 'audiobook' || combinedSelectionActive
                                ? 'bg-emerald-600 text-white'
                                : 'hover-surface'
                            }`}
                            style={
-                              contentType === 'audiobook' || combinedMode
+                              contentType === 'audiobook' || combinedSelectionActive
                                ? { borderColor: 'rgb(16 185 129 / 0.7)' }
                                : { color: 'var(--text)', borderColor: 'var(--border-muted)' }
                            }
                          >
-                            {contentType === 'audiobook' || combinedMode ? (
+                            {contentType === 'audiobook' || combinedSelectionActive ? (
                              <CheckIcon />
                            ) : (
                              <AudiobookIcon />
@@ -747,9 +759,9 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                            <span>Audiobooks</span>
                          </button>
                        </div>
-                        {onCombinedModeChange &&
+                        {combinedToggleAvailable &&
                          (() => {
-                            const lineColor = combinedMode
+                            const lineColor = combinedSelectionActive
                              ? 'bg-emerald-500'
                              : 'bg-(--border-muted) group-hover:bg-zinc-400 dark:group-hover:bg-zinc-500';
                            return (
@@ -787,7 +799,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                                    {/* Chain icon centered at bottom */}
                                    <div
                                      className={`relative z-10 mx-auto rounded-full p-1 transition-colors ${
-                                        combinedMode
+                                        combinedSelectionActive
                                          ? 'bg-emerald-600 text-white'
                                          : 'bg-(--bg) text-zinc-400 group-hover:bg-zinc-200 group-hover:text-zinc-600 dark:text-zinc-500 dark:group-hover:bg-zinc-700 dark:group-hover:text-zinc-300'
                                      }`}
@@ -800,7 +812,7 @@ export const SearchBar = forwardRef<SearchBarHandle, SearchBarProps>(
                                        stroke="currentColor"
                                        aria-hidden="true"
                                      >
-                                        {combinedModeLocked ? (
+                                        {combinedSelectorLocked ? (
                                          <path
                                            strokeLinecap="round"
                                            strokeLinejoin="round"
@@ -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):
@@ -317,6 +317,44 @@ class TestSearchAudiobookbay:
        assert "s=%22test+query%22" in requested_url
        assert "cat=undefined%2Cundefined" in requested_url

+    @patch("shelfmark.release_sources.audiobookbay.scraper.downloader.html_get_page")
+    @patch("shelfmark.release_sources.audiobookbay.scraper.config.get")
+    def test_search_audiobookbay_normalizes_curly_apostrophe(self, mock_config_get, mock_html_get):
+        """Test curly apostrophes are searched as the ASCII form ABB stores."""
+        mock_config_get.return_value = 0.0
+        mock_html_get.return_value = (SAMPLE_SEARCH_HTML, "https://audiobookbay.lu/?s=x")
+
+        scraper.search_audiobookbay(
+            "the stranger’s wife",
+            max_pages=1,
+            hostname="audiobookbay.lu",
+        )
+
+        requested_url = mock_html_get.call_args.args[0]
+        assert "s=the+stranger%27s+wife" in requested_url
+        assert "%E2%80%99" not in requested_url
+
+    @patch("shelfmark.release_sources.audiobookbay.scraper.downloader.html_get_page")
+    @patch("shelfmark.release_sources.audiobookbay.scraper.config.get")
+    def test_search_audiobookbay_percent_encodes_reserved_characters(
+        self, mock_config_get, mock_html_get
+    ):
+        """Test reserved characters cannot break out of the search parameter."""
+        mock_config_get.return_value = 0.0
+        mock_html_get.return_value = (SAMPLE_SEARCH_HTML, "https://audiobookbay.lu/?s=x")
+
+        scraper.search_audiobookbay(
+            "sense & sensibility 100% c++",
+            max_pages=1,
+            hostname="audiobookbay.lu",
+        )
+
+        requested_url = mock_html_get.call_args.args[0]
+        assert "s=sense+%26+sensibility+100%25+c%2B%2B" in requested_url
+        # The only surviving '&' introduces the legacy category parameter.
+        assert requested_url.count("&") == 1
+        assert requested_url.endswith("&cat=undefined%2Cundefined")
+
    @patch("shelfmark.release_sources.audiobookbay.scraper.downloader.html_get_page")
    @patch("shelfmark.release_sources.audiobookbay.scraper.config.get")
    def test_search_audiobookbay_always_uses_legacy_category_query(
@@ -306,6 +306,42 @@ class TestAudiobookBaySource:
        assert len(results) == 1
        assert results[0].title == "Test Book by Test Author"

+    @patch("shelfmark.release_sources.audiobookbay.source.scraper.search_audiobookbay")
+    def test_search_relevance_filtering_spans_typographic_punctuation(self, mock_search):
+        """Test an ASCII query still matches the typographic title ABB renders."""
+        mock_search.return_value = [
+            {
+                "title": "The Stranger’s Wife — Anna‑Lou Weatherley",
+                "link": "https://audiobookbay.lu/abss/the-strangers-wife/",
+                "format": "M4B",
+                "size": "259 MB",
+                "language": "English",
+            },
+        ]
+
+        source = AudiobookBaySource()
+        book = BookMetadata(
+            provider="test",
+            provider_id="123",
+            title="Stranger's",
+            authors=["Anna-Lou Weatherley"],
+        )
+        # Every query word carries punctuation, so the result survives only when
+        # both sides of the comparison are normalized.
+        plan = ReleaseSearchPlan(
+            languages=["en"],
+            isbn_candidates=[],
+            author="",
+            title_variants=[ReleaseSearchVariant(title="Stranger's", author="")],
+            grouped_title_variants=[],
+        )
+
+        results = source.search(book, plan, content_type="audiobook")
+
+        assert len(results) == 1
+        # The release keeps the title as ABB rendered it; only matching normalizes.
+        assert results[0].title == "The Stranger’s Wife — Anna‑Lou Weatherley"
+
    @patch("shelfmark.release_sources.audiobookbay.source.scraper.search_audiobookbay")
    def test_search_result_mapping(self, mock_search):
        """Test conversion of scraper results to Release objects."""
@@ -2,7 +2,52 @@
 Tests for AudiobookBay utility functions.
 """

-from shelfmark.release_sources.audiobookbay.utils import parse_size
+from shelfmark.release_sources.audiobookbay.utils import normalize_search_punctuation, parse_size
+
+
+class TestNormalizeSearchPunctuation:
+    """Tests for the normalize_search_punctuation function."""
+
+    def test_curly_apostrophe_becomes_ascii(self):
+        """ABB matches the stored ASCII apostrophe, not the rendered curly one."""
+        assert normalize_search_punctuation("The Stranger’s Wife") == "The Stranger's Wife"
+
+    def test_all_single_quote_variants(self):
+        """Every single-quote lookalike collapses to the ASCII apostrophe."""
+        for variant in ("‘", "’", "‚", "‛", "′", "´", "`"):
+            assert normalize_search_punctuation(f"don{variant}t") == "don't"
+
+    def test_all_double_quote_variants(self):
+        """Every double-quote lookalike collapses to the ASCII double quote."""
+        for variant in ("“", "”", "„", "‟", "″"):
+            assert normalize_search_punctuation(f"{variant}quoted{variant}") == '"quoted"'
+
+    def test_all_dash_variants(self):
+        """Every dash lookalike collapses to the ASCII hyphen."""
+        for variant in ("‐", "‑", "‒", "–", "—", "―", "−", "﹘", "﹣", "－"):
+            assert normalize_search_punctuation(f"anna{variant}lou") == "anna-lou"
+
+    def test_ellipsis_expands_to_three_dots(self):
+        """WordPress renders '...' as a single ellipsis character."""
+        assert normalize_search_punctuation("And Then…") == "And Then..."
+
+    def test_ascii_query_is_unchanged(self):
+        """A query that is already ASCII passes through untouched."""
+        assert normalize_search_punctuation("The Stranger's Wife") == "The Stranger's Wife"
+
+    def test_ascii_dash_runs_are_not_collapsed(self):
+        """Only characters ABB cannot have stored are rewritten."""
+        assert normalize_search_punctuation("Book -- Subtitle") == "Book -- Subtitle"
+
+    def test_other_punctuation_is_preserved(self):
+        """Colons and commas carry search signal and are left alone."""
+        assert normalize_search_punctuation("Weatherley: Book 3, Part 1") == (
+            "Weatherley: Book 3, Part 1"
+        )
+
+    def test_empty_query(self):
+        """An empty query is returned as-is."""
+        assert normalize_search_punctuation("") == ""


 class TestParseSize:
@@ -0,0 +1,222 @@
+"""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.cookie_store as cs
+import shelfmark.bypass.internal_bypasser as ib
+
+
+@pytest.fixture(autouse=True)
+def _clean_cookie_store(monkeypatch):
+    monkeypatch.setattr(cs, "_cf_cookies", {})
+    monkeypatch.setattr(cs, "_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"):
+    cs.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(cs, "_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 cs.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(cs._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"}
@@ -1,5 +1,7 @@
 """Tests for the external bypasser flow."""

+import pytest
+

 class _FakeResponse:
    def __init__(self, payload: dict) -> None:
@@ -55,6 +57,165 @@ def test_fetch_via_bypasser_posts_expected_payload_and_uses_ssl_verify(monkeypat
    ]


+def _stub_solution(monkeypatch, external_bypasser, solution: dict) -> None:
+    """Answer one bypass with `solution`, with config and SSL stubbed out."""
+
+    def fake_get(key, default=""):
+        values = {
+            "EXT_BYPASSER_URL": "https://bypass.example",
+            "EXT_BYPASSER_PATH": "/v1",
+            "EXT_BYPASSER_TIMEOUT": 60000,
+        }
+        return values.get(key, default)
+
+    monkeypatch.setattr(external_bypasser.config, "get", fake_get)
+    monkeypatch.setattr(
+        external_bypasser.requests,
+        "post",
+        lambda *_a, **_k: _FakeResponse({"status": "ok", "solution": solution}),
+    )
+    monkeypatch.setattr(external_bypasser, "get_ssl_verify", lambda _url: False)
+
+
+def test_solved_clearance_is_stored_for_reuse(monkeypatch):
+    """A solve costs tens of seconds of real browser; its clearance must be kept.
+
+    Without this every request paid a 403 plus a full solve, and the file download -
+    which the solver cannot proxy - presented no clearance at all.
+    """
+    import shelfmark.bypass.cookie_store as cookie_store
+    import shelfmark.bypass.external_bypasser as external_bypasser
+
+    monkeypatch.setattr(cookie_store, "_cf_cookies", {})
+    monkeypatch.setattr(cookie_store, "_cf_user_agents", {})
+    _stub_solution(
+        monkeypatch,
+        external_bypasser,
+        {
+            "response": "<html>ok</html>",
+            "userAgent": "Mozilla/5.0 (solver)",
+            "cookies": [
+                {"name": "__ddg1_", "value": "clearance", "domain": ".annas-archive.gl"},
+                {"name": "__ddg2_", "value": "c2", "domain": ".annas-archive.gl"},
+                # Per-check cookies: kept out of the store, same as the internal path.
+                {"name": "__ddg9_", "value": "203.0.113.7", "domain": ".annas-archive.gl"},
+            ],
+        },
+    )
+
+    external_bypasser._fetch_via_bypasser("https://annas-archive.gl/search?q=dune")
+
+    assert cookie_store.get_cf_cookies_for_domain("annas-archive.gl") == {
+        "__ddg1_": "clearance",
+        "__ddg2_": "c2",
+    }
+    # Cloudflare ties clearance to the solving UA, so replaying one without the other fails.
+    assert cookie_store.get_cf_user_agent_for_domain("annas-archive.gl") == "Mozilla/5.0 (solver)"
+
+
+@pytest.mark.parametrize(
+    ("field", "shape"),
+    [
+        # Byparr drives Playwright/camoufox, whose cookies spell it "expires".
+        ("expires", "playwright"),
+        # FlareSolverr assigns driver.get_cookies() - the WebDriver cookie object,
+        # which spells it "expiry". Reading only "expires" made every FlareSolverr
+        # cookie immortal, so dead clearance was replayed forever.
+        ("expiry", "webdriver"),
+    ],
+)
+def test_expired_solution_cookie_is_not_replayed(monkeypatch, field, shape):
+    import time
+
+    import shelfmark.bypass.cookie_store as cookie_store
+    import shelfmark.bypass.external_bypasser as external_bypasser
+
+    monkeypatch.setattr(cookie_store, "_cf_cookies", {})
+    monkeypatch.setattr(cookie_store, "_cf_user_agents", {})
+    _stub_solution(
+        monkeypatch,
+        external_bypasser,
+        {
+            "response": "<html>ok</html>",
+            "cookies": [{"name": "__ddg1_", "value": "dead", field: int(time.time()) - 60}],
+        },
+    )
+
+    external_bypasser._fetch_via_bypasser("https://annas-archive.gl/search?q=dune")
+
+    assert cookie_store.get_cf_cookies_for_domain("annas-archive.gl") == {}, (
+        f"a dead {shape} cookie was kept for replay"
+    )
+
+
+def test_solution_cookie_expiry_is_coerced_not_trusted(monkeypatch):
+    """The solver is not ours; a stringified expiry must be read, not raised on."""
+    import time
+
+    import shelfmark.bypass.cookie_store as cookie_store
+    import shelfmark.bypass.external_bypasser as external_bypasser
+
+    monkeypatch.setattr(cookie_store, "_cf_cookies", {})
+    monkeypatch.setattr(cookie_store, "_cf_user_agents", {})
+    _stub_solution(
+        monkeypatch,
+        external_bypasser,
+        {
+            "response": "<html>ok</html>",
+            "cookies": [
+                {"name": "__ddg1_", "value": "live", "expires": str(int(time.time()) + 3600)},
+                {"name": "__ddg2_", "value": "dead", "expires": str(int(time.time()) - 60)},
+            ],
+        },
+    )
+
+    result = external_bypasser._fetch_via_bypasser("https://annas-archive.gl/search?q=dune")
+
+    assert result == "<html>ok</html>"
+    assert cookie_store.get_cf_cookies_for_domain("annas-archive.gl") == {"__ddg1_": "live"}
+
+
+def test_storing_clearance_can_never_discard_the_solved_page(monkeypatch):
+    """A solve costs ~30s; a surprise in the cookie shape must not throw it away.
+
+    The store call sits inside the request try/except, whose handler returns None -
+    so without its own guard a raising store turned a good page into a failed fetch
+    and sent the caller round for up to MAX_RETRY more solves.
+    """
+    import shelfmark.bypass.external_bypasser as external_bypasser
+
+    _stub_solution(
+        monkeypatch,
+        external_bypasser,
+        {"response": "<html>ok</html>", "cookies": [{"name": "__ddg1_", "value": "v"}]},
+    )
+
+    def boom(*_args, **_kwargs):
+        raise TypeError("unexpected cookie shape")
+
+    monkeypatch.setattr(external_bypasser, "store_extracted_cookies", boom)
+
+    assert (
+        external_bypasser._fetch_via_bypasser("https://annas-archive.gl/search?q=dune")
+        == "<html>ok</html>"
+    )
+
+
+def test_solution_without_cookies_is_still_returned(monkeypatch):
+    """A solver that returns no cookie list must not break the page fetch."""
+    import shelfmark.bypass.cookie_store as cookie_store
+    import shelfmark.bypass.external_bypasser as external_bypasser
+
+    monkeypatch.setattr(cookie_store, "_cf_cookies", {})
+    monkeypatch.setattr(cookie_store, "_cf_user_agents", {})
+    _stub_solution(monkeypatch, external_bypasser, {"response": "<html>ok</html>"})
+
+    result = external_bypasser._fetch_via_bypasser("https://annas-archive.gl/search?q=dune")
+
+    assert result == "<html>ok</html>"
+    assert cookie_store.get_cf_cookies_for_domain("annas-archive.gl") == {}
+
+
 def test_get_bypassed_page_retries_and_rotates_selector_between_attempts(monkeypatch):
    import shelfmark.bypass.external_bypasser as external_bypasser

@@ -101,3 +262,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,7 @@
 import asyncio
+import json
+import threading
+from pathlib import Path

 import pytest

@@ -112,7 +115,9 @@ def test_extract_cookies_from_cdp_keeps_full_session_cookies_for_configured_zlib
        async def evaluate(self, _expr):
            return "TestUA/1.0"

-    monkeypatch.setattr(internal_bypasser, "_get_full_cookie_domains", lambda: {"z-lib.fm"})
+    from shelfmark.bypass import cookie_store
+
+    monkeypatch.setattr(cookie_store, "_get_full_cookie_domains", lambda: {"z-lib.fm"})

    internal_bypasser.clear_cf_cookies()
    asyncio.run(
@@ -164,12 +169,14 @@ def test_extract_cookies_from_cdp_normalizes_session_expiry():
        )
    )

-    stored = internal_bypasser._cf_cookies.get("example.com", {})
+    from shelfmark.bypass import cookie_store
+
+    stored = cookie_store._cf_cookies.get("example.com", {})
    assert stored["cf_clearance"]["expiry"] is None
    assert internal_bypasser.get_cf_cookies_for_domain("example.com") == {"cf_clearance": "abc"}

    # Verify fallback to "expires" key for expiry checks
-    internal_bypasser._cf_cookies["example.com"]["cf_clearance"]["expires"] = int(time.time()) - 10
+    cookie_store._cf_cookies["example.com"]["cf_clearance"]["expires"] = int(time.time()) - 10
    assert internal_bypasser.get_cf_cookies_for_domain("example.com") == {}


@@ -373,7 +380,9 @@ def test_try_with_cached_cookies_returns_none_on_request_exception(monkeypatch):
    import shelfmark.bypass.internal_bypasser as internal_bypasser

    internal_bypasser.clear_cf_cookies()
-    internal_bypasser._cf_cookies["example.com"] = {
+    from shelfmark.bypass import cookie_store
+
+    cookie_store._cf_cookies["example.com"] = {
        "cf_clearance": {
            "value": "abc",
            "domain": "example.com",
@@ -430,3 +439,290 @@ 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
+
+
+def _write_fake_proc_entry(proc_root, pid: int, pgid: int, argv: list[str]) -> None:
+    """Create a /proc-shaped entry for a fake process."""
+    entry = proc_root / str(pid)
+    entry.mkdir()
+    (entry / "cmdline").write_bytes(b"\0".join(arg.encode() for arg in argv) + b"\0")
+    # pid (comm) state ppid pgrp ... - comm is parenthesised and may contain spaces.
+    (entry / "stat").write_text(f"{pid} (some (odd) name) S 1 {pgid} {pgid} 0 -1 4194304 0 0")
+
+
+def test_cleanup_only_kills_own_and_abandoned_browser_sessions(monkeypatch, tmp_path):
+    """Regression test for issue #1231: the sweep used a container-wide `pkill -f chrome`,
+    so every worker that started a bypass killed the browsers the other workers were
+    still driving. Only our own process group and groups whose leader is gone are ours."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    proc_root = tmp_path / "proc"
+    proc_root.mkdir()
+    _write_fake_proc_entry(proc_root, 1000, 1000, ["python", "-m", "shelfmark.bypass"])
+    _write_fake_proc_entry(proc_root, 1001, 1000, ["/usr/bin/chromium", "--headless"])
+    _write_fake_proc_entry(proc_root, 1002, 1000, ["Xvfb", ":99"])
+    # Live sibling session: another worker is solving a challenge with these right now.
+    _write_fake_proc_entry(proc_root, 2000, 2000, ["python", "-m", "shelfmark.bypass"])
+    _write_fake_proc_entry(proc_root, 2001, 2000, ["/usr/bin/chromium", "--headless"])
+    # Abandoned session: its leader (pid 3000) is gone, so its browser really is an orphan.
+    _write_fake_proc_entry(proc_root, 3001, 3000, ["/usr/bin/chromium", "--headless"])
+
+    killed: list[int] = []
+
+    monkeypatch.setattr(internal_bypasser.env, "DOCKERMODE", True)
+    monkeypatch.setattr(internal_bypasser, "_PROC_ROOT", proc_root)
+    monkeypatch.setattr(internal_bypasser.os, "getpid", lambda: 1000)
+    monkeypatch.setattr(internal_bypasser.os, "getpgrp", lambda: 1000)
+    monkeypatch.setattr(internal_bypasser.os, "kill", lambda pid, _sig: killed.append(pid))
+    monkeypatch.setattr(internal_bypasser.time, "sleep", lambda _seconds: None)
+
+    assert internal_bypasser._cleanup_orphan_processes() == 3
+    assert sorted(killed) == [1001, 1002, 3001]
+
+
+def test_cleanup_is_skipped_without_proc(monkeypatch, tmp_path):
+    """Without /proc there is no way to tell sessions apart, so kill nothing."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    monkeypatch.setattr(internal_bypasser.env, "DOCKERMODE", True)
+    monkeypatch.setattr(internal_bypasser, "_PROC_ROOT", tmp_path / "missing")
+    monkeypatch.setattr(
+        internal_bypasser.os, "kill", lambda *_args: pytest.fail("must not kill anything")
+    )
+
+    assert internal_bypasser._cleanup_orphan_processes() == 0
+
+
+class _FakeHelperStdin:
+    """The request pipe: a write is how the helper receives one request."""
+
+    def __init__(self, process):
+        self._process = process
+        self.closed = False
+
+    def write(self, data):
+        self._process.serve(data)
+
+    def flush(self):
+        return None
+
+    def close(self):
+        self.closed = True
+
+
+class _FakeHelperProcess:
+    """Stand-in for the bypass helper subprocess.
+
+    The helper serves one request per line of stdin and answers by writing the result file
+    the request named, so that is what this fakes: a write produces an answer.
+    """
+
+    def __init__(self, *_args, **kwargs):
+        self.kwargs = kwargs
+        self.pid = 4242
+        self.returncode = None
+        self.answers = True
+        self.killed = False
+        self.waited = False
+        self.stdin = _FakeHelperStdin(self)
+        self.requests: list[dict] = []
+
+    def serve(self, payload):
+        request = json.loads(payload)
+        self.requests.append(request)
+        if not self.answers:
+            return
+        result = {"ok": True, "html": "<html>solved</html>", "cookies": {}, "user_agents": {}}
+        Path(request["result_path"]).write_text(json.dumps(result), encoding="utf-8")
+
+    def poll(self):
+        return self.returncode
+
+    def kill(self):
+        self.killed = True
+        self.returncode = -9
+
+    def wait(self, timeout=None):
+        self.waited = True
+        if self.returncode is None:
+            self.returncode = 0
+        return self.returncode
+
+
+def _patch_helper_subprocess(monkeypatch, internal_bypasser, process, killed_groups):
+    monkeypatch.setattr(internal_bypasser.subprocess, "Popen", lambda *a, **kw: process(*a, **kw))
+    monkeypatch.setattr(internal_bypasser.network, "get_dns_config", dict)
+    monkeypatch.setattr(
+        internal_bypasser.os, "killpg", lambda pgid, _sig: killed_groups.append(pgid)
+    )
+    # A fresh helper per test: the module-level one is shared, and a process parked by one
+    # test would be handed to the next.
+    helper = internal_bypasser._BypassHelper()
+    monkeypatch.setattr(internal_bypasser._BypassHelper, "_idle_timeout", lambda _self: 0.0)
+    monkeypatch.setattr(internal_bypasser, "_BYPASS_HELPER", helper)
+    return helper
+
+
+def test_helper_runs_in_its_own_session_and_is_torn_down(monkeypatch):
+    """Regression test for issue #1231: the helper's Chrome and Xvfb must belong to the
+    helper's own process group, and the whole group must die with it - otherwise the
+    leftovers break the next worker's browser and can only be cleared by a sweep broad
+    enough to kill a concurrent worker's browser too.
+
+    The helper outlives a single request, so the teardown happens when it is dropped rather
+    than after every solve. Each bypass still closes its own browser, so what survives in
+    between is the process, not a Chrome.
+    """
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    processes: list[_FakeHelperProcess] = []
+    killed_groups: list[int] = []
+
+    def _make_process(*args, **kwargs):
+        process = _FakeHelperProcess(*args, **kwargs)
+        processes.append(process)
+        return process
+
+    helper = _patch_helper_subprocess(monkeypatch, internal_bypasser, _make_process, killed_groups)
+
+    assert internal_bypasser._get_via_subprocess("https://example.com", 1) == "<html>solved</html>"
+    assert processes[0].kwargs["start_new_session"] is True
+    assert killed_groups == [], "the helper was torn down after a single request"
+
+    helper._discard()
+
+    assert killed_groups == [processes[0].pid]
+
+
+def test_helper_serves_a_second_request_without_respawning(monkeypatch):
+    """The interpreter start and imports are paid once, not per protected request."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    processes: list[_FakeHelperProcess] = []
+    killed_groups: list[int] = []
+
+    def _make_process(*args, **kwargs):
+        process = _FakeHelperProcess(*args, **kwargs)
+        processes.append(process)
+        return process
+
+    _patch_helper_subprocess(monkeypatch, internal_bypasser, _make_process, killed_groups)
+
+    internal_bypasser._get_via_subprocess("https://example.com/one", 1)
+    internal_bypasser._get_via_subprocess("https://example.com/two", 1)
+
+    assert len(processes) == 1
+    assert [request["url"] for request in processes[0].requests] == [
+        "https://example.com/one",
+        "https://example.com/two",
+    ]
+
+
+def test_helper_timeout_kills_the_whole_session(monkeypatch):
+    """A timed-out solve must not leave a live browser behind for the next worker."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    processes: list[_FakeHelperProcess] = []
+    killed_groups: list[int] = []
+
+    def _make_process(*args, **kwargs):
+        process = _FakeHelperProcess(*args, **kwargs)
+        process.answers = False  # accepts the request, never writes a result
+        processes.append(process)
+        return process
+
+    _patch_helper_subprocess(monkeypatch, internal_bypasser, _make_process, killed_groups)
+    monkeypatch.setattr(internal_bypasser, "_BYPASS_SUBPROCESS_TIMEOUT_SECONDS", 0.1)
+
+    with pytest.raises(TimeoutError):
+        internal_bypasser._get_via_subprocess("https://example.com", 1)
+
+    assert killed_groups == [processes[0].pid]
+    assert processes[0].killed is True
+
+
+def test_helper_takes_the_browser_down_when_its_parent_dies(monkeypatch):
+    """Cleanup only reclaims process groups whose leader is gone (#1231), so an orphaned
+    helper must not sit there holding a browser no later bypass is allowed to touch."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    terminated: list[str] = []
+
+    monkeypatch.setattr(internal_bypasser.os, "getppid", lambda: 1)
+    monkeypatch.setattr(
+        internal_bypasser, "_terminate_own_session", lambda: terminated.append("terminated")
+    )
+    monkeypatch.setattr(
+        internal_bypasser.time, "sleep", lambda _seconds: pytest.fail("should not wait")
+    )
+
+    internal_bypasser._watch_parent_process(999, interval=0.0)
+
+    assert terminated == ["terminated"]
+
+
+def test_helper_watchdog_waits_while_its_parent_is_alive(monkeypatch):
+    """The watchdog must only fire on a changed ppid, not on every poll."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    ppids = iter([999, 999, 1])
+    sleeps: list[float] = []
+
+    monkeypatch.setattr(internal_bypasser.os, "getppid", lambda: next(ppids))
+    monkeypatch.setattr(internal_bypasser, "_terminate_own_session", lambda: None)
+    monkeypatch.setattr(internal_bypasser.time, "sleep", sleeps.append)
+
+    internal_bypasser._watch_parent_process(999, interval=0.5)
+
+    assert sleeps == [0.5, 0.5]
@@ -0,0 +1,658 @@
+"""Tests for keeping the bypass helper process alive between requests.
+
+The browser is deliberately not kept: every bypass starts and closes its own Chrome. What
+survives is the helper process, whose interpreter start and imports are pure overhead.
+"""
+
+import asyncio
+import json
+
+import pytest
+
+
+class _FakeStdin:
+    def __init__(self) -> None:
+        self.closed = False
+        self.written: list[str] = []
+
+    def write(self, data: str) -> None:
+        if self.closed:
+            raise BrokenPipeError("stdin is closed")
+        self.written.append(data)
+
+    def flush(self) -> None:
+        return None
+
+    def close(self) -> None:
+        self.closed = True
+
+
+class _FakeProc:
+    """Enough of subprocess.Popen for the helper's process bookkeeping."""
+
+    _next_pid = 90001
+
+    def __init__(self) -> None:
+        self.stdin = _FakeStdin()
+        self.returncode: int | None = None
+        self.waited = False
+        # A pid nothing may actually be signalled by: _terminate_helper_session is patched
+        # out in these tests, and a stray killpg on a live pid would take out the test run.
+        type(self)._next_pid += 1
+        self.pid = type(self)._next_pid
+
+    def poll(self) -> int | None:
+        return self.returncode
+
+    def wait(self, timeout: float | None = None) -> int:
+        self.waited = True
+        if self.returncode is None:
+            self.returncode = 0
+        return self.returncode
+
+    def kill(self) -> None:
+        self.returncode = -9
+
+
+def _helper_with_fake_spawn(monkeypatch, procs: list[_FakeProc], terminated=None):
+    """Build a helper that hands out fake processes and never arms a real timer."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    def _spawn(_self) -> _FakeProc:
+        proc = _FakeProc()
+        procs.append(proc)
+        return proc
+
+    def _terminate(proc) -> None:
+        if terminated is not None:
+            terminated.append(proc)
+
+    monkeypatch.setattr(internal_bypasser._BypassHelper, "_spawn", _spawn)
+    monkeypatch.setattr(internal_bypasser._BypassHelper, "_idle_timeout", lambda _self: 0.0)
+    monkeypatch.setattr(internal_bypasser, "_terminate_helper_session", _terminate)
+    return internal_bypasser._BypassHelper()
+
+
+def _answered_payload(tmp_path, name: str = "result.json") -> dict:
+    """A request whose result file already exists, so the helper resolves immediately."""
+    result_path = tmp_path / name
+    result_path.write_text(json.dumps({"ok": True, "html": "<html/>"}), encoding="utf-8")
+    return {"url": "https://example.com", "retry": 1, "result_path": str(result_path)}
+
+
+def test_helper_serves_consecutive_requests_from_one_process(monkeypatch, tmp_path):
+    """The point of the whole thing: request two and three must not re-pay the spawn."""
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    for i in range(3):
+        result = helper.run(_answered_payload(tmp_path, f"r{i}.json"), timeout=5, cancel_flag=None)
+        assert result["ok"] is True
+
+    assert len(procs) == 1, "each request spawned its own helper"
+    assert len(procs[0].stdin.written) == 3
+    assert all(line.endswith("\n") for line in procs[0].stdin.written), (
+        "requests must be newline-delimited or the helper's loop cannot split them"
+    )
+
+
+def test_helper_respawns_after_the_previous_one_died(monkeypatch, tmp_path):
+    """A helper can be reaped while idle; the next request must not fail on it."""
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    helper.run(_answered_payload(tmp_path, "a.json"), timeout=5, cancel_flag=None)
+    procs[0].returncode = 1  # died between requests
+
+    result = helper.run(_answered_payload(tmp_path, "b.json"), timeout=5, cancel_flag=None)
+
+    assert result["ok"] is True
+    assert len(procs) == 2
+
+
+def test_helper_retries_once_when_the_pipe_breaks_on_write(monkeypatch, tmp_path):
+    """poll() can still say alive when the far end is already gone."""
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    helper.run(_answered_payload(tmp_path, "a.json"), timeout=5, cancel_flag=None)
+    procs[0].stdin.closed = True  # pipe gone, but poll() still reports running
+
+    result = helper.run(_answered_payload(tmp_path, "b.json"), timeout=5, cancel_flag=None)
+
+    assert result["ok"] is True
+    assert len(procs) == 2
+
+
+def test_helper_reports_a_helper_that_exits_without_answering(monkeypatch, tmp_path):
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    payload = {
+        "url": "https://example.com",
+        "retry": 1,
+        "result_path": str(tmp_path / "never-written.json"),
+    }
+
+    def _die_on_write(_self, proc, _line) -> None:
+        proc.returncode = 3
+
+    monkeypatch.setattr(internal_bypasser._BypassHelper, "_write", _die_on_write)
+
+    with pytest.raises(RuntimeError, match="exited without a result"):
+        helper.run(payload, timeout=5, cancel_flag=None)
+
+
+def test_helper_times_out_and_discards_the_wedged_process(monkeypatch, tmp_path):
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    payload = {
+        "url": "https://example.com",
+        "retry": 1,
+        "result_path": str(tmp_path / "never-written.json"),
+    }
+
+    with pytest.raises(TimeoutError):
+        helper.run(payload, timeout=0.05, cancel_flag=None)
+
+    assert helper._proc is None, "a wedged helper must not be handed to the next request"
+
+
+def test_idle_reaper_rearms_when_work_arrived_while_it_waited(monkeypatch, tmp_path):
+    """The timer fires on its own thread and can lose the race against a new request."""
+    import time
+
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+    helper.run(_answered_payload(tmp_path), timeout=5, cancel_flag=None)
+
+    rearmed: list[bool] = []
+    monkeypatch.setattr(internal_bypasser._BypassHelper, "_idle_timeout", lambda _self: 3600.0)
+    monkeypatch.setattr(
+        internal_bypasser._BypassHelper, "_arm_idle_timer", lambda _self: rearmed.append(True)
+    )
+    helper._last_used = time.monotonic()
+
+    helper._reap_if_idle()
+
+    assert rearmed == [True]
+    assert helper._proc is not None, "helper was killed despite recent work"
+
+
+def test_idle_reaper_closes_a_genuinely_idle_helper(monkeypatch, tmp_path):
+    import time
+
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+    helper.run(_answered_payload(tmp_path), timeout=5, cancel_flag=None)
+
+    monkeypatch.setattr(internal_bypasser._BypassHelper, "_idle_timeout", lambda _self: 60.0)
+    helper._last_used = time.monotonic() - 120
+
+    helper._reap_if_idle()
+
+    assert helper._proc is None
+    assert procs[0].stdin.closed
+
+
+def test_discard_tears_down_the_whole_session(monkeypatch, tmp_path):
+    """Dropping the helper must reach its browser tree, not just the helper itself.
+
+    The helper is a session leader (start_new_session), so a Chrome left behind by one
+    killed mid-bypass would keep a process group alive that the cleanup sweep is then not
+    allowed to reclaim - the leak #1231 was about.
+    """
+    procs: list[_FakeProc] = []
+    terminated: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs, terminated)
+
+    helper.run(_answered_payload(tmp_path), timeout=5, cancel_flag=None)
+    helper._discard()
+
+    assert terminated == [procs[0]]
+
+
+def test_helper_asks_before_it_kills(monkeypatch, tmp_path):
+    """An idle helper should get to exit on its own; the kill is the fallback."""
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    helper.run(_answered_payload(tmp_path), timeout=5, cancel_flag=None)
+    helper._discard()
+
+    assert procs[0].stdin.closed, "stdin must be closed to end the helper's request loop"
+    assert procs[0].returncode == 0, "an idle helper should have exited on its own"
+
+
+def _bypass_with_recorded_driver(monkeypatch, get_impl):
+    """Wire up a bypass whose browser creation and closing are observable."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    driver = object()
+    closed: list[object] = []
+
+    async def _create(_url):
+        return driver
+
+    async def _close(drv):
+        closed.append(drv)
+
+    monkeypatch.setattr(internal_bypasser, "_create_cdp_browser", _create)
+    monkeypatch.setattr(internal_bypasser, "_get", get_impl)
+    monkeypatch.setattr(internal_bypasser, "_close_cdp_driver", _close)
+    return driver, closed
+
+
+def test_successful_bypass_closes_its_browser(monkeypatch):
+    """A living helper must not accumulate browsers: each bypass ends with Chrome gone."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    async def _get(_url, _driver, _cancel=None):
+        return "<html>ok</html>"
+
+    driver, closed = _bypass_with_recorded_driver(monkeypatch, _get)
+
+    result = internal_bypasser._run_bypass_in_current_process("https://example.com", 1)
+
+    assert result == "<html>ok</html>"
+    assert closed == [driver]
+
+
+def test_failed_bypass_closes_its_browser(monkeypatch):
+    """The same has to hold when the bypass raises on its way out."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    async def _get(_url, _driver, _cancel=None):
+        raise internal_bypasser.BypassCancelledError("cancelled")
+
+    driver, closed = _bypass_with_recorded_driver(monkeypatch, _get)
+
+    with pytest.raises(internal_bypasser.BypassCancelledError):
+        internal_bypasser._run_bypass_in_current_process("https://example.com", 1)
+
+    assert closed == [driver]
+
+
+def test_child_process_serves_every_line_it_is_given(monkeypatch, tmp_path):
+    """One helper, several requests: the loop is what saves the repeated process start."""
+    import io
+
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    urls: list[str] = []
+
+    def _fake_get(url, retry=None, cancel_flag=None):
+        urls.append(url)
+        return f"<html>{url}</html>"
+
+    requests = [
+        {"url": "https://example.com/one", "retry": 1, "result_path": str(tmp_path / "1.json")},
+        {"url": "https://example.com/two", "retry": 1, "result_path": str(tmp_path / "2.json")},
+    ]
+    stdin = io.StringIO("\n".join(json.dumps(request) for request in requests) + "\n")
+
+    monkeypatch.setattr(internal_bypasser, "get", _fake_get)
+    monkeypatch.setattr(internal_bypasser.sys, "stdin", stdin)
+
+    assert internal_bypasser._run_child_process() == 0
+    assert urls == ["https://example.com/one", "https://example.com/two"]
+
+    for index, request in enumerate(requests, start=1):
+        result = json.loads((tmp_path / f"{index}.json").read_text(encoding="utf-8"))
+        assert result["ok"] is True
+        assert result["html"] == f"<html>{request['url']}</html>"
+
+
+def test_child_process_keeps_serving_after_a_failed_request(monkeypatch, tmp_path):
+    """One failing URL must not take the helper - and everything queued - down."""
+    import io
+
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    def _fake_get(url, retry=None, cancel_flag=None):
+        if url.endswith("boom"):
+            raise RuntimeError("bypass exploded")
+        return "<html>ok</html>"
+
+    requests = [
+        {"url": "https://example.com/boom", "retry": 1, "result_path": str(tmp_path / "1.json")},
+        {"url": "https://example.com/fine", "retry": 1, "result_path": str(tmp_path / "2.json")},
+    ]
+    stdin = io.StringIO("\n".join(json.dumps(request) for request in requests) + "\n")
+
+    monkeypatch.setattr(internal_bypasser, "get", _fake_get)
+    monkeypatch.setattr(internal_bypasser.sys, "stdin", stdin)
+
+    assert internal_bypasser._run_child_process() == 0
+
+    failed = json.loads((tmp_path / "1.json").read_text(encoding="utf-8"))
+    assert failed["ok"] is False
+    assert failed["error"] == "bypass exploded"
+
+    served = json.loads((tmp_path / "2.json").read_text(encoding="utf-8"))
+    assert served["ok"] is True
+
+
+def test_result_file_becomes_visible_only_when_complete(tmp_path):
+    """The parent treats the file's existence as the answer, so no partial writes."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    result_path = tmp_path / "result.json"
+    internal_bypasser._publish_result(result_path, {"ok": True, "html": "<html/>"})
+
+    assert json.loads(result_path.read_text(encoding="utf-8"))["ok"] is True
+    assert list(tmp_path.iterdir()) == [result_path], "temporary file was left behind"
+
+
+def test_child_bypass_runs_on_the_long_lived_worker_loop(monkeypatch):
+    """A helper serving many requests must not build and close a loop per bypass.
+
+    asyncio.run() owns the loop for one call and closes it on the way out, which is why the
+    child goes through the worker unconditionally: one loop for the process's lifetime.
+    """
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    monkeypatch.setenv("SHELFMARK_INTERNAL_BYPASSER_CHILD", "1")
+
+    loops: list[asyncio.AbstractEventLoop] = []
+
+    async def _record_loop(_url, _driver, _cancel=None):
+        loops.append(asyncio.get_running_loop())
+        return "<html>ok</html>"
+
+    _bypass_with_recorded_driver(monkeypatch, _record_loop)
+
+    internal_bypasser._run_bypass_in_current_process("https://example.com", 1)
+    internal_bypasser._run_bypass_in_current_process("https://example.com", 1)
+
+    assert len(loops) == 2
+    assert loops[0] is loops[1], "second bypass ran on a different loop than the first"
+    assert not loops[0].is_closed()
+
+
+def test_child_bypass_carries_its_own_deadline(monkeypatch):
+    """The child bounds itself, rather than relying only on the parent's deadline."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    monkeypatch.setenv("SHELFMARK_INTERNAL_BYPASSER_CHILD", "1")
+
+    timeouts: list[float | None] = []
+    real_run = internal_bypasser._CDP_WORKER.run
+
+    def _record_timeout(coro, timeout=None):
+        timeouts.append(timeout)
+        return real_run(coro, timeout=timeout)
+
+    async def _get(_url, _driver, _cancel=None):
+        return "<html>ok</html>"
+
+    _bypass_with_recorded_driver(monkeypatch, _get)
+    monkeypatch.setattr(internal_bypasser._CDP_WORKER, "run", _record_timeout)
+
+    internal_bypasser._run_bypass_in_current_process("https://example.com", 1)
+
+    assert timeouts == [internal_bypasser._CHILD_BYPASS_TIMEOUT_SECONDS]
+
+
+def test_child_deadline_leaves_the_parent_room_to_hear_the_answer(monkeypatch):
+    """If the parent gave up first it could only kill the helper, losing a warm process."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    # The child's worst case is its deadline plus the grace it is given to close the
+    # browser after that deadline cancels the bypass, and all of it has to fit inside the
+    # parent's wait - otherwise the parent gives up first and kills a helper that was
+    # about to answer.
+    assert (
+        internal_bypasser._CHILD_BYPASS_TIMEOUT_SECONDS
+        + internal_bypasser._CDP_UNWIND_GRACE_SECONDS
+        < internal_bypasser._BYPASS_SUBPROCESS_TIMEOUT_SECONDS
+    )
+
+
+def test_in_process_bypass_keeps_the_parents_budget(monkeypatch):
+    """Non-Docker installs run in-process, where there is no helper to outlive anything."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    monkeypatch.delenv("SHELFMARK_INTERNAL_BYPASSER_CHILD", raising=False)
+
+    timeouts: list[float | None] = []
+    real_run = internal_bypasser._CDP_WORKER.run
+
+    def _record_timeout(coro, timeout=None):
+        timeouts.append(timeout)
+        return real_run(coro, timeout=timeout)
+
+    async def _get(_url, _driver, _cancel=None):
+        return "<html>ok</html>"
+
+    _bypass_with_recorded_driver(monkeypatch, _get)
+    monkeypatch.setattr(internal_bypasser._CDP_WORKER, "run", _record_timeout)
+
+    internal_bypasser._run_bypass_in_current_process("https://example.com", 1)
+
+    assert timeouts == [internal_bypasser._IN_PROCESS_BYPASS_TIMEOUT_SECONDS]
+
+
+def test_timed_out_bypass_finishes_unwinding_before_the_call_returns():
+    """A helper serving the next request must not race the browser teardown of the last.
+
+    The deadline cancels the bypass, but cancelling from the calling thread only schedules
+    that - it returns while `finally: await _close_cdp_driver(driver)` is still running.
+    In a helper that now outlives the request, the next bypass would open its Chrome on the
+    same loop while the abandoned one was still closing its own, sharing the DISPLAY
+    globals and one process group.
+    """
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    events: list[str] = []
+
+    async def _wedged():
+        try:
+            await asyncio.sleep(30)
+        finally:
+            # Teardown that yields, the way closing websockets and Chrome does.
+            await asyncio.sleep(0.05)
+            events.append("browser closed")
+
+    with pytest.raises(TimeoutError):
+        internal_bypasser._CDP_WORKER.run(_wedged(), timeout=0.1)
+
+    assert events == ["browser closed"], "run() returned before the bypass had unwound"
+
+
+def test_unwind_that_wedges_does_not_hold_the_caller_forever(monkeypatch):
+    """The grace is a bound, not a promise: cleanup can hang on a dead browser too."""
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    monkeypatch.setattr(internal_bypasser, "_CDP_UNWIND_GRACE_SECONDS", 0.1)
+
+    async def _wedged_on_both_ends():
+        try:
+            await asyncio.sleep(30)
+        finally:
+            await asyncio.sleep(30)
+
+    with pytest.raises(TimeoutError):
+        internal_bypasser._CDP_WORKER.run(_wedged_on_both_ends(), timeout=0.1)
+
+
+def test_cancelling_does_not_wait_out_the_shutdown_grace(monkeypatch, tmp_path):
+    """The grace only helps a helper that can still read its stdin.
+
+    One dropped mid-bypass is blocked inside the solve and will never reach its read loop,
+    so waiting it out cannot end in anything but the kill - while the user who asked to
+    cancel, and every bypass queued behind them on LOCKED, waits for it.
+    """
+    import threading
+
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    cancel_flag = threading.Event()
+    cancel_flag.set()
+    payload = {
+        "url": "https://example.com",
+        "retry": 1,
+        "result_path": str(tmp_path / "never-written.json"),
+    }
+
+    with pytest.raises(internal_bypasser.BypassCancelledError):
+        helper.run(payload, timeout=5, cancel_flag=cancel_flag)
+
+    assert not procs[0].waited, "a helper wedged mid-bypass was given the full exit grace"
+    assert procs[0].stdin.closed
+
+
+def test_idle_helper_still_gets_its_grace(monkeypatch, tmp_path):
+    """The reaper drops a helper that *is* in its read loop, and that one gets to exit."""
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    helper.run(_answered_payload(tmp_path), timeout=5, cancel_flag=None)
+    helper._discard()
+
+    assert procs[0].waited, "an idle helper should be asked to exit before being killed"
+
+
+def test_failed_request_leaves_no_result_files_behind(monkeypatch, tmp_path):
+    """Result paths are unique per request, so anything left is left for good."""
+    procs: list[_FakeProc] = []
+    helper = _helper_with_fake_spawn(monkeypatch, procs)
+
+    result_path = tmp_path / "result.json"
+    # A helper killed part-way through _publish_result leaves the staging file.
+    (tmp_path / "result.json.part").write_text('{"ok": tr', encoding="utf-8")
+    payload = {"url": "https://example.com", "retry": 1, "result_path": str(result_path)}
+
+    with pytest.raises(TimeoutError):
+        helper.run(payload, timeout=0.05, cancel_flag=None)
+
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_child_does_not_export_cookies_left_by_an_earlier_request(monkeypatch, tmp_path):
+    """The parent owns the store; a warm helper must not push its own history back over it.
+
+    http.py purges a host's clearance the moment that host challenges a request carrying
+    it. A helper that kept its store across requests would still be holding the purged
+    cookies, and the next solve - for some entirely different host - would export them and
+    the parent would merge them straight back in.
+    """
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    def _solve_host(url, retry=None, cancel_flag=None):
+        # A solve fills the store for the host it solved, which is all it should report.
+        host = url.rsplit("/", 1)[-1]
+        internal_bypasser.import_store({host: {"cf_clearance": "fresh"}}, {host: "UA"})
+        return "<html>ok</html>"
+
+    monkeypatch.setattr(internal_bypasser, "get", _solve_host)
+    internal_bypasser.clear_cf_cookies()
+
+    for index, host in enumerate(("first.example", "second.example")):
+        internal_bypasser._handle_child_request(
+            json.dumps(
+                {
+                    "url": f"https://example.com/{host}",
+                    "retry": 1,
+                    "result_path": str(tmp_path / f"{index}.json"),
+                }
+            )
+        )
+
+    second = json.loads((tmp_path / "1.json").read_text(encoding="utf-8"))
+    assert list(second["cookies"]) == ["second.example"], (
+        "the helper exported clearance won by an earlier request"
+    )
+    assert list(second["user_agents"]) == ["second.example"]
+
+    internal_bypasser.clear_cf_cookies()
+
+
+def _record_dns_calls(monkeypatch):
+    """Stand in for the network module: report a resolver state, record changes to it.
+
+    A helper starts on system DNS, which is what the parent reports as "auto".
+    """
+    import shelfmark.bypass.internal_bypasser as internal_bypasser
+
+    calls: list[tuple] = []
+    state = {"provider": "auto", "servers": [], "doh_enabled": False}
+
+    def _set(provider, servers=None, use_doh=None):
+        calls.append((provider, servers, use_doh))
+        state.update({"provider": provider, "servers": servers or [], "doh_enabled": bool(use_doh)})
+
+    monkeypatch.setattr(internal_bypasser.network, "set_dns_provider", _set)
+    monkeypatch.setattr(internal_bypasser.network, "get_dns_config", lambda: dict(state))
+    return internal_bypasser, calls
+
+
+def test_helper_follows_the_parent_back_to_auto_dns(monkeypatch):
+    """A user flipping CUSTOM_DNS back to auto applies live - the helper has to hear it.
+
+    The old early-return on "auto" was correct only because a fresh helper had never been
+    told anything else. One that outlives the request has, and would go on resolving AA
+    through a resolver the parent has already abandoned.
+    """
+    internal_bypasser, calls = _record_dns_calls(monkeypatch)
+
+    internal_bypasser._apply_parent_dns_config(
+        {"provider": "cloudflare", "servers": [], "doh_enabled": True}
+    )
+    internal_bypasser._apply_parent_dns_config(
+        {"provider": "auto", "servers": [], "doh_enabled": False}
+    )
+
+    assert calls == [("cloudflare", None, True), ("auto", None, False)]
+
+
+def test_helper_does_not_reinitialize_dns_for_an_unchanged_config(monkeypatch):
+    """set_dns_provider() rebuilds resolvers; every request would pay for it otherwise."""
+    internal_bypasser, calls = _record_dns_calls(monkeypatch)
+
+    for _ in range(3):
+        internal_bypasser._apply_parent_dns_config(
+            {"provider": "quad9", "servers": [], "doh_enabled": True}
+        )
+
+    assert calls == [("quad9", None, True)]
+
+
+def test_fresh_helper_leaves_auto_dns_alone(monkeypatch):
+    """A helper starts on system DNS, which is what the parent reports as auto."""
+    internal_bypasser, calls = _record_dns_calls(monkeypatch)
+
+    internal_bypasser._apply_parent_dns_config(
+        {"provider": "auto", "servers": [], "doh_enabled": False}
+    )
+
+    assert calls == []
+
+
+def test_failed_dns_apply_is_retried_on_the_next_request(monkeypatch):
+    """A provider that did not land leaves the resolver where it was, so the next request
+    sees the same mismatch and tries again."""
+    internal_bypasser, calls = _record_dns_calls(monkeypatch)
+
+    def _explode(provider, servers=None, use_doh=None):
+        calls.append((provider, servers, use_doh))
+        msg = "resolver unreachable"
+        raise OSError(msg)
+
+    monkeypatch.setattr(internal_bypasser.network, "set_dns_provider", _explode)
+
+    config = {"provider": "google", "servers": [], "doh_enabled": True}
+    internal_bypasser._apply_parent_dns_config(config)
+    internal_bypasser._apply_parent_dns_config(config)
+
+    assert calls == [("google", None, True), ("google", None, True)]
@@ -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
@@ -66,6 +66,32 @@ def test_download_settings_booklore_destination_field_defaults_to_library():
    assert option_values == {"library", "bookdrop"}


+def test_download_settings_audiobook_grouping_is_opt_in():
+    from shelfmark.config.settings import download_settings
+
+    fields = download_settings()
+    organization_field = next(
+        field for field in fields if getattr(field, "key", None) == "FILE_ORGANIZATION_AUDIOBOOK"
+    )
+    rename_template = next(
+        field
+        for field in fields
+        if getattr(field, "key", None) == "template_audiobook_rename_editor"
+    )
+
+    assert organization_field.default == "rename"
+    assert [option["value"] for option in organization_field.options] == [
+        "none",
+        "rename",
+        "organize",
+        "rename_and_group",
+    ]
+    assert rename_template.show_when == {
+        "field": "FILE_ORGANIZATION_AUDIOBOOK",
+        "value": ["rename", "rename_and_group"],
+    }
+
+
 def test_download_settings_grimmory_copy_is_exposed_in_ui_metadata():
    from shelfmark.config.settings import download_settings

@@ -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
 # =============================================================================
@@ -375,14 +385,15 @@ class TestSettingsValidation:
        assert "Naming Template" in result["message"]
        assert "Organize" in result["message"]

-    def test_downloads_audiobooks_rename_template_rejects_path_separators(self):
+    @pytest.mark.parametrize("organization_mode", ["rename", "rename_and_group"])
+    def test_downloads_audiobooks_rename_template_rejects_path_separators(self, organization_mode):
        import shelfmark.config.settings  # noqa: F401
        from shelfmark.core.settings_registry import update_settings

        result = update_settings(
            "downloads",
            {
-                "FILE_ORGANIZATION_AUDIOBOOK": "rename",
+                "FILE_ORGANIZATION_AUDIOBOOK": organization_mode,
                "TEMPLATE_AUDIOBOOK_RENAME": "{Author}/{Title}",
            },
        )
@@ -436,6 +447,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 +464,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
@@ -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
@@ -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"
+  }
+}
--- a/Show More
+++ b/Show More