fix(visibility): preserve report diagnostics on stdio

Author: claude

.github/workflows/haos-e2e-stdio-tests.yml

@@ -162,14 +162,28 @@ jobs:
         run: ls -lh /tmp/haos-test-image.qcow2
 
       - name: Run full E2E suite through stdio against HAOS
+        # Keep self-restarting addon tests away from concurrent workers. The
+        # stdio lane normally skips them because they are inaddon-only, but
+        # retaining the two-phase contract makes that isolation fail-safe if
+        # their transport coverage is widened later.
         run: |
           cd tests
-          uv run pytest src/e2e/ -n2 --dist loadscope -v --tb=short --maxfail=0 ${{ github.event.inputs.pytest_args }}
+          # PYTEST_ARGS is intentionally word-split into individual pytest args.
+          # shellcheck disable=SC2086
+          uv run pytest src/e2e/ \
+            -n2 --dist loadscope -v --tb=short --maxfail=0 \
+            -m "not addon_disruptive" $PYTEST_ARGS
+          # shellcheck disable=SC2086
+          uv run pytest src/e2e/ \
+            -n0 -v --tb=short --maxfail=0 \
+            -m addon_disruptive $PYTEST_ARGS \
+            || { rc=$?; [ "$rc" -eq 5 ] && echo "no disruptive tests in selection"; [ "$rc" -eq 5 ]; }
         env:
           HAMCP_ENV_FILE: "tests/.env.test"
           HAOS_TEST_IMAGE_PATH: /tmp/haos-test-image.qcow2
           HAOS_TEST_MODE: stdio
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PYTEST_ARGS: ${{ github.event.inputs.pytest_args }}
 
       - name: Extract HA diagnostics from booted qcow2
         if: always()

src/ha_mcp/settings_ui/locales/en.json

@@ -98,6 +98,8 @@
     "visibility.enforce.title": "Enforce mode",
     "visibility.enforce.help": "Extends the filter from decluttering search and overview to every tool read. A direct read of a hidden entity returns “not found”, and a content read (dashboard, template, automation, trace, log, or file) that would surface a hidden entity is refused. Best-effort concealment against incidental exposure, not a hardened security boundary.",
     "visibility.enforce.only_enforced": "Make hidden entities unreadable across all tools (not just search)",
+    "visibility.enforce.report_issue_help": "The issue-report tool stays available by default so it can collect diagnostics when visibility data cannot be loaded. Enable this only if issue reports and logs must also be checked for hidden entity IDs.",
+    "visibility.enforce.restrict_report_issue": "Apply enforce mode to ha_report_issue",
     "visibility.categories.title": "Hide by category",
     "visibility.categories.help": "Home Assistant tags auto-generated entities as diagnostic or config.",
     "visibility.categories.legend": "Entity categories to hide",

src/ha_mcp/settings_ui/settings.html

@@ -487,6 +487,8 @@ <h2 class="a11y-section-title" data-i18n="accessibility.colors.title">Custom col
     <h2 class="a11y-section-title" data-i18n="visibility.enforce.title">Enforce mode</h2>
     <p class="a11y-section-help" data-i18n="visibility.enforce.help">Extends the filter from decluttering search and overview to every tool read. A direct read of a hidden entity returns &ldquo;not found&rdquo;, and a content read (dashboard, template, automation, trace, log, or file) that would surface a hidden entity is refused. Best-effort concealment against incidental exposure, not a hardened security boundary.</p>
     <label class="a11y-option"><input type="checkbox" id="visibility-enforce"> <span data-i18n="visibility.enforce.only_enforced">Make hidden entities unreadable across all tools (not just search)</span></label>
+    <p class="a11y-section-help" data-i18n="visibility.enforce.report_issue_help">The issue-report tool stays available by default so it can collect diagnostics when visibility data cannot be loaded. Enable this only if issue reports and logs must also be checked for hidden entity IDs.</p>
+    <label class="a11y-option"><input type="checkbox" id="visibility-restrict-report-issue"> <span data-i18n="visibility.enforce.restrict_report_issue">Apply enforce mode to ha_report_issue</span></label>
   </section>
 
   <section class="a11y-section">

src/ha_mcp/settings_ui/settings.js

@@ -4488,6 +4488,7 @@ async function visibilityLoadConfig() {
   const cats = c.exclude_categories || [];
   document.getElementById('visibility-enabled').checked = !!c.enabled;
   document.getElementById('visibility-enforce').checked = !!c.enforce;
+  document.getElementById('visibility-restrict-report-issue').checked = !!c.restrict_report_issue;
   document.getElementById('visibility-cat-diagnostic').checked = cats.includes('diagnostic');
   document.getElementById('visibility-cat-config').checked = cats.includes('config');
   document.getElementById('visibility-exclude-hidden').checked = !!c.exclude_hidden;
@@ -4509,6 +4510,7 @@ async function visibilitySaveConfig() {
     version: visibilityVersion,
     enabled: document.getElementById('visibility-enabled').checked,
     enforce: document.getElementById('visibility-enforce').checked,
+    restrict_report_issue: document.getElementById('visibility-restrict-report-issue').checked,
     exclude_categories: cats,
     exclude_hidden: document.getElementById('visibility-exclude-hidden').checked,
     deny_entity_ids: _visibilityParseList(document.getElementById('visibility-deny').value, '\n'),

src/ha_mcp/stdio_settings_sidecar.py

@@ -1217,6 +1217,19 @@ async def dispatch(
             handlers["policy_get_value_source"],
             methods=["GET"],
         ),
+        # Entity visibility filter endpoints. The sidecar owns a hand-maintained
+        # route table (it cannot reuse FastMCP custom-route registration), so
+        # keep this pair in lockstep with settings_ui.register_settings_routes.
+        Route(
+            f"{secret_prefix}/api/visibility/config",
+            handlers["visibility_get_config"],
+            methods=["GET"],
+        ),
+        Route(
+            f"{secret_prefix}/api/visibility/config",
+            handlers["visibility_put_config"],
+            methods=["PUT"],
+        ),
     ]
 
     # /shutdown — POST endpoint that drops the disable sentinel and

src/ha_mcp/visibility/enforcement.py

@@ -19,6 +19,9 @@
 - **Unscannable surfaces are refused wholesale** while enforce is active — sandbox
   code execution and screenshot/pixel output can read arbitrary state that no text
   scan can attribute to an entity.
+- **Issue reports stay available by default.** ``ha_report_issue`` is the recovery
+  path when visibility inputs fail, so operators must explicitly opt it into the
+  same inbound/outbound scans with ``restrict_report_issue``.
 
 This is a strong read barrier against *incidental* exposure, not a cryptographic
 guarantee: a Jinja template that derives a hidden entity's state without ever
@@ -70,6 +73,7 @@
 _DASHBOARD_TOOL = "ha_config_get_dashboard"
 _DASHBOARD_SET_TOOL = "ha_config_set_dashboard"
 _CUSTOM_TOOL = "ha_manage_custom_tool"
+_REPORT_ISSUE_TOOL = "ha_report_issue"
 
 _SANDBOX_REASON = (
     "'{name}' executes sandbox code that can read arbitrary Home Assistant state, "
@@ -249,8 +253,8 @@ def _coerce_arguments(arguments: Any) -> dict[str, Any] | None:
     return None
 
 
-def _unwrap_proxy_call(args: dict[str, Any]) -> dict[str, Any] | None:
-    """Extract the innermost proxy-envelope ``arguments`` dict, or None if unusable.
+def _unwrap_proxy_call(args: dict[str, Any]) -> tuple[str, dict[str, Any]] | None:
+    """Extract the innermost proxy target and arguments, or None if unusable.
 
     Mirrors ``ReadOnlyMiddleware._unwrap_proxy_call``: the categorized call proxies
     accept ``arguments`` as a JSON string, so an inner exact entity_id match would
@@ -269,7 +273,15 @@ def _unwrap_proxy_call(args: dict[str, Any]) -> dict[str, Any] | None:
         arguments = _coerce_arguments(arguments.get("arguments"))
     if not isinstance(name, str) or arguments is None:
         return None
-    return arguments
+    return name, arguments
+
+
+def _effective_tool_name(name: str, args: dict[str, Any]) -> str:
+    """Return the real tool name when this call is a categorized proxy."""
+    if name not in PROXY_META_TOOLS:
+        return name
+    inner = _unwrap_proxy_call(args)
+    return inner[0] if inner is not None else name
 
 
 def _config_cache_key(config: VisibilityConfig) -> str:
@@ -324,6 +336,14 @@ async def _active_config(self, tool_name: str) -> VisibilityConfig | None:
                 "using last-known-good config" if config else "failing closed",
                 exc_info=True,
             )
+        # ``ha_report_issue`` is intentionally the diagnostic escape hatch. A
+        # missing/corrupt first config load therefore follows its safe default
+        # (unrestricted), while a last-known-good explicit opt-in continues to
+        # enforce. Successful loads consult the live toggle on every call.
+        if tool_name == _REPORT_ISSUE_TOOL and (
+            config is None or not config.restrict_report_issue
+        ):
+            return None
         if config is None:
             _raise_enforced(tool_name, _CONFIG_LOAD_FAILED_REASON)
         if not (
@@ -354,12 +374,11 @@ class VisibilityInboundEnforcement(_VisibilityEnforcementBase):
     async def on_call_tool(
         self, context: MiddlewareContext, call_next: CallNext
     ) -> Any:
-        config = await self._active_config(context.message.name)
-        if config is None:
-            return await call_next(context)
-
         name = context.message.name
         args = context.message.arguments or {}
+        config = await self._active_config(_effective_tool_name(name, args))
+        if config is None:
+            return await call_next(context)
 
         reason = _unscannable_reason(name, args)
         if reason is not None:
@@ -387,7 +406,7 @@ def _scan_inbound(
         if name in PROXY_META_TOOLS:
             inner = _unwrap_proxy_call(args)
             if inner is not None:
-                exact, embedded = _scan_value(inner, hidden, regex)
+                exact, embedded = _scan_value(inner[1], hidden, regex)
         raw_exact, raw_embedded = _scan_value(args, hidden, regex)
         exact = exact or raw_exact
         embedded = embedded or raw_embedded
@@ -409,10 +428,11 @@ class VisibilityOutboundEnforcement(_VisibilityEnforcementBase):
     async def on_call_tool(
         self, context: MiddlewareContext, call_next: CallNext
     ) -> Any:
-        config = await self._active_config(context.message.name)
+        name = context.message.name
+        args = context.message.arguments or {}
+        config = await self._active_config(_effective_tool_name(name, args))
         if config is None:
             return await call_next(context)
-        name = context.message.name
         try:
             _hidden, regex = await self._hidden_and_regex(config)
         except VisibilityDataUnavailable:

src/ha_mcp/visibility/model.py

@@ -42,6 +42,11 @@ class VisibilityConfig(BaseModel):
     # the same hidden set is applied, not which entities are hidden, so it is
     # deliberately absent from ``to_wire`` and ``config_has_active_hide_dimensions``.
     enforce: bool = False
+    # ``ha_report_issue`` is the recovery path when visibility enforcement or
+    # its HA registry inputs fail. Keep it outside the barrier by default so it
+    # can return diagnostics; operators who treat report/log output as sensitive
+    # can opt it back into the normal inbound + outbound scans.
+    restrict_report_issue: bool = False
 
     def to_wire(self) -> dict[str, Any]:
         """Serialize the hide dimensions for the component ``search`` fast path.

tests/src/e2e/basic/test_backend_dispatch_smoke.py

@@ -85,13 +85,13 @@
     # gain 10; container is unchanged because the tests run there.
     # Entries below are CI-observed item counts, bumped only for intentional
     # marker-gated additions rather than runtime skips.
-    "container": 74,  # +1 HAOS stdio visibility e2e (haos_only)
+    "container": 74,  # +1 HAOS stdio visibility e2e (haos_stdio_only)
     "haos": 49,  # +1 HAOS stdio visibility e2e (haos_stdio_only)
     # HAOS stdio is the external HAOS set plus ``external_only`` tests, whose
-    # test-process monkeypatches cannot reach the subprocess server. Start with
-    # a conservative static ceiling; replace it with the CI-observed count once
-    # the first lane run reports its collection summary.
-    "haos_stdio": 112,
+    # test-process monkeypatches cannot reach the subprocess server. The first
+    # full lane run on 2026-08-18 observed 103 collection-time marker skips
+    # (plus 9 runtime skips); keep the same five-item buffer as established lanes.
+    "haos_stdio": 108,
     "haos_inaddon": 77,  # +1 HAOS stdio visibility e2e (haos_stdio_only)
     # Embedded backend (#1527, E2E_BACKEND=embedded). Skips exactly the container
     # lane's marker-skips PLUS two embedded-specific additions:
@@ -106,7 +106,7 @@
     # 1) + not_on_embedded 2 = 101. Parametrize inflates that to the CI-observed
     # count the entry below is pinned to — 133 on this PR's run, 132 before the
     # self-restart e2e. Read the count off a run rather than deriving it.
-    "embedded": 134,  # +1 HAOS stdio visibility e2e (haos_only)
+    "embedded": 134,  # +1 HAOS stdio visibility e2e (haos_stdio_only)
     # HAOS embedded backend (#1527, HAOS_TEST_MODE=embedded). A HAOS lane, so it
     # skips the SAME set as the external HAOS lane (container_only + inaddon_only)
     # PLUS two haos_embedded-specific additions:

tests/src/e2e/conftest.py

@@ -241,9 +241,9 @@ def pytest_collection_modifyitems(config, items):
     - ``container_only``: only runs on the testcontainer backend.
     - ``external_only``: any tier where the server-under-test lives IN the
       pytest process — plain testcontainer AND HAOS external (``mcp_client``
-      is an in-process FastMCP server talking HTTP to HAOS). Skipped on
-      inaddon, container-embedded and HAOS-embedded. The name is historical
-      and does NOT mean "HAOS external only"; see the skip expression below.
+      is an in-process FastMCP server talking HTTP to HAOS). Skipped on stdio,
+      inaddon, container-embedded, and HAOS-embedded. The name is historical and
+      does NOT mean "HAOS external only"; see the skip expression below.
     - ``inaddon_only``: HAOS inaddon mode only (``mcp_client`` is HTTP
       to the addon's MCP endpoint, ``is_running_in_addon()=True`` paths
       exercised). Skipped on external mode and on testcontainer.
@@ -264,10 +264,10 @@ def pytest_collection_modifyitems(config, items):
     # The HAOS embedded lane (#1527) IS a HAOS backend (``haos`` True — qcow2
     # staged), so ``haos_only`` runs and ``container_only`` skips exactly like the
     # other HAOS lanes. Its server-under-test is the in-process MCP server
-    # inside the HAOS core container, driven over its ingress webhook — same
-    # out-of-process constraint as inaddon / container-embedded, so ``external_only``
-    # skips here too; and the haos_only embedded smoke module is redundant with the
-    # lane's own session backend, so it skips via ``not_on_haos_embedded``.
+    # inside the HAOS core container, driven over its ingress webhook — the same
+    # out-of-process constraint as stdio/inaddon/container-embedded, so
+    # ``external_only`` skips here too; the haos_only embedded smoke module is
+    # redundant with the lane's session backend and skips via ``not_on_haos_embedded``.
     haos_embedded = haos and is_haos_embedded_mode()
     skip_haos = pytest.mark.skip(
         reason="HAOS backend not selected (set HAOS_TEST_IMAGE_PATH)"
@@ -282,7 +282,7 @@ def pytest_collection_modifyitems(config, items):
         reason="HAOS stdio mode required (set HAOS_TEST_MODE=stdio)"
     )
     skip_external_only = pytest.mark.skip(
-        reason="out-of-process server (inaddon/embedded); test needs an "
+        reason="out-of-process server (stdio/inaddon/embedded); test needs an "
         "in-process server it can reconfigure via env/monkeypatch or reach an "
         "in-process mock"
     )
@@ -2823,9 +2823,7 @@ async def mcp_client(
         client = _stdio_client(container_info, haos_stdio_config_dir)
         try:
             async with client:
-                logger.debug(
-                    "🔗 FastMCP client connected (stdio subprocess transport)"
-                )
+                logger.debug("🔗 FastMCP client connected (stdio subprocess transport)")
                 yield client
         finally:
             _retire_stdio_sidecar(haos_stdio_config_dir)
@@ -2897,6 +2895,7 @@ def _stdio_client(container_info: dict[str, Any], config_dir: Path) -> Client:
         command="ha-mcp",
         args=[],
         env=_stdio_env(container_info, config_dir),
+        keep_alive=False,
     )
     return Client(transport)
 

tests/src/e2e/haos_only/test_stdio_entity_visibility.py

@@ -64,13 +64,9 @@ async def test_stdio_sidecar_config_drives_real_visibility_middleware(
             # Seed the subprocess usage log with the entity id. report_issue's
             # recent_logs field makes the later outbound-policy assertion
             # deterministic without creating or mutating any HA entity.
-            await mcp.call_tool_success(
-                "ha_get_state", {"entity_id": _HIDDEN_ENTITY}
-            )
+            await mcp.call_tool_success("ha_get_state", {"entity_id": _HIDDEN_ENTITY})
 
-            current = await asyncio.to_thread(
-                _visibility_request, settings_url, "GET"
-            )
+            current = await asyncio.to_thread(_visibility_request, settings_url, "GET")
             saved = await asyncio.to_thread(
                 _visibility_request,
                 settings_url,
@@ -119,10 +115,9 @@ async def test_stdio_sidecar_config_drives_real_visibility_middleware(
                 "ha_report_issue",
                 {"tool_call_count": 2, "fields": ["recent_logs"]},
             )
-            assert (
-                restricted_report["error"]["code"]
-                == "ENTITY_VISIBILITY_ENFORCED"
-            ), restricted_report
+            assert restricted_report["error"]["code"] == "ENTITY_VISIBILITY_ENFORCED", (
+                restricted_report
+            )
     finally:
         # Session-scoped stdio clients are shared by many tests on this worker;
         # always restore no-op visibility even when an API assertion fails.