fix(hud): sync hooks/lib in _install_statusline (#1490)

The v5.6.0 refactor extracted 11 hud_*.py modules + tiny_actor_presets
into hooks/lib/, but _install_statusline still ran a single shutil.copy
on codingbuddy-hud.py and never touched the sibling lib/ directory.

End-state on every upgraded user machine:
  ~/.claude/hud/codingbuddy-hud.py  ← updated
  ~/.claude/hud/lib/                 ← MISSING

The script tries `from hud_buddy import BUDDY_FACE` first; the
ImportError trips its outer try/except, which prints the bare
fallback `◕‿◕ CodingBuddy`. Every Wave 1/2/3 status line feature
shipped in v5.6.0 / v5.6.1 was therefore invisible to all users.

Fix:
  - Replace shutil.copy(...) with _atomic_sync_with_lib(source, hud_dir)
    so the script and the entire sibling lib/ are synced as a single
    unit on every session start.
  - Write ~/.claude/hud/.version stamp so health_check (next commit)
    can detect drift.
  - Honour CODINGBUDDY_HUD_DEBUG=1 to surface installer errors on
    stderr (default still silent so session start is never blocked).

Test coverage (test_session_start_hud.py):
  - TestSyncHudAssets (8 tests): copies all 12 required modules,
    excludes __pycache__/*.pyc/.pytest_cache/test_*.py, replaces
    stale renamed modules, idempotent re-invocation, writes version
    stamp, gracefully skips lib when absent, preserves settings.json
    update.
  - TestHudInstallE2ERegressionGate (4 parametrized scenarios):
    runs the installed script as a real subprocess and asserts the
    output is NOT '◕‿◕ CodingBuddy'. Scenarios cover clean install,
    partial (current v5.6.1 user state), stale lib (renamed module),
    and fresh idempotent re-run. This is the single regression gate
    that would have caught the v5.6.0 / v5.6.1 ship.

Total: 6 prior + 14 new = 20 statusline tests. All green.

Refs #1490

Author: JeremyDev87

packages/claude-code-plugin/hooks/session-start.py

@@ -620,19 +620,45 @@ def _find_hud_source() -> Optional[Path]:
 
 
 def _install_statusline(home: Path, settings_file: Path) -> None:
-    """Install codingbuddy statusLine (#1089)."""
-    # 1. Find and copy HUD script
+    """Install codingbuddy statusLine (#1089, fix #1490).
+
+    v5.6.2: now syncs ``hooks/lib`` alongside the script via
+    :func:`_atomic_sync_with_lib`. Previous versions only copied the
+    single ``codingbuddy-hud.py`` file, leaving ``~/.claude/hud/lib``
+    empty or stale. Once Wave 1/2/3 modules were extracted to
+    ``hooks/lib`` in v5.6.0 every statusLine import failed and the
+    outer ``try/except`` in ``codingbuddy-hud.py`` rendered only
+    ``◕‿◕ CodingBuddy``.
+
+    Set ``CODINGBUDDY_HUD_DEBUG=1`` to surface install errors on
+    stderr; without the env var, errors bubble to ``main()``'s outer
+    silent except so session start is never blocked.
+    """
+    # 1. Find HUD source
     source = _find_hud_source()
     if not source:
+        if os.environ.get("CODINGBUDDY_HUD_DEBUG"):
+            print("[hud] _install_statusline: source not found", file=sys.stderr)
         return
 
     hud_dir = home / ".claude" / "hud"
-    hud_dir.mkdir(parents=True, exist_ok=True)
-    target = hud_dir / HUD_FILENAME
-    shutil.copy(source, target)
-    target.chmod(0o755)
 
-    # 2. Update settings.json
+    # 2. Atomic sync (script + lib/) — replaces previous shutil.copy-only path
+    try:
+        _atomic_sync_with_lib(source, hud_dir)
+    except Exception as exc:
+        if os.environ.get("CODINGBUDDY_HUD_DEBUG"):
+            print(f"[hud] _atomic_sync_with_lib failed: {exc}", file=sys.stderr)
+        raise  # bubble to main()'s outer except
+
+    # 3. Write version stamp for health_check / diagnostics
+    try:
+        version = _get_plugin_version()
+        (hud_dir / ".version").write_text(version, encoding="utf-8")
+    except Exception:
+        pass  # stamp is best-effort
+
+    # 4. Update settings.json
     settings = _read_settings_file(settings_file) if settings_file.exists() else {}
 
     current_sl = settings.get("statusLine", {}).get("command", "")

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

@@ -1,7 +1,11 @@
-"""Tests for statusLine auto-install in session-start (#1089, #1092)."""
+"""Tests for statusLine auto-install in session-start (#1089, #1092, #1490)."""
 import json
 import os
+import shutil
+import subprocess
 import sys
+from pathlib import Path
+from unittest import mock
 
 import pytest
 
@@ -53,6 +57,80 @@ def hud_source(home_dir):
     return src
 
 
+# ----- v5.6.2 (#1490) fixtures -----
+
+
+HUD_REQUIRED_LIB_MODULES = [
+    "hud_buddy.py",
+    "hud_cache_savings.py",
+    "hud_context_bar.py",
+    "hud_helpers.py",
+    "hud_layout.py",
+    "hud_rainbow.py",
+    "hud_rate_limits.py",
+    "hud_session.py",
+    "hud_state.py",
+    "hud_velocity.py",
+    "hud_version.py",
+    "tiny_actor_presets.py",
+]
+
+
+@pytest.fixture
+def hud_source_with_lib(tmp_path):
+    """Synthetic HUD source dir with lib/ containing all 12 required modules."""
+    hooks = tmp_path / "src_hooks"
+    hooks.mkdir()
+    (hooks / "codingbuddy-hud.py").write_text("#!/usr/bin/env python3\nprint('stub')")
+    lib = hooks / "lib"
+    lib.mkdir()
+    for name in HUD_REQUIRED_LIB_MODULES:
+        (lib / name).write_text(f"# {name} stub")
+    return hooks / "codingbuddy-hud.py"
+
+
+@pytest.fixture
+def hud_source_with_lib_and_caches(tmp_path):
+    """HUD source with lib/ + __pycache__ + .pytest_cache + test_*.py."""
+    hooks = tmp_path / "src_hooks"
+    hooks.mkdir()
+    (hooks / "codingbuddy-hud.py").write_text("# stub")
+    lib = hooks / "lib"
+    lib.mkdir()
+    for name in HUD_REQUIRED_LIB_MODULES:
+        (lib / name).write_text(f"# {name} stub")
+    # Pollutants that must NOT be copied
+    pycache = lib / "__pycache__"
+    pycache.mkdir()
+    (pycache / "x.cpython-39.pyc").write_text("compiled")
+    (lib / "stale.pyc").write_text("compiled")
+    pcache = lib / ".pytest_cache"
+    pcache.mkdir()
+    (pcache / "v").write_text("cache")
+    (lib / "test_hud_buddy.py").write_text("def test_x(): pass")
+    return hooks / "codingbuddy-hud.py"
+
+
+@pytest.fixture
+def hud_source_no_lib(tmp_path):
+    """HUD source without sibling lib/."""
+    hooks = tmp_path / "src_hooks"
+    hooks.mkdir()
+    src = hooks / "codingbuddy-hud.py"
+    src.write_text("# stub")
+    return src
+
+
+@pytest.fixture
+def real_plugin_hud_source():
+    """Path to the real packages/claude-code-plugin/hooks/codingbuddy-hud.py.
+
+    Used by E2E render smoke tests — exercises the real import chain.
+    """
+    here = Path(__file__).resolve()
+    return here.parents[1] / "hooks" / "codingbuddy-hud.py"
+
+
 class TestInstallStatusline:
     def test_installs_hud_script_to_claude_hud_dir(self, home_dir, settings_file, hud_source, monkeypatch):
         monkeypatch.setenv("CLAUDE_PLUGIN_DIR", str(hud_source.parent.parent))
@@ -133,3 +211,231 @@ def test_returns_none_when_not_found(self, monkeypatch):
         # This may return None or a valid path depending on the test machine
         # Just verify it doesn't crash
         session_start._find_hud_source()
+
+
+# ============================================================================
+# v5.6.2 (#1490) — _install_statusline must sync hooks/lib alongside script.
+# Prior versions only ran shutil.copy on the script, leaving lib/ empty
+# or stale and causing every Wave 1/2/3 import to fall back to the
+# '◕‿◕ CodingBuddy' face.
+# ============================================================================
+
+
+class TestSyncHudAssets:
+    """Unit tests verifying _install_statusline now syncs the lib dir."""
+
+    def test_copies_lib_directory(
+        self, home_dir, settings_file, hud_source_with_lib, monkeypatch
+    ):
+        monkeypatch.setattr(
+            session_start, "_find_hud_source", lambda: hud_source_with_lib
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        target_lib = home_dir / ".claude" / "hud" / "lib"
+        assert target_lib.is_dir()
+
+    def test_copies_all_required_hud_modules(
+        self, home_dir, settings_file, hud_source_with_lib, monkeypatch
+    ):
+        monkeypatch.setattr(
+            session_start, "_find_hud_source", lambda: hud_source_with_lib
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        target_lib = home_dir / ".claude" / "hud" / "lib"
+        for name in HUD_REQUIRED_LIB_MODULES:
+            assert (target_lib / name).is_file(), f"missing {name} in target lib"
+
+    def test_excludes_pycache_pyc_pytest_cache_and_test_files(
+        self,
+        home_dir,
+        settings_file,
+        hud_source_with_lib_and_caches,
+        monkeypatch,
+    ):
+        monkeypatch.setattr(
+            session_start,
+            "_find_hud_source",
+            lambda: hud_source_with_lib_and_caches,
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        target_lib = home_dir / ".claude" / "hud" / "lib"
+        assert (target_lib / "hud_buddy.py").is_file()  # real module copied
+        assert not (target_lib / "__pycache__").exists()
+        assert not (target_lib / ".pytest_cache").exists()
+        assert not list(target_lib.glob("*.pyc"))
+        assert not list(target_lib.glob("test_*.py"))
+
+    def test_replaces_stale_lib_modules(
+        self, home_dir, settings_file, hud_source_with_lib, monkeypatch
+    ):
+        """A pre-existing renamed module from a prior version must be removed."""
+        target_lib = home_dir / ".claude" / "hud" / "lib"
+        target_lib.mkdir(parents=True)
+        (target_lib / "hud_obsolete_v5_5.py").write_text("# stale renamed module")
+        monkeypatch.setattr(
+            session_start, "_find_hud_source", lambda: hud_source_with_lib
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        assert not (target_lib / "hud_obsolete_v5_5.py").exists()
+        assert (target_lib / "hud_buddy.py").exists()
+
+    def test_idempotent_double_invocation(
+        self, home_dir, settings_file, hud_source_with_lib, monkeypatch
+    ):
+        monkeypatch.setattr(
+            session_start, "_find_hud_source", lambda: hud_source_with_lib
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        first = sorted(
+            p.name for p in (home_dir / ".claude" / "hud" / "lib").iterdir()
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        second = sorted(
+            p.name for p in (home_dir / ".claude" / "hud" / "lib").iterdir()
+        )
+        assert first == second
+
+    def test_writes_version_stamp(
+        self, home_dir, settings_file, hud_source_with_lib, monkeypatch
+    ):
+        monkeypatch.setattr(
+            session_start, "_find_hud_source", lambda: hud_source_with_lib
+        )
+        monkeypatch.setattr(
+            session_start, "_get_plugin_version", lambda: "5.6.2"
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        stamp = home_dir / ".claude" / "hud" / ".version"
+        assert stamp.exists()
+        assert stamp.read_text(encoding="utf-8") == "5.6.2"
+
+    def test_no_lib_in_source_silently_skips(
+        self, home_dir, settings_file, hud_source_no_lib, monkeypatch
+    ):
+        monkeypatch.setattr(
+            session_start, "_find_hud_source", lambda: hud_source_no_lib
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        assert (home_dir / ".claude" / "hud" / "codingbuddy-hud.py").exists()
+        assert not (home_dir / ".claude" / "hud" / "lib").exists()
+
+    def test_settings_still_updated_after_lib_sync(
+        self, home_dir, settings_file, hud_source_with_lib, monkeypatch
+    ):
+        """Lib sync must not regress the settings.json update behavior."""
+        monkeypatch.setattr(
+            session_start, "_find_hud_source", lambda: hud_source_with_lib
+        )
+        session_start._install_statusline(home_dir, settings_file)
+        data = json.loads(settings_file.read_text())
+        assert "codingbuddy-hud" in data["statusLine"]["command"]
+
+
+class TestHudInstallE2ERegressionGate:
+    """🔴 The single regression gate that would have caught v5.6.0/v5.6.1.
+
+    Simulates a user receiving cache 5.6.2 and starting a fresh Claude
+    Code session in 4 different starting states, then runs the installed
+    script as a real subprocess and asserts the output is NOT the
+    fallback face.
+
+    Scenarios:
+      - clean   : ~/.claude/hud absent
+      - partial : script present, lib absent (current v5.6.1 user state)
+      - stale   : lib has obsolete modules from a prior version
+      - fresh   : already populated by a prior install (idempotency)
+    """
+
+    @pytest.mark.parametrize("scenario", ["clean", "partial", "stale", "fresh"])
+    def test_install_then_render_full_status_line(
+        self, tmp_path, real_plugin_hud_source, scenario
+    ):
+        if not real_plugin_hud_source.exists():
+            pytest.skip(
+                f"real plugin source not found at {real_plugin_hud_source}"
+            )
+
+        # Build a fake "home" that mimics the user's machine.
+        home = tmp_path / "fake_home"
+        home.mkdir()
+        settings_file = home / ".claude" / "settings.json"
+        settings_file.parent.mkdir(parents=True)
+        settings_file.write_text("{}")
+
+        hud_dir = home / ".claude" / "hud"
+
+        if scenario == "partial":
+            # Mimic v5.6.1 user: script present, lib absent.
+            hud_dir.mkdir(parents=True)
+            shutil.copy(real_plugin_hud_source, hud_dir / "codingbuddy-hud.py")
+        elif scenario == "stale":
+            hud_dir.mkdir(parents=True)
+            shutil.copy(real_plugin_hud_source, hud_dir / "codingbuddy-hud.py")
+            stale_lib = hud_dir / "lib"
+            stale_lib.mkdir()
+            (stale_lib / "hud_obsolete_v5_5.py").write_text("# stale")
+        elif scenario == "fresh":
+            # Pre-populate by running the installer once.
+            with mock.patch.object(
+                session_start,
+                "_find_hud_source",
+                return_value=real_plugin_hud_source,
+            ):
+                session_start._install_statusline(home, settings_file)
+
+        # The actual install under test
+        with mock.patch.object(
+            session_start,
+            "_find_hud_source",
+            return_value=real_plugin_hud_source,
+        ):
+            session_start._install_statusline(home, settings_file)
+
+        installed_script = hud_dir / "codingbuddy-hud.py"
+        installed_lib = hud_dir / "lib"
+
+        # Post-condition: script + lib + 12 modules
+        assert installed_script.exists()
+        assert installed_lib.is_dir()
+        for name in HUD_REQUIRED_LIB_MODULES:
+            assert (installed_lib / name).exists(), (
+                f"scenario={scenario}: missing {name} in target lib"
+            )
+        # Stale module gone
+        if scenario == "stale":
+            assert not (installed_lib / "hud_obsolete_v5_5.py").exists()
+
+        # 🔴 The render gate
+        stdin_payload = json.dumps(
+            {
+                "session_id": "regression-gate",
+                "model": {"display_name": "Opus 4.6"},
+                "cost": {
+                    "total_cost_usd": 0.42,
+                    "total_duration_ms": 120000,
+                },
+            }
+        )
+        result = subprocess.run(
+            ["python3", str(installed_script)],
+            input=stdin_payload,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        assert result.returncode == 0, (
+            f"scenario={scenario} crashed: stderr={result.stderr!r}"
+        )
+        out = result.stdout
+
+        assert out.strip() != "◕‿◕ CodingBuddy", (
+            f"FALLBACK FACE REGRESSION (#1490) — scenario={scenario}\n"
+            f"stdout: {out!r}\n"
+            f"stderr: {result.stderr!r}\n"
+            f"installed lib contents: "
+            f"{sorted(p.name for p in installed_lib.iterdir())}"
+        )
+
+        assert "CB v" in out, f"version segment missing: {out!r}"
+        assert "Opus 4.6" in out, f"model segment missing: {out!r}"
+        assert "$0.42" in out, f"cost segment missing: {out!r}"