feat(ai_admin): enhance AI reconciliation engine, series deduplication, and artwork healing

Thunder/bot/plugins/ai_admin.py

@@ -30,7 +30,7 @@ from ai_admin.snapshot_store import SnapshotStore
 from ai_admin.telegram_router import TelegramAIAdminRouter
 from ai_admin.tool_registry import ToolRegistry
 from ai_admin.tool_runner import ToolRunner
-from ai_admin.tools_jellyfin import get_jellyfin_read_tool_definitions
+from ai_admin.tools_jellyfin import get_jellyfin_active_mutation_definitions, get_jellyfin_read_tool_definitions
 from ai_admin.tools_providers import get_provider_read_tool_definitions
 
 logger = logging.getLogger("Thunder.Plugin.AIAdmin")
@@ -110,6 +110,10 @@ def setup_ai_admin(client: Optional[Client] = None) -> Optional[TelegramAIAdminR
         for tool_def in get_jellyfin_read_tool_definitions(jf_client):
             registry.register(tool_def)
 
+        if config.mutations_enabled:
+            for tool_def in get_jellyfin_active_mutation_definitions(jf_client):
+                registry.register(tool_def)
+
         prov_client = ProvidersClient(
             tmdb_api_key=os.environ.get("TMDB_API_KEY", ""),
             fanart_api_key=os.environ.get("FANART_API_KEY", ""),

ai_admin/handler.py

@@ -144,19 +144,23 @@ class AIAdminHandler:
         system_prompt = (
             "You are an intelligent, friendly, and expert Jellyfin Media Server AI Assistant.\n"
             "You have direct control to inspect and manage the Jellyfin library and query metadata/artwork providers:\n"
-            "• Search Jellyfin library for movies, series, episodes (`jellyfin_search`, `jellyfin_get_item`, `jellyfin_get_media_info`).\n"
+            "• Search Jellyfin library for movies, series, episodes (`jellyfin_search`, `jellyfin_get_item`, `jellyfin_get_media_info`, `jellyfin_list_library`).\n"
+            "• Ground-Truth Telegram Files: Access all files injected from Telegram with their exact raw file names and message IDs (`telegram_list_injected`). Telegram injected files are the 100% ground truth.\n"
+            "• Library Reconciliation & Audit: Compare Telegram ground truth with Jellyfin items to detect rogue un-injected items, duplicate series, and title mismatches (`library_audit_and_compare`).\n"
+            "• Automatic Fixing & Cleanup: Reconcile mismatched items (`library_fix_item`), remove rogue items / duplicate series (`library_cleanup_rogue_and_duplicates`), and apply artwork (`jellyfin_apply_artwork`).\n"
             "• Search artwork & posters across providers (`artwork_search` for multi-provider search, `tmdb_get_images`, `cinemeta_search`, `cinemeta_get_meta`, `tvmaze_search`, `fanart_get_images`).\n"
-            "• Free providers like Cinemeta (IMDb catalog) and TVmaze require zero API keys and find authentic posters/thumbnails for movies and series.\n"
-            "• Query TMDb (themoviedb) for official details and images (`tmdb_search`, `tmdb_get_details`, `tmdb_get_images`).\n"
+            "• Free providers like Cinemeta (IMDb catalog) and TVmaze require zero API keys and find authentic posters/thumbnails for movies and series worldwide.\n"
             "• Search subtitles on OpenSubtitles (`opensubtitles_search`).\n\n"
             "Workflow Guidelines:\n"
-            "1. When the user asks to find a movie/series and check or fix its poster/thumbnail:\n"
-            "   a) FIRST search Jellyfin (`jellyfin_search`) to locate the item, its ID, current metadata, and existing artwork.\n"
-            "   b) THEN search artwork via `artwork_search` or `cinemeta_search` / `tmdb_get_images` using the title or IMDb/TMDb ID.\n"
-            "   c) PRESENT the results conversationally with titles, years, current status, and direct preview links for the best authentic posters found.\n"
-            "   d) Offer to apply the selected poster.\n"
-            "2. If the user is just chatting or asking a question that doesn't need tools, reply warmly, concisely, and conversationally.\n"
-            "3. Format all responses using Telegram markdown (*bold*, `code`, [link](url)). Never output raw JSON unless specifically requested."
+            "1. When the user asks to find a movie/series and check or fix its poster/thumbnail (e.g. Khalifa):\n"
+            "   a) Search Jellyfin (`jellyfin_search`) or Telegram files (`telegram_list_injected`) to find the exact item ID and raw filename.\n"
+            "   b) Search artwork via `artwork_search`, `cinemeta_search`, or `tmdb_get_images` using the title or IMDb ID (`tt22797990` for Khalifa).\n"
+            "   c) If requested, fix the item directly (`library_fix_item` or `jellyfin_apply_artwork`) and present the poster options conversationally.\n"
+            "2. When the user asks about rogue movies, duplicate series, or mismatched items:\n"
+            "   a) Run `library_audit_and_compare` to compare Telegram ground truth with Jellyfin.\n"
+            "   b) Explain the findings clearly and perform cleanup or reconciliation as needed.\n"
+            "3. If the user is just chatting or asking a general question, reply warmly, concisely, and conversationally.\n"
+            "4. Format all responses using Telegram markdown (*bold*, `code`, [link](url)). Never output raw JSON unless specifically requested."
         )
 
         messages = [{"role": "system", "content": system_prompt}]

ai_admin/jellyfin_client.py

@@ -98,11 +98,15 @@ class JellyfinClient:
         path: str,
         params: Optional[Dict[str, Any]] = None,
         json_body: Optional[Dict[str, Any]] = None,
+        raw_body: Optional[bytes] = None,
+        content_type: Optional[str] = None,
         session: Optional[aiohttp.ClientSession] = None,
     ) -> Any:
         """Execute HTTP request against Jellyfin API with timeout and payload capping."""
         url = f"{self.base_url}{path}"
         headers = self._get_auth_headers()
+        if content_type:
+            headers["Content-Type"] = content_type
 
         close_session = False
         if session is None:
@@ -110,19 +114,24 @@ class JellyfinClient:
             close_session = True
 
         try:
-            async with session.request(
-                method=method,
-                url=url,
-                params=params,
-                json=json_body,
-                headers=headers,
-                allow_redirects=False,
-                timeout=aiohttp.ClientTimeout(
+            req_kwargs: Dict[str, Any] = {
+                "method": method,
+                "url": url,
+                "params": params,
+                "headers": headers,
+                "allow_redirects": False,
+                "timeout": aiohttp.ClientTimeout(
                     total=self.timeout_seconds,
                     connect=min(3.0, self.timeout_seconds),
                     sock_read=self.timeout_seconds,
                 ),
-            ) as resp:
+            }
+            if json_body is not None:
+                req_kwargs["json"] = json_body
+            elif raw_body is not None:
+                req_kwargs["data"] = raw_body
+
+            async with session.request(**req_kwargs) as resp:
                 if resp.status in (301, 302, 303, 307, 308):
                     raise JellyfinError(f"Unexpected redirect from Jellyfin server (HTTP {resp.status}).")
                 if resp.status in (401, 403):
@@ -246,6 +255,7 @@ class JellyfinClient:
             "has_backdrop": len(backdrop_tags) > 0,
             "backdrop_count": len(backdrop_tags),
             "media_sources_count": len(data.get("MediaSources") or []),
+            "path": data.get("Path"),
             "path_basename": os.path.basename(str(data.get("Path") or "")),
         }
 
@@ -369,3 +379,121 @@ class JellyfinClient:
             "total_audio_tracks": len(audio_streams),
             "total_subtitle_tracks": len(subtitle_streams),
         }
+
+    async def get_all_library_items(
+        self,
+        include_item_types: str = "Movie,Series",
+        limit: int = 1000,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> List[Dict[str, Any]]:
+        """Fetch all media items in Jellyfin library with paths and provider IDs."""
+        bounded_limit = max(1, min(limit, 5000))
+        params = {
+            "Recursive": "true",
+            "IncludeItemTypes": include_item_types,
+            "Fields": "Path,ProviderIds,Overview,ProductionYear,ImageTags,BackdropImageTags,SeriesName,SeasonName",
+            "Limit": str(bounded_limit),
+        }
+        data = await self._request("GET", "/Items", params=params, session=session)
+        raw_items = data.get("Items") or []
+        results = []
+        for it in raw_items:
+            results.append({
+                "id": it.get("Id"),
+                "name": it.get("Name"),
+                "type": it.get("Type"),
+                "path": it.get("Path") or "",
+                "year": it.get("ProductionYear"),
+                "overview": it.get("Overview") or "",
+                "provider_ids": it.get("ProviderIds") or {},
+                "has_poster": bool((it.get("ImageTags") or {}).get("Primary")),
+                "has_backdrop": bool(it.get("BackdropImageTags")),
+                "series_name": it.get("SeriesName"),
+            })
+        return results
+
+    async def update_item_metadata(
+        self,
+        item_id: str,
+        fields: Dict[str, Any],
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> Dict[str, Any]:
+        """Update metadata fields (Name, ProductionYear, ProviderIds, Overview) for a Jellyfin item."""
+        if not validate_item_id(item_id):
+            raise ValueError(f"Invalid item_id format: '{item_id}'")
+
+        # Fetch current item representation first to preserve intact fields
+        current = await self._request("GET", f"/Items/{item_id}", session=session)
+        if not current:
+            raise JellyfinNotFoundError(f"Item '{item_id}' not found.")
+
+        # Merge allowed fields
+        for k, v in fields.items():
+            if k == "ProviderIds" and isinstance(v, dict):
+                current.setdefault("ProviderIds", {}).update(v)
+            else:
+                current[k] = v
+
+        await self._request("POST", f"/Items/{item_id}", json_body=current, session=session)
+        return {"id": item_id, "updated": True, "fields": list(fields.keys())}
+
+    async def set_item_image_bytes(
+        self,
+        item_id: str,
+        image_type: str,
+        image_bytes: bytes,
+        mime_type: str = "image/jpeg",
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> Dict[str, Any]:
+        """Set artwork for a Jellyfin item using raw image bytes."""
+        if not validate_item_id(item_id):
+            raise ValueError(f"Invalid item_id format: '{item_id}'")
+
+        clean_type = "Primary" if image_type.lower() in ("poster", "primary") else ("Backdrop" if image_type.lower() in ("backdrop", "background", "thumb") else "Logo")
+        await self._request(
+            "POST",
+            f"/Items/{item_id}/Images/{clean_type}",
+            raw_body=image_bytes,
+            content_type=mime_type,
+            session=session,
+        )
+        return {"id": item_id, "image_type": clean_type, "success": True}
+
+    async def delete_item(
+        self,
+        item_id: str,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> Dict[str, Any]:
+        """Delete an item from Jellyfin."""
+        if not validate_item_id(item_id):
+            raise ValueError(f"Invalid item_id format: '{item_id}'")
+
+        await self._request("DELETE", f"/Items/{item_id}", session=session)
+        return {"id": item_id, "deleted": True}
+
+    async def refresh_item(
+        self,
+        item_id: str,
+        replace_all: bool = True,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> Dict[str, Any]:
+        """Trigger metadata and image refresh for an item."""
+        if not validate_item_id(item_id):
+            raise ValueError(f"Invalid item_id format: '{item_id}'")
+
+        params = {
+            "MetadataRefreshMode": "FullRefresh",
+            "ImageRefreshMode": "FullRefresh",
+            "ReplaceAllMetadata": "true" if replace_all else "false",
+            "ReplaceAllImages": "true" if replace_all else "false",
+        }
+        await self._request("POST", f"/Items/{item_id}/Refresh", params=params, session=session)
+        return {"id": item_id, "refreshed": True}
+
+    async def refresh_library(
+        self,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> Dict[str, Any]:
+        """Trigger full library scan in Jellyfin."""
+        await self._request("POST", "/Library/Refresh", session=session)
+        return {"refreshed": True}

ai_admin/reconciler.py

@@ -0,0 +1,414 @@
+"""Reconciliation engine comparing 100% ground-truth Telegram injected media against Jellyfin library."""
+
+import aiohttp
+import asyncio
+import json
+import logging
+import os
+import re
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from ai_admin.jellyfin_client import JellyfinClient
+from ai_admin.net_guard import validate_outbound_url
+from ai_admin.providers_client import ProvidersClient
+
+logger = logging.getLogger("AIAdmin.Reconciler")
+
+DEFAULT_CACHE_FILE = "/data/jellyfin/file_ids.json"
+
+
+def load_telegram_injected_catalog(cache_path: str = DEFAULT_CACHE_FILE) -> List[Dict[str, Any]]:
+    """Load the ground-truth catalog of media injected from Telegram."""
+    if not os.path.exists(cache_path):
+        return []
+
+    try:
+        with open(cache_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except Exception as e:
+        logger.warning(f"[RECONCILER] Error reading {cache_path}: {e}")
+        return []
+
+    items = []
+    for key, entry in data.items():
+        if not isinstance(entry, dict):
+            continue
+
+        raw_name = entry.get("file_name") or entry.get("raw_name") or entry.get("title") or ""
+        strm_path = entry.get("strm_path") or ""
+
+        items.append({
+            "key": key,
+            "chat_id": entry.get("chat_id"),
+            "message_id": entry.get("message_id") or entry.get("msg_id"),
+            "raw_name": raw_name,
+            "title": entry.get("title") or raw_name,
+            "clean_title": entry.get("clean_title") or entry.get("title") or raw_name,
+            "year": entry.get("year"),
+            "is_tv": bool(entry.get("is_tv")),
+            "show_name": entry.get("show_name"),
+            "season": entry.get("season"),
+            "episode": entry.get("episode"),
+            "strm_path": strm_path,
+            "tmdb_id": entry.get("tmdb_id"),
+            "imdb_id": entry.get("imdb_id"),
+            "file_size": entry.get("file_size"),
+            "poster_url": entry.get("poster_url"),
+            "backdrop_url": entry.get("backdrop_url"),
+        })
+    return items
+
+
+async def audit_and_compare(
+    jf_client: JellyfinClient,
+    cache_path: str = DEFAULT_CACHE_FILE,
+) -> Dict[str, Any]:
+    """Compare 100% ground-truth Telegram injected media with current Jellyfin library.
+    
+    Identifies:
+    1. Rogue / un-injected items in Jellyfin.
+    2. Duplicate series or duplicate movies.
+    3. Metadata mismatches (where Jellyfin title/year diverges from Telegram file).
+    4. Missing artwork (items without posters or backdrops).
+    """
+    injected_files = load_telegram_injected_catalog(cache_path)
+    jellyfin_items = await jf_client.get_all_library_items(include_item_types="Movie,Series,Episode", limit=2000)
+
+    # Normalize strm paths from Telegram catalog
+    injected_by_strm: Dict[str, Dict[str, Any]] = {}
+    injected_by_name: Dict[str, List[Dict[str, Any]]] = {}
+
+    for inj in injected_files:
+        strm = os.path.normpath(str(inj.get("strm_path") or "")).lower()
+        if strm and strm.endswith(".strm"):
+            injected_by_strm[strm] = inj
+            base = os.path.splitext(os.path.basename(strm))[0].lower()
+            injected_by_strm[base] = inj
+
+        clean_name = re.sub(r"[^a-z0-9]+", " ", str(inj.get("clean_title") or inj.get("title") or "")).strip().lower()
+        if clean_name:
+            injected_by_name.setdefault(clean_name, []).append(inj)
+
+    rogue_items = []
+    duplicate_series = []
+    duplicate_movies = []
+    mismatches = []
+    missing_artwork = []
+
+    series_seen: Dict[str, List[Dict[str, Any]]] = {}
+    movie_seen: Dict[str, List[Dict[str, Any]]] = {}
+
+    for it in jellyfin_items:
+        itype = it.get("Type")
+        item_id = it.get("id")
+        name = it.get("name") or "Unknown"
+        path = os.path.normpath(str(it.get("path") or "")).lower()
+        prov_ids = it.get("provider_ids") or {}
+
+        # 1. Check duplicate Series
+        if itype == "Series":
+            norm_series = re.sub(r"[^a-z0-9]+", " ", name).strip().lower()
+            series_seen.setdefault(norm_series, []).append(it)
+            if not it.get("has_poster"):
+                missing_artwork.append({
+                    "id": item_id,
+                    "title": name,
+                    "type": "Series",
+                    "missing": "poster",
+                })
+            continue
+
+        # 2. Check Movies and Episodes
+        if itype == "Movie":
+            norm_movie = re.sub(r"[^a-z0-9]+", " ", name).strip().lower()
+            movie_seen.setdefault(norm_movie, []).append(it)
+
+            if not it.get("has_poster"):
+                missing_artwork.append({
+                    "id": item_id,
+                    "title": name,
+                    "type": "Movie",
+                    "missing": "poster",
+                })
+
+        # Match Jellyfin item to Telegram injection
+        matched_inj = injected_by_strm.get(path)
+        if not matched_inj and path:
+            base_fname = os.path.splitext(os.path.basename(path))[0].lower()
+            matched_inj = injected_by_strm.get(base_fname)
+
+        if not matched_inj:
+            # Check name match
+            norm_name = re.sub(r"[^a-z0-9]+", " ", name).strip().lower()
+            name_hits = injected_by_name.get(norm_name) or []
+            if name_hits:
+                matched_inj = name_hits[0]
+
+        if not matched_inj and path and path.endswith(".strm"):
+            # Rogue item in Jellyfin with no Telegram injection
+            rogue_items.append({
+                "id": item_id,
+                "title": name,
+                "type": itype,
+                "path": it.get("path"),
+                "reason": "No corresponding Telegram injected file found",
+            })
+        elif matched_inj:
+            # Check for title/TMDb mismatch
+            inj_raw = matched_inj.get("raw_name") or ""
+            inj_title = matched_inj.get("title") or ""
+            inj_tmdb = matched_inj.get("tmdb_id")
+            jf_tmdb = prov_ids.get("Tmdb")
+
+            norm_jf = re.sub(r"[^a-z0-9]+", "", name.lower())
+            norm_raw = re.sub(r"[^a-z0-9]+", "", inj_title.lower())
+
+            # Divergence check
+            if norm_raw and norm_jf and norm_raw not in norm_jf and norm_jf not in norm_raw:
+                mismatches.append({
+                    "id": item_id,
+                    "jellyfin_title": name,
+                    "telegram_raw_name": inj_raw,
+                    "expected_title": inj_title,
+                    "expected_year": matched_inj.get("year"),
+                    "jellyfin_tmdb": jf_tmdb,
+                    "expected_tmdb": inj_tmdb,
+                    "expected_imdb": matched_inj.get("imdb_id"),
+                })
+
+    # Collect duplicate Series
+    for s_name, s_list in series_seen.items():
+        if len(s_list) > 1:
+            duplicate_series.append({
+                "series_name": s_list[0].get("name"),
+                "count": len(s_list),
+                "items": [{"id": x.get("id"), "path": x.get("path")} for x in s_list],
+            })
+
+    # Collect duplicate Movies
+    for m_name, m_list in movie_seen.items():
+        if len(m_list) > 1:
+            duplicate_movies.append({
+                "movie_name": m_list[0].get("name"),
+                "count": len(m_list),
+                "items": [{"id": x.get("id"), "path": x.get("path")} for x in m_list],
+            })
+
+    return {
+        "total_telegram_injected": len(injected_files),
+        "total_jellyfin_items": len(jellyfin_items),
+        "rogue_items_count": len(rogue_items),
+        "rogue_items": rogue_items[:20],
+        "duplicate_series_count": len(duplicate_series),
+        "duplicate_series": duplicate_series[:10],
+        "duplicate_movies_count": len(duplicate_movies),
+        "duplicate_movies": duplicate_movies[:10],
+        "mismatches_count": len(mismatches),
+        "mismatches": mismatches[:20],
+        "missing_artwork_count": len(missing_artwork),
+        "missing_artwork": missing_artwork[:20],
+    }
+
+
+async def apply_artwork_from_url(
+    jf_client: JellyfinClient,
+    item_id: str,
+    image_url: str,
+    image_type: str = "Primary",
+) -> Dict[str, Any]:
+    """Download image safely and upload directly to a Jellyfin item."""
+    is_safe, reason = validate_outbound_url(image_url)
+    if not is_safe:
+        raise ValueError(f"Artwork URL rejected by NetGuard: {reason}")
+
+    clean_type = "Primary" if image_type.lower() in ("poster", "primary") else "Backdrop"
+    mime = "image/jpeg"
+
+    async with aiohttp.ClientSession() as session:
+        async with session.get(
+            image_url,
+            timeout=aiohttp.ClientTimeout(total=15.0),
+            headers={"User-Agent": "Apex-ArtworkFetcher/1.0"},
+        ) as resp:
+            if resp.status != 200:
+                raise ValueError(f"Failed to download image (HTTP {resp.status}) from {image_url}")
+            content_type = resp.headers.get("Content-Type", "image/jpeg")
+            if "png" in content_type:
+                mime = "image/png"
+            img_bytes = await resp.read()
+
+    if len(img_bytes) < 100 or len(img_bytes) > 15 * 1024 * 1024:
+        raise ValueError(f"Invalid image payload size: {len(img_bytes)} bytes")
+
+    # Upload to Jellyfin
+    await jf_client.set_item_image_bytes(item_id, clean_type, img_bytes, mime_type=mime)
+    await jf_client.refresh_item(item_id, replace_all=False)
+    return {"id": item_id, "image_type": clean_type, "status": "applied", "url": image_url}
+
+
+async def reconcile_item(
+    jf_client: JellyfinClient,
+    item_id: str,
+    title: Optional[str] = None,
+    year: Optional[int] = None,
+    tmdb_id: Optional[int] = None,
+    imdb_id: Optional[str] = None,
+    overview: Optional[str] = None,
+    poster_url: Optional[str] = None,
+    backdrop_url: Optional[str] = None,
+    cache_path: str = DEFAULT_CACHE_FILE,
+    raw_name: Optional[str] = None,
+    cache_key: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Correct an item's metadata and artwork in Jellyfin and synchronize with FILE_ID_CACHE."""
+    current_name = None
+    current_path = None
+    try:
+        cur_item = await jf_client.get_item(item_id)
+        if cur_item:
+            current_name = cur_item.get("name")
+            current_path = os.path.normpath(str(cur_item.get("path") or "")).lower()
+    except Exception:
+        pass
+
+    fields: Dict[str, Any] = {}
+    if title:
+        fields["Name"] = title
+    if year:
+        fields["ProductionYear"] = int(year)
+    if overview:
+        fields["Overview"] = overview
+
+    prov_ids: Dict[str, str] = {}
+    if tmdb_id:
+        prov_ids["Tmdb"] = str(tmdb_id)
+    if imdb_id:
+        prov_ids["Imdb"] = str(imdb_id)
+    if prov_ids:
+        fields["ProviderIds"] = prov_ids
+
+    # 1. Update metadata in Jellyfin
+    if fields:
+        await jf_client.update_item_metadata(item_id, fields)
+
+    # 2. Apply artwork if provided
+    applied_art = []
+    if poster_url:
+        try:
+            res = await apply_artwork_from_url(jf_client, item_id, poster_url, image_type="Primary")
+            applied_art.append(res)
+        except Exception as e:
+            logger.warning(f"[RECONCILE] Failed to apply poster: {e}")
+
+    if backdrop_url:
+        try:
+            res = await apply_artwork_from_url(jf_client, item_id, backdrop_url, image_type="Backdrop")
+            applied_art.append(res)
+        except Exception as e:
+            logger.warning(f"[RECONCILE] Failed to apply backdrop: {e}")
+
+    # 3. Synchronize FILE_ID_CACHE on disk
+    if os.path.exists(cache_path):
+        try:
+            with open(cache_path, "r", encoding="utf-8") as f:
+                cache_data = json.load(f)
+
+            updated = False
+            for key, entry in cache_data.items():
+                if not isinstance(entry, dict):
+                    continue
+                match = False
+                if cache_key and key == cache_key:
+                    match = True
+                elif raw_name and raw_name.lower() in str(entry.get("raw_name") or entry.get("file_name") or "").lower():
+                    match = True
+                elif current_path:
+                    strm = os.path.normpath(str(entry.get("strm_path") or "")).lower()
+                    if strm and (strm == current_path or os.path.basename(strm) == os.path.basename(current_path)):
+                        match = True
+                if not match and current_name and (current_name.lower() in (entry.get("title") or "").lower() or (entry.get("title") or "").lower() in current_name.lower()):
+                    match = True
+                if not match and title and title.lower() in (entry.get("title") or "").lower():
+                    match = True
+                if not match and tmdb_id and entry.get("tmdb_id") == tmdb_id:
+                    match = True
+
+                if match:
+                    if title:
+                        entry["title"] = title
+                        entry["clean_title"] = title
+                    if year:
+                        entry["year"] = int(year)
+                    if tmdb_id:
+                        entry["tmdb_id"] = int(tmdb_id)
+                    if imdb_id:
+                        entry["imdb_id"] = str(imdb_id)
+                    if poster_url:
+                        entry["poster_url"] = poster_url
+                    if backdrop_url:
+                        entry["backdrop_url"] = backdrop_url
+                    updated = True
+
+            if updated:
+                with open(cache_path, "w", encoding="utf-8") as f:
+                    json.dump(cache_data, f, indent=2)
+        except Exception as e:
+            logger.warning(f"[RECONCILE] Error updating {cache_path}: {e}")
+
+    await jf_client.refresh_item(item_id, replace_all=True)
+    return {
+        "id": item_id,
+        "title": title,
+        "year": year,
+        "tmdb_id": tmdb_id,
+        "imdb_id": imdb_id,
+        "artwork": applied_art,
+        "status": "reconciled",
+    }
+
+
+async def cleanup_rogue_and_duplicates(
+    jf_client: JellyfinClient,
+    remove_rogue: bool = True,
+    deduplicate_series: bool = True,
+    cache_path: str = DEFAULT_CACHE_FILE,
+) -> Dict[str, Any]:
+    """Clean up rogue un-injected items and merge duplicate series in Jellyfin."""
+    audit = await audit_and_compare(jf_client, cache_path=cache_path)
+
+    deleted_rogue = []
+    if remove_rogue:
+        for r in audit.get("rogue_items", []):
+            rid = r.get("id")
+            if rid:
+                try:
+                    await jf_client.delete_item(rid)
+                    deleted_rogue.append(r)
+                except Exception as e:
+                    logger.warning(f"[CLEANUP] Failed to delete rogue item {rid}: {e}")
+
+    deleted_duplicate_series = []
+    if deduplicate_series:
+        for s in audit.get("duplicate_series", []):
+            items = s.get("items") or []
+            if len(items) > 1:
+                # Keep the first, delete the rest
+                for dup in items[1:]:
+                    dup_id = dup.get("id")
+                    if dup_id:
+                        try:
+                            await jf_client.delete_item(dup_id)
+                            deleted_duplicate_series.append(dup)
+                        except Exception as e:
+                            logger.warning(f"[CLEANUP] Failed to delete duplicate series {dup_id}: {e}")
+
+    # Trigger library refresh
+    await jf_client.refresh_library()
+
+    return {
+        "deleted_rogue_count": len(deleted_rogue),
+        "deleted_rogue_items": deleted_rogue,
+        "deleted_duplicate_series_count": len(deleted_duplicate_series),
+        "deleted_duplicate_series": deleted_duplicate_series,
+        "status": "cleanup_complete",
+    }

ai_admin/tools_jellyfin.py

@@ -5,6 +5,13 @@ from typing import Any, Dict, List, Optional
 
 from ai_admin.jellyfin_client import JellyfinClient
 from ai_admin.mutation_contracts import MUTATION_CONTRACTS
+from ai_admin.reconciler import (
+    apply_artwork_from_url,
+    audit_and_compare,
+    cleanup_rogue_and_duplicates,
+    load_telegram_injected_catalog,
+    reconcile_item,
+)
 from ai_admin.tool_registry import ToolDefinition, ToolRegistry
 from ai_admin.validators import validate_item_id
 
@@ -57,6 +64,105 @@ def make_jellyfin_get_media_info_handler(client: JellyfinClient):
     return handler
 
 
+def make_telegram_list_injected_handler():
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        query = (params.get("query") or "").strip().lower()
+        filter_type = params.get("filter_type")
+        items = load_telegram_injected_catalog()
+
+        if query:
+            items = [
+                it for it in items
+                if query in (it.get("raw_name") or "").lower()
+                or query in (it.get("title") or "").lower()
+                or query in (it.get("show_name") or "").lower()
+            ]
+
+        if filter_type == "movie":
+            items = [it for it in items if not it.get("is_tv")]
+        elif filter_type == "tv":
+            items = [it for it in items if it.get("is_tv")]
+
+        return {
+            "count": len(items),
+            "items": items[:params.get("limit", 50)],
+        }
+    return handler
+
+
+def make_jellyfin_list_library_handler(client: JellyfinClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        item_types = params.get("item_types", "Movie,Series")
+        limit = params.get("limit", 100)
+        items = await client.get_all_library_items(include_item_types=item_types, limit=limit)
+        return {
+            "count": len(items),
+            "items": items,
+        }
+    return handler
+
+
+def make_library_audit_and_compare_handler(client: JellyfinClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        audit = await audit_and_compare(jf_client=client)
+        return audit
+    return handler
+
+
+def make_library_fix_item_handler(client: JellyfinClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        item_id = params.get("item_id", "")
+        title = params.get("title")
+        year = params.get("year")
+        tmdb_id = params.get("tmdb_id")
+        imdb_id = params.get("imdb_id")
+        overview = params.get("overview")
+        poster_url = params.get("poster_url")
+        backdrop_url = params.get("backdrop_url")
+
+        res = await reconcile_item(
+            jf_client=client,
+            item_id=item_id,
+            title=title,
+            year=year,
+            tmdb_id=tmdb_id,
+            imdb_id=imdb_id,
+            overview=overview,
+            poster_url=poster_url,
+            backdrop_url=backdrop_url,
+        )
+        return res
+    return handler
+
+
+def make_library_cleanup_rogue_and_duplicates_handler(client: JellyfinClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        remove_rogue = params.get("remove_rogue", True)
+        deduplicate_series = params.get("deduplicate_series", True)
+        res = await cleanup_rogue_and_duplicates(
+            jf_client=client,
+            remove_rogue=remove_rogue,
+            deduplicate_series=deduplicate_series,
+        )
+        return res
+    return handler
+
+
+def make_jellyfin_apply_artwork_handler(client: JellyfinClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        item_id = params.get("item_id", "")
+        image_url = params.get("image_url", "")
+        image_type = params.get("image_type", "Primary")
+        res = await apply_artwork_from_url(
+            jf_client=client,
+            item_id=item_id,
+            image_url=image_url,
+            image_type=image_type,
+        )
+        return res
+    return handler
+
+
 # ==============================================================================
 # 2. Disabled Mutation Placeholders (Fail-closed)
 # ==============================================================================
@@ -157,6 +263,141 @@ def get_jellyfin_read_tool_definitions(client: JellyfinClient) -> List[ToolDefin
             handler=make_jellyfin_get_media_info_handler(client),
             validators=[lambda p: validate_item_id(p.get("item_id", ""))],
         ),
+        ToolDefinition(
+            name="telegram_list_injected",
+            purpose="List raw media files injected from Telegram, with original file names, message IDs, and parsed details.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "maxLength": 100},
+                    "filter_type": {"type": "string", "maxLength": 10},
+                    "limit": {"type": "integer"},
+                },
+                "additionalProperties": False,
+            },
+            read_only=True,
+            mutates=False,
+            risk="low",
+            requires_confirmation="never",
+            permission="read",
+            timeout_seconds=10,
+            max_output_chars=4000,
+            handler=make_telegram_list_injected_handler(),
+        ),
+        ToolDefinition(
+            name="jellyfin_list_library",
+            purpose="List all media items currently in Jellyfin library, with item IDs, titles, and paths.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "item_types": {"type": "string", "maxLength": 50},
+                    "limit": {"type": "integer"},
+                },
+                "additionalProperties": False,
+            },
+            read_only=True,
+            mutates=False,
+            risk="low",
+            requires_confirmation="never",
+            permission="read",
+            timeout_seconds=20,
+            max_output_chars=4000,
+            handler=make_jellyfin_list_library_handler(client),
+        ),
+        ToolDefinition(
+            name="library_audit_and_compare",
+            purpose="Compare Telegram injected files (the 100% ground truth) with Jellyfin items to detect rogue movies, duplicate series, and mismatches.",
+            json_schema={
+                "type": "object",
+                "properties": {},
+                "additionalProperties": False,
+            },
+            read_only=True,
+            mutates=False,
+            risk="low",
+            requires_confirmation="never",
+            permission="read",
+            timeout_seconds=30,
+            max_output_chars=4000,
+            handler=make_library_audit_and_compare_handler(client),
+        ),
+    ]
+
+
+def get_jellyfin_active_mutation_definitions(client: JellyfinClient) -> List[ToolDefinition]:
+    """Tool definitions for active mutating operations when AI_MUTATIONS_ENABLED=true."""
+    return [
+        ToolDefinition(
+            name="library_fix_item",
+            purpose="Correct title, year, TMDb ID, IMDb ID, or authentic artwork for a Jellyfin item and update cache.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "item_id": {"type": "string", "maxLength": 64},
+                    "title": {"type": "string", "maxLength": 100},
+                    "year": {"type": "integer"},
+                    "tmdb_id": {"type": "integer"},
+                    "imdb_id": {"type": "string", "maxLength": 20},
+                    "overview": {"type": "string", "maxLength": 1000},
+                    "poster_url": {"type": "string", "maxLength": 300},
+                    "backdrop_url": {"type": "string", "maxLength": 300},
+                },
+                "required": ["item_id"],
+                "additionalProperties": False,
+            },
+            read_only=False,
+            mutates=True,
+            risk="medium",
+            requires_confirmation="never",
+            permission="write",
+            timeout_seconds=30,
+            max_output_chars=4000,
+            handler=make_library_fix_item_handler(client),
+            validators=[lambda p: validate_item_id(p.get("item_id", ""))],
+        ),
+        ToolDefinition(
+            name="library_cleanup_rogue_and_duplicates",
+            purpose="Delete rogue un-injected items and merge/clean duplicate series in Jellyfin.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "remove_rogue": {"type": "boolean"},
+                    "deduplicate_series": {"type": "boolean"},
+                },
+                "additionalProperties": False,
+            },
+            read_only=False,
+            mutates=True,
+            risk="medium",
+            requires_confirmation="never",
+            permission="write",
+            timeout_seconds=30,
+            max_output_chars=4000,
+            handler=make_library_cleanup_rogue_and_duplicates_handler(client),
+        ),
+        ToolDefinition(
+            name="jellyfin_apply_artwork",
+            purpose="Download and apply authentic poster or backdrop image from URL to a Jellyfin item.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "item_id": {"type": "string", "maxLength": 64},
+                    "image_url": {"type": "string", "maxLength": 300},
+                    "image_type": {"type": "string", "maxLength": 20},
+                },
+                "required": ["item_id", "image_url"],
+                "additionalProperties": False,
+            },
+            read_only=False,
+            mutates=True,
+            risk="medium",
+            requires_confirmation="never",
+            permission="write",
+            timeout_seconds=25,
+            max_output_chars=4000,
+            handler=make_jellyfin_apply_artwork_handler(client),
+            validators=[lambda p: validate_item_id(p.get("item_id", ""))],
+        ),
     ]
 
 

apex/tg_streamer.py

@@ -230,7 +230,33 @@ def load_cache():
             cache_updated = True
             logger.info(f"[CACHE-HEAL] Corrected Generation Iron to real Iron Man 3 for '{raw_name}'")
 
-        # 2. Clean release-size noise from title, clean_title, strm_base
+        # 2. Heal Khalifa misidentification and assign authentic metadata & artwork
+        is_khalifa = (
+            "khalifa" in raw_lower
+            or "khalifa" in (data.get("tmdb_title") or "").lower()
+            or "khalifa" in (data.get("title") or "").lower()
+            or "khalifa" in (data.get("strm_base") or "").lower()
+        )
+        if is_khalifa:
+            data["title"] = "Khalifa"
+            data["clean_title"] = "Khalifa"
+            data["search_title"] = "khalifa"
+            data["tmdb_title"] = "Khalifa"
+            data["tmdb_id"] = 1036081
+            data["imdb_id"] = "tt22797990"
+            data["year"] = 2026
+            data["tmdb_year"] = 2026
+            data["strm_base"] = "Khalifa (2026)"
+            lang = data.get("language") or "Malayalam"
+            data["target_dir"] = os.path.join(MOVIES_DIR, lang, "Khalifa (2026)")
+            data["strm_path"] = os.path.join(data["target_dir"], "Khalifa (2026).strm")
+            data["poster_url"] = "https://images.metahub.space/poster/medium/tt22797990/img"
+            data["backdrop_url"] = "https://images.metahub.space/background/medium/tt22797990/img"
+            data["_force_art_refresh"] = True
+            cache_updated = True
+            logger.info(f"[CACHE-HEAL] Corrected Khalifa metadata and artwork for '{raw_name}'")
+
+        # 3. Clean release-size noise from title, clean_title, strm_base
         cur_title = data.get("title") or ""
         cur_clean = data.get("clean_title") or ""
         cur_base = data.get("strm_base") or ""
@@ -2938,19 +2964,46 @@ async def deduplicate_jellyfin_items():
                 payload = await response.json()
             items = payload.get("Items") or []
             groups = {}
+            series_groups = {}
+            orphan_items = []
+
+            # Valid cached strm paths
+            valid_cached_paths = {
+                os.path.normpath(str(d.get("strm_path") or "")).lower()
+                for d in FILE_ID_CACHE.values()
+                if isinstance(d, dict) and d.get("strm_path")
+            }
+
             for item in items:
+                itype = item.get("Type")
                 path = os.path.normpath(str(item.get("Path") or ""))
+                provider_ids = item.get("ProviderIds") or {}
+
+                # 1. Series deduplication
+                if itype == "Series":
+                    s_name = str(item.get("Name") or "").strip().lower()
+                    tmdb_s = provider_ids.get("Tmdb")
+                    s_ident = f"series:tmdb:{tmdb_s}" if tmdb_s else f"series:name:{s_name}"
+                    series_groups.setdefault(s_ident, []).append((item, path))
+                    continue
+
                 if not path.lower().endswith(".strm"):
                     continue
                 if not (path.startswith(os.path.normpath(MOVIES_DIR)) or
                         path.startswith(os.path.normpath(SHOWS_DIR))):
                     continue
+
+                # If .strm does not exist on disk, mark immediately as orphan for cleanup
+                if not os.path.exists(path):
+                    orphan_items.append((item, path))
+                    continue
+
                 item_name = str(item.get("Name") or "").strip().lower().replace(" ", "_")
                 path_name = os.path.basename(path).lower().replace(" ", "_")
                 if item_name in {"unknown_media", "unknown"} or "unknown_media" in path_name:
                     groups.setdefault("unknown-media", []).append((item, path))
                     continue
-                provider_ids = item.get("ProviderIds") or {}
+
                 year_match = re.search(r"\((\d{4})\)", path)
                 year_suffix = year_match.group(1) if year_match else ""
                 if provider_ids.get("Tmdb"):
@@ -2979,7 +3032,17 @@ async def deduplicate_jellyfin_items():
                             + f":{year_suffix}"
                         )
                 groups.setdefault(identity, []).append((item, path))
-            duplicates = []
+
+            duplicates = list(orphan_items)
+
+            # Process Series duplicates
+            for s_ident, s_entries in series_groups.items():
+                if len(s_entries) > 1:
+                    existing_s = [pair for pair in s_entries if os.path.exists(pair[1])]
+                    # Keep series with the deepest or existing folder path
+                    keep_s = sorted(existing_s or s_entries, key=lambda pair: len(pair[1]), reverse=True)[0]
+                    duplicates.extend(pair for pair in s_entries if pair is not keep_s)
+
             for identity, entries in groups.items():
                 if identity == "unknown-media":
                     duplicates.extend(entries)
@@ -2987,6 +3050,7 @@ async def deduplicate_jellyfin_items():
                 existing = [pair for pair in entries if os.path.exists(pair[1])]
                 keep = sorted(existing or entries, key=lambda pair: len(pair[1]))[0]
                 duplicates.extend(pair for pair in entries if pair is not keep)
+
             for item, path in duplicates:
                 item_id = item.get("Id")
                 if not item_id:

tests/ai_admin/test_reconciler.py

@@ -0,0 +1,222 @@
+import json
+import os
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from ai_admin.jellyfin_client import JellyfinClient
+from ai_admin.reconciler import (
+    load_telegram_injected_catalog,
+    audit_and_compare,
+    reconcile_item,
+    cleanup_rogue_and_duplicates,
+    apply_artwork_from_url,
+)
+
+
+@pytest.fixture
+def mock_jf_client():
+    client = MagicMock(spec=JellyfinClient)
+    client.get_all_library_items = AsyncMock()
+    client.get_item = AsyncMock(return_value={"id": "item-123", "name": "Old Title", "path": "/data/jellyfin/media/Movies/Old.strm"})
+    client.update_item_metadata = AsyncMock(return_value={"status": "ok"})
+    client.set_item_image_bytes = AsyncMock(return_value=True)
+    client.refresh_item = AsyncMock(return_value=True)
+    client.refresh_library = AsyncMock(return_value=True)
+    client.delete_item = AsyncMock(return_value=True)
+    return client
+
+
+def test_load_telegram_injected_catalog_nonexistent(tmp_path):
+    res = load_telegram_injected_catalog(str(tmp_path / "nonexistent.json"))
+    assert res == []
+
+
+def test_load_telegram_injected_catalog_valid(tmp_path):
+    cache_file = tmp_path / "file_ids.json"
+    cache_data = {
+        "-100123:456": {
+            "chat_id": -100123,
+            "message_id": 456,
+            "file_name": "Khalifa.2026.1080p.mkv",
+            "title": "Khalifa",
+            "clean_title": "Khalifa",
+            "year": 2026,
+            "is_tv": False,
+            "strm_path": "/data/jellyfin/media/Movies/Khalifa (2026)/Khalifa.strm",
+            "tmdb_id": 1036081,
+            "imdb_id": "tt22797990",
+            "file_size": 1500000000,
+            "poster_url": "https://images.metahub.space/poster/medium/tt22797990/img",
+        }
+    }
+    cache_file.write_text(json.dumps(cache_data))
+
+    catalog = load_telegram_injected_catalog(str(cache_file))
+    assert len(catalog) == 1
+    assert catalog[0]["title"] == "Khalifa"
+    assert catalog[0]["tmdb_id"] == 1036081
+    assert catalog[0]["strm_path"] == "/data/jellyfin/media/Movies/Khalifa (2026)/Khalifa.strm"
+
+
+@pytest.mark.asyncio
+async def test_audit_and_compare(mock_jf_client, tmp_path):
+    cache_file = tmp_path / "file_ids.json"
+    cache_data = {
+        "-1001:1": {
+            "chat_id": -1001,
+            "message_id": 1,
+            "file_name": "Inception.2010.mkv",
+            "title": "Inception",
+            "year": 2010,
+            "is_tv": False,
+            "strm_path": "/data/jellyfin/media/Movies/Inception (2010)/Inception.strm",
+            "tmdb_id": 27205,
+        }
+    }
+    cache_file.write_text(json.dumps(cache_data))
+
+    # Mock Jellyfin returning:
+    # 1. Matching movie (Inception) without poster
+    # 2. Rogue movie (Random.strm)
+    # 3. Duplicate series (Show A x2)
+    mock_jf_client.get_all_library_items.return_value = [
+        {
+            "id": "item-1",
+            "name": "Inception",
+            "Type": "Movie",
+            "path": "/data/jellyfin/media/Movies/Inception (2010)/Inception.strm",
+            "has_poster": False,
+            "provider_ids": {"Tmdb": "27205"},
+        },
+        {
+            "id": "item-2",
+            "name": "Rogue Movie",
+            "Type": "Movie",
+            "path": "/data/jellyfin/media/Movies/Rogue (2020)/Rogue.strm",
+            "has_poster": True,
+            "provider_ids": {},
+        },
+        {
+            "id": "series-1",
+            "name": "Dark",
+            "Type": "Series",
+            "path": "/data/jellyfin/media/TV Shows/Dark",
+            "has_poster": True,
+        },
+        {
+            "id": "series-2",
+            "name": "Dark",
+            "Type": "Series",
+            "path": "/data/jellyfin/media/TV Shows/Dark Duplicate",
+            "has_poster": True,
+        },
+    ]
+
+    audit = await audit_and_compare(mock_jf_client, cache_path=str(cache_file))
+
+    assert audit["total_telegram_injected"] == 1
+    assert audit["total_jellyfin_items"] == 4
+    assert audit["rogue_items_count"] == 1
+    assert audit["rogue_items"][0]["id"] == "item-2"
+
+    assert audit["duplicate_series_count"] == 1
+    assert audit["duplicate_series"][0]["series_name"] == "Dark"
+    assert audit["duplicate_series"][0]["count"] == 2
+
+    assert audit["missing_artwork_count"] == 1
+    assert audit["missing_artwork"][0]["id"] == "item-1"
+
+
+@pytest.mark.asyncio
+async def test_reconcile_item(mock_jf_client, tmp_path):
+    cache_file = tmp_path / "file_ids.json"
+    cache_data = {
+        "-1001:1": {
+            "title": "Old Title",
+            "year": 2020,
+            "tmdb_id": 100,
+        }
+    }
+    cache_file.write_text(json.dumps(cache_data))
+
+    res = await reconcile_item(
+        mock_jf_client,
+        item_id="item-123",
+        title="Khalifa",
+        year=2026,
+        tmdb_id=1036081,
+        imdb_id="tt22797990",
+        cache_path=str(cache_file),
+    )
+
+    assert res["status"] == "reconciled"
+    assert res["id"] == "item-123"
+    assert res["title"] == "Khalifa"
+    mock_jf_client.update_item_metadata.assert_called_once()
+    mock_jf_client.refresh_item.assert_called_once_with("item-123", replace_all=True)
+
+    # Check cache update
+    updated_cache = json.loads(cache_file.read_text())
+    entry = updated_cache["-1001:1"]
+    assert entry["title"] == "Khalifa"
+    assert entry["year"] == 2026
+    assert entry["tmdb_id"] == 1036081
+    assert entry["imdb_id"] == "tt22797990"
+
+
+@pytest.mark.asyncio
+async def test_cleanup_rogue_and_duplicates(mock_jf_client, tmp_path):
+    cache_file = tmp_path / "file_ids.json"
+    cache_file.write_text(json.dumps({}))
+
+    mock_jf_client.get_all_library_items.return_value = [
+        {
+            "id": "rogue-1",
+            "name": "Rogue",
+            "Type": "Movie",
+            "path": "/data/jellyfin/media/Movies/Rogue.strm",
+            "has_poster": True,
+        },
+        {
+            "id": "series-1",
+            "name": "Breaking Bad",
+            "Type": "Series",
+            "path": "/data/jellyfin/media/TV Shows/Breaking Bad",
+            "has_poster": True,
+        },
+        {
+            "id": "series-2",
+            "name": "Breaking Bad",
+            "Type": "Series",
+            "path": "/data/jellyfin/media/TV Shows/Breaking Bad (2)",
+            "has_poster": True,
+        },
+    ]
+
+    res = await cleanup_rogue_and_duplicates(
+        mock_jf_client,
+        remove_rogue=True,
+        deduplicate_series=True,
+        cache_path=str(cache_file),
+    )
+
+    assert res["status"] == "cleanup_complete"
+    assert res["deleted_rogue_count"] == 1
+    assert res["deleted_duplicate_series_count"] == 1
+
+    # Verified delete calls
+    deleted_ids = [call.args[0] for call in mock_jf_client.delete_item.call_args_list]
+    assert "rogue-1" in deleted_ids
+    assert "series-2" in deleted_ids
+    assert "series-1" not in deleted_ids
+    mock_jf_client.refresh_library.assert_called_once()
+
+
+@pytest.mark.asyncio
+async def test_apply_artwork_from_url_blocked_by_netguard(mock_jf_client):
+    with pytest.raises(ValueError, match="Artwork URL rejected by NetGuard"):
+        await apply_artwork_from_url(
+            mock_jf_client,
+            item_id="item-1",
+            image_url="http://192.168.1.1/exploit.jpg",
+        )

tests/ai_admin/test_stage6_e2e_integration.py

@@ -120,14 +120,17 @@ def test_stage6_exact_tool_count_and_absence_of_mutations(monkeypatch, tmp_path)
     registry = router.handler.registry
     registered_tools = registry.list_tools()
 
-    # Must contain exactly 13 read-only tools
-    assert len(registered_tools) == 13, f"Expected 13 tools, got {len(registered_tools)}: {[t.name for t in registered_tools]}"
+    # Must contain exactly 16 read-only tools
+    assert len(registered_tools) == 16, f"Expected 16 tools, got {len(registered_tools)}: {[t.name for t in registered_tools]}"
 
     expected_tool_names = {
         "jellyfin_search",
         "jellyfin_get_item",
         "jellyfin_list_missing_metadata",
         "jellyfin_get_media_info",
+        "telegram_list_injected",
+        "jellyfin_list_library",
+        "library_audit_and_compare",
         "tmdb_search",
         "tmdb_get_details",
         "tmdb_get_images",