Add smart-import decision for importBlocked items before blocklisting

Most importBlocked downloads are junk/duplicates and still fall straight
through to blocklist+research unchanged. But some are releases arr already
correctly parsed (episode/movie, quality, language all known) that just
trip the title-vs-grab-history safety net — those get imported directly
if the target has no file yet, or the candidate is a same-language
resolution upgrade over what's already there. Sonarr/Radarr only; Lidarr's
manual-import matching doesn't reliably resolve album/track context.

Gated by ARR_SMART_IMPORT_ENABLED (default true) and
ARR_SMART_IMPORT_PREFERRED_LANGUAGE (default English).

Arrs_Stack/arrs_failed_stalled_recovery.sh

@@ -18,18 +18,22 @@
 #   importPending  — downloaded, stuck waiting to import (will not self-resolve)
 #   importBlocked  — downloaded, but arr matched the release to the wrong media
 #                    by grab-history ID instead of by title and refuses to import
-#                    (permanent block, never self-resolves — same handling as
+#                    (permanent block, never self-resolves)
-#                    importFailed since most real-world cases are junk/duplicate
-#                    releases; the rare case where the file is actually good but
-#                    mis-parsed will just get re-searched instead of manually
-#                    imported, an acceptable tradeoff for hands-free operation)
 #   error status   — serious failure not covered by the above two states
 #   stalled        — download stuck with no connections or no progress
 #
 # Never touches items with state "downloading" or "imported" — safe to run anytime.
 # Items newer than ARR_IMPORT_RECOVERY_AGE are skipped — gives arr time to retry first.
 #
-# Per problem item (3-step response):
+# importBlocked items get one extra check first (try_smart_import, Sonarr/Radarr only):
+# most are junk/duplicates and fall straight through to the normal 3-step response below,
+# but some are a release arr already correctly parsed — episode/movie identified, quality
+# and language known — that's just tripping the title-vs-grab-history safety net. If the
+# target has no file yet (missing) or the candidate is a same-language resolution upgrade
+# over what's already there, it's imported directly instead of being discarded. See
+# ARR_SMART_IMPORT_ENABLED in CONFIGURATION below.
+#
+# Per problem item that isn't smart-imported (3-step response):
 #   1. Blocklist the release  — prevents re-grabbing the same bad release
 #   2. Remove from queue      — cleans up the failed item
 #   3. Trigger new search     — finds a different release automatically
@@ -43,6 +47,14 @@
 #   re-search. No operator decision required. A failed import at midnight resolves
 #   itself before morning without any intervention.
 #
+# Smart Import Is Conservative By Design
+#   try_smart_import only acts when every file in the download is unambiguous: no
+#   rejections from arr's own analysis, and (no existing file) or (matching language
+#   plus a strictly higher resolution). Any ambiguity — mixed multi-episode files,
+#   unknown language, equal-or-lower quality, wrong language — falls straight through
+#   to blocklist+research, exactly today's behavior. It only ever adds a chance to
+#   keep something worth keeping; it never makes the no-smart-import case worse.
+#
 # Age Gate Before Action
 #   Items newer than ARR_IMPORT_RECOVERY_AGE are skipped. Arrs have their own
 #   retry logic — acting immediately would race against it. The age gate gives
@@ -103,6 +115,13 @@
 #   ARR_IMPORT_RECOVERY_AGE — hours before item is eligible for recovery (default: 6)
 #   ARR_RECOVERY_MAX_ATTEMPTS — consecutive failures before an item is flagged chronic
 #                             and auto re-search stops (default: 3)
+#   ARR_SMART_IMPORT_ENABLED — try_smart_import gate for importBlocked items, Sonarr/
+#                             Radarr only — Lidarr's manual-import matching doesn't
+#                             reliably resolve album/track context (default: true)
+#   ARR_SMART_IMPORT_PREFERRED_LANGUAGE — only import as a match/upgrade if the
+#                             candidate is this language; existing files in a
+#                             different language are always treated as upgradeable
+#                             (default: English)
 #   SONARR_VERSION_MAJOR    — expected Sonarr major version (e.g. 4)
 #   RADARR_VERSION_MAJOR    — expected Radarr major version (e.g. 6)
 #   LIDARR_VERSION_MAJOR    — expected Lidarr major version (e.g. 3)
@@ -174,6 +193,7 @@ fi
 TOTAL_ACTIONED=0
 TOTAL_SKIPPED=0
 TOTAL_CHRONIC=0
+TOTAL_SMART_IMPORTED=0
 ARR_SUMMARIES=()
 
 # ==============================================================================================
@@ -188,6 +208,7 @@ if [[ "$SHOW_STATUS" == true ]]; then
     echo "$ICON_SYNC    Lidarr:      ${LIDARR_URL:-not configured on this host} (recovery: ${LIDARR_RECOVERY:-false})"
     echo "$ICON_TIME    Age thresh:  ${ARR_IMPORT_RECOVERY_AGE}hr"
     echo "$ICON_GEAR    Max attempts: ${ARR_RECOVERY_MAX_ATTEMPTS:-3} (chronic after this many)"
+    echo "$ICON_GEAR    Smart import: ${ARR_SMART_IMPORT_ENABLED:-true} (preferred language: ${ARR_SMART_IMPORT_PREFERRED_LANGUAGE:-English})"
     echo "$ICON_GEAR    Sonarr ver:  v${SONARR_VERSION_MAJOR} expected"
     echo "$ICON_GEAR    Radarr ver:  v${RADARR_VERSION_MAJOR} expected"
     echo "$ICON_GEAR    Lidarr ver:  v${LIDARR_VERSION_MAJOR} expected"
@@ -287,6 +308,132 @@ trigger_search() {
         >/dev/null 2>&1
 }
 
+# Decide whether an importBlocked download is actually worth keeping, and import
+# it directly if so — instead of always discarding it via blocklist+research.
+#
+# Fires the ManualImport command and returns as soon as it's accepted (HTTP 201)
+# rather than polling for completion. Deliberately does NOT fall back to
+# blocklist_item() after a successful trigger: Radarr/Sonarr's import runs async
+# in the background, and blocklisting (which deletes the source via
+# removeFromClient) right after firing it would race a still-in-progress import
+# for anything but the smallest files. If the import silently fails, the item
+# simply reappears as importBlocked next run and gets tried again — safe, if not
+# maximally fast, since the source file is never touched by this function.
+#
+# Returns 0 if a smart-import was triggered (caller should skip the normal
+# blocklist+research path for this item), 1 if declined or failed (caller should
+# fall through to the normal path exactly as before this function existed).
+# Args: url, api_key, api_version, arr_type, download_id, title
+try_smart_import() {
+    local url="$1" api_key="$2" api_version="$3" arr_type="$4" download_id="$5" title="$6"
+
+    # Lidarr's manual-import matching doesn't reliably resolve album/track context
+    # (confirmed 2026-07-15 — 659/659 track candidates came back with no album
+    # match at all) — not worth attempting, always fall through to normal handling.
+    [[ "$arr_type" == "lidarr" ]] && return 1
+    [[ -z "$download_id" ]] && return 1
+
+    local candidates
+    candidates=$(curl -sf --max-time 30 \
+        -H "X-Api-Key: $api_key" \
+        "${url}/api/${api_version}/manualimport?downloadId=${download_id}" \
+        2>/dev/null)
+    [[ -z "$candidates" || "$candidates" == "[]" || "$candidates" == "null" ]] && return 1
+
+    # Any rejected file (Sample, Unknown Movie/Series, "Not an upgrade", etc.)
+    # disqualifies the whole download — conservative by design.
+    local rejected_count
+    rejected_count=$(echo "$candidates" | jq '[.[] | select(.rejections | length > 0)] | length' 2>/dev/null)
+    [[ -z "$rejected_count" || "$rejected_count" -gt 0 ]] && return 1
+
+    local file_count
+    file_count=$(echo "$candidates" | jq 'length' 2>/dev/null)
+    [[ -z "$file_count" || "$file_count" -eq 0 ]] && return 1
+
+    local preferred_lang="${ARR_SMART_IMPORT_PREFERRED_LANGUAGE:-English}"
+    local qualifying_files=()
+    local i entry target_id has_file existing existing_res existing_lang candidate_res candidate_lang decision
+
+    for (( i=0; i<file_count; i++ )); do
+        entry=$(echo "$candidates" | jq -c ".[$i]" 2>/dev/null)
+        [[ -z "$entry" ]] && return 1
+
+        candidate_res=$(echo "$entry" | jq -r '.quality.quality.resolution // 0' 2>/dev/null)
+        candidate_lang=$(echo "$entry" | jq -r '.languages[0].name // "Unknown"' 2>/dev/null)
+        existing_res=0
+        existing_lang="Unknown"
+        target_id=""
+        has_file="false"
+
+        case "$arr_type" in
+            sonarr)
+                # Multi-episode files complicate the existing-quality comparison per
+                # episode — skip rather than guess when a release covers more than one.
+                [[ "$(echo "$entry" | jq '.episodes | length' 2>/dev/null)" != "1" ]] && return 1
+                target_id=$(echo "$entry" | jq -r '.episodes[0].id // empty' 2>/dev/null)
+                has_file=$(echo "$entry" | jq -r '.episodes[0].hasFile // false' 2>/dev/null)
+                if [[ "$has_file" == "true" ]]; then
+                    existing=$(curl -sf --max-time 15 -H "X-Api-Key: $api_key" \
+                        "${url}/api/${api_version}/episode/${target_id}?includeEpisodeFile=true" 2>/dev/null)
+                    existing_res=$(echo "$existing" | jq -r '.episodeFile.quality.quality.resolution // 0' 2>/dev/null)
+                    existing_lang=$(echo "$existing" | jq -r '.episodeFile.languages[0].name // "Unknown"' 2>/dev/null)
+                fi
+                ;;
+            radarr)
+                target_id=$(echo "$entry" | jq -r '.movie.id // empty' 2>/dev/null)
+                has_file=$(echo "$entry" | jq -r '.movie.hasFile // false' 2>/dev/null)
+                if [[ "$has_file" == "true" ]]; then
+                    existing=$(echo "$entry" | jq -c '.movie.movieFile // empty' 2>/dev/null)
+                    if [[ -z "$existing" || "$existing" == "null" ]]; then
+                        existing=$(curl -sf --max-time 15 -H "X-Api-Key: $api_key" \
+                            "${url}/api/${api_version}/movie/${target_id}" 2>/dev/null | jq -c '.movieFile // empty')
+                    fi
+                    existing_res=$(echo "$existing" | jq -r '.quality.quality.resolution // 0' 2>/dev/null)
+                    existing_lang=$(echo "$existing" | jq -r '.languages[0].name // "Unknown"' 2>/dev/null)
+                fi
+                ;;
+        esac
+
+        [[ -z "$target_id" ]] && return 1
+
+        if [[ "$has_file" != "true" ]]; then
+            decision="import"      # nothing there yet — fills a real gap
+        elif [[ "$candidate_lang" != "$preferred_lang" ]]; then
+            decision="decline"     # never replace anything with a non-preferred language
+        elif [[ "$existing_lang" != "$preferred_lang" ]]; then
+            decision="import"      # existing is wrong-language, candidate is right — upgrade
+        elif [[ "$candidate_res" -gt "$existing_res" ]]; then
+            decision="import"      # same language, strictly higher resolution — upgrade
+        else
+            decision="decline"     # same or worse, same language — no benefit
+        fi
+
+        [[ "$decision" == "decline" ]] && return 1
+        qualifying_files+=("$entry")
+    done
+
+    [[ "${#qualifying_files[@]}" -eq 0 ]] && return 1
+
+    if [[ "$DRY_RUN" == true ]]; then
+        warn "  DRY RUN — would smart-import: $title"
+        return 0
+    fi
+
+    local files_json cmd_body http_code
+    files_json=$(printf '%s\n' "${qualifying_files[@]}" | jq -s -c '.' 2>/dev/null)
+    [[ -z "$files_json" ]] && return 1
+    cmd_body=$(jq -c -n --argjson files "$files_json" \
+        '{name:"ManualImport", files:$files, importMode:"auto"}' 2>/dev/null)
+    [[ -z "$cmd_body" ]] && return 1
+
+    http_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+        -H "X-Api-Key: $api_key" -H "Content-Type: application/json" \
+        -d "$cmd_body" \
+        "${url}/api/${api_version}/command" 2>/dev/null)
+
+    [[ "$http_code" == "201" ]]
+}
+
 # ==============================================================================================
 # ── PROCESS AN ARR ────────────────────────────────────────────────────────────────────────────
 # ==============================================================================================
@@ -308,7 +455,7 @@ process_arr() {
     local version_major="$7"
     local version_api_prefix="$8"
 
-    local actioned=0 skipped_new=0 chronic=0
+    local actioned=0 skipped_new=0 chronic=0 smart_imported=0
     local is_chronic fail_key fail_count
 
     echo ""
@@ -391,7 +538,7 @@ process_arr() {
     while IFS= read -r item; do
         [[ -z "$item" ]] && continue
 
-        local queue_id title added tracked_state tracked_status problem_type media_id
+        local queue_id title added tracked_state tracked_status problem_type media_id download_id
 
         queue_id=$(echo "$item"       | jq -r '.id // empty' 2>/dev/null)
         title=$(echo "$item"          | jq -r '.title // "Unknown"' 2>/dev/null)
@@ -427,6 +574,23 @@ process_arr() {
             continue
         fi
 
+        # importBlocked gets one extra chance before the normal blocklist path —
+        # most are junk/duplicates and fall straight through unchanged, but a
+        # clean same-language upgrade or gap-fill gets imported directly instead
+        # of discarded. See try_smart_import() for the full decision logic.
+        if [[ "${ARR_SMART_IMPORT_ENABLED:-true}" == "true" ]] && \
+           [[ "$tracked_state" == "importBlocked" ]]; then
+            download_id=$(echo "$item" | jq -r '.downloadId // empty' 2>/dev/null)
+            if try_smart_import "$url" "$api_key" "$api_version" "$arr_type" "$download_id" "$title"; then
+                log "  $ICON_DONE Smart-imported (upgrade/gap-fill): $title"
+                (( smart_imported++ ))
+                (( TOTAL_SMART_IMPORTED++ ))
+                (( actioned++ ))
+                (( TOTAL_ACTIONED++ ))
+                continue
+            fi
+        fi
+
         warn "  $ICON_TRASH $problem_type — $title"
 
         # Step 1: Blocklist + remove from queue
@@ -476,12 +640,12 @@ process_arr() {
     done <<< "$problem_items"
 
     if [[ "$actioned" -gt 0 ]]; then
-        warn "$arr_name — actioned: $actioned | skipped (too new): $skipped_new | chronic: $chronic"
+        warn "$arr_name — actioned: $actioned (smart-imported: $smart_imported) | skipped (too new): $skipped_new | chronic: $chronic"
     else
         log "$arr_name — nothing actioned | skipped (too new): $skipped_new"
     fi
 
-    ARR_SUMMARIES+=("$arr_name: actioned $actioned | too new $skipped_new | chronic $chronic")
+    ARR_SUMMARIES+=("$arr_name: actioned $actioned (smart-imported $smart_imported) | too new $skipped_new | chronic $chronic")
 }
 
 # ==============================================================================================
@@ -546,6 +710,7 @@ echo "━━━━━ $ICON_SUMMARY ARR RECOVERY SUMMARY ━━━━━"
 echo "$ICON_HOST    Identity: $MY_ID ($LOCAL_SERVER_NAME)"
 echo "$ICON_TIME    Duration: $(format_duration $(( END - START )))"
 echo "$ICON_TRASH   Actioned: $TOTAL_ACTIONED items blocklisted + searched"
+echo "$ICON_DONE    Smart-imported: $TOTAL_SMART_IMPORTED items (upgrade/gap-fill, kept instead of discarded)"
 echo "$ICON_SKIP    Skipped:  $TOTAL_SKIPPED items (too new)"
 echo "$ICON_WARN    Chronic:  $TOTAL_CHRONIC items (blocklisted, auto re-search stopped)"
 echo ""

Deployment/master.conf.template

@@ -1205,9 +1205,12 @@
 # Auto blocklist + re-search failed imports and stalled downloads.
 # Runs every 6 hours — schedule: 0 */6 * * *
 #
-# Targets four problem types:
+# Targets five problem types:
 #   importFailed   — downloaded but arr couldn't import
 #   importPending  — downloaded, stuck waiting to import (won't self-resolve)
+#   importBlocked  — arr matched the release by grab-history ID, not title, and
+#                    refuses to auto-import — gets a smart-import check first,
+#                    see ARR_SMART_IMPORT_ENABLED below
 #   error status   — serious failure not covered above
 #   stalled        — download stuck with no connections or progress
 #
@@ -1217,6 +1220,12 @@
                                         # matches cron interval — items eligible after one missed cycle
     ARR_RECOVERY_MAX_ATTEMPTS=3         # consecutive failures before an item is flagged chronic
                                         # and auto re-search stops (still blocklisted/cleaned up)
+    ARR_SMART_IMPORT_ENABLED=true       # importBlocked items: try importing a clean same-language
+                                        # upgrade/gap-fill directly before falling back to blocklist
+                                        # + re-search. Sonarr/Radarr only — see try_smart_import()
+    ARR_SMART_IMPORT_PREFERRED_LANGUAGE="English"  # only treated as a match/upgrade if the
+                                        # candidate is this language; an existing file in a
+                                        # different language is always considered upgradeable
 
 # ==============================================================================================
 # ── TRANSCODES ────────────────────────────────────────────────────────────────────────────────