fix(inject): gate backend dispatch when traced Python ABI != bundled

[christophergeyer]

Summary

uv tool install roar-cli installs roar under one CPython (whatever uv picks — typically 3.13). When a user then runs roar run python3 … against a different interpreter (system 3.12, a venv 3.11, etc.), roar's injected backend init pulls compiled deps tagged for the install Python into the traced Python. That mismatch surfaces as ImportError: cannot import name 'Sentinel' from 'typing_extensions' deep in pydantic_core's import chain — a 30-line traceback that looks like a tool bug, and that I've seen pretty cleanly bisected in an engineer-feedback friction journal: "This is the moment a real user quits."

The injection mechanism itself is ABI-safe. The bomb is concentrated in two paths:

• RuntimeImportController.initialize_selected_backend() — fires once during sitecustomize.
• RuntimeImportController.handle_import() — fires on every traced-process import, can lazily load a matched backend's plugin.

Both end up importing the selected backend's plugin (Ray, OSMO), which pulls pydantic + pydantic_core and explodes.

This PR detects the ABI mismatch at sitecustomize entry and disables backend dispatch without disturbing the stdlib tracker hooks.

How it works

1. Detect roar's bundled ABI — bundled_abi_tag(inject_dir) walks up to the enclosing site-packages and parses cpython-NNN from a known compiled dep's .so filename (pydantic_core preferred, falls back to blake3). Returns None if the layout doesn't look like a wheel install — in which case we don't gate.
2. Compare to the running interpreter — abi_minor_version(...) extracts (major, minor) from both forms (cp313 from sys.implementation.cache_tag, cpython-313 from .so filename) into a comparable tuple.
3. Gate — on mismatch under ROAR_WRAP=1, print an actionable stderr line and call _runtime_import_controller.disable_backend_dispatch(). Both initialize_selected_backend and handle_import short-circuit.

What stays running on mismatch:

• File-open wrapping (tracking_open)
• Import-name recording (tracking_import, minus the backend dispatch)
• Env-var read recording (patched_environ_get)
• write_log atexit
• Syscall-level capture (eBPF/preload/ptrace) — unaffected, it's a separate process

What's disabled on mismatch:

• Ray driver/worker hooks
• OSMO backend hooks
• Anything else that registered a RuntimeImportAdapter (today: just those two)

These were effectively already gated on Python-ABI matching — they just failed loudly mid-pipeline instead of refusing at startup with a fix-it.

Stderr on mismatch

roar: traced Python is 3.12 but roar-cli was installed under Python 3.13.
  Backend integrations (Ray, OSMO) are disabled for this run.
  File I/O is still captured.
  To re-enable backends, reinstall under the matching Python:
    uv tool install --python python3.12 roar-cli --force

Test plan

• New unit tests for bundled_abi_tag (pydantic-core fixture, blake3 fallback, no-compiled-deps None, no-site-packages None) and abi_minor_version (both forms, unparseable inputs).
• New unit tests for disable_backend_dispatch short-circuiting initialize_selected_backend and handle_import (the matched-backend path also writes to _environ, asserted unchanged).
• Existing test_pth_pydantic_import.py::test_pth_import_does_not_require_pydantic still passes — the helper import in sitecustomize.py is hoisted above _runtime_tracker.install() so it doesn't go through the patched __import__.
• Full tests/execution/ sweep (54 tests) clean.
• ruff check + ruff format --check clean.

What this isn't

This is the gate, not the fix. The actionable message tells the user how to reinstall under the matching Python, but it's a manual step. The next PR is lazy per-ABI runtime install on roar run — keep uv tool install as the recommended path, install the right per-ABI runtime tree on demand, transparently. That's larger work (manifest split, install backend, locking, version-stamping). This PR rescues the modal first-run experience independently.

🤖 Generated with Claude Code