fix(hud): version resolution fallback to plugin.json (Wave 1-A)

Resolves the stale version display bug ("shows v5.2.0 when actual is
v5.5.0") by adding a deterministic tier-2 fallback that reads
.claude-plugin/plugin.json via __file__-relative path.

- hud_version.get_fresh_version gains plugin_json_file parameter:
  * None (default): tier-2 disabled, preserves backcompat
  * "": enables dev-install default path (production)
  * non-empty: test override
- _default_plugin_json_path() + _read_local_plugin_json() helpers
- format_status_line accepts plugin_json_file passthrough
- main() passes plugin_json_file="" to enable Wave 1-A in production
- 7 new tests for fallback ordering, malformed files, default path
- 162/162 tests pass (133 Golden Rule + 29 version/Wave 0)

Closes #1466
Part of #1464 (Wave 0 statusbar refactor)

Author: JeremyDev87

packages/claude-code-plugin/hooks/codingbuddy-hud.py

@@ -14,6 +14,7 @@
 import os
 import sys
 from datetime import datetime, timezone
+from typing import Optional
 
 # --- lib import bootstrap ---
 # statusLine entry script: sys.path insertion here is intentional so
@@ -42,8 +43,15 @@ def format_rate_limits(stdin_data: dict) -> str:  # type: ignore[misc]
     from hud_version import get_fresh_version as _get_fresh_version  # backcompat alias
 except Exception:  # pragma: no cover - defensive
     def _get_fresh_version(  # type: ignore[misc]
-        hud_state: dict, *, plugins_file: str = ""
+        hud_state: dict,
+        *,
+        plugins_file: str = "",
+        plugin_json_file: Optional[str] = None,
     ) -> str:
+        # Signature must stay in sync with hud_version.get_fresh_version
+        # (see Wave 1-A PR #1467 review — HIGH finding H1). When this
+        # stub is active, hud_version is unavailable so tier-2 cannot
+        # be honoured regardless of the kwarg value; accept and ignore.
         return hud_state.get("version", "")
 
 # Agent eye glyphs from .ai-rules agent definitions.
@@ -411,17 +419,30 @@ def format_status_line(
     active_agent: str = "",
     *,
     plugins_file: str = "",
+    plugin_json_file: Optional[str] = None,
 ) -> str:
     """Format the statusLine output.
 
     Fallback order per field:
-      version  → installed_plugins.json > hud-state.version
+      version  → installed_plugins.json > plugin.json > hud-state.version
       cost     → stdin cost.total_cost_usd  > estimate_cost()
       duration → stdin cost.total_duration_ms > hud-state sessionStartTimestamp
       agent    → stdin agent.name > hud_state.activeAgent > active_agent param
       model    → stdin model.display_name > model.id
+
+    Args:
+        plugin_json_file: Wave 1-A control for the local ``plugin.json``
+            fallback. ``None`` (default) disables tier-2 — matches the
+            hud_version contract for backwards compatibility. ``""``
+            enables the dev-install default path. A non-empty string
+            overrides the path for tests. ``main()`` passes ``""`` in
+            production so statusLine always reflects a fresh version.
     """
-    version = _get_fresh_version(hud_state, plugins_file=plugins_file)
+    version = _get_fresh_version(
+        hud_state,
+        plugins_file=plugins_file,
+        plugin_json_file=plugin_json_file,
+    )
     mode = hud_state.get("currentMode")
     mode_label = mode if mode else "Ready"
 
@@ -482,7 +503,12 @@ def main():
 
         env_agent = os.environ.get("CODINGBUDDY_ACTIVE_AGENT", "")
 
-        output = format_status_line(stdin_data, hud_state, env_agent)
+        # Pass plugin_json_file="" to enable Wave 1-A dev-install
+        # plugin.json fallback. Tests opt out by omitting this kwarg
+        # and relying on the Optional[str]=None default.
+        output = format_status_line(
+            stdin_data, hud_state, env_agent, plugin_json_file=""
+        )
         print(output)
     except Exception:
         print(f"{BUDDY_FACE} CodingBuddy")

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

@@ -1,48 +1,96 @@
-"""Version resolution for CodingBuddy statusLine (#1326).
+"""Version resolution for CodingBuddy statusLine (#1326, #1464 Wave 1-A).
 
-Wave 0 extracts the plugin-version fallback logic from
-``codingbuddy-hud.py`` so Wave 1-A can extend the resolution chain
-without touching the monolith.
+Wave 1-A strengthens the version resolution chain with a local
+``plugin.json`` fallback so the HUD never shows a stale snapshot after
+a plugin update even when ``installed_plugins.json`` is missing or
+cannot be parsed.
 
 The public entry point is :func:`get_fresh_version`. ``codingbuddy-hud``
 calls it internally from ``format_status_line``; callers pass the
-current ``hud_state`` dict and an optional ``plugins_file`` override
-used by the test-suite to point at a fixture path.
+current ``hud_state`` dict and optional path overrides used by tests.
 
-Behavior-preserving contract (mirrors the original monolith helper):
+Resolution chain (first non-empty result wins):
 
-1. Attempt to read the freshest version from
-   ``installed_plugins.json`` via
-   :func:`hud_helpers.read_installed_version`.
-2. On success, return that value.
-3. On any failure (missing file, parse error, unexpected exception),
-   fall back to ``hud_state.get("version", "")``.
+1. ``installed_plugins.json`` — authoritative after ``/plugin update``
+   (global Claude Code plugin registry).
+2. ``../.claude-plugin/plugin.json`` — deterministic via ``__file__``
+   relative path, authoritative for dev installs where the plugin is
+   running from a git checkout.
+3. ``hud_state.get("version", "")`` — snapshot written at session
+   start (may be stale, last resort).
 """
 from __future__ import annotations
 
-from typing import Any, Dict
+import json
+import os
+from typing import Any, Dict, Optional
+
+
+def _default_plugin_json_path() -> str:
+    """Resolve ``plugin.json`` relative to this module's location.
+
+    ``hud_version.py`` lives at
+    ``packages/claude-code-plugin/hooks/lib/hud_version.py``.
+    ``plugin.json`` lives at
+    ``packages/claude-code-plugin/.claude-plugin/plugin.json``.
+    So we walk up two levels (``lib/`` -> ``hooks/`` -> package root)
+    and then descend into ``.claude-plugin/``.
+    """
+    here = os.path.dirname(os.path.abspath(__file__))
+    return os.path.normpath(
+        os.path.join(here, "..", "..", ".claude-plugin", "plugin.json")
+    )
+
+
+def _read_local_plugin_json(path: str) -> str:
+    """Read ``plugin.json`` and return its ``version`` field.
+
+    Returns an empty string on any failure (missing file, parse error,
+    missing key). Never raises — caller must be able to skip silently.
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        v = data.get("version")
+        return v if isinstance(v, str) else ""
+    except Exception:
+        return ""
 
 
 def get_fresh_version(
     hud_state: Dict[str, Any],
     *,
     plugins_file: str = "",
+    plugin_json_file: Optional[str] = None,
 ) -> str:
     """Return the freshest known plugin version string.
 
     Args:
-        hud_state: Current HUD state dict (supplies the fallback
+        hud_state: Current HUD state dict (supplies the final fallback
             ``version`` field).
         plugins_file: Optional override for the
             ``installed_plugins.json`` path, used by tests.
+        plugin_json_file: Local ``plugin.json`` fallback control:
+
+            * ``None`` (default) — tier-2 fallback is **disabled**.
+              Only ``installed_plugins.json`` and ``hud_state`` are
+              consulted. This keeps the signature backwards-compatible
+              with callers that do not opt in.
+            * ``""`` — use the default dev-install path resolved from
+              ``__file__`` (i.e. ``../.claude-plugin/plugin.json``).
+              ``format_status_line`` passes this in production so
+              statusLine always reflects a fresh local version.
+            * non-empty string — treat as an explicit file path
+              override, used by the test suite for fixture files.
 
     Notes:
         ``hud_helpers`` is imported lazily inside the function body to
         preserve the hot-path resilience of the original monolith. If
         ``hud_helpers`` is temporarily broken (e.g. mid-wave refactor),
-        the statusLine still renders via the ``hud_state`` fallback
-        instead of crashing at module load.
+        the statusLine still renders via the later fallbacks instead
+        of crashing at module load.
     """
+    # 1. Global installed_plugins.json (authoritative after /plugin update)
     try:
         from hud_helpers import read_installed_version  # lazy for resilience
         kwargs = {"plugins_file": plugins_file} if plugins_file else {}
@@ -51,4 +99,13 @@ def get_fresh_version(
             return fresh
     except Exception:
         pass
+
+    # 2. Local plugin.json (opt-in: None disables this tier entirely)
+    if plugin_json_file is not None:
+        path_to_try = plugin_json_file or _default_plugin_json_path()
+        local = _read_local_plugin_json(path_to_try)
+        if local:
+            return local
+
+    # 3. hud-state snapshot (may be stale, last resort)
     return hud_state.get("version", "")

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

@@ -44,6 +44,104 @@ def test_reads_installed_plugins_file_when_present(tmp_path):
     assert result == "7.7.7"
 
 
+def test_plugin_json_fallback_when_installed_plugins_missing(tmp_path):
+    """Wave 1-A: plugin.json is the second-tier fallback.
+
+    When installed_plugins.json is missing but a local plugin.json
+    exists, the returned version must be the plugin.json value.
+    """
+    missing_plugins = tmp_path / "no_plugins.json"
+    plugin_json = tmp_path / "plugin.json"
+    plugin_json.write_text('{"version": "8.8.8"}', encoding="utf-8")
+    result = hud_version.get_fresh_version(
+        {"version": "stale"},
+        plugins_file=str(missing_plugins),
+        plugin_json_file=str(plugin_json),
+    )
+    assert result == "8.8.8"
+
+
+def test_installed_plugins_wins_over_plugin_json(tmp_path):
+    """Wave 1-A: installed_plugins.json (tier 1) beats plugin.json (tier 2)."""
+    plugins = tmp_path / "installed_plugins.json"
+    plugins.write_text(
+        '{"plugins": {"codingbuddy@dev": [{"version": "tier-1"}]}}',
+        encoding="utf-8",
+    )
+    plugin_json = tmp_path / "plugin.json"
+    plugin_json.write_text('{"version": "tier-2"}', encoding="utf-8")
+    result = hud_version.get_fresh_version(
+        {"version": "tier-3"},
+        plugins_file=str(plugins),
+        plugin_json_file=str(plugin_json),
+    )
+    assert result == "tier-1"
+
+
+def test_plugin_json_beats_hud_state(tmp_path):
+    """Wave 1-A: plugin.json (tier 2) beats hud_state.version (tier 3)."""
+    missing_plugins = tmp_path / "no_plugins.json"
+    plugin_json = tmp_path / "plugin.json"
+    plugin_json.write_text('{"version": "tier-2"}', encoding="utf-8")
+    result = hud_version.get_fresh_version(
+        {"version": "tier-3-stale"},
+        plugins_file=str(missing_plugins),
+        plugin_json_file=str(plugin_json),
+    )
+    assert result == "tier-2"
+
+
+def test_all_fallbacks_fail_returns_hud_state_version(tmp_path):
+    """Wave 1-A: if both files are absent, fall through to hud_state."""
+    missing_plugins = tmp_path / "no_plugins.json"
+    missing_plugin_json = tmp_path / "no_plugin.json"
+    result = hud_version.get_fresh_version(
+        {"version": "9.9.9"},
+        plugins_file=str(missing_plugins),
+        plugin_json_file=str(missing_plugin_json),
+    )
+    assert result == "9.9.9"
+
+
+def test_plugin_json_malformed_skipped(tmp_path):
+    """Wave 1-A: malformed plugin.json must not crash — skip to hud_state."""
+    missing_plugins = tmp_path / "no_plugins.json"
+    bad_plugin_json = tmp_path / "plugin.json"
+    bad_plugin_json.write_text("this is not json", encoding="utf-8")
+    result = hud_version.get_fresh_version(
+        {"version": "fallback"},
+        plugins_file=str(missing_plugins),
+        plugin_json_file=str(bad_plugin_json),
+    )
+    assert result == "fallback"
+
+
+def test_plugin_json_missing_version_key_skipped(tmp_path):
+    """Wave 1-A: plugin.json without version key skips to hud_state."""
+    missing_plugins = tmp_path / "no_plugins.json"
+    plugin_json = tmp_path / "plugin.json"
+    plugin_json.write_text('{"name": "codingbuddy"}', encoding="utf-8")
+    result = hud_version.get_fresh_version(
+        {"version": "fallback"},
+        plugins_file=str(missing_plugins),
+        plugin_json_file=str(plugin_json),
+    )
+    assert result == "fallback"
+
+
+def test_default_plugin_json_path_resolves_to_real_file():
+    """Wave 1-A: __file__-relative default path must point at the real
+    .claude-plugin/plugin.json in the repo so dev installs work."""
+    import pathlib
+    path = hud_version._default_plugin_json_path()
+    assert os.path.isfile(path), (
+        f"Expected plugin.json at {path}; hud_version default path is wrong."
+    )
+    # Smoke check: the file is parseable and has a version field
+    version = hud_version._read_local_plugin_json(path)
+    assert version, "plugin.json exists but version field is empty"
+
+
 def test_import_does_not_read_real_plugins_file(monkeypatch, tmp_path):
     """Lock: module load must not touch ~/.claude/plugins/installed_plugins.json."""
     fake_home = tmp_path / "fake_home"