test: ensure sentence-transformers is in test env + conftest gate

tests/conftest.py

@@ -110,12 +110,59 @@ if not _warmup_app_controller.wait_for_warmup(timeout=60.0):
 import threading
 _pytest_finished_event: threading.Event = threading.Event()
 
+def pytest_configure(config: object) -> None:
+ """
+ Pytest session-start hook. Runs required-dependency check before any
+ test is collected so the user sees a clear, actionable error if the
+ test environment is incomplete.
+ [C: tests/test_required_test_dependencies.py:test_check_succeeds_when_deps_present, tests/test_required_test_dependencies.py:test_check_raises_on_missing_sentence_transformers]
+ """
+ _check_required_test_dependencies()
+
+
 def pytest_terminal_summary(terminalreporter: object, exitstatus: int, config: object) -> None:
  _pytest_finished_event.set()
 
 def pytest_unconfigure(config: object) -> None:
  _pytest_finished_event.set()
 
+_REQUIRED_TEST_IMPORTS: list[tuple[str, str]] = [
+ ("sentence_transformers", "sentence-transformers"),
+]
+
+def _check_required_test_dependencies() -> None:
+ """
+ Verify that all packages required by the integration test suite are
+ importable. Raises pytest.UsageError with a clear fix command if a
+ required package is missing.
+
+ This gate is a regression test for the 2026-06-09 incident where
+ sentence-transformers was in [project.optional-dependencies] but the
+ test suite requires it unconditionally. A fresh `uv sync` (without
+ --extra local-rag) produced a confusing "rag_status = error: ...
+ Install with manual_slop[local-rag]" failure inside the live_gui
+ subprocess. This gate fails fast at session start with the exact
+ fix command instead.
+
+ To add a new required test dep, append its import to _REQUIRED_TEST_IMPORTS.
+ [C: tests/test_required_test_dependencies.py:test_check_succeeds_when_deps_present, tests/test_required_test_dependencies.py:test_check_raises_on_missing_sentence_transformers]
+ """
+ missing: list[str] = []
+ for module_name, package_name in _REQUIRED_TEST_IMPORTS:
+  try:
+   __import__(module_name)
+  except ImportError:
+   missing.append(package_name)
+ if missing:
+  msg = (
+   "Required test dependencies are missing from the venv:\n"
+   f"  - {', '.join(missing)}\n\n"
+   "Fix: uv sync --extra local-rag\n"
+   "Or, if pyproject.toml already lists the dep in [dependency-groups].dev:\n"
+   "     uv sync\n"
+  )
+  raise pytest.UsageError(msg)
+
 def _smart_watchdog_exit() -> None:
  if not _pytest_finished_event.wait(timeout=300.0):
   os._exit(2)