@@ -339,7 +339,7 @@ def test_user_override_ungates_a_session_tracked_without_identities() -> None:
 
 
 def test_explicit_identity_free_argument_wins_over_the_manifest() -> None:
-    """_run_one_session passes the answer it already holds, since it is
+    """_run_one_unit passes the answer it already holds, since it is
     keyed by ref.session_id and a reader-derived id may differ."""
     from track2data.api import Engine
 
@@ -1490,7 +1490,7 @@ def _report_fingerprint(report: PreprocessReport) -> list[tuple]:
 def test_run_attaches_preprocess_report_to_session_run_result(tmp_path: Path) -> None:
     """SessionRunResult.preprocess_report must carry the same PreprocessReport
     that Engine.preprocess() produces for that session -- currently it's
-    computed but discarded before _run_one_session() builds the result."""
+    computed but discarded before _run_one_unit() builds the result."""
     from track2data.api import Engine
 
     session = _make_session(n_frames=10, n_animals=1)
@@ -1533,7 +1533,7 @@ def failing_preprocess(_session):
 
 
 def test_run_keeps_preprocess_report_when_a_later_stage_fails(tmp_path: Path) -> None:
-    """_run_one_session()'s except block covers import, preprocess, metrics,
+    """_run_one_unit()'s except block covers import, preprocess, metrics,
     payload build and export alike. When preprocessing succeeded and a *later*
     stage blew up, the report exists and is exactly what the user needs to
     diagnose the failure -- it must not be discarded along with the rest."""
 
@@ -249,7 +249,7 @@ def test_task_failure_shows_a_dialog_with_message_and_traceback(
 ) -> None:
     """Engine.run is patched directly, not a sub-step: a session-level
     exception from import/preprocess/metrics/export is caught by
-    Engine._run_one_session into SessionRunResult.error and still yields
+    Engine._run_one_unit into SessionRunResult.error and still yields
     a *successful* RunResult, never a taskFinished(..., Exception) --
     that's the whole point of #7's fix, extending the same per-session
     resilience that already covered preprocess/metrics/export to import
 
@@ -0,0 +1,58 @@
+"""`run` and `validate` on a 3-D project with fusable pairs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from tests.test_fusion.scene import build_scene, fusion_settings, pair
+from track2data.cli import cli
+from track2data.core.manifest import write as write_manifest
+
+
+def _project(tmp_path: Path, **kw: object) -> Path:
+    path = tmp_path / "p3d.t2d.json"
+    write_manifest(build_scene(tmp_path / "data", **kw), path)  # type: ignore[arg-type]
+    return path
+
+
+def test_run_3d_project_writes_pair_units_and_lists_the_skips(tmp_path: Path) -> None:
+    out = tmp_path / "out"
+    result = CliRunner().invoke(
+        cli, ["run", str(_project(tmp_path, side2_fps=10.0)), "-o", str(out)]
+    )
+    assert result.exit_code == 0, result.output
+    assert (out / "t1+s1").is_dir()
+    assert not (out / "t2+s2").exists()
+    assert "[skipped] t2: pair t2+s2: frame rates differ: 25 vs 10 fps" in result.output
+    assert "[skipped] lone: not in a fusable pair" in result.output
+    assert "Traceback" not in result.output
+
+
+def test_run_3d_project_with_no_fusable_pair_refuses(tmp_path: Path) -> None:
+    pairs = [pair("t1", "s1", fusion=fusion_settings(frame_offset=1000))]
+    out = tmp_path / "out"
+    result = CliRunner().invoke(
+        cli, ["run", str(_project(tmp_path, pairs=pairs)), "-o", str(out)]
+    )
+    assert result.exit_code == 2
+    assert "[error] no pair is ready to fuse: pair t1+s1: " in result.output
+    assert "Running" not in result.output
+    assert not out.exists()
+
+
+def test_validate_3d_reports_pair_issues_and_passes(tmp_path: Path) -> None:
+    result = CliRunner().invoke(cli, ["validate", str(_project(tmp_path, side2_fps=10.0))])
+    assert result.exit_code == 0, result.output
+    assert "[issue] pair t2+s2: frame rates differ: 25 vs 10 fps" in result.output
+    assert "[issue] session lone: not in a fusable pair" in result.output
+    assert "ready to run" in result.output
+
+
+def test_validate_3d_fails_when_no_pair_fuses(tmp_path: Path) -> None:
+    pairs = [pair("t1", "s1", fusion=fusion_settings(frame_offset=1000))]
+    result = CliRunner().invoke(cli, ["validate", str(_project(tmp_path, pairs=pairs))])
+    assert result.exit_code == 1
+    assert "[issue] no pair is ready to fuse: pair t1+s1: " in result.output
+    assert "ready to run" not in result.output
@@ -0,0 +1,125 @@
+"""A small 3-D project on disk: real idtracker.ai v5 session folders with known depths.
+
+The folders are read by a built-in reader, so a spawned worker process (which sees none of the
+tests' monkeypatches) runs exactly what the calling process runs.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+import numpy as np
+
+from track2data.core.models import (
+    CalibrationConfig,
+    FusionSettings,
+    MetricSelection,
+    ProjectManifest,
+    ProjectMode,
+    SessionRef,
+    ViewPair,
+)
+
+N_FRAMES = 100
+FPS = 25.0
+#: Side-view rows of fish 0, 1, 2: depth 0.25 / 0.5 / 0.75 between surface row 100 and floor 300.
+SIDE_ROWS = (150.0, 200.0, 250.0)
+DEPTHS = (0.25, 0.5, 0.75)
+TANK_CM = 20.0
+LABELS = ("0", "1", "2")  # the v5 reader has no labels, so fish are named by column
+
+
+def write_v5_session(folder: Path, xy: np.ndarray, *, fps: float = FPS) -> Path:
+    """Write ``xy`` (n_frames, n_animals, 2) as an idtracker.ai v5 session folder."""
+    (folder / "trajectories").mkdir(parents=True)
+    np.save(folder / "trajectories" / "trajectories.npy", xy)
+    n_frames, n_animals = xy.shape[:2]
+    np.save(
+        folder / "video_object.npy",
+        {
+            "fps": fps,
+            "frame_number": n_frames,
+            "height": 400,
+            "width": 400,
+            "paths_to_video_files": ["video.mp4"],
+        },
+    )
+    (folder / "session_progress.json").write_text(
+        json.dumps(
+            {
+                "session_name": folder.name,
+                "number_of_animals": n_animals,
+                "frames_per_second": fps,
+                "video_height": 400,
+                "video_width": 400,
+                "status": "finished",
+            }
+        ),
+        encoding="utf-8",
+    )
+    return folder
+
+
+def top_xy(shift: float = 0.0) -> np.ndarray:
+    t = np.arange(N_FRAMES, dtype=float)
+    out = np.empty((N_FRAMES, 3, 2))
+    for k in range(3):
+        out[:, k, 0] = 20 + 10 * k + t + shift
+        out[:, k, 1] = 50 + 20 * k
+    return out
+
+
+def side_xy(shift: float = 0.0) -> np.ndarray:
+    out = top_xy(shift)
+    for k in range(3):
+        out[:, k, 1] = SIDE_ROWS[k]
+    return out
+
+
+def fusion_settings(**kw: object) -> FusionSettings:
+    base: dict[str, object] = {"surface_row": 100.0, "floor_row": 300.0, "tank_height_cm": TANK_CM}
+    base.update(kw)
+    return FusionSettings(**base)  # type: ignore[arg-type]
+
+
+def pair(top: str, side: str, *, fusion: FusionSettings | None = None) -> ViewPair:
+    return ViewPair(
+        top_session_id=top,
+        side_session_id=side,
+        fish_map={lab: lab for lab in LABELS},
+        fusion=fusion if fusion is not None else fusion_settings(),
+    )
+
+
+def build_scene(
+    base: Path,
+    *,
+    side2_fps: float = FPS,
+    pairs: list[ViewPair] | None = None,
+    with_lone: bool = True,
+) -> ProjectManifest:
+    """Two top/side pairs (t1+s1, t2+s2) and, with ``with_lone``, a top session in no pair.
+
+    ``side2_fps`` other than ``FPS`` makes the second pair fail to fuse (frame rates differ).
+    """
+    write_v5_session(base / "t1", top_xy())
+    write_v5_session(base / "s1", side_xy())
+    write_v5_session(base / "t2", top_xy(5.0))
+    write_v5_session(base / "s2", side_xy(5.0), fps=side2_fps)
+    ids = ["t1", "s1", "t2", "s2"]
+    if with_lone:
+        write_v5_session(base / "lone", top_xy(9.0))
+        ids.append("lone")
+    now = datetime.now(tz=UTC)
+    return ProjectManifest(
+        project_name="scene3d",
+        created_at=now,
+        updated_at=now,
+        sessions=[SessionRef(session_id=i, folder=base / i, sha256="") for i in ids],
+        mode=ProjectMode(dimension="3d", layout="two_videos"),
+        calibration=CalibrationConfig(mode="scalar", px_per_cm=10.0),
+        metrics=MetricSelection(individual=["IL-1", "IL-15"], group=[], zone=[], diagnostic=[]),
+        view_pairs=pairs if pairs is not None else [pair("t1", "s1"), pair("t2", "s2")],
+    )