ha-mcp-dev 9.2.0.dev3434__tar.gz → 9.2.0.dev3439__tar.gz

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.2.0.dev3434
+Version: 9.2.0.dev3439
 Summary: Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants.
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.2.0.dev3434"
+version = "9.2.0.dev3439"
 description = "Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants."
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
@@ -85,23 +85,8 @@ ha-mcp-web = "ha_mcp.__main__:main_web"
 ha-mcp-oauth = "ha_mcp.__main__:main_oauth"
 ha-mcp-oidc = "ha_mcp.__main__:main_oidc"
 
-[tool.uv.build-backend]
-module-name = "ha_mcp"
-source-exclude = [
-    "src/ha_mcp/resources/skills-vendor/.*",
-    "src/ha_mcp/resources/skills-vendor/*.md",
-    "src/ha_mcp/resources/skills-vendor/evals",
-    "src/ha_mcp/resources/skills-vendor/scripts",
-    "src/ha_mcp/settings_ui/AGENTS.md",
-    "src/ha_mcp/settings_ui/CLAUDE.md",
-]
-
-[tool.uv.sources.hamcp-test-env]
-path = "tests/test-env"
-editable = true
-
 [tool.mypy]
-python_version = "3.13"
+python_version = "3.14"
 mypy_path = "src"
 cache_dir = "/tmp/.mypy_cache"
 exclude = ["^src/ha_mcp/resources/skills-vendor/"]
@@ -118,6 +103,13 @@ module = ["ha_mcp._vendor.*"]
 follow_imports = "skip"
 ignore_errors = true
 
+[[tool.mypy.overrides]]
+module = [
+    "voluptuous",
+    "voluptuous.*",
+]
+follow_imports = "skip"
+
 [[tool.mypy.overrides]]
 module = [
     "annotatedyaml.*",
@@ -201,14 +193,18 @@ ignore = [
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 empty_parameter_set_mark = "fail_at_collect"
+strict_markers = true
+strict_config = true
 addopts = [
-    "--strict-markers",
-    "--strict-config",
     "--verbose",
     "--tb=short",
     "--maxfail=3",
     "-ra",
     "--durations=10",
+    "-p",
+    "no:pytest_homeassistant",
+    "-p",
+    "no:respx",
 ]
 markers = [
     "slow: marks tests as slow (use -m 'not slow' to skip)",
@@ -258,8 +254,8 @@ markers = [
     "requires_component_surface: needs an active ha_mcp_tools config entry - skipped on the no-tools lanes without an active server entry (plain container, HAOS inaddon, where it is absent or disabled); #2584",
 ]
 asyncio_mode = "auto"
-asyncio_default_fixture_loop_scope = "session"
-asyncio_default_test_loop_scope = "session"
+asyncio_default_fixture_loop_scope = "function"
+asyncio_default_test_loop_scope = "function"
 timeout = 300
 timeout_method = "signal"
 timeout_func_only = true
@@ -272,8 +268,27 @@ filterwarnings = [
     "ignore::DeprecationWarning",
     "ignore::PendingDeprecationWarning",
     "ignore::ResourceWarning",
+    "ignore::aiohttp.web_exceptions.NotAppKeyWarning",
+]
+
+[tool.uv]
+environments = ["python_full_version >= '3.14.2'"]
+
+[tool.uv.build-backend]
+module-name = "ha_mcp"
+source-exclude = [
+    "src/ha_mcp/resources/skills-vendor/.*",
+    "src/ha_mcp/resources/skills-vendor/*.md",
+    "src/ha_mcp/resources/skills-vendor/evals",
+    "src/ha_mcp/resources/skills-vendor/scripts",
+    "src/ha_mcp/settings_ui/AGENTS.md",
+    "src/ha_mcp/settings_ui/CLAUDE.md",
 ]
 
+[tool.uv.sources.hamcp-test-env]
+path = "tests/test-env"
+editable = true
+
 [tool.semantic_release]
 version_toml = ["pyproject.toml:project.version"]
 version_variables = [
@@ -306,7 +321,8 @@ upload_to_vcs_release = false
 
 [dependency-groups]
 dev = [
-    "aiohttp>=3.13.5",
+    "homeassistant==2026.11.0",
+    "pytest-homeassistant==2026.11.0",
     "websockets>=15.0.1",
     "docker>=7.1.0",
     "mcp>=1.26.0,<2",
@@ -317,9 +333,7 @@ dev = [
     "pytest-timeout>=2.3.0",
     "quickjs-ng==0.17.0.2",
     "pytest-rerunfailures>=15.0",
-    "voluptuous>=0.15.2",
     "voluptuous-openapi>=0.4.1",
-    "probatio>=0.11.4",
     "pytest-xdist>=3.8.0",
     "requests>=2.25.0",
     "lefthook>=1.10.0",

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/pyproject.toml.orig

@@ -4,12 +4,14 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.2.0.dev3434"
+version = "9.2.0.dev3439"
 description = "Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants."
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's
 # interpreter when run in-process by the ha_mcp_tools component (HA
-# core-2026.7 ships Python 3.14). src/ stays 3.13-compatible.
+# core-2026.7 ships Python 3.14). ruff infers its target from this floor, so
+# it writes no 3.14-only syntax while 3.13 can still install; CI, mypy, the
+# images and the dev environment run 3.14.
 requires-python = ">=3.13,<3.15"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -125,7 +127,7 @@ source-exclude = [
 ]
 
 [tool.mypy]
-python_version = "3.13"
+python_version = "3.14"
 mypy_path = "src"
 # /tmp keeps the cache on Linux tmpfs — avoids the slow Windows FS in WSL2.
 # Windows-native contributors can remove this line or override with MYPY_CACHE_DIR.
@@ -154,6 +156,13 @@ module = ["ha_mcp._vendor.*"]
 follow_imports = "skip"
 ignore_errors = true
 
+[[tool.mypy.overrides]]
+# Core 2026.11 installs probatio as ``voluptuous`` at import; the component and
+# the webhook proxy run on Core versions before and after that switch, so
+# voluptuous schemas stay untyped rather than typed as either library.
+module = ["voluptuous", "voluptuous.*"]
+follow_imports = "skip"
+
 [[tool.mypy.overrides]]
 module = [
     "annotatedyaml.*",
@@ -268,15 +277,30 @@ testpaths = ["tests"]
 # as neither a failure nor a real skip. Make it a collection error instead.
 empty_parameter_set_mark = "fail_at_collect"
 
+# Unregistered markers and unknown config keys are errors. Set here, not as
+# --strict-* in addopts: pytest 9.0 (the version Core's test package pins)
+# silently ignores those flags in addopts.
+strict_markers = true
+strict_config = true
+
 # Command line options
 addopts = [
-    "--strict-markers",
-    "--strict-config",
     "--verbose",
     "--tb=short",
     "--maxfail=3",
     "-ra",
     "--durations=10",
+    # Core's test plugin (pytest-homeassistant, dev group) blocks sockets,
+    # fails tests that leave threads or tasks behind, and needs a fresh event
+    # loop per test. The unit and app (add-on) trees load it from their
+    # conftest; E2E sessions, which share one loop and reach real containers,
+    # must not get it from the installed entry point.
+    "-p",
+    "no:pytest_homeassistant",
+    # respx's entry point imports httpx before Home Assistant can alias it to
+    # httpx2, which Core refuses at import. Core's plugin imports respx itself.
+    "-p",
+    "no:respx",
 ]
 
 # Test markers
@@ -333,13 +357,13 @@ markers = [
     "requires_component_surface: needs an active ha_mcp_tools config entry - skipped on the no-tools lanes without an active server entry (plain container, HAOS inaddon, where it is absent or disabled); #2584",
 ]
 
-# Async support - session-scoped loop lets session-scoped fixtures
-# (mcp_server, mcp_client, ha_client) share one event loop with tests.
-# Without this, each test gets a new loop and session-scoped httpx
-# clients fail with "Event loop is closed".
+# A fresh event loop per test, as Core's test plugin requires. The E2E tree
+# runs its tests and fixtures on one session loop instead (session-scoped
+# mcp_server, mcp_client and ha_client share it); see
+# tests/src/e2e/_conftest_collection.py.
 asyncio_mode = "auto"
-asyncio_default_fixture_loop_scope = "session"
-asyncio_default_test_loop_scope = "session"
+asyncio_default_fixture_loop_scope = "function"
+asyncio_default_test_loop_scope = "function"
 
 # Per-test timeout (pytest-timeout). A stuck server-side await otherwise
 # stalls the run silently until the JOB timeout - observed as a 22-minute
@@ -375,17 +399,23 @@ filterwarnings = [
     "ignore::PendingDeprecationWarning",
     # Allow all ResourceWarnings, including those emitted during test cleanup
     "ignore::ResourceWarning",
+    # Core's http component keeps a plain string key on its aiohttp app.
+    "ignore::aiohttp.web_exceptions.NotAppKeyWarning",
 ]
 
 [dependency-groups]
 dev = [
-    # Real aiohttp so tests can pin the ClientTimeout defaults the custom
-    # component's relay and the webhook-proxy addon rely on (both are stubbed
-    # in unit tests; nothing else would catch stub drift). NOT a runtime
-    # dependency — src/ never imports aiohttp; HA core provides it in-process.
-    # Floor = the aiohttp HA core 2026.6 pins (2026.7 pins 3.14.1, 2026.8.dev
-    # pins 3.14.3), so the version tested here is one a supported HA runs.
-    "aiohttp>=3.13.5",
+    # Real Home Assistant Core and Core's own test package: unit tests run
+    # against Core's modules and its `hass` fixture instead of hand-written
+    # fakes, and uv.lock resolves Core's exact pins for the packages ha-mcp
+    # shares with the embedded install (packages Core pins only in
+    # package_constraints.txt are moved by check_ha_constraint_alignment.py
+    # --sync-lock). Both stay on the Core version of the
+    # e2e image (tests/test_constants.py); Renovate bumps all three together.
+    # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
+    "homeassistant==2026.11.0",
+    # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
+    "pytest-homeassistant==2026.11.0",
     # Test infrastructure imports the SHARED websockets directly (the HAOS
     # runtime harness, the image bake, wait_helpers) to talk to Home
     # Assistant's own WebSocket API — that is test tooling driving HA, not
@@ -404,20 +434,12 @@ dev = [
     # Exercise the component's real sandbox thread affinity in focused unit tests.
     "quickjs-ng==0.17.0.2",
     "pytest-rerunfailures>=15.0",
-    # Real voluptuous for the config-flow tests (the component's
-    # config_flow imports it; HA provides it at runtime, tests need it here).
-    "voluptuous>=0.15.2",
     # Real voluptuous-openapi for the embedded e2e LLM-API test: it converts
     # the REAL tool-schema catalog exactly like llm_api.py does at runtime.
     # HA core shipped it through 2026.8; from 2026.9 the component manifest
-    # is what installs it. Unit tests stub it.
+    # is what installs it. aiohttp, voluptuous and probatio (what core 2026.9
+    # converts with) come with homeassistant above.
     "voluptuous-openapi>=0.4.1",
-    # What core 2026.9 switched to, and converts with when the manifest
-    # requirement above is missing. Needed to assert the round trip an
-    # LLM-API tool schema actually makes there (#2361): voluptuous-openapi
-    # alone cannot show the defect, since it spells an exclusive bound in the
-    # numeric form Anthropic accepts.
-    "probatio>=0.11.4",
     "pytest-xdist>=3.8.0",
     "requests>=2.25.0",
     "lefthook>=1.10.0",
@@ -433,6 +455,11 @@ dev = [
     "hamcp-test-env",
 ]
 
+[tool.uv]
+# The dev group's homeassistant requires Python >=3.14.2; the published
+# package keeps >=3.13, so only the lock is narrowed.
+environments = ["python_full_version >= '3.14.2'"]
+
 [tool.uv.sources]
 hamcp-test-env = { path = "tests/test-env", editable = true }
 

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/src/ha_mcp/__main__.py

@@ -502,7 +502,7 @@ def _log_startup_version() -> None:
             "A newer ha-mcp release is available: %s (you have %s). %s",
             info.latest,
             info.current,
-            update_command_hint(info.current),
+            update_command_hint(info.current, info),
         )
 
 

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/src/ha_mcp/backup_entity_ids.py

@@ -46,9 +46,9 @@ async def with_registry_icon(
     """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
+    it there when Core's schema has no icon field or cannot be read (older
+    versions also for zones and on every update), 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.
     """

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/src/ha_mcp/backup_zones.py

@@ -1,8 +1,9 @@
 """The zone a zone tool names, its registry icon, and a removed zone on restore.
 
-The helper tools keep a zone's icon in the entity registry unless the stored
-zone already has one (#2643), so the stored item alone can miss it: the
-snapshot records the registry's icon too. Core's ``zone/update`` needs the
+A zone's entity can carry an icon override in the entity registry (set with
+ha_set_entity, or by older ha-mcp versions in place of the stored icon), so
+the stored item alone can miss it: the snapshot records the registry's icon
+too. Core's ``zone/update`` needs the
 stored zone; once it was removed, the restore creates it again, and Core takes
 the new zone's id from the slug of its name. Core keeps a removed zone's
 registry entry for 30 days, so a zone created again under its old id in that

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/src/ha_mcp/config_registry.py

@@ -4,7 +4,7 @@ Every table is derived from the ``Setting`` metadata on the ``Settings``
 fields; add or change a setting there, not here.
 """
 
-from typing import NamedTuple
+from typing import NamedTuple, cast
 
 from pydantic.fields import FieldInfo
 
@@ -173,7 +173,7 @@ def _env(field: FieldInfo) -> str:
 
 def _ftype(field: FieldInfo) -> RegistryFieldType:
     assert field.annotation in (bool, int, float, str)
-    return field.annotation
+    return cast(RegistryFieldType, field.annotation)
 
 
 FEATURE_FLAG_FIELDS: tuple[FeatureFlagField, ...] = tuple(

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/src/ha_mcp/tools/bug_report_sources.py

@@ -5,6 +5,7 @@ import asyncio
 import contextlib
 import ipaddress
 import logging
+import platform
 from collections.abc import Callable
 from typing import Any
 from urllib.parse import urlparse
@@ -282,3 +283,14 @@ async def fetch_ha_install(client: Any) -> dict[str, Any] | None:
         if ws_client is not None:
             with contextlib.suppress(Exception):
                 await ws_client.disconnect()
+
+
+def detect_platform() -> dict[str, str]:
+    """Detect platform information."""
+    return {
+        "os": platform.system(),  # Windows, Darwin, Linux
+        "os_release": platform.release(),
+        "os_version": platform.version(),
+        "architecture": platform.machine(),
+        "python_version": platform.python_version(),
+    }

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/src/ha_mcp/tools/config_helpers/core_payload.py

@@ -61,7 +61,6 @@ def merged_update(
     name: str | None,
     icon: str | None,
     fields: dict[str, Any],
-    entity_id: str,
 ) -> dict[str, Any]:
     """The stored item plus the changes: Core's update writes the whole item.
 
@@ -75,8 +74,6 @@ def merged_update(
         body.pop("name", None)
     if name is not None:
         body["name"] = name
-    if helper_type == "zone":
-        icon = _zone_item_icon(stored, icon, entity_id)
     if icon is not None:
         if icon:
             body["icon"] = icon
@@ -86,33 +83,6 @@ def merged_update(
     return body
 
 
-def _zone_item_icon(
-    stored: dict[str, Any], icon: str | None, entity_id: str
-) -> str | None:
-    """The icon to write into a zone's stored item, ``None`` to leave it (#2643).
-
-    The zone entity shows the registry icon over the item's, and Core's zone
-    update merges into the item and rejects an empty icon, so an icon stored
-    there can never be removed. A new icon therefore goes into the item only
-    when it already holds one; otherwise the registry alone carries it and
-    stays clearable. Clearing an icon the item holds is refused.
-    """
-    if not stored.get("icon"):
-        return None
-    if icon == "":
-        raise_tool_error(
-            create_error_response(
-                ErrorCode.VALIDATION_INVALID_PARAMETER,
-                f"The icon of {entity_id} cannot be removed: the zone's stored "
-                f"icon ({stored['icon']}) is kept by Home Assistant's zone update "
-                "and would show again.",
-                context=_simple_helper_error_context("zone", entity_id=entity_id),
-                suggestions=["Set a different icon instead of an empty one"],
-            )
-        )
-    return icon
-
-
 def _reject(helper_type: str, message: str, **context: Any) -> None:
     raise_tool_error(
         create_error_response(

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/src/ha_mcp/tools/config_helpers/create.py

@@ -17,7 +17,7 @@ from ..ws_waiters import wait_for_entity_registered
 from .core_payload import (
     with_create_defaults,
 )
-from .icon_route import collection_icon
+from .icon_route import icon_targets, note_hidden_icon
 from .registry import _ws_error_msg
 from .schemas import (
     _attach_helper_skill,
@@ -125,24 +125,14 @@ async def _execute_create_simple_helper(
             )
         )
 
-    # A zone's update merges into the stored item and rejects an empty icon, so
-    # an icon stored there can never be removed: a new zone's icon goes to the
-    # entity registry (#2643), like the icon of a type whose schema has none or
-    # cannot be read.
-    item_icon = (
-        None
-        if helper_type == "zone"
-        else await collection_icon(client, helper_type, "create", icon)
-    )
-    registry_icon = icon if item_icon is None else None
-    message = _build_create_message(
-        helper_type, name, None if registry_icon else icon, fields
-    )
+    item_icon, registry_icon = await icon_targets(client, helper_type, "create", icon)
+    message = _build_create_message(helper_type, name, item_icon, fields)
     native = await _create_via_component(
         client, helper_type, message, area_id, labels, category, registry_icon
     )
     if native is not None:
         native_data, native_entity_id, native_warnings = native
+        await note_hidden_icon(client, native_entity_id, item_icon, native_warnings)
         create_response = _helper_response(
             "create",
             helper_type,
@@ -212,6 +202,7 @@ async def _execute_create_simple_helper(
             registry_icon,
         )
         await _apply_create_category(client, entity_id, category, helper_data, warnings)
+        await note_hidden_icon(client, entity_id, item_icon, warnings)
 
     create_response = _helper_response(
         "create",

ha_mcp_dev-9.2.0.dev3439/src/ha_mcp/tools/config_helpers/icon_route.py

@@ -0,0 +1,72 @@
+"""Route a storage helper's icon by the running Core collection's own fields."""
+
+from typing import Any
+
+from ...client.rest_client import HomeAssistantError
+from ..component_helper_collections import fetch_helper_schemas
+
+
+async def icon_targets(
+    client: Any, helper_type: str, action: str, icon: str | None
+) -> tuple[str | None, str | None]:
+    """Where an icon is written: ``(stored item, entity registry)``.
+
+    The item takes the icon when Core's ``action`` schema for the type
+    declares an ``icon`` field (person and tag declare none), and then the
+    registry does not: the helper and zone dialogs write the icon only to the
+    item, and a registry override would hide every later change made there
+    (#3001). A type without the field keeps its icon in the registry.
+
+    When the schemas cannot be read (no component, or a failed read) or do
+    not list the type or action, nothing is guessed: the icon goes to the
+    registry, as the entity settings set it, and a cleared icon ('') clears
+    both, since clearing only the registry would bring an older stored icon
+    back. A zone keeps its icon in the item even then: its schema has always
+    declared one, and the Zones editor shows only the stored icon.
+    """
+    if icon is None:
+        return None, None
+    schemas = await fetch_helper_schemas(client)
+    fields = schemas.get(helper_type, {}).get(action) if schemas else None
+    if isinstance(fields, list):
+        if any(isinstance(f, dict) and f.get("name") == "icon" for f in fields):
+            return icon, None
+        return None, icon
+    if helper_type == "zone":
+        return icon, None
+    return (icon, icon) if icon == "" else (None, icon)
+
+
+async def note_hidden_icon(
+    client: Any, entity_id: str | None, item_icon: str | None, warnings: list[str]
+) -> None:
+    """Warn when the entity's registry icon hides the icon just stored or
+    cleared.
+
+    The entity shows a registry icon over the stored one, and older ha-mcp
+    versions kept icons there (a zone's alone, every helper's on update), so
+    a changed or cleared stored icon can stay invisible. The registry read is
+    advisory: when it fails the write has still succeeded, so no warning is
+    given.
+    """
+    if item_icon is None or not entity_id:
+        return
+    try:
+        result = await client.send_websocket_message(
+            {"type": "config/entity_registry/get", "entity_id": entity_id}
+        )
+    except (HomeAssistantError, OSError, TimeoutError):
+        return
+    entry = result.get("result") if result.get("success") else None
+    override = entry.get("icon") if isinstance(entry, dict) else None
+    if not override or override == item_icon:
+        return
+    shown = (
+        f"shows its entity registry icon {override} over the stored icon {item_icon}"
+        if item_icon
+        else f"still shows its entity registry icon {override}"
+    )
+    warnings.append(
+        f"{entity_id} {shown}; clear it with "
+        f"ha_set_entity(entity_id='{entity_id}', icon='')."
+    )

{ha_mcp_dev-9.2.0.dev3434 → ha_mcp_dev-9.2.0.dev3439}/src/ha_mcp/tools/config_helpers/update.py

@@ -22,7 +22,7 @@ from ..config_write_helpers import apply_entity_category
 from ..helpers import raise_tool_error, ws_failure_code
 from ..ws_waiters import wait_for_entity_registered
 from .core_payload import merged_update
-from .icon_route import collection_icon
+from .icon_route import icon_targets, note_hidden_icon
 from .listing import listed_items
 from .registry import _ws_error_msg
 from .schemas import (
@@ -67,13 +67,12 @@ async def _execute_legacy_update(
     entity_id: str,
     unique_id: str,
     name: str | None,
-    icon: str | None,
+    item_icon: str | None,
     fields: dict[str, Any],
 ) -> dict[str, Any]:
     """Update through Core's ``<type>/update`` WS command (no component)."""
     stored = await _stored_item(client, helper_type, entity_id, unique_id)
-    item_icon = await collection_icon(client, helper_type, "update", icon)
-    body = merged_update(helper_type, stored, name, item_icon, fields, entity_id)
+    body = merged_update(helper_type, stored, name, item_icon, fields)
     result = await client.send_websocket_message(
         {**body, "type": f"{helper_type}/update", f"{helper_type}_id": unique_id}
     )
@@ -246,13 +245,15 @@ async def _execute_update_simple_helper(
         )
 
     warnings: list[str] = []
+    item_icon, registry_icon = await icon_targets(client, helper_type, "update", icon)
     native = await _update_via_component(
         client,
         helper_type,
         entity_id,
         helper_id,
         name,
-        icon,
+        item_icon,
+        registry_icon,
         area_id,
         labels,
         category,
@@ -260,6 +261,7 @@ async def _execute_update_simple_helper(
     )
     if native is not None:
         updated_data, entity, warnings = native
+        _note_kept_icon(helper_type, item_icon, updated_data, warnings)
     else:
         stored = await stored_helper_target(client, helper_type, helper_id, name)
         if stored is not None:
@@ -270,13 +272,14 @@ async def _execute_update_simple_helper(
             )
             entity, reason = entity_id, None
         updated_data = await _execute_legacy_update(
-            client, helper_type, entity or helper_id, unique_id, name, icon, fields
+            client, helper_type, entity or helper_id, unique_id, name, item_icon, fields
         )
+        _note_kept_icon(helper_type, item_icon, updated_data, warnings)
         if entity is None:
             given = [
                 field
                 for field, value in (
-                    ("icon", icon),
+                    ("icon", registry_icon),
                     ("area", area_id),
                     ("labels", labels),
                     ("category", category),
@@ -298,7 +301,7 @@ async def _execute_update_simple_helper(
             await _apply_update_registry_and_category(
                 client,
                 entity_id,
-                icon,
+                registry_icon,
                 area_id,
                 labels,
                 category,
@@ -315,6 +318,7 @@ async def _execute_update_simple_helper(
                 except Exception as e:  # noqa: BLE001
                     warnings.append(f"Update applied but verification failed: {e}")
 
+    await note_hidden_icon(client, entity, item_icon, warnings)
     update_response = _helper_response(
         "update",
         helper_type,
@@ -333,7 +337,8 @@ async def _update_via_component(
     entity_id: str,
     helper_id: str,
     name: str | None,
-    icon: str | None,
+    item_icon: str | None,
+    registry_icon: str | None,
     area_id: str | None,
     labels: list[str] | None,
     category: str | None,
@@ -353,12 +358,11 @@ async def _update_via_component(
     # The component names the item's own entity; without one the storage id
     # names the item, never the caller's guessed entity_id.
     entity_id = item.get("entity_id") or helper_id
-    item_icon = await collection_icon(client, helper_type, "update", icon)
-    body = merged_update(helper_type, item["item"], name, item_icon, fields, entity_id)
+    body = merged_update(helper_type, item["item"], name, item_icon, fields)
     registry = {
         key: value
         for key, value in (
-            ("icon", icon),
+            ("icon", registry_icon),
             ("area_id", area_id),
             ("labels", labels),
             ("category", category),
@@ -375,3 +379,22 @@ async def _update_via_component(
         error_context=_simple_helper_error_context(helper_type, entity_id=entity_id),
     )
     return None if result is None else native_result(result)
+
+
+def _note_kept_icon(
+    helper_type: str,
+    item_icon: str | None,
+    updated_data: dict[str, Any],
+    warnings: list[str],
+) -> None:
+    """Say so when Core kept a stored icon the caller cleared.
+
+    A zone's update merges into the stored item, so leaving the icon out keeps
+    it, as it does when the zone dialog's icon is emptied and saved.
+    """
+    if item_icon == "" and updated_data.get("icon"):
+        warnings.append(
+            f"Home Assistant kept the {helper_type}'s icon "
+            f"{updated_data['icon']}: its update keeps a stored icon, as the "
+            f"{helper_type} dialog does, so it can be changed but not removed."
+        )