fix(screenshot): do not recommend a restore the tool will refuse

The report told the agent to call ha_manage_theme(action='set_engine_theme')
even when the observation came from the client-credential fallback -- which
is the same condition under which the engine-theme actions refuse. It named
a command that cannot succeed.

The remedy is now chosen by provenance. With the engine's own token the
report keeps the guarded ha_manage_theme call. With the fallback it says
ha-mcp cannot confirm which account the value belongs to and will not act
on it, and directs restoration to that account's own Profile > General
instead. Both paths keep the dedicated-engine-account recommendation, which
removes the problem rather than working around it.

Tests assert each branch, including that the fallback report does not name
ha_manage_theme and the engine-credential report does not send the reader
to the UI.

Raised by CodeRabbit.

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

Author: kingpanther13

src/ha_mcp/dashboard_screenshot/theme_guard.py

@@ -351,25 +351,34 @@ async def detect_change(self) -> None:
             self._snapshot,
             current,
         )
+        if self.credential_is_engine:
+            remedy = (
+                "To restore it, call ha_manage_theme(action="
+                f"'set_engine_theme', value={restore_value!r}, "
+                f"expected_current={current!r}) -- that guard re-checks the "
+                "stored theme immediately before writing and skips the write "
+                "if it changed."
+            )
+        else:
+            # Do NOT name ha_manage_theme here: this branch is reached via the
+            # client-credential fallback, which is the same condition under
+            # which the engine-theme actions refuse. Recommending them would
+            # send the agent at a command that cannot succeed.
+            remedy = (
+                "This was observed with ha-mcp's own Home Assistant "
+                "credential rather than the engine's own token, so ha-mcp "
+                "cannot confirm which account it belongs to and will not act "
+                "on it. Restore it from that account's own session: Profile "
+                "> General in the Home Assistant UI."
+            )
         self.warnings.append(
             "The screenshot engine changed the saved frontend theme of the "
             "account its token belongs to, which also changes that account's "
             "live web and mobile sessions. This tool is read-only and will "
-            "not change it back. To restore it, call ha_manage_theme("
-            f"action='set_engine_theme', value={restore_value!r}, "
-            f"expected_current={current!r}) -- the expected_current guard "
-            "refuses the write if anything changed the theme in the "
-            "meantime. To stop this happening at all, give the screenshot "
-            "engine its own Home Assistant user and long-lived token, so "
-            "its writes land on an account nobody looks at."
-            + (
-                ""
-                if self.credential_is_engine
-                else " NOTE: this was observed with ha-mcp's own Home "
-                "Assistant credential rather than the engine's own token, so "
-                "it is the engine's account only if both run as the same "
-                "user. Verify before restoring."
-            )
+            f"not change it back. {remedy} To stop this happening at all, "
+            "give the screenshot engine its own Home Assistant user and "
+            "long-lived token, so its writes land on an account nobody "
+            "looks at."
         )
 
 

tests/src/unit/test_dashboard_screenshot_theme_guard.py

@@ -777,8 +777,13 @@ async def test_uncertain_provenance_is_stated_in_the_report(self) -> None:
         _FakeWsClient.user_data[THEME_USER_DATA_KEY] = dict(_CLOBBERED_THEME)
         await guard.detect_change()
 
-        assert guard.warnings
-        assert "only if both run as the same user" in guard.warnings[0]
+        warning = guard.warnings[0]
+        assert "cannot confirm which account" in warning
+        # Must NOT name the tool: engine-theme actions refuse under exactly
+        # the condition that selected this fallback credential, so pointing
+        # the agent at them would recommend a command that cannot succeed.
+        assert "ha_manage_theme" not in warning
+        assert "Profile > General" in warning
 
     async def test_engine_credential_report_carries_no_caveat(self) -> None:
         _FakeWsClient.user_data[THEME_USER_DATA_KEY] = dict(_DARK_THEME)
@@ -787,5 +792,7 @@ async def test_engine_credential_report_carries_no_caveat(self) -> None:
         _FakeWsClient.user_data[THEME_USER_DATA_KEY] = dict(_CLOBBERED_THEME)
         await guard.detect_change()
 
-        assert guard.warnings
-        assert "same user" not in guard.warnings[0]
+        warning = guard.warnings[0]
+        assert "ha_manage_theme" in warning
+        assert "expected_current=" in warning
+        assert "Profile > General" not in warning