Wire styxcache into setup_runner for subprocess rbc invocations

tests/integration/test_all.py spawns `rbc all` via subprocess.run;
that fresh process hits setup_runner() rather than the pytest autouse
fixture, so it was running the full pipeline uncached. Cache diagnose
confirmed 0 new entries during warm runs and revealed `setup` of
those two fixtures took ~81 min combined.

setup_runner now wraps the configured runner with styxcache's
CachingRunner when RBC_STYXCACHE_DIR is set, matching the behavior
we already had in tests/conftest.py. The wrapping logic (attribute
proxy + policy) now lives in rbc.core.niwrap.maybe_wrap_with_cache;
tests/conftest.py imports and reuses it.

styxcache moves from dev to runtime dependency since rbc.core now
imports it unconditionally. Drop the try/except fallback and the
deptry DEP004 ignore.

Author: nx10

pyproject.toml

@@ -13,6 +13,7 @@ dependencies = [
   "numpy>=2.4.2",
   "polars>=1.38.1",
   "scipy>=1.17.0",
+  "styxcache>=0.2.0,<0.3",
   "styxpodman>=0.1.1",
   "tqdm>=4.67.3"
 ]
@@ -28,8 +29,7 @@ dev = [
   "pytest-cov>=7.0.0",
   "ruff>=0.8.1",
   "deptry>=0.23.0",
-  "pytest-xdist[psutil]>=3.8.0",
-  "styxcache>=0.2.0,<0.3"
+  "pytest-xdist[psutil]>=3.8.0"
 ]
 docs = ["pdoc>=15.0.0"]
 
@@ -44,11 +44,6 @@ markers = [
   "full_pipeline: End-to-end workflow tests"
 ]
 
-[tool.deptry.per_rule_ignores]
-# styxcache is optional — imported via try/except so the dependency is only
-# needed on CI where the cache is wired up. src/rbc runs fine without it.
-DEP004 = ["styxcache"]
-
 [tool.coverage.report]
 omit = ["src/rbc_resources/"]
 

src/rbc/core/common.py

@@ -7,29 +7,20 @@
 
 from __future__ import annotations
 
-import contextlib
 from typing import TYPE_CHECKING
 
 import nibabel as nib
+import styxcache
 from niwrap import afni
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence
+    from collections.abc import Sequence
     from pathlib import Path
 
 from rbc.core.fileops import file_tmp_copy
 from rbc.core.nifti import strip_afni_volatile_metadata
 from rbc.core.niwrap import generate_exec_folder
 
-try:
-    from styxcache import bypass as _styxcache_bypass
-except ImportError:  # styxcache is optional — only used on CI
-
-    @contextlib.contextmanager
-    def _styxcache_bypass() -> Iterator[None]:
-        yield
-
-
 __all__ = ["deoblique_and_reorient", "merge_3d_to_4d", "split_4d"]
 
 
@@ -52,11 +43,11 @@ def deoblique_and_reorient(
         AFNI 3dresample outputs (use ``.out_file`` for the reoriented image).
     """
     with file_tmp_copy(in_file) as tmp_file:
-        # 3drefit mutates in place, and styxcache 0.2.0 does not replay
+        # 3drefit mutates in place, and styxcache does not replay
         # mutable-input mutations on cache hits. Bypass it so it always runs,
         # then strip AFNI's non-deterministic extension (timestamps + random
         # UUID) so the downstream cached 3dresample call keys on stable bytes.
-        with _styxcache_bypass():
+        with styxcache.bypass():
             afni.v_3drefit(in_file=tmp_file, deoblique=True)
         strip_afni_volatile_metadata(tmp_file)
         return afni.v_3dresample(

src/rbc/core/niwrap.py

@@ -14,6 +14,8 @@
 from typing import Literal, NamedTuple
 
 import niwrap
+from styxcache import CachePolicy, CachingRunner
+from styxcache.backends import docker_digest_resolver, podman_digest_resolver
 from styxpodman import PodmanRunner
 
 _LOG_LEVELS = [logging.WARNING, logging.INFO, logging.DEBUG]
@@ -27,6 +29,50 @@
 ]
 
 
+# styxcache's CachingRunner doesn't proxy base-runner attributes, but rbc
+# touches data_dir / uid / execution_counter on the global runner. This shim
+# forwards anything it doesn't own to self.base.
+class _CacheProxyingRunner(CachingRunner):
+    _OWN_ATTRS = frozenset({"base", "store", "policy"})
+
+    def __getattr__(self, name: str) -> object:
+        return getattr(self.__dict__["base"], name)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        if "base" not in self.__dict__ or name in self._OWN_ATTRS:
+            super().__setattr__(name, value)
+        else:
+            setattr(self.__dict__["base"], name, value)
+
+
+def maybe_wrap_with_cache(
+    runner: niwrap.Runner, runner_type: RunnerType
+) -> niwrap.Runner:
+    """Wrap *runner* with a styxcache CachingRunner if RBC_STYXCACHE_DIR is set.
+
+    Registers the wrapped runner as the niwrap global and returns it. When the
+    env var is unset, or the runner type isn't a container runner with a
+    digest resolver, the runner is returned unchanged.
+    """
+    cache_dir = os.environ.get("RBC_STYXCACHE_DIR")
+    if not cache_dir or runner_type not in {"docker", "podman"}:
+        return runner
+    resolver = (
+        docker_digest_resolver if runner_type == "docker" else podman_digest_resolver
+    )
+    wrapped = _CacheProxyingRunner(
+        base=runner,
+        cache_dir=cache_dir,
+        policy=CachePolicy(
+            image_digest=resolver,
+            # Bump to invalidate when styxcache storage semantics change.
+            extra={"cache_generation": "2026-1"},
+        ),
+    )
+    niwrap.set_global_runner(wrapped)
+    return wrapped
+
+
 class StyxContext(NamedTuple):
     """Styx execution context with logger and runner."""
 
@@ -120,6 +166,11 @@ def setup_runner(
     log_level = min(verbose, len(_LOG_LEVELS) - 1)
     styx_logger.setLevel(_LOG_LEVELS[log_level])
 
+    # Opt-in persistent caching: subprocess invocations of `rbc` in CI (e.g.
+    # tests/integration/test_all.py's `rbc all` spawn) pick this up through
+    # the RBC_STYXCACHE_DIR env var inherited from the parent pytest process.
+    styx_runner = maybe_wrap_with_cache(styx_runner, runner_type)
+
     rbc_logger = logging.getLogger("rbc")
     rbc_logger.setLevel(_LOG_LEVELS[log_level])
     if not rbc_logger.handlers:

tests/conftest.py

@@ -12,29 +12,12 @@
 
 import niwrap
 import pytest
-from styxcache import CachePolicy, CachingRunner
-from styxcache.backends import docker_digest_resolver, podman_digest_resolver
 from styxpodman import PodmanRunner
 
-from rbc.core.niwrap import resolve_runner
+from rbc.core.niwrap import maybe_wrap_with_cache, resolve_runner
 from rbc.orchestration import _DEFAULT_ENV_VARS
 
 
-class _AttrProxyCachingRunner(CachingRunner):
-    # CachingRunner doesn't proxy base-runner attrs, but rbc.core.niwrap
-    # reads/mutates data_dir, uid, execution_counter on the global runner.
-    _OWN_ATTRS = frozenset({"base", "store", "policy"})
-
-    def __getattr__(self, name: str) -> object:
-        return getattr(self.__dict__["base"], name)
-
-    def __setattr__(self, name: str, value: object) -> None:
-        if "base" not in self.__dict__ or name in self._OWN_ATTRS:
-            super().__setattr__(name, value)
-        else:
-            setattr(self.__dict__["base"], name, value)
-
-
 class TestSubjectData(NamedTuple):
     """Test subject file paths."""
 
@@ -100,26 +83,7 @@ def niwrap_runner(
     logger = logging.getLogger(runner.logger_name)
     logger.setLevel(logging.DEBUG)
 
-    cache_dir = os.environ.get("RBC_STYXCACHE_DIR")
-    if cache_dir and runner_type in {"docker", "podman"}:
-        resolver = (
-            docker_digest_resolver
-            if runner_type == "docker"
-            else podman_digest_resolver
-        )
-        wrapped = _AttrProxyCachingRunner(
-            base=runner,
-            cache_dir=cache_dir,
-            policy=CachePolicy(
-                image_digest=resolver,
-                # Bump to invalidate when styxcache storage semantics change
-                # (e.g. 0.1.x entries lacked persisted stdout).
-                extra={"cache_generation": "2026-1"},
-            ),
-        )
-        niwrap.set_global_runner(wrapped)
-        return wrapped
-    return runner
+    return maybe_wrap_with_cache(runner, runner_type)
 
 
 @pytest.fixture(scope="session")