feat(downloads): bulk retry respects cooldown; single-source RETRY overrides

Today's platform-cooldown commit (61ce1ce) only filtered the scan tick
— manual /api/sources/<id>/check still bypassed it. Operator-flagged
2026-05-30: clicked "Retry failed" on a Patreon failure pile and saw
every one go 'queued' without realising the cooldown wasn't in the
loop. Bulk retry with N sources on a cooled-down platform bowls right
back into the rate limit the cooldown is trying to prevent.

**Backend (`/api/sources/<id>/check`):**
- Reads optional `?force=true` query flag.
- Without force: queries `active_platform_cooldowns` (renamed from the
  private `_platforms_in_cooldown` since it's now a cross-module API).
  If the source's platform is in cooldown, returns **202** with
  `{status: 'deferred', platform, cooldown_until}` — no event created,
  no dispatch.
- With force: cooldown skipped entirely.
- In-flight guard always applies (no point creating duplicate pendings).

**Frontend (`sourcesStore.checkNow(id, {force=false})`):** new optional
`force` flag → adds `?force=true` to the URL.

**Frontend (`DownloadsTab`):**
- `onRetrySource` (single-source RETRY click): passes `force: true` →
  explicit operator override, useful for rapid auth-fix testing.
- `onRetryAll` (RETRY ALL + MaintenanceMenu "Retry failed"): no force →
  cooldown respected. Tallies `deferred` alongside `queued` /
  `already_running`; toast reads e.g. *"5 queued, 12 deferred
  (cooldown), 3 already running"*. That count is the operator's
  diagnostic answer for "is rate-limit the cause of most failures?"
  (12-of-20 deferred → yes; 0 deferred → no).

**Auto-resume:** no new sweep needed. Deferred sources still have stale
`last_checked_at`, so the next scan tick after the cooldown AppSetting
expires picks them up via `select_due_sources` (which already filters
on `active_platform_cooldowns`).

Tests: two new — deferred-on-cooldown returns 202 with the right body
and no dispatch; force=true overrides the cooldown and creates the
event normally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/app/api/sources.py

@@ -5,7 +5,7 @@ from sqlalchemy import select
 
 from ..extensions import get_session
 from ..models import DownloadEvent, Source
-from ..services.scheduler_service import scheduler_status
+from ..services.scheduler_service import active_platform_cooldowns, scheduler_status
 from ..services.source_service import (
     KNOWN_PLATFORMS,
     ArtistNotFoundError,
@@ -125,7 +125,16 @@ async def check_source(source_id: int):
     """FC-3c: enqueue a download for this source.
 
     Returns 202 with the new DownloadEvent id. If a pending/running
-    event already exists for this source, returns 409 with that id."""
+    event already exists for this source, returns 409 with that id. If
+    the source's platform is currently in a rate-limit cooldown, returns
+    **202 with `{status: "deferred", cooldown_until, platform}`** and
+    does NOT create an event or dispatch — the bulk retry path uses this
+    to avoid bowling N sources right back into the rate limit the
+    cooldown is preventing. Single-click "retry this one source" passes
+    `?force=true` to override the cooldown (operator-explicit, useful
+    for rapid auth-fix testing). The in-flight guard always applies.
+    """
+    force = (request.args.get("force") or "").lower() in ("1", "true", "yes")
     async with get_session() as session:
         source = (await session.execute(
             select(Source).where(Source.id == source_id)
@@ -135,6 +144,19 @@ async def check_source(source_id: int):
         if not source.enabled:
             return _bad("source_disabled", detail="enable the source first")
 
+        # Cooldown gate (unless explicitly overridden). Checked before the
+        # in-flight guard because a deferred retry doesn't need to create
+        # or check for an event at all.
+        if not force:
+            cooldowns = await active_platform_cooldowns(session)
+            expires_at = cooldowns.get(source.platform)
+            if expires_at is not None:
+                return jsonify({
+                    "status": "deferred",
+                    "platform": source.platform,
+                    "cooldown_until": expires_at.isoformat(),
+                }), 202
+
         in_flight = (await session.execute(
             select(DownloadEvent.id).where(
                 DownloadEvent.source_id == source_id,