Move rbc scratch dirs off cache shards via independent scratch root

Two problems with the prior generate_exec_folder pattern:

1. It hijacked the niwrap runner's data_dir + uid + execution_counter,
   forcing _CacheProxyingRunner to forward those attributes through to
   the base runner on every access.
2. Several rbc sites then wrote sibling files via `input_file.parent /
   ...`. When input_file was served from a styxcache shard (which is
   the norm under caching), those writes landed inside the shard,
   racing other workers' reads and silently truncating cached files.
   The test_single_session_qc EOFError was a cached .nii.gz truncated
   this way.

generate_exec_folder now owns its own root (RBC_SCRATCH_DIR override,
else a process-unique tempfile.mkdtemp). Every touched call site was
migrated off `input_file.parent / ...` to `generate_exec_folder(...) /
...`. Sites audited:
  - core/functional/resampling.py:107, 201
  - core/functional/nuisance.py:112
  - core/longitudinal/transform.py:145
  - core/longitudinal/freesurfer.py:142
  - core/metrics/reho.py:191
  - core/metrics/alff.py:259
  - core/metrics/standardization.py:74
  - core/metrics/timeseries.py:159

distortion.py's topup.parent is a read-only lookup into the tool's own
output set (no write), left as-is.

Unit tests for generate_exec_folder rewritten for the new semantics:
no more uid/counter-based naming, just unique scratch dirs.

Author: nx10

src/rbc/core/functional/nuisance.py

@@ -109,7 +109,7 @@ def bandpass_regressor_file(
         f_data[~freq_mask] = 0.0
         filtered[:, col] = np.real(ifft(f_data))[:n_tp]
 
-    out_path = regressor_file.parent / "regressors_filtered.1D"
+    out_path = generate_exec_folder("regressors_filtered") / "regressors_filtered.1D"
     with out_path.open("w") as f:
         for line in header_lines:
             f.write(line)

src/rbc/core/functional/resampling.py

@@ -104,7 +104,7 @@ def apply_motion_transforms(
         )
         transformed_vols.append(result.output.output_image_outfile)
 
-    out_path = transformed_vols[0].parent / "preproc_bold.nii.gz"
+    out_path = generate_exec_folder("preproc_bold_merge") / "preproc_bold.nii.gz"
     merged = merge_3d_to_4d(transformed_vols, out_path)
 
     # antsApplyTransforms writes the reference image's pixdim into the output
@@ -198,7 +198,10 @@ def resample_bold_to_template(
         )
         transformed_vols.append(result.output.output_image_outfile)
 
-    out_path = transformed_vols[0].parent / "bold_to_template_resampled.nii.gz"
+    out_path = (
+        generate_exec_folder("bold_to_template_merge")
+        / "bold_to_template_resampled.nii.gz"
+    )
     merged = merge_3d_to_4d(transformed_vols, out_path)
 
     # antsApplyTransforms writes the reference (template) image's pixdim into

src/rbc/core/longitudinal/freesurfer.py

@@ -16,6 +16,7 @@
 from niwrap import freesurfer
 
 from rbc.core.fsl2itk import mat_to_itk
+from rbc.core.niwrap import generate_exec_folder
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -139,7 +140,7 @@ def fs_to_itk_xfm(
     for ses, source, in_xfm in zip(sessions, sources, in_xfms, strict=True):
         fsl_fname = in_xfm.with_suffix(".mat").name
         lta = freesurfer.lta_convert(in_lta=in_xfm, out_fsl=fsl_fname)
-        itk_path = in_xfm.parent / itk_filename(sub, ses)
+        itk_path = generate_exec_folder("itk_xfm") / itk_filename(sub, ses)
         mat_to_itk(
             mat=lta.root / fsl_fname,
             reference=reference,

src/rbc/core/longitudinal/transform.py

@@ -8,6 +8,7 @@
 
 from rbc.core.common import merge_3d_to_4d, split_4d
 from rbc.core.functional.resampling import _restore_tr
+from rbc.core.niwrap import generate_exec_folder
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -142,7 +143,10 @@ def _transform_4d_chunked(in_file: Path, template: Path, xfm: Path) -> Path:
         )
         transformed_vols.append(result.output.output_image_outfile)
 
-    out_path = transformed_vols[0].parent / "bold_to_longitudinal.nii.gz"
+    out_path = (
+        generate_exec_folder("bold_to_longitudinal_merge")
+        / "bold_to_longitudinal.nii.gz"
+    )
     merged = merge_3d_to_4d(transformed_vols, out_path)
     _restore_tr(merged, in_file)
     return merged

src/rbc/core/metrics/alff.py

@@ -17,6 +17,7 @@
 import numpy as np
 
 from rbc.core.nifti import Volume
+from rbc.core.niwrap import generate_exec_folder
 
 if TYPE_CHECKING:
     from typing import Literal
@@ -256,7 +257,8 @@ def compute_alff(
 
     stem = in_file.name.split(".nii")[0]
     if out_file is None:
-        alff_path = in_file.parent / f"{stem}_alff.nii.gz"
+        out_dir = generate_exec_folder("alff")
+        alff_path = out_dir / f"{stem}_alff.nii.gz"
     else:
         alff_path = Path(out_file)
 

src/rbc/core/metrics/reho.py

@@ -15,6 +15,7 @@
 from scipy.stats import rankdata
 
 from rbc.core.nifti import Volume
+from rbc.core.niwrap import generate_exec_folder
 
 if TYPE_CHECKING:
     from typing import Literal
@@ -188,7 +189,7 @@ def compute_reho(
 
     if out_file is None:
         stem = in_file.name.split(".nii")[0]
-        out_file = in_file.parent / f"{stem}_reho.nii.gz"
+        out_file = generate_exec_folder("reho") / f"{stem}_reho.nii.gz"
     out_file = Path(out_file)
 
     bold.derive(reho_map).save(out_file)

src/rbc/core/metrics/standardization.py

@@ -11,6 +11,8 @@
 
 import numpy as np
 
+from rbc.core.niwrap import generate_exec_folder
+
 
 def zscore(data: np.ndarray, mask: np.ndarray) -> np.ndarray:
     """Z-score a 3D map within a brain mask.
@@ -71,7 +73,7 @@ def compute_zscore(
 
     if out_file is None:
         stem = in_file.name.split(".nii")[0]
-        out_file = in_file.parent / f"{stem}_zscored.nii.gz"
+        out_file = generate_exec_folder("zscore") / f"{stem}_zscored.nii.gz"
     out_file = Path(out_file)
 
     nib.nifti1.Nifti1Image(zscored, img.affine, img.header).to_filename(str(out_file))

src/rbc/core/metrics/timeseries.py

@@ -12,6 +12,8 @@
 
 import numpy as np
 
+from rbc.core.niwrap import generate_exec_folder
+
 logger = logging.getLogger(__name__)
 
 
@@ -156,7 +158,7 @@ def compute_timeseries(
     corr = correlation_matrix(ts)
 
     if out_dir is None:
-        out_dir = in_file.parent
+        out_dir = generate_exec_folder("timeseries")
     out_dir = Path(out_dir)
     out_dir.mkdir(parents=True, exist_ok=True)
 

src/rbc/core/niwrap.py

@@ -213,19 +213,34 @@ def mount_fs_license(runner: niwrap.Runner, fs_license: Path) -> None:
     runner.environ["FS_LICENSE"] = _CONTAINER_FS_LICENSE_PATH
 
 
-def generate_exec_folder(suffix: str = "python") -> Path:
-    """Generate an execution folder following Styx hash pattern.
+_SCRATCH_ROOT: Path | None = None
 
-    Args:
-        suffix: Task to append to suffix of folder (default: 'python')
 
-    Returns:
-        Path to created execution folder
+def _scratch_root() -> Path:
+    """Return the shared rbc scratch root, creating it on first use.
+
+    Honors ``RBC_SCRATCH_DIR`` if set; otherwise creates a process-unique
+    temp dir. Isolated from niwrap's runner data_dir so rbc scratch paths
+    never collide with or scribble into cache shards.
     """
-    runner = niwrap.get_global_runner()
-    dir_path = (
-        Path(runner.data_dir) / f"{runner.uid}_{runner.execution_counter}_{suffix}"
-    )
-    dir_path.mkdir(parents=True)
-    runner.execution_counter += 1
-    return dir_path
+    global _SCRATCH_ROOT
+    if _SCRATCH_ROOT is not None and _SCRATCH_ROOT.exists():
+        return _SCRATCH_ROOT
+    override = os.environ.get("RBC_SCRATCH_DIR")
+    if override:
+        root = Path(override)
+        root.mkdir(parents=True, exist_ok=True)
+    else:
+        root = Path(tempfile.mkdtemp(prefix="rbc_scratch_"))
+    _SCRATCH_ROOT = root
+    return root
+
+
+def generate_exec_folder(suffix: str = "python") -> Path:
+    """Create a fresh scratch directory for intermediate rbc-owned outputs.
+
+    Returns a unique directory under the rbc scratch root. The directory
+    does not live under any niwrap runner's data dir, so writes here are
+    guaranteed not to touch a cached tool output.
+    """
+    return Path(tempfile.mkdtemp(prefix=f"{suffix}_", dir=_scratch_root()))

tests/unit/core/test_longitudinal_freesurfer.py

@@ -143,9 +143,9 @@ def test_per_session_itk_naming(
             in_xfms=in_xfms,
         )
 
-        assert result == [
-            tmp_path / itk_filename("01", "baseline"),
-            tmp_path / itk_filename("01", "vis2"),
+        assert [p.name for p in result] == [
+            itk_filename("01", "baseline"),
+            itk_filename("01", "vis2"),
         ]
         assert mock_fs.lta_convert.call_count == 2
         assert mock_mat_to_itk.call_count == 2