feat(runtime): lazy-install matching ABI runtime tree for cross-Python roar run

Solves the cross-Python first-run experience: `uv tool install roar-cli`
installs roar under one CPython (typically uv's default), but the user
runs `roar run python3 …` against a different one. Without a matching
ABI tree, backend dispatch loads roar's bundled (wrong-ABI) compiled
deps and crashes inside pydantic_core.

The previous PR (#107) gates that crash gracefully. This one closes the
loop: probe the target Python's ABI before launching, install a matching
runtime tree at `~/.cache/roar/runtime/<tag>/` on the fly (or use the
existing cache), and prepend it to ROAR_RUNTIME_PYTHONPATH so the
traced process picks up ABI-correct compiled deps.

What's added

- `roar/execution/runtime/abi_probe.py` — `probe_python_abi(executable)`
  runs the target Python in a one-shot subprocess to read its
  `sys.implementation.cache_tag`. Bails fast for non-Python targets
  (bash/make/etc.) so `roar run cmd` doesn't pay a probe cost for
  things it couldn't lazy-install for anyway.
- `roar/execution/runtime/lazy_install.py` — XDG-respecting cache
  (`$XDG_CACHE_HOME/roar/runtime/<tag>/` or `~/.cache/...`), atomic
  install via `uv pip install --target --python` (with plain pip
  fallback), roar-version-stamped cache invalidation, and the
  `ensure_runtime(...)` orchestrator. Failures return None — the
  sitecustomize gate handles fallback.
- `runtime.install` config key — `auto` (default, lazy install on
  mismatch) or `skip` (use bundled only; backend dispatch off on
  mismatch). Env `ROAR_RUNTIME_INSTALL` overrides. The `skip` mode
  covers restricted-network containers where lazy-install would fail
  anyway.
- `TracerService._lazy_install_runtime_entries(command, roar_dir)` —
  hooks the probe + ensure_runtime into `execute()` right before
  `ROAR_RUNTIME_PYTHONPATH` is set.

Gate refactor (touches #107 territory)

The original ABI-tag check (`bundled_abi_tag` + `abi_minor_version`)
parsed roar's bundled `.so` filenames. That works for the bundled-only
case but is blind to a lazy-installed runtime tree on the same path.
Replaced with `matching_compiled_pydantic_core(sys.path, expected_soabi)`
— walks sys.path for a pydantic_core SO whose filename matches the
running interpreter's SOABI. Composes naturally with the lazy-install
path (matching SO anywhere on sys.path satisfies the gate).

The old helpers are kept (still tested) for future use and to avoid
churning the API surface of `support.py`.

User-visible

- Lazy-install path emits a single 🦖 line on cache miss:
    🦖 installing roar runtime for cp312 ...
- Cache hits are silent.
- Skip mode + ABI mismatch falls through to the gate's actionable
  message, which now also recommends `pip install roar-cli` for
  single-Python container environments.

Test coverage

- `test_abi_probe.py`: success / non-Python target / subprocess failure
  / blank stdout / versioned python names.
- `test_lazy_install.py`: cache layout, stamp invalidation, atomic
  install (mocked subprocess, real tempdir/rename), failure paths,
  mode resolution (env / config / default / case normalization), and
  the `ensure_runtime` decision tree (match / skip / cache-hit /
  cache-miss-install / install-fail).
- `test_inject_support.py`: `matching_compiled_pydantic_core` finds in
  bundled, finds in lazy runtime, returns False on mismatch / missing
  pkg / wrong extension / blank entries.

968 unit tests passing, 1 pre-existing skipped.

Stacked on #107 (the gate). When #107 merges, this branch rebases
cleanly onto main.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 2 people

roar/execution/runtime/abi_probe.py

@@ -0,0 +1,39 @@
+"""Probe a target Python interpreter's CPython ABI tag."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+_PROBE_TIMEOUT_SECONDS = 5
+_PROBE_SCRIPT = "import sys; print(sys.implementation.cache_tag)"
+
+
+def probe_python_abi(executable: str) -> str | None:
+    """Return the running ABI tag (e.g. ``cp312``) of ``executable``, or ``None``.
+
+    Returns ``None`` if the target doesn't look like Python (we only probe
+    invocations whose argv[0] basename starts with ``python``), the probe
+    fails, or the interpreter is something exotic that doesn't expose
+    ``sys.implementation.cache_tag``. Callers should treat ``None`` as
+    "don't lazy-install for this target" — the sitecustomize gate handles
+    whatever the traced process turns out to be.
+    """
+    if not executable:
+        return None
+    if not os.path.basename(executable).startswith("python"):
+        return None
+    try:
+        result = subprocess.run(
+            [executable, "-c", _PROBE_SCRIPT],
+            capture_output=True,
+            text=True,
+            timeout=_PROBE_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    tag = result.stdout.strip()
+    return tag or None

roar/execution/runtime/inject/sitecustomize.py

@@ -20,7 +20,7 @@ def _append_roar_runtime_pythonpath() -> None:
 _append_roar_runtime_pythonpath()
 
 from roar.execution.framework.runtime_imports import RuntimeImportController
-from roar.execution.runtime.inject.support import abi_minor_version, bundled_abi_tag
+from roar.execution.runtime.inject.support import matching_compiled_pydantic_core
 from roar.execution.runtime.inject.tracker import RuntimeInjectionTracker
 
 LOG_FILE = os.environ.get("ROAR_LOG_FILE")
@@ -43,17 +43,18 @@ def _append_roar_runtime_pythonpath() -> None:
 
 
 if os.environ.get("ROAR_WRAP") == "1":
-    _bundled_abi = abi_minor_version(bundled_abi_tag(_ROAR_INJECT_DIR))
     _running_abi = (sys.version_info.major, sys.version_info.minor)
-    if _bundled_abi is not None and _bundled_abi != _running_abi:
+    _expected_soabi = f"cpython-{_running_abi[0]}{_running_abi[1]}"
+    if not matching_compiled_pydantic_core(sys.path, _expected_soabi):
         sys.stderr.write(
-            f"roar: traced Python is {_running_abi[0]}.{_running_abi[1]} but "
-            f"roar-cli was installed under Python "
-            f"{_bundled_abi[0]}.{_bundled_abi[1]}.\n"
+            f"roar: no ABI-matched runtime found for Python "
+            f"{_running_abi[0]}.{_running_abi[1]}.\n"
             f"  Backend integrations (Ray, OSMO) are disabled for this run.\n"
             f"  File I/O is still captured.\n"
-            f"  To re-enable backends, reinstall under the matching Python:\n"
-            f"    uv tool install --python python{_running_abi[0]}.{_running_abi[1]} "
+            f"  Fix one of:\n"
+            f"    - Install roar in this Python: pip install roar-cli\n"
+            f"    - Reinstall roar-cli under matching Python:\n"
+            f"        uv tool install --python python{_running_abi[0]}.{_running_abi[1]} "
             f"roar-cli --force\n"
         )
         _runtime_import_controller.disable_backend_dispatch()

roar/execution/runtime/inject/support.py

@@ -56,6 +56,32 @@ def abi_minor_version(tag: str | None) -> tuple[int, int] | None:
     return (int(digits[0]), int(digits[1:]))
 
 
+def matching_compiled_pydantic_core(sys_path: list[str], expected_soabi: str) -> bool:
+    """Return True if a pydantic_core/_pydantic_core.<soabi>.so exists on ``sys_path``.
+
+    ``expected_soabi`` is the long-form CPython SOABI substring (e.g.
+    ``cpython-313``) — typically built from the running interpreter's version
+    tuple. Used as the gate primitive in ``sitecustomize.py``: if a matching
+    compiled pydantic_core is reachable (either in roar's bundled tree or in
+    a lazy-installed runtime tree on ``ROAR_RUNTIME_PYTHONPATH``), backend
+    dispatch can safely fire.
+    """
+    for entry in sys_path:
+        if not entry:
+            continue
+        pdc_dir = os.path.join(entry, "pydantic_core")
+        if not os.path.isdir(pdc_dir):
+            continue
+        try:
+            filenames = os.listdir(pdc_dir)
+        except OSError:
+            continue
+        for filename in filenames:
+            if expected_soabi in filename and filename.endswith(".so"):
+                return True
+    return False
+
+
 def is_suppressed() -> bool:
     return bool(getattr(_roar_suppress, "active", False))
 

roar/execution/runtime/lazy_install.py

@@ -0,0 +1,213 @@
+"""Lazy install of a per-ABI runtime tree for cross-Python ``roar run``.
+
+When ``uv tool install roar-cli`` installs roar under one Python (e.g. 3.13)
+but ``roar run`` is invoked against a different one (e.g. system 3.12),
+roar's bundled compiled deps don't match the traced Python's ABI. This
+module installs a matching tree of runtime deps on demand into a per-ABI
+cache directory under ``~/.cache/roar/runtime/<tag>/``.
+
+``sitecustomize.py``'s ``_append_roar_runtime_pythonpath`` prepends the
+cache directory to ``sys.path`` in the traced process, so imports there
+resolve to the ABI-matched copies before reaching roar's bundled tree.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+# Deps backend dispatch needs in the traced Python. Kept short — pip/uv
+# resolves transitive deps. Unpinned: roar tolerates any pydantic 2.x.
+_RUNTIME_DEPS: tuple[str, ...] = ("pydantic", "blake3")
+
+_STAMP_FILENAME = "roar_runtime.json"
+_INSTALL_TIMEOUT_SECONDS = 180
+
+
+def runtime_cache_root() -> Path:
+    """Return ``$XDG_CACHE_HOME/roar/runtime`` (default ``~/.cache/roar/runtime``)."""
+    xdg_cache = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg_cache) if xdg_cache else Path.home() / ".cache"
+    return base / "roar" / "runtime"
+
+
+def runtime_cache_dir(abi_tag: str) -> Path:
+    """Return the per-ABI cache directory (e.g. ``.../roar/runtime/cp312/``)."""
+    return runtime_cache_root() / abi_tag
+
+
+def runtime_site_packages(abi_tag: str) -> Path:
+    return runtime_cache_dir(abi_tag) / "site-packages"
+
+
+def is_runtime_cached(abi_tag: str, roar_version: str) -> bool:
+    """True iff a matching, roar-version-stamped runtime tree exists for ``abi_tag``."""
+    stamp_path = runtime_cache_dir(abi_tag) / _STAMP_FILENAME
+    if not stamp_path.is_file():
+        return False
+    try:
+        stamp = json.loads(stamp_path.read_text())
+    except (OSError, ValueError):
+        return False
+    return stamp.get("roar_version") == roar_version
+
+
+def install_runtime(
+    abi_tag: str,
+    target_python: str,
+    roar_version: str,
+    deps: tuple[str, ...] = _RUNTIME_DEPS,
+) -> bool:
+    """Install a matching runtime tree for ``abi_tag``. Returns ``True`` on success.
+
+    Atomic: installs into a tempdir alongside the cache root, then renames
+    into place. Failures (no network, missing pip, etc.) leave the cache in
+    its prior state — callers should treat a ``False`` return as "fall back
+    to the sitecustomize gate."
+    """
+    cache_dir = runtime_cache_dir(abi_tag)
+    sys.stderr.write(f"🦖 installing roar runtime for {abi_tag} ...\n")
+    sys.stderr.flush()
+
+    try:
+        cache_root = runtime_cache_root()
+        cache_root.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return False
+
+    tmpdir = Path(tempfile.mkdtemp(prefix="roar-runtime-", dir=cache_root))
+    moved = False
+    try:
+        target_site = tmpdir / "site-packages"
+        target_site.mkdir(parents=True)
+        installer_cmd = _select_installer(target_python, target_site, deps)
+        if installer_cmd is None:
+            sys.stderr.write("🦖 install failed: no installer found (need uv or pip)\n")
+            return False
+        try:
+            result = subprocess.run(
+                installer_cmd,
+                capture_output=True,
+                text=True,
+                timeout=_INSTALL_TIMEOUT_SECONDS,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            sys.stderr.write(f"🦖 install failed: {exc}\n")
+            return False
+        if result.returncode != 0:
+            stderr_tail = (result.stderr or "").strip()[-500:]
+            sys.stderr.write(f"🦖 install failed (rc={result.returncode}): {stderr_tail}\n")
+            return False
+
+        stamp_data = {
+            "roar_version": roar_version,
+            "abi_tag": abi_tag,
+            "installed_at": time.time(),
+            "deps": list(deps),
+        }
+        (tmpdir / _STAMP_FILENAME).write_text(json.dumps(stamp_data, indent=2))
+
+        if cache_dir.exists():
+            with contextlib.suppress(OSError):
+                shutil.rmtree(cache_dir)
+        try:
+            os.rename(tmpdir, cache_dir)
+            moved = True
+        except OSError:
+            return False
+    finally:
+        if not moved:
+            with contextlib.suppress(Exception):
+                shutil.rmtree(tmpdir)
+
+    return is_runtime_cached(abi_tag, roar_version)
+
+
+def _select_installer(
+    target_python: str, target_dir: Path, deps: tuple[str, ...]
+) -> list[str] | None:
+    """Pick the install command. Prefer ``uv pip install --target --python``."""
+    uv = shutil.which("uv")
+    if uv:
+        return [
+            uv,
+            "pip",
+            "install",
+            "--target",
+            str(target_dir),
+            "--python",
+            target_python,
+            *deps,
+        ]
+    # Fallback: plain pip. Only works if `pip` is in the target Python's env;
+    # best-effort. uv is strongly preferred because of the --python flag.
+    pip = shutil.which("pip") or shutil.which("pip3")
+    if pip:
+        return [pip, "install", "--target", str(target_dir), *deps]
+    return None
+
+
+def runtime_install_mode(start_dir: Path | None = None) -> str:
+    """Resolve runtime.install mode: ``'auto'`` (default) or ``'skip'``.
+
+    ``ROAR_RUNTIME_INSTALL`` env var takes precedence over project config.
+    Anything unrecognized falls back to ``'auto'``.
+    """
+    env_value = os.environ.get("ROAR_RUNTIME_INSTALL")
+    if env_value:
+        normalized = env_value.strip().lower()
+        if normalized in ("auto", "skip"):
+            return normalized
+        return "auto"
+
+    try:
+        from roar.integrations.config.access import config_get
+
+        configured = config_get("runtime.install", start_dir=start_dir)
+    except Exception:
+        return "auto"
+    if isinstance(configured, str) and configured.lower() in ("auto", "skip"):
+        return configured.lower()
+    return "auto"
+
+
+def ensure_runtime(
+    target_python: str,
+    target_abi: str,
+    bundled_abi: str | None,
+    roar_version: str,
+    mode: str | None = None,
+    start_dir: Path | None = None,
+) -> Path | None:
+    """Return the site-packages path for an ABI-matched runtime, or ``None``.
+
+    Behavior:
+    - No action when ``target_abi`` matches ``bundled_abi`` — bundled wins.
+    - No action when mode is ``'skip'`` — gate handles whatever happens.
+    - Cache hit: return the cached path.
+    - Cache miss: install lazily and return the path on success.
+    - Install failure: ``None`` (caller falls back to the gate).
+    """
+    if not target_abi:
+        return None
+    if bundled_abi and target_abi == bundled_abi:
+        return None
+
+    resolved_mode = mode or runtime_install_mode(start_dir)
+    if resolved_mode == "skip":
+        return None
+
+    if is_runtime_cached(target_abi, roar_version):
+        return runtime_site_packages(target_abi)
+
+    if install_runtime(target_abi, target_python, roar_version):
+        return runtime_site_packages(target_abi)
+    return None

roar/execution/runtime/tracer.py

@@ -95,6 +95,50 @@ def add(path: str | Path) -> None:
 
         return entries
 
+    def _lazy_install_runtime_entries(self, command: list[str], roar_dir: Path) -> list[str]:
+        """Probe the target Python and lazy-install a matching runtime tree on mismatch.
+
+        Returns a list of site-packages paths to prepend to
+        ``ROAR_RUNTIME_PYTHONPATH``. Empty on:
+        - non-Python targets (bash, make, etc.) — can't probe a python ABI;
+        - matching ABI — bundled deps work as-is;
+        - ``runtime.install = skip`` — opted out;
+        - install failure (no network, no installer, etc.) — the sitecustomize
+          gate handles the fallback.
+        """
+        if not command:
+            return []
+        try:
+            from roar import __version__ as roar_version
+
+            from .abi_probe import probe_python_abi
+            from .lazy_install import ensure_runtime
+        except Exception as exc:
+            self.logger.debug("lazy-install import skipped: %s", exc)
+            return []
+
+        target_python = command[0]
+        target_abi = probe_python_abi(target_python)
+        if not target_abi:
+            return []
+        bundled_abi = sys.implementation.cache_tag
+        if target_abi == bundled_abi:
+            return []
+        try:
+            tree = ensure_runtime(
+                target_python=target_python,
+                target_abi=target_abi,
+                bundled_abi=bundled_abi,
+                roar_version=roar_version,
+                start_dir=roar_dir,
+            )
+        except Exception as exc:
+            self.logger.debug("lazy-install failed: %s", exc)
+            return []
+        if tree is None:
+            return []
+        return [str(tree)]
+
     def _find_ptrace_tracer(self) -> str | None:
         """Find the roar-tracer (ptrace) binary."""
         return tracer_backends.find_ptrace_tracer(self._package_path)
@@ -430,7 +474,9 @@ def execute(
         env["PYTHONPATH"] = (
             f"{inject_dir}{os.pathsep}{existing_pythonpath}" if existing_pythonpath else inject_dir
         )
-        env["ROAR_RUNTIME_PYTHONPATH"] = os.pathsep.join(self._runtime_pythonpath_entries())
+        runtime_entries = self._lazy_install_runtime_entries(command, roar_dir)
+        runtime_entries.extend(self._runtime_pythonpath_entries())
+        env["ROAR_RUNTIME_PYTHONPATH"] = os.pathsep.join(runtime_entries)
         env["ROAR_LOG_FILE"] = inject_log_file
         env["ROAR_WRAP"] = "1"
         env["ROAR_PROJECT_DIR"] = str(roar_dir.parent)