feat(health): add check_hud_installation diagnostic (#1490)

Adds check #11 to HealthChecker so the v5.6.0/v5.6.1 failure mode is
detectable from the user's existing health check workflow without
having to read installer source.

What it verifies:
  1. ~/.claude/hud/codingbuddy-hud.py is present
  2. ~/.claude/hud/lib/ exists and contains the seven critical
     modules: hud_buddy, hud_state, hud_helpers, tiny_actor_presets,
     hud_version, hud_rate_limits, hud_layout
  3. Subprocess render smoke test catches the case where every file
     looks present but imports still fail at runtime (permission
     issues, partial copy, .pyc clash). The smoke test fails if
     the script returns the bare '◕‿◕ CodingBuddy' fallback.
  4. ~/.claude/hud/.version stamp is reported in the PASS message
     so users can confirm which plugin version installed the assets.

Coverage (test_health_check.py, +5 cases):
  - test_fail_when_script_missing
  - test_fail_when_lib_directory_missing
  - test_fail_when_required_modules_missing — names the missing module
  - test_fail_when_smoke_test_returns_fallback — uses a stub script
    that always prints the fallback face
  - test_pass_with_real_plugin_install — end-to-end: runs the real
    _install_statusline against the real codingbuddy-hud.py source
    in tmpdir, then asserts check_hud_installation returns PASS

run_all now returns 11 results (was 10); test renamed accordingly.

Refs #1490

Author: JeremyDev87

packages/claude-code-plugin/hooks/lib/health_check.py

@@ -246,11 +246,113 @@ def check_standalone_readiness(self) -> Dict[str, str]:
             )
         return _result("standalone_readiness", "WARN", f"Standalone not ready: {', '.join(issues)}")
 
+    # ------------------------------------------------------------------
+    # Check 11: HUD asset installation (#1490 prevention)
+    # ------------------------------------------------------------------
+    def check_hud_installation(self) -> Dict[str, str]:
+        """Verify HUD asset installation integrity.
+
+        Detects the v5.6.0/v5.6.1 failure mode where ``~/.claude/hud/lib``
+        is missing or stale and the statusLine renders only the
+        fallback ``◕‿◕ CodingBuddy`` face.
+
+        Performs three layers of verification:
+          1. Script presence at ``~/.claude/hud/codingbuddy-hud.py``
+          2. Lib directory presence + the seven critical modules:
+             ``hud_buddy``, ``hud_state``, ``hud_helpers``,
+             ``tiny_actor_presets``, ``hud_version``, ``hud_rate_limits``,
+             ``hud_layout``
+          3. A subprocess render smoke test that catches the case where
+             everything looks present but imports still fail at runtime
+             (e.g. permission issues, partial copy)
+        """
+        import subprocess
+
+        hud_dir = os.path.join(self._claude_dir, "hud")
+        script = os.path.join(hud_dir, "codingbuddy-hud.py")
+        lib = os.path.join(hud_dir, "lib")
+        stamp = os.path.join(hud_dir, ".version")
+
+        if not os.path.isfile(script):
+            return _result(
+                "hud_installation",
+                "FAIL",
+                "HUD script missing at ~/.claude/hud/codingbuddy-hud.py",
+            )
+
+        if not os.path.isdir(lib):
+            return _result(
+                "hud_installation",
+                "FAIL",
+                "HUD lib/ directory missing — statusLine renders fallback only",
+            )
+
+        required_modules = [
+            "hud_buddy.py",
+            "hud_state.py",
+            "hud_helpers.py",
+            "tiny_actor_presets.py",
+            "hud_version.py",
+            "hud_rate_limits.py",
+            "hud_layout.py",
+        ]
+        missing = [
+            m for m in required_modules if not os.path.isfile(os.path.join(lib, m))
+        ]
+        if missing:
+            return _result(
+                "hud_installation",
+                "FAIL",
+                f"HUD lib missing modules: {', '.join(missing)}",
+            )
+
+        # Subprocess render smoke — catches runtime import failures.
+        try:
+            r = subprocess.run(
+                ["python3", script],
+                input='{"session_id":"healthcheck","model":{"display_name":"Test"}}',
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if r.stdout.strip() == "◕‿◕ CodingBuddy":
+                return _result(
+                    "hud_installation",
+                    "FAIL",
+                    "HUD smoke test produced fallback face — lib import failing at runtime",
+                )
+        except subprocess.TimeoutExpired:
+            return _result(
+                "hud_installation",
+                "WARN",
+                "HUD smoke test timed out (5s)",
+            )
+        except Exception as e:
+            return _result(
+                "hud_installation",
+                "WARN",
+                f"HUD smoke test crashed: {e}",
+            )
+
+        version_msg = ""
+        if os.path.isfile(stamp):
+            try:
+                with open(stamp, "r", encoding="utf-8") as f:
+                    version_msg = f" (v{f.read().strip()})"
+            except OSError:
+                pass
+
+        return _result(
+            "hud_installation",
+            "PASS",
+            f"HUD assets installed and rendering full status line{version_msg}",
+        )
+
     # ------------------------------------------------------------------
     # Aggregate
     # ------------------------------------------------------------------
     def run_all(self) -> List[Dict[str, str]]:
-        """Run all 10 diagnostic checks and return results."""
+        """Run all 11 diagnostic checks and return results."""
         return [
             self.check_hooks_json(),
             self.check_hook_files(),
@@ -262,6 +364,7 @@ def run_all(self) -> List[Dict[str, str]]:
             self.check_mcp_connection(),
             self.check_runtime_mode(),
             self.check_standalone_readiness(),
+            self.check_hud_installation(),
         ]
 
     @staticmethod

packages/claude-code-plugin/tests/test_health_check.py

@@ -310,10 +310,10 @@ def test_missing_ai_rules_passes_with_fallback(self, env):
 class TestRunAll:
     """run_all() returns all 10 check results."""
 
-    def test_returns_10_results(self, env):
+    def test_returns_11_results(self, env):
         checker = _make_checker(env)
         results = checker.run_all()
-        assert len(results) == 10
+        assert len(results) == 11  # bumped from 10 in v5.6.2 (#1490)
 
     def test_each_check_has_required_keys(self, env):
         checker = _make_checker(env)
@@ -342,3 +342,111 @@ def test_format_report_shows_failures(self, env):
         results = checker.run_all()
         report = checker.format_report(results)
         assert "FAIL" in report
+
+
+# ============================================================================
+# v5.6.2 (#1490) — check_hud_installation diagnostic
+# ============================================================================
+
+
+HUD_REQUIRED_LIB_MODULES = [
+    "hud_buddy.py",
+    "hud_state.py",
+    "hud_helpers.py",
+    "tiny_actor_presets.py",
+    "hud_version.py",
+    "hud_rate_limits.py",
+    "hud_layout.py",
+]
+
+
+def _populate_minimal_hud(home: "os.PathLike", lib_modules=None) -> None:
+    """Populate ~/.claude/hud with a stub script and (optionally) lib stubs.
+
+    The stub script always prints the fallback face so the smoke test
+    has predictable output. Pass lib_modules=None to omit the lib dir.
+    """
+    from pathlib import Path
+    h = Path(home) / ".claude" / "hud"
+    h.mkdir(parents=True, exist_ok=True)
+    (h / "codingbuddy-hud.py").write_text(
+        "#!/usr/bin/env python3\nprint('\u25d5\u203f\u25d5 CodingBuddy')\n"
+    )
+    os.chmod(str(h / "codingbuddy-hud.py"), 0o755)
+    if lib_modules is not None:
+        lib = h / "lib"
+        lib.mkdir(exist_ok=True)
+        for name in lib_modules:
+            (lib / name).write_text(f"# {name} stub")
+
+
+class TestCheckHudInstallation:
+    """Check 11: HUD asset installation integrity (#1490)."""
+
+    def test_fail_when_script_missing(self, env):
+        checker = _make_checker(env)
+        # env fixture creates ~/.claude but no hud/ dir
+        result = checker.check_hud_installation()
+        assert result["status"] == "FAIL"
+        assert "script missing" in result["message"].lower()
+
+    def test_fail_when_lib_directory_missing(self, env):
+        _populate_minimal_hud(env, lib_modules=None)  # script only
+        checker = _make_checker(env)
+        result = checker.check_hud_installation()
+        assert result["status"] == "FAIL"
+        assert "lib/" in result["message"] or "lib" in result["message"].lower()
+
+    def test_fail_when_required_modules_missing(self, env):
+        # Create lib but only with a subset of modules
+        _populate_minimal_hud(env, lib_modules=["hud_buddy.py", "hud_state.py"])
+        checker = _make_checker(env)
+        result = checker.check_hud_installation()
+        assert result["status"] == "FAIL"
+        assert "missing modules" in result["message"]
+        # The specific missing names must be reported
+        assert "tiny_actor_presets.py" in result["message"]
+
+    def test_fail_when_smoke_test_returns_fallback(self, env):
+        # Populate everything but stub script always prints fallback
+        _populate_minimal_hud(env, lib_modules=HUD_REQUIRED_LIB_MODULES)
+        checker = _make_checker(env)
+        result = checker.check_hud_installation()
+        assert result["status"] == "FAIL"
+        assert "fallback" in result["message"].lower()
+
+    def test_pass_with_real_plugin_install(self, env, monkeypatch):
+        """End-to-end: install real HUD via _install_statusline, then check.
+
+        This is the green-path regression gate — if check_hud_installation
+        ever stops returning PASS for a freshly-installed real plugin,
+        we know either the installer or the diagnostic regressed.
+        """
+        from pathlib import Path
+        import importlib.util as importutil
+
+        # Bootstrap session-start.py import
+        repo_hooks = Path(__file__).resolve().parents[1] / "hooks"
+        real_hud_source = repo_hooks / "codingbuddy-hud.py"
+        if not real_hud_source.exists():
+            pytest.skip(f"real HUD source not found at {real_hud_source}")
+
+        spec = importutil.spec_from_file_location(
+            "session_start_for_health", str(repo_hooks / "session-start.py")
+        )
+        session_start = importutil.module_from_spec(spec)
+        spec.loader.exec_module(session_start)
+
+        # Force the installer to use the real source
+        monkeypatch.setattr(
+            session_start, "_find_hud_source", lambda: real_hud_source
+        )
+        settings_file = env / ".claude" / "settings.json"
+        session_start._install_statusline(env, settings_file)
+
+        checker = _make_checker(env)
+        result = checker.check_hud_installation()
+        assert result["status"] == "PASS", (
+            f"expected PASS, got {result}"
+        )
+        assert "rendering full status line" in result["message"]