feat: download lifecycle — stalled and failed downloads are given up and searched again; imported ones seed, then go (M502 #5523)

Ported from Fabled Librarian's System 104. A new lifecycle poller, every
ten minutes:
- a download the client fails is given up at once;
- one nobody shares, or still fetching its file list, past the stall
  setting (6 h) is asked for again three times, then given up;
- giving up removes the download with its files, holds the release back
  for a week (release_blocks.expires_at), ends the grab and searches the
  album again, with no limit per album;
- a running download the client stops listing for half an hour ends and is
  searched again, not held back; an empty list is not taken as gone;
- an imported download seeds to ratio 2.0 or 14 days, then is removed;
- a download the client would not remove is asked again every pass.

Every condition and act is one open row per (client, download, condition)
in download_interventions. Activity shows what is wrong with a download and
how often it was retried, why one ended, its seeding, and a banner for a
client that does not answer. A running download can be given up by hand
(set aside for good). The seed ratio, seed days and stall hours are on the
search settings card. The download client lookup moves to
acquire.DownloadClientFor, shared by the importer and the lifecycle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/db/queries/imports.sql

@@ -51,6 +51,9 @@ UPDATE grabs
        import_updated_at = now(),
        import_forced = false,
        imported_at = CASE WHEN sqlc.arg(import_state)::text = 'imported' THEN now() ELSE imported_at END,
+       -- The files were copied, so an imported download goes on sharing
+       -- until the lifecycle removes it (#5523).
+       seeding = sqlc.arg(import_state)::text = 'imported',
        imported_files = sqlc.arg(imported_files),
        destination = sqlc.arg(destination),
        ended_at = CASE WHEN sqlc.arg(end_reason)::text <> '' THEN now() ELSE ended_at END,
@@ -110,21 +113,30 @@ SELECT DISTINCT COALESCE(t.disc_number, 1)::int AS disc, t.track_number::int AS
 
 -- name: ListGrabs :many
 -- The Wanted view's Activity tab: downloads waiting on a person first, then
--- the rest still running, then the ended ones newest first.
+-- the rest still running, then the ended ones newest first. Each carries
+-- what is wrong with it now, if anything (#5523).
 SELECT g.id, g.want_id, g.name, g.indexer, g.client, g.quality, g.origin, g.forced,
        g.grabbed_at, g.ended_at, g.end_reason, g.end_detail, g.progress, g.import_state,
        g.import_reason, g.import_detail, g.import_updated_at, g.imported_at, g.imported_files,
-       g.destination, w.title AS want_title, w.artist_name AS want_artist
+       g.destination, g.seeding, g.ratio, g.seed_released_at,
+       w.title AS want_title, w.artist_name AS want_artist,
+       di.trigger AS condition, di.detail AS condition_detail, di.remediations AS condition_retries,
+       di.first_seen AS condition_since
   FROM grabs g
   LEFT JOIN wants w ON w.id = g.want_id
+  LEFT JOIN download_interventions di
+         ON di.id = (SELECT x.id FROM download_interventions x
+                      WHERE x.grab_id = g.id AND x.outcome = 'open'
+                      ORDER BY x.last_seen DESC LIMIT 1)
  ORDER BY (g.ended_at IS NULL AND g.import_state IN ('review', 'failed')) DESC,
           g.ended_at IS NULL DESC, g.grabbed_at DESC, g.id
  LIMIT sqlc.arg(max_rows) OFFSET sqlc.arg(skip);
 
 -- name: ListReleaseBlocksPage :many
-SELECT b.info_hash, b.name, b.reason, b.detail, b.blocked_at, w.title AS want_title,
+SELECT b.info_hash, b.name, b.reason, b.detail, b.blocked_at, b.expires_at, w.title AS want_title,
        w.artist_name AS want_artist
   FROM release_blocks b
   LEFT JOIN wants w ON w.id = b.want_id
+ WHERE b.expires_at IS NULL OR b.expires_at > now()
  ORDER BY b.blocked_at DESC, b.info_hash
  LIMIT sqlc.arg(max_rows) OFFSET sqlc.arg(skip);

internal/db/queries/lifecycle.sql

@@ -0,0 +1,96 @@
+-- The download lifecycle (M502 #5523): the intervention ledger, giving a
+-- download up, and seeding after import.
+
+-- name: RaiseIntervention :one
+-- A condition seen, or seen again: a second pass lands on the open row, so
+-- a download stuck for a week is one row that says how long. The name only
+-- improves, and the detail is the latest word.
+INSERT INTO download_interventions (client, info_hash, grab_id, name, trigger, detail)
+VALUES (sqlc.arg(client), sqlc.arg(info_hash), sqlc.narg(grab_id), sqlc.arg(name),
+        sqlc.arg(trigger), sqlc.arg(detail))
+ON CONFLICT (client, info_hash, trigger) WHERE outcome = 'open' DO UPDATE SET
+    observations = download_interventions.observations + 1,
+    last_seen    = now(),
+    detail       = EXCLUDED.detail,
+    grab_id      = COALESCE(EXCLUDED.grab_id, download_interventions.grab_id),
+    name         = CASE WHEN EXCLUDED.name <> '' THEN EXCLUDED.name ELSE download_interventions.name END
+RETURNING *;
+
+-- name: SettleIntervention :execrows
+-- The condition cleared.
+UPDATE download_interventions
+   SET outcome = 'resolved', settled_at = now(), last_seen = now()
+ WHERE client = sqlc.arg(client) AND info_hash = sqlc.arg(info_hash)
+   AND trigger = sqlc.arg(trigger) AND outcome = 'open';
+
+-- name: SettleInterventionsFor :execrows
+-- Everything open about one download is over: it is gone from the client.
+UPDATE download_interventions
+   SET outcome = 'resolved', settled_at = now(), last_seen = now()
+ WHERE client = sqlc.arg(client) AND info_hash = sqlc.arg(info_hash) AND outcome = 'open';
+
+-- name: SettleEndedGrabs :execrows
+-- What was wrong with a download whose grab has ended (imported, refused,
+-- given up) is over, except a download left in the client to remove.
+UPDATE download_interventions di
+   SET outcome = 'resolved', settled_at = now(), last_seen = now()
+  FROM grabs g
+ WHERE g.id = di.grab_id AND g.ended_at IS NOT NULL
+   AND di.outcome = 'open' AND di.trigger <> 'not_removed';
+
+-- name: CountRemediation :one
+-- Minstrel acted on an open condition. A retry climbs the ladder; giving up
+-- or removing ends the condition, since what it was about is gone. Written
+-- before the act, so a retry that happened is never uncounted.
+UPDATE download_interventions
+   SET remediations = remediations + 1,
+       action       = sqlc.arg(action),
+       last_seen    = now(),
+       outcome      = CASE WHEN sqlc.arg(action)::text IN ('given_up', 'removed') THEN 'resolved' ELSE outcome END,
+       settled_at   = CASE WHEN sqlc.arg(action)::text IN ('given_up', 'removed') THEN now() ELSE settled_at END
+ WHERE client = sqlc.arg(client) AND info_hash = sqlc.arg(info_hash)
+   AND trigger = sqlc.arg(trigger) AND outcome = 'open'
+RETURNING remediations;
+
+-- name: ListLeftovers :many
+-- Downloads given up on that the client would not remove; each pass asks
+-- again.
+SELECT * FROM download_interventions
+ WHERE trigger = 'not_removed' AND outcome = 'open' AND info_hash <> ''
+ ORDER BY first_seen;
+
+-- name: ListClientsDown :many
+-- Download clients not answering now, for the Activity tab.
+SELECT client, detail, first_seen FROM download_interventions
+ WHERE trigger = 'client_unreachable' AND outcome = 'open'
+ ORDER BY client;
+
+-- name: LiveGrabOnHash :one
+SELECT EXISTS (SELECT 1 FROM grabs WHERE info_hash = sqlc.arg(info_hash) AND ended_at IS NULL)::bool;
+
+-- name: GiveUpGrab :one
+-- Ends a running grab, given up on. Only from the states named: the update
+-- is the lock against an import that claimed the download meanwhile.
+UPDATE grabs
+   SET ended_at = now(), end_reason = sqlc.arg(end_reason), end_detail = sqlc.arg(end_detail),
+       import_updated_at = now()
+ WHERE id = sqlc.arg(id) AND ended_at IS NULL AND import_state = ANY(sqlc.arg(states)::text[])
+RETURNING *;
+
+-- name: ListSeedingGrabs :many
+-- Imported downloads still sharing, oldest import first.
+SELECT id, client, info_hash, name, imported_at FROM grabs
+ WHERE seeding AND seed_released_at IS NULL
+ ORDER BY imported_at, id;
+
+-- name: SetGrabRatio :exec
+UPDATE grabs SET ratio = sqlc.arg(ratio) WHERE id = sqlc.arg(id);
+
+-- name: ReleaseSeed :exec
+-- The seeding download was removed, or found gone.
+UPDATE grabs SET seed_released_at = now() WHERE id = $1 AND seed_released_at IS NULL;
+
+-- name: DeleteExpiredBlocks :execrows
+-- A release given up on is held back for a while; after that the search may
+-- take it again.
+DELETE FROM release_blocks WHERE expires_at IS NOT NULL AND expires_at <= now();

internal/db/queries/search.sql

@@ -9,6 +9,9 @@ UPDATE acquisition_settings
        search_interval_hours = sqlc.arg(search_interval_hours),
        allowed_qualities     = sqlc.arg(allowed_qualities),
        import_root           = sqlc.arg(import_root),
+       seed_ratio            = sqlc.arg(seed_ratio),
+       seed_days             = sqlc.arg(seed_days),
+       stall_hours           = sqlc.arg(stall_hours),
        updated_at            = now()
  WHERE id = true
 RETURNING *;
@@ -109,14 +112,23 @@ UPDATE grabs
  WHERE id = sqlc.arg(id) AND ended_at IS NULL;
 
 -- name: ListReleaseBlocks :many
-SELECT * FROM release_blocks ORDER BY blocked_at DESC;
+-- Every release set aside and still held back: a stalled one lifts by itself
+-- at expires_at (#5523).
+SELECT * FROM release_blocks
+ WHERE expires_at IS NULL OR expires_at > now()
+ ORDER BY blocked_at DESC;
 
 -- name: BlockRelease :exec
-INSERT INTO release_blocks (info_hash, name, reason, detail, want_id, blocked_by)
+-- A release set aside. expires_at NULL is for good. A block for good is never
+-- shortened by a timed one: only a timed block, or another for good, is
+-- replaced.
+INSERT INTO release_blocks (info_hash, name, reason, detail, want_id, blocked_by, expires_at)
 VALUES (sqlc.arg(info_hash), sqlc.arg(name), sqlc.arg(reason), sqlc.arg(detail),
-        sqlc.narg(want_id), sqlc.narg(blocked_by))
+        sqlc.narg(want_id), sqlc.narg(blocked_by), sqlc.narg(expires_at))
 ON CONFLICT (info_hash) DO UPDATE
-   SET reason = EXCLUDED.reason, detail = EXCLUDED.detail, blocked_at = now();
+   SET reason = EXCLUDED.reason, detail = EXCLUDED.detail, blocked_at = now(),
+       expires_at = EXCLUDED.expires_at, blocked_by = EXCLUDED.blocked_by
+ WHERE release_blocks.expires_at IS NOT NULL OR EXCLUDED.expires_at IS NULL;
 
 -- name: UnblockRelease :execrows
 DELETE FROM release_blocks WHERE info_hash = $1;

internal/db/queries/wanted.sql

@@ -194,7 +194,7 @@ SELECT w.id, w.release_group_mbid, w.artist_mbid, w.artist_name, w.title, w.reas
        gr.id AS grab_id, gr.name AS grab_name, gr.grabbed_at, gr.origin AS grab_origin,
        gr.quality AS grab_quality, gr.ended_at AS grab_ended_at, gr.end_reason AS grab_end_reason,
        gr.progress AS grab_progress, gr.import_state AS grab_import_state,
-       gr.import_reason AS grab_import_reason, gr.imported_at AS grab_imported_at,
+       gr.import_reason AS grab_import_reason, gr.end_detail AS grab_end_detail, gr.imported_at AS grab_imported_at,
        gr.imported_files AS grab_imported_files
   FROM wants w
   LEFT JOIN users u ON u.id = w.created_by
@@ -219,5 +219,6 @@ SELECT COUNT(*) FILTER (WHERE fulfilled_at IS NULL AND reason <> 'missing')::big
        (SELECT COUNT(*) FROM grabs WHERE ended_at IS NULL)::bigint                  AS activity,
        (SELECT COUNT(*) FROM grabs
          WHERE ended_at IS NULL AND import_state IN ('review', 'failed'))::bigint   AS attention,
-       (SELECT COUNT(*) FROM release_blocks)::bigint                                AS blocked
+       (SELECT COUNT(*) FROM release_blocks b
+         WHERE b.expires_at IS NULL OR b.expires_at > now())::bigint               AS blocked
   FROM wants;