fix: prevent telemetry from causing CLI hangs

- Defer OpenPanel import until telemetry is actually enabled
- Add _is_telemetry_enabled() to check config before creating client
- Add shutdown_telemetry() to properly stop OpenPanel's background thread
- Call shutdown_telemetry() from run_with_cleanup()

The OpenPanel library creates a background thread with an event loop
that can cause hangs when the telemetry endpoint is unreachable (firewall,
network issues) due to requests.post() having no timeout. By not creating
the client when telemetry is disabled, we avoid the background thread entirely.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/cli/commands/command_utils.py

@@ -14,6 +14,7 @@
 from basic_memory.mcp.tools.utils import call_post, call_get
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.schemas import ProjectInfoResponse
+from basic_memory.telemetry import shutdown_telemetry
 
 console = Console()
 
@@ -23,8 +24,8 @@
 def run_with_cleanup(coro: Coroutine[Any, Any, T]) -> T:
     """Run an async coroutine with proper database cleanup.
 
-    This helper ensures database connections are cleaned up before the event
-    loop closes, preventing process hangs in CLI commands.
+    This helper ensures database connections and telemetry threads are cleaned up
+    before the event loop closes, preventing process hangs in CLI commands.
 
     Args:
         coro: The coroutine to run
@@ -38,6 +39,9 @@ async def _with_cleanup() -> T:
             return await coro
         finally:
             await db.shutdown_db()
+            # Shutdown telemetry to stop the OpenPanel background thread
+            # This prevents hangs on Python 3.14+ during thread shutdown
+            shutdown_telemetry()
 
     return asyncio.run(_with_cleanup())
 

src/basic_memory/telemetry.py

@@ -19,17 +19,21 @@
 Documentation: https://basicmemory.com/telemetry
 """
 
+from __future__ import annotations
+
 import platform
 import re
 import uuid
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from loguru import logger
-from openpanel import OpenPanel
 
 from basic_memory import __version__
 
+if TYPE_CHECKING:
+    from openpanel import OpenPanel
+
 # --- Configuration ---
 
 # OpenPanel credentials (write-only, safe to embed in client code)
@@ -51,6 +55,29 @@
 
 _client: OpenPanel | None = None
 _initialized: bool = False
+_telemetry_enabled: bool | None = None  # Cached to avoid repeated config reads
+
+
+# --- Telemetry State ---
+
+
+def _is_telemetry_enabled() -> bool:
+    """Check if telemetry is enabled (cached).
+
+    Returns False if:
+    - User disabled via `bm telemetry disable`
+    - DO_NOT_TRACK environment variable is set
+    - Running in test environment
+    """
+    global _telemetry_enabled
+
+    if _telemetry_enabled is None:
+        from basic_memory.config import ConfigManager
+
+        config = ConfigManager().config
+        _telemetry_enabled = config.telemetry_enabled and not config.is_test_env
+
+    return _telemetry_enabled
 
 
 # --- Installation ID ---
@@ -76,30 +103,31 @@ def get_install_id() -> str:
 # --- Client Management ---
 
 
-def _get_client() -> OpenPanel:
+def _get_client() -> OpenPanel | None:
     """Get or create the OpenPanel client (singleton).
 
     Lazily initializes the client with global properties.
+    Returns None if telemetry is disabled (avoids creating background thread).
     """
     global _client, _initialized
 
-    if _client is None:
-        from basic_memory.config import ConfigManager
+    # Trigger: telemetry disabled via config, env var, or test mode
+    # Why: OpenPanel creates a background thread even when disabled=True,
+    #      which can cause hangs on Python 3.14 during thread shutdown
+    # Outcome: return None early, no OpenPanel client or thread created
+    if not _is_telemetry_enabled():
+        return None
 
-        config = ConfigManager().config
+    if _client is None:
+        # Defer import to avoid creating background thread when telemetry disabled
+        from openpanel import OpenPanel
 
-        # Trigger: first call to track an event
-        # Why: lazy init avoids work if telemetry never used; disabled flag
-        #      tells OpenPanel to skip network calls when user opts out or during tests
-        # Outcome: client ready to queue events (or silently discard if disabled)
-        is_disabled = not config.telemetry_enabled or config.is_test_env
         _client = OpenPanel(
             client_id=OPENPANEL_CLIENT_ID,
             client_secret=OPENPANEL_CLIENT_SECRET,
-            disabled=is_disabled,
         )
 
-        if config.telemetry_enabled and not config.is_test_env and not _initialized:
+        if not _initialized:
             # Set global properties that go with every event
             _client.set_global_properties(
                 {
@@ -118,9 +146,29 @@ def _get_client() -> OpenPanel:
 
 def reset_client() -> None:
     """Reset the telemetry client (for testing or after config changes)."""
-    global _client, _initialized
+    global _client, _initialized, _telemetry_enabled
     _client = None
     _initialized = False
+    _telemetry_enabled = None
+
+
+def shutdown_telemetry() -> None:
+    """Shutdown the telemetry client, stopping its background thread.
+
+    Call this on application exit to ensure clean shutdown.
+    The OpenPanel client creates a background thread with an event loop
+    that needs to be stopped to avoid hangs on Python 3.14+.
+    """
+    global _client
+
+    if _client is not None:
+        try:
+            # OpenPanel._cleanup stops the event loop and joins the thread
+            _client._cleanup()
+        except Exception as e:
+            logger.opt(exception=False).debug(f"Telemetry shutdown failed: {e}")
+        finally:
+            _client = None
 
 
 # --- Event Tracking ---
@@ -136,7 +184,9 @@ def track(event: str, properties: dict[str, Any] | None = None) -> None:
     # Constraint: telemetry must never break the application
     # Even if OpenPanel API is down or config is corrupt, user's command must succeed
     try:
-        _get_client().track(event, properties or {})
+        client = _get_client()
+        if client is not None:
+            client.track(event, properties or {})
     except Exception as e:
         logger.opt(exception=False).debug(f"Telemetry failed: {e}")
 

tests/test_telemetry.py

@@ -88,18 +88,20 @@ def test_track_does_not_raise_on_error(self, config_home, monkeypatch):
 
         basic_memory.config._CONFIG_CACHE = None
         telemetry.reset_client()
+        # Force telemetry to be enabled for this test
+        monkeypatch.setattr(telemetry, "_is_telemetry_enabled", lambda: True)
 
         # Replace OpenPanel with a stub that raises on track
         stub_client = _StubOpenPanel(client_id="id", client_secret="sec", disabled=False)
         stub_client.raise_on_track = Exception("Network error")
 
-        def openpanel_factory(*, client_id, client_secret, disabled=False):
+        def openpanel_factory(*, client_id, client_secret):
             stub_client.client_id = client_id
             stub_client.client_secret = client_secret
-            stub_client.disabled = disabled
             return stub_client
 
-        monkeypatch.setattr(telemetry, "OpenPanel", openpanel_factory)
+        # Mock the import inside _get_client()
+        monkeypatch.setattr("openpanel.OpenPanel", openpanel_factory)
 
         # Should not raise
         telemetry.track("test_event", {"key": "value"})
@@ -115,16 +117,16 @@ def test_track_respects_disabled_config(self, config_home, monkeypatch):
 
         created: list[_StubOpenPanel] = []
 
-        def openpanel_factory(*, client_id, client_secret, disabled=False):
-            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=disabled)
+        def openpanel_factory(*, client_id, client_secret):
+            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=False)
             created.append(client)
             return client
 
-        monkeypatch.setattr(telemetry, "OpenPanel", openpanel_factory)
+        monkeypatch.setattr("openpanel.OpenPanel", openpanel_factory)
 
         telemetry.track("test_event")
-        assert len(created) == 1
-        assert created[0].disabled is True
+        # With disabled config, OpenPanel client is never created (early return)
+        assert len(created) == 0
 
 
 class TestShowNoticeIfNeeded:
@@ -181,15 +183,17 @@ def test_track_app_started(self, config_home, monkeypatch):
 
         basic_memory.config._CONFIG_CACHE = None
         telemetry.reset_client()
+        # Force telemetry to be enabled for this test (pytest sets PYTEST_CURRENT_TEST)
+        monkeypatch.setattr(telemetry, "_is_telemetry_enabled", lambda: True)
 
         created: list[_StubOpenPanel] = []
 
-        def openpanel_factory(*, client_id, client_secret, disabled=False):
-            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=disabled)
+        def openpanel_factory(*, client_id, client_secret):
+            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=False)
             created.append(client)
             return client
 
-        monkeypatch.setattr(telemetry, "OpenPanel", openpanel_factory)
+        monkeypatch.setattr("openpanel.OpenPanel", openpanel_factory)
 
         telemetry.track_app_started("cli")
         assert created
@@ -201,15 +205,17 @@ def test_track_mcp_tool(self, config_home, monkeypatch):
 
         basic_memory.config._CONFIG_CACHE = None
         telemetry.reset_client()
+        # Force telemetry to be enabled for this test
+        monkeypatch.setattr(telemetry, "_is_telemetry_enabled", lambda: True)
 
         created: list[_StubOpenPanel] = []
 
-        def openpanel_factory(*, client_id, client_secret, disabled=False):
-            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=disabled)
+        def openpanel_factory(*, client_id, client_secret):
+            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=False)
             created.append(client)
             return client
 
-        monkeypatch.setattr(telemetry, "OpenPanel", openpanel_factory)
+        monkeypatch.setattr("openpanel.OpenPanel", openpanel_factory)
 
         telemetry.track_mcp_tool("write_note")
         assert created
@@ -221,15 +227,17 @@ def test_track_error_truncates_message(self, config_home, monkeypatch):
 
         basic_memory.config._CONFIG_CACHE = None
         telemetry.reset_client()
+        # Force telemetry to be enabled for this test
+        monkeypatch.setattr(telemetry, "_is_telemetry_enabled", lambda: True)
 
         created: list[_StubOpenPanel] = []
 
-        def openpanel_factory(*, client_id, client_secret, disabled=False):
-            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=disabled)
+        def openpanel_factory(*, client_id, client_secret):
+            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=False)
             created.append(client)
             return client
 
-        monkeypatch.setattr(telemetry, "OpenPanel", openpanel_factory)
+        monkeypatch.setattr("openpanel.OpenPanel", openpanel_factory)
 
         telemetry.track_error("ValueError", "x" * 500)
         _, props = created[0].events[-1]
@@ -241,15 +249,17 @@ def test_track_error_sanitizes_file_paths(self, config_home, monkeypatch):
 
         basic_memory.config._CONFIG_CACHE = None
         telemetry.reset_client()
+        # Force telemetry to be enabled for this test
+        monkeypatch.setattr(telemetry, "_is_telemetry_enabled", lambda: True)
 
         created: list[_StubOpenPanel] = []
 
-        def openpanel_factory(*, client_id, client_secret, disabled=False):
-            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=disabled)
+        def openpanel_factory(*, client_id, client_secret):
+            client = _StubOpenPanel(client_id=client_id, client_secret=client_secret, disabled=False)
             created.append(client)
             return client
 
-        monkeypatch.setattr(telemetry, "OpenPanel", openpanel_factory)
+        monkeypatch.setattr("openpanel.OpenPanel", openpanel_factory)
 
         telemetry.track_error("FileNotFoundError", "No such file: /Users/john/notes/secret.md")
         _, props = created[0].events[-1]
@@ -259,7 +269,7 @@ def openpanel_factory(*, client_id, client_secret, disabled=False):
         telemetry.reset_client()
         created.clear()
 
-        monkeypatch.setattr(telemetry, "OpenPanel", openpanel_factory)
+        monkeypatch.setattr("openpanel.OpenPanel", openpanel_factory)
         telemetry.track_error("FileNotFoundError", "Cannot open C:\\Users\\john\\docs\\private.txt")
         _, props = created[0].events[-1]
         assert "C:\\Users\\john" not in props["message"]