plugin-scanner 2.0.586__tar.gz → 2.0.588__tar.gz

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.586
+Version: 2.0.588
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/hol-guard
 Project-URL: Repository, https://github.com/hashgraph-online/hol-guard

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.586"
+version = "2.0.588"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.586"
+version = "2.0.588"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/src/codex_plugin_scanner/guard/aibom_cli.py

@@ -141,6 +141,9 @@ def build_aibom_export_payload(
 
 
 _AIBOM_AUTO_SYNC_INTERVAL_SECONDS = 60 * 60
+_AIBOM_EMPTY_SYNC_RETRY_SECONDS = 5 * 60
+_AIBOM_GUARD_EVENTS_BACKOFF_KEY = "aibom_guard_events_backoff"
+_AIBOM_GUARD_EVENTS_BACKOFF_HOURS = 24
 
 
 def _aware_utc_timestamp(value: str) -> datetime:
@@ -161,18 +164,37 @@ def _aibom_sync_is_due(
         return True
     if prior.get("synced") is not True:
         return True
-    if prior.get("snapshots") == 0:
-        return True
     synced_at = prior.get("synced_at")
     if not isinstance(synced_at, str) or not synced_at.strip():
         return True
+    retry_interval = min_interval_seconds
+    if prior.get("snapshots") == 0:
+        retry_interval = min(min_interval_seconds, _AIBOM_EMPTY_SYNC_RETRY_SECONDS)
     try:
         last_sync = _aware_utc_timestamp(synced_at)
         now = _aware_utc_timestamp(generated_at)
         elapsed = (now - last_sync).total_seconds()
     except (ValueError, OverflowError, TypeError):
         return True
-    return elapsed >= min_interval_seconds
+    return elapsed >= retry_interval
+
+
+def _aibom_guard_events_endpoint_unavailable_recently(store: GuardStore) -> bool:
+    from datetime import timedelta
+
+    summary = store.get_sync_payload(_AIBOM_GUARD_EVENTS_BACKOFF_KEY)
+    if not isinstance(summary, dict):
+        return False
+    if summary.get("sync_reason") != "guard_events_endpoint_unavailable":
+        return False
+    synced_at = summary.get("synced_at")
+    if not isinstance(synced_at, str) or not synced_at.strip():
+        return False
+    try:
+        parsed = _aware_utc_timestamp(synced_at)
+    except (ValueError, OverflowError, TypeError):
+        return False
+    return datetime.now(timezone.utc) - parsed < timedelta(hours=_AIBOM_GUARD_EVENTS_BACKOFF_HOURS)
 
 
 def _resolve_operator_home_dir(home_dir: Path | None = None) -> Path:
@@ -194,14 +216,11 @@ def sync_aibom_snapshots_if_due(
     home_dir: Path | None = None,
     workspace_dir: Path | None = None,
 ) -> dict[str, object]:
-    from .runtime.runner import (
-        GuardSyncNotConfiguredError,
-        _guard_events_endpoint_unavailable_recently,
-    )
+    from .runtime.runner import GuardSyncNotConfiguredError
 
     if store.get_cloud_workspace_id() is None:
         return {"synced": False, "skipped": True, "reason": "not_configured"}
-    if _guard_events_endpoint_unavailable_recently(store):
+    if _aibom_guard_events_endpoint_unavailable_recently(store):
         return {
             "synced": False,
             "skipped": True,
@@ -301,7 +320,7 @@ def sync_aibom_snapshots(
         if error.code == 404:
             synced_at = generated_at
             store.set_sync_payload(
-                "guard_events_v1_summary",
+                _AIBOM_GUARD_EVENTS_BACKOFF_KEY,
                 {
                     "synced_at": synced_at,
                     "events": 0,

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/src/codex_plugin_scanner/guard/cli/update_commands.py

@@ -133,13 +133,16 @@ def run_guard_update(
         resulting_version,
     )
     payload["status"] = _success_status(payload)
-    payload["changed"] = payload["status"] == "updated"
+    payload["changed"] = _version_changed(current_version, resulting_version) or payload["status"] == "updated"
+    stale_retry_command = _stale_retry_command(payload)
+    if stale_retry_command:
+        payload["retry_command"] = stale_retry_command
     payload["message"] = _success_message(
         status=str(payload["status"]),
         current_version=current_version,
         resulting_version=resulting_version,
         version_check=payload.get("version_check"),
-        retry_command=_stale_retry_command(payload),
+        retry_command=stale_retry_command,
     )
     notes = _success_notes(payload)
     if notes:
@@ -157,8 +160,8 @@ def run_guard_update(
         payload["managed_installs"] = repaired_installs
         if len(repaired_installs) == 1:
             payload["managed_install"] = repaired_installs[0]
-    # Sync dashboard static assets after package update so the daemon serves fresh UI.
-    if not dry_run and payload.get("status") in {"updated", "current"}:
+    # Sync dashboard assets when the package changed, even if the install still trails PyPI.
+    if not dry_run and (payload.get("status") in {"updated", "current"} or payload.get("changed") is True):
         dashboard_sync = _sync_dashboard_assets()
         if dashboard_sync:
             payload["dashboard_sync"] = dashboard_sync
@@ -248,12 +251,20 @@ def _success_status(payload: dict[str, object]) -> str:
 
 
 def _is_stale_install(payload: dict[str, object]) -> bool:
-    if payload.get("vcs_install") is None and payload.get("upgrade_source") != "pypi":
-        return False
     version_check = payload.get("version_check")
     return isinstance(version_check, dict) and version_check.get("update_available") is True
 
 
+def _version_changed(current_version: str, resulting_version: str) -> bool:
+    return (
+        bool(current_version)
+        and bool(resulting_version)
+        and current_version != "unknown"
+        and resulting_version != "unknown"
+        and current_version != resulting_version
+    )
+
+
 def _merge_version_checks(
     initial_version_check: object,
     post_version_check: object,
@@ -285,7 +296,8 @@ def _merge_version_checks(
 
 
 def _stale_retry_command(payload: dict[str, object]) -> str:
-    if payload.get("vcs_install") is not None or payload.get("upgrade_source") == "pypi":
+    version_check = payload.get("version_check")
+    if isinstance(version_check, dict) and version_check.get("update_available") is True:
         installer = str(payload.get("installer") or "pip")
         return _shell_command(_update_command(installer, use_pypi=True))
     retry_command = payload.get("retry_command")
@@ -313,10 +325,7 @@ def _success_message(
                 latest_version = latest.strip()
         installed_version = resulting_version or current_version
         if latest_version and installed_version not in {"", "unknown"}:
-            message = (
-                f"HOL Guard {installed_version} is behind PyPI {latest_version}. "
-                "The installed package source is not tracking PyPI releases."
-            )
+            message = f"HOL Guard {installed_version} is behind PyPI {latest_version} after the update attempt."
         else:
             message = "HOL Guard is behind the latest PyPI release."
         if retry_command:

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/src/codex_plugin_scanner/guard/store.py

@@ -151,6 +151,8 @@ _GUARD_CLOUD_RESET_STATE_KEYS = (
     "alert_preferences",
     "team_policy_pack",
     "guard_events_v1_summary",
+    "aibom_guard_events_backoff",
+    "aibom_sync_summary",
     "runtime_session_summary",
     "supply_chain_bundle_summary",
     "supply_chain_bundle_entitlement",

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/src/codex_plugin_scanner/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for tool version."""
 
-__version__ = "2.0.586"
+__version__ = "2.0.588"

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/tests/test_guard_aibom_cli.py

@@ -227,6 +227,123 @@ def test_sync_aibom_snapshots_if_due_skips_recent_sync(tmp_path: Path, monkeypat
     assert summary.get("reason") == "recently_synced"
 
 
+def test_sync_aibom_snapshots_if_due_skips_recent_empty_sync(tmp_path: Path, monkeypatch) -> None:
+    from codex_plugin_scanner.guard.aibom_cli import sync_aibom_snapshots_if_due
+
+    store = GuardStore(tmp_path / "guard")
+    monkeypatch.setattr(store, "get_cloud_workspace_id", lambda: "workspace-1")
+    now = "2026-06-10T12:03:00+00:00"
+    store.set_sync_payload(
+        "aibom_sync_summary",
+        {
+            "synced": True,
+            "synced_at": "2026-06-10T12:00:00+00:00",
+            "snapshots": 0,
+            "accepted": 0,
+        },
+        "2026-06-10T12:00:00+00:00",
+    )
+
+    summary = sync_aibom_snapshots_if_due(store, generated_at=now)
+
+    assert summary.get("skipped") is True
+    assert summary.get("reason") == "recently_synced"
+
+
+def test_sync_aibom_snapshots_if_due_retries_empty_sync_after_interval(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    from codex_plugin_scanner.guard import aibom_cli
+    from codex_plugin_scanner.guard.aibom_cli import sync_aibom_snapshots_if_due
+
+    store = GuardStore(tmp_path / "guard")
+    monkeypatch.setattr(store, "get_cloud_workspace_id", lambda: "workspace-1")
+    calls: list[str] = []
+
+    def _fake_sync(*_args, **_kwargs):
+        calls.append("sync")
+        return {"synced": True, "synced_at": "2026-06-10T12:06:00+00:00", "snapshots": 1, "accepted": 1}
+
+    monkeypatch.setattr(aibom_cli, "sync_aibom_snapshots", _fake_sync)
+    store.set_sync_payload(
+        "aibom_sync_summary",
+        {
+            "synced": True,
+            "synced_at": "2026-06-10T12:00:00+00:00",
+            "snapshots": 0,
+            "accepted": 0,
+        },
+        "2026-06-10T12:00:00+00:00",
+    )
+
+    summary = sync_aibom_snapshots_if_due(store, generated_at="2026-06-10T12:06:00+00:00")
+
+    assert calls == ["sync"]
+    assert summary.get("synced") is True
+
+
+def test_sync_aibom_snapshots_404_backoff_isolated_from_guard_events_summary(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    import urllib.error
+
+    from codex_plugin_scanner.guard import aibom_cli
+    from codex_plugin_scanner.guard.adapters.base import HarnessContext
+    from codex_plugin_scanner.guard.aibom_cli import sync_aibom_snapshots
+    from codex_plugin_scanner.guard.inventory_contract import GuardAgentInventorySnapshot
+    from codex_plugin_scanner.guard.runtime import runner
+
+    store = GuardStore(tmp_path / "guard")
+    monkeypatch.setattr(store, "get_cloud_workspace_id", lambda: "workspace-1")
+    store.set_sync_payload(
+        "guard_events_v1_summary",
+        {"synced_at": "2026-06-10T11:00:00+00:00", "events": 12, "accepted": 12},
+        "2026-06-10T11:00:00+00:00",
+    )
+    snapshot = GuardAgentInventorySnapshot(
+        snapshot_id="cursor-proof",
+        agent_id="cursor:local",
+        agent_type="cursor",
+        generated_at="2026-06-10T12:00:00+00:00",
+        runtime_version="test",
+    )
+    monkeypatch.setattr(aibom_cli, "collect_aibom_snapshots", lambda *_args, **_kwargs: (snapshot,))
+
+    def _raise_404(*_args, **_kwargs):
+        raise urllib.error.HTTPError(
+            url="https://hol.test/api/v1/guard/events",
+            code=404,
+            msg="Not Found",
+            hdrs=None,
+            fp=None,
+        )
+
+    monkeypatch.setattr(runner, "_urlopen_json_with_timeout_retry", _raise_404)
+    monkeypatch.setattr(runner, "_guard_events_sync_url", lambda url: url)
+    monkeypatch.setattr(runner, "_guard_sync_request", lambda *_args, **_kwargs: object())
+
+    summary = sync_aibom_snapshots(
+        store,
+        HarnessContext(home_dir=tmp_path / "home", workspace_dir=tmp_path / "workspace", guard_home=store.guard_home),
+        generated_at="2026-06-10T12:00:00+00:00",
+        auth_context={
+            "sync_url": "https://hol.test/api/v1/guard/events",
+            "token": "test-token",
+        },
+    )
+
+    guard_events_summary = store.get_sync_payload("guard_events_v1_summary")
+    aibom_backoff = store.get_sync_payload("aibom_guard_events_backoff")
+
+    assert summary.get("reason") == "guard_events_endpoint_unavailable"
+    assert isinstance(guard_events_summary, dict)
+    assert guard_events_summary.get("events") == 12
+    assert isinstance(aibom_backoff, dict)
+    assert aibom_backoff.get("sync_reason") == "guard_events_endpoint_unavailable"
+
+
 def test_aibom_export_json_includes_redaction_report(tmp_path: Path, capsys) -> None:
     home_dir = tmp_path / "home"
     workspace_dir = tmp_path / "workspace"

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/tests/test_guard_cli.py

@@ -3760,6 +3760,7 @@ args = ["workspace-skill.js", "--changed"]
         monkeypatch.setattr(guard_update_commands_module.sys, "executable", "/opt/guard-venv/bin/python")
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.18")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.18")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -3782,6 +3783,7 @@ args = ["workspace-skill.js", "--changed"]
         monkeypatch.setattr(guard_update_commands_module.sys, "prefix", "/mock-home/.local/pipx/venvs/hol-guard")
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.18")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.18")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -3850,6 +3852,7 @@ args = ["workspace-skill.js", "--changed"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "unknown")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.36")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.36")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -3981,6 +3984,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -4018,6 +4022,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -4056,6 +4061,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -4093,6 +4099,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -4128,6 +4135,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -4171,6 +4179,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
 
         rc = main(["guard", "update", "--home", str(home_dir), "--json"])
         output = json.loads(capsys.readouterr().out)
@@ -4213,6 +4222,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
         monkeypatch.setattr(
             guard_update_commands_module,
             "apply_managed_install",
@@ -4255,6 +4265,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
         original_get_managed_install = GuardStore.get_managed_install
         lookup_calls: list[str] = []
 
@@ -4311,6 +4322,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
         original_get_managed_install = GuardStore.get_managed_install
         lookup_calls: list[str] = []
 
@@ -4356,6 +4368,7 @@ args = ["-lc", "echo hi"]
         monkeypatch.setattr(guard_update_commands_module, "_direct_url_payload", lambda: None)
         monkeypatch.setattr(guard_update_commands_module, "_current_version", lambda: "2.0.39")
         monkeypatch.setattr(guard_update_commands_module, "_current_version_from_subprocess", lambda: "2.0.39")
+        monkeypatch.setattr(guard_update_commands_module, "_latest_version_from_pypi", lambda: "2.0.39")
         original_get_managed_install = GuardStore.get_managed_install
         lookup_calls: list[str] = []
 

{plugin_scanner-2.0.586 → plugin_scanner-2.0.588}/tests/test_guard_phase03_local_install.py

@@ -121,7 +121,7 @@ def test_update_binary_diagnostics_treats_pipx_shim_as_healthy(monkeypatch: pyte
     monkeypatch.setattr(
         update_commands.shutil,
         "which",
-        lambda name: "/Users/test/.local/bin/hol-guard" if name == "hol-guard" else None,
+        lambda name: "/mock-home/.local/bin/hol-guard" if name == "hol-guard" else None,
     )
 
     payload, exit_code = update_commands.run_guard_update(dry_run=True)
@@ -144,7 +144,7 @@ def test_update_skips_existing_local_source_install(monkeypatch: pytest.MonkeyPa
     monkeypatch.setattr(
         update_commands.shutil,
         "which",
-        lambda name: "/Users/test/.local/bin/hol-guard" if name == "hol-guard" else None,
+        lambda name: "/mock-home/.local/bin/hol-guard" if name == "hol-guard" else None,
     )
 
     payload, exit_code = update_commands.run_guard_update(dry_run=False)
@@ -171,7 +171,7 @@ def test_update_repairs_missing_pipx_local_source_install(monkeypatch: pytest.Mo
     monkeypatch.setattr(
         update_commands.shutil,
         "which",
-        lambda name: "/Users/test/.local/bin/hol-guard" if name == "hol-guard" else None,
+        lambda name: "/mock-home/.local/bin/hol-guard" if name == "hol-guard" else None,
     )
 
     captured_commands: list[list[str]] = []
@@ -299,10 +299,74 @@ def test_update_marks_partial_pypi_repair_as_stale(monkeypatch: pytest.MonkeyPat
 
     assert exit_code == 0
     assert payload["status"] == "stale"
+    assert payload["changed"] is True
     assert payload["resulting_version"] == "2.0.400"
     assert "behind PyPI 2.0.489" in str(payload["message"])
 
 
+def test_update_syncs_dashboard_assets_after_partial_stale_upgrade(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(update_commands, "_current_version", lambda: "2.0.345")
+    monkeypatch.setattr(update_commands, "_current_version_from_subprocess", lambda: "2.0.400")
+    monkeypatch.setattr(update_commands, "_latest_version_from_pypi", lambda: "2.0.489")
+    monkeypatch.setattr(update_commands, "_direct_url_payload", lambda: None)
+    monkeypatch.setattr(update_commands, "_installer_kind", lambda: "pipx")
+    monkeypatch.setattr(
+        update_commands.shutil,
+        "which",
+        lambda name: "/mock-home/.local/bin/hol-guard" if name == "hol-guard" else None,
+    )
+    monkeypatch.setattr(update_commands, "_sync_dashboard_assets", lambda: {"notes": ["synced dashboard"]})
+
+    def fake_run(command: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        assert command == ["pipx", "upgrade", "hol-guard"]
+        return subprocess.CompletedProcess(command, 0, "installed hol-guard 2.0.400", "")
+
+    monkeypatch.setattr(update_commands.subprocess, "run", fake_run)
+
+    payload, exit_code = update_commands.run_guard_update(dry_run=False)
+
+    assert exit_code == 0
+    assert payload["status"] == "stale"
+    assert payload["changed"] is True
+    assert payload["dashboard_sync"] == {"notes": ["synced dashboard"]}
+    assert "synced dashboard" in payload["notes"]
+
+
+def test_update_marks_plain_pipx_upgrade_as_stale_when_version_does_not_change(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(update_commands, "_current_version", lambda: "2.0.584")
+    monkeypatch.setattr(update_commands, "_current_version_from_subprocess", lambda: "2.0.584")
+    monkeypatch.setattr(update_commands, "_latest_version_from_pypi", lambda: "2.0.585")
+    monkeypatch.setattr(update_commands, "_direct_url_payload", lambda: None)
+    monkeypatch.setattr(update_commands, "_installer_kind", lambda: "pipx")
+    monkeypatch.setattr(
+        update_commands.shutil,
+        "which",
+        lambda name: "/mock-home/.local/bin/hol-guard" if name == "hol-guard" else None,
+    )
+
+    def fake_run(command: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
+        assert command == ["pipx", "upgrade", "hol-guard"]
+        return subprocess.CompletedProcess(
+            command,
+            0,
+            "hol-guard is already at latest version 2.0.584",
+            "upgrading shared libraries...\nupgrading hol-guard...\n",
+        )
+
+    monkeypatch.setattr(update_commands.subprocess, "run", fake_run)
+
+    payload, exit_code = update_commands.run_guard_update(dry_run=False)
+
+    assert exit_code == 0
+    assert payload["status"] == "stale"
+    assert payload["changed"] is False
+    assert payload["resulting_version"] == "2.0.584"
+    assert payload["retry_command"] == "pipx install --force hol-guard"
+    assert "behind PyPI 2.0.585 after the update attempt" in str(payload["message"])
+
+
 def test_update_switches_git_install_to_pypi_when_release_is_newer(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(update_commands, "_current_version", lambda: "2.0.345")
     monkeypatch.setattr(update_commands, "_current_version_from_subprocess", lambda: "2.0.489")