Merge branch 'main' into fix/manual-search-combined-media-type

build(deps-dev): bump knip from 6.32.1 to 6.32.2 in /src/frontend in the npm-deps group (#1246 )
Bumps the npm-deps group in /src/frontend with 1 update: [knip](https://github.com/webpro-nl/knip/tree/HEAD/packages/knip). Updates `knip` from 6.32.1 to 6.32.2 <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/webpro-nl/knip/releases">knip's releases</a>.</em></p> <blockquote> <h2>Release 6.32.2</h2> <ul> <li>Support <code>oxfmt.config.mts</code> (<a href="https://github.com/webpro-nl/knip/tree/HEAD/packages/knip/issues/1933">#1933</a>) (795900191dc75eec8d1e717b866bf57e1e2912cc) - thanks <a href="https://github.com/joealden"><code>@joealden</code></a>!</li> <li>Support <code>oxlint.config.mts</code> (<a href="https://github.com/webpro-nl/knip/tree/HEAD/packages/knip/issues/1934">#1934</a>) (531e2dc7c1d8bf31babea0068c34391182ec2d50) - thanks <a href="https://github.com/joealden"><code>@joealden</code></a>!</li> <li>Fix Supported <code>lint-staged</code> Configs (<a href="https://github.com/webpro-nl/knip/tree/HEAD/packages/knip/issues/1935">#1935</a>) (f9c755e414ed10baa4d01af8ddac6d04cb8d5617) - thanks <a href="https://github.com/joealden"><code>@joealden</code></a>!</li> <li>Update dependencies (95f7c529f918dd9e1a84f92c68d064738977b825)</li> <li>Update sentry snapshot (ea7929fcbd6b323c8bdd9252ac57017feeb29ecf)</li> </ul> </blockquote> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/webpro-nl/knip/commit/196a11a4e0cb5208c0dc8382a54341d5630af631"><code>196a11a</code></a> Release knip@6.32.2</li> <li><a href="https://github.com/webpro-nl/knip/commit/95f7c529f918dd9e1a84f92c68d064738977b825"><code>95f7c52</code></a> Update dependencies</li> <li><a href="https://github.com/webpro-nl/knip/commit/f9c755e414ed10baa4d01af8ddac6d04cb8d5617"><code>f9c755e</code></a> Fix Supported <code>lint-staged</code> Configs (<a href="https://github.com/webpro-nl/knip/tree/HEAD/packages/knip/issues/1935">#1935</a>)</li> <li><a href="https://github.com/webpro-nl/knip/commit/531e2dc7c1d8bf31babea0068c34391182ec2d50"><code>531e2dc</code></a> Support <code>oxlint.config.mts</code> (<a href="https://github.com/webpro-nl/knip/tree/HEAD/packages/knip/issues/1934">#1934</a>)</li> <li><a href="https://github.com/webpro-nl/knip/commit/795900191dc75eec8d1e717b866bf57e1e2912cc"><code>7959001</code></a> Support <code>oxfmt.config.mts</code> (<a href="https://github.com/webpro-nl/knip/tree/HEAD/packages/knip/issues/1933">#1933</a>)</li> <li>See full diff in <a href="https://github.com/webpro-nl/knip/commits/knip@6.32.2/packages/knip">compare view</a></li> </ul> </details> <br /> [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=knip&package-manager=npm_and_yarn&previous-version=6.32.1&new-version=6.32.2)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore <dependency name> major version` will close this group update PR and stop Dependabot creating any more for the specific dependency's major version (unless you unignore this specific dependency's major version or upgrade to it yourself) - `@dependabot ignore <dependency name> minor version` will close this group update PR and stop Dependabot creating any more for the specific dependency's minor version (unless you unignore this specific dependency's minor version or upgrade to it yourself) - `@dependabot ignore <dependency name>` will close this group update PR and stop Dependabot creating any more for the specific dependency (unless you unignore this specific dependency or upgrade to it yourself) - `@dependabot unignore <dependency name>` will remove all of the ignore conditions of the specified dependency - `@dependabot unignore <dependency name> <ignore condition>` will remove the ignore condition of the specified dependency and ignore conditions </details> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-09-24 19:30:30 +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
112 changed files with 11138 additions and 1724 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:cea0e6040540fb2b965b6e7fb5ffa00871e632eef63719f0ea54bca189ce14a6 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"]
@@ -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`

@@ -703,7 +704,7 @@ 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`

@@ -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,6 +1223,7 @@ 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` |
@@ -1255,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**
@@ -1291,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>
@@ -1324,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**
@@ -1408,7 +1452,7 @@ Delay between requests in seconds to avoid rate limiting (0-10).
 | `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). Searches are sent as "@<bot> <query>". | string | _none_ |
-| `IRC_AUDIOBOOK_CHANNEL` | Optional. Channel name (without the # prefix) to use for audiobook searches. Leave blank to use the main channel above for audiobooks too. | 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` |

@@ -1477,7 +1521,7 @@ The search bot to address queries to (required). Searches are sent as "@<bot> <q

 **Audiobook channel**

-Optional. Channel name (without the # prefix) to use for audiobook searches. Leave blank to use the main channel above for audiobooks too.
+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_
@@ -1508,6 +1552,8 @@ 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_ |
@@ -1559,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`

@@ -1924,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` |
@@ -1946,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_
@@ -2064,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
@@ -2231,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>
@@ -2286,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>=2026.5.3",
+    "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.8",
+    "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.16.0",
+    "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]],
@@ -14,6 +14,7 @@ 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 (
@@ -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

@@ -215,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 = [
@@ -416,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",
@@ -754,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 {
@@ -1282,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,
@@ -1300,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
@@ -1643,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},
+        ),
    ]


@@ -1761,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
@@ -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,
@@ -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(
@@ -26,6 +26,11 @@ from shelfmark.download.clients import (
    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

@@ -202,41 +207,19 @@ class AllDebridClient(DownloadClient):
        expected_hash: str | None = None,
        **kwargs: object,
    ) -> str:
-        """Upload a magnet link to AllDebrid and return the magnet ID."""
+        """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)

-        magnet_link = url
-        if not magnet_link.startswith("magnet:") and expected_hash:
-            magnet_link = f"magnet:?xt=urn:btih:{expected_hash}"
-
-        api_url = f"{_API_BASE}/magnet/upload"
        try:
-            resp = requests.post(
-                api_url,
-                headers=self._auth_headers(),
-                data={"magnets[]": magnet_link},
-                timeout=_API_TIMEOUT,
-                verify=get_ssl_verify(api_url),
-            )
-            resp.raise_for_status()
-            data = resp.json()
-            if data.get("status") != "success":
-                code = data.get("error", {}).get("code", "UNKNOWN")
-                msg = f"AllDebrid upload failed: {code}"
-                _raise_runtime_error(msg)
-
-            magnets = data.get("data", {}).get("magnets", [])
-            if not magnets:
-                msg = "No magnet returned from AllDebrid"
-                _raise_runtime_error(msg)
-
-            info = magnets[0]
-            if info.get("error"):
-                code = info["error"].get("code", "UNKNOWN")
-                msg = f"AllDebrid magnet error: {code}"
-                _raise_runtime_error(msg)
+            upload = resolve_debrid_upload(url, expected_hash=expected_hash)
+            info = self._send_torrent(upload)

            magnet_id = str(info.get("id", ""))
            if not magnet_id:
@@ -262,12 +245,65 @@ class AllDebridClient(DownloadClient):
            )

        except Exception:
-            logger.exception("Failed to upload magnet to AllDebrid")
+            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)
@@ -843,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:
@@ -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._ensure_authenticated()
-            response = self._client._session.get(url, params=params, timeout=10)
-
-            # Re-authenticate and retry once on 403
-            if response.status_code == _HTTP_STATUS_FORBIDDEN and self._can_reauthenticate:
-                logger.debug(
-                    "qBittorrent returned 403 for properties; re-authenticating and retrying"
-                )
-                self._ensure_authenticated()
-                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"

@@ -274,37 +237,18 @@ class QBittorrentClient(DownloadClient):
            return
        self._client.auth_log_in()

-    def _get_torrents_info(
-        self, torrent_hash: str | None = None, category: str | None = None
+    def _request_torrent_info_records(
+        self, params: dict[str, str]
    ) -> tuple[list[SimpleNamespace], str | None]:
-        """Get torrent info using GET.
-
-        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)
-
-        """
+        """Request torrent info records from qBittorrent."""
        url = f"{self._base_url}/api/v2/torrents/info"
-
-        def do_request(params: dict[str, str]) -> requests.Response:
+        try:
            self._ensure_authenticated()
-            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]:
+            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._ensure_authenticated()
-                response = self._client._session.get(url, params=request_params, timeout=10)
+                response = self._client._session.get(url, params=params, timeout=10)

            if response.status_code == _HTTP_STATUS_FORBIDDEN:
                logger.warning("qBittorrent authentication failed (HTTP 403)")
@@ -313,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:
@@ -374,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
@@ -397,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:
@@ -534,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")
@@ -567,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")

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

@@ -825,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
@@ -24,6 +24,11 @@ from shelfmark.download.clients import (
    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

@@ -173,26 +178,19 @@ class RealDebridClient(DownloadClient):
        expected_hash: str | None = None,
        **kwargs: object,
    ) -> str:
-        """Upload a magnet link to Real-Debrid and select all files."""
+        """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)

-        magnet_link = url
-        if not magnet_link.startswith("magnet:") and expected_hash:
-            magnet_link = f"magnet:?xt=urn:btih:{expected_hash}"
-
-        add_url = f"{_API_BASE}/torrents/addMagnet"
        try:
-            resp = requests.post(
-                add_url,
-                headers=self._auth_headers(),
-                data={"magnet": magnet_link},
-                timeout=_API_TIMEOUT,
-                verify=get_ssl_verify(add_url),
-            )
-            resp.raise_for_status()
-            data = resp.json()
+            upload = resolve_debrid_upload(url, expected_hash=expected_hash)
+            data = self._send_torrent(upload)

            torrent_id = str(data.get("id", ""))
            if not torrent_id:
@@ -229,12 +227,41 @@ class RealDebridClient(DownloadClient):
            )

        except Exception:
-            logger.exception("Failed to upload magnet to Real-Debrid")
+            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)
@@ -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,
@@ -173,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
            )
@@ -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,
    *,
@@ -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
@@ -649,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(
@@ -886,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:
@@ -933,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
@@ -942,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:
@@ -992,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:
@@ -1027,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:
@@ -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",
@@ -17,6 +17,7 @@ from shelfmark.core.naming import (
    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,
@@ -160,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,
@@ -169,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:
@@ -238,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:
@@ -256,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:
@@ -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,
+        ),
+    ]
@@ -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()

@@ -23,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
@@ -227,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
            }

@@ -239,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.
@@ -539,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.

@@ -601,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)
@@ -657,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")

@@ -885,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
            )
@@ -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


@@ -102,10 +102,13 @@ def irc_settings() -> list[SettingsField]:
            key="audiobook_heading",
            title="Audiobooks",
            description=(
-                "Some networks index audiobooks in a separate channel from ebooks "
-                "(for example #ebooks for ebooks and #bookz for audiobooks). "
-                "Configure that channel here to search it for audiobook requests. "
-                "Leave these blank to search the main channel above for both."
+                "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(
@@ -113,8 +116,9 @@ def irc_settings() -> list[SettingsField]:
            label="Audiobook channel",
            placeholder="e.g. bookz",
            description=(
-                "Optional. Channel name (without the # prefix) to use for audiobook "
-                "searches. Leave blank to use the main channel above for audiobooks too."
+                "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,
@@ -240,11 +240,11 @@ class IRCReleaseSource(ReleaseSource):
        nick = _config_text("IRC_NICK")
        search_bot = _config_text("IRC_SEARCH_BOT")

-        # Audiobooks may be indexed in a separate channel from ebooks on some networks
-        # (e.g. #ebooks for ebooks, #bookz for audiobooks). 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, which keeps the
-        # single-channel networks that index both formats working unchanged.
+        # 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:
@@ -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(
            {
@@ -307,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 []
@@ -329,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"
@@ -347,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

@@ -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",
@@ -2,6 +2,7 @@

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

@@ -16,6 +17,7 @@ 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,
@@ -29,9 +31,14 @@ 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,
@@ -49,10 +56,10 @@ _PROWLARR_SOURCE_ERRORS = (AttributeError, OSError, RuntimeError, TypeError, Val
 # Prowlarr indexer priority is 1-50 and lower is preferred; unknown sorts last.
 _UNRANKED_INDEXER_RANK = 51

-# Errors that can surface from ProwlarrClient.get_indexer_seed_settings(). The
+# 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:
@@ -222,7 +229,7 @@ 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
@@ -231,6 +238,35 @@ ALL_BOOK_FORMATS = AUDIOBOOK_FORMATS + EBOOK_FORMATS
 # 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)."""
@@ -538,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(
@@ -894,8 +930,16 @@ class ProwlarrSource(ReleaseSource):

        try:
            auto_expand_enabled = config.get("PROWLARR_AUTO_EXPAND", False)
-            deadline = time.monotonic() + PROWLARR_SEARCH_TIMEOUT_SECONDS
-            enabled_indexers = client.get_enabled_indexers_detailed()
+            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(
@@ -910,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()
@@ -930,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[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()
@@ -952,23 +1006,39 @@ 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:
+                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:
@@ -976,6 +1046,14 @@ class ProwlarrSource(ReleaseSource):
                        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)
@@ -1032,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
@@ -1039,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:
@@ -18,23 +18,23 @@
  },
  "dependencies": {
    "@tailwindcss/vite": "^4.3.3",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "react-router-dom": "^7.18.1",
+    "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.27.0",
-    "oxfmt": "^0.59.0",
-    "oxlint": "^1.74.0",
-    "oxlint-tsgolint": "^0.25.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": "^7.0.2",
-    "vite": "^8.1.5",
+    "vite": "^8.2.1",
    "vitest": "^4.1.10"
  }
 }
@@ -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);
 };
@@ -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
@@ -0,0 +1,38 @@
+"""The audiobook format list must stay in agreement across every layer that gates on it.
+
+These lists were maintained by hand in four places and drifted: the settings UI offered
+only m4b/mp3/m4a, so FLAC/OPUS/OGG could never be enabled even though the parsers
+recognized them, the sorter ranked them, and archive extraction knew them. The result was
+a FLAC audiobook that was invisible in search and rejected after download. They now all
+derive from `shelfmark.core.utils.AUDIOBOOK_FORMATS`; this test fails if one drifts again.
+"""
+
+from shelfmark.config.settings import _AUDIOBOOK_FORMAT_OPTIONS
+from shelfmark.core.utils import ARCHIVE_FORMATS, AUDIOBOOK_FORMATS
+from shelfmark.download.archive import ALL_AUDIO_EXTENSIONS
+from shelfmark.release_sources.irc import parser
+from shelfmark.release_sources.prowlarr.source import AUDIOBOOK_FORMATS as PROWLARR_FORMATS
+
+
+def test_archive_extraction_knows_every_audiobook_format():
+    assert ALL_AUDIO_EXTENSIONS == {f".{fmt}" for fmt in AUDIOBOOK_FORMATS}
+
+
+def test_prowlarr_knows_every_audiobook_format():
+    assert PROWLARR_FORMATS == list(AUDIOBOOK_FORMATS)
+
+
+def test_irc_parser_knows_every_audiobook_format():
+    assert set(AUDIOBOOK_FORMATS) <= set(parser.ALL_RECOGNIZED_FORMATS)
+
+
+def test_every_audiobook_format_is_selectable_in_settings():
+    """The settings list is the only one a user's config can be built from."""
+    selectable = {option["value"] for option in _AUDIOBOOK_FORMAT_OPTIONS}
+
+    assert selectable == {*AUDIOBOOK_FORMATS, *ARCHIVE_FORMATS}
+
+
+def test_audiobook_and_ebook_formats_do_not_overlap():
+    """Overlap would make content-type classification by extension ambiguous."""
+    assert not set(AUDIOBOOK_FORMATS) & set(parser.EBOOK_FORMATS)
@@ -28,6 +28,9 @@ _BOOTSTRAP_ENV_ACCESS_ALLOWLIST = {
 }
 _BOOTSTRAP_ENV_ACCESS_KEY_ALLOWLIST = {
    (Path("shelfmark/config/settings.py"), "USING_TOR"),
+    # Loggers are configured while settings_registry itself is still importing,
+    # so the level has to come from the bootstrap env module.
+    (Path("shelfmark/core/logger.py"), "LOG_LEVEL"),
 }
 _RAW_CONFIG_READ_ALLOWLIST = {
    Path("shelfmark/config/notifications_settings.py"),
@@ -205,7 +208,10 @@ class ConfigAccessVisitor(ast.NodeVisitor):
                return
            for alias in node.names:
                imported_name = alias.name
-                if imported_name in self.registered_keys:
+                if (
+                    imported_name in self.registered_keys
+                    and imported_name not in self._bootstrap_env_key_allowlist
+                ):
                    self._record_violation(
                        node,
                        "direct env-module import",
@@ -95,6 +95,64 @@ def test_upsert_updates_existing_cwa_user_by_username_before_email(user_db):
    assert user["role"] == "admin"


+def test_upsert_renames_existing_cwa_user_matched_by_email(user_db):
+    cwa_user = user_db.create_user(
+        username="old_reader",
+        email="reader@example.com",
+        role="user",
+        auth_source="cwa",
+    )
+
+    user, action = upsert_cwa_user(
+        user_db,
+        cwa_username="renamed_reader",
+        cwa_email="reader@example.com",
+        role="user",
+    )
+
+    assert action == "updated"
+    assert user["id"] == cwa_user["id"]
+    assert user["username"] == "renamed_reader"
+    assert user_db.get_user(username="old_reader") is None
+
+
+def test_upsert_uses_stable_alias_when_renamed_cwa_username_is_taken(user_db):
+    cwa_user = user_db.create_user(
+        username="old_reader",
+        email="reader@example.com",
+        role="user",
+        auth_source="cwa",
+    )
+    local_user = user_db.create_user(
+        username="renamed_reader",
+        email="local@example.com",
+        role="user",
+        auth_source="builtin",
+    )
+
+    first, first_action = upsert_cwa_user(
+        user_db,
+        cwa_username="renamed_reader",
+        cwa_email="reader@example.com",
+        role="admin",
+    )
+    second, second_action = upsert_cwa_user(
+        user_db,
+        cwa_username="renamed_reader",
+        cwa_email="reader@example.com",
+        role="admin",
+    )
+
+    assert first_action == second_action == "updated"
+    assert first["id"] == second["id"] == cwa_user["id"]
+    assert first["username"] == second["username"] == "renamed_reader__cwa"
+    assert first["role"] == second["role"] == "admin"
+    local_after = user_db.get_user(user_id=local_user["id"])
+    assert local_after is not None
+    assert local_after["username"] == "renamed_reader"
+    assert local_after["email"] == "local@example.com"
+
+
 def test_sync_prunes_cwa_users_missing_from_source(user_db):
    active_cwa = user_db.create_user(
        username="active_cwa",
@@ -66,6 +66,20 @@ def test_get_file_organization_uses_current_keys(monkeypatch):
    assert policy.get_file_organization(is_audiobook=True) == "none"


+def test_get_file_organization_accepts_audiobook_grouping(monkeypatch):
+    import shelfmark.download.postprocess.policy as policy
+
+    monkeypatch.setattr(
+        policy.core_config.config,
+        "get",
+        lambda key, default=None: {
+            "FILE_ORGANIZATION_AUDIOBOOK": "rename_and_group",
+        }.get(key, default),
+    )
+
+    assert policy.get_file_organization(is_audiobook=True) == "rename_and_group"
+
+
 def test_get_file_organization_ignores_pre_release_processing_mode_keys(monkeypatch):
    import shelfmark.download.postprocess.policy as policy

@@ -14,6 +14,7 @@ Two approaches to preserve torrent files for seeding:
 import os
 import shutil
 import tempfile
+import zipfile
 from pathlib import Path
 from threading import Event
 from unittest.mock import MagicMock, patch
@@ -1003,8 +1004,13 @@ class TestTorrentSourceCleanupProtection:
    Each test simulates a specific real-world content type and file structure.
    """

-    def _make_config_mock(self, library_path: str, hardlink: bool = True):
-        """Create config mock for library/organize mode with hardlinking."""
+    def _make_config_mock(
+        self,
+        library_path: str,
+        hardlink: bool = True,
+        organization_mode: str = "organize",
+    ):
+        """Create a folder-output config mock for torrent transfers."""
        return MagicMock(
            side_effect=lambda key, default=None, **_kwargs: {
                # Destination paths (what _get_final_destination uses)
@@ -1013,9 +1019,10 @@ class TestTorrentSourceCleanupProtection:
                # Templates (what _get_template uses)
                "TEMPLATE_ORGANIZE": "{Author}/{Title}",
                "TEMPLATE_AUDIOBOOK_ORGANIZE": "{Author}/{Title}{ - PartNumber}",
+                "TEMPLATE_AUDIOBOOK_RENAME": "{Author} - {Title}",
                # File organization mode
                "FILE_ORGANIZATION": "organize",
-                "FILE_ORGANIZATION_AUDIOBOOK": "organize",
+                "FILE_ORGANIZATION_AUDIOBOOK": organization_mode,
                # Hardlink toggle
                "HARDLINK_TORRENTS": hardlink,
                "HARDLINK_TORRENTS_AUDIOBOOK": hardlink,
@@ -1122,6 +1129,163 @@ class TestTorrentSourceCleanupProtection:

    # ==================== AUDIOBOOK TESTS ====================

+    @pytest.mark.parametrize(
+        ("organization_mode", "grouped"),
+        [("rename", False), ("rename_and_group", True)],
+    )
+    @pytest.mark.parametrize("hardlink", [True, False])
+    def test_torrent_audiobook_multifile_grouping_is_opt_in(
+        self, tmp_path, organization_mode, grouped, hardlink
+    ):
+        """Multi-file audiobooks retain their torrent folder only when opted in."""
+        from shelfmark.core.models import DownloadTask, SearchMode
+        from shelfmark.download.postprocess.router import (
+            post_process_download as _post_process_download,
+        )
+
+        torrent_dir = tmp_path / "downloads" / "Project: Hail Mary Audiobook"
+        torrent_dir.mkdir(parents=True)
+        source_files = [torrent_dir / "Part 01.mp3", torrent_dir / "Part 02.mp3"]
+        for index, source_file in enumerate(source_files, start=1):
+            source_file.write_bytes(f"audio {index}".encode())
+
+        library = tmp_path / "library"
+        library.mkdir()
+        task = DownloadTask(
+            task_id=f"audiobook_{organization_mode}_{hardlink}",
+            source="prowlarr",
+            title="Project Hail Mary",
+            author="Andy Weir",
+            format="mp3",
+            content_type="audiobook",
+            search_mode=SearchMode.UNIVERSAL,
+            original_download_path=str(torrent_dir),
+        )
+
+        with patch("shelfmark.core.config.config") as mock_orch:
+            mock_orch.get = self._make_config_mock(
+                str(library),
+                hardlink=hardlink,
+                organization_mode=organization_mode,
+            )
+            mock_orch.CUSTOM_SCRIPT = None
+            result = _post_process_download(torrent_dir, task, Event(), MagicMock())
+
+        transfer_dir = library / "Project_ Hail Mary Audiobook" if grouped else library
+        assert result is not None
+        assert Path(result).parent == transfer_dir
+        assert sorted(path.name for path in transfer_dir.glob("*.mp3")) == [
+            "Part 01.mp3",
+            "Part 02.mp3",
+        ]
+        assert bool(list(library.glob("*.mp3"))) is not grouped
+
+        for source_file in source_files:
+            destination_file = transfer_dir / source_file.name
+            assert source_file.exists()
+            assert destination_file.exists()
+            if hardlink:
+                assert source_file.stat().st_ino == destination_file.stat().st_ino
+            else:
+                assert source_file.stat().st_ino != destination_file.stat().st_ino
+
+    @pytest.mark.parametrize("organization_mode", ["rename", "none", "rename_and_group"])
+    def test_torrent_audiobook_single_file_stays_in_destination_root(
+        self, tmp_path, organization_mode
+    ):
+        """Single-file audiobooks do not gain a source-folder wrapper."""
+        from shelfmark.core.models import DownloadTask, SearchMode
+        from shelfmark.download.postprocess.router import (
+            post_process_download as _post_process_download,
+        )
+
+        torrent_file = tmp_path / "downloads" / "Project Hail Mary.mp3"
+        torrent_file.parent.mkdir()
+        torrent_file.write_bytes(b"audio")
+        library = tmp_path / "library"
+        library.mkdir()
+        task = DownloadTask(
+            task_id=f"single_audiobook_{organization_mode}",
+            source="prowlarr",
+            title="Project Hail Mary",
+            author="Andy Weir",
+            format="mp3",
+            content_type="audiobook",
+            search_mode=SearchMode.UNIVERSAL,
+            original_download_path=str(torrent_file),
+        )
+
+        with patch("shelfmark.core.config.config") as mock_orch:
+            mock_orch.get = self._make_config_mock(
+                str(library), organization_mode=organization_mode
+            )
+            mock_orch.CUSTOM_SCRIPT = None
+            result = _post_process_download(torrent_file, task, Event(), MagicMock())
+
+        expected_name = (
+            "Andy Weir - Project Hail Mary.mp3"
+            if organization_mode in {"rename", "rename_and_group"}
+            else torrent_file.name
+        )
+        assert result is not None
+        assert Path(result) == library / expected_name
+        assert torrent_file.exists()
+
+    def test_torrent_audiobook_archive_groups_under_the_release_name(self, tmp_path):
+        """Torrent: a single archive of chapters groups under the release name.
+
+        Simulates: a torrent whose only file is "Project Hail Mary.zip" holding
+        two chapters. Extraction only runs with hardlinking off, and the archive
+        itself must stay put for seeding.
+        """
+        from shelfmark.core.models import DownloadTask, SearchMode
+        from shelfmark.download.postprocess.router import (
+            post_process_download as _post_process_download,
+        )
+
+        torrent_file = tmp_path / "downloads" / "Project Hail Mary.zip"
+        torrent_file.parent.mkdir(parents=True)
+        with zipfile.ZipFile(torrent_file, "w") as zf:
+            zf.writestr("Part 01.mp3", "audio 1")
+            zf.writestr("Part 02.mp3", "audio 2")
+
+        library = tmp_path / "library"
+        library.mkdir()
+        task = DownloadTask(
+            task_id="torrent_archive_audiobook",
+            source="prowlarr",
+            title="Project Hail Mary",
+            author="Andy Weir",
+            format="mp3",
+            content_type="audiobook",
+            search_mode=SearchMode.UNIVERSAL,
+            original_download_path=str(torrent_file),
+        )
+
+        with (
+            patch("shelfmark.core.config.config") as mock_orch,
+            patch("shelfmark.config.env.TMP_DIR", tmp_path / "staging"),
+        ):
+            mock_orch.get = self._make_config_mock(
+                str(library),
+                hardlink=False,
+                organization_mode="rename_and_group",
+            )
+            mock_orch.CUSTOM_SCRIPT = None
+            result = _post_process_download(torrent_file, task, Event(), MagicMock())
+
+        grouped_dir = library / "Project Hail Mary"
+        assert result is not None
+        assert Path(result).parent == grouped_dir
+        assert sorted(path.name for path in grouped_dir.glob("*.mp3")) == [
+            "Part 01.mp3",
+            "Part 02.mp3",
+        ]
+        assert not list(library.glob("*.mp3"))
+        # The archive stays behind for seeding, and never names the folder.
+        assert torrent_file.exists()
+        assert not (library / "Project Hail Mary.zip").exists()
+
    def test_torrent_audiobook_multifile_hardlink(self, tmp_path):
        """Torrent: Multi-file audiobook - all source files preserved for seeding.

@@ -1184,6 +1348,7 @@ class TestTorrentSourceCleanupProtection:
        # Verify library has all 12 files
        library_files = list((library / "Andy Weir").glob("*.mp3"))
        assert len(library_files) == 12
+        assert not (library / torrent_dir.name).exists()

    # ==================== COMIC/CBZ TESTS ====================

@@ -2,16 +2,27 @@ import errno
 from pathlib import Path
 from unittest.mock import MagicMock, patch

+import pytest
+
 from shelfmark.core.models import DownloadTask, SearchMode
+from shelfmark.download import fs
 from shelfmark.download.postprocess.pipeline import collect_directory_files, validate_destination


+@pytest.fixture(autouse=True)
+def _reset_delete_denied():
+    fs._DELETE_DENIED_DIRS.clear()
+    yield
+    fs._DELETE_DENIED_DIRS.clear()
+
+
 def test_validate_destination_success_cleans_up_probe(tmp_path):
    destination = tmp_path / "dest"
    status_cb = MagicMock()

    assert validate_destination(destination, status_cb) is True
-    assert list(destination.glob(".shelfmark_write_test_*")) == []
+    assert list(destination.glob(".shelfmark_write_test*")) == []
+    assert fs.is_delete_denied(destination) is False


 def test_validate_destination_write_probe_permission_error(tmp_path):
@@ -22,7 +33,7 @@ def test_validate_destination_write_probe_permission_error(tmp_path):
    real_write_text = Path.write_text

    def fake_write_text(self, data, *args, **kwargs):
-        if ".shelfmark_write_test_" in self.name:
+        if ".shelfmark_write_test" in self.name:
            raise PermissionError(errno.EACCES, "Permission denied", str(self))
        return real_write_text(self, data, *args, **kwargs)

@@ -34,6 +45,37 @@ def test_validate_destination_write_probe_permission_error(tmp_path):
    assert "Destination not writable" in status_cb.call_args[0][1]


+def test_validate_destination_accepts_writable_but_undeletable_destination(tmp_path):
+    """Synology-style share: creating files is allowed, deleting them is not."""
+    destination = tmp_path / "dest"
+    destination.mkdir()
+    status_cb = MagicMock()
+
+    real_unlink = Path.unlink
+
+    def fake_unlink(self, *args, **kwargs):
+        if ".shelfmark_write_test" in self.name:
+            raise PermissionError(errno.EACCES, "Permission denied", str(self))
+        return real_unlink(self, *args, **kwargs)
+
+    with patch("pathlib.Path.unlink", new=fake_unlink):
+        assert validate_destination(destination, status_cb) is True
+
+    # Not fatal: no error is surfaced, and the destination is flagged so
+    # transfers write in place instead of publishing via rename.
+    assert not any(call[0][0] == "error" for call in status_cb.call_args_list)
+    assert fs.is_delete_denied(destination) is True
+
+
+def test_validate_destination_clears_stale_delete_denial(tmp_path):
+    destination = tmp_path / "dest"
+    destination.mkdir()
+    fs.mark_delete_denied(destination)
+
+    assert validate_destination(destination, MagicMock()) is True
+    assert fs.is_delete_denied(destination) is False
+
+
 def test_collect_directory_files_ignores_permission_errors(tmp_path):
    directory = tmp_path / "download"
    directory.mkdir()
@@ -748,6 +748,94 @@ def test_archive_extraction_organize_multifile_assigns_part_numbers(tmp_path):
    assert files[1].name == "Archive Audio - 02.mp3"


+@pytest.mark.parametrize(
+    ("organization_mode", "grouped"),
+    [("rename_and_group", True), ("rename", False)],
+)
+def test_archive_extraction_groups_chapters_under_the_archive_stem(
+    tmp_path, organization_mode, grouped
+):
+    """An extracted multi-chapter archive groups into `Book/`, never `Book.zip/`."""
+    from shelfmark.download.postprocess.router import (
+        post_process_download as _post_process_download,
+    )
+
+    staging = tmp_path / "staging"
+    ingest = tmp_path / "ingest"
+    staging.mkdir()
+    ingest.mkdir()
+
+    archive_path = staging / "Book.zip"
+    with zipfile.ZipFile(archive_path, "w") as zf:
+        zf.writestr("Part 1.mp3", "audio1")
+        zf.writestr("Part 2.mp3", "audio2")
+
+    task = DownloadTask(
+        task_id=f"direct-archive-audio-{organization_mode}",
+        source="direct_download",
+        title="Archive Audio",
+        author="Tester",
+        format="mp3",
+        content_type="audiobook",
+        search_mode=SearchMode.DIRECT,
+    )
+
+    with (
+        patch("shelfmark.core.config.config") as mock_config,
+        patch("shelfmark.config.env.TMP_DIR", staging),
+    ):
+        mock_config.get = _build_config(ingest, organization=organization_mode)
+        mock_config.CUSTOM_SCRIPT = None
+        _sync_config(mock_config, mock_config)
+
+        result = _post_process_download(archive_path, task, Event(), lambda *_args: None)
+
+    transfer_dir = ingest / "Book" if grouped else ingest
+    assert result is not None
+    assert Path(result).parent == transfer_dir
+    assert sorted(path.name for path in transfer_dir.glob("*.mp3")) == ["Part 1.mp3", "Part 2.mp3"]
+    assert bool(list(ingest.glob("*.mp3"))) is not grouped
+    # The suffix is packaging, not part of the release name.
+    assert not (ingest / "Book.zip").exists()
+
+
+def test_usenet_audiobook_multifile_preserves_source_folder(tmp_path):
+    from shelfmark.download.postprocess.router import (
+        post_process_download as _post_process_download,
+    )
+
+    source_dir = tmp_path / "downloads" / "Usenet Audiobook"
+    source_dir.mkdir(parents=True)
+    for part in (1, 2):
+        (source_dir / f"Part {part}.mp3").write_text(f"audio{part}")
+
+    ingest = tmp_path / "ingest"
+    ingest.mkdir()
+    task = DownloadTask(
+        task_id="usenet-audio-grouped",
+        source="prowlarr",
+        title="Usenet Audio",
+        author="Tester",
+        format="mp3",
+        content_type="audiobook",
+        search_mode=SearchMode.UNIVERSAL,
+    )
+
+    with patch("shelfmark.core.config.config") as mock_config:
+        mock_config.get = _build_config(ingest, organization="rename_and_group")
+        mock_config.CUSTOM_SCRIPT = None
+
+        result = _post_process_download(source_dir, task, Event(), lambda *_args: None)
+
+    grouped_dir = ingest / "Usenet Audiobook"
+    assert result is not None
+    assert Path(result).parent == grouped_dir
+    assert sorted(path.name for path in grouped_dir.glob("*.mp3")) == [
+        "Part 1.mp3",
+        "Part 2.mp3",
+    ]
+
+
 def test_archive_extraction_organize_multifile_can_use_original_name(tmp_path):
    from shelfmark.download.postprocess.router import (
        post_process_download as _post_process_download,
@@ -0,0 +1,46 @@
+import importlib
+from unittest.mock import Mock, patch
+
+import pytest
+
+
+@pytest.fixture(scope="module")
+def main_module():
+    with patch("shelfmark.download.orchestrator.start"):
+        import shelfmark.main as main
+
+        importlib.reload(main)
+        return main
+
+
+@pytest.mark.parametrize(
+    "headers",
+    [
+        {
+            "X-Forwarded-Proto": "https",
+            "X-Forwarded-Host": "library.example.com:12345",
+        },
+        {
+            "X-Forwarded-Proto": "https",
+            "X-Forwarded-Host": "library.example.com",
+            "X-Forwarded-Port": "12345",
+        },
+    ],
+)
+def test_oidc_redirect_uses_forwarded_external_port(main_module, headers):
+    oidc_client = Mock()
+    oidc_client.authorize_redirect.return_value = ("", 302)
+
+    with patch(
+        "shelfmark.core.oidc_routes._get_oidc_client",
+        return_value=(oidc_client, {}),
+    ):
+        response = main_module.app.test_client().get(
+            "/api/auth/oidc/login",
+            headers=headers,
+        )
+
+    assert response.status_code == 302
+    oidc_client.authorize_redirect.assert_called_once_with(
+        "https://library.example.com:12345/api/auth/oidc/callback"
+    )
@@ -568,11 +568,13 @@ class TestUserCRUD:
        user = user_db.create_user(username="john", role="user")
        user_db.update_user(
            user["id"],
+            username="jane",
            role="admin",
            email="new@example.com",
            auth_source="proxy",
        )
        updated = user_db.get_user(user_id=user["id"])
+        assert updated["username"] == "jane"
        assert updated["role"] == "admin"
        assert updated["email"] == "new@example.com"
        assert updated["auth_source"] == "proxy"
@@ -0,0 +1,131 @@
+"""A mirror that answers 200 with a non-AA page is quarantined, not reported as empty.
+
+Seized and for-sale domains keep serving 200. Without a look at *what* came back, a
+parking page is indistinguishable from a broken search, so the mirror stays in
+rotation and every later search pays for it again.
+"""
+
+import pytest
+from bs4 import Tag
+
+PARKED_PAGE = """<!doctype html><html><head><title>annas-archive.li</title></head>
+<body><h1>This domain is for sale</h1><p>Inquire now. Buy this domain.</p></body></html>"""
+
+AA_RESULTS_PAGE = """<!doctype html><html><body><main><table><tbody>
+<tr><td><a href="/md5/abc123"><img src="/c.jpg"></a></td><td><span>Dune</span></td></tr>
+</tbody></table></main></body></html>"""
+
+AA_EMPTY_PAGE = """<!doctype html><html><body><main>
+<div>No files found.</div><a href="https://annas-archive.gl/about">about</a>
+</main></body></html>"""
+
+DDOS_GUARD_PAGE = """<!doctype html><html><head><title>DDoS-Guard</title></head>
+<body><div id="ddos-guard">Checking your browser</div></body></html>"""
+
+
+class _Selector:
+    def __init__(self, bases: list[str]) -> None:
+        self._bases = bases
+        self._index = 0
+        self.current_base = bases[0]
+        self.quarantined: list[str] = []
+
+    def rewrite(self, url: str) -> str:
+        for base in self._bases:
+            if url.startswith(base):
+                return url.replace(base, self.current_base, 1)
+        return url
+
+    def next_mirror_or_rotate_dns(self, *, fatal: bool = False, reason: str = ""):
+        if fatal:
+            self.quarantined.append(self.current_base)
+        self._index += 1
+        if self._index >= len(self._bases):
+            return None, "exhausted"
+        self.current_base = self._bases[self._index]
+        return self.current_base, "mirror"
+
+
+def _patch_pages(monkeypatch, pages: list[str]):
+    """Serve `pages` in order, recording the URL each call was made against."""
+    import shelfmark.release_sources.direct_download as dd
+
+    calls: list[str] = []
+
+    def fake_get(url, **_kwargs):
+        calls.append(url)
+        return pages[len(calls) - 1] if len(calls) <= len(pages) else ""
+
+    monkeypatch.setattr(dd.downloader, "html_get_page", fake_get)
+    monkeypatch.setattr(dd.network, "get_available_aa_urls", lambda: ["a", "b", "c"])
+    return dd, calls
+
+
+def test_parked_mirror_is_quarantined_and_search_retries_next_mirror(monkeypatch):
+    dd, calls = _patch_pages(monkeypatch, [PARKED_PAGE, AA_RESULTS_PAGE])
+    selector = _Selector(["https://parked.test", "https://real.test"])
+
+    html, table = dd._fetch_search_table("https://parked.test/search?q=dune", selector)
+
+    assert selector.quarantined == ["https://parked.test"]
+    assert isinstance(table, Tag)
+    assert "Dune" in html
+    # The retry went to the live mirror, not back to the parked one.
+    assert calls[1].startswith("https://real.test")
+
+
+def test_genuinely_empty_aa_result_does_not_quarantine(monkeypatch):
+    """'No files found.' is a real answer from a healthy mirror."""
+    dd, _calls = _patch_pages(monkeypatch, [AA_EMPTY_PAGE])
+    selector = _Selector(["https://real.test", "https://other.test"])
+
+    html, table = dd._fetch_search_table("https://real.test/search?q=zzz", selector)
+
+    assert selector.quarantined == []
+    assert table is None
+    assert "No files found." in html
+
+
+def test_challenge_page_is_reported_not_passed_off_as_an_empty_result(monkeypatch):
+    """An unsolved interstitial means the search never ran.
+
+    The mirror is alive and holds our clearance, so it must not be quarantined - but
+    returning it as "no table" made the caller tell the user their query found nothing.
+    """
+    dd, _calls = _patch_pages(monkeypatch, [DDOS_GUARD_PAGE])
+    selector = _Selector(["https://real.test", "https://other.test"])
+
+    with pytest.raises(dd.SearchUnavailableError, match="protection challenge"):
+        dd._fetch_search_table("https://real.test/search?q=dune", selector)
+
+    assert selector.quarantined == []
+
+
+def test_unreachable_mirror_raises_search_unavailable(monkeypatch):
+    dd, _calls = _patch_pages(monkeypatch, [""])
+    selector = _Selector(["https://real.test"])
+
+    try:
+        dd._fetch_search_table("https://real.test/search?q=dune", selector)
+    except dd.SearchUnavailableError:
+        return
+    raise AssertionError("expected SearchUnavailableError")
+
+
+def test_recorded_failure_reason_is_surfaced_to_the_caller(monkeypatch):
+    """The concrete give-up reason html_get_page stashed replaces the generic line."""
+    import shelfmark.release_sources.direct_download as dd
+
+    reason = "Anna's Archive returned 403 (blocked) and no bypasser is enabled."
+
+    def fake_get(url, *, selector=None, **_kwargs):
+        selector.last_failure = reason
+        return ""
+
+    monkeypatch.setattr(dd.downloader, "html_get_page", fake_get)
+    monkeypatch.setattr(dd.network, "get_available_aa_urls", lambda: ["a"])
+    selector = _Selector(["https://real.test"])
+    selector.last_failure = None
+
+    with pytest.raises(dd.SearchUnavailableError, match="403 .blocked."):
+        dd._fetch_search_table("https://real.test/search?q=dune", selector)
@@ -0,0 +1,61 @@
+"""Tests for the stall-detection activity grace signalling."""
+
+import pytest
+
+from shelfmark.core.models import QueueStatus
+from shelfmark.download.activity import (
+    ACTIVITY_GRACE_STATUS,
+    parse_activity_grace,
+    release_activity_grace,
+    request_activity_grace,
+)
+
+
+def test_request_and_parse_round_trip():
+    calls: list[tuple[str, str | None]] = []
+    request_activity_grace(lambda status, message: calls.append((status, message)), 330)
+
+    assert len(calls) == 1
+    assert parse_activity_grace(*calls[0]) == 330.0
+
+
+def test_release_emits_zero_grace():
+    calls: list[tuple[str, str | None]] = []
+    release_activity_grace(lambda status, message: calls.append((status, message)))
+
+    assert parse_activity_grace(*calls[0]) == 0.0
+
+
+def test_parse_returns_none_for_real_status_events():
+    assert parse_activity_grace("resolving", "Bypassing protection...") is None
+    assert parse_activity_grace("downloading", None) is None
+
+
+@pytest.mark.parametrize("status", [s.value for s in QueueStatus])
+def test_sentinel_cannot_collide_with_a_queue_status(status):
+    """The sentinel must never be mistaken for a real status, or vice versa."""
+    assert status != ACTIVITY_GRACE_STATUS
+    assert parse_activity_grace(status, "anything") is None
+
+
+def test_parse_tolerates_a_malformed_sentinel():
+    """A bad emitter must not take down the status pipeline."""
+    assert parse_activity_grace(ACTIVITY_GRACE_STATUS, "not-a-number") == 0.0
+    assert parse_activity_grace(ACTIVITY_GRACE_STATUS, None) == 0.0
+
+
+def test_parse_clamps_negative_grace():
+    assert parse_activity_grace(ACTIVITY_GRACE_STATUS, "-5") == 0.0
+
+
+def test_emitters_are_noops_without_a_callback():
+    request_activity_grace(None, 30)
+    release_activity_grace(None)
+
+
+def test_emitters_swallow_a_raising_callback():
+    def boom(_status: str, _message: str | None) -> None:
+        raise RuntimeError("callback failed")
+
+    request_activity_grace(boom, 30)
+    release_activity_grace(boom)
@@ -0,0 +1,143 @@
+"""RFC 8484 wireformat codec.
+
+Quad9 and OpenDNS reject the JSON API that Cloudflare and Google popularised, so
+these providers only work through wireformat. Quad9 additionally requires HTTP/2
+(section 5.2) and answers HTTP/1.1 with 505.
+"""
+
+import base64
+import struct
+
+import pytest
+
+from shelfmark.download import doh_wireformat as wf
+
+
+def _decode_param(param: str) -> bytes:
+    padding = "=" * (-len(param) % 4)
+    return base64.urlsafe_b64decode(param + padding)
+
+
+def _build_response(
+    *, qname: str = "example.com", answers: list[tuple[int, bytes]], qtype: int = wf.TYPE_A
+) -> bytes:
+    """Assemble a response whose answer names are compression pointers to the question."""
+    question = b""
+    for label in qname.split("."):
+        question += bytes([len(label)]) + label.encode()
+    question += b"\x00" + struct.pack(">HH", qtype, 1)
+
+    body = b""
+    for rtype, rdata in answers:
+        body += b"\xc0\x0c"  # pointer to offset 12 (the question name)
+        body += struct.pack(">HHIH", rtype, 1, 300, len(rdata)) + rdata
+
+    header = struct.pack(">HHHHHH", 0, 0x8180, 1, len(answers), 0, 0)
+    return header + question + body
+
+
+def test_encode_query_is_a_well_formed_dns_message():
+    raw = _decode_param(wf.encode_query_param("example.com", wf.TYPE_A))
+
+    msg_id, flags, qdcount, ancount, _ns, _ar = struct.unpack_from(">HHHHHH", raw, 0)
+    assert msg_id == 0  # RFC 8484 section 4.1: zero for cacheability
+    assert flags == 0x0100  # recursion desired
+    assert (qdcount, ancount) == (1, 0)
+    assert raw[12:] == b"\x07example\x03com\x00" + struct.pack(">HH", wf.TYPE_A, 1)
+
+
+def test_encode_query_param_is_unpadded_base64url():
+    param = wf.encode_query_param("example.com", wf.TYPE_A)
+    assert "=" not in param
+    assert "+" not in param and "/" not in param
+
+
+def test_encode_query_strips_trailing_dot():
+    assert _decode_param(wf.encode_query_param("example.com.", wf.TYPE_A)) == _decode_param(
+        wf.encode_query_param("example.com", wf.TYPE_A)
+    )
+
+
+def test_encode_query_rejects_empty_hostname():
+    with pytest.raises(wf.WireformatError):
+        wf.encode_query("", wf.TYPE_A)
+
+
+def test_encode_query_rejects_oversized_label():
+    with pytest.raises(wf.WireformatError):
+        wf.encode_query("a" * 64 + ".com", wf.TYPE_A)
+
+
+def test_decode_a_records():
+    response = _build_response(answers=[(wf.TYPE_A, bytes([93, 184, 216, 34]))])
+    assert wf.decode_answer(response, wf.TYPE_A) == ["93.184.216.34"]
+
+
+def test_decode_multiple_a_records_preserves_order():
+    response = _build_response(
+        answers=[(wf.TYPE_A, bytes([1, 1, 1, 1])), (wf.TYPE_A, bytes([8, 8, 8, 8]))]
+    )
+    assert wf.decode_answer(response, wf.TYPE_A) == ["1.1.1.1", "8.8.8.8"]
+
+
+def test_decode_skips_cname_records_in_the_chain():
+    """Answers routinely lead with a CNAME; only the requested type is an address."""
+    cname = b"\x03www\x07example\x03com\x00"
+    response = _build_response(answers=[(5, cname), (wf.TYPE_A, bytes([93, 184, 216, 34]))])
+    assert wf.decode_answer(response, wf.TYPE_A) == ["93.184.216.34"]
+
+
+def test_decode_aaaa_compresses_zero_run():
+    # 2606:4700:0:0:0:0:6810:84e5 -> the middle zero run collapses to "::"
+    rdata = struct.pack(">8H", 0x2606, 0x4700, 0, 0, 0, 0, 0x6810, 0x84E5)
+    response = _build_response(answers=[(wf.TYPE_AAAA, rdata)], qtype=wf.TYPE_AAAA)
+    assert wf.decode_answer(response, wf.TYPE_AAAA) == ["2606:4700::6810:84e5"]
+
+
+def test_decode_aaaa_collapses_only_the_longest_zero_run():
+    # 2001:0:0:1:0:0:0:1 - the second, longer run is the one that collapses.
+    rdata = struct.pack(">8H", 0x2001, 0, 0, 1, 0, 0, 0, 1)
+    response = _build_response(answers=[(wf.TYPE_AAAA, rdata)], qtype=wf.TYPE_AAAA)
+    assert wf.decode_answer(response, wf.TYPE_AAAA) == ["2001:0:0:1::1"]
+
+
+def test_decode_aaaa_without_zero_run():
+    rdata = struct.pack(">8H", 0x2001, 0x0DB8, 1, 2, 3, 4, 5, 6)
+    response = _build_response(answers=[(wf.TYPE_AAAA, rdata)], qtype=wf.TYPE_AAAA)
+    assert wf.decode_answer(response, wf.TYPE_AAAA) == ["2001:db8:1:2:3:4:5:6"]
+
+
+def test_decode_nxdomain_returns_empty_not_an_error():
+    """An empty answer is a valid response; the caller falls back rather than retrying."""
+    response = _build_response(answers=[])
+    assert wf.decode_answer(response, wf.TYPE_A) == []
+
+
+def test_decode_rejects_truncated_header():
+    with pytest.raises(wf.WireformatError):
+        wf.decode_answer(b"\x00\x01", wf.TYPE_A)
+
+
+def test_decode_rejects_truncated_record():
+    response = _build_response(answers=[(wf.TYPE_A, bytes([1, 2, 3, 4]))])
+    with pytest.raises(wf.WireformatError):
+        wf.decode_answer(response[:-2], wf.TYPE_A)
+
+
+def test_decode_does_not_hang_on_a_malicious_name():
+    """A self-referential name must not loop forever."""
+    header = struct.pack(">HHHHHH", 0, 0x8180, 1, 0, 0, 0)
+    # A run of maximum-length labels that never terminates.
+    body = (b"\x3f" + b"a" * 63) * 8
+    with pytest.raises(wf.WireformatError):
+        wf.decode_answer(header + body, wf.TYPE_A)
+
+
+def test_wireformat_providers_are_flagged(monkeypatch):
+    """The provider table and the resolver must agree on who needs wireformat."""
+    import shelfmark.download.network as network
+
+    for name, servers, url in network.DNS_PROVIDERS:
+        resolver = network.DoHResolver(url, "x.invalid", servers[0])
+        expected = name in ("quad9", "opendns")
+        assert resolver.use_wireformat is expected, f"{name} wireformat flag wrong"
@@ -0,0 +1,170 @@
+"""Transfers into destinations that accept writes but refuse deletes.
+
+Reproduces the Synology case from issue #1174: a share where "Delete subfolders
+and files" is unticked. Creating files is allowed, but `os.replace()` cannot
+publish a temp file into place because renaming removes a directory entry.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+from pathlib import Path
+
+import pytest
+
+from shelfmark.download import fs
+from shelfmark.download.fs import atomic_copy, atomic_move
+
+CONTENT = b"a book" * 1024
+
+
+@pytest.fixture(autouse=True)
+def _reset_delete_denied():
+    fs._DELETE_DENIED_DIRS.clear()
+    yield
+    fs._DELETE_DENIED_DIRS.clear()
+
+
+@pytest.fixture
+def source(tmp_path: Path) -> Path:
+    src = tmp_path / "tmp_dir" / "staged.epub"
+    src.parent.mkdir()
+    src.write_bytes(CONTENT)
+    return src
+
+
+@pytest.fixture
+def library(tmp_path: Path) -> Path:
+    lib = tmp_path / "library"
+    lib.mkdir()
+    return lib
+
+
+def _leftover_temps(directory: Path) -> list[Path]:
+    return list(directory.glob(".shelfmark.*"))
+
+
+def _deny_replace(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Make os.replace fail the way a no-delete share does."""
+
+    def fake_replace(src, dst, *args, **kwargs):
+        raise PermissionError(errno.EACCES, "Permission denied", str(dst))
+
+    monkeypatch.setattr(fs.os, "replace", fake_replace)
+
+
+def test_copy_writes_in_place_when_destination_is_known_undeletable(
+    source: Path, library: Path
+) -> None:
+    fs.mark_delete_denied(library)
+
+    final_path = atomic_copy(source, library / "book.epub")
+
+    assert final_path == library / "book.epub"
+    assert final_path.read_bytes() == CONTENT
+    # The temp file is skipped entirely, so nothing is stranded in the library.
+    assert _leftover_temps(library) == []
+    assert source.exists()
+
+
+def test_copy_falls_back_when_rename_is_refused(
+    source: Path, library: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Cold cache: the denial is discovered at publish time and recovered from."""
+    _deny_replace(monkeypatch)
+
+    final_path = atomic_copy(source, library / "book.epub")
+
+    assert final_path.read_bytes() == CONTENT
+    assert _leftover_temps(library) == []
+    # The destination is remembered so later transfers skip the temp file.
+    assert fs.is_delete_denied(library) is True
+
+
+def test_move_falls_back_to_copy_and_removes_source(source: Path, library: Path) -> None:
+    fs.mark_delete_denied(library)
+
+    final_path = atomic_move(source, library / "book.epub")
+
+    assert final_path.read_bytes() == CONTENT
+    assert not source.exists()
+    assert _leftover_temps(library) == []
+
+
+def test_move_falls_back_when_rename_is_refused(
+    source: Path, library: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    real_rename = fs.os.rename
+
+    def fake_rename(src, dst, *args, **kwargs):
+        if str(dst).startswith(str(library)):
+            raise PermissionError(errno.EACCES, "Permission denied", str(dst))
+        return real_rename(src, dst, *args, **kwargs)
+
+    monkeypatch.setattr(fs.os, "rename", fake_rename)
+    _deny_replace(monkeypatch)
+
+    final_path = atomic_move(source, library / "book.epub")
+
+    assert final_path.read_bytes() == CONTENT
+    assert not source.exists()
+    assert fs.is_delete_denied(library) is True
+
+
+def test_in_place_copy_still_resolves_collisions(source: Path, library: Path) -> None:
+    fs.mark_delete_denied(library)
+    (library / "book.epub").write_bytes(b"existing")
+
+    final_path = atomic_copy(source, library / "book.epub")
+
+    assert final_path == library / "book_1.epub"
+    assert final_path.read_bytes() == CONTENT
+    # The pre-existing file is never overwritten.
+    assert (library / "book.epub").read_bytes() == b"existing"
+
+
+def test_denial_applies_to_subdirectories(source: Path, library: Path) -> None:
+    """`organize` mode writes into per-author subfolders under the library root."""
+    fs.mark_delete_denied(library)
+    nested = library / "Frank Herbert" / "Dune"
+    nested.mkdir(parents=True)
+
+    assert fs.is_delete_denied(nested) is True
+
+    final_path = atomic_copy(source, nested / "book.epub")
+
+    assert final_path.read_bytes() == CONTENT
+    assert _leftover_temps(nested) == []
+
+
+def test_clearing_a_denial_also_clears_subdirectories(library: Path) -> None:
+    nested = library / "Frank Herbert"
+    fs.mark_delete_denied(library)
+    fs.mark_delete_denied(nested)
+
+    fs.clear_delete_denied(library)
+
+    assert fs.is_delete_denied(library) is False
+    assert fs.is_delete_denied(nested) is False
+
+
+def test_normal_destination_still_publishes_atomically(
+    source: Path, library: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Regression guard: unaffected shares keep the temp-file + rename path."""
+    replaced: list[tuple[str, str]] = []
+    real_replace = os.replace
+
+    def spy_replace(src, dst, *args, **kwargs):
+        replaced.append((str(src), str(dst)))
+        return real_replace(src, dst, *args, **kwargs)
+
+    monkeypatch.setattr(fs.os, "replace", spy_replace)
+
+    final_path = atomic_copy(source, library / "book.epub")
+
+    assert final_path.read_bytes() == CONTENT
+    assert len(replaced) == 1
+    assert Path(replaced[0][0]).name.startswith(".shelfmark.")
+    assert fs.is_delete_denied(library) is False
@@ -27,6 +27,7 @@ class _DummySelector:
        self._index = 0
        self.current_base = bases[0]
        self.attempts_this_dns = 0
+        self.quarantined: list[tuple[str, str]] = []

    def rewrite(self, url: str) -> str:
        for base in self._bases:
@@ -34,7 +35,11 @@ class _DummySelector:
                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 next_mirror_or_rotate_dns(
+        self, allow_dns: bool = True, *, fatal: bool = False, reason: str = ""
+    ) -> tuple[str | None, str]:
+        if fatal:
+            self.quarantined.append((self.current_base, reason))
        self.attempts_this_dns += 1
        self._index = (self._index + 1) % len(self._bases)
        self.current_base = self._bases[self._index]
@@ -149,3 +154,50 @@ def test_html_get_page_locked_aa_does_not_fail_over_on_cross_host_redirect(monke

    assert html == ""
    assert calls == ["https://annas-archive.li/search?q=test"]
+
+
+def test_html_get_page_echoes_cookies_across_same_host_redirects(monkeypatch):
+    """DDoS-Guard's ?check=1 probe is cleared by echoing the Set-Cookie it issues.
+
+    Without this the __ddg* cookie is dropped on every hop, the server re-issues the same
+    redirect, and the request dies with TooManyRedirects.
+    """
+    import shelfmark.download.http as http
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: False)
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http.time, "sleep", lambda _s: None)
+    monkeypatch.setattr(http.network, "get_aa_base_url", lambda: "https://annas-archive.li")
+    monkeypatch.setattr(http.network, "is_aa_auto_mode", lambda: True)
+
+    sent_cookies: list[dict[str, str]] = []
+
+    def fake_get(url: str, **kwargs):
+        sent_cookies.append(dict(kwargs["cookies"]))
+        if url == "https://annas-archive.li/search?q=test":
+            response = _FakeResponse(302, headers={"Location": "/search?q=test&check=1"}, url=url)
+            response.cookies = {"__ddg2_": "probe"}
+            return response
+        if url == "https://annas-archive.li/search?q=test&check=1":
+            # The probe only clears if the cookie comes back on this hop.
+            if kwargs["cookies"].get("__ddg2_") != "probe":
+                response = _FakeResponse(
+                    302, headers={"Location": "/search?q=test&check=1"}, url=url
+                )
+                response.cookies = {"__ddg2_": "probe"}
+                return response
+            return _FakeResponse(200, text="RESULTS", url=url)
+        raise AssertionError(f"Unexpected URL: {url}")
+
+    monkeypatch.setattr(http.requests, "get", fake_get)
+
+    selector = _DummySelector(["https://annas-archive.li"])
+    html = http.html_get_page(
+        "https://annas-archive.li/search?q=test",
+        selector=selector,
+        retry=1,
+        allow_bypasser_fallback=False,
+    )
+
+    assert html == "RESULTS"
+    assert sent_cookies == [{}, {"__ddg2_": "probe"}]
@@ -11,22 +11,141 @@ class _FakeResponse:
        self.url = url


-class _ImmediateThread:
-    def __init__(self, *args, **kwargs) -> None:
-        self._target = kwargs["target"]
+def test_external_bypasser_clearance_is_presented_on_the_next_request(monkeypatch):
+    """Clearance is read from the shared store whichever bypasser filled it.

-    def start(self) -> None:
-        self._target()
+    Guards the regression where the external path returned {} unconditionally: every
+    request re-paid a 403 plus a full solve, and a download - which the solver cannot
+    proxy - presented no clearance at all.
+    """
+    import shelfmark.bypass.cookie_store as cookie_store
+    import shelfmark.download.http as http

-    def join(self, timeout: float | None = None) -> None:
-        del timeout
+    monkeypatch.setattr(cookie_store, "_cf_cookies", {})
+    monkeypatch.setattr(cookie_store, "_cf_user_agents", {})
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_is_using_external_bypasser", lambda: True)
+
+    cookie_store.store_extracted_cookies(
+        url="https://annas-archive.gl/search",
+        cookies=[{"name": "__ddg1_", "value": "clearance"}],
+        user_agent="Mozilla/5.0 (solver)",
+    )
+
+    headers: dict[str, str] = {}
+    cookies = http._apply_cf_bypass("https://annas-archive.gl/md5/abc", headers)
+
+    assert cookies == {"__ddg1_": "clearance"}
+    assert headers["User-Agent"] == "Mozilla/5.0 (solver)"


-def test_html_get_page_ignores_heartbeat_callback_failure(monkeypatch):
+def test_external_bypasser_solve_is_reused_instead_of_re_solved(monkeypatch):
+    """One solve should clear the following requests, not just the one that paid for it.
+
+    A solve is tens of seconds of real browser, so re-running it per request is what
+    made direct download unusable behind an external bypasser.
+    """
+    import shelfmark.bypass.cookie_store as cookie_store
+    import shelfmark.download.http as http
+
+    monkeypatch.setattr(cookie_store, "_cf_cookies", {})
+    monkeypatch.setattr(cookie_store, "_cf_user_agents", {})
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_is_using_external_bypasser", lambda: True)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 100.0)
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: False)
+    monkeypatch.setattr(http.time, "sleep", lambda _seconds: None)
+
+    class _Cleared:
+        is_redirect = False
+        status_code = 200
+        cookies: dict[str, str] = {}
+        text = "<table>results</table>"
+        url = "https://annas-archive.gl/search?q=dune"
+
+        def raise_for_status(self) -> None:
+            return None
+
+    def gated_get(url: str, **kwargs):
+        if kwargs.get("cookies", {}).get("cf_clearance") != "token":
+            error = requests.exceptions.HTTPError("forbidden")
+            error.response = _FakeResponse(403, url=url)
+            raise error
+        return _Cleared()
+
+    solves: list[str] = []
+
+    def fake_solve(url: str, *_args, **_kwargs):
+        solves.append(url)
+        cookie_store.store_extracted_cookies(
+            url=url,
+            cookies=[{"name": "cf_clearance", "value": "token"}],
+            user_agent="Mozilla/5.0 (solver)",
+        )
+        return "<table>results</table>"
+
+    monkeypatch.setattr(http.requests, "get", gated_get)
+    monkeypatch.setattr(http, "get_bypassed_page", fake_solve)
+
+    url = "https://annas-archive.gl/search?q=dune"
+    first = http.html_get_page(url, retry=2, allow_bypasser_fallback=True, success_delay=0)
+    second = http.html_get_page(url, retry=2, allow_bypasser_fallback=True, success_delay=0)
+
+    assert first == "<table>results</table>"
+    assert second == "<table>results</table>"
+    # The second request rode the stored clearance instead of paying for another solve.
+    assert solves == [url]
+
+
+def test_403_with_a_concurrently_won_clearance_still_reaches_the_bypasser(monkeypatch):
+    """The last attempt must hand off, not `continue` into the end of the loop.
+
+    Another worker's solve can land between our request and its 403, which used to
+    send this branch back round the retry loop - but on the final attempt (and
+    MAX_RETRY=1 is the supported setting) `continue` just ends it, abandoning the
+    request without ever offering the URL to the bypasser.
+    """
    import shelfmark.download.http as http

    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
-    monkeypatch.setattr(http, "Thread", _ImmediateThread)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 100.0)
+    # A concurrent solve has filled the store, but this request went out before it did.
+    monkeypatch.setattr(http, "get_cf_cookies_for_domain", lambda _hostname: {"__ddg1_": "fresh"})
+    monkeypatch.setattr(http, "_apply_cf_bypass", lambda _url, _headers: {})
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: False)
+    monkeypatch.setattr(http.time, "sleep", lambda _seconds: None)
+
+    def gated(url: str, **_kwargs):
+        error = requests.exceptions.HTTPError("forbidden")
+        error.response = _FakeResponse(403, url=url)
+        raise error
+
+    bypassed: list[str] = []
+    monkeypatch.setattr(http.requests, "get", gated)
+    monkeypatch.setattr(
+        http,
+        "get_bypassed_page",
+        lambda url, *_a, **_k: bypassed.append(url) or "<table>results</table>",
+    )
+
+    url = "https://annas-archive.gl/search?q=dune"
+    html = http.html_get_page(url, retry=1, allow_bypasser_fallback=True, success_delay=0)
+
+    assert html == "<table>results</table>"
+    assert bypassed == [url]
+
+
+def test_html_get_page_ignores_status_callback_failure(monkeypatch):
+    """A raising status_callback must not break the bypass it was reporting on."""
+    import shelfmark.download.http as http
+    from shelfmark.download.activity import ACTIVITY_GRACE_STATUS
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 330.0)
    monkeypatch.setattr(http, "get_bypassed_page", lambda *_args, **_kwargs: "OK")

    calls: list[tuple[str, str | None]] = []
@@ -46,10 +165,92 @@ def test_html_get_page_ignores_heartbeat_callback_failure(monkeypatch):
    assert html == "OK"
    assert calls == [
        ("resolving", "Bypassing protection..."),
-        ("resolving", "Bypassing protection..."),
+        (ACTIVITY_GRACE_STATUS, "330.0"),
+        (ACTIVITY_GRACE_STATUS, "0.0"),
    ]


+def test_html_get_page_requests_and_releases_activity_grace(monkeypatch):
+    """The bypass declares its budget before blocking and releases it afterwards."""
+    import shelfmark.download.http as http
+    from shelfmark.download.activity import ACTIVITY_GRACE_STATUS
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 424.0)
+
+    calls: list[tuple[str, str | None]] = []
+
+    def fake_bypass(*_args, **_kwargs):
+        # The grace must already be in place before the long blocking call starts.
+        assert calls[-1] == (ACTIVITY_GRACE_STATUS, "424.0")
+        return "OK"
+
+    monkeypatch.setattr(http, "get_bypassed_page", fake_bypass)
+
+    html = http.html_get_page(
+        "https://example.com",
+        retry=1,
+        use_bypasser=True,
+        status_callback=lambda status, message: calls.append((status, message)),
+    )
+
+    assert html == "OK"
+    assert calls[-1] == (ACTIVITY_GRACE_STATUS, "0.0")
+
+
+def test_html_get_page_releases_grace_and_reports_error_when_bypasser_fails(monkeypatch):
+    """A failing bypasser surfaces its real error instead of a silent empty result."""
+    import shelfmark.download.http as http
+    from shelfmark.download.activity import ACTIVITY_GRACE_STATUS
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 100.0)
+
+    def failing_bypasser(*_args, **_kwargs):
+        raise requests.exceptions.RequestException("500 Server Error")
+
+    monkeypatch.setattr(http, "get_bypassed_page", failing_bypasser)
+
+    calls: list[tuple[str, str | None]] = []
+    html = http.html_get_page(
+        "https://example.com",
+        retry=1,
+        use_bypasser=True,
+        status_callback=lambda status, message: calls.append((status, message)),
+    )
+
+    assert html == ""
+    errors = [message for status, message in calls if status == "error"]
+    assert len(errors) == 1
+    assert "500 Server Error" in (errors[0] or "")
+    # The grace is always released, even on the failure path.
+    assert calls[-1] == (ACTIVITY_GRACE_STATUS, "0.0")
+
+
+def test_html_get_page_does_not_report_error_when_bypass_is_cancelled(monkeypatch):
+    """Cancellation is a user action, not a failure worth surfacing as an error."""
+    import shelfmark.download.http as http
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 100.0)
+
+    def cancelled_bypasser(*_args, **_kwargs):
+        raise BypassCancelledError("Bypass cancelled")
+
+    monkeypatch.setattr(http, "get_bypassed_page", cancelled_bypasser)
+
+    calls: list[tuple[str, str | None]] = []
+    html = http.html_get_page(
+        "https://example.com",
+        retry=1,
+        use_bypasser=True,
+        status_callback=lambda status, message: calls.append((status, message)),
+    )
+
+    assert html == ""
+    assert [status for status, _message in calls if status == "error"] == []
+
+
 def test_html_get_page_returns_empty_on_bypass_cancellation(monkeypatch):
    import shelfmark.download.http as http

@@ -65,6 +266,104 @@ def test_html_get_page_returns_empty_on_bypass_cancellation(monkeypatch):
    assert html == ""


+def test_challenged_search_switches_to_bypasser(monkeypatch):
+    """AA gates /search behind DDoS-Guard; the 403 must reach the bypasser, not a 503.
+
+    Guards the regression where search passed allow_bypasser_fallback=False, so a
+    challenge on every mirror surfaced as "mirrors are blocked" with no solve attempted.
+    """
+    import shelfmark.download.http as http
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 100.0)
+    monkeypatch.setattr(http, "get_cf_cookies_for_domain", lambda _hostname: {})
+    monkeypatch.setattr(http, "_apply_cf_bypass", lambda _url, _headers: {})
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: False)
+    monkeypatch.setattr(http.time, "sleep", lambda _seconds: None)
+
+    def ddos_guarded(url: str, **_kwargs):
+        error = requests.exceptions.HTTPError("forbidden")
+        error.response = _FakeResponse(403, url=url)
+        raise error
+
+    bypassed: list[str] = []
+    monkeypatch.setattr(http.requests, "get", ddos_guarded)
+    monkeypatch.setattr(
+        http,
+        "get_bypassed_page",
+        lambda url, *_a, **_k: bypassed.append(url) or "<table>results</table>",
+    )
+
+    html = http.html_get_page(
+        "https://annas-archive.gl/search?q=dune",
+        retry=10,
+        allow_bypasser_fallback=True,
+        success_delay=0,
+    )
+
+    assert html == "<table>results</table>"
+    assert bypassed == ["https://annas-archive.gl/search?q=dune"]
+
+
+def test_redirect_loop_purges_stale_cookies_and_switches_to_bypasser(monkeypatch):
+    """A stale clearance cookie turns the gate into a `?check=1` redirect loop.
+
+    Guards the regression where TooManyRedirects carried no status code, so the
+    403-only rescue never fired and every retry re-sent the dead cookie.
+    """
+    import shelfmark.download.http as http
+
+    stale = {"__ddg8_": "stale"}
+    cleared: list[str] = []
+
+    def fake_clear(domain: str) -> None:
+        cleared.append(domain)
+        stale.clear()
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_is_using_external_bypasser", lambda: False)
+    monkeypatch.setattr(http.cookie_store, "clear_cf_cookies", fake_clear)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 100.0)
+    monkeypatch.setattr(http, "_apply_cf_bypass", lambda _url, _headers: dict(stale))
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: True)
+    monkeypatch.setattr(http.network, "is_aa_auto_mode", lambda: True)
+    monkeypatch.setattr(http.time, "sleep", lambda _seconds: None)
+
+    sent_cookies: list[dict[str, str]] = []
+
+    def check_redirect(url: str, **kwargs):
+        sent_cookies.append(kwargs["cookies"])
+        response = _FakeResponse(302, url=url)
+        response.is_redirect = True
+        response.headers = {"Location": f"{url}&check=1"}
+        return response
+
+    bypassed: list[str] = []
+    monkeypatch.setattr(http.requests, "get", check_redirect)
+    monkeypatch.setattr(
+        http,
+        "get_bypassed_page",
+        lambda url, *_a, **_k: bypassed.append(url) or "<table>results</table>",
+    )
+
+    html = http.html_get_page(
+        "https://annas-archive.gl/search?q=dune",
+        retry=10,
+        allow_bypasser_fallback=True,
+        success_delay=0,
+    )
+
+    assert html == "<table>results</table>"
+    assert cleared == ["annas-archive.gl"]
+    assert len(bypassed) == 1
+    # Escaped on the first exception, not retried with the dead cookie.
+    assert sent_cookies[0] == {"__ddg8_": "stale"}
+
+
 def test_download_url_ignores_zlib_cookie_refresh_failure(monkeypatch):
    import shelfmark.download.http as http

@@ -110,3 +409,138 @@ def test_get_bypassed_page_uses_external_bypasser_when_enabled(monkeypatch):

    assert http.get_bypassed_page("https://example.com", selector, cancel_flag) == "EXT"
    assert calls == [("https://example.com", selector, cancel_flag)]
+
+
+def test_redirect_loop_gives_up_immediately_when_bypasser_not_allowed(monkeypatch):
+    """A loop the bypasser may not rescue must fail fast, not burn the retry budget.
+
+    Guards the regression where the unrescued loop raised TooManyRedirects into the
+    retry path: that error is not retryable and carries no status, so every attempt
+    re-ran the full 6-redirect loop for ~60 requests to AA before giving up.
+    """
+    import shelfmark.download.http as http
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_apply_cf_bypass", lambda _url, _headers: {})
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: True)
+    monkeypatch.setattr(http.network, "is_aa_auto_mode", lambda: True)
+    monkeypatch.setattr(http.time, "sleep", lambda _seconds: None)
+
+    requested: list[str] = []
+
+    def check_redirect(url: str, **_kwargs):
+        requested.append(url)
+        response = _FakeResponse(302, url=url)
+        response.is_redirect = True
+        response.headers = {"Location": f"{url}&check=1"}
+        return response
+
+    def unreachable_bypasser(*_args, **_kwargs):
+        msg = "bypasser must not run when allow_bypasser_fallback is False"
+        raise AssertionError(msg)
+
+    monkeypatch.setattr(http.requests, "get", check_redirect)
+    monkeypatch.setattr(http, "get_bypassed_page", unreachable_bypasser)
+
+    html = http.html_get_page(
+        "https://annas-archive.gl/dyn/md5/summary/abc",
+        retry=10,
+        allow_bypasser_fallback=False,
+        success_delay=0,
+    )
+
+    assert html == ""
+    # One pass through the redirect cap, not one pass per retry attempt.
+    assert len(requested) == http._MAX_REDIRECTS + 1
+
+
+def test_html_get_page_redirect_loop_purges_cookies_and_bypasses(monkeypatch):
+    """A redirect loop is the challenge served against stale cookies, not a retryable error.
+
+    TooManyRedirects carries no status code, so without an explicit branch it falls through
+    to the generic retry path and repeats the identical failure for the whole retry budget.
+    """
+    import shelfmark.download.http as http
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_is_using_external_bypasser", lambda: False)
+    monkeypatch.setattr(http, "_bypass_grace_seconds", lambda: 330.0)
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http.time, "sleep", lambda _s: None)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: True)
+    monkeypatch.setattr(http.network, "get_aa_base_url", lambda: "https://annas-archive.li")
+    monkeypatch.setattr(http.network, "is_aa_auto_mode", lambda: False)
+
+    cleared: list[str] = []
+
+    monkeypatch.setattr(http.cookie_store, "clear_cf_cookies", cleared.append)
+    monkeypatch.setattr(
+        http.cookie_store, "get_cf_cookies_for_domain", lambda _domain: {"__ddg2_": "stale"}
+    )
+    monkeypatch.setattr(http.cookie_store, "get_cf_user_agent_for_domain", lambda _domain: None)
+    monkeypatch.setattr(http, "get_bypassed_page", lambda *_args, **_kwargs: "SOLVED")
+
+    class _FakeRedirect:
+        """A 302 that always points at the same ?check=1 URL, cookies unchanged."""
+
+        is_redirect = True
+        status_code = 302
+        cookies = {"__ddg2_": "stale"}
+
+        def __init__(self, url: str) -> None:
+            self.url = url
+            self.headers = {"Location": "https://annas-archive.li/search?q=test&check=1"}
+
+    hits: list[str] = []
+
+    def fake_get(url: str, **kwargs):
+        hits.append(url)
+        # Stale cookies: the server keeps re-issuing the same ?check=1 redirect.
+        return _FakeRedirect(url)
+
+    monkeypatch.setattr(http.requests, "get", fake_get)
+
+    html = http.html_get_page(
+        "https://annas-archive.li/search?q=test",
+        retry=2,
+        success_delay=0,
+    )
+
+    assert html == "SOLVED"
+    assert cleared == ["annas-archive.li"]
+    # The loop is cut short: no second attempt spent repeating the same redirects.
+    assert len(hits) == http._MAX_REDIRECTS + 1
+
+
+def test_html_get_page_redirect_loop_on_non_aa_host_is_left_alone(monkeypatch):
+    """Only hosts whose redirects we follow manually get the challenge treatment.
+
+    Elsewhere requests follows redirects itself, so a loop is an ordinary misconfiguration -
+    purging that host's cookies and forcing a bypass would be the wrong response.
+    """
+    import shelfmark.download.http as http
+
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_is_using_external_bypasser", lambda: False)
+    monkeypatch.setattr(http, "_apply_cf_bypass", lambda _url, _headers: {})
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(http.time, "sleep", lambda _s: None)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: False)
+
+    bypassed: list[str] = []
+    monkeypatch.setattr(
+        http, "get_bypassed_page", lambda url, *_args, **_kwargs: bypassed.append(url) or "SOLVED"
+    )
+
+    def fake_get(_url: str, **_kwargs):
+        raise requests.exceptions.TooManyRedirects("Exceeded 30 redirects.")
+
+    monkeypatch.setattr(http.requests, "get", fake_get)
+
+    html = http.html_get_page("https://example.com/loop", retry=2, success_delay=0)
+
+    assert html == ""
+    assert bypassed == []
@@ -0,0 +1,127 @@
+"""Tests for handing a 503 that carries a browser challenge to the bypasser."""
+
+import requests
+
+_CHALLENGE_HTML = (
+    "<html><head><title>Checking your browser before accessing z-lib.gd</title>"
+    "<script src='/.well-known/ddos-guard/check.js'></script></head>"
+    "<body>Please wait...</body></html>"
+)
+
+
+class _FakeResponse:
+    """Minimal stand-in for requests.Response covering what html_get_page touches."""
+
+    def __init__(
+        self,
+        status_code: int,
+        *,
+        url: str = "https://z-lib.gd/md5/abc",
+        text: str = "",
+        cookies: dict[str, str] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.url = url
+        self.text = text
+        self.cookies = cookies or {}
+        self.headers = {"Content-Type": "text/html;charset=utf-8"}
+        self.is_redirect = False
+
+    def raise_for_status(self) -> None:
+        if self.status_code >= 400:
+            error = requests.exceptions.HTTPError(f"{self.status_code} Error")
+            error.response = self
+            raise error
+
+
+def _neutralize_network(monkeypatch, http):
+    monkeypatch.setattr(http, "_apply_cf_bypass", lambda _url, _headers: {})
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: False)
+    monkeypatch.setattr(http.time, "sleep", lambda _seconds: None)
+
+
+def test_503_challenge_is_handed_to_the_bypasser(monkeypatch):
+    """The reissued-cookie 503 from #1233 reaches the bypasser instead of retrying."""
+    import shelfmark.download.http as http
+
+    _neutralize_network(monkeypatch, http)
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+
+    attempts: list[dict[str, str]] = []
+    bypassed: list[str] = []
+
+    def fake_get(_url: str, **kwargs):
+        attempts.append(dict(kwargs["cookies"]))
+        # Hit 1 issues the cookie; every later hit re-serves the challenge unchanged,
+        # which is what leaves the handshake with nothing to echo back.
+        if len(attempts) == 1:
+            return _FakeResponse(503, cookies={"bsrv": "1"})
+        return _FakeResponse(503, text=_CHALLENGE_HTML, cookies={"bsrv": "1"})
+
+    def fake_bypass(url: str, _selector=None, _cancel_flag=None):
+        bypassed.append(url)
+        return "<html>real page</html>"
+
+    monkeypatch.setattr(http.requests, "get", fake_get)
+    monkeypatch.setattr(http, "get_bypassed_page", fake_bypass)
+
+    html = http.html_get_page("https://z-lib.gd/md5/abc", retry=10, success_delay=0)
+
+    assert html == "<html>real page</html>"
+    assert bypassed == ["https://z-lib.gd/md5/abc"]
+    # The handshake still gets its echo; the challenge ends the loop on the second hit
+    # rather than burning all ten attempts.
+    assert attempts == [{}, {"bsrv": "1"}]
+
+
+def test_plain_503_still_retries_without_bypassing(monkeypatch):
+    """An overloaded origin has no challenge marker, so its retry path is untouched."""
+    import shelfmark.download.http as http
+
+    _neutralize_network(monkeypatch, http)
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+
+    attempts: list[dict[str, str]] = []
+    bypassed: list[str] = []
+
+    def fake_get(_url: str, **kwargs):
+        attempts.append(dict(kwargs["cookies"]))
+        return _FakeResponse(503, text="<html><body>Service Unavailable</body></html>")
+
+    monkeypatch.setattr(http.requests, "get", fake_get)
+    monkeypatch.setattr(
+        http, "get_bypassed_page", lambda url, *_a, **_k: bypassed.append(url) or ""
+    )
+
+    html = http.html_get_page("https://z-lib.gd/md5/abc", retry=3, success_delay=0)
+
+    assert html == ""
+    assert bypassed == []
+    assert attempts == [{}, {}, {}]
+
+
+def test_503_challenge_respects_disabled_bypasser_fallback(monkeypatch):
+    """Best-effort fetches must not stall on a minutes-long solve."""
+    import shelfmark.download.http as http
+
+    _neutralize_network(monkeypatch, http)
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+
+    bypassed: list[str] = []
+    monkeypatch.setattr(
+        http.requests,
+        "get",
+        lambda _url, **_kwargs: _FakeResponse(503, text=_CHALLENGE_HTML),
+    )
+    monkeypatch.setattr(
+        http, "get_bypassed_page", lambda url, *_a, **_k: bypassed.append(url) or ""
+    )
+
+    html = http.html_get_page(
+        "https://z-lib.gd/md5/abc", retry=1, success_delay=0, allow_bypasser_fallback=False
+    )
+
+    assert html == ""
+    assert bypassed == []
@@ -0,0 +1,103 @@
+"""Tests for the Z-Library 503 cookie handshake."""
+
+import requests
+
+
+class _FakeResponse:
+    """Minimal stand-in for requests.Response covering what html_get_page touches."""
+
+    def __init__(
+        self,
+        status_code: int,
+        *,
+        url: str = "https://z-lib.fm/md5/abc",
+        text: str = "",
+        cookies: dict[str, str] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.url = url
+        self.text = text
+        self.cookies = cookies or {}
+        self.headers = {"Content-Type": "text/html;charset=utf-8"}
+        self.is_redirect = False
+
+    def raise_for_status(self) -> None:
+        if self.status_code >= 400:
+            error = requests.exceptions.HTTPError(f"{self.status_code} Error")
+            error.response = self
+            raise error
+
+
+def _neutralize_network(monkeypatch, http):
+    monkeypatch.setattr(http, "_apply_cf_bypass", lambda _url, _headers: {})
+    monkeypatch.setattr(http, "get_proxies", lambda _url: {})
+    monkeypatch.setattr(http, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(http.network, "should_rotate_dns_for_url", lambda _url: False)
+    monkeypatch.setattr(http.time, "sleep", lambda _seconds: None)
+
+
+def test_html_get_page_echoes_503_cookie(monkeypatch):
+    """A 503 that only sets a cookie is cleared by sending that cookie back."""
+    import shelfmark.download.http as http
+
+    _neutralize_network(monkeypatch, http)
+
+    sent_cookies: list[dict[str, str]] = []
+
+    def fake_get(_url: str, **kwargs):
+        sent_cookies.append(dict(kwargs["cookies"]))
+        if len(sent_cookies) == 1:
+            return _FakeResponse(503, cookies={"zlib_sid": "s3cr3t"})
+        return _FakeResponse(200, text="<html>real page</html>")
+
+    monkeypatch.setattr(http.requests, "get", fake_get)
+
+    html = http.html_get_page("https://z-lib.fm/md5/abc", retry=3, success_delay=0)
+
+    assert html == "<html>real page</html>"
+    # The first hit carries nothing; the retry echoes back exactly what the 503 issued.
+    assert sent_cookies == [{}, {"zlib_sid": "s3cr3t"}]
+
+
+def test_html_get_page_stops_echoing_when_cookie_is_reissued(monkeypatch):
+    """A server repeating the same cookie must not spin the request loop forever."""
+    import shelfmark.download.http as http
+
+    _neutralize_network(monkeypatch, http)
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: False)
+
+    sent_cookies: list[dict[str, str]] = []
+
+    def fake_get(_url: str, **kwargs):
+        sent_cookies.append(dict(kwargs["cookies"]))
+        return _FakeResponse(503, cookies={"zlib_sid": "same"})
+
+    monkeypatch.setattr(http.requests, "get", fake_get)
+
+    html = http.html_get_page("https://z-lib.fm/md5/abc", retry=1, success_delay=0)
+
+    assert html == ""
+    # One initial hit plus one echo; the reissued identical cookie yields no third request.
+    assert sent_cookies == [{}, {"zlib_sid": "same"}]
+
+
+def test_html_get_page_leaves_cookieless_503_on_the_retry_path(monkeypatch):
+    """A plain overloaded-server 503 keeps its existing retry behaviour."""
+    import shelfmark.download.http as http
+
+    _neutralize_network(monkeypatch, http)
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: False)
+
+    attempts: list[dict[str, str]] = []
+
+    def fake_get(_url: str, **kwargs):
+        attempts.append(dict(kwargs["cookies"]))
+        return _FakeResponse(503)
+
+    monkeypatch.setattr(http.requests, "get", fake_get)
+
+    html = http.html_get_page("https://z-lib.fm/md5/abc", retry=2, success_delay=0)
+
+    assert html == ""
+    # Two ordinary attempts, no extra in-place retry and no cookies invented.
+    assert attempts == [{}, {}]
@@ -0,0 +1,221 @@
+"""Tests for AA mirror quarantine: dead mirrors leave the rotation, live ones stay.
+
+The distinction these guard is the whole point of the feature. A mirror that answers
+403 (DDoS-Guard) is alive and holds our bypass clearance, so rotating off it makes the
+next search solve a fresh challenge on a domain we have no cookie for. A mirror that
+NXDOMAINs, refuses the connection, or answers 200 with a parking page is not a mirror
+at all and must never be tried again this session.
+"""
+
+import requests
+
+
+def _fresh_network(monkeypatch, urls: list[str], *, auto: bool = True):
+    import shelfmark.download.network as network
+
+    monkeypatch.setattr(network, "_initialized", True)
+    monkeypatch.setattr(network, "_aa_urls", list(urls))
+    monkeypatch.setattr(network, "_aa_base_url", urls[0])
+    monkeypatch.setattr(network, "_current_aa_url_index", 0)
+    monkeypatch.setattr(network, "_dead_aa_urls", set())
+    monkeypatch.setattr(network, "_save_state", lambda **kwargs: None)
+    monkeypatch.setattr(network, "is_aa_auto_mode", lambda: auto)
+    return network
+
+
+MIRRORS = ["https://aa-one.test", "https://aa-two.test", "https://aa-three.test"]
+
+
+def test_quarantined_mirror_leaves_the_available_list(monkeypatch):
+    network = _fresh_network(monkeypatch, MIRRORS)
+
+    assert network.mark_aa_url_dead("https://aa-two.test", "NXDOMAIN") is True
+    assert network.get_available_aa_urls() == ["https://aa-one.test", "https://aa-three.test"]
+    assert network.get_dead_aa_urls() == {"https://aa-two.test"}
+
+
+def test_quarantine_accepts_a_full_request_url(monkeypatch):
+    """Callers hold the failing request URL, not the bare mirror base."""
+    network = _fresh_network(monkeypatch, MIRRORS)
+
+    assert network.mark_aa_url_dead("https://aa-two.test/search?q=dune", "parked") is True
+    assert "https://aa-two.test" in network.get_dead_aa_urls()
+
+
+def test_quarantine_is_idempotent(monkeypatch):
+    network = _fresh_network(monkeypatch, MIRRORS)
+
+    assert network.mark_aa_url_dead("https://aa-two.test", "NXDOMAIN") is True
+    assert network.mark_aa_url_dead("https://aa-two.test", "NXDOMAIN") is False
+    assert network.get_available_aa_urls() == ["https://aa-one.test", "https://aa-three.test"]
+
+
+def test_last_surviving_mirror_is_never_quarantined(monkeypatch):
+    """Misclassification must not leave the app with nowhere to search."""
+    network = _fresh_network(monkeypatch, MIRRORS)
+
+    assert network.mark_aa_url_dead("https://aa-one.test", "NXDOMAIN") is True
+    assert network.mark_aa_url_dead("https://aa-two.test", "NXDOMAIN") is True
+    assert network.mark_aa_url_dead("https://aa-three.test", "NXDOMAIN") is False
+    assert network.get_available_aa_urls() == ["https://aa-three.test"]
+
+
+def test_selector_skips_quarantined_mirror_when_rotating(monkeypatch):
+    network = _fresh_network(monkeypatch, MIRRORS)
+    selector = network.AAMirrorSelector()
+
+    new_base, action = selector.next_mirror_or_rotate_dns(fatal=True, reason="NXDOMAIN")
+
+    assert action == "mirror"
+    # Landed on the next live mirror, not skipped past it onto the third.
+    assert new_base == "https://aa-two.test"
+    assert "https://aa-one.test" in network.get_dead_aa_urls()
+    assert selector.rewrite("https://aa-one.test/search") == "https://aa-two.test/search"
+
+
+def test_non_fatal_rotation_keeps_the_mirror(monkeypatch):
+    """A 5xx or a challenge rotates but must not burn the mirror."""
+    network = _fresh_network(monkeypatch, MIRRORS)
+    selector = network.AAMirrorSelector()
+
+    selector.next_mirror_or_rotate_dns()
+
+    assert network.get_dead_aa_urls() == set()
+    assert network.get_available_aa_urls() == MIRRORS
+
+
+def test_dns_reset_does_not_resurrect_quarantined_mirrors(monkeypatch):
+    """A new DNS provider cannot revive a parked domain, so it stays skipped."""
+    network = _fresh_network(monkeypatch, MIRRORS)
+    monkeypatch.setattr(network, "rotate_dns_provider", lambda: True)
+    monkeypatch.setattr(network, "_get_configured_aa_url", lambda: "auto")
+    network.mark_aa_url_dead("https://aa-one.test", "parked")
+
+    assert network.rotate_dns_and_reset_aa() is True
+    assert network.get_aa_base_url() == "https://aa-two.test"
+
+
+def test_editing_the_mirror_list_clears_quarantine(monkeypatch):
+    """Quarantine decisions were made about a list the user has now changed."""
+    network = _fresh_network(monkeypatch, MIRRORS)
+    network.mark_aa_url_dead("https://aa-two.test", "parked")
+    monkeypatch.setattr(network, "_build_aa_urls", lambda: [*MIRRORS, "https://aa-four.test"])
+    monkeypatch.setattr(network, "_get_configured_aa_url", lambda: "auto")
+    monkeypatch.setattr(network, "state", {"aa_base_url": "https://aa-one.test"})
+
+    network._initialize_aa_state()
+
+    assert network.get_dead_aa_urls() == set()
+
+
+def test_reinit_with_an_unchanged_list_keeps_quarantine(monkeypatch):
+    """Re-init happens constantly (settings sync, DNS rotation, helper startup).
+
+    Clearing quarantine on every one of those resurrects a parked mirror mid-session,
+    which is exactly the bug this guards: the mirror gets re-elected and the next
+    search pays for it again.
+    """
+    network = _fresh_network(monkeypatch, MIRRORS)
+    network.mark_aa_url_dead("https://aa-two.test", "parked")
+    monkeypatch.setattr(network, "_build_aa_urls", lambda: list(MIRRORS))
+    monkeypatch.setattr(network, "_get_configured_aa_url", lambda: "auto")
+    monkeypatch.setattr(network, "state", {"aa_base_url": "https://aa-one.test"})
+
+    network._initialize_aa_state()
+
+    assert network.get_dead_aa_urls() == {"https://aa-two.test"}
+
+
+# --------------------------------------------------------------------------- #
+# Failure classification
+# --------------------------------------------------------------------------- #
+def _http_error(status: int) -> requests.exceptions.HTTPError:
+    response = requests.Response()
+    response.status_code = status
+    return requests.exceptions.HTTPError(response=response)
+
+
+def test_dns_failure_is_fatal_for_the_mirror():
+    import shelfmark.download.http as http
+
+    exc = requests.exceptions.ConnectionError(
+        "HTTPSConnectionPool(host='aa.test', port=443): Max retries exceeded "
+        "(Caused by NameResolutionError(\"Failed to resolve 'aa.test'\"))"
+    )
+    assert http._fatal_mirror_reason(exc) == "DNS does not resolve"
+
+
+def test_connection_refused_is_fatal_for_the_mirror():
+    import shelfmark.download.http as http
+
+    exc = requests.exceptions.ConnectionError("Connection refused")
+    assert http._fatal_mirror_reason(exc) == "connection refused"
+
+
+def test_gone_and_legal_block_are_fatal():
+    import shelfmark.download.http as http
+
+    assert http._fatal_mirror_reason(_http_error(410)) == "HTTP 410"
+    assert http._fatal_mirror_reason(_http_error(451)) == "HTTP 451"
+
+
+def test_timeout_is_not_fatal():
+    """A slow mirror is still a mirror - and may hold our bypass clearance."""
+    import shelfmark.download.http as http
+
+    assert http._fatal_mirror_reason(requests.exceptions.ConnectTimeout("timed out")) is None
+    assert http._fatal_mirror_reason(requests.exceptions.ReadTimeout("timed out")) is None
+
+
+def test_challenge_and_server_errors_are_not_fatal():
+    import shelfmark.download.http as http
+
+    for status in (403, 429, 500, 502, 503):
+        assert http._fatal_mirror_reason(_http_error(status)) is None
+
+
+def test_startup_probe_skips_quarantined_mirrors(monkeypatch):
+    """Re-init must not re-probe (or re-elect) a mirror already known to be dead.
+
+    A parking page answers 200, so an unfiltered probe elects it every single time
+    the app re-initialises - one wasted request per re-init, forever.
+    """
+    import requests
+
+    network = _fresh_network(monkeypatch, MIRRORS)
+    network.mark_aa_url_dead("https://aa-one.test", "parked")
+    probed: list[str] = []
+
+    def fake_get(url, **_kwargs):
+        probed.append(url)
+        response = requests.Response()
+        response.status_code = 200
+        return response
+
+    monkeypatch.setattr(network.requests, "get", fake_get)
+    monkeypatch.setattr(network, "_build_aa_urls", lambda: list(MIRRORS))
+    monkeypatch.setattr(network, "_get_configured_aa_url", lambda: "auto")
+    monkeypatch.setattr(network, "state", {})
+    monkeypatch.setattr(network, "get_proxies", lambda _url: None)
+    monkeypatch.setattr(network, "get_ssl_verify", lambda _url: True)
+
+    network._initialize_aa_state()
+
+    assert "https://aa-one.test" not in probed
+    assert network.get_aa_base_url() == "https://aa-two.test"
+
+
+def test_startup_probe_does_not_restore_a_quarantined_mirror(monkeypatch):
+    """Saved state can name a mirror that has since been quarantined."""
+    network = _fresh_network(monkeypatch, MIRRORS)
+    network.mark_aa_url_dead("https://aa-one.test", "parked")
+    monkeypatch.setattr(network, "_build_aa_urls", lambda: list(MIRRORS))
+    monkeypatch.setattr(network, "_get_configured_aa_url", lambda: "auto")
+    monkeypatch.setattr(network, "state", {"aa_base_url": "https://aa-one.test"})
+    monkeypatch.setattr(network, "get_proxies", lambda _url: None)
+    monkeypatch.setattr(network, "get_ssl_verify", lambda _url: True)
+    monkeypatch.setattr(network.requests, "get", lambda *a, **k: (_ for _ in ()).throw(OSError()))
+
+    network._initialize_aa_state()
+
+    assert network.get_aa_base_url() != "https://aa-one.test"
@@ -9,6 +9,10 @@ class _StopLoop(BaseException):
    """Sentinel used to stop the infinite coordinator loop during tests."""


+class _UnexpectedCall(BaseException):
+    """Guard-rail failure that the coordinator's `except Exception` must not swallow."""
+
+
 class _FakeExecutor:
    def __init__(self, *args, **kwargs) -> None:
        self.args = args
@@ -21,7 +25,7 @@ class _FakeExecutor:
        return False

    def submit(self, *args, **kwargs):  # pragma: no cover - not expected in these tests
-        raise AssertionError("submit() should not be called in this test")
+        raise _UnexpectedCall("submit() should not be called in this test")


 class _StopCoordinator(BaseException):
@@ -68,6 +72,69 @@ def test_concurrent_download_loop_logs_and_recovers_after_loop_error(monkeypatch
    ]


+def test_concurrent_download_loop_survives_exceptions_outside_the_legacy_list(monkeypatch):
+    """Regression for #823/#1166: the coordinator must not die on an unlisted exception.
+
+    `gevent.exceptions.LoopExit` and `StopIteration` are Exceptions that the old narrow
+    except tuple let through, silently killing the only thread that drives the queue.
+    """
+    import shelfmark.download.orchestrator as orchestrator
+
+    raised: list[type[BaseException]] = []
+    escapes = [StopIteration, ZeroDivisionError, KeyboardInterrupt]
+
+    def fake_get_next():
+        if escapes:
+            exc = escapes.pop(0)
+            if exc is KeyboardInterrupt:
+                # BaseException: must still propagate and stop the loop.
+                raise KeyboardInterrupt
+            raised.append(exc)
+            raise exc("boom")
+        return None
+
+    mock_queue = MagicMock()
+    mock_queue.get_next.side_effect = fake_get_next
+
+    monkeypatch.setattr(orchestrator, "book_queue", mock_queue)
+    monkeypatch.setattr(orchestrator, "ThreadPoolExecutor", _FakeExecutor)
+    monkeypatch.setattr(orchestrator.time, "sleep", lambda _delay: None)
+    monkeypatch.setattr(orchestrator.logger, "error_trace", MagicMock())
+
+    with pytest.raises(KeyboardInterrupt):
+        orchestrator.concurrent_download_loop()
+
+    assert raised == [StopIteration, ZeroDivisionError]
+
+
+def test_concurrent_download_loop_backs_off_on_repeated_errors(monkeypatch):
+    """A persistent failure must not spin the loop at 1Hz forever."""
+    import shelfmark.download.orchestrator as orchestrator
+
+    sleep_delays: list[float] = []
+
+    def fake_sleep(delay: float) -> None:
+        sleep_delays.append(delay)
+        if len(sleep_delays) >= 4:
+            raise _StopLoop()
+
+    mock_queue = MagicMock()
+    mock_queue.get_next.side_effect = RuntimeError("persistent boom")
+
+    monkeypatch.setattr(orchestrator, "book_queue", mock_queue)
+    monkeypatch.setattr(orchestrator, "ThreadPoolExecutor", _FakeExecutor)
+    monkeypatch.setattr(orchestrator.time, "sleep", fake_sleep)
+    monkeypatch.setattr(orchestrator.logger, "error_trace", MagicMock())
+
+    with pytest.raises(_StopLoop):
+        orchestrator.concurrent_download_loop()
+
+    base = orchestrator.COORDINATOR_LOOP_ERROR_RETRY_DELAY
+    # First delay stays unchanged for a normal transient blip, then doubles.
+    assert sleep_delays == [base, base * 2, base * 4, base * 8]
+    assert max(sleep_delays) <= orchestrator._COORDINATOR_LOOP_ERROR_MAX_DELAY
+
+
 def test_concurrent_download_loop_recovers_and_processes_task_after_transient_loop_error(
    monkeypatch,
 ):
@@ -91,13 +158,16 @@ def test_concurrent_download_loop_recovers_and_processes_task_after_transient_lo
                raise _StopCoordinator()
            return None

+        # These raise _UnexpectedCall rather than AssertionError because the coordinator
+        # loop catches Exception: an AssertionError here would be swallowed and logged,
+        # letting the test pass vacuously instead of reporting the unexpected call.
        def cancel_download(self, task_id: str) -> None:  # pragma: no cover - unused
-            raise AssertionError(f"cancel_download unexpectedly called for {task_id}")
+            raise _UnexpectedCall(f"cancel_download unexpectedly called for {task_id}")

        def update_status_message(
            self, task_id: str, message: str
        ) -> None:  # pragma: no cover - unused
-            raise AssertionError(
+            raise _UnexpectedCall(
                f"update_status_message unexpectedly called for {task_id}: {message}"
            )

@@ -0,0 +1,291 @@
+"""Tests for stall detection and the activity-grace window.
+
+Covers the regression behind issue #1001: a protection bypass is a single long blocking
+call that emits no changing status or progress, so it used to be cancelled at exactly
+STALL_TIMEOUT even though the bypasser itself was still working.
+"""
+
+from unittest.mock import MagicMock
+
+import requests
+
+
+def _stub_ext_bypasser_timeout(monkeypatch, external_bypasser, value: int) -> None:
+    """Override only EXT_BYPASSER_TIMEOUT.
+
+    `external_bypasser.config` is the shared config singleton, so a blanket `get` stub
+    also answers unrelated lookups (DNS setup, etc.) with the wrong value.
+    """
+    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 _reset(orchestrator) -> None:
+    orchestrator._last_activity.clear()
+    orchestrator._last_progress_value.clear()
+    orchestrator._last_status_event.clear()
+    orchestrator._activity_grace.clear()
+
+
+def test_find_stalled_tasks_flags_task_past_stall_timeout():
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    orchestrator._last_activity["book"] = 1000.0
+    now = 1000.0 + orchestrator.STALL_TIMEOUT + 1
+
+    assert orchestrator._find_stalled_tasks(["book"], now) == ["book"]
+
+
+def test_find_stalled_tasks_ignores_task_within_stall_timeout():
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    orchestrator._last_activity["book"] = 1000.0
+    now = 1000.0 + orchestrator.STALL_TIMEOUT - 1
+
+    assert orchestrator._find_stalled_tasks(["book"], now) == []
+
+
+def test_find_stalled_tasks_ignores_unknown_task():
+    """A task with no recorded activity yet is not considered stalled."""
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+
+    assert orchestrator._find_stalled_tasks(["never-seen"], 99999.0) == []
+
+
+def test_activity_grace_suppresses_stall_until_its_deadline(monkeypatch):
+    """A bypass that legitimately outlives STALL_TIMEOUT is not cancelled."""
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    monkeypatch.setattr(orchestrator.time, "time", lambda: 1000.0)
+    orchestrator._last_activity["book"] = 1000.0
+    orchestrator.set_activity_grace("book", 400.0)
+
+    # Well past STALL_TIMEOUT, but inside the declared budget.
+    assert orchestrator._find_stalled_tasks(["book"], 1390.0) == []
+
+
+def test_activity_grace_expires_and_task_is_flagged(monkeypatch):
+    """A genuinely wedged operation still dies - the grace never extends itself."""
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    monkeypatch.setattr(orchestrator.time, "time", lambda: 1000.0)
+    orchestrator._last_activity["book"] = 1000.0
+    orchestrator.set_activity_grace("book", 400.0)
+
+    assert orchestrator._find_stalled_tasks(["book"], 1401.0) == ["book"]
+
+
+def test_set_activity_grace_is_clamped(monkeypatch):
+    """A caller cannot buy immortality by asking for an absurd grace."""
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    monkeypatch.setattr(orchestrator.time, "time", lambda: 1000.0)
+    orchestrator.set_activity_grace("book", 10_000_000.0)
+
+    assert orchestrator._activity_grace["book"] == 1000.0 + orchestrator._MAX_ACTIVITY_GRACE_SECONDS
+
+
+def test_max_activity_grace_covers_the_largest_bypass_budget():
+    """The clamp must not silently bite the one caller that exists."""
+    import shelfmark.download.http as http
+    import shelfmark.download.orchestrator as orchestrator
+    from shelfmark.bypass import external_bypasser, internal_bypasser
+
+    largest = (
+        max(
+            external_bypasser.max_duration_seconds(),
+            internal_bypasser.max_duration_seconds(),
+        )
+        + http._BYPASS_GRACE_SLACK_SECONDS
+    )
+
+    assert largest <= orchestrator._MAX_ACTIVITY_GRACE_SECONDS
+
+
+def test_set_activity_grace_touches_neither_queue_nor_websocket(monkeypatch):
+    """A liveness hint is not a user-visible status transition."""
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    mock_queue = MagicMock()
+    mock_ws = MagicMock()
+    monkeypatch.setattr(orchestrator, "book_queue", mock_queue)
+    monkeypatch.setattr(orchestrator, "ws_manager", mock_ws)
+
+    orchestrator.set_activity_grace("book", 100.0)
+    orchestrator.clear_activity_grace("book")
+
+    assert mock_queue.mock_calls == []
+    assert mock_ws.mock_calls == []
+
+
+def test_clear_activity_grace_refreshes_last_activity(monkeypatch):
+    """Releasing a grace restarts the normal window rather than stalling instantly."""
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    orchestrator._last_activity["book"] = 1.0
+    monkeypatch.setattr(orchestrator.time, "time", lambda: 5000.0)
+
+    orchestrator.set_activity_grace("book", 100.0)
+    orchestrator.clear_activity_grace("book")
+
+    assert "book" not in orchestrator._activity_grace
+    assert orchestrator._last_activity["book"] == 5000.0
+    assert orchestrator._find_stalled_tasks(["book"], 5000.0) == []
+
+
+def test_cleanup_progress_tracking_drops_activity_grace(monkeypatch):
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    monkeypatch.setattr(orchestrator, "ws_manager", None)
+    orchestrator.set_activity_grace("book", 100.0)
+
+    orchestrator._cleanup_progress_tracking("book")
+
+    assert "book" not in orchestrator._activity_grace
+
+
+def test_update_download_status_rejects_the_grace_sentinel(monkeypatch):
+    """Defence in depth: the sentinel is intercepted upstream, but must be inert here too."""
+    import shelfmark.download.orchestrator as orchestrator
+    from shelfmark.download.activity import ACTIVITY_GRACE_STATUS
+
+    _reset(orchestrator)
+    mock_queue = MagicMock()
+    mock_ws = MagicMock()
+    monkeypatch.setattr(orchestrator, "book_queue", mock_queue)
+    monkeypatch.setattr(orchestrator, "ws_manager", mock_ws)
+    monkeypatch.setattr(orchestrator, "queue_status", lambda: {})
+
+    orchestrator.update_download_status("book", ACTIVITY_GRACE_STATUS, "330.0")
+
+    assert mock_queue.mock_calls == []
+    assert mock_ws.mock_calls == []
+    assert "book" not in orchestrator._last_activity
+
+
+def test_issue_1001_slow_bypass_is_not_cancelled_at_stall_timeout(monkeypatch):
+    """End-to-end replay of the issue #1001 timeline.
+
+    From a reporter's debug log: a 403 switched to the external bypasser at 07:04:33, five
+    FlareSolverr attempts each took ~64s and returned HTTP 500, and the watchdog cancelled
+    the download at 07:09:33.987 - exactly STALL_TIMEOUT later and 41s before the bypasser
+    would have finished and reported the real error.
+
+    Now the bypass declares its own budget, so the watchdog holds off and the user sees the
+    actual failure instead of a five-minute silent hang.
+    """
+    import shelfmark.download.http as http
+    import shelfmark.download.orchestrator as orchestrator
+    from shelfmark.bypass import external_bypasser
+    from shelfmark.download.activity import parse_activity_grace
+
+    _reset(orchestrator)
+    clock = [1000.0]
+    monkeypatch.setattr(orchestrator.time, "time", lambda: clock[0])
+
+    # Mirror the orchestrator's per-task status_callback closure.
+    events: list[tuple[str, str | None]] = []
+
+    def status_callback(status: str, message: str | None = None) -> None:
+        grace = parse_activity_grace(status, message)
+        if grace is not None:
+            if grace > 0:
+                orchestrator.set_activity_grace("book", grace)
+            else:
+                orchestrator.clear_activity_grace("book")
+            return
+        events.append((status, message))
+        orchestrator._last_activity["book"] = clock[0]
+
+    # The reporter was on external FlareSolverr with the default 60s timeout.
+    monkeypatch.setattr(http, "_is_cf_bypass_enabled", lambda: True)
+    monkeypatch.setattr(http, "_is_using_external_bypasser", lambda: True)
+    monkeypatch.setattr(http, "_get_external_bypasser", lambda: external_bypasser)
+    _stub_ext_bypasser_timeout(monkeypatch, external_bypasser, 60000)
+
+    stall_checks: list[list[str]] = []
+
+    def slow_failing_bypasser(*_args, **_kwargs):
+        # Five attempts at ~64s, then give up - as in the log.
+        for _attempt in range(5):
+            clock[0] += 64.0
+            stall_checks.append(orchestrator._find_stalled_tasks(["book"], clock[0]))
+        raise requests.exceptions.RequestException("500 Server Error")
+
+    monkeypatch.setattr(http, "get_bypassed_page", slow_failing_bypasser)
+
+    html = http.html_get_page(
+        "https://annas-archive.gl/slow_download/abc/0/6",
+        retry=1,
+        use_bypasser=True,
+        status_callback=status_callback,
+    )
+
+    # The bypass ran 320s - past STALL_TIMEOUT - and was never flagged as stalled.
+    assert 320.0 > orchestrator.STALL_TIMEOUT
+    assert stall_checks[-1] == []
+    assert all(check == [] for check in stall_checks)
+
+    # And the real reason reached the user instead of a generic stall message.
+    assert html == ""
+    assert [status for status, _m in events if status == "error"]
+    assert "500 Server Error" in str(events[-1][1])
+
+
+def test_issue_1001_bypass_overrunning_its_own_budget_is_still_cancelled(monkeypatch):
+    """The other half: declaring a budget must not make a wedged bypass immortal."""
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    monkeypatch.setattr(orchestrator.time, "time", lambda: 1000.0)
+    orchestrator._last_activity["book"] = 1000.0
+
+    # External bypasser default budget (394s) plus http's 30s slack.
+    orchestrator.set_activity_grace("book", 424.0)
+
+    assert orchestrator._find_stalled_tasks(["book"], 1000.0 + 424.0) == []
+    assert orchestrator._find_stalled_tasks(["book"], 1000.0 + 425.0) == ["book"]
+
+
+def test_cancel_stalled_task_does_not_hold_the_progress_lock(monkeypatch):
+    """Regression guard: cancelling reaches a sqlite write that must not block the hub.
+
+    `book_queue.cancel_download` runs the terminal-status hooks, which are not
+    gevent-patched. Holding `_progress_lock` across that stalls every download worker.
+    """
+    import shelfmark.download.orchestrator as orchestrator
+
+    _reset(orchestrator)
+    observed: list[bool] = []
+
+    def fake_cancel(_task_id: str) -> bool:
+        acquired = orchestrator._progress_lock.acquire(blocking=False)
+        observed.append(acquired)
+        if acquired:
+            orchestrator._progress_lock.release()
+        return True
+
+    mock_queue = MagicMock()
+    mock_queue.cancel_download.side_effect = fake_cancel
+    monkeypatch.setattr(orchestrator, "book_queue", mock_queue)
+
+    orchestrator._cancel_stalled_task("book")
+
+    assert observed == [True], "_progress_lock was held while cancelling a stalled task"
+    mock_queue.update_status_message.assert_called_once_with(
+        "book", f"Download stalled (no activity for {orchestrator.STALL_TIMEOUT}s)"
+    )
@@ -0,0 +1,170 @@
+"""Boot-time search warm-up.
+
+The warm-up exists to move the cold DDoS-Guard solve off the user's first search. It
+is an optimisation, so the load-bearing property is that it can never affect startup:
+a source that is down, misconfigured or raising must leave the app running.
+"""
+
+import pytest
+
+
+@pytest.fixture
+def warmup(monkeypatch):
+    import shelfmark.download.warmup as warmup_module
+
+    monkeypatch.setattr(warmup_module, "_warmup_thread", None)
+    return warmup_module
+
+
+def _patch_config(monkeypatch, warmup, values: dict):
+    def fake_get(key, default=None):
+        return values.get(key, default)
+
+    monkeypatch.setattr(warmup.config, "get", fake_get)
+
+
+def test_disabled_by_setting(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {"SEARCH_WARMUP_ENABLED": False})
+    assert warmup.is_enabled() is False
+    assert warmup.start() is False
+
+
+def test_disabled_by_string_false(monkeypatch, warmup):
+    """Deployment ENV arrives as a string, not a bool."""
+    _patch_config(monkeypatch, warmup, {"SEARCH_WARMUP_ENABLED": "false"})
+    assert warmup.is_enabled() is False
+
+
+def test_skipped_when_direct_download_is_off(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {"DIRECT_DOWNLOAD_ENABLED": False})
+    assert warmup.is_enabled() is False
+
+
+def test_enabled_by_default(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {})
+    assert warmup.is_enabled() is True
+
+
+def test_query_defaults_and_is_configurable(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {})
+    assert warmup.warmup_query() == "The Great Gatsby"
+
+    _patch_config(monkeypatch, warmup, {"SEARCH_WARMUP_QUERY": "Dune"})
+    assert warmup.warmup_query() == "Dune"
+
+    # A blank override must not send an empty query at the source.
+    _patch_config(monkeypatch, warmup, {"SEARCH_WARMUP_QUERY": "   "})
+    assert warmup.warmup_query() == "The Great Gatsby"
+
+
+def test_skipped_when_no_mirrors_configured(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {})
+    import shelfmark.core.mirrors as mirrors
+
+    monkeypatch.setattr(mirrors, "has_aa_mirror_configuration", lambda: False)
+
+    called: list[str] = []
+    import shelfmark.release_sources.direct_download as dd
+
+    monkeypatch.setattr(dd, "search_books", lambda q, f: called.append(q))
+
+    assert warmup.run_warmup() is False
+    assert called == []
+
+
+def test_successful_warmup_reports_true(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {})
+    import shelfmark.core.mirrors as mirrors
+    import shelfmark.release_sources.direct_download as dd
+
+    monkeypatch.setattr(mirrors, "has_aa_mirror_configuration", lambda: True)
+    seen: list[str] = []
+
+    def fake_search(query, _filters):
+        seen.append(query)
+        return ["a", "b"]
+
+    monkeypatch.setattr(dd, "search_books", fake_search)
+
+    assert warmup.run_warmup() is True
+    assert seen == ["The Great Gatsby"]
+
+
+def test_empty_results_are_not_an_error(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {})
+    import shelfmark.core.mirrors as mirrors
+    import shelfmark.release_sources.direct_download as dd
+
+    monkeypatch.setattr(mirrors, "has_aa_mirror_configuration", lambda: True)
+    monkeypatch.setattr(dd, "search_books", lambda q, f: [])
+
+    assert warmup.run_warmup() is False
+
+
+def test_search_failure_is_swallowed(monkeypatch, warmup):
+    """A source that is down at boot must not propagate out of the warm-up."""
+    _patch_config(monkeypatch, warmup, {})
+    import shelfmark.core.mirrors as mirrors
+    import shelfmark.release_sources.direct_download as dd
+
+    monkeypatch.setattr(mirrors, "has_aa_mirror_configuration", lambda: True)
+
+    def boom(_query, _filters):
+        msg = "mirrors are blocked"
+        raise RuntimeError(msg)
+
+    monkeypatch.setattr(dd, "search_books", boom)
+
+    assert warmup.run_warmup() is False
+
+
+def test_start_schedules_a_daemon_thread_and_is_idempotent(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {})
+
+    assert warmup.start(delay_seconds=30) is True
+    thread = warmup._warmup_thread
+    assert thread is not None
+    assert thread.daemon is True
+
+    # A second call must not stack up another timer.
+    assert warmup.start(delay_seconds=30) is False
+    assert warmup._warmup_thread is thread
+
+    thread.cancel()
+
+
+def test_start_does_not_run_the_search_inline(monkeypatch, warmup):
+    """Startup must not block on a search that can take a minute."""
+    _patch_config(monkeypatch, warmup, {})
+    ran: list[bool] = []
+    monkeypatch.setattr(warmup, "run_warmup", lambda: ran.append(True))
+
+    warmup.start(delay_seconds=30)
+    assert ran == []
+
+    if warmup._warmup_thread:
+        warmup._warmup_thread.cancel()
+
+
+def test_env_var_can_disable_the_warmup(monkeypatch, warmup):
+    """SEARCH_WARMUP_ENABLED is not in the settings registry, so config.get never
+    sees it - the documented off-switch only works if os.environ is consulted."""
+    _patch_config(monkeypatch, warmup, {})  # config knows nothing about the key
+    monkeypatch.setenv("SEARCH_WARMUP_ENABLED", "false")
+
+    assert warmup.is_enabled() is False
+    assert warmup.start() is False
+
+
+def test_env_var_can_set_the_query(monkeypatch, warmup):
+    _patch_config(monkeypatch, warmup, {})
+    monkeypatch.setenv("SEARCH_WARMUP_QUERY", "Moby Dick")
+
+    assert warmup.warmup_query() == "Moby Dick"
+
+
+def test_env_var_absent_falls_back_to_config(monkeypatch, warmup):
+    monkeypatch.delenv("SEARCH_WARMUP_QUERY", raising=False)
+    _patch_config(monkeypatch, warmup, {"SEARCH_WARMUP_QUERY": "From Config"})
+
+    assert warmup.warmup_query() == "From Config"
@@ -87,12 +87,14 @@ end-to-end (`docker compose up` + suite + teardown) and passes.
 | `full` | **real Chrome solves Cloudflare** + DoH + **real qBittorrent** download → /books (Moby-Dick) | 1,4,5 + DoH | **#284 #1030** #386 #1040 #214 | ✅ 6 passed |
 | *(every profile)* | boots healthy under PUID/PGID, no perm errors | 6 entrypoint | #171 #447 #801 | ✅ |

-> **The bypasser is download-time, not search-time.** Running the stack revealed
-> that shelfmark fetches AA search/detail with `allow_bypasser_fallback=False`, so a
-> search behind Cloudflare returns 503 **regardless** of the bypasser; the bypasser
-> (internal Chrome or external FlareSolverr) only runs during a file *download*
-> (`use_bypasser=True`). The bypasser profiles therefore assert a *clean*
-> CF-gated-search failure, while the **`full` profile exercises the real end-to-end
+> **The bypasser now runs for search too.** AA search/detail used to be fetched with
+> `allow_bypasser_fallback=False`, so a search behind Cloudflare returned 503
+> regardless of the bypasser — which left search dead when AA put DDoS-Guard in front
+> of `/search`. Both now pass `allow_bypasser_fallback=True`, so a 403 switches
+> straight to the bypasser rather than rotating to another mirror behind the same
+> gate. The bypasser profiles therefore assert that a gated search *recovers* when the
+> external bypasser is available and still fails cleanly when it is off, while the
+> **`full` profile exercises the real end-to-end
 > CF solve**: AA search/detail are reachable, but the AA slow-download link points
 > at the gate, so downloading Moby-Dick forces the in-image headless Chromium to
 > detect the challenge, solve it (`_bypass_method_cdp_solve`), and fetch the file —
@@ -59,8 +59,17 @@ fi

 echo "==> [$PROFILE] waiting for shelfmark health"
 HEALTHY=0
-for _ in $(seq 1 60); do
-  if curl -fsS http://localhost:8084/api/health >/dev/null 2>&1; then HEALTHY=1; break; fi
+# The curl timeouts are load-bearing, not belt-and-braces. A container that
+# binds 8084 but never answers (e.g. a broken C-extension wheel wedging the
+# gunicorn worker) blocks a bare `curl` forever on read, so an iteration-counted
+# loop never reaches iteration 2 and the wait becomes unbounded — that hung CI
+# for the full 6h job limit on PR #1169. Bound each probe AND the whole wait.
+HEALTH_DEADLINE=$((SECONDS + 120))
+while ((SECONDS < HEALTH_DEADLINE)); do
+  if curl -fsS --connect-timeout 3 --max-time 5 http://localhost:8084/api/health >/dev/null 2>&1; then
+    HEALTHY=1
+    break
+  fi
  sleep 2
 done

@@ -1,20 +1,18 @@
-"""Cluster 1 — Cloudflare bypasser wiring + clean-failure behavior.
+"""Cluster 1 — Cloudflare bypasser wiring + gated-search behavior.

-Reality discovered by running the stack: shelfmark's AA *search* and *detail*
-fetches use ``html_get_page(allow_bypasser_fallback=False)``, so a search behind a
-Cloudflare gate returns 503 **regardless** of the bypasser. The bypasser (internal
-Chrome or external FlareSolverr) is a *download-time* mechanism
-(``html_get_page(use_bypasser=True)``); it never runs for search.
+AA search/detail used to be fetched with ``allow_bypasser_fallback=False``, so a
+search behind a Cloudflare gate returned 503 no matter how the bypasser was
+configured — which left search dead when AA put DDoS-Guard in front of ``/search``.
+Both now pass ``allow_bypasser_fallback=True``: a 403 switches straight to the
+bypasser instead of rotating to another mirror behind the same gate.

-So these tests assert what is actually true and host-observable:
-  * the external bypasser is configured from env, and
-  * a CF-gated search fails *cleanly* (a 503 the client can act on, not a hang or
-    a crash) — both with the bypasser on (it isn't used for search) and off.
+So these tests assert:
+  * the external bypasser is configured from env,
+  * a CF-gated search *recovers* once the external bypasser is available, and
+  * with the bypasser off it still fails *cleanly* (a 503 the client can act on,
+    not a hang or a crash) — the negative control that the gate is not ignored.

-Exercising shelfmark's *use* of the bypasser end-to-end (a real CF solve during a
-download) needs the AA slow-download HTML flow mocked — see the README roadmap.
-The bypass *mechanism* itself is verified to work: the mock FlareSolverr solves
-the gate (manually confirmed; see README). Guards: #284 #226 #202 #1030 #410 #369.
+Guards: #284 #226 #202 #1030 #410 #369.
 """

 from __future__ import annotations
@@ -70,10 +68,26 @@ def test_external_bypasser_is_configured(client) -> None:


@pytest.mark.profiles("bypasser-external")
-def test_cf_gated_search_fails_cleanly_with_external_bypasser(client) -> None:
-    """Even with the external bypasser configured, a CF-gated *search* yields no
-    releases (the bypasser is download-time) — but it must fail cleanly."""
-    assert _cf_gated_search_has_no_releases(client)
+def test_cf_gated_search_recovers_via_external_bypasser(client) -> None:
+    """A CF-gated search is solved through the bypasser instead of returning 503.
+
+    The mock FlareSolverr refetches with the clearance cookie, which the cloudflare
+    role then passes through to the AA origin — so the 403 that used to end the
+    search now turns into real results.
+    """
+    resp = client.get(
+        "/api/releases",
+        params={"source": "direct_download", "query": "Mistborn"},
+        timeout=120,
+    )
+    assert resp.status_code == 200, (
+        f"CF-gated search did not recover through the external bypasser: "
+        f"{resp.status_code} {resp.text[:200]}"
+    )
+    assert client.releases_from(resp), (
+        "external bypasser was configured but the gated search returned no releases — "
+        "the 403 did not switch search over to the bypasser"
+    )


@pytest.mark.profiles("bypasser-disabled")
@@ -1,5 +1,96 @@
+import pytest
+
+from shelfmark.core.utils import ARCHIVE_FORMATS, AUDIOBOOK_FORMATS
 from shelfmark.release_sources.irc import parser

+# What a stock install actually filters with, so these tests fail if the defaults regress.
+_DEFAULT_CONFIG = {
+    "SUPPORTED_FORMATS": ["epub", "mobi", "azw3", "fb2", "djvu", "cbz", "cbr"],
+    "SUPPORTED_AUDIOBOOK_FORMATS": [*AUDIOBOOK_FORMATS, *ARCHIVE_FORMATS],
+}
+
+
+@pytest.fixture
+def default_formats(monkeypatch):
+    """Filter with the shipped default format lists."""
+    monkeypatch.setattr(
+        parser.config, "get", lambda key, default=None: _DEFAULT_CONFIG.get(key, default)
+    )
+
+
+def test_audiobook_archives_are_found_with_default_settings(default_formats):
+    """Regression for #1129: audiobooks ship as .rar/.zip and were dropped by both buckets.
+
+    A single "@search" answers with one file holding every format. These are the lines an
+    audiobook actually occupies in it - the extension is a container, and the release name
+    is the only thing saying what is inside.
+    """
+    content = "\n".join(
+        [
+            "!Oatmeal Andy Weir - Project Hail Mary (Audiobook) [MP3 64kbps].rar ::INFO:: 620.5MB",
+            "!DV8 Andy Weir - Project Hail Mary - Audiobook.zip ::INFO:: 700MB",
+            "!Horla Andy Weir - Project Hail Mary [Unabridged].m4b ::INFO:: 850.1MB",
+        ]
+    )
+
+    results = parser.parse_results_file(content, content_type="audiobook")
+
+    assert [result.format for result in results] == ["rar", "zip", "m4b"]
+
+
+def test_ebook_archive_does_not_leak_into_audiobook_results(default_formats):
+    """An ebook .rar must not be offered as an audiobook just because it is an archive."""
+    content = "!bald Andy Weir - Project Hail Mary (retail).rar ::INFO:: 2.1MB"
+
+    assert parser.parse_results_file(content, content_type="audiobook") == []
+
+
+def test_flac_audiobook_is_reachable_with_default_settings(default_formats):
+    """FLAC was recognized by the parser and ranked by the sorter, but never selectable."""
+    content = "!Ook Andy Weir - Project Hail Mary.flac ::INFO:: 1.1GB"
+
+    results = parser.parse_results_file(content, content_type="audiobook")
+
+    assert [result.format for result in results] == ["flac"]
+
+
+def test_decimal_size_is_not_mistaken_for_a_file_extension():
+    """A line with no extension used to parse as format="5mb" out of "::INFO:: 620.5MB"."""
+    line = "!Ook Andy Weir - Project Hail Mary (2021) Audiobook ::INFO:: 620.5MB"
+
+    result = parser.parse_result_line(line)
+
+    assert result.format == "unknown"
+    assert result.title == "Project Hail Mary (2021) Audiobook"
+    assert result.size == "620.5MB"
+
+
+@pytest.mark.parametrize(
+    ("line", "expected"),
+    [
+        ("!s A - T.epub ::INFO:: 1MB", "ebook"),
+        ("!s A - T.mp3 ::INFO:: 1MB", "audiobook"),
+        ("!s A - T.flac ::INFO:: 1MB", "audiobook"),
+        # Archives carry no format information, so the name has to decide.
+        ("!s A - T (Audiobook).rar ::INFO:: 1MB", "audiobook"),
+        ("!s A - T [Unabridged].zip ::INFO:: 1MB", "audiobook"),
+        ("!s A - T (Narrated by Someone).rar ::INFO:: 1MB", "audiobook"),
+        ("!s A - T [64kbps].zip ::INFO:: 1MB", "audiobook"),
+        ("!s A - T (retail).rar ::INFO:: 1MB", "ebook"),
+        ("!s A - T.zip ::INFO:: 1MB", "ebook"),
+    ],
+)
+def test_detect_content_type(line, expected):
+    assert parser.detect_content_type(parser.parse_result_line(line)) == expected
+
+
+def test_recognized_formats_order_is_deterministic():
+    """This was a set, so which format won for a multi-extension line varied per restart."""
+    assert parser.ALL_RECOGNIZED_FORMATS == tuple(parser.ALL_RECOGNIZED_FORMATS)
+    # Longest-first, so ".azw3" cannot be truncated to "azw" (nor ".docx" to "doc").
+    lengths = [len(fmt) for fmt in parser.ALL_RECOGNIZED_FORMATS]
+    assert lengths == sorted(lengths, reverse=True)
+

 def test_parse_results_file_uses_audiobook_format_settings(monkeypatch):
    values = {
@@ -0,0 +1,53 @@
+import pytest
+
+from shelfmark.metadata_providers import hardcover
+from shelfmark.metadata_providers.hardcover import (
+    HardcoverProvider,
+    _test_hardcover_connection,
+)
+
+# Hardcover replaced its ~500 char JWTs with short opaque tokens.
+PAT = "hc_pat_" + "a" * 32
+
+
+@pytest.fixture(autouse=True)
+def _no_config_writes(monkeypatch):
+    """Keep the connection test from touching the on-disk provider config."""
+    monkeypatch.setattr(hardcover, "_save_connected_user", lambda user_id, username: None)
+
+
+class TestHardcoverApiKey:
+    def test_personal_access_token_is_accepted(self, monkeypatch):
+        monkeypatch.setattr(
+            HardcoverProvider,
+            "_execute_query",
+            lambda self, query, variables: {"me": [{"id": 1, "username": "alex"}]},
+        )
+
+        result = _test_hardcover_connection({"HARDCOVER_API_KEY": PAT})
+
+        assert result == {"success": True, "message": "Connected as: alex"}
+
+    def test_short_key_without_the_prefix_is_rejected(self):
+        result = _test_hardcover_connection({"HARDCOVER_API_KEY": "eyJhbGciOiJIUzI1NiJ9.short"})
+
+        assert result["success"] is False
+        assert "too short" in result["message"]
+
+    def test_short_prefixed_key_still_reaches_the_api(self, monkeypatch):
+        """A key wearing the hc_pat_ prefix is Hardcover's to accept or reject."""
+        monkeypatch.setattr(
+            HardcoverProvider,
+            "_execute_query",
+            lambda self, query, variables: None,
+        )
+
+        result = _test_hardcover_connection({"HARDCOVER_API_KEY": "hc_pat_ab"})
+
+        assert result == {"success": False, "message": "API request failed - check your API key"}
+
+    @pytest.mark.parametrize("pasted", [f"Bearer {PAT}", f"bearer {PAT}", f"  {PAT}  "])
+    def test_pasted_auth_header_noise_is_stripped(self, pasted):
+        provider = HardcoverProvider(api_key=pasted)
+
+        assert provider.session.headers["Authorization"] == f"Bearer {PAT}"
--- a/Show More
+++ b/Show More