ha-mcp-dev 8.5.0.dev2675__tar.gz → 8.5.0.dev2680__tar.gz

{ha_mcp_dev-8.5.0.dev2675/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2680}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.5.0.dev2675
+Version: 8.5.0.dev2680
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.5.0.dev2675 → ha_mcp_dev-8.5.0.dev2680}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.5.0.dev2675"
+version = "8.5.0.dev2680"
 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.5.0.dev2675 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/backup_manager.py

@@ -54,7 +54,7 @@ import time
 import weakref
 from collections import Counter
 from collections.abc import AsyncIterator, Awaitable, Callable
-from contextlib import asynccontextmanager, suppress
+from contextlib import AsyncExitStack, asynccontextmanager, suppress
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from functools import cached_property
@@ -67,6 +67,7 @@ from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
 from .client.rest_client import HomeAssistantConnectionError, HomeAssistantError
 from .utils.data_paths import get_data_dir
+from .utils.registry_update_lock import registry_update_lock
 
 logger = logging.getLogger(__name__)
 
@@ -2592,7 +2593,8 @@ async def _restore_area_or_floor(client: Any, entity_id: str, config: Any) -> An
         payload["floor_id"] = real_id
     else:
         raise ValueError(f"Unknown area/floor kind: {kind!r}")
-    return await _ws_send(client, payload)
+    async with registry_update_lock(kind, real_id):
+        return await _ws_send(client, payload)
 
 
 # Todo items — entity_id is "<todo.entity>::<item_uid>"
@@ -3538,43 +3540,56 @@ async def _restore_template_entity_id(
     """Restore only the newly created entity's ID/name, guarded by ownership."""
     row = await _created_template_entity(client, entry_id)
     source, target = row["entity_id"], saved["entity_id"]
-    if source.split(".")[0] != target.split(".")[0]:
-        raise BackupRestoreError(
-            "Recreated Template entity has an unexpected domain",
-            reason="entity_identity_mismatch",
-            verification_status="mismatched",
-        )
-    await _check_template_entity_collision(client, target, owned_entry_id=entry_id)
-    update: dict[str, Any] = {
-        "type": "config/entity_registry/update",
-        "entity_id": source,
-    }
-    if source != target:
-        update["new_entity_id"] = target
-    if row.get("name") != saved.get("name"):
-        update["name"] = saved.get("name")
-    if len(update) > 2:
-        try:
-            await _ws_send(client, update)
-        except _CAPTURE_TRANSIENT_ERRORS as err:
-            _log_template_failure("entity_rename", err)
+    locked_ids = {source, target}
+    async with AsyncExitStack() as locks:
+        # A rename changes the lock key; hold both IDs in a stable order.
+        for entity_id in sorted(locked_ids):
+            await locks.enter_async_context(registry_update_lock("entity", entity_id))
+        row = await _created_template_entity(client, entry_id)
+        source = row["entity_id"]
+        if source not in locked_ids:
             raise BackupRestoreError(
-                "The recreated helper's entity rename outcome is unknown",
-                reason="entity_rename_outcome_unknown",
-                entity_id_mapping={
-                    "created_entity_id": source,
-                    "target_entity_id": target,
-                },
-                verification_status="unavailable",
-            ) from err
-    actual = await _created_template_entity(client, entry_id)
-    if actual["entity_id"] != target or actual.get("name") != saved.get("name"):
-        raise BackupRestoreError(
-            "Recreated Template entity identity did not match",
-            reason="entity_identity_mismatch",
-            verification_status="mismatched",
-        )
-    return {"created_entity_id": source, "restored_entity_id": target}
+                "Recreated Template entity ID changed while waiting to restore it",
+                reason="entity_identity_mismatch",
+                verification_status="mismatched",
+            )
+        if source.split(".")[0] != target.split(".")[0]:
+            raise BackupRestoreError(
+                "Recreated Template entity has an unexpected domain",
+                reason="entity_identity_mismatch",
+                verification_status="mismatched",
+            )
+        await _check_template_entity_collision(client, target, owned_entry_id=entry_id)
+        update: dict[str, Any] = {
+            "type": "config/entity_registry/update",
+            "entity_id": source,
+        }
+        if source != target:
+            update["new_entity_id"] = target
+        if row.get("name") != saved.get("name"):
+            update["name"] = saved.get("name")
+        if len(update) > 2:
+            try:
+                await _ws_send(client, update)
+            except _CAPTURE_TRANSIENT_ERRORS as err:
+                _log_template_failure("entity_rename", err)
+                raise BackupRestoreError(
+                    "The recreated helper's entity rename outcome is unknown",
+                    reason="entity_rename_outcome_unknown",
+                    entity_id_mapping={
+                        "created_entity_id": source,
+                        "target_entity_id": target,
+                    },
+                    verification_status="unavailable",
+                ) from err
+        actual = await _created_template_entity(client, entry_id)
+        if actual["entity_id"] != target or actual.get("name") != saved.get("name"):
+            raise BackupRestoreError(
+                "Recreated Template entity identity did not match",
+                reason="entity_identity_mismatch",
+                verification_status="mismatched",
+            )
+        return {"created_entity_id": source, "restored_entity_id": target}
 
 
 async def _recreate_template_helper(

{ha_mcp_dev-8.5.0.dev2675 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/server.py

@@ -217,6 +217,10 @@ class HomeAssistantSmartMCPServer:
         # of the full description we just discarded).
         self._apply_lite_docstrings()
 
+        # Append the Claude Desktop approval note to write tools. After
+        # lite docstrings so the note survives the replacement.
+        self._apply_write_tool_note()
+
         # Enrich tool descriptions with BM25 keyword boosts. Runs
         # unconditionally so Claude's native deferred-tool search
         # (claude.ai) benefits even when ENABLE_TOOL_SEARCH is off.
@@ -1127,6 +1131,20 @@ class HomeAssistantSmartMCPServer:
                 "default."
             )
 
+    def _apply_write_tool_note(self) -> None:
+        """Append the Claude Desktop manual-approval note to write tools.
+
+        Applied unconditionally: the dropped calls never reach the server
+        (issue #2367), so the tool description is the only channel that
+        reaches the agent before the user clicks approve.
+        """
+        try:
+            from .transforms import WriteToolNoteTransform
+
+            self.mcp.add_transform(WriteToolNoteTransform())
+        except Exception:
+            logger.exception("Failed to apply WriteToolNoteTransform")
+
     def _apply_search_keyword_enrichment(self) -> None:
         """Append BM25 keyword boosts to tool descriptions.
 

{ha_mcp_dev-8.5.0.dev2675 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/tools/tools_areas.py

@@ -7,6 +7,7 @@ Home Assistant areas and floors - essential organizational features for smart ho
 
 import asyncio
 import logging
+from contextlib import nullcontext
 from typing import Annotated, Any, Literal
 
 from pydantic import Field
@@ -15,6 +16,7 @@ from ha_mcp._vendor.fastmcp.exceptions import ToolError
 from ha_mcp._vendor.fastmcp.tools import tool
 
 from ..errors import ErrorCode, create_error_response, create_validation_error
+from ..utils.registry_update_lock import registry_update_lock
 from .auto_backup import with_auto_backup
 from .component_registries import fetch_registries_via_component
 from .helpers import (
@@ -871,35 +873,38 @@ class AreaTools:
                 )
             )
 
-            # Issue #2159: the area registry stores an unknown floor_id
-            # verbatim, and an unknown label_id is dropped on the way in
-            # (HA filters the set through the label registry) — both end as a
-            # success envelope that does not match what was asked for, so
-            # validate before writing. ``_validate_cross_kind_params`` already
-            # rejected floor_id/labels for kind='floor', so this only ever
-            # runs for areas; None and "" / [] (clear) skip the lookup.
-            await validate_registry_ids(
-                self._client,
-                None,
-                parsed_labels,
-                None,
-                floor_id=floor_id,
-                fail_closed=True,
-            )
+            async with (
+                registry_update_lock(kind, id) if id is not None else nullcontext()
+            ):
+                # Issue #2159: the area registry stores an unknown floor_id
+                # verbatim, and an unknown label_id is dropped on the way in
+                # (HA filters the set through the label registry) — both end as a
+                # success envelope that does not match what was asked for, so
+                # validate before writing. ``_validate_cross_kind_params`` already
+                # rejected floor_id/labels for kind='floor', so this only ever
+                # runs for areas; None and "" / [] (clear) skip the lookup.
+                await validate_registry_ids(
+                    self._client,
+                    None,
+                    parsed_labels,
+                    None,
+                    floor_id=floor_id,
+                    fail_closed=True,
+                )
 
-            result = await self._client.send_websocket_message(message)
+                result = await self._client.send_websocket_message(message)
 
-            if result.get("success"):
-                return await self._area_or_floor_write_success(
-                    result,
-                    result_key=result_key,
-                    id_key=id_key,
-                    identifier=id,
-                    kind=kind,
-                    operation=operation,
-                    name=name,
-                    parsed_labels=parsed_labels,
-                )
+                if result.get("success"):
+                    return await self._area_or_floor_write_success(
+                        result,
+                        result_key=result_key,
+                        id_key=id_key,
+                        identifier=id,
+                        kind=kind,
+                        operation=operation,
+                        name=name,
+                        parsed_labels=parsed_labels,
+                    )
 
             error = result.get("error", {})
             error_msg = (

{ha_mcp_dev-8.5.0.dev2675 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/tools/tools_bug_report.py

@@ -73,6 +73,32 @@ MISSING_TOOL_HINT = (
     "tool is still missing after a refresh."
 )
 
+# Known Claude Desktop bugs that present as ha-mcp failures. Both live in
+# the client, never reach this server, and already have upstream tickets, so
+# the agent must rule them out before filing here.
+KNOWN_CLIENT_ISSUES_HINT = (
+    "KNOWN CLAUDE DESKTOP ISSUES (not ha-mcp bugs; check before filing):\n"
+    "1. A write tool (dashboard, automation, script, helper, service call) "
+    "hangs and the client reports a 4-minute timeout with no result, while "
+    "read tools work. Cause: Claude Desktop's manual-approval dialog for a "
+    "local MCP server accepts the click before the call is fully generated "
+    "and silently drops the call. The server never receives it. Tracked in "
+    "homeassistant-ai/ha-mcp#2367 and anthropics/claude-code#92014. Tell the "
+    "user to retry and wait a few seconds before clicking Allow once, or to "
+    "set the write tools to Always allow (Settings -> Connectors -> the "
+    "server -> Tool permissions). A dropped call never reached Home "
+    "Assistant, but the same timeout can also hide a call that landed and "
+    "lost only its result (anthropics/claude-code#80012), so read the target "
+    "back before repeating a write that is not idempotent.\n"
+    "2. Every tool call fails with 'expected nonoptional, received "
+    "undefined' when an optional parameter is omitted. Cause: Claude Desktop "
+    "2.110.0 rejects omitted optional MCP parameters. Tracked in "
+    "homeassistant-ai/ha-mcp#2472 and anthropics/claude-code#94608. Tell the "
+    "user to downgrade Claude Desktop to 1.52386.6 (links in #2472) until "
+    "the upstream fix ships.\n"
+    "Only file a bug if the problem persists after the matching workaround."
+)
+
 # Max characters to include from addon container logs.
 # 3000 chars ≈ 750 LLM tokens — keeps the tool response well below context budgets
 # while still capturing enough recent output to diagnose most issues.
@@ -906,7 +932,8 @@ class BugReportTools:
                     "None = full response. Typical for a runtime bug: "
                     "'runtime_bug_template,suggested_title,"
                     "runtime_bug_submit_url,duplicate_check_urls,"
-                    "anonymization_guide,instructions'; for agent feedback "
+                    "anonymization_guide,missing_tool_hint,"
+                    "known_client_issues_hint,instructions'; for agent feedback "
                     "swap in agent_behavior_template and "
                     "agent_behavior_submit_url. The templates already embed "
                     "the relevant logs, so the raw log keys are only needed "
@@ -917,7 +944,8 @@ class BugReportTools:
                     "runtime_bug_template, agent_behavior_template, "
                     "anonymization_guide, suggested_title, "
                     "runtime_bug_submit_url, agent_behavior_submit_url, "
-                    "duplicate_check_urls, missing_tool_hint, instructions."
+                    "duplicate_check_urls, missing_tool_hint, "
+                    "known_client_issues_hint, instructions."
                 ),
             ),
         ] = None,
@@ -1139,6 +1167,7 @@ class BugReportTools:
             "agent_behavior_submit_url": agent_behavior_submit_url,
             "duplicate_check_urls": duplicate_check_urls,
             "missing_tool_hint": MISSING_TOOL_HINT,
+            "known_client_issues_hint": KNOWN_CLIENT_ISSUES_HINT,
             "instructions": (
                 "WORKFLOW FOR PRESENTING BUG REPORTS:\n\n"
                 "0. **PRE-CHECK — is the problem a missing/unavailable tool?** If "
@@ -1148,6 +1177,12 @@ class BugReportTools:
                 "client tool list (not a server bug), fixed by refreshing or "
                 "reconnecting the MCP connection. Only continue with this report "
                 "if the tool is still missing after the user refreshes.\n\n"
+                "0b. **PRE-CHECK — is it a known Claude Desktop bug?** A write "
+                "tool that hangs to a 4-minute timeout, or every call failing "
+                "with 'expected nonoptional, received undefined', is a client "
+                "bug with an upstream ticket. See the `known_client_issues_hint` "
+                "field for the workaround to give the user, and only continue "
+                "if the problem persists after it.\n\n"
                 "1. **Check for duplicates FIRST** (before presenting the template):\n"
                 "   - Use the duplicate_check_urls to search for similar issues\n"
                 '   - If gh CLI is available: use `gh issue list --search "keyword"`\n'

{ha_mcp_dev-8.5.0.dev2675 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/tools/tools_config_helpers.py

@@ -27,6 +27,7 @@ from ..client.websocket_client import get_websocket_client
 from ..errors import ErrorCode, create_auth_error, create_error_response
 from ..redaction import redact_flow_schema, redaction_enabled
 from ..strict_bps import BestPracticeKeyParam
+from ..utils.registry_update_lock import registry_update_lock
 from .auto_backup import with_auto_backup
 from .component_api import (
     component_supports,
@@ -1826,7 +1827,8 @@ async def _entity_registry_update_coro(
         update_message["labels"] = labels
     if icon is not None:
         update_message["icon"] = icon if icon else None
-    return await client.send_websocket_message(update_message)
+    async with registry_update_lock("entity", entity_id):
+        return await client.send_websocket_message(update_message)
 
 
 async def _category_apply_coro(
@@ -2637,7 +2639,8 @@ async def _apply_create_entity_registry(
         update_message["area_id"] = area_id if area_id else None
     if labels is not None:
         update_message["labels"] = labels
-    update_result = await client.send_websocket_message(update_message)
+    async with registry_update_lock("entity", entity_id):
+        update_result = await client.send_websocket_message(update_message)
     if update_result.get("success"):
         if icon is not None:
             helper_data["icon"] = icon if icon else None
@@ -3269,7 +3272,8 @@ async def _apply_update_icon_area_labels(
         registry_update["area_id"] = area_id if area_id else None
     if labels is not None:
         registry_update["labels"] = labels
-    reg_result = await client.send_websocket_message(registry_update)
+    async with registry_update_lock("entity", entity_id):
+        reg_result = await client.send_websocket_message(registry_update)
     if reg_result.get("success"):
         if icon is not None:
             updated_data["icon"] = icon if icon else None
@@ -3333,7 +3337,8 @@ async def _execute_fallback_registry_update(
         fallback_msg["area_id"] = area_id if area_id else None
     if labels is not None:
         fallback_msg["labels"] = labels
-    result = await client.send_websocket_message(fallback_msg)
+    async with registry_update_lock("entity", entity_id):
+        result = await client.send_websocket_message(fallback_msg)
     updated_data: dict[str, Any] = {}
     if result.get("success"):
         updated_data = result.get("result", {}).get("entity_entry", {})

{ha_mcp_dev-8.5.0.dev2675 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/tools/tools_entities.py

@@ -21,6 +21,7 @@ from ..client.rest_client import (
 )
 from ..client.websocket_client import get_websocket_client
 from ..errors import ErrorCode, create_error_response
+from ..utils.registry_update_lock import registry_update_lock
 from .auto_backup import with_auto_backup
 from .component_api import (
     DEVICE_REGISTRY_CHILD_SEMANTICS,
@@ -1021,65 +1022,65 @@ class EntityTools:
         new_device_name: str | None = None,
         device_class: str | None = None,
         parsed_options: dict[str, dict[str, Any]] | None = None,
-        preflighted: bool = False,
     ) -> dict[str, Any]:
         """Update a single entity. Orchestrates the phase pipeline."""
-        # Phase 1: For add/remove label operations, fetch current labels first
-        final_labels = await self._resolve_final_labels(
-            entity_id, parsed_labels, label_operation
-        )
+        async with registry_update_lock("entity", entity_id):
+            # Phase 1: For add/remove label operations, fetch current labels first
+            final_labels = await self._resolve_final_labels(
+                entity_id, parsed_labels, label_operation
+            )
 
-        # Phase 2: Build update message for entity registry
-        message: dict[str, Any] = {
-            "type": "config/entity_registry/update",
-            "entity_id": entity_id,
-        }
-        updates_made: list[str] = []
-        _build_name_visibility_fields(
-            message, updates_made, area_id, name, icon, device_class
-        )
-        _build_state_tag_fields(
-            message,
-            updates_made,
-            enabled,
-            hidden,
-            parsed_aliases,
-            parsed_categories,
-            final_labels,
-            label_operation,
-            parsed_labels,
-        )
-        if new_entity_id is not None:
-            self._validate_entity_rename(
-                entity_id, new_entity_id, message, updates_made
+            # Phase 2: Build update message for entity registry
+            message: dict[str, Any] = {
+                "type": "config/entity_registry/update",
+                "entity_id": entity_id,
+            }
+            updates_made: list[str] = []
+            _build_name_visibility_fields(
+                message, updates_made, area_id, name, icon, device_class
             )
-        # expose_to and device_name are appended to updates_made only after their
-        # WS phases run (Phases 5-6), so the Phase-4 error context never claims
-        # they were applied before they ran.
-        has_deferred_work = parsed_expose_to is not None or new_device_name is not None
-        if not updates_made and not parsed_options and not has_deferred_work:
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    "No updates specified",
-                    suggestions=[
-                        "Provide at least one of: area_id, name, icon, device_class, enabled, hidden, aliases, categories, labels, options, expose_to, new_entity_id, or new_device_name"
-                    ],
+            _build_state_tag_fields(
+                message,
+                updates_made,
+                enabled,
+                hidden,
+                parsed_aliases,
+                parsed_categories,
+                final_labels,
+                label_operation,
+                parsed_labels,
+            )
+            if new_entity_id is not None:
+                self._validate_entity_rename(
+                    entity_id, new_entity_id, message, updates_made
                 )
+            # expose_to and device_name are appended to updates_made only after their
+            # WS phases run (Phases 5-6), so the Phase-4 error context never claims
+            # they were applied before they ran.
+            has_deferred_work = (
+                parsed_expose_to is not None or new_device_name is not None
             )
+            if not updates_made and not parsed_options and not has_deferred_work:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        "No updates specified",
+                        suggestions=[
+                            "Provide at least one of: area_id, name, icon, device_class, enabled, hidden, aliases, categories, labels, options, expose_to, new_entity_id, or new_device_name"
+                        ],
+                    )
+                )
+
+            # Save original entity_id before potential rename
+            original_entity_id = entity_id
 
-        # Save original entity_id before potential rename
-        original_entity_id = entity_id
-
-        # Issue #2159: validate cross-registry references immediately before
-        # the write — the narrowest window against a concurrent registry
-        # deletion (#2160 placed the area check here for the same reason).
-        # The bulk path preflights its shared labels/categories once at tool
-        # entry and passes preflighted=True so N entities don't repeat the
-        # lookups. For label add, only the added IDs are checked: the merged
-        # set may legitimately carry pre-existing dangling labels, whose
-        # cleanup path (label_operation="remove") must stay open.
-        if not preflighted:
+            # Issue #2159: validate cross-registry references immediately before
+            # the write — the narrowest window against a concurrent registry
+            # deletion (#2160 placed the area check here for the same reason).
+            # Bulk calls also revalidate here after waiting for the entity lock.
+            # For label add, only the added IDs are checked: the merged
+            # set may legitimately carry pre-existing dangling labels, whose
+            # cleanup path (label_operation="remove") must stay open.
             await validate_registry_ids(
                 self._client,
                 area_id,
@@ -1088,14 +1089,14 @@ class EntityTools:
                 fail_closed=True,
             )
 
-        # Phase 3: Send entity registry update (covers all fields except expose_to)
-        (
-            entity_id,
-            entity_entry,
-            has_registry_updates,
-        ) = await self._execute_registry_update(
-            entity_id, message, updates_made, new_entity_id
-        )
+            # Phase 3: Send entity registry update (covers all fields except expose_to)
+            (
+                entity_id,
+                entity_entry,
+                has_registry_updates,
+            ) = await self._execute_registry_update(
+                entity_id, message, updates_made, new_entity_id
+            )
 
         # Phase 4: Per-domain options
         entity_entry, options_succeeded = await self._apply_options_updates(
@@ -1221,7 +1222,6 @@ class EntityTools:
                     parsed_labels,
                     label_operation,
                     None,  # expose_to batched separately below
-                    preflighted=True,  # labels/categories validated at entry
                 )
                 for eid in entity_ids
             ],
@@ -1812,12 +1812,9 @@ class EntityTools:
             parsed_options = _parse_options_param(options)
             parsed_expose_to = _parse_expose_to_param(expose_to)
 
-            # Issue #2159 bulk preflight: labels/categories are shared across
-            # the fan-out, so validate them once here instead of once per
-            # entity inside _update_single_entity (area_id was rejected for
-            # bulk above). The single-entity path instead validates
-            # immediately before its registry write, minimizing the
-            # check-to-write window.
+            # Reject invalid shared references before any bulk writes. Each
+            # entity also revalidates under its lock to catch references deleted
+            # while waiting, preserving per-entity partial-progress reporting.
             if is_bulk:
                 await validate_registry_ids(
                     self._client,

{ha_mcp_dev-8.5.0.dev2675 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/tools/tools_labels.py

@@ -19,6 +19,7 @@ from ha_mcp._vendor.fastmcp.tools import tool
 from ..backup_manager import get_backup_manager
 from ..config import get_global_settings
 from ..errors import TOOL_ERROR_LOG_LEVEL, ErrorCode, create_error_response
+from ..utils.registry_update_lock import registry_update_lock
 from .auto_backup import with_auto_backup
 from .helpers import (
     exception_to_structured_error,
@@ -375,47 +376,48 @@ class LabelTools:
         self, label_id: str, area_id: str, assigned: list[str]
     ) -> None:
         """Fresh read-modify-write for one area. HA has no atomic label-add."""
-        areas = await self._list_area_registry(
-            context={"label_id": label_id, "area_id": area_id}
-        )
-        area = self._area_from_registry(areas, area_id)
-        if area is None:
-            self._raise_area_label_assign_failure(
-                label_id=label_id,
-                area_id=area_id,
-                message=f"area_id={area_id!r} does not exist in the area registry.",
-                assigned=assigned,
+        async with registry_update_lock("area", area_id):
+            areas = await self._list_area_registry(
+                context={"label_id": label_id, "area_id": area_id}
             )
-        current = _string_labels(area)
-        if label_id in current:
-            return
-        update = await self._client.send_websocket_message(
-            {
-                "type": "config/area_registry/update",
-                "area_id": area_id,
-                "labels": [*current, label_id],
-            }
-        )
-        if not update.get("success"):
-            self._raise_area_label_assign_failure(
-                label_id=label_id,
-                area_id=area_id,
-                message=(
-                    f"Failed to assign label {label_id!r} to area {area_id!r}: "
-                    f"{update.get('error', 'Unknown error')}"
-                ),
-                assigned=assigned,
-            )
-        if not await self._confirm_area_has_label(label_id, area_id, update):
-            self._raise_area_label_assign_failure(
-                label_id=label_id,
-                area_id=area_id,
-                message=(
-                    f"Area {area_id!r} update succeeded but label "
-                    f"{label_id!r} is not present on the area."
-                ),
-                assigned=assigned,
+            area = self._area_from_registry(areas, area_id)
+            if area is None:
+                self._raise_area_label_assign_failure(
+                    label_id=label_id,
+                    area_id=area_id,
+                    message=f"area_id={area_id!r} does not exist in the area registry.",
+                    assigned=assigned,
+                )
+            current = _string_labels(area)
+            if label_id in current:
+                return
+            update = await self._client.send_websocket_message(
+                {
+                    "type": "config/area_registry/update",
+                    "area_id": area_id,
+                    "labels": [*current, label_id],
+                }
             )
+            if not update.get("success"):
+                self._raise_area_label_assign_failure(
+                    label_id=label_id,
+                    area_id=area_id,
+                    message=(
+                        f"Failed to assign label {label_id!r} to area {area_id!r}: "
+                        f"{update.get('error', 'Unknown error')}"
+                    ),
+                    assigned=assigned,
+                )
+            if not await self._confirm_area_has_label(label_id, area_id, update):
+                self._raise_area_label_assign_failure(
+                    label_id=label_id,
+                    area_id=area_id,
+                    message=(
+                        f"Area {area_id!r} update succeeded but label "
+                        f"{label_id!r} is not present on the area."
+                    ),
+                    assigned=assigned,
+                )
 
     async def _add_label_to_areas(
         self, label_id: str, area_ids: list[str]