plugin-scanner 2.0.1001__tar.gz → 2.0.1003__tar.gz

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.1001
+Version: 2.0.1003
 Summary: Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, OpenCode, and Pi.
 Project-URL: Homepage, https://github.com/hashgraph-online/hol-guard
 Project-URL: Repository, https://github.com/hashgraph-online/hol-guard

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/pyproject.toml

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

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/pyproject.toml.bak

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

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/cli.py

@@ -304,6 +304,10 @@ def main(argv: list[str] | None = None) -> int:
         program_name=program_name,
     )
     args = parser.parse_args(resolved_argv)
+    # Surface silent stale-install shadowing before dispatching. Non-fatal.
+    from .install_integrity import warn_if_shadowed
+
+    warn_if_shadowed()
     if program_mode == "guard":
         try:
             return run_guard_command(args)

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/guard/cli/commands_hook_copilot.py

@@ -185,6 +185,7 @@ def _run_hook_copilot_pretool(
             signals=decision.signals,
             risk_categories=decision.risk_categories,
             remember=False,
+            arguments=runtime_arguments,
         )
         if _should_emit_copilot_hook_response(args):
             _record_harness_usage_for_hook(
@@ -205,6 +206,7 @@ def _run_hook_copilot_pretool(
                 now=now,
                 signals=decision.signals,
                 risk_categories=decision.risk_categories,
+                arguments=runtime_arguments,
             )
         if _should_emit_copilot_hook_response(args):
             _record_harness_usage_for_hook(
@@ -318,6 +320,7 @@ def _run_hook_copilot_permission_request(
             signals=decision.signals,
             risk_categories=decision.risk_categories,
             remember=False,
+            arguments=runtime_arguments,
         )
         if _should_emit_copilot_hook_response(args):
             _record_harness_usage_for_hook(
@@ -344,6 +347,7 @@ def _run_hook_copilot_permission_request(
         now=now,
         signals=decision.signals,
         risk_categories=decision.risk_categories,
+        arguments=runtime_arguments,
     )
     approval_center_url = ensure_guard_daemon(guard_home)
     approval_flow = get_adapter(args.harness).approval_flow(managed_install=managed_install)

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/guard/mcp_tool_calls.py

@@ -35,6 +35,59 @@ class ToolCallDecision:
     risk_categories: tuple[str, ...] = ()
 
 
+_MCP_COMMAND_ARGUMENT_KEYS: tuple[str, ...] = (
+    "command",
+    "cmd",
+    "shell_command",
+    "shellCommand",
+    "script",
+    "expression",
+    "code",
+    "query",
+)
+
+_MCP_PATH_ARGUMENT_KEYS: tuple[str, ...] = (
+    "path",
+    "file_path",
+    "filePath",
+    "filepath",
+    "directory",
+    "dir",
+    "cwd",
+    "working_dir",
+    "workingDir",
+    "url",
+    "uri",
+)
+
+
+def extract_mcp_command_text(
+    artifact: GuardArtifact,
+    arguments: object,
+) -> str | None:
+    """Extract a human-readable command string from MCP tool call arguments.
+
+    For tools like ctx_shell/bash the primary argument is a ``command`` string.
+    For file/path tools we surface the path. For other tools we return None so
+    the UI falls back to the artifact name.
+    """
+    if not isinstance(arguments, Mapping):
+        return None
+
+    tool_name = artifact.name
+    for key in _MCP_COMMAND_ARGUMENT_KEYS:
+        value = arguments.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+
+    for key in _MCP_PATH_ARGUMENT_KEYS:
+        value = arguments.get(key)
+        if isinstance(value, str) and value.strip():
+            return f"{tool_name} {value.strip()}"
+
+    return None
+
+
 def build_tool_call_artifact(
     *,
     harness: str,
@@ -667,6 +720,7 @@ def allow_tool_call(
     remember: bool,
     risk_categories: tuple[str, ...] = (),
     approval_gate_grant: ApprovalGateGrant | None = None,
+    arguments: object = None,
 ) -> GuardReceipt:
     if remember:
         store.upsert_policy(
@@ -691,6 +745,7 @@ def allow_tool_call(
         now=now,
         approved=True,
     )
+    raw_command_text = extract_mcp_command_text(artifact, arguments)
     receipt = build_receipt(
         harness=artifact.harness,
         artifact_id=artifact.artifact_id,
@@ -709,6 +764,7 @@ def allow_tool_call(
                 risk_categories=risk_categories,
             ),
         ),
+        raw_command_text=raw_command_text,
     )
     store.add_receipt(receipt)
     store.add_event(
@@ -734,6 +790,7 @@ def block_tool_call(
     now: str,
     signals: tuple[str, ...],
     risk_categories: tuple[str, ...] = (),
+    arguments: object = None,
 ) -> GuardReceipt:
     store.record_inventory_artifact(
         artifact=artifact,
@@ -743,6 +800,7 @@ def block_tool_call(
         now=now,
         approved=False,
     )
+    raw_command_text = extract_mcp_command_text(artifact, arguments)
     receipt = build_receipt(
         harness=artifact.harness,
         artifact_id=artifact.artifact_id,
@@ -761,6 +819,7 @@ def block_tool_call(
                 risk_categories=risk_categories,
             ),
         ),
+        raw_command_text=raw_command_text,
     )
     store.add_receipt(receipt)
     store.add_event(

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/guard/models.py

@@ -179,6 +179,7 @@ class GuardReceipt:
     approval_request_id: str | None = None
     scanner_evidence: tuple[dict[str, object], ...] = ()
     browser_intent: dict[str, object] | None = None
+    raw_command_text: str | None = None
 
     def to_dict(self) -> dict[str, object]:
         payload = asdict(self)

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/guard/proxy/runtime_mcp.py

@@ -389,6 +389,7 @@ class RuntimeMcpGuardProxy:
                             signals=decision.signals,
                             risk_categories=decision.risk_categories,
                             remember=True,
+                            arguments=arguments,
                         )
                     except ApprovalGateError:
                         return self._queue_approval_center_response(
@@ -423,6 +424,7 @@ class RuntimeMcpGuardProxy:
                         now=_now(),
                         signals=decision.signals,
                         risk_categories=decision.risk_categories,
+                        arguments=arguments,
                     )
                     return _blocked_tool_response(
                         message.get("id"),
@@ -441,6 +443,7 @@ class RuntimeMcpGuardProxy:
                         now=_now(),
                         signals=decision.signals,
                         risk_categories=decision.risk_categories,
+                        arguments=arguments,
                     )
                     return _blocked_tool_response(
                         message.get("id"),
@@ -544,6 +547,7 @@ class RuntimeMcpGuardProxy:
                     now=_now(),
                     signals=decision.signals,
                     risk_categories=decision.risk_categories,
+                    arguments=arguments,
                 )
                 return _blocked_tool_response(
                     message.get("id"),
@@ -562,6 +566,7 @@ class RuntimeMcpGuardProxy:
                     now=_now(),
                     signals=decision.signals,
                     risk_categories=decision.risk_categories,
+                    arguments=arguments,
                 )
                 return _blocked_tool_response(
                     message.get("id"),
@@ -672,6 +677,7 @@ class RuntimeMcpGuardProxy:
                         signals=remember_signals,
                         risk_categories=remember_risk_categories,
                         remember=True,
+                        arguments=params.get("arguments"),
                     )
                 except ApprovalGateError:
                     return self._queue_approval_center_response(
@@ -732,6 +738,7 @@ class RuntimeMcpGuardProxy:
                         signals=remember_signals,
                         risk_categories=remember_risk_categories,
                         remember=True,
+                        arguments=params.get("arguments"),
                     )
                 except ApprovalGateError:
                     return self._queue_approval_center_response(
@@ -879,6 +886,7 @@ class RuntimeMcpGuardProxy:
                 signals=signals,
                 risk_categories=risk_categories,
                 remember=remember,
+                arguments=params.get("arguments"),
             )
         except ApprovalGateError:
             if remember:
@@ -1221,6 +1229,7 @@ class RuntimeMcpGuardProxy:
             now=_now(),
             signals=signals,
             risk_categories=tool_call_risk_categories(artifact, params.get("arguments")),
+            arguments=params.get("arguments"),
         )
         request_id = str(queued[0]["request_id"]) if queued else "unknown"
         review_url = first_approval_url(queued, approval_center_url=approval_center_url) or approval_center_url

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/guard/receipts/manager.py

@@ -91,6 +91,7 @@ def build_receipt(
     diff_summary: str | None = None,
     approval_source: str | None = None,
     approval_request_id: str | None = None,
+    raw_command_text: str | None = None,
 ) -> GuardReceipt:
     """Create a runtime receipt."""
 
@@ -116,4 +117,5 @@ def build_receipt(
         approval_source=approval_source,
         approval_request_id=approval_request_id,
         scanner_evidence=tuple(dict(item) for item in scanner_evidence),
+        raw_command_text=raw_command_text,
     )

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/guard/runtime/runner.py

@@ -4340,6 +4340,9 @@ def _cloud_sync_receipt_payload(
         "recommendation": _cloud_sync_recommendation(policy_decision),
         "summary": summary,
     }
+    raw_command_text = _optional_string(receipt.get("raw_command_text"))
+    if raw_command_text is not None:
+        payload["raw_command_text"] = _cloud_sync_command_display_part(raw_command_text)
     publisher = _optional_string(receipt.get("publisher"))
     if publisher is not None:
         payload["publisher"] = publisher

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/guard/store_connection_schema.py

@@ -264,7 +264,8 @@ class StoreConnectionSchemaMixin:
               artifact_name text,
               source_scope text,
               scanner_evidence_json text not null default '[]',
-              timestamp text not null
+              timestamp text not null,
+              raw_command_text text
             )
             """,
             """
@@ -481,6 +482,7 @@ class StoreConnectionSchemaMixin:
             self._ensure_runtime_receipts_column(connection, "diff_summary", "text")
             self._ensure_runtime_receipts_column(connection, "approval_source", "text")
             self._ensure_runtime_receipts_column(connection, "approval_request_id", "text")
+            self._ensure_runtime_receipts_column(connection, "raw_command_text", "text")
             self._ensure_runtime_receipt_envelopes_table(connection)
             if not self._schema_version_applied(connection, version=5):
                 self._migrate_v5_receipt_envelopes(connection)
@@ -637,7 +639,8 @@ class StoreConnectionSchemaMixin:
               timestamp text not null,
               diff_summary text,
               approval_source text,
-              approval_request_id text
+              approval_request_id text,
+              raw_command_text text
             )
             """
         )
@@ -647,13 +650,13 @@ class StoreConnectionSchemaMixin:
               rowid, receipt_id, harness, artifact_id, artifact_hash, policy_decision,
               capabilities_summary, changed_capabilities_json, provenance_summary, user_override,
               artifact_name, source_scope, scanner_evidence_json, timestamp, diff_summary,
-              approval_source, approval_request_id
+              approval_source, approval_request_id, raw_command_text
             )
             select
               rowid, receipt_id, harness, artifact_id, artifact_hash, policy_decision,
               capabilities_summary, changed_capabilities_json, provenance_summary, user_override,
               artifact_name, source_scope, scanner_evidence_json, timestamp, diff_summary,
-              approval_source, null
+              approval_source, null, null
             from runtime_receipts
             """
         )

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/guard/store_receipts.py

@@ -24,9 +24,9 @@ class StoreReceiptsRuntimeMixin:
                   receipt_id, harness, artifact_id, artifact_hash, policy_decision, capabilities_summary,
                   changed_capabilities_json,
                   provenance_summary, user_override, artifact_name, source_scope, scanner_evidence_json,
-                  diff_summary, approval_source, approval_request_id, timestamp
+                  diff_summary, approval_source, approval_request_id, timestamp, raw_command_text
                 )
-                values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 """,
                 (
                     receipt.receipt_id,
@@ -45,6 +45,7 @@ class StoreReceiptsRuntimeMixin:
                     receipt.approval_source,
                     receipt.approval_request_id,
                     receipt.timestamp,
+                    receipt.raw_command_text,
                 ),
             )
             if action_envelope is not None:
@@ -156,6 +157,7 @@ class StoreReceiptsRuntimeMixin:
               r.approval_source,
               r.approval_request_id,
               r.timestamp,
+              r.raw_command_text,
               e.envelope_full_json as envelope_full_json,
               e.envelope_redacted_json as envelope_redacted_json,
               a.action_envelope_json as approval_envelope_json
@@ -189,6 +191,7 @@ class StoreReceiptsRuntimeMixin:
                 "approval_source": row["approval_source"],
                 "approval_request_id": row["approval_request_id"],
                 "timestamp": str(row["timestamp"]),
+                "raw_command_text": row["raw_command_text"],
                 "action_envelope_json": envelope,
                 "envelope_redacted_json": _json_object(row["envelope_redacted_json"]),
             }

plugin_scanner-2.0.1003/src/codex_plugin_scanner/install_integrity.py

@@ -0,0 +1,178 @@
+"""Startup install-integrity self-check.
+
+Detects the silent "stale install shadowing" failure where a long-running
+daemon process (launched with system Python) imports an ancient
+``codex_plugin_scanner`` from user site-packages or Homebrew global site, while
+the user believes they are running the latest ``hol-guard`` from a pipx venv.
+The symptom is that the daemon runs months-old code with no new features
+(memory decision events, etc.) and nothing surfaces the discrepancy.
+
+The check is non-fatal: it prints a loud warning to stderr when a shadowing
+install is detected, so the user sees it in daemon logs and CLI output. It
+never raises or blocks, so it cannot break a working install.
+
+Version files are read via AST parsing only — never executed — so a rogue
+``version.py`` on ``sys.path`` cannot run arbitrary code during the check.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+from pathlib import Path
+
+PACKAGE_NAME = "codex_plugin_scanner"
+
+
+def detect_shadowed_install() -> str | None:
+    """Return a human-readable warning if a stale install shadows the loaded one.
+
+    Returns ``None`` when the install looks healthy (single source, or the
+    loaded package is the newest reachable). Returns a warning string when a
+    different ``codex_plugin_scanner`` directory on ``sys.path`` reports a
+    newer version than the loaded one, or when multiple package roots are
+    reachable.
+    """
+    try:
+        import codex_plugin_scanner as _loaded
+        from codex_plugin_scanner.version import __version__ as loaded_version
+    except Exception:
+        return None
+
+    loaded_package_dir = Path(getattr(_loaded, "__file__", "")).resolve().parent
+    seen_roots: dict[str, str] = {}
+    for entry in sys.path:
+        if not entry:
+            continue
+        candidate_root = Path(entry) / PACKAGE_NAME
+        if not (candidate_root / "__init__.py").is_file():
+            continue
+        version_value = _read_version_via_ast(candidate_root / "version.py")
+        if version_value:
+            seen_roots[str(candidate_root.resolve())] = version_value
+
+    if len(seen_roots) <= 1:
+        return None
+
+    loaded_key = str(loaded_package_dir)
+    loaded_tuple = _parse_version(loaded_version)
+
+    newer_roots = [
+        (path, version)
+        for path, version in seen_roots.items()
+        if path != loaded_key and _parse_version(version) > loaded_tuple
+    ]
+    other_roots = [f"  - {path} ({version})" for path, version in seen_roots.items() if path != loaded_key]
+    if not other_roots:
+        return None
+
+    if not newer_roots:
+        return (
+            "hol-guard: multiple codex_plugin_scanner installs detected on sys.path.\n"
+            "This can cause long-running daemons to import the wrong copy.\n"
+            + "\n".join(other_roots)
+            + f"\nLoaded: {loaded_package_dir} ({loaded_version})"
+        )
+
+    stale_lines = [f"  - {path} ({version}) is NEWER than the loaded copy" for path, version in newer_roots]
+    return (
+        "hol-guard WARNING: a newer codex_plugin_scanner install is being shadowed.\n"
+        "The currently running process loaded an older copy; features may be missing.\n"
+        + "\n".join(stale_lines)
+        + f"\nLoaded: {loaded_package_dir} ({loaded_version})\n"
+        "Fix: uninstall the stale copy (pip uninstall codex-plugin-scanner) or "
+        "restart the process with the Python that has the newer install."
+    )
+
+
+def warn_if_shadowed() -> None:
+    """Print a shadowing warning to stderr if one is detected. Never raises."""
+    try:
+        warning = detect_shadowed_install()
+    except Exception:
+        return
+    if warning:
+        print(f"\n{warning}\n", file=sys.stderr)
+
+
+def _read_version_via_ast(version_file: Path) -> str | None:
+    """Read ``__version__`` from a version.py via AST parsing (no execution)."""
+    if not version_file.is_file():
+        return None
+    try:
+        tree = ast.parse(version_file.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError):
+        return None
+    for node in ast.walk(tree):
+        # Support both plain assignments (__version__ = "...") and annotated
+        # assignments (__version__: str = "...").
+        if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            assign_targets = [node.target]
+            assign_value = node.value
+        elif isinstance(node, ast.Assign):
+            assign_targets = node.targets
+            assign_value = node.value
+        else:
+            continue
+        if not isinstance(assign_value, ast.Constant) or not isinstance(assign_value.value, str):
+            continue
+        for target in assign_targets:
+            if isinstance(target, ast.Name) and target.id == "__version__":
+                return assign_value.value
+    return None
+
+
+_RELEASE_SEGMENT_RE = re.compile(r"\d+(?:\.\d+)*")
+_PRE_RELEASE_RE = re.compile(r"(a|b|rc|alpha|beta|pre|preview)(\d*)", re.IGNORECASE)
+_POST_RELEASE_RE = re.compile(r"\.(post|rev|r)(\d*)", re.IGNORECASE)
+_DEV_RELEASE_RE = re.compile(r"\.?(dev)(\d*)", re.IGNORECASE)
+
+# Sort sentinels for PEP 440 ordering: dev < pre < final < post.
+_DEV_SENTINEL = -3
+_PRE_SENTINEL = -2
+_FINAL_SENTINEL = 0
+_POST_SENTINEL = 1
+
+
+def _parse_version(value: str) -> tuple[int, ...]:
+    """Parse a version string into a comparable tuple.
+
+    Numeric release segments are compared as integers, with PEP 440 suffix
+    ordering: dev < pre-release (a/b/rc) < final < post-release.
+    """
+    match = _RELEASE_SEGMENT_RE.search(value)
+    if not match:
+        return (0,)
+    release = tuple(int(part) for part in match.group(0).split("."))
+    suffix = value[match.end() :]
+    pre_match = _PRE_RELEASE_RE.search(suffix)
+    post_match = _POST_RELEASE_RE.search(suffix)
+    dev_match = _DEV_RELEASE_RE.search(suffix)
+    if dev_match:
+        dev_number = int(dev_match.group(2)) if dev_match.group(2) else 0
+        return (*release, _DEV_SENTINEL, dev_number)
+    if pre_match:
+        pre_number = int(pre_match.group(2)) if pre_match.group(2) else 0
+        # Rank the pre-release type so a < b < rc (PEP 440).
+        pre_type_rank = _pre_release_type_rank(pre_match.group(1))
+        return (*release, _PRE_SENTINEL, pre_type_rank, pre_number)
+    if post_match:
+        post_number = int(post_match.group(2)) if post_match.group(2) else 0
+        return (*release, _POST_SENTINEL, post_number)
+    return (*release, _FINAL_SENTINEL)
+
+
+_PRE_RELEASE_TYPE_RANK = {
+    "a": 0,
+    "alpha": 0,
+    "b": 1,
+    "beta": 1,
+    "pre": 2,
+    "preview": 2,
+    "rc": 2,
+}
+
+
+def _pre_release_type_rank(label: str) -> int:
+    return _PRE_RELEASE_TYPE_RANK.get(label.lower(), 0)

{plugin_scanner-2.0.1001 → plugin_scanner-2.0.1003}/src/codex_plugin_scanner/version.py

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

plugin_scanner-2.0.1003/tests/test_install_integrity.py

@@ -0,0 +1,119 @@
+"""Tests for the install-integrity self-check."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from codex_plugin_scanner.install_integrity import (
+    _parse_version,
+    _read_version_via_ast,
+    detect_shadowed_install,
+    warn_if_shadowed,
+)
+
+
+def _make_fake_root(tmp_path: Path, version: str) -> Path:
+    root = tmp_path / "codex_plugin_scanner"
+    root.mkdir(parents=True)
+    (root / "__init__.py").write_text('"""stub"""\n')
+    (root / "version.py").write_text(f'__version__ = "{version}"\n')
+    return root
+
+
+def _loaded_package_dir() -> Path:
+    import codex_plugin_scanner as pkg
+
+    return Path(pkg.__file__).resolve().parent
+
+
+class TestParseVersion:
+    def test_simple(self) -> None:
+        assert _parse_version("2.0.1000") == (2, 0, 1000, 0)
+
+    def test_ordering(self) -> None:
+        assert _parse_version("2.0.345") < _parse_version("2.0.1000")
+
+    def test_empty(self) -> None:
+        assert _parse_version("") == (0,)
+
+    def test_pre_release_sorts_before_final(self) -> None:
+        assert _parse_version("2.0.1rc1") < _parse_version("2.0.1")
+
+    def test_pre_release_ordering(self) -> None:
+        assert _parse_version("2.0.1rc1") < _parse_version("2.0.1rc2")
+
+    def test_post_release_sorts_after_final(self) -> None:
+        assert _parse_version("2.0.1") < _parse_version("2.0.1.post1")
+
+    def test_dev_release_sorts_before_pre(self) -> None:
+        assert _parse_version("2.0.1.dev1") < _parse_version("2.0.1rc1")
+
+    def test_full_pep440_ordering(self) -> None:
+        assert (
+            _parse_version("2.0.1.dev1")
+            < _parse_version("2.0.1a1")
+            < _parse_version("2.0.1rc1")
+            < _parse_version("2.0.1")
+            < _parse_version("2.0.1.post1")
+        )
+
+
+class TestReadVersionViaAst:
+    def test_reads_version_without_executing(self, tmp_path: Path) -> None:
+        # A version.py that would crash if executed, but AST-parses fine.
+        version_file = tmp_path / "version.py"
+        version_file.write_text('__version__ = "9.9.9"\n')
+        assert _read_version_via_ast(version_file) == "9.9.9"
+
+    def test_returns_none_for_missing_file(self, tmp_path: Path) -> None:
+        assert _read_version_via_ast(tmp_path / "nope.py") is None
+
+    def test_returns_none_without_version_assignment(self, tmp_path: Path) -> None:
+        version_file = tmp_path / "version.py"
+        version_file.write_text('OTHER = "1.0.0"\n')
+        assert _read_version_via_ast(version_file) is None
+
+    def test_reads_annotated_assignment(self, tmp_path: Path) -> None:
+        version_file = tmp_path / "version.py"
+        version_file.write_text('__version__: str = "8.8.8"\n')
+        assert _read_version_via_ast(version_file) == "8.8.8"
+
+
+class TestDetectShadowedInstall:
+    def test_returns_none_with_single_install(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        loaded_dir = _loaded_package_dir()
+        monkeypatch.setattr(sys, "path", [str(loaded_dir.parent)])
+        assert detect_shadowed_install() is None
+
+    def test_warns_when_newer_install_is_shadowed(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        loaded_dir = _loaded_package_dir()
+        newer_root = _make_fake_root(tmp_path / "newer", "99.0.0")
+        monkeypatch.setattr(sys, "path", [str(loaded_dir.parent), str(newer_root.parent)])
+        warning = detect_shadowed_install()
+        assert warning is not None
+        assert "NEWER" in warning
+        assert "99.0.0" in warning
+
+    def test_notes_multiple_even_if_loaded_is_newest(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        loaded_dir = _loaded_package_dir()
+        older_root = _make_fake_root(tmp_path / "older", "0.0.1")
+        monkeypatch.setattr(sys, "path", [str(loaded_dir.parent), str(older_root.parent)])
+        warning = detect_shadowed_install()
+        assert warning is not None
+        assert "multiple" in warning.lower()
+        # The loaded install must NOT be listed as an "other" root.
+        assert str(loaded_dir) not in warning.split("Loaded:")[0]
+
+    def test_warn_if_shadowed_never_raises(
+        self, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setattr(
+            "codex_plugin_scanner.install_integrity.detect_shadowed_install",
+            lambda: (_ for _ in ()).throw(RuntimeError("boom")),
+        )
+        warn_if_shadowed()  # must not raise
+        captured = capsys.readouterr()
+        assert captured.err == ""