ha-mcp-dev 7.4.1.dev427__tar.gz → 7.4.1.dev429__tar.gz

{ha_mcp_dev-7.4.1.dev427/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev429}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev427
+Version: 7.4.1.dev429
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.4.1.dev427 → ha_mcp_dev-7.4.1.dev429}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.4.1.dev427"
+version = "7.4.1.dev429"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.4.1.dev427 → ha_mcp_dev-7.4.1.dev429}/src/ha_mcp/tools/tools_energy.py

@@ -96,7 +96,7 @@ def _compute_per_key_hashes(prefs: dict[str, Any]) -> dict[_PrefsKey, str]:
 
 
 def _is_no_prefs_error(error_msg: str) -> bool:
-    """True if an error string from send_websocket_message indicates
+    """Return True if an error string from send_websocket_message indicates
     ``ERR_NOT_FOUND "No prefs"`` from HA Core's energy/get_prefs handler.
 
     HA Core wraps the error as ``f"Command failed: {message}"``; the
@@ -143,13 +143,30 @@ def _flatten_validation_errors(raw: Any) -> list[dict[str, str]]:
     return errors
 
 
-def _shape_check(config: dict[str, Any]) -> list[dict[str, str]]:
-    """Cheap local shape check before sending to the server.
+def _shape_check(
+    config: dict[str, Any],
+    validate_only: dict[str, set[int]] | None = None,
+) -> list[dict[str, str]]:
+    """Validate config shape locally before sending to the server.
 
     Validates that top-level keys have the expected list-of-dicts shape and
     that required identifying fields are present. Does NOT validate semantic
     correctness (stat IDs existing, units matching, etc.) — that's surfaced
     by the post-save server-side ``energy/validate`` call.
+
+    ``validate_only`` scopes the per-entry check. ``None`` (default) validates
+    every entry under every present top-level key — the original contract.
+    A dict scopes the check to the listed keys and, within each, only the
+    listed indices: top-level keys absent from the dict are skipped entirely,
+    indices outside each key's set are skipped per-entry. The "must be a
+    list" structural check still fires for any present-and-listed key with a
+    non-list value, so ``validate_only`` cannot be used to bypass structural
+    sanity. A dict with an empty set for a key (``{key: set()}``) skips the
+    per-entry pass for that key while preserving the structural check —
+    this is what convenience-mode write paths pass for remove operations
+    (no new entries to validate, but the list shape is still checked). An
+    empty dict (``{}``) skips all keys entirely. See issue #1086 for the
+    asymmetric over-validation problem this addresses.
     """
     errors: list[dict[str, str]] = []
 
@@ -159,11 +176,18 @@ def _shape_check(config: dict[str, Any]) -> list[dict[str, str]]:
     for key in _PREFS_TOP_LEVEL_KEYS:
         if key not in config:
             continue
+        if validate_only is not None and key not in validate_only:
+            continue
         value = config[key]
         if not isinstance(value, list):
             errors.append({"path": key, "message": "must be a list"})
             continue
+        allowed_indices: set[int] | None = (
+            validate_only[key] if validate_only is not None else None
+        )
         for idx, entry in enumerate(value):
+            if allowed_indices is not None and idx not in allowed_indices:
+                continue
             if not isinstance(entry, dict):
                 errors.append(
                     {
@@ -217,6 +241,47 @@ def _shape_check(config: dict[str, Any]) -> list[dict[str, str]]:
     return errors
 
 
+def _appended_tail_indices(existing: list[Any], new: list[Any]) -> set[int]:
+    """Return the indices in ``new`` that lie past the end of ``existing``.
+
+    Per issue #1086, this builds the ``validate_only`` index set scoped to the
+    appended tail of an append-only / shrink-only mutation, so pre-existing
+    HA-validated siblings are not re-checked on every add/remove:
+
+    - Append-only mutators (``_add_*``): returns indices of the new entries.
+    - Shrink-only mutators (``_remove_*``): returns an empty set — nothing
+      new to validate, and the surviving entries already passed HA validation.
+
+    Refuses in-place mutators where ``len(new) == len(existing)`` but the
+    contents differ — the appended-tail formula would yield an empty index
+    set on a list whose entries actually changed, silently bypassing
+    per-entry validation. Add explicit handling (e.g. an
+    ``_indices_of_modified_entries`` helper) before introducing such a
+    mutator; do not extend this one.
+    """
+    if len(new) == len(existing) and new != existing:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.INTERNAL_ERROR,
+                "_appended_tail_indices: in-place mutation detected "
+                "(same length, different content) — the appended-tail "
+                "validation heuristic only covers append-only / shrink-only "
+                "mutators. Add explicit per-entry validation handling for "
+                "in-place mutators before reusing this helper.",
+                context={
+                    "existing_len": len(existing),
+                    "new_len": len(new),
+                },
+                suggestions=[
+                    "If introducing a _replace_* / _update_* mutator, "
+                    "compute the indices of modified entries explicitly "
+                    "and pass those to _shape_check via validate_only.",
+                ],
+            )
+        )
+    return set(range(len(existing), len(new)))
+
+
 class EnergyTools:
     """Energy Dashboard preference management tools for Home Assistant."""
 
@@ -629,6 +694,7 @@ class EnergyTools:
         config_hash: str | dict[_PrefsKey, str],
         *,
         current_prefs: dict[str, Any] | None = None,
+        validate_only: dict[str, set[int]] | None = None,
     ) -> dict[str, Any]:
         """Shape-check → hash-check → save → post-save validate.
 
@@ -650,11 +716,18 @@ class EnergyTools:
         path uses this to avoid a second ``energy/get_prefs`` round trip
         per attempt (the snapshot was already fetched by ``_mutate_atomic``).
         Convenience modes always pass a ``str`` hash; the dict form is
-        only reachable via direct mode='set' callers.
+        only reachable via direct mode='set' callers. The hash check still
+        runs against the provided snapshot as a defensive guard.
+
+        ``validate_only`` is forwarded to ``_shape_check`` and lets a caller
+        scope the per-entry check to specific top-level keys / indices.
+        Convenience-mode writes pass the appended tail indices so
+        pre-existing (HA-validated) entries are not re-validated against the
+        local schema — see issue #1086.
         """
         try:
             # 1. Shape check (fast local, fail closed)
-            shape_errors = _shape_check(config)
+            shape_errors = _shape_check(config, validate_only=validate_only)
             if shape_errors:
                 raise_tool_error(
                     create_error_response(
@@ -1176,7 +1249,7 @@ class EnergyTools:
         dry_run: bool,
         preview_payload: dict[str, Any],
     ) -> dict[str, Any]:
-        """Read-modify-write loop for convenience modes.
+        """Run convenience-mode read-modify-write with dry-run backstop and hash-conflict retry.
 
         Atomicity is with respect to the *entire* prefs snapshot, not just
         ``target_key``: ``_set_prefs`` validates the full ``config_hash``, so
@@ -1205,9 +1278,14 @@ class EnergyTools:
                 new_list = mutator(existing_list)
 
                 # Backstop shape-check, mirroring the real-run path through
-                # ``_set_prefs`` — keeps dry_run/real-run shape-equivalent
-                # if the entry-construction logic ever changes.
-                shape_errors = _shape_check({target_key: new_list})
+                # ``_set_prefs`` — keeps dry_run/real-run shape-equivalent if
+                # the entry-construction logic ever changes. See
+                # ``_appended_tail_indices`` for the validate_only contract.
+                appended_indices = _appended_tail_indices(existing_list, new_list)
+                shape_errors = _shape_check(
+                    {target_key: new_list},
+                    validate_only={target_key: appended_indices},
+                )
                 if shape_errors:
                     raise_tool_error(
                         create_error_response(
@@ -1241,11 +1319,17 @@ class EnergyTools:
                 new_list = mutator(existing_list)
 
                 partial_config = {target_key: new_list}
+                # Per issue #1086: validate only the appended tail so a
+                # pre-existing HA-validated entry cannot block an unrelated
+                # add/remove. See ``_appended_tail_indices`` for the
+                # validate_only contract.
+                appended_indices = _appended_tail_indices(existing_list, new_list)
                 try:
                     set_result = await self._set_prefs(
                         partial_config,
                         current_hash,
                         current_prefs=current_config,
+                        validate_only={target_key: appended_indices},
                     )
                 except ToolError as exc:
                     # _set_prefs raises ToolError(RESOURCE_LOCKED) on hash mismatch.
@@ -1289,10 +1373,21 @@ class EnergyTools:
             # Unreachable as long as every iteration either returns or raises:
             # the only ``continue`` is gated on ``attempt + 1 < max_attempts``,
             # which is False on the final iteration — so the bare ``raise``
-            # in the except block always fires there.
-            raise AssertionError(
-                f"_mutate_atomic({mode}, {target_key}): "
-                "retry loop exited without a return or raise"
+            # in the except block always fires there. Surface as an actionable
+            # structured error rather than a bare AssertionError that would
+            # otherwise fall through to ``except Exception`` and lose context.
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.INTERNAL_ERROR,
+                    f"_mutate_atomic({mode}, {target_key}): retry loop exited "
+                    "without a return or raise",
+                    context={"mode": mode, "target_key": target_key},
+                    suggestions=[
+                        "This indicates a bug in the optimistic-concurrency "
+                        "loop logic — please file an issue with the mode and "
+                        "target_key from the context.",
+                    ],
+                )
             )
 
         except ToolError:

ha_mcp_dev-7.4.1.dev429/src/ha_mcp/utils/kill_signal_diagnostics.py

@@ -0,0 +1,488 @@
+"""Kill-signal diagnostics for the HA MCP add-on.
+
+Opt-in (gated by the "Advanced debug logging" addon toggle) signal handler
+that, on SIGTERM/SIGINT/SIGHUP, captures and logs:
+
+- Signal name + ``si_code`` (USER/KERNEL/QUEUE/TKILL/...).
+- Sender PID + its ``comm`` and ``cmdline`` from ``/proc/<pid>``, captured
+  via ``sigaction(SA_SIGINFO)`` through ``ctypes`` so we can read
+  ``siginfo_t`` (Python's ``signal.signal`` only sees ``signum``).
+- ``/proc/self/status`` snapshot of memory + OOM context.
+
+Then chains to whatever handler was previously installed (typically
+uvicorn's ``handle_exit`` for SIGTERM/SIGINT) so the server still shuts
+down cleanly. SIGHUP, which uvicorn doesn't capture, falls back to
+libc-direct ``SIG_DFL`` + re-raise. Linux-only by design.
+
+Without this, the addon only sees that ``mcp.run()`` returned cleanly —
+it can't tell whether Supervisor sent SIGTERM, the OOM killer fired, a
+container watchdog acted, or something else.
+
+Install ordering
+----------------
+``signal.signal(...)`` from CPython calls libc's ``sigaction`` with no
+``SA_SIGINFO`` flag, which overwrites any ``SA_SIGINFO`` handler we
+installed first. uvicorn's ``Server.capture_signals()`` does exactly
+this for SIGTERM and SIGINT immediately after ``serve()`` enters. So
+installing from ``start.py`` *before* ``mcp.run()`` would silently lose
+the SA_SIGINFO bit before any signal arrives.
+
+``schedule_install_after_uvicorn`` spawns a daemon thread that polls
+``signal.getsignal`` until uvicorn's handler is detected (or a timeout
+elapses), then calls ``install_kill_signal_diagnostics`` which captures
+the existing handler and overlays SA_SIGINFO on top. The handler chains
+to the captured handler so uvicorn still receives the shutdown signal.
+
+Async-signal-safety
+-------------------
+The handler is best-effort, not strict POSIX AS-safe:
+
+- It does **not** call any code that takes Python-level locks; the
+  ``usage_logger`` ring buffer is intentionally excluded because its
+  ``threading.Lock`` is held by the main thread during normal tool calls
+  and would deadlock the handler.
+- It uses ``os.write(STDERR_FILENO, ...)`` (AS-safe) instead of ``print``.
+- It chains to the captured uvicorn handler in pure Python (uvicorn's
+  ``handle_exit`` only sets attributes — synchronous, no locks). The
+  fallback re-raise path uses ``libc.signal(sig, SIG_DFL)`` and
+  ``kill(2)`` directly (both AS-safe).
+- ``/proc`` reads use ``open(2)``, which POSIX classifies as not strictly
+  AS-safe. In practice the kernel side of ``/proc`` doesn't take
+  userspace-allocator locks, so this is acceptable for an opt-in
+  diagnostic.
+
+ctypes adds one more theoretical risk: the trampoline acquires the GIL
+on entry to Python code. In a single-threaded asyncio event loop (this
+addon's shape) the GIL acquisition is a no-op when the handler runs on
+the main thread. Multi-threaded callers should evaluate before enabling.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import logging
+import os
+import signal
+import sys
+import threading
+import time
+from collections.abc import Callable
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# SIGKILL/SIGSTOP omitted — uncatchable by design.
+_INSTRUMENTED_SIGNALS = (signal.SIGTERM, signal.SIGINT, signal.SIGHUP)
+
+# si_code constants from Linux's <asm-generic/siginfo.h>. Pinned in
+# tests so a wrong value can't silently mislabel diagnostics.
+_SI_CODE_NAMES = {
+    0: "SI_USER",
+    0x80: "SI_KERNEL",
+    -1: "SI_QUEUE",
+    -2: "SI_TIMER",
+    -3: "SI_MESGQ",
+    -4: "SI_ASYNCIO",
+    -5: "SI_SIGIO",
+    -6: "SI_TKILL",
+}
+
+
+class _Siginfo(ctypes.Structure):
+    """Minimal ``siginfo_t`` for kill-style signals.
+
+    Linux's ``siginfo_t`` is arch-dependent: on architectures without
+    ``__ARCH_HAS_SWAPPED_SIGINFO`` (x86, x86_64, arm, aarch64 — all of
+    the addon's target arches), the leading layout is ``si_signo``,
+    ``si_errno``, ``si_code``, then the ``_kill`` union starting with
+    ``si_pid`` / ``si_uid``. Trailing bytes are reserved padding from
+    the kernel's ``SI_MAX_SIZE = 128``.
+    """
+
+    _fields_ = [
+        ("si_signo", ctypes.c_int),
+        ("si_errno", ctypes.c_int),
+        ("si_code", ctypes.c_int),
+        ("_pad0", ctypes.c_int),  # 64-bit alignment for the _kill union
+        ("si_pid", ctypes.c_int),
+        ("si_uid", ctypes.c_uint),
+        # Pad out to the kernel's SI_MAX_SIZE so libc writes the full
+        # union without truncating.
+        ("_tail", ctypes.c_byte * 104),
+    ]
+
+
+# Pinned by SI_MAX_SIZE in the kernel. If a future ctypes change shifts
+# field offsets, fail loudly at import rather than during signal delivery.
+assert ctypes.sizeof(_Siginfo) == 128, (
+    f"_Siginfo size {ctypes.sizeof(_Siginfo)} != kernel SI_MAX_SIZE 128"
+)
+assert _Siginfo.si_pid.offset == 16, (
+    f"_Siginfo.si_pid offset {_Siginfo.si_pid.offset} != expected 16"
+)
+assert _Siginfo.si_uid.offset == 20, (
+    f"_Siginfo.si_uid offset {_Siginfo.si_uid.offset} != expected 20"
+)
+
+
+_SignalHandler = ctypes.CFUNCTYPE(None, ctypes.c_int, ctypes.POINTER(_Siginfo), ctypes.c_void_p)
+
+
+class _Sigaction(ctypes.Structure):
+    _fields_ = [
+        ("sa_sigaction", _SignalHandler),
+        ("sa_mask", ctypes.c_byte * 128),  # sigset_t — opaque, zeroed
+        ("sa_flags", ctypes.c_int),
+        ("sa_restorer", ctypes.c_void_p),
+    ]
+
+
+_SA_SIGINFO = 0x00000004
+_SA_RESTART = 0x10000000
+
+# SIG_DFL = 0 cast to a function pointer; libc.signal accepts this to
+# restore the kernel's default disposition.
+_SIG_DFL_PTR = ctypes.c_void_p(0)
+
+
+def read_proc_status_summary() -> dict[str, str]:
+    """Return a small dict of memory/OOM-relevant fields from /proc/self/status.
+
+    Empty dict on non-Linux or unreadable status — callers don't need
+    to special-case missing data.
+    """
+    fields = {"VmRSS", "VmHWM", "VmPeak", "Threads", "State", "oom_score", "oom_score_adj"}
+    out: dict[str, str] = {}
+    try:
+        with open("/proc/self/status", "rb") as f:
+            for raw_line in f:
+                line = raw_line.decode("utf-8", errors="replace")
+                key, _, value = line.partition(":")
+                if key in fields:
+                    out[key] = value.strip()
+    except OSError:
+        return {}
+    return out
+
+
+def read_proc_comm(pid: int) -> str:
+    """Return the ``comm`` (process name, ≤15 chars) for the given PID.
+
+    Empty string if the PID is gone or /proc isn't available. Reads as
+    bytes + ``errors="replace"`` because comm can contain arbitrary
+    bytes (set via ``prctl(PR_SET_NAME)``) — strict UTF-8 decode would
+    raise on those.
+    """
+    if pid <= 0:
+        return ""
+    try:
+        with open(f"/proc/{pid}/comm", "rb") as f:
+            return f.read().decode("utf-8", errors="replace").strip()
+    except OSError:
+        return ""
+
+
+def read_proc_cmdline(pid: int) -> str:
+    """Return the cmdline (argv joined by spaces) for the given PID.
+
+    Cmdline can be more informative than ``comm`` (which is truncated to
+    15 chars and often shows just "supervisor" for many distinct
+    binaries). Empty string if unavailable.
+    """
+    if pid <= 0:
+        return ""
+    try:
+        with open(f"/proc/{pid}/cmdline", "rb") as f:
+            raw = f.read()
+    except OSError:
+        return ""
+    return raw.replace(b"\x00", b" ").decode("utf-8", errors="replace").strip()
+
+
+def format_diagnostic_block(
+    *,
+    signum: int,
+    si_code: int,
+    sender_pid: int,
+    sender_comm: str,
+    sender_cmdline: str,
+    proc_status: dict[str, str],
+) -> str:
+    """Compose the multi-line log block written when a signal is caught."""
+    sig_name = signal.Signals(signum).name if signum in signal.Signals.__members__.values() else str(signum)
+    code_name = _SI_CODE_NAMES.get(si_code, f"SI_UNKNOWN({si_code})")
+
+    # si_pid == 0 from the kernel means the sender was outside our PID
+    # namespace (typically Supervisor or the host) — its PID didn't
+    # translate, so /proc/0/{comm,cmdline} can't resolve. Render an
+    # explicit label so the diagnostic isn't read as "we failed to
+    # capture the sender" — the cross-namespace case is itself the
+    # signal in #1109-style reports.
+    if sender_pid == 0:
+        sender_pid_str = "0 (cross-namespace; likely Supervisor or host process)"
+        sender_comm_str = "<cross-namespace>"
+        sender_cmdline_str = "<cross-namespace>"
+    else:
+        sender_pid_str = str(sender_pid)
+        sender_comm_str = sender_comm or "<unavailable>"
+        sender_cmdline_str = sender_cmdline or "<unavailable>"
+
+    lines = [
+        "=" * 80,
+        "ADVANCED DEBUG LOGGING — kill-signal diagnostics",
+        "=" * 80,
+        f"Signal:         {sig_name} ({signum})",
+        f"si_code:        {code_name}",
+        f"Sender PID:     {sender_pid_str}",
+        f"Sender comm:    {sender_comm_str}",
+        f"Sender cmdline: {sender_cmdline_str}",
+        "",
+        "Process state (from /proc/self/status):",
+    ]
+    if proc_status:
+        lines.extend(
+            f"  {key}: {proc_status[key]}"
+            for key in ("State", "VmRSS", "VmHWM", "VmPeak", "Threads", "oom_score", "oom_score_adj")
+            if key in proc_status
+        )
+    else:
+        lines.append("  <unavailable — non-Linux or /proc not mounted>")
+    lines.append("=" * 80)
+    return "\n".join(lines)
+
+
+# Module-level reference set so the kernel-installed pointer isn't GC'd
+# mid-flight. Comment exists because the variable looks unused — without
+# it a future maintainer will delete it and ship a use-after-free.
+_handler_refs: list[Any] = []
+_libc: Any = None
+# Captured at install time so our handler can chain back to whatever
+# was installed before (typically uvicorn's handle_exit).
+_chained_handlers: dict[int, Any] = {}
+
+
+def _emit_block_safely(block: str) -> None:
+    """Write ``block`` to stderr using only async-signal-safe primitives."""
+    payload = (block + "\n").encode("utf-8", errors="replace")
+    try:
+        os.write(2, payload)
+    except OSError:
+        pass
+
+
+def _restore_default_and_reraise(signum: int) -> None:
+    """Reset disposition to SIG_DFL via direct libc and re-raise.
+
+    Uses ``libc.signal(signum, SIG_DFL)`` (AS-safe) instead of Python's
+    ``signal.signal`` because the latter mutates CPython signal-state
+    bookkeeping that assumes main-thread + bytecode-boundary calls.
+    """
+    if _libc is not None:
+        try:
+            _libc.signal(int(signum), _SIG_DFL_PTR)
+        except OSError:
+            pass
+    os.kill(os.getpid(), signum)
+
+
+def _chain_or_reraise(signum: int) -> None:
+    """Hand control to the previously-installed handler, or re-raise default.
+
+    Uvicorn's ``handle_exit`` only sets ``self.should_exit`` (synchronous,
+    no locks), so calling it directly from this trampoline is safe.
+    """
+    chained = _chained_handlers.get(signum)
+    if callable(chained):
+        try:
+            chained(signum, None)
+            return
+        except Exception:
+            # Fall through to the default-disposition path so the
+            # process still terminates if the chained handler explodes.
+            pass
+    _restore_default_and_reraise(signum)
+
+
+def _make_handler() -> Any:
+    """Build the C-callable signal handler closure.
+
+    Returns a ``_SignalHandler`` (``ctypes.CFUNCTYPE`` instance), typed
+    as ``Any`` because Pyright doesn't accept dynamically-generated
+    ctypes function-pointer types in static type expressions.
+    """
+
+    def _handler(signum: int, info_ptr: Any, _ucontext: int) -> None:
+        try:
+            info = info_ptr.contents
+            si_code = int(info.si_code)
+            sender_pid = int(info.si_pid)
+            block = format_diagnostic_block(
+                signum=signum,
+                si_code=si_code,
+                sender_pid=sender_pid,
+                sender_comm=read_proc_comm(sender_pid),
+                sender_cmdline=read_proc_cmdline(sender_pid),
+                proc_status=read_proc_status_summary(),
+            )
+            _emit_block_safely(block)
+        except Exception as exc:  # pragma: no cover — last-resort safety
+            try:
+                os.write(
+                    2,
+                    f"advanced_debug_logging handler failed for signal {signum}: {exc!r}\n".encode(
+                        "utf-8", errors="replace"
+                    ),
+                )
+            except OSError:
+                pass
+
+        _chain_or_reraise(signum)
+
+    return _SignalHandler(_handler)
+
+
+def install_kill_signal_diagnostics() -> bool:
+    """Install the SA_SIGINFO signal handler.
+
+    Captures any previously-installed handler (e.g. uvicorn's
+    ``handle_exit``) via ``signal.getsignal`` so the SA_SIGINFO handler
+    can chain to it. Idempotent — second call is a no-op.
+
+    Returns True if at least one signal was installed; False on
+    non-Linux, missing libc, or if every sigaction call failed. Never
+    raises: callers don't need to wrap in try/except. This contract is
+    load-bearing — diagnostics must not block addon startup.
+    """
+    global _libc
+
+    if sys.platform != "linux":
+        logger.warning(
+            "advanced_debug_logging is Linux-only; skipping signal handler install on %s",
+            sys.platform,
+        )
+        return False
+
+    if _handler_refs:
+        logger.warning(
+            "advanced_debug_logging: install_kill_signal_diagnostics already called; skipping"
+        )
+        return True
+
+    try:
+        libc_path = ctypes.util.find_library("c")
+        if libc_path is None:
+            logger.warning("advanced_debug_logging: libc not found; skipping signal handler install")
+            return False
+
+        libc = ctypes.CDLL(libc_path, use_errno=True)
+        libc.sigaction.restype = ctypes.c_int
+        libc.sigaction.argtypes = [ctypes.c_int, ctypes.POINTER(_Sigaction), ctypes.POINTER(_Sigaction)]
+        # signal(int, sighandler_t) — used by the handler itself to
+        # restore SIG_DFL via the AS-safe libc entry point.
+        libc.signal.restype = ctypes.c_void_p
+        libc.signal.argtypes = [ctypes.c_int, ctypes.c_void_p]
+        _libc = libc
+
+        # Snapshot the existing handler for each instrumented signal
+        # before we overwrite. This is what we chain back to so uvicorn
+        # (or whoever was there) still receives the shutdown signal.
+        for sig in _INSTRUMENTED_SIGNALS:
+            existing = signal.getsignal(int(sig))
+            if callable(existing):
+                _chained_handlers[int(sig)] = existing
+
+        handler = _make_handler()
+        _handler_refs.append(handler)
+
+        sa = _Sigaction()
+        ctypes.memset(ctypes.byref(sa), 0, ctypes.sizeof(sa))
+        sa.sa_sigaction = handler
+        sa.sa_flags = _SA_SIGINFO | _SA_RESTART
+        _handler_refs.append(sa)
+
+        installed_for: list[str] = []
+        for sig in _INSTRUMENTED_SIGNALS:
+            rc = libc.sigaction(int(sig), ctypes.byref(sa), None)
+            if rc != 0:
+                err = ctypes.get_errno()
+                logger.warning(
+                    "advanced_debug_logging: sigaction(%s) failed: errno=%d",
+                    sig.name,
+                    err,
+                )
+                continue
+            installed_for.append(sig.name)
+    except Exception as exc:
+        logger.warning(
+            "advanced_debug_logging: install failed (%r); continuing without diagnostics",
+            exc,
+        )
+        _handler_refs.clear()
+        _chained_handlers.clear()
+        _libc = None
+        return False
+
+    if installed_for:
+        chained_signals = sorted(signal.Signals(s).name for s in _chained_handlers)
+        logger.info(
+            "advanced_debug_logging enabled — kill-signal diagnostics installed for: %s "
+            "(chains to existing handlers for: %s)",
+            ", ".join(installed_for),
+            ", ".join(chained_signals) or "<none>",
+        )
+        return True
+    _handler_refs.clear()
+    _chained_handlers.clear()
+    _libc = None
+    return False
+
+
+def schedule_install_after_uvicorn(
+    *,
+    timeout_secs: float = 10.0,
+    poll_interval_secs: float = 0.1,
+    install: Callable[[], bool] = install_kill_signal_diagnostics,
+) -> threading.Thread:
+    """Defer install until uvicorn's ``capture_signals()`` has run.
+
+    uvicorn's ``Server.capture_signals()`` calls
+    ``signal.signal(SIGTERM/SIGINT, handle_exit)`` immediately after
+    ``Server.serve()`` enters. Python's ``signal.signal`` reaches libc's
+    ``sigaction`` *without* ``SA_SIGINFO``, so any handler we installed
+    before ``mcp.run()`` would lose its SA_SIGINFO bit before any signal
+    arrived. This polls ``signal.getsignal(SIGTERM)`` from a daemon
+    thread until uvicorn replaces the default disposition, then calls
+    ``install`` so our SA_SIGINFO handler lands on top and chains to
+    uvicorn's ``handle_exit``.
+
+    If uvicorn never installs (e.g. addon was started without HTTP
+    transport), install runs anyway after ``timeout_secs``.
+
+    Returns the started thread so callers can ``.join()`` in tests.
+    """
+
+    def _wait_then_install() -> None:
+        deadline = time.monotonic() + timeout_secs
+        while time.monotonic() < deadline:
+            current = signal.getsignal(signal.SIGTERM)
+            if callable(current) and current not in (signal.SIG_DFL, signal.SIG_IGN):
+                logger.debug(
+                    "advanced_debug_logging: detected uvicorn signal handler; installing on top"
+                )
+                install()
+                return
+            time.sleep(poll_interval_secs)
+        logger.info(
+            "advanced_debug_logging: uvicorn handler not detected within %.1fs; installing anyway",
+            timeout_secs,
+        )
+        install()
+
+    thread = threading.Thread(
+        target=_wait_then_install,
+        name="kill-signal-diagnostics-install",
+        daemon=True,
+    )
+    thread.start()
+    return thread

{ha_mcp_dev-7.4.1.dev427 → ha_mcp_dev-7.4.1.dev429/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev427
+Version: 7.4.1.dev429
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.4.1.dev427 → ha_mcp_dev-7.4.1.dev429}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -89,6 +89,7 @@ src/ha_mcp/utils/__init__.py
 src/ha_mcp/utils/config_hash.py
 src/ha_mcp/utils/domain_handlers.py
 src/ha_mcp/utils/fuzzy_search.py
+src/ha_mcp/utils/kill_signal_diagnostics.py
 src/ha_mcp/utils/operation_manager.py
 src/ha_mcp/utils/python_sandbox.py
 src/ha_mcp/utils/usage_logger.py