ha-mcp-dev 8.7.0.dev3060__tar.gz → 8.7.0.dev3061__tar.gz

{ha_mcp_dev-8.7.0.dev3060 → ha_mcp_dev-8.7.0.dev3061}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.7.0.dev3060
+Version: 8.7.0.dev3061
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.7.0.dev3060 → ha_mcp_dev-8.7.0.dev3061}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.7.0.dev3060"
+version = "8.7.0.dev3061"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.7.0.dev3060 → ha_mcp_dev-8.7.0.dev3061}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.7.0.dev3060"
+version = "8.7.0.dev3061"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.7.0.dev3060 → ha_mcp_dev-8.7.0.dev3061}/src/ha_mcp/backup_entity_ids.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 from contextlib import AsyncExitStack
 from typing import Any
 
+from ._vendor.websockets.exceptions import WebSocketException
+
 
 def _manager() -> Any:
     from . import backup_manager
@@ -16,6 +18,81 @@ def _manager() -> Any:
     return backup_manager
 
 
+async def registry_row(
+    client: Any, platform: str, unique_id: str
+) -> dict[str, Any] | None:
+    """The entity-registry row of ``platform``'s entity with ``unique_id``."""
+    rows = await _manager()._entity_registry_rows(client)
+    return next(
+        (
+            row
+            for row in rows
+            if row.get("platform") == platform and row.get("unique_id") == unique_id
+        ),
+        None,
+    )
+
+
+async def with_registry_icon(
+    client: Any, platform: str, item: dict[str, Any]
+) -> dict[str, Any]:
+    """The stored item plus the icon its entity's registry entry sets, if any.
+
+    The registry icon is the one the entity shows, and the helper tools write
+    it there (an update always; a create for a zone, or when Core's schema
+    has no icon field or cannot be read), so the stored item alone can miss
+    it. A failed registry read
+    propagates, so the capture reports it instead of saving a snapshot
+    without the icon.
+    """
+    entity = await registry_row(client, platform, str(item.get("id")))
+    return {**item, "registry_icon": entity.get("icon") if entity else None}
+
+
+async def restore_registry_icon(
+    client: Any, platform: str, item_id: str, registry_icon: str | None
+) -> list[str]:
+    """Write the recorded registry icon back; problems come back as warnings,
+    because the stored item was already restored."""
+    bm = _manager()
+    try:
+        entity = await registry_row(client, platform, item_id)
+        if entity is None:
+            if registry_icon is None:
+                return []
+            return [
+                f"The registry icon {registry_icon} was not restored: "
+                f"{platform} {item_id} has no entity."
+            ]
+        async with bm.registry_update_lock("entity", entity["entity_id"]):
+            await bm._ws_send(
+                client,
+                {
+                    "type": "config/entity_registry/update",
+                    "entity_id": entity["entity_id"],
+                    "icon": registry_icon,
+                },
+            )
+    except (*bm._CAPTURE_TRANSIENT_ERRORS, WebSocketException) as err:
+        return [f"The {platform} was restored, but its registry icon was not: {err}"]
+    return []
+
+
+async def update_with_registry_icon(
+    client: Any, platform: str, item_id: str, payload: dict[str, Any]
+) -> Any:
+    """``<platform>/update`` without the snapshot's registry icon, then the icon."""
+    recorded = "registry_icon" in payload
+    registry_icon = payload.pop("registry_icon", None)
+    result = await _manager()._ws_send(client, payload)
+    warnings = (
+        await restore_registry_icon(client, platform, item_id, registry_icon)
+        if recorded
+        else []
+    )
+    return {**result, "warnings": warnings} if warnings else result
+
+
 def _recreated_unique_id(saved: dict[str, Any], old_entry: str, new_entry: str) -> str:
     """Core derives a helper entity's unique_id from its config-entry ID."""
     return str(saved["unique_id"]).replace(old_entry, new_entry)

ha_mcp_dev-8.7.0.dev3061/src/ha_mcp/backup_helper_target.py

@@ -0,0 +1,183 @@
+"""The storage helper a helper tool writes, for its pre-write snapshot (#2632).
+
+``ha_config_set_helper``, ``ha_remove_helpers_integrations`` and the zone tools
+resolve their target as ``stored_target`` does: a bare id is a storage id,
+and ``<type>.<name>`` is the entity_id of the helper's registry entry, whose
+``unique_id`` is the storage id. A renamed entity can carry another helper's
+id as its name, so a bare id never names an entity. The snapshot resolves
+the same way, so it holds the item the write changes. A restore whose write
+fails raises through ``raise_with_restore_outcome``, so its caller still learns
+the safety backup to revert with.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, NoReturn
+
+from ._vendor.fastmcp.exceptions import ToolError
+from .backup_entity_ids import _manager
+
+
+async def _stored_items(client: Any, helper_type: str) -> list[Any]:
+    bm = _manager()
+    listed = await bm._ws_send(client, {"type": f"{helper_type}/list"})
+    if helper_type == "person" and isinstance(listed, dict):
+        listed = listed.get("storage")  # YAML-defined persons are not editable
+    items: list[Any] = bm._require_list(listed, f"{helper_type}/list")
+    return items
+
+
+def stored_target(
+    helper_type: str, target: str, stored_ids: Any, rows: list[Any]
+) -> tuple[str | None, str | None]:
+    """The storage id and entity_id of the stored helper ``target`` names.
+
+    A bare ``target`` is a storage id; ``<type>.<name>`` is the entity_id of
+    a registry entry on the type's platform, whose unique_id is the storage id.
+    Its entity_id is None when the item has no registry entry, and both are
+    None when nothing matches. A storage id from the registry need not be
+    stored: a YAML helper has an entry but no stored item.
+    """
+    ids = {str(i) for i in stored_ids}
+    own = [r for r in rows if r.get("platform") == helper_type]
+    if target in ids:
+        entity = next(
+            (r.get("entity_id") for r in own if r.get("unique_id") == target), None
+        )
+        return target, entity
+    row = next((r for r in own if r.get("entity_id") == target), None)
+    if row is None or not row.get("unique_id"):
+        return None, None
+    return str(row["unique_id"]), target
+
+
+async def fetch_helper(client: Any, entity_id: str, helper_type: str) -> Any:
+    """Fetch a storage helper's full config from its ``<helper_type>/list``.
+
+    Registered for the storage helper types only; flow helpers (config
+    entries) have their own handler family (``_make_flow_helper_handler``).
+    A failed list or registry read propagates: maybe_snapshot logs a WARNING,
+    or for a mandatory snapshot (a restore's safety backup) blocks the write,
+    rather than silently skipping.
+    """
+    bm = _manager()
+    items = await _stored_items(client, helper_type)
+    by_id = {str(item.get("id")): item for item in items}
+    storage_id, _ = stored_target(
+        helper_type, entity_id, by_id, await bm._entity_registry_rows(client)
+    )
+    item = by_id.get(storage_id) if storage_id else None
+    return await bm._registry_snapshot(client, helper_type, item) if item else None
+
+
+async def safety_target(
+    client: Any, domain: str, entity_id: str, config: Any
+) -> str | None:
+    """The entity a restore's safety backup is taken under, None when the item
+    the restore writes no longer exists.
+
+    The restore writes a stored item by its id; the backup is keyed by the
+    entity_id the item had, which a rename since can leave naming nothing, or
+    another item. For a storage item the registry entry whose unique_id is the
+    stored id follows it. An item can outlive its registry entry, so only its
+    absence from the stored items means it is gone: the restore recreates it or
+    fails, and overwrites nothing that needs a backup.
+    """
+    bm = _manager()
+    platform = domain.removeprefix("helper_")
+    stored = config.get("id") if isinstance(config, dict) else None
+    if not stored or platform not in bm._HELPER_LIST_TYPES:
+        return entity_id
+    try:
+        rows = await bm._entity_registry_rows(client)
+    except bm._CAPTURE_TRANSIENT_ERRORS as err:
+        raise bm.MandatoryBackupError(
+            f"the entity registry could not be read: {type(err).__name__}",
+            safe_detail="the entity registry could not be read",
+        ) from err
+    target: str | None = next(
+        (
+            row["entity_id"]
+            for row in rows
+            if row.get("platform") == platform and row.get("unique_id") == str(stored)
+        ),
+        None,
+    )
+    if target is not None:
+        return target
+    try:
+        items = await _stored_items(client, platform)
+    except bm._CAPTURE_TRANSIENT_ERRORS as err:
+        raise bm.MandatoryBackupError(
+            f"the stored {platform} items could not be read: {type(err).__name__}",
+            safe_detail=f"the stored {platform} items could not be read",
+        ) from err
+    if not any(str(item.get("id")) == str(stored) for item in items):
+        return None
+    # Without a registry entry the item is found by its storage id.
+    return str(stored)
+
+
+def require_holds(config: Any, stored: Any, entity_id: str) -> None:
+    """Block a restore whose safety backup would hold another item than the
+    one it overwrites: an entity_id the registry cannot follow, renamed since
+    the backup, can name another item."""
+    held = config.get("id") if isinstance(config, dict) else None
+    if held != stored:
+        raise _manager().BackupRestoreError(
+            f"Restore blocked: the safety backup would hold {held}, not {stored}, "
+            f"which this restore overwrites: {entity_id} names another item since "
+            "this backup. Nothing was changed.",
+            reason="backup_capture_failed",
+            suggestions=[
+                f"Find the current entity_id of {stored} with ha_search",
+                f"If {stored} has no entity, rename the entity that holds {entity_id}",
+            ],
+        )
+
+
+def raise_with_restore_outcome(err: BaseException, outcome: dict[str, Any]) -> NoReturn:
+    """Raise a failed restore write's error with the restore's outcome.
+
+    Every error keeps the outcome as ``restore_outcome`` for the Settings
+    handler and is raised again as it is. A tool error reaches the MCP client
+    as its JSON text alone, so it is raised as a copy with the outcome in that
+    text as ``data``, chained to the original so logs keep where it failed.
+    """
+    err.restore_outcome = outcome  # type: ignore[attr-defined]
+    original: BaseException = err
+    if not isinstance(err, ToolError):
+        raise original
+    try:
+        reply = json.loads(str(err))
+    except ValueError:
+        reply = None  # raised below, outside this handler, to keep its context
+    if not isinstance(reply, dict):
+        raise original
+    data = reply.get("data")
+    reply["data"] = {**data, **outcome} if isinstance(data, dict) else outcome
+    carried = ToolError(
+        json.dumps(reply, indent=2, default=str), log_level=err.log_level
+    )
+    carried.__dict__.update(err.__dict__)
+    raise carried from err
+
+
+def note_no_safety_backup(
+    outcome: Any, domain: str, target: str | None, config: Any
+) -> None:
+    """Say why a restore goes ahead without a safety backup."""
+    if target is None:  # safety_target: the stored item no longer exists
+        stored = config.get("id") if isinstance(config, dict) else None
+        outcome["warnings"] = [
+            f"No safety backup was taken: {domain.removeprefix('helper_')} "
+            f"{stored} no longer exists, "
+            "so this restore overwrites none of its state."
+        ]
+        return
+    outcome["warnings"] = [
+        f"No safety backup was taken: nothing was found under {target}. If it "
+        "was renamed since this backup, the restore overwrites its current state "
+        "without one."
+    ]

{ha_mcp_dev-8.7.0.dev3060 → ha_mcp_dev-8.7.0.dev3061}/src/ha_mcp/backup_manager.py

@@ -75,9 +75,21 @@ from .backup_diff import (
     _compute_json_patch,
     _summarize_patch_counts,
 )
-from .backup_entity_ids import _restore_entity_ids
+from .backup_entity_ids import (
+    _restore_entity_ids,
+    update_with_registry_icon,
+    with_registry_icon,
+)
+from .backup_helper_target import fetch_helper as _fetch_helper
+from .backup_helper_target import note_no_safety_backup as _note_no_safety_backup
+from .backup_helper_target import (
+    raise_with_restore_outcome as _raise_with_restore_outcome,
+)
+from .backup_helper_target import require_holds as _require_holds
+from .backup_helper_target import safety_target as _safety_target
 from .backup_integrations import fetch_integration, restore_integration
 from .backup_tags import restore_tag, tag_snapshot
+from .backup_zones import fetch_zone, restore_zone
 from .client.rest_client import (
     HomeAssistantCommandError,
     HomeAssistantConnectionError,
@@ -738,6 +750,7 @@ class BackupManager:
         force: bool = False,
         mandatory: bool = False,
         skip_reasons: list[str] | None = None,
+        holds: Any = None,
     ) -> Path | None:
         """Capture a snapshot for ``domain:entity_id`` if throttle elapsed.
 
@@ -765,6 +778,9 @@ class BackupManager:
 
         ``skip_reasons`` (best-effort mode) collects why a capture that was
         due did not happen, so the caller can tell its own caller.
+
+        ``holds`` is the id the captured item must have; another item raises
+        ``BackupRestoreError`` before anything is written.
         """
         if not force:
             await self.ensure_directory_ready()
@@ -809,6 +825,8 @@ class BackupManager:
             )
             if config is _SNAPSHOT_SKIP:
                 return None
+            if holds is not None:
+                _require_holds(config, holds, entity_id)
             return await self._write_and_rotate(
                 domain, entity_id, key, config, tool_name, now, mandatory=mandatory
             )
@@ -1502,7 +1520,9 @@ class BackupManager:
             flow_driven = is_flow or domain == "helper_config_subentry"
             if needs_safety and (flow_driven or take_safety_backup):
                 step = "safety_backup"
-                safety_path = await self._capture_restore_safety(domain, entity_id)
+                safety_path = await self._capture_restore_safety(
+                    domain, entity_id, outcome, config
+                )
                 if safety_path is not None:
                     self._protect_snapshot(safety_path.name)
                     await _await_backup_io(_require_restore_safety, safety_path)
@@ -1541,7 +1561,9 @@ class BackupManager:
                     reason=_flow_failure_reason(step, err),
                     **outcome,
                 ) from err
-            raise
+            # The error keeps its own type and code; the safety backup to revert
+            # with and any warnings ride along for the caller.
+            _raise_with_restore_outcome(err, {**outcome, "apply_status": apply_status})
         finally:
             if safety_path is not None:
                 self._unprotect_snapshot(safety_path.name)
@@ -1559,21 +1581,41 @@ class BackupManager:
         # existing one is checked against the snapshot by its options flow.
         return await handler.fetch(self._client, entity_id) is not None
 
-    async def _capture_restore_safety(self, domain: str, entity_id: str) -> Path | None:
+    async def _capture_restore_safety(
+        self,
+        domain: str,
+        entity_id: str,
+        outcome: dict[str, Any] | None = None,
+        config: Any = None,
+    ) -> Path | None:
         """Take a restore's recovery point; a failed capture raises and blocks it."""
         is_flow = _is_flow_helper_domain(domain)
-        path = await self.maybe_snapshot(
-            domain,
-            entity_id,
-            tool_name="ha_manage_backup.restore.safety",
-            force=is_flow or domain == "helper_config_subentry",
-            mandatory=True,
-        )
+        flow_driven = is_flow or domain == "helper_config_subentry"
+        if not flow_driven and not getattr(self._settings, "enable_auto_backup", False):
+            return None  # auto-backup off: no safety backup is promised
+        # The restore overwrites the current state, so the throttle that a
+        # recent snapshot of an older state set does not apply.
+        target = await _safety_target(self._client, domain, entity_id, config)
+        checked = not flow_driven and outcome is not None
+        path = None
+        if target is not None:  # None: the item the restore writes is gone
+            path = await self.maybe_snapshot(
+                domain,
+                target,
+                tool_name="ha_manage_backup.restore.safety",
+                force=True,
+                mandatory=True,
+                holds=config.get("id")
+                if checked and isinstance(config, dict)
+                else None,
+            )
         if path is None and is_flow:
             raise MandatoryBackupError(
                 f"{_flow_label(_flow_type(domain))} helper no longer exists; "
                 "restore was not attempted"
             )
+        if checked and path is None:
+            _note_no_safety_backup(outcome, domain, target, config)
         return path
 
     # ----- diff ----------------------------------------------------------
@@ -1592,6 +1634,14 @@ class BackupManager:
         if handler is None:
             raise LookupError(f"No diff handler registered for domain {domain!r}")
         current = await handler.fetch(self._client, data["entity_id"])
+        if (
+            isinstance(current, dict)
+            and isinstance(data["config"], dict)
+            and "registry_icon" not in data["config"]
+        ):
+            # A snapshot from before registry icons were recorded: its restore
+            # leaves the registry alone, so the icon is no difference.
+            current.pop("registry_icon", None)
         if _is_flow_helper_domain(domain) and current is not None:
             # Both MCP and Settings preview this comparison. Registry metadata
             # is recreation-only; an existing-entry restore applies options.
@@ -2524,25 +2574,6 @@ async def _restore_calendar_event(client: Any, entity_id: str, config: Any) -> A
     return await _recreate_calendar_event(client, cal, event, start, end)
 
 
-# Zones — zone/{list,update} (no ``config/`` prefix per HA's actual WS API;
-# matches ``tools_zones.py`` which is the authoritative usage).
-
-
-async def _fetch_zone(client: Any, entity_id: str) -> Any:
-    items = _require_list(await _ws_send(client, {"type": "zone/list"}), "zone/list")
-    for item in items:
-        if item.get("id") == entity_id or item.get("name") == entity_id:
-            return item
-    return None
-
-
-async def _restore_zone(client: Any, entity_id: str, config: Any) -> Any:
-    payload = _strip_readonly(config, "id")
-    payload["type"] = "zone/update"
-    payload["zone_id"] = config.get("id", entity_id)
-    return await _ws_send(client, payload)
-
-
 # Areas / floors — config/area_registry/{list,update}, config/floor_registry/{list,update}
 
 
@@ -2717,8 +2748,9 @@ async def _restore_device(client: Any, entity_id: str, config: Any) -> Any:
 # Integration enable/disable — restore re-applies the disabled flag.
 
 
-# Helpers — one handler family. Entity ID is "<helper_type>:<id>" so each
-# helper type lists/restores via its native WS endpoints. The decorator
+# Helpers — one handler family. Entity ID is the id the tool was given (a bare
+# id or <type>.<id>); each helper type lists/restores via its native WS
+# endpoints (fetch: backup_helper_target.py). The decorator
 # constructs the domain key as ``helper_<type>`` so files group naturally.
 
 _HELPER_LIST_TYPES = {
@@ -2737,57 +2769,10 @@ _HELPER_LIST_TYPES = {
 }
 
 
-async def _fetch_helper(client: Any, entity_id: str, helper_type: str) -> Any:
-    """Fetch a storage helper's full config from its ``<helper_type>/list``.
-
-    Registered for ``_KNOWN_HELPER_TYPES`` only; flow helpers (config
-    entries) have their own handler family (``_make_flow_helper_handler``).
-    """
-    listed = await _ws_send(client, {"type": f"{helper_type}/list"})
-    if helper_type == "person" and isinstance(listed, dict):
-        listed = listed.get("storage")  # YAML-defined persons are not editable
-    items = _require_list(listed, f"{helper_type}/list")
-    object_id = entity_id.split(".", 1)[-1] if "." in entity_id else entity_id
-    for item in items:
-        if item.get("id") == object_id or item.get("id") == entity_id:
-            return await tag_snapshot(client, item) if helper_type == "tag" else item
-    # Fallback for renamed helpers: after an entity_id rename the object_id
-    # no longer equals the storage collection id (which stays the original
-    # create-time id == the registry unique_id), so the direct match above
-    # misses and the snapshot was silently skipped. Resolve the unique_id
-    # via the entity registry and match on that — the same key the helper
-    # update tool itself resolves to.
-    eid = entity_id if "." in entity_id else f"{helper_type}.{entity_id}"
-    try:
-        entry = await _ws_send(
-            client, {"type": "config/entity_registry/get", "entity_id": eid}
-        )
-    except HomeAssistantError as err:
-        # Only a genuine "entity not found" means there's nothing to back up;
-        # transport/auth/5xx errors must propagate so maybe_snapshot logs a
-        # WARNING rather than silently skipping. Same POLICY as _fetch_automation,
-        # but matched on the message substring because config/entity_registry/get
-        # failures arrive as a WS command error with no status_code to switch on.
-        # Best-effort: if HA's not-found wording ever changes, a real miss
-        # degrades to a WARNING + skip (never a swallowed fatal error).
-        msg = str(err).lower()
-        if "not_found" in msg or "not found" in msg:
-            return None
-        raise
-    unique_id = entry.get("unique_id") if isinstance(entry, dict) else None
-    if unique_id:
-        for item in items:
-            if str(item.get("id")) == str(unique_id):
-                return (
-                    await tag_snapshot(client, item) if helper_type == "tag" else item
-                )
-    return None
-
-
 async def _restore_helper(
     client: Any, entity_id: str, config: Any, helper_type: str
 ) -> Any:
-    """Restore a storage-backed helper via ``<helper_type>/update``.
+    """Restore a storage helper via ``<helper_type>/update`` (tag, zone: restore_*).
 
     Symmetric with ``_fetch_helper``: only list-backed types are
     supported. Unsupported types raise ``LookupError`` so the restore
@@ -2803,9 +2788,19 @@ async def _restore_helper(
     payload = _strip_readonly(config, "id")
     payload["type"] = f"{helper_type}/update"
     payload[f"{helper_type}_id"] = config.get("id", entity_id)
+    item_id = payload[f"{helper_type}_id"]
     if helper_type == "tag":
-        return await restore_tag(client, payload["tag_id"], payload)
-    return await _ws_send(client, payload)
+        return await restore_tag(client, item_id, payload)
+    if helper_type == "zone":
+        return await restore_zone(client, item_id, payload)
+    return await update_with_registry_icon(client, helper_type, item_id, payload)
+
+
+async def _registry_snapshot(client: Any, helper_type: str, item: dict) -> Any:
+    """The stored item plus its registry icon, and for a tag its registry name."""
+    if helper_type == "tag":
+        return await tag_snapshot(client, item)
+    return await with_registry_icon(client, helper_type, item)
 
 
 # Files & YAML (#1579 PR2) — capture is MCP-side via the ha_mcp_tools
@@ -3942,7 +3937,8 @@ def register_default_handlers(mgr: BackupManager, _client: Any) -> None:
     mgr.register(
         DomainHandler("calendar_event", _fetch_calendar_event, _restore_calendar_event)
     )
-    mgr.register(DomainHandler("zone", _fetch_zone, _restore_zone))
+    restore_zone_item = functools.partial(_restore_helper, helper_type="zone")
+    mgr.register(DomainHandler("zone", fetch_zone, restore_zone_item))
     mgr.register(
         DomainHandler("area_or_floor", _fetch_area_or_floor, _restore_area_or_floor)
     )

{ha_mcp_dev-8.7.0.dev3060 → ha_mcp_dev-8.7.0.dev3061}/src/ha_mcp/backup_tags.py

@@ -1,4 +1,4 @@
-"""A tag's name in its snapshot and on restore.
+"""A tag's name and icon in its snapshot and on restore.
 
 Core keeps a tag's name in the entity registry, not in the tag store:
 ``tag/list`` fills ``name`` with ``entity.name or entity.original_name`` (the
@@ -11,31 +11,29 @@ from __future__ import annotations
 
 from typing import Any
 
-from .backup_entity_ids import _manager
+from .backup_entity_ids import _manager, registry_row, restore_registry_icon
 
 
 async def _tag_entity(client: Any, tag_id: str) -> dict[str, Any] | None:
-    bm = _manager()
-    return next(
-        (
-            row
-            for row in await bm._entity_registry_rows(client)
-            if row.get("platform") == "tag" and row.get("unique_id") == tag_id
-        ),
-        None,
-    )
+    return await registry_row(client, "tag", tag_id)
 
 
 async def tag_snapshot(client: Any, item: dict[str, Any]) -> dict[str, Any]:
     """The listed tag with its registry name instead of the listed fallback."""
     entity = await _tag_entity(client, str(item.get("id")))
-    return {**item, "name": entity.get("name") if entity else item.get("name")}
+    return {
+        **item,
+        "name": entity.get("name") if entity else item.get("name"),
+        "registry_icon": entity.get("icon") if entity else None,
+    }
 
 
 async def restore_tag(client: Any, tag_id: str, payload: dict[str, Any]) -> Any:
     """``tag/update`` without a name the tag never had; a name given after the
     snapshot is cleared in the registry, which ``tag/update`` cannot do."""
     bm = _manager()
+    recorded = "registry_icon" in payload
+    registry_icon = payload.pop("registry_icon", None)
     unnamed = payload.get("name") is None
     if unnamed:
         payload.pop("name", None)
@@ -51,4 +49,7 @@ async def restore_tag(client: Any, tag_id: str, payload: dict[str, Any]) -> Any:
                     "name": None,
                 },
             )
-    return result
+    if not recorded:
+        return result
+    warnings = await restore_registry_icon(client, "tag", tag_id, registry_icon)
+    return {**result, "warnings": warnings} if warnings else result