fix(downloads): rewire MaintenanceMenu to the downloads pipeline

The maintenance dropdown in Subscriptions → Downloads was wired to the
filesystem-import pipeline (POST /api/import/retry-failed +
POST /api/import/clear-stuck) — the subtitles even said so ("Re-enqueue
every failed import task"), but it was contextually misplaced. From the
Downloads view "Retry failed" queued nothing the operator could see
because the action operated on import_task rows, not download_event
rows. Import-pipeline maintenance is already reachable from Settings →
Imports (ImportTaskList.vue), so removing the import wiring loses
nothing.

Rewired:
- "Retry failed" → bulk-retries the failing-sources list, same loop as
  FailingSourcesCard's RETRY ALL (sourcesStore.checkNow per source).
  Subtitle now matches: "Re-queue every currently failing source".
- "Force recovery sweep" → triggers recover_stalled_download_events on
  demand via a new POST /api/downloads/recover-stalled endpoint. The
  sweep also runs every 5 min on Beat; this is the manual fallback so
  the operator doesn't have to wait for the next tick to clear newly
  stranded events.

MaintenanceMenu is now stateless — emits retry-failed and recover-
stalled. DownloadsTab owns the handlers (reuses the existing
onRetryAll; new onRecoverStalled with a delayed refresh so swept rows
land in the failing rollup).

Operator-flagged 2026-05-29 — "the retry failed button in the
maintenance dropdown doesn't appear to queue anything but manual
requeues works."

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

backend/app/api/downloads.py

@@ -187,3 +187,20 @@ async def get_download(event_id: int):
             return jsonify({"error": "not_found"}), 404
         event, source, artist = row
     return jsonify(_detail_record(event, source, artist))
+
+
+@downloads_bp.route("/recover-stalled", methods=["POST"])
+async def recover_stalled():
+    """Trigger the recover_stalled_download_events sweep on demand.
+
+    The same sweep runs every 5 min via Beat (see celery_app.beat_schedule);
+    this endpoint exists so the operator can force-clear stuck pending/
+    running download_events from the Subscriptions → Downloads maintenance
+    menu without waiting for the next scheduled tick.
+    """
+    # Local import: avoids registering maintenance tasks during blueprint
+    # import (Celery task discovery races with the API import otherwise).
+    from ..tasks.maintenance import recover_stalled_download_events
+
+    recover_stalled_download_events.delay()
+    return jsonify({"queued": True}), 202

frontend/src/components/subscriptions/DownloadsTab.vue

@@ -22,7 +22,10 @@
           <v-icon>mdi-refresh</v-icon>
           <v-tooltip activator="parent" location="top">Refresh</v-tooltip>
         </v-btn>
-        <MaintenanceMenu @refresh="refresh" />
+        <MaintenanceMenu
+          @retry-failed="onRetryAll(store.failing)"
+          @recover-stalled="onRecoverStalled"
+        />
       </div>
 
       <div class="fc-dl__controls">
@@ -207,6 +210,24 @@ async function onRetryAll(sources) {
   toast({ text: parts.join(', ') || 'Nothing to retry', type: 'info' })
 }
 
+// Manual trigger for recover_stalled_download_events. The sweep runs on
+// Beat every 5 min; this lets the operator force-clear stuck pending/
+// running events on demand. Fire-and-forget: the API returns 202 once the
+// task is dispatched, and we refresh after a few seconds so swept rows
+// show up in the failing rollup.
+async function onRecoverStalled() {
+  try {
+    await store.recoverStalled()
+    toast({
+      text: 'Recovery sweep queued — refreshing in a few seconds',
+      type: 'success',
+    })
+    setTimeout(refresh, 4000)
+  } catch (e) {
+    toast({ text: `Sweep failed: ${e?.detail || e?.message || e}`, type: 'error' })
+  }
+}
+
 // Live auto-refresh: while any download is queued or running, poll the
 // stats + first page every 4s so the operator can watch events succeed/
 // fail in real time without hitting Refresh. Polling stops automatically

frontend/src/components/subscriptions/MaintenanceMenu.vue

@@ -9,14 +9,14 @@
       <v-list-item
         prepend-icon="mdi-refresh"
         title="Retry failed"
-        subtitle="Re-enqueue every failed import task"
-        @click="onRetry"
+        subtitle="Re-queue every currently failing source"
+        @click="emit('retry-failed')"
       />
       <v-list-item
         prepend-icon="mdi-broom"
-        title="Clear stuck"
-        subtitle="Mark long-running import tasks failed and finalize their batch"
-        @click="onClear"
+        title="Force recovery sweep"
+        subtitle="Mark stranded pending/running events as error (also runs every 5 min)"
+        @click="emit('recover-stalled')"
       />
       <v-list-item
         :disabled="true"
@@ -31,33 +31,9 @@
 </template>
 
 <script setup>
-import { toast } from '../../utils/toast.js'
-import { useImportStore } from '../../stores/import.js'
-
-const emit = defineEmits(['refresh'])
-const importStore = useImportStore()
-
-async function onRetry() {
-  try {
-    await importStore.retryFailed()
-    toast({ text: 'Retry queued', type: 'success' })
-    emit('refresh')
-  } catch (e) {
-    toast({ text: `Retry failed: ${e?.detail || e?.message || e}`, type: 'error' })
-  }
-}
-
-async function onClear() {
-  try {
-    const body = await importStore.clearStuck()
-    const n = body?.cleared ?? 0
-    toast({
-      text: n ? `Cleared ${n} stuck task${n === 1 ? '' : 's'}` : 'Nothing stuck',
-      type: 'success',
-    })
-    emit('refresh')
-  } catch (e) {
-    toast({ text: `Clear failed: ${e?.detail || e?.message || e}`, type: 'error' })
-  }
-}
+// The Downloads tab parent (DownloadsTab.vue) owns the actual retry/sweep
+// handlers — same toast + refresh logic already used by the failing-sources
+// RETRY ALL button. We just emit. Import-pipeline maintenance lives in
+// Settings → Imports (ImportTaskList.vue), not here.
+const emit = defineEmits(['retry-failed', 'recover-stalled'])
 </script>

frontend/src/stores/downloads.js

@@ -88,10 +88,17 @@ export const useDownloadsStore = defineStore('downloads', () => {
     return activeEvents.value
   }
 
+  // POSTs to the download-recovery sweep endpoint (fire-and-forget — the
+  // Beat schedule also runs it every 5 min). The caller should refresh
+  // failing/stats a few seconds after this resolves to see swept rows.
+  async function recoverStalled() {
+    return api.post('/api/downloads/recover-stalled')
+  }
+
   return {
     events, cursor, hasMore, filter, selected, loading, error, stats,
     activity, failing, activeEvents,
     loadFirst, loadMore, loadOne, applyFilter, closeDetail, loadStats,
-    loadActivity, loadFailing, loadActive,
+    loadActivity, loadFailing, loadActive, recoverStalled,
   }
 })

tests/test_api_downloads.py

@@ -134,3 +134,23 @@ async def test_activity_returns_fixed_bucket_array(client, seed):
 async def test_activity_rejects_bogus_hours(client):
     resp = await client.get("/api/downloads/activity?hours=bogus")
     assert resp.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_recover_stalled_dispatches_task(client, monkeypatch):
+    """POST /api/downloads/recover-stalled returns 202 and dispatches the
+    recover_stalled_download_events task. The task body itself is exercised
+    in test_maintenance.py — this just covers the API → Celery hand-off."""
+    from backend.app.tasks import maintenance
+
+    called: list[tuple] = []
+    monkeypatch.setattr(
+        maintenance.recover_stalled_download_events, "delay",
+        lambda *a, **kw: called.append((a, kw)),
+    )
+
+    resp = await client.post("/api/downloads/recover-stalled")
+    assert resp.status_code == 202
+    body = await resp.get_json()
+    assert body == {"queued": True}
+    assert len(called) == 1