plugin-scanner 2.0.1112__tar.gz → 2.0.1114__tar.gz

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.1112
+Version: 2.0.1114
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://hol.org/guard
 Project-URL: Documentation, https://github.com/hashgraph-online/hol-guard/tree/main/docs/guard

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/pyproject.toml

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

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.1112"
+version = "2.0.1114"
 description = "Open-source antivirus and runtime protection for AI agents, tools, MCP servers, plugins, skills, and package installs."
 readme = "README.md"
 license = "Apache-2.0"

plugin_scanner-2.0.1112/release-metadata/plugin-scanner-v2.0.1112.toolchain.cdx.json → plugin_scanner-2.0.1114/release-metadata/plugin-scanner-v2.0.1114.toolchain.cdx.json

@@ -27,7 +27,7 @@
     "component": {
       "name": "hol-guard-release-toolchain",
       "type": "application",
-      "version": "2.0.1112"
+      "version": "2.0.1114"
     }
   },
   "specVersion": "1.6",

plugin_scanner-2.0.1114/src/codex_plugin_scanner/guard/action_lattice.py

@@ -0,0 +1,147 @@
+"""Canonical normalization and ordering for Guard enforcement actions.
+
+Guard actions form a total order from least to most restrictive::
+
+    allow < warn < review < require-reapproval < sandbox-required < block
+
+``require-reapproval`` invalidates a prior grant and requires a fresh user
+decision. ``sandbox-required`` additionally requires an enforceable sandbox;
+it is therefore strictly stronger and must never collapse to ``review``.
+
+Values crossing an untyped boundary are normalized to ``review`` by default.
+This is deliberately fail-closed: an action introduced by a newer producer,
+or a malformed action, cannot receive a permissive sentinel rank and lose to
+``allow`` or ``warn`` during composition.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Final, TypeGuard, get_args
+
+from .models import GUARD_ACTION_VALUES, GuardAction
+
+UNKNOWN_GUARD_ACTION_REASON: Final = "guard_action_unknown"
+DEFAULT_UNKNOWN_GUARD_ACTION: Final[GuardAction] = "review"
+
+_GUARD_ACTION_SEVERITY: dict[GuardAction, int] = {
+    "allow": 0,
+    "warn": 1,
+    "review": 2,
+    "require-reapproval": 3,
+    "sandbox-required": 4,
+    "block": 5,
+}
+
+# Exposed read-only for contracts, diagnostics, and exhaustiveness tests. Code
+# should compose actions through the helpers below instead of indexing it.
+GUARD_ACTION_SEVERITY: Final[Mapping[GuardAction, int]] = MappingProxyType(_GUARD_ACTION_SEVERITY)
+GUARD_ACTION_LATTICE: Final[tuple[GuardAction, ...]] = tuple(_GUARD_ACTION_SEVERITY)
+
+if (  # pragma: no cover - import-time invariant
+    frozenset(GUARD_ACTION_LATTICE) != frozenset(GUARD_ACTION_VALUES)
+    or frozenset(GUARD_ACTION_LATTICE) != frozenset(get_args(GuardAction))
+):
+    raise RuntimeError("GuardAction values and the canonical action lattice are out of sync")
+if tuple(_GUARD_ACTION_SEVERITY.values()) != tuple(range(len(_GUARD_ACTION_SEVERITY))):  # pragma: no cover
+    raise RuntimeError("GuardAction severity ranks must be unique and contiguous")
+
+
+@dataclass(frozen=True, slots=True)
+class GuardActionNormalization:
+    """Normalized action plus safe diagnostics for an untyped input value."""
+
+    action: GuardAction
+    reason_code: str | None
+    original_action: str | None
+    original_type: str
+
+    @property
+    def recognized(self) -> bool:
+        return self.reason_code is None
+
+
+def is_guard_action(value: object) -> TypeGuard[GuardAction]:
+    """Return whether ``value`` is an action covered by the canonical lattice."""
+
+    return isinstance(value, str) and value in GUARD_ACTION_SEVERITY
+
+
+def coerce_guard_action(value: object) -> GuardAction | None:
+    """Return a typed action when recognized, otherwise ``None``.
+
+    Use this only when absence is meaningful and the caller supplies its own
+    already-typed policy fallback. Untyped enforcement inputs should use
+    :func:`normalize_guard_action` so they fail closed.
+    """
+
+    return value if is_guard_action(value) else None
+
+
+def normalize_guard_action_result(
+    value: object,
+    *,
+    unknown_action: GuardAction = DEFAULT_UNKNOWN_GUARD_ACTION,
+) -> GuardActionNormalization:
+    """Normalize an untyped value and retain stable, non-coercive diagnostics."""
+
+    if not is_guard_action(unknown_action):  # Defensive even for untyped callers.
+        raise ValueError(f"unknown_action is not a GuardAction: {unknown_action!r}")
+    if is_guard_action(value):
+        return GuardActionNormalization(
+            action=value,
+            reason_code=None,
+            original_action=value,
+            original_type="str",
+        )
+    return GuardActionNormalization(
+        action=unknown_action,
+        reason_code=UNKNOWN_GUARD_ACTION_REASON,
+        original_action=value if isinstance(value, str) else None,
+        original_type=type(value).__name__,
+    )
+
+
+def normalize_guard_action(
+    value: object,
+    *,
+    unknown_action: GuardAction = DEFAULT_UNKNOWN_GUARD_ACTION,
+) -> GuardAction:
+    """Return a known action, conservatively normalizing unknown values."""
+
+    return normalize_guard_action_result(value, unknown_action=unknown_action).action
+
+
+def guard_action_severity(
+    action: object,
+    *,
+    unknown_action: GuardAction = DEFAULT_UNKNOWN_GUARD_ACTION,
+) -> int:
+    """Return the canonical rank; unknown inputs receive a conservative rank."""
+
+    normalized = normalize_guard_action(action, unknown_action=unknown_action)
+    return GUARD_ACTION_SEVERITY[normalized]
+
+
+def most_restrictive_guard_action(
+    *actions: object,
+    unknown_action: GuardAction = DEFAULT_UNKNOWN_GUARD_ACTION,
+) -> GuardAction:
+    """Compose actions using the canonical total order.
+
+    Every provided value is normalized independently. With no candidates, the
+    conservative ``unknown_action`` is returned.
+    """
+
+    if not actions:
+        return normalize_guard_action(None, unknown_action=unknown_action)
+    normalized: tuple[GuardAction, ...] = tuple(
+        normalize_guard_action(action, unknown_action=unknown_action) for action in actions
+    )
+    winner: GuardAction = normalized[0]
+    for candidate in normalized[1:]:
+        if GUARD_ACTION_SEVERITY[candidate] > GUARD_ACTION_SEVERITY[winner]:
+            winner = candidate
+    return winner

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/approvals.py

@@ -12,6 +12,7 @@ from pathlib import Path
 from typing import TypeGuard
 from urllib.parse import ParseResult, parse_qsl, urlencode, urlparse, urlunparse
 
+from .action_lattice import normalize_guard_action_result
 from .adapters import get_adapter
 from .adapters.base import HarnessContext
 from .approval_gate import ApprovalGateGrant, ApprovalGateInput, require_approval_decision
@@ -37,9 +38,7 @@ from .local_supply_chain import build_local_supply_chain_posture
 from .memory_decision_outbox import enqueue_memory_decision_event
 from .models import (
     DECISION_SCOPE_VALUES,
-    GUARD_ACTION_VALUES,
     DecisionScope,
-    GuardAction,
     GuardApprovalRequest,
     GuardArtifact,
     HarnessDetection,
@@ -116,10 +115,6 @@ def _normalize_harness_slug(harness: str | None) -> str | None:
     return normalized or None
 
 
-def _is_guard_action(value: object) -> TypeGuard[GuardAction]:
-    return isinstance(value, str) and value in GUARD_ACTION_VALUES
-
-
 def _is_decision_scope(value: object) -> TypeGuard[DecisionScope]:
     return isinstance(value, str) and value in DECISION_SCOPE_VALUES
 
@@ -408,13 +403,29 @@ def queue_blocked_approvals(
     for item in artifacts:
         if not isinstance(item, dict):
             continue
-        policy_action = item.get("policy_action")
-        if not _is_guard_action(policy_action) or policy_action not in {
+        normalization = normalize_guard_action_result(
+            item.get("policy_action"),
+            unknown_action="require-reapproval",
+        )
+        policy_action = normalization.action
+        if policy_action not in {
             "block",
             "sandbox-required",
             "require-reapproval",
         }:
             continue
+        scanner_evidence = _item_scanner_evidence(item)
+        if not normalization.recognized:
+            normalization_evidence: dict[str, object] = {
+                "source": "guard_action_normalizer",
+                "reason_code": normalization.reason_code,
+                "original_action": normalization.original_action,
+                "normalized_action": normalization.action,
+            }
+            scanner_evidence = (
+                *scanner_evidence,
+                normalization_evidence,
+            )
         artifact_id = str(item.get("artifact_id") or "")
         if not artifact_id:
             continue
@@ -469,7 +480,7 @@ def queue_blocked_approvals(
             risk_headline=incident["risk_headline"],
             action_envelope_json=_item_action_envelope_json(item),
             decision_v2_json=_item_decision_v2_json(item),
-            scanner_evidence=_item_scanner_evidence(item),
+            scanner_evidence=scanner_evidence,
             raw_command_text=raw_command_text,
         )
         persisted_request_id = store.add_approval_request(request, timestamp)

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/_commands_shared.py

@@ -128,7 +128,7 @@ from ..mcp_tool_calls import (
     build_tool_call_hash,
     evaluate_tool_call,
 )
-from ..models import SEVERITY_RANK, GuardArtifact, HarnessDetection, PolicyDecision
+from ..models import GUARD_ACTION_VALUES, SEVERITY_RANK, GuardArtifact, HarnessDetection, PolicyDecision
 from ..package_firewall_entitlement import (
     package_firewall_action_states,
     package_firewall_available_actions,

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/commands_dispatch_local.py

@@ -162,6 +162,18 @@ def _run_guard_update_command(
         now=_now(),
         wheel=getattr(args, "wheel", None),
     )
+    if not dry_run and exit_code == 0 and context is not None:
+        from .update_commands import refresh_guard_daemon_after_update
+
+        daemon_refresh, daemon_refresh_note = refresh_guard_daemon_after_update(context)
+        if daemon_refresh is not None:
+            payload["daemon_refresh"] = daemon_refresh
+        if daemon_refresh_note is not None:
+            notes_value = payload.get("notes")
+            note_items = notes_value if isinstance(notes_value, list) else []
+            notes = [str(item) for item in note_items if isinstance(item, str)]
+            notes.append(daemon_refresh_note)
+            payload["notes"] = notes
     if update_store_error is not None:
         notes_value = payload.get("notes")
         notes = [str(item) for item in (notes_value if isinstance(notes_value, list) else []) if isinstance(item, str)]

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/commands_hook_runtime_eval.py

@@ -8,7 +8,6 @@ from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from ._commands_shared import _now
-    from .commands_support_hook_payload import _coalesce_string
     from .commands_support_hook_state import _cursor_native_shell_is_approved
     from .commands_support_interaction import _emit, _record_harness_usage_for_hook
     from .commands_support_permission_store import (
@@ -32,6 +31,12 @@ if TYPE_CHECKING:
     )
 
 
+from ..action_lattice import (
+    GuardActionNormalization,
+    coerce_guard_action,
+    normalize_guard_action,
+    normalize_guard_action_result,
+)
 from ..approval_scope_support import package_request_runtime_workspace_scope
 from ..models import GuardAction
 from ..package_execution_context import PackageExecutionContext, build_package_execution_context
@@ -42,19 +47,21 @@ from .commands_support_runtime_policy import _remembered_rule_rejection_reason,
 
 
 def _resolved_guard_action(value: object, fallback: GuardAction) -> GuardAction:
-    if value == "allow":
-        return "allow"
-    if value == "warn":
-        return "warn"
-    if value == "review":
-        return "review"
-    if value == "block":
-        return "block"
-    if value == "sandbox-required":
-        return "sandbox-required"
-    if value == "require-reapproval":
-        return "require-reapproval"
-    return fallback
+    return coerce_guard_action(value) or fallback
+
+
+def _requested_policy_action_normalization(
+    cli_action: object | None,
+    stored_action: object | None,
+    payload: Mapping[str, object],
+) -> GuardActionNormalization | None:
+    if cli_action is not None:
+        return normalize_guard_action_result(cli_action, unknown_action="require-reapproval")
+    if stored_action is not None:
+        return normalize_guard_action_result(stored_action, unknown_action="require-reapproval")
+    if "policy_action" in payload:
+        return normalize_guard_action_result(payload.get("policy_action"), unknown_action="require-reapproval")
+    return None
 
 
 def _evaluate_runtime_artifact_hook(
@@ -168,23 +175,16 @@ def _evaluate_runtime_artifact_hook(
                 artifact_hash=artifact_hash(legacy_artifact),
                 workspace=str(runtime_workspace) if runtime_workspace else None,
             )
-    requested_policy_action = _coalesce_string(
+    requested_action_normalization = _requested_policy_action_normalization(
         getattr(args, "policy_action", None),
         stored_policy_action,
-        payload_map.get("policy_action"),
+        payload_map,
+    )
+    requested_policy_action = (
+        requested_action_normalization.original_action if requested_action_normalization is not None else None
     )
-    if requested_policy_action == "allow":
-        policy_action: GuardAction = "allow"
-    elif requested_policy_action == "warn":
-        policy_action = "warn"
-    elif requested_policy_action == "review":
-        policy_action = "review"
-    elif requested_policy_action == "block":
-        policy_action = "block"
-    elif requested_policy_action == "sandbox-required":
-        policy_action = "sandbox-required"
-    elif requested_policy_action == "require-reapproval":
-        policy_action = "require-reapproval"
+    if requested_action_normalization is not None:
+        policy_action = requested_action_normalization.action
     else:
         policy_action = _resolved_guard_action(
             _runtime_artifact_policy_action(config, runtime_artifact, args.harness),
@@ -251,10 +251,21 @@ def _evaluate_runtime_artifact_hook(
         else ()
     )
     scanner_evidence_payload = [signal.to_dict() for signal in scanner_evidence]
+    if requested_action_normalization is not None and not requested_action_normalization.recognized:
+        scanner_evidence_payload.append(
+            {
+                "source": "guard_action_normalizer",
+                "input_source": "runtime_hook_requested_policy",
+                "reason_code": requested_action_normalization.reason_code,
+                "original_action": requested_action_normalization.original_action,
+                "original_type": requested_action_normalization.original_type,
+                "normalized_action": requested_action_normalization.action,
+            }
+        )
     if package_execution_context is not None:
         scanner_evidence_payload.append(package_execution_context.to_evidence())
     package_policy_action: GuardAction | None = (
-        _resolved_guard_action(package_evaluation.policy_action, "warn") if package_evaluation is not None else None
+        normalize_guard_action(package_evaluation.policy_action) if package_evaluation is not None else None
     )
     if package_policy_action is not None and guard_action_severity(package_policy_action) > guard_action_severity(
         policy_action
@@ -438,4 +449,5 @@ def _evaluate_runtime_artifact_hook(
 
 __all__ = [
     "_evaluate_runtime_artifact_hook",
+    "_requested_policy_action_normalization",
 ]

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/commands_parser_cloud.py

@@ -363,7 +363,7 @@ def _configure_guard_cloud_parsers(
     hook_parser.add_argument("--artifact-name")
     hook_parser.add_argument(
         "--policy-action",
-        choices=("allow", "warn", "review", "block", "sandbox-required", "require-reapproval"),
+        choices=GUARD_ACTION_VALUES,
     )
     hook_parser.add_argument("--event-file")
     hook_parser.add_argument("--json", action="store_true")

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/commands_parser_local.py

@@ -153,7 +153,7 @@ def _configure_guard_local_parsers(
     run_parser.add_argument("--dry-run", action="store_true")
     run_parser.add_argument(
         "--default-action",
-        choices=("allow", "warn", "review", "block", "sandbox-required", "require-reapproval"),
+        choices=GUARD_ACTION_VALUES,
     )
     run_parser.add_argument(
         "--grok-executable",

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/commands_support_claude_approval.py

@@ -26,6 +26,7 @@ if TYPE_CHECKING:
     from .commands_support_runtime_resolution import _canonical_harness_name
 
 
+from ..action_lattice import most_restrictive_guard_action, normalize_guard_action
 from ._commands_shared import *
 from .commands_parser_helpers import *
 
@@ -391,8 +392,10 @@ def _resolve_claude_permission_request_policy_action(
             store=store,
             workspace_dir=runtime_workspace,
         )
-        if guard_action_severity(package_evaluation.policy_action) > guard_action_severity(policy_action):
-            policy_action = package_evaluation.policy_action
+        policy_action = most_restrictive_guard_action(
+            policy_action,
+            normalize_guard_action(package_evaluation.policy_action),
+        )
     stub: dict[str, object] = {
         "harness": _canonical_harness_name(args.harness),
         "policy_action": policy_action,

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/commands_support_prompts.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
     from ._commands_shared import _NAMED_SECURITY_LEVELS, _SETTINGS_POLICY_RISK_ACTIONS, _guard_risk_action_key
 
 
+from ..action_lattice import coerce_guard_action
 from ._commands_shared import *
 from .commands_parser_helpers import *
 
@@ -47,18 +48,9 @@ def _copilot_hook_permission_decision(policy_action: str) -> str:
 
 def _guard_action_from_cli(value: object) -> GuardAction:
     normalized = str(value).strip()
-    if normalized == "allow":
-        return "allow"
-    if normalized == "warn":
-        return "warn"
-    if normalized == "review":
-        return "review"
-    if normalized == "block":
-        return "block"
-    if normalized == "sandbox-required":
-        return "sandbox-required"
-    if normalized == "require-reapproval":
-        return "require-reapproval"
+    action = coerce_guard_action(normalized)
+    if action is not None:
+        return action
     raise ValueError(f"Unsupported Guard action '{normalized}'.")
 
 def _run_approval_password_settings_command(*, args: argparse.Namespace, guard_home: Path) -> dict[str, object]:

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/commands_support_runtime_policy.py

@@ -14,6 +14,8 @@ if TYPE_CHECKING:
     from .commands_support_prompts import _prompt_request_classes, _prompt_requires_hard_block
 
 
+from ..action_lattice import coerce_guard_action, most_restrictive_guard_action, normalize_guard_action
+from ..models import GuardAction
 from ..runtime.command_extensions import risk_classes_for_command_action
 from ..store import _runtime_scoped_exact_match_key, runtime_tool_action_exact_match_context
 from ..text import ensure_terminal_punctuation as _ensure_terminal_punctuation
@@ -338,7 +340,7 @@ def _runtime_artifact_exact_match_context(artifact: GuardArtifact) -> str | None
         raw_command_text=raw_command_text if isinstance(raw_command_text, str) else None,
         wrapper_chain=normalized_wrapper_chain,
     )
-def _runtime_artifact_policy_action(config: GuardConfig, artifact: GuardArtifact, harness: str) -> str:
+def _runtime_artifact_policy_action(config: GuardConfig, artifact: GuardArtifact, harness: str) -> GuardAction:
     if _prompt_requires_hard_block(artifact):
         return "block"
     canonical_harness = _canonical_harness_name(harness)
@@ -352,19 +354,19 @@ def _runtime_artifact_policy_action(config: GuardConfig, artifact: GuardArtifact
             or resolve_risk_action(config, risk_class, harness=canonical_harness)
             for risk_class in risk_classes
         ]
-        resolved_actions = [action for action in risk_actions if action in VALID_GUARD_ACTIONS]
+        resolved_actions = [action for action in risk_actions if coerce_guard_action(action) is not None]
         if resolved_actions:
-            return max(resolved_actions, key=guard_action_severity)
+            return most_restrictive_guard_action(*resolved_actions)
     guard_default_action = _runtime_artifact_guard_default_action(artifact)
     risk_actions = [resolve_risk_action(config, risk_class, harness=canonical_harness) for risk_class in risk_classes]
-    resolved_actions = [action for action in risk_actions if action in VALID_GUARD_ACTIONS]
+    resolved_actions = [action for action in risk_actions if coerce_guard_action(action) is not None]
     if resolved_actions:
-        resolved = max(resolved_actions, key=guard_action_severity)
-        if guard_default_action is not None and guard_action_severity(guard_default_action) > guard_action_severity(
-            resolved
-        ):
-            return guard_default_action
-        return resolved
+        resolved = most_restrictive_guard_action(*resolved_actions)
+        return (
+            most_restrictive_guard_action(resolved, guard_default_action)
+            if guard_default_action is not None
+            else resolved
+        )
     if guard_default_action is not None:
         return guard_default_action
     return SAFE_CHANGED_HASH_ACTION
@@ -378,11 +380,9 @@ def _resolve_configured_risk_action(config: GuardConfig, risk_class: str, *, har
         return config.risk_actions[risk_class]
     return None
 
-def _runtime_artifact_guard_default_action(artifact: GuardArtifact) -> str | None:
+def _runtime_artifact_guard_default_action(artifact: GuardArtifact) -> GuardAction | None:
     value = artifact.metadata.get("guard_default_action")
-    if value in VALID_GUARD_ACTIONS:
-        return str(value)
-    return None
+    return normalize_guard_action(value, unknown_action="require-reapproval") if value is not None else None
 
 def _runtime_action_data_flow_signals(
     action_envelope: GuardActionEnvelope | None,

{plugin_scanner-2.0.1112 → plugin_scanner-2.0.1114}/src/codex_plugin_scanner/guard/cli/update_commands.py

@@ -78,6 +78,38 @@ if before.get("installed_managers"):
 after = package_shim_status(context)
 print(json.dumps({"before": before, "repair": repair, "after": after}))
 """.strip()
+_DAEMON_REFRESH_TIMEOUT_SECONDS = 35.0
+_DAEMON_REFRESH_SCRIPT = """
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from codex_plugin_scanner.guard.daemon.manager import (
+    clear_guard_daemon_state,
+    ensure_guard_daemon_after_update,
+    repair_approval_center_locator,
+    retire_all_guard_daemons_for_home,
+)
+
+payload = json.loads(sys.stdin.read())
+guard_home = Path(payload["guard_home"]).expanduser().resolve()
+state_path = guard_home / "daemon-state.json"
+if not state_path.is_file():
+    print(json.dumps({"status": "not_running"}))
+    raise SystemExit(0)
+try:
+    state = json.loads(state_path.read_text(encoding="utf-8"))
+except (OSError, json.JSONDecodeError):
+    state = {}
+preferred_port = state.get("port") if isinstance(state.get("port"), int) else None
+retired = retire_all_guard_daemons_for_home(guard_home)
+clear_guard_daemon_state(guard_home)
+repair_approval_center_locator(guard_home)
+daemon_url = ensure_guard_daemon_after_update(guard_home, preferred_port=preferred_port)
+print(json.dumps({"status": "restarted", "retired": retired, "daemon_url": daemon_url}))
+""".strip()
 
 
 def _read_direct_url_dir_info(direct_url: dict[str, object] | None) -> dict[str, object]:
@@ -1226,6 +1258,42 @@ def _refresh_package_shims_after_update(
     return refresh_payload, _package_shim_refresh_note(refresh_payload)
 
 
+def refresh_guard_daemon_after_update(context: HarnessContext) -> tuple[dict[str, object] | None, str | None]:
+    """Restart a resident daemon in a fresh interpreter after a CLI package update."""
+
+    if not (context.guard_home / "daemon-state.json").is_file():
+        return None, None
+    try:
+        refresh_env = dict(os.environ)
+        refresh_env.pop("PYTHONPATH", None)
+        result = subprocess.run(
+            [sys.executable, *_trusted_python_flags(), "-c", _DAEMON_REFRESH_SCRIPT],
+            input=json.dumps({"guard_home": str(context.guard_home)}),
+            capture_output=True,
+            check=False,
+            cwd=str(_trusted_import_root()),
+            env=refresh_env,
+            text=True,
+            timeout=_DAEMON_REFRESH_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError) as error:
+        return None, f"Could not restart the Guard daemon after update: {redact_sensitive_text(str(error))}"
+    stdout = _normalize_output_text(result.stdout)
+    stderr = _normalize_output_text(result.stderr)
+    if result.returncode != 0:
+        details = stderr or stdout or f"exit code {result.returncode}"
+        return None, f"Could not restart the Guard daemon after update: {details}"
+    try:
+        payload = json.loads(stdout) if stdout else {}
+    except json.JSONDecodeError as error:
+        return None, f"Could not parse the Guard daemon restart result after update: {error}"
+    if not isinstance(payload, dict):
+        return None, "Could not parse the Guard daemon restart result after update: invalid payload"
+    status = payload.get("status")
+    note = "Restarted the Guard daemon to load the updated package." if status == "restarted" else None
+    return payload, note
+
+
 def _package_shim_manifest_has_installed_managers(context: HarnessContext) -> bool:
     manifest_path = context.guard_home / "package-shims" / "manifest.json"
     try: