fix(themes): refuse engine-theme actions on an unidentifiable account

expected_current does not establish account identity. It compares values,
so when ha-mcp's own user and the sidecar's engine user happen to hold the
same theme the comparison passes and get_engine_theme reads, and
set_engine_theme overwrites, the WRONG profile -- leaving the engine
account untouched. My earlier answer that the compare-and-set covered this
was wrong.

An explicitly configured engine URL yields no addon_credential, so the only
fallback is ha-mcp's own credential, which under the dedicated-engine-
account setup this feature recommends is a different Home Assistant user.
Both engine-theme actions now refuse in that case with an error naming the
sidecar situation and pointing at the engine account's own Profile page,
rather than acting on a profile that may not be the engine's.

The restore examples in the tool docstring and beta.md omitted
expected_current, teaching the unguarded form to any agent following them
after a warning. Both now pass the warning's expected_current alongside the
value.

Raised by Codex.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Nm7tyA1nfxNCWFXaR3AxV

Author: kingpanther13

docs/beta.md

@@ -190,7 +190,9 @@ The screenshot and dashboard-get tools **detect** this and report it, but
 never write: they read the engine account's saved theme before and after the
 render and, when it changed, emit a warning naming the previous value. Undoing
 it is a separate, explicitly write-annotated call —
-`ha_manage_theme(action="set_engine_theme", value=...)` — so these tools stay
+`ha_manage_theme(action="set_engine_theme", value=..., expected_current=...)`
+— passing both values from the warning, so a theme changed in the meantime is
+refused rather than overwritten — so these tools stay
 honestly `readOnlyHint: True` (#1991). `ha_manage_theme(action=
 "get_engine_theme")` inspects the same value. Note this is the engine
 account's *per-user* profile, a different layer from the backend default that

src/ha_mcp/tools/tools_themes.py

@@ -50,6 +50,33 @@ async def _engine_credential(self) -> Any:
         from ..dashboard_screenshot.theme_guard import ThemeGuard
 
         engine_target = await resolve_engine()
+        if engine_target.addon_credential is None:
+            # An explicitly configured engine URL yields no addon_credential,
+            # so the only fallback is ha-mcp's OWN credential -- which under
+            # the dedicated-engine-account setup this feature recommends is a
+            # different Home Assistant user. Acting on it would read and
+            # overwrite the wrong profile while leaving the engine account
+            # untouched. expected_current cannot save us: it compares values,
+            # not identity, and two users sharing a theme compare equal.
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    "The screenshot engine's Home Assistant account cannot be "
+                    "identified, so its theme cannot be read or written.",
+                    suggestions=[
+                        (
+                            "This applies to an explicitly configured engine "
+                            + "URL (a Docker/standalone sidecar), where the "
+                            + "engine's own token is not discoverable."
+                        ),
+                        (
+                            "Restore the theme from that account's own "
+                            + "session: Profile > General in the Home "
+                            + "Assistant UI."
+                        ),
+                    ],
+                )
+            )
         guard = ThemeGuard.for_capture(engine_target.addon_credential, self._client)
         if guard.credential is None:
             raise_tool_error(
@@ -271,8 +298,11 @@ async def ha_manage_theme(
               action="set", theme_name="default")
         - Inspect the engine account's theme: ha_manage_theme(
               action="get_engine_theme")
-        - Undo a screenshot's theme change: ha_manage_theme(
-              action="set_engine_theme", value={"theme": "", "dark": False})
+        - Undo a screenshot's theme change (pass BOTH values from the
+          warning, so a theme changed since then is not overwritten):
+          ha_manage_theme(action="set_engine_theme",
+              value={"theme": "", "dark": False},
+              expected_current={"theme": "default", "dark": True})
         """
         try:
             if action == "list":

tests/src/unit/test_dashboard_screenshot_theme_guard.py

@@ -630,3 +630,48 @@ async def test_without_force_the_mismatch_is_refused(self) -> None:
                 force=False,
             )
         assert _FakeWsClient.user_data[THEME_USER_DATA_KEY] == _DARK_THEME
+
+
+class TestEngineAccountIdentity:
+    """Engine-theme actions refuse when the engine account is unidentifiable.
+
+    An explicit engine URL yields no addon_credential, so the only fallback is
+    ha-mcp's own credential -- a different user under the dedicated-account
+    setup this feature recommends. expected_current cannot substitute: it
+    compares values, not identity.
+    """
+
+    async def test_refuses_when_no_addon_credential(self, monkeypatch: Any) -> None:
+        from ha_mcp.tools.tools_themes import ThemesTools
+
+        async def fake_resolve() -> EngineTarget:
+            return EngineTarget(url="http://sidecar:10000", addon_credential=None)
+
+        monkeypatch.setattr(
+            "ha_mcp.dashboard_screenshot.provision.resolve_engine", fake_resolve
+        )
+        tools = ThemesTools(_client())
+
+        with pytest.raises(ToolError) as exc_info:
+            await tools.ha_manage_theme(action="get_engine_theme")
+
+        assert "cannot be identified" in str(exc_info.value)
+        assert _FakeWsClient.instances == []
+
+    async def test_addon_credential_is_accepted(self, monkeypatch: Any) -> None:
+        from ha_mcp.tools.tools_themes import ThemesTools
+
+        async def fake_resolve() -> EngineTarget:
+            return EngineTarget(
+                url="http://homeassistant:8123",
+                addon_credential=_PUPPET_CREDENTIAL,
+            )
+
+        monkeypatch.setattr(
+            "ha_mcp.dashboard_screenshot.provision.resolve_engine", fake_resolve
+        )
+        _FakeWsClient.user_data[THEME_USER_DATA_KEY] = dict(_DARK_THEME)
+        tools = ThemesTools(_client())
+
+        result = await tools.ha_manage_theme(action="get_engine_theme")
+        assert result["data"]["theme"] == _DARK_THEME