fix(telemetry): classify setup-mode TUI preflight and preparation failures

error events now carry phase (startup/preflight/sandbox_init/agent_setup/
agent_loop) and the exception class name (plus its cause), never the message
or trace. Startup and preflight failures that exit(1) before the scan starts
are beaconed with a stable error_type instead of vanishing. scan_ended
distinguishes budget_exceeded, rate_limited, and headless agent_stopped
from user_exit.

strix/core/runner.py

@@ -45,6 +45,7 @@ from strix.core.paths import run_dir_for, runtime_state_dir
 from strix.core.sessions import open_agent_session
 from strix.report.state import get_global_report_state
 from strix.runtime import session_manager
+from strix.telemetry import set_scan_phase
 from strix.telemetry.logging import set_scan_id, setup_scan_logging
 from strix.tools.output_store import (
     WORKSPACE_SPILL_DIR,
@@ -116,6 +117,13 @@ def _record_mcp_connections(connections: list[ConnectedMcpServer]) -> None:
     report_state.record_mcp_connections([connection.name for connection in connections])
 
 
+def _note_exit_reason(reason: str) -> None:
+    """Record why the scan stopped so the end-of-scan beacon reports it."""
+    report_state = get_global_report_state()
+    if report_state is not None and report_state.scan_ended_exit_reason is None:
+        report_state.scan_ended_exit_reason = reason
+
+
 def _persist_mcp_status(roster: list[dict[str, Any]]) -> None:
     """Write the run's non-secret MCP connection status roster to run.json.
 
@@ -313,6 +321,7 @@ async def run_strix_scan(
         root_id = uuid.uuid4().hex[:8]
 
     logger.info("Bringing up sandbox session for scan %s", scan_id)
+    set_scan_phase("sandbox_init")
     bundle = await session_manager.create_or_reuse(
         scan_id,
         image=image,
@@ -322,6 +331,7 @@ async def run_strix_scan(
     )
     report("Waiting for the first model response")
     logger.info("Sandbox ready for scan %s", scan_id)
+    set_scan_phase("agent_setup")
 
     sandbox_session = bundle["session"]
 
@@ -573,6 +583,7 @@ async def run_strix_scan(
         async with coordinator._lock:
             root_status = coordinator.statuses.get(root_id)
 
+        set_scan_phase("agent_loop")
         result = await run_agent_loop(
             agent=root_agent,
             initial_input=initial_input,
@@ -610,6 +621,7 @@ async def run_strix_scan(
         return result  # noqa: TRY300
     except BudgetExceededError as exc:
         logger.info("Scan %s stopped: %s", scan_id, exc)
+        _note_exit_reason("budget_exceeded")
         if root_id is not None:
             with contextlib.suppress(Exception):
                 await coordinator.set_status(root_id, "stopped")
@@ -622,6 +634,7 @@ async def run_strix_scan(
             exc,
             scan_id,
         )
+        _note_exit_reason("rate_limited")
         if root_id is not None:
             with contextlib.suppress(Exception):
                 await coordinator.set_status(root_id, "stopped")

strix/interface/environment.py

@@ -14,6 +14,7 @@ from strix.interface.utils import (
     image_exists,
     process_pull_line,
 )
+from strix.telemetry import report_error
 
 
 logger = logging.getLogger(__name__)
@@ -44,6 +45,7 @@ def validate_environment() -> None:
                 f"[red]STRIX_LLM={settings.llm.model} uses your ChatGPT subscription, "
                 "but you're not signed in.[/] Run [cyan]strix auth login chatgpt[/] first."
             )
+            report_error("subscription_not_signed_in")
             sys.exit(1)
         logger.info("Environment OK (ChatGPT subscription)")
         return
@@ -153,6 +155,7 @@ def validate_environment() -> None:
         console.print("\n")
         console.print(panel)
         console.print()
+        report_error("missing_required_config")
         sys.exit(1)
     logger.info(
         "Environment OK (optional missing: %s)",
@@ -180,6 +183,7 @@ def check_docker_installed() -> None:
             padding=(1, 2),
         )
         console.print("\n", panel, "\n")
+        report_error("docker_not_installed")
         sys.exit(1)
     logger.debug("Docker CLI present")
 
@@ -227,6 +231,7 @@ def pull_docker_image() -> None:
                 padding=(1, 2),
             )
             console.print(panel, "\n")
+            report_error("image_pull_failed", e)
             sys.exit(1)
 
     logger.info("Docker image %s ready", image)

strix/interface/main.py

@@ -41,7 +41,8 @@ from strix.interface.update_check import (
 from strix.interface.utils import (
     build_final_stats_text,
 )
-from strix.telemetry import posthog, scarf
+from strix.llm.warmup import start_import_warmup, wait_for_import_warmup
+from strix.telemetry import posthog, report_error, scarf, set_scan_phase
 from strix.telemetry.logging import configure_dependency_logging
 
 
@@ -395,15 +396,18 @@ def _bootstrap_scan(args: argparse.Namespace) -> None:
     happen inside the TUI so the interface paints immediately instead of
     waiting on a model round trip.
     """
+    set_scan_phase("preflight")
     try:
         asyncio.run(warm_up_llm(show_model_warning=True))
     except ModelConnectionError as exc:
+        report_error("model_connection_failed", exc)
         _print_model_connection_error(exc, exc.model_name)
         sys.exit(1)
     persist_current()
     try:
         prepare_run(args)
     except ValueError as e:
+        report_error("scan_preparation_failed", e)
         _print_error_panel("SCAN PREPARATION FAILED", str(e))
         sys.exit(1)
     telemetry_start(args)
@@ -450,8 +454,6 @@ def main() -> None:
 
         sys.exit(run_cloud(sys.argv[2:]))
 
-    from strix.llm.warmup import start_import_warmup
-
     start_import_warmup()
 
     args = parse_arguments()
@@ -466,6 +468,9 @@ def main() -> None:
     pull_docker_image()
     validate_environment()
 
+    # Everything below imports the scan engine; do not race the warm-up thread.
+    wait_for_import_warmup()
+
     if args.non_interactive:
         _bootstrap_scan(args)
 
@@ -477,18 +482,21 @@ def main() -> None:
             from strix.interface.cli import run_cli
 
             asyncio.run(run_cli(args))
+            # Headless runs have no user to quit: the agent either finished
+            # (already beaconed as finished_by_tool) or stopped on its own.
+            exit_reason = "agent_stopped"
         else:
             asyncio.run(run_tui(args))
     except InteractiveSetupUnavailableError as exc:
         exit_reason = "error"
+        report_error("interactive_setup_unavailable", exc)
         _print_error_panel("INTERACTIVE SETUP UNAVAILABLE", str(exc))
         sys.exit(1)
     except KeyboardInterrupt:
         exit_reason = "interrupted"
-    except Exception:
+    except Exception as exc:
         exit_reason = "error"
-        posthog.error("unhandled_exception")
-        scarf.error("unhandled_exception")
+        report_error("unhandled_exception", exc)
         raise
     finally:
         report_state = get_global_report_state()

strix/interface/tui/runtime.py

@@ -37,6 +37,7 @@ from strix.interface.tui.sidecar import (
 )
 from strix.interface.utils import read_workspace_files
 from strix.report.state import ReportState, set_global_report_state
+from strix.telemetry import report_error, set_scan_phase
 from strix.utils.resource_paths import get_strix_resource_path
 
 
@@ -138,11 +139,13 @@ class GoTuiRuntime:
             await self._preflight_model()
         except Exception as exc:
             logger.exception("Go TUI setup model preflight failed")
+            report_error("model_connection_failed", exc)
             raise RuntimeError(f"Model connection failed: {exc}") from exc
 
     async def _preflight_model(self) -> None:
         model = (load_settings().llm.model or "").strip()
         self.controller.add_message("Verifying model connection...")
+        set_scan_phase("preflight")
         await preflight_model_connection(model)
         self.model_verified = True
 
@@ -181,7 +184,11 @@ class GoTuiRuntime:
             candidate.target = list(self.controller.targets)
             candidate.target_list = []
             build_targets_info(candidate)
-        prepare_run(candidate)
+        try:
+            prepare_run(candidate)
+        except Exception as exc:
+            report_error("scan_preparation_failed", exc)
+            raise
         telemetry_start(candidate)
 
         vars(self.args).update(vars(candidate))
@@ -195,13 +202,21 @@ class GoTuiRuntime:
         launch so the interface appears immediately.
         """
         model = (load_settings().llm.model or "").strip()
+        set_scan_phase("preflight")
         try:
             await preflight_model_connection(model)
+        except Exception as exc:
+            logger.exception("Go TUI scan preparation failed")
+            report_error("model_connection_failed", exc)
+            self.controller.fail_preparation(str(exc))
+            return
+        try:
             persist_current()
             prepare_run(self.args)
             telemetry_start(self.args)
         except Exception as exc:
             logger.exception("Go TUI scan preparation failed")
+            report_error("scan_preparation_failed", exc)
             self.controller.fail_preparation(str(exc))
             return
         self.controller.scan_state = "running"
@@ -240,6 +255,9 @@ class GoTuiRuntime:
             self.controller.scan_state = "completed" if report_status == "completed" else "stopped"
         except Exception as exc:
             logger.exception("Go TUI scan failed")
+            report_error("unhandled_exception", exc)
+            if self.report_state is not None and self.report_state.scan_ended_exit_reason is None:
+                self.report_state.scan_ended_exit_reason = "error"
             self.scan_error = exc
             self.controller.error = str(exc)
             self.controller.scan_state = "failed"

strix/interface/utils.py

@@ -19,6 +19,7 @@ from rich.panel import Panel
 from rich.text import Text
 
 from strix.config import load_settings
+from strix.telemetry import report_error
 from strix.utils.api_spec import detect_spec_format
 
 
@@ -1602,7 +1603,8 @@ def check_docker_connection() -> Any:
 
     try:
         return docker.from_env()
-    except DockerException:
+    except DockerException as exc:
+        report_error("docker_unavailable", exc)
         console = Console()
         error_text = Text()
         error_text.append("DOCKER NOT AVAILABLE", style="bold red")

strix/llm/warmup.py

@@ -1,20 +1,22 @@
 """Background pre-import of the heavy scan dependencies.
 
 The scan engine's import graph (the agents SDK, OpenAI client, LiteLLM, the
-Caido SDK, the Docker SDK) costs seconds to import cold, but none of it is
-needed until a scan actually starts. Importing it on a daemon thread at CLI
-entry overlaps that cost with the I/O-bound startup work that always precedes
-a scan (argument parsing, Docker checks, image pull, TUI setup), so by the
-time the scan begins the modules are already in ``sys.modules``. Any thread
-that needs one of them before the warm-up finishes just blocks on the normal
-import lock, so behaviour is unchanged either way.
+Caido SDK) costs seconds to import cold, but none of it is needed until a scan
+actually starts. Importing it on a daemon thread at CLI entry overlaps that
+cost with the I/O-bound startup work that always precedes a scan (argument
+parsing, Docker checks, image pull, TUI setup). The Docker SDK is not on the
+list: the Docker checks import it on the main thread during that same window.
+
+The main thread must call :func:`wait_for_import_warmup` before its first
+import from that graph. Two threads that enter the same package graph from
+different modules hold each other's import locks, and CPython breaks the cycle
+by failing one of the imports.
 """
 
 from __future__ import annotations
 
 import importlib
 import logging
-import sys
 import threading
 
 
@@ -24,45 +26,17 @@ WARMUP_MODULES = (
     "strix.core.runner",
     "litellm",
     "caido_sdk_client",
-    "docker",
 )
 
-_lock = threading.Lock()
 _thread: threading.Thread | None = None
 
 
-def _purge_orphaned_modules(before: frozenset[str]) -> None:
-    """Remove submodules stranded by an import attempt that just failed.
-
-    When a package import fails partway (for example CPython's import-lock
-    deadlock avoidance breaking a cross-thread cycle), the failed package is
-    removed from ``sys.modules`` but submodules it already finished stay
-    behind. A later import of one of those submodules then short-circuits on
-    the cached entry without re-importing its parent, and re-entering the
-    parent from inside a submodule crashes with "partially initialized
-    module". Dropping the orphans (cached submodules whose ancestor package is
-    gone) restores a clean slate, and touches nothing another thread imported
-    successfully.
-    """
-    added = set(sys.modules) - before
-    for name in added:
-        parent = name.rpartition(".")[0]
-        while parent:
-            if parent not in sys.modules:
-                sys.modules.pop(name, None)
-                logger.debug("Import warm-up purged orphaned module %r", name)
-                break
-            parent = parent.rpartition(".")[0]
-
-
 def _warm(modules: tuple[str, ...]) -> None:
     for name in modules:
-        before = frozenset(sys.modules)
         try:
             importlib.import_module(name)
         except Exception:  # noqa: BLE001 - a failed warm-up must never fail the run.
             logger.debug("Import warm-up for %r failed", name, exc_info=True)
-            _purge_orphaned_modules(before)
 
 
 def start_import_warmup(modules: tuple[str, ...] = WARMUP_MODULES) -> threading.Thread:
@@ -72,11 +46,15 @@ def start_import_warmup(modules: tuple[str, ...] = WARMUP_MODULES) -> threading.
     runtime that has no local Docker) warm a narrower set.
     """
     global _thread  # noqa: PLW0603
-    with _lock:
-        if _thread is not None:
-            return _thread
+    if _thread is None:
         _thread = threading.Thread(
             target=_warm, args=(modules,), name="strix-import-warmup", daemon=True
         )
         _thread.start()
-        return _thread
+    return _thread
+
+
+def wait_for_import_warmup() -> None:
+    """Block until the warm-up thread has finished, if one was started."""
+    if _thread is not None:
+        _thread.join()

strix/skills/__init__.py

@@ -1,6 +1,5 @@
 import logging
 import re
-import threading
 from collections import Counter
 from collections.abc import Iterator
 from pathlib import Path
@@ -8,7 +7,6 @@ from typing import TypeGuard
 
 import yaml
 
-from strix.telemetry import posthog, scarf
 from strix.utils.resource_paths import get_strix_resource_path
 
 
@@ -241,16 +239,19 @@ def validate_requested_skills(skill_list: list[str], max_skills: int = 5) -> str
     return None
 
 
+_LOADED_SKILLS: set[str] = set()
+
+
 def _track_skill_loaded(skill_name: str, file_path: Path) -> None:
     builtin = get_strix_resource_path("skills")
     if not file_path.is_relative_to(builtin):
         skill_name = "custom"
+    _LOADED_SKILLS.add(skill_name)
 
-    def _send() -> None:
-        posthog.skill_loaded(skill_name)
-        scarf.skill_loaded(skill_name)
 
-    threading.Thread(target=_send, daemon=True).start()
+def get_loaded_skill_names() -> list[str]:
+    """Distinct skills loaded so far in this process (custom skills collapse to ``"custom"``)."""
+    return sorted(_LOADED_SKILLS)
 
 
 def _candidate_skill_files(skill_name: str) -> list[Path]:

strix/telemetry/README.md

@@ -12,11 +12,11 @@ Privacy is our priority. All collected data is anonymized by default. Each sessi
 
 We collect only very **basic** usage data including:
 
-**Session Errors:** Duration and error types (not messages or stack traces)\
+**Session Errors:** Duration, the failure category, the scan phase, and the exception class name (not messages or stack traces)\
 **System Context:** OS type, architecture, Strix version\
 **Scan Context:** Scan mode (quick/standard/deep), scan type (whitebox/blackbox)\
 **Model Usage:** Which LLM model is being used and whether it runs via an API key or a model subscription (not prompts or responses)\
-**Feature Usage:** Which built-in skills are loaded\
+**Feature Usage:** Which built-in skills were used during a scan (reported once, at scan end)\
 **Aggregate Metrics:** Vulnerability counts by severity and weakness category (CWE)
 
 ### What We **Never** Collect

strix/telemetry/__init__.py

@@ -1,7 +1,19 @@
 from . import posthog, scarf
+from ._common import set_scan_phase
+
+
+def report_error(error_type: str, exc: BaseException | None = None) -> None:
+    """Beacon a failure category, plus the exception class when one is given.
+
+    Only class names travel: never the message, arguments, or traceback.
+    """
+    posthog.error(error_type, exc)
+    scarf.error(error_type, exc)
 
 
 __all__ = [
     "posthog",
+    "report_error",
     "scarf",
+    "set_scan_phase",
 ]

strix/telemetry/_common.py

@@ -5,7 +5,7 @@ import platform
 import sys
 from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 from uuid import uuid4
 
 
@@ -54,3 +54,43 @@ def base_props() -> dict[str, Any]:
         "python": f"{sys.version_info.major}.{sys.version_info.minor}",
         "strix_version": get_version(),
     }
+
+
+# Coarse stage of the current run, attached to ``error`` beacons so a failure
+# can be placed without a message or trace. Process-local, like the rest of the
+# CLI telemetry: one process runs one scan.
+_scan_phase = "startup"
+
+
+def set_scan_phase(phase: str) -> None:
+    global _scan_phase  # noqa: PLW0603
+    _scan_phase = phase
+
+
+def get_scan_phase() -> str:
+    return _scan_phase
+
+
+def _exception_name(exc: BaseException) -> str:
+    cls = type(exc)
+    package = cls.__module__.split(".")[0]
+    return cls.__name__ if package == "builtins" else f"{package}.{cls.__name__}"
+
+
+def _unwrap_group(exc: BaseException) -> BaseException:
+    if not isinstance(exc, BaseExceptionGroup):
+        return exc
+    group = cast("BaseExceptionGroup[BaseException]", exc)
+    return group.exceptions[0] if group.exceptions else group
+
+
+def exception_props(exc: BaseException) -> dict[str, str]:
+    """Class names only. Messages, arguments, and tracebacks never leave the machine."""
+    exc = _unwrap_group(exc)
+    props = {"exception_type": _exception_name(exc)}
+    cause = exc.__cause__
+    if cause is None and not exc.__suppress_context__:
+        cause = exc.__context__
+    if cause is not None:
+        props["exception_cause"] = _exception_name(cause)
+    return props

strix/telemetry/posthog.py

@@ -4,10 +4,14 @@ from typing import TYPE_CHECKING, Any
 import requests
 
 from strix.config import load_settings
+from strix.skills import get_loaded_skill_names
 from strix.telemetry._common import (
     SEND_TIMEOUT,
     SESSION_ID,
     base_props,
+    exception_props,
+    get_scan_phase,
+    get_version,
     is_first_run,
 )
 
@@ -35,7 +39,12 @@ def _send(event: str, properties: dict[str, Any]) -> bool:
             "api_key": _POSTHOG_PUBLIC_API_KEY,
             "event": event,
             "distinct_id": SESSION_ID,
-            "properties": properties,
+            "properties": {
+                **properties,
+                "$lib": "strix-cli",
+                "$lib_version": get_version(),
+                "$process_person_profile": False,
+            },
         }
         with requests.post(f"{_POSTHOG_HOST}/capture/", json=payload, timeout=SEND_TIMEOUT):
             pass
@@ -82,16 +91,6 @@ def finding(severity: str, cwe: str | None = None, is_cve: bool = False) -> None
     )
 
 
-def skill_loaded(skill_name: str) -> None:
-    _send(
-        "skill_loaded",
-        {
-            **base_props(),
-            "skill": skill_name,
-        },
-    )
-
-
 def end(report_state: "ReportState", exit_reason: str = "completed") -> None:
     if report_state.posthog_scan_ended_sent:
         return
@@ -130,6 +129,7 @@ def end(report_state: "ReportState", exit_reason: str = "completed") -> None:
             "vulnerabilities_total": len(report_state.vulnerability_reports),
             **{f"vulnerabilities_{k}": v for k, v in vulnerabilities_counts.items()},
             **llm_props,
+            "skills": get_loaded_skill_names(),
         },
     )
 
@@ -180,6 +180,12 @@ def viewer_agent_steered() -> None:
     _send("viewer_agent_steered", {**base_props()})
 
 
-def error(error_type: str) -> None:
-    props = {**base_props(), "error_type": error_type}
+def error(error_type: str, exc: BaseException | None = None) -> None:
+    props: dict[str, Any] = {
+        **base_props(),
+        "error_type": error_type,
+        "phase": get_scan_phase(),
+    }
+    if exc is not None:
+        props.update(exception_props(exc))
     _send("error", props)

strix/telemetry/scarf.py

@@ -7,10 +7,13 @@ from typing import TYPE_CHECKING, Any
 import requests
 
 from strix.config import load_settings
+from strix.skills import get_loaded_skill_names
 from strix.telemetry._common import (
     SEND_TIMEOUT,
     SESSION_ID,
     base_props,
+    exception_props,
+    get_scan_phase,
     get_version,
     is_first_run,
 )
@@ -90,17 +93,6 @@ def finding(severity: str, cwe: str | None = None, is_cve: bool = False) -> None
     )
 
 
-def skill_loaded(skill_name: str) -> None:
-    _send(
-        "skill_loaded",
-        {
-            **base_props(),
-            "session": SESSION_ID,
-            "skill": skill_name,
-        },
-    )
-
-
 def end(report_state: ReportState, exit_reason: str = "completed") -> None:
     if report_state.scarf_scan_ended_sent:
         return
@@ -140,14 +132,18 @@ def end(report_state: ReportState, exit_reason: str = "completed") -> None:
             "vulnerabilities_total": len(report_state.vulnerability_reports),
             **{f"vulnerabilities_{k}": v for k, v in vulnerabilities_counts.items()},
             **llm_props,
+            "skills": ",".join(get_loaded_skill_names()),
         },
     )
 
 
-def error(error_type: str) -> None:
+def error(error_type: str, exc: BaseException | None = None) -> None:
     props: dict[str, Any] = {
         **base_props(),
         "session": SESSION_ID,
         "error_type": error_type,
+        "phase": get_scan_phase(),
     }
+    if exc is not None:
+        props.update(exception_props(exc))
     _send("error", props)

tests/test_import_warmup.py

@@ -1,12 +1,10 @@
-"""The import warm-up thread must never leave the import system poisoned.
+"""The import warm-up thread must never race the main thread into the engine.
 
-Field failure: the warm-up thread's ``strix.core.runner`` import and the main
-thread's ``strix.report`` import both walked the agents SDK graph, and the two
-held each other's import locks (report -> dedupe -> agents while runner ->
-hooks -> report.state). CPython's deadlock avoidance breaks such a cycle by
-failing one import, which strands finished submodules in ``sys.modules`` with
-their parent package gone — and the next import of one of those submodules
-crashes with "partially initialized module".
+Two threads that enter the same package graph from different modules hold
+each other's import locks (warm-up: ``strix.core.runner`` -> ``agents``;
+main: ``agents.models.interface``). CPython breaks such a cycle by failing one
+of the imports, so the main thread waits for the warm-up before its first
+engine import.
 """
 
 from __future__ import annotations
@@ -14,10 +12,16 @@ from __future__ import annotations
 import subprocess
 import sys
 import textwrap
+import threading
+from typing import TYPE_CHECKING
 
 from strix.llm import warmup
 
 
+if TYPE_CHECKING:
+    import pytest
+
+
 def _run(code: str) -> subprocess.CompletedProcess[str]:
     return subprocess.run(  # noqa: S603
         [sys.executable, "-c", textwrap.dedent(code)],
@@ -56,44 +60,49 @@ def test_check_duplicate_resolves_lazily() -> None:
     assert result.returncode == 0, result.stderr
 
 
-def test_failed_warm_import_purges_orphaned_submodules() -> None:
+def test_wait_for_import_warmup_lets_main_thread_import_the_agents_graph() -> None:
     result = _run(
         """
         import sys
 
-        from strix.llm.warmup import _warm
+        from strix.llm.warmup import start_import_warmup, wait_for_import_warmup
 
-        # A package whose import fails after a submodule already completed:
-        # CPython removes the package but leaves the submodule stranded.
-        import pathlib
-        import tempfile
+        # Same shape as the CLI: warm-up starts, then the main thread needs a
+        # module from the middle of the agents graph.
+        start_import_warmup()
+        wait_for_import_warmup()
 
-        root = pathlib.Path(tempfile.mkdtemp())
-        pkg = root / "stranded_pkg"
-        pkg.mkdir()
-        (pkg / "ok.py").write_text("VALUE = 1")
-        (pkg / "__init__.py").write_text("from . import ok\\nraise RuntimeError('boom')")
-        sys.path.insert(0, str(root))
+        from agents.models.interface import ModelTracing  # noqa: F401
 
-        _warm(("stranded_pkg",))
-
-        assert "stranded_pkg" not in sys.modules
-        assert "stranded_pkg.ok" not in sys.modules, "orphan survived the purge"
-
-        # And the subtree imports cleanly afterwards up to the real error.
-        try:
-            import stranded_pkg  # noqa: F401
-        except RuntimeError:
-            pass
-        else:
-            raise AssertionError("expected the package's own error")
+        assert "agents" in sys.modules
+        assert "agents.models" in sys.modules
+        assert "strix.core.runner" in sys.modules
         """
     )
     assert result.returncode == 0, result.stderr
 
 
-def test_purge_does_not_touch_preexisting_or_healthy_modules() -> None:
-    before = frozenset(sys.modules) - {"strix.llm.warmup"}
-    warmup._purge_orphaned_modules(before)
-    assert "strix.llm.warmup" in sys.modules  # parent chain intact -> kept
-    assert "strix" in sys.modules
+def test_wait_for_import_warmup_blocks_until_the_thread_finishes(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    release = threading.Event()
+    monkeypatch.setattr(warmup, "_warm", lambda _modules: release.wait())
+    monkeypatch.setattr(warmup, "_thread", None)
+    warmup.start_import_warmup(())
+
+    waiter = threading.Thread(target=warmup.wait_for_import_warmup)
+    waiter.start()
+    waiter.join(0.2)
+    assert waiter.is_alive(), "returned before the warm-up finished"
+
+    release.set()
+    waiter.join(5)
+    assert not waiter.is_alive()
+
+
+def test_failed_warm_import_does_not_raise() -> None:
+    warmup._warm(("strix_no_such_module_for_warmup_test",))
+
+
+def test_wait_for_import_warmup_is_a_no_op_without_a_thread() -> None:
+    warmup.wait_for_import_warmup()

tests/test_telemetry_errors.py

@@ -0,0 +1,125 @@
+"""Error beacons carry a category, phase, and exception class — never a message."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+import requests
+
+from strix.report.state import ReportState
+from strix.telemetry import posthog, report_error, scarf, set_scan_phase
+from strix.telemetry._common import exception_props
+
+
+PRIVATE_MESSAGE = "private message that must stay on the machine"
+
+
+def _capture(sent: list[dict[str, Any]], event: str, props: dict[str, Any]) -> bool:
+    sent.append({"event": event, **props})
+    return True
+
+
+def test_exception_props_uses_bare_name_for_builtins() -> None:
+    assert exception_props(ValueError(PRIVATE_MESSAGE)) == {"exception_type": "ValueError"}
+
+
+def test_exception_props_prefixes_third_party_top_level_package() -> None:
+    props = exception_props(requests.exceptions.ConnectTimeout(PRIVATE_MESSAGE))
+    assert props == {"exception_type": "requests.ConnectTimeout"}
+
+
+def _chained(cause: BaseException | None, *, explicit: bool) -> RuntimeError:
+    exc = RuntimeError("wrapped")
+    if explicit:
+        exc.__cause__ = cause
+        exc.__suppress_context__ = True
+    else:
+        exc.__context__ = cause
+    return exc
+
+
+def test_exception_props_reports_explicit_cause() -> None:
+    props = exception_props(_chained(ConnectionError(PRIVATE_MESSAGE), explicit=True))
+    assert props == {"exception_type": "RuntimeError", "exception_cause": "ConnectionError"}
+
+
+def test_exception_props_reports_implicit_context() -> None:
+    props = exception_props(_chained(KeyError("k"), explicit=False))
+    assert props["exception_cause"] == "KeyError"
+
+
+def test_exception_props_ignores_suppressed_context() -> None:
+    exc = _chained(None, explicit=True)
+    exc.__context__ = KeyError("k")
+    assert exception_props(exc) == {"exception_type": "RuntimeError"}
+
+
+def test_exception_props_unwraps_exception_group() -> None:
+    group = ExceptionGroup("tasks", [TimeoutError("t"), ValueError("v")])
+    assert exception_props(group) == {"exception_type": "TimeoutError"}
+
+
+@pytest.mark.parametrize("telemetry", [posthog, scarf])
+def test_error_event_carries_phase_and_class_but_no_message(
+    telemetry: Any,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    sent: list[dict[str, Any]] = []
+    monkeypatch.setattr(telemetry, "_send", lambda event, props: _capture(sent, event, props))
+    set_scan_phase("sandbox_init")
+
+    telemetry.error("scan_failed", RuntimeError(PRIVATE_MESSAGE))
+
+    assert len(sent) == 1
+    event = sent[0]
+    assert event["event"] == "error"
+    assert event["error_type"] == "scan_failed"
+    assert event["phase"] == "sandbox_init"
+    assert event["exception_type"] == "RuntimeError"
+    assert PRIVATE_MESSAGE not in repr(event)
+
+
+@pytest.mark.parametrize("telemetry", [posthog, scarf])
+def test_error_event_without_exception_omits_exception_fields(
+    telemetry: Any,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    sent: list[dict[str, Any]] = []
+    monkeypatch.setattr(telemetry, "_send", lambda event, props: _capture(sent, event, props))
+    set_scan_phase("startup")
+
+    telemetry.error("docker_not_installed")
+
+    assert sent[0]["error_type"] == "docker_not_installed"
+    assert sent[0]["phase"] == "startup"
+    assert "exception_type" not in sent[0]
+    assert "exception_cause" not in sent[0]
+
+
+def test_report_error_fans_out_to_both_backends(monkeypatch: pytest.MonkeyPatch) -> None:
+    sent: list[dict[str, Any]] = []
+    monkeypatch.setattr(posthog, "_send", lambda event, props: _capture(sent, event, props))
+    monkeypatch.setattr(scarf, "_send", lambda event, props: _capture(sent, event, props))
+
+    report_error("model_connection_failed", TimeoutError(PRIVATE_MESSAGE))
+
+    assert len(sent) == 2
+    assert {e["error_type"] for e in sent} == {"model_connection_failed"}
+    assert {e["exception_type"] for e in sent} == {"TimeoutError"}
+
+
+@pytest.mark.parametrize("telemetry", [posthog, scarf])
+def test_scan_ended_prefers_recorded_exit_reason(
+    telemetry: Any,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    state = ReportState()
+    state.scan_ended_exit_reason = "budget_exceeded"
+    sent: list[dict[str, Any]] = []
+    monkeypatch.setattr(telemetry, "_send", lambda event, props: _capture(sent, event, props))
+
+    telemetry.end(state, exit_reason="user_exit")
+
+    assert sent[0]["event"] == "scan_ended"
+    assert sent[0]["exit_reason"] == "budget_exceeded"