Cache styx tool outputs across full-pipeline CI runs

Wrap the session runner with styxcache's CachingRunner on the self-hosted
runner (gated on RBC_STYXCACHE_DIR) so ANTs/AFNI/FSL invocations reuse
outputs across runs when inputs, env, and container digest match. Also
moves the pytest basetemp off /dev/shm onto disk to free up RAM for the
tools themselves.

CachingRunner doesn't proxy base-runner attributes, so rbc.core.niwrap
helpers that read/mutate data_dir/uid/execution_counter would break;
_AttrProxyCachingRunner forwards attr reads and writes to self.base.

The workflow provisions /var/lib/rbc-ci/styxcache, purges stale
.incoming staging dirs, enforces a 50GB soft cap, and reports size and
entry count to the job summary.

Author: nx10

.github/workflows/test_full.yaml

@@ -15,6 +15,10 @@ on:
         description: Keep intermediate files after running tests
         default: false
         type: boolean
+      styxcache_dir:
+        description: Override persistent styxcache directory on the self-hosted runner
+        default: ""
+        type: string
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -23,6 +27,9 @@ concurrency:
 jobs:
   test:
     runs-on: arcana
+    env:
+      STYXCACHE_DIR: ${{ inputs.styxcache_dir || '/var/lib/rbc-ci/styxcache' }}
+      STYXCACHE_MAX_GB: "50"
     steps:
     - uses: actions/checkout@v6
     - uses: astral-sh/setup-uv@v8.0.0
@@ -31,20 +38,50 @@ jobs:
         enable-cache: true # not automatic on self-hosted runners
     - run: uv sync
 
+    - name: Prepare styx cache
+      shell: bash
+      run: |
+        mkdir -p "$STYXCACHE_DIR"
+        # Purge stale staging dirs from crashed previous runs (safe: atomic-rename commits)
+        rm -rf "$STYXCACHE_DIR/.incoming" 2>/dev/null || true
+
+        size_kb=$(du -sk "$STYXCACHE_DIR" 2>/dev/null | awk '{print $1}')
+        size_kb=${size_kb:-0}
+        cap_kb=$(( STYXCACHE_MAX_GB * 1024 * 1024 ))
+        if [ "$size_kb" -gt "$cap_kb" ]; then
+          echo "Cache size ${size_kb}KB exceeds cap ${cap_kb}KB; evicting oldest shards"
+          find "$STYXCACHE_DIR" -mindepth 2 -maxdepth 2 -type d -printf '%T@ %p\n' \
+            | sort -n \
+            | while read -r _ path; do
+                rm -rf "$path"
+                cur=$(du -sk "$STYXCACHE_DIR" 2>/dev/null | awk '{print $1}')
+                [ "${cur:-0}" -le "$cap_kb" ] && break
+              done
+        fi
+
+        {
+          echo "## styxcache"
+          echo "- dir: \`$STYXCACHE_DIR\`"
+          echo "- size before: $(du -sh "$STYXCACHE_DIR" 2>/dev/null | cut -f1)"
+        } >> "$GITHUB_STEP_SUMMARY"
+
     - name: Run all tests
       shell: bash
       run: |
-        # Clean up stale tmpfs dirs from previous crashed runs
-        find /dev/shm -maxdepth 1 -name 'rbc_test_*' -mmin +120 -exec rm -rf {} + 2>/dev/null || true
+        tmp_root="${RUNNER_TEMP:-/var/lib/rbc-ci/tmp}"
+        mkdir -p "$tmp_root"
+        # Clean up stale job tmp dirs from previous crashed runs
+        find "$tmp_root" -maxdepth 1 -name 'rbc_test_*' -mmin +120 -exec rm -rf {} + 2>/dev/null || true
 
-        export JOB_TMP="/dev/shm/rbc_test_$(date +%s%N)"
+        export JOB_TMP="$tmp_root/rbc_test_$(date +%s%N)"
         mkdir -p $JOB_TMP
         echo "JOB_TMP=$JOB_TMP" >> $GITHUB_ENV
         echo "Job temp directory: $JOB_TMP"
 
         export PYTEST_CACHE_DIR="$JOB_TMP/.pytest_cache"
         export PYTHONPYCACHEPREFIX="$JOB_TMP/__pycache__"
         export COVERAGE_FILE="$JOB_TMP/.coverage"
+        export RBC_STYXCACHE_DIR="$STYXCACHE_DIR"
 
         uv run pytest \
           -n 8 \
@@ -87,6 +124,17 @@ jobs:
           --show-missing \
           --format=markdown >> $GITHUB_STEP_SUMMARY
 
+    - name: styxcache summary
+      if: always()
+      shell: bash
+      run: |
+        size=$(du -sh "$STYXCACHE_DIR" 2>/dev/null | cut -f1)
+        entries=$(find "$STYXCACHE_DIR" -mindepth 2 -maxdepth 2 -type d 2>/dev/null | wc -l)
+        {
+          echo "- size after: ${size:-0}"
+          echo "- entries: ${entries:-0}"
+        } >> "$GITHUB_STEP_SUMMARY"
+
     - name: Cleanup
       if: ${{ always() && github.event.inputs.no_cleanup != true }}
       shell: bash

pyproject.toml

@@ -28,7 +28,8 @@ dev = [
   "pytest-cov>=7.0.0",
   "ruff>=0.8.1",
   "deptry>=0.23.0",
-  "pytest-xdist[psutil]>=3.8.0"
+  "pytest-xdist[psutil]>=3.8.0",
+  "styxcache>=0.1.0"
 ]
 docs = ["pdoc>=15.0.0"]
 

tests/full_pipeline/conftest.py

@@ -10,6 +10,8 @@
 
 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
@@ -29,6 +31,21 @@
 MANIFEST_PATH = Path(__file__).parent / ".last_run.json"
 
 
+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 PipelineData(NamedTuple):
     """Shared outputs from the anatomical + functional preprocessing chain."""
 
@@ -69,6 +86,21 @@ def _niwrap_session_runner(
     runner.data_dir = data_dir
     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),
+        )
+        niwrap.set_global_runner(wrapped)
+        return wrapped
     return runner