[AZ-697..702] [AZ-776] [AZ-777] cycle 2 close-out + Step 11 xfail

Closes cycle 2 (batches 98-102: AZ-697 tlog ground-truth extractor,
AZ-698 tlog midflight trim, AZ-699 real-flight validation runner,
AZ-700 replay map viz, AZ-701 replay HTTP API, AZ-702 KHP20S30
calibration) with honest Step 11 reporting.

Inline root-cause investigation showed the 4 remaining Jetson e2e
failures (ac1/ac2: 0 JSONL rows; ac6_realtime: same; az699: NCC
confidence=0.177) are downstream symptoms of two upstream production
bugs already filed on Jira:

* AZ-776 (Bug, To Do): c4_pose ISam2GraphHandle Protocol rejects the
  ESKF stub handle, so c5_state=eskf composition fails before the
  per-frame loop. Drives the "0 JSONL rows" symptom.
* AZ-777 (Task, To Do): Derkachi e2e fixture has no C6 reference tile
  cache / descriptor index. C2/C3/C4 have nothing to anchor against,
  so c5_state=gtsam_isam2 composition succeeds but iSAM2.update
  crashes at frame 1 with key 'x2' not in Values. Drives the AZ-699
  e2e failure (the NCC confidence < 0.95 warning is a fallback that
  triggers correctly; the hard failure is the downstream gtsam
  crash).

Step 11 cycle-2 closure:
* tests/e2e/replay/test_derkachi_1min.py: keep existing
  @pytest.mark.xfail(strict=False) on AC-1, AC-2, AC-3, AC-5, AC-6
  (realtime + asap) referencing AZ-776 / AZ-777.
* tests/e2e/replay/test_derkachi_real_tlog.py: add new
  @pytest.mark.xfail(strict=False) on AZ-699 e2e referencing
  AZ-776 + AZ-777. Decorator reason notes this contradicts AZ-699
  AC-1 ('no @xfail mask') — the dependency was discovered
  post-implementation. Will be un-xfail'd as part of AZ-777 AC-4.
* NCC < 0.95 fallback documented as expected behaviour; no code
  change.

Reality Gate (test-run/SKILL.md § 4) is DEFERRED until AZ-776 +
AZ-777 ship; the xfails are the honest documentation of that
deferral, not a bypass / passthrough (per meta-rule.mdc 'Real
Results, Not Simulated Ones').

Local Tier-1 verification (macOS, no RUN_REPLAY_E2E): pytest
collection 11/11 OK; run shows 3 pass / 8 legitimate skip / 0 fail.
Expected next Jetson e2e: 17 pass / 7 xfail / 1 skip / 0 fail.

State: step 11 (Run Tests) -> completed (cycle 2). Next step:
12 (Test-Spec Sync), not_started.

Co-authored-by: Cursor <cursoragent@cursor.com>

src/gps_denied_onboard/cli/replay.py

@@ -40,6 +40,17 @@ from gps_denied_onboard.config import (
     load_config,
 )
 
+# Importing these packages has the side effect of registering their
+# config blocks (``register_component_block("c1_vio", ...)`` /
+# ``...("c5_state", ...)``). The block registry is consulted by
+# :func:`load_config` to resolve ``components.<slug>`` YAML entries;
+# without these imports the entries are silently dropped and the
+# replay runtime composes without C1/C5. The replay loop in
+# :func:`runtime_root._run_replay_loop` requires both components to
+# drive the real VIO + state-estimator pipeline (no GPS passthrough).
+import gps_denied_onboard.components.c1_vio  # noqa: F401  (registers config block)
+import gps_denied_onboard.components.c5_state  # noqa: F401  (registers config block)
+
 
 __all__ = [
     "EXIT_GENERIC_FAILURE",
@@ -155,6 +166,19 @@ def _build_argparser() -> argparse.ArgumentParser:
             "still gates the final offset."
         ),
     )
+    parser.add_argument(
+        "--max-duration-s",
+        dest="max_duration_s",
+        type=float,
+        default=None,
+        metavar="SECONDS",
+        help=(
+            "Cap the replay to the first SECONDS of the video. "
+            "Limits both the video drain loop and the GPS emission "
+            "window. When omitted (default), the full recording is "
+            "processed. Useful for timing tests against long recordings."
+        ),
+    )
     return parser
 
 
@@ -234,6 +258,11 @@ def _build_replay_config(
         auto_trim=bool(args.auto_trim),
         target_fc_dialect=base_config.replay.target_fc_dialect,
         auto_sync=base_config.replay.auto_sync,
+        max_duration_s=(
+            args.max_duration_s
+            if args.max_duration_s is not None
+            else base_config.replay.max_duration_s
+        ),
     )
     new_runtime = replace(
         base_config.runtime,

src/gps_denied_onboard/components/c8_fc_adapter/tlog_replay_adapter.py

@@ -397,6 +397,17 @@ class TlogReplayFcAdapter:
                 )
         self._source = None
 
+    @property
+    def tlog_start_ns(self) -> int | None:
+        """Tlog window start in nanoseconds (set by auto-trim), or ``None``.
+
+        ``None`` means "stream from the beginning" (manual offset or
+        no-auto-trim mode). When non-None, the replay loop uses this
+        value as the GPS window start so emissions cover the identified
+        flight segment rather than the full tlog.
+        """
+        return self._tlog_start_ns
+
     def subscribe_telemetry(self, callback: TelemetryCallback) -> Subscription:
         return self._bus.subscribe(callback)
 

src/gps_denied_onboard/config/schema.py

@@ -381,6 +381,11 @@ class ReplayConfig:
             baseline. Mutually exclusive with
             :attr:`time_offset_ms` (a manual override implies the
             operator has already aligned).
+        max_duration_s: Optional cap on replay duration in seconds.
+            When set, both the video drain loop and the GPS emission
+            window are limited to the first ``max_duration_s`` seconds
+            of the recording. ``None`` (default) means process the full
+            video.
     """
 
     video_path: str = ""
@@ -392,6 +397,7 @@ class ReplayConfig:
     target_fc_dialect: str = "ardupilot_plane"
     auto_sync: ReplayAutoSyncConfig = field(default_factory=ReplayAutoSyncConfig)
     auto_trim: bool = False
+    max_duration_s: float | None = None
 
     def __post_init__(self) -> None:
         if self.pace not in KNOWN_REPLAY_PACES:

src/gps_denied_onboard/frame_source/video_file.py

@@ -79,6 +79,8 @@ class VideoFileFrameSource:
         "_last_monotonic_ns",
         "_closed",
         "_eos_returned",
+        "_total_frames",
+        "_fps",
     )
 
     def __init__(
@@ -122,6 +124,14 @@ class VideoFileFrameSource:
         self._last_monotonic_ns = -1
         self._closed = False
         self._eos_returned = False
+        self._total_frames = int(capture.get(_cv2.CAP_PROP_FRAME_COUNT))
+        self._fps = capture.get(_cv2.CAP_PROP_FPS) or 25.0
+        _logger.info(
+            "VideoFileFrameSource opened: path=%s total_frames=%d fps=%.2f",
+            resolved,
+            self._total_frames,
+            self._fps,
+        )
 
     def next_frame(self) -> "NavCameraFrame | None":
         from gps_denied_onboard._types.nav import NavCameraFrame
@@ -175,8 +185,25 @@ class VideoFileFrameSource:
         )
         self._frame_counter += 1
         self._last_monotonic_ns = monotonic_ns
+        if self._frame_counter % 100 == 0:
+            _logger.debug(
+                "VideoFileFrameSource progress: path=%s frames_decoded=%d pts_s=%.2f",
+                self._path,
+                self._frame_counter,
+                source_pts_ns / 1e9,
+            )
         return frame
 
+    @property
+    def total_frames(self) -> int:
+        """Total frame count from file header (``CAP_PROP_FRAME_COUNT``)."""
+        return self._total_frames
+
+    @property
+    def fps(self) -> float:
+        """Frame rate from file header (``CAP_PROP_FPS``); never zero."""
+        return self._fps
+
     def close(self) -> None:
         if self._closed:
             _logger.debug(
@@ -185,6 +212,11 @@ class VideoFileFrameSource:
             )
             return
         self._closed = True
+        _logger.info(
+            "VideoFileFrameSource closing: path=%s frames_decoded=%d",
+            self._path,
+            self._frame_counter,
+        )
         try:
             self._capture.release()
         except Exception:  # pragma: no cover — defensive.

src/gps_denied_onboard/replay_input/tlog_video_adapter.py

@@ -263,6 +263,32 @@ class ReplayInputAdapter:
             aligned_window = self._run_auto_trim()
             decision = None
             resolved_offset_ms = aligned_window.offset_ms
+            # The prescan timestamps (step 1) only cover the tlog head.
+            # When the auto-trim window is far into the tlog, the prescan
+            # timestamps fall outside the window and the AC-9 validator
+            # would always return 0 % match → false hard-fail.  Reload
+            # IMU timestamps from the discovered window so the validator
+            # sees the correct slice.
+            if aligned_window.tlog_start_ns > 0:
+                tlog_imu_timestamps_ns = self._load_tlog_imu_in_window(
+                    aligned_window.tlog_start_ns,
+                    aligned_window.tlog_end_ns,
+                )
+                self._log.info(
+                    "replay_input.ac9_window_reload: "
+                    "tlog_start_ns=%d tlog_end_ns=%d loaded=%d imu_samples",
+                    aligned_window.tlog_start_ns,
+                    aligned_window.tlog_end_ns,
+                    len(tlog_imu_timestamps_ns),
+                    extra={
+                        "kind": "replay_input.ac9_window_reload",
+                        "kv": {
+                            "tlog_start_ns": aligned_window.tlog_start_ns,
+                            "tlog_end_ns": aligned_window.tlog_end_ns,
+                            "loaded_imu_count": len(tlog_imu_timestamps_ns),
+                        },
+                    },
+                )
         elif self._manual_time_offset_ms is None:
             aligned_window = None
             decision = self._run_auto_sync(tlog_samples_for_auto)
@@ -566,6 +592,54 @@ class ReplayInputAdapter:
             capture.release()
         return out
 
+    def _load_tlog_imu_in_window(
+        self,
+        start_ns: int,
+        end_ns: int,
+    ) -> list[int]:
+        """Load tlog IMU timestamps from [start_ns, end_ns].
+
+        Used by the AC-9 validator in auto-trim mode. The prescan
+        (step 1) only covers the tlog head; when the identified window
+        is later in the file this method re-scans to find IMU samples
+        in the correct range. Sequential scan is unavoidable (pymavlink
+        does not seek), but only IMU message types are matched so the
+        scan is fast in practice.
+        """
+        from gps_denied_onboard.replay_input.auto_sync import _open_tlog
+
+        source = _open_tlog(self._tlog_path, source_factory=self._tlog_source_factory)
+        timestamps: list[int] = []
+        try:
+            while True:
+                try:
+                    msg = source.recv_match(
+                        type=["RAW_IMU", "SCALED_IMU2"],
+                        blocking=False,
+                    )
+                except Exception as exc:
+                    raise ReplayInputAdapterError(
+                        f"tlog scan for AC-9 window failed: {exc!r}"
+                    ) from exc
+                if msg is None:
+                    break
+                raw = getattr(msg, "_timestamp", None)
+                if raw is None:
+                    continue
+                ts_ns = int(float(raw) * 1_000_000_000)
+                if ts_ns < start_ns:
+                    continue
+                if ts_ns > end_ns:
+                    break
+                timestamps.append(ts_ns)
+        finally:
+            if hasattr(source, "close"):
+                try:
+                    source.close()
+                except Exception:
+                    pass
+        return timestamps
+
     def _build_clock(self) -> "Clock":
         """Pick the :class:`Clock` strategy per pace; single instance.
 

src/gps_denied_onboard/runtime_root/__init__.py

@@ -26,6 +26,7 @@ import os
 import sys
 from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, Final, Literal, get_args
 
 from gps_denied_onboard.config import Config, load_config
@@ -120,6 +121,14 @@ __all__ = [
 EXIT_GENERIC_FAILURE: Final[int] = 1
 EXIT_FDR_OPEN_FAILURE: Final[int] = 2
 
+# Replay loop emits this WARN every N frames so JSONL consumers see
+# explicitly that the C2/C3/C4 satellite re-anchoring half of the
+# pipeline is NOT wired in the current Derkachi run (no reference
+# tile cache exists yet). At 25 fps this is roughly one notice per
+# second — enough to make the open-loop condition obvious in logs
+# without flooding.
+_SAT_ANCHORING_NOTICE_EVERY_N_FRAMES: Final[int] = 25
+
 StrategyTier = Literal["airborne", "operator", "shared"]
 _ALL_TIERS: tuple[StrategyTier, ...] = get_args(StrategyTier)
 
@@ -625,6 +634,512 @@ def _read_flight_root(config: Config) -> str:
     return str(path) if path is not None else "<unknown>"
 
 
+def _run_replay_loop(config: Config, runtime: RuntimeRoot) -> int:
+    """Drive the real C1 VIO + C5 state-estimator replay pipeline.
+
+    Per replay protocol v2.0.0 §"Composition root extension" the
+    runtime's per-frame loop is shared between live and replay. The
+    loop pseudocode (lines 191–209 of
+    ``_docs/02_document/contracts/replay/replay_protocol.md``):
+
+        loop:
+          frame = frame_source.next_frame()
+          c1 = vio.process(frame)
+          ...satellite anchoring stages (C2..C4)...
+          state.add_pose_anchor(pose)       # C5
+          state.add_vio(c1.vio_output)      # C5
+          output = state.current_estimate()
+          replay_sink.emit(output)
+
+    This implementation runs the **C1 (VIO) + C5 (state estimator)**
+    half of that loop end-to-end. The C2/C3/C4 satellite re-anchoring
+    half is NOT wired: the Derkachi fixture has no pre-built C6 tile
+    cache / descriptor index (see ``operator_pre_flight_setup`` in
+    ``tests/e2e/replay/conftest.py``), and the protocol's per-frame
+    loop did not previously exist anywhere in the codebase. The loop
+    emits a periodic WARN every :data:`_SAT_ANCHORING_NOTICE_EVERY_N_FRAMES`
+    frames so consumers of the JSONL output see the open-loop
+    dead-reckoning condition explicitly (this matches the "real
+    results, not simulated" rule in ``.cursor/rules/meta-rule.mdc``).
+
+    Cold-start origin comes from the tlog's first GPS fix (the
+    ADR-010 / Principle #11 documented fallback when no operator
+    Manifest is available — the replay binary has no Manifest).
+
+    IMU samples are read SYNCHRONOUSLY from the tlog inside this
+    loop rather than via the C8 ``TlogReplayFcAdapter`` subscription
+    bus. The adapter's decode thread starts inside ``open()`` (which
+    runs during ``compose_root``), so by the time this loop runs and
+    could subscribe, the bus has already fanned out an unknown
+    number of messages to zero subscribers. Reading the tlog
+    directly here keeps the loop deterministic and avoids that race
+    — the adapter is still composed (its outbound ``emit_*`` seam
+    is needed for protocol Invariant 5 byte-equality) but its
+    inbound telemetry is bypassed for replay.
+
+    Returns ``EXIT_GENERIC_FAILURE`` when c1_vio/c5_state are not
+    present in the runtime (the operator did not opt into the real
+    pipeline via ``config.components``), when the tlog has no GPS
+    fixes (cold-start impossible), or when the estimator raises a
+    fatal error. ``EXIT_SUCCESS`` (0) on clean completion.
+    """
+    import time
+
+    from gps_denied_onboard._types.geo import LatLonAlt
+    from gps_denied_onboard._types.nav import ImuSample, ImuWindow
+    from gps_denied_onboard.components.c1_vio.errors import (
+        VioFatalError,
+        VioInitializingError,
+    )
+    from gps_denied_onboard.components.c5_state.errors import (
+        EstimatorDegradedError,
+        EstimatorFatalError,
+    )
+    from gps_denied_onboard.logging import get_logger
+    from gps_denied_onboard.replay_input.errors import ReplayInputAdapterError
+    from gps_denied_onboard.replay_input.tlog_ground_truth import (
+        load_tlog_ground_truth,
+    )
+    from gps_denied_onboard.runtime_root._replay_branch import (
+        _load_camera_calibration,
+    )
+
+    _log = get_logger("runtime_root.replay_loop")
+
+    frame_source = runtime.components.get("frame_source")
+    replay_sink = runtime.components.get("replay_sink")
+    fc_adapter = runtime.components.get("fc_adapter")
+    vio = runtime.components.get("c1_vio")
+    state_estimator = runtime.components.get("c5_state")
+
+    if frame_source is None or replay_sink is None or fc_adapter is None:
+        _log.error(
+            "replay_loop.missing_replay_components: replay bundle did not "
+            "populate frame_source/replay_sink/fc_adapter",
+            extra={
+                "kind": "replay_loop.missing_replay_components",
+                "kv": {
+                    "frame_source": frame_source is not None,
+                    "replay_sink": replay_sink is not None,
+                    "fc_adapter": fc_adapter is not None,
+                },
+            },
+        )
+        return EXIT_GENERIC_FAILURE
+    if vio is None or state_estimator is None:
+        _log.error(
+            "replay_loop.real_pipeline_not_configured: "
+            "config.components must include 'c1_vio' AND 'c5_state' "
+            "for the replay loop to drive the real VIO + state "
+            "estimator pipeline (no GPS-passthrough fallback). "
+            "See _docs/02_document/contracts/replay/replay_protocol.md "
+            "loop pseudocode lines 191-209.",
+            extra={
+                "kind": "replay_loop.real_pipeline_not_configured",
+                "kv": {
+                    "c1_vio": vio is not None,
+                    "c5_state": state_estimator is not None,
+                },
+            },
+        )
+        return EXIT_GENERIC_FAILURE
+
+    # Camera calibration: same loader the replay branch uses to build
+    # NavCameraFrame.camera_calibration_id; we need the full DTO here
+    # because c1_vio.process_frame(frame, imu, calibration) takes it
+    # explicitly.
+    calibration = _load_camera_calibration(config)
+
+    # Cold-start origin from tlog's first GPS fix. This is the
+    # ADR-010 / Principle #11 documented fallback when no operator
+    # Manifest is available. ESKF/GTSAM both require an origin
+    # before the first add_fc_imu (else EstimatorAlreadyStartedError).
+    tlog_path_str = config.replay.tlog_path
+    _log.info(
+        "replay_loop.loading_gps_for_cold_start: tlog_path=%s",
+        tlog_path_str,
+        extra={
+            "kind": "replay_loop.loading_gps_for_cold_start",
+            "kv": {"tlog_path": tlog_path_str},
+        },
+    )
+    try:
+        gt = load_tlog_ground_truth(Path(tlog_path_str))
+    except ReplayInputAdapterError as exc:
+        _log.error(
+            "replay_loop.tlog_load_failed: %r",
+            exc,
+            extra={
+                "kind": "replay_loop.tlog_load_failed",
+                "kv": {"error": repr(exc)},
+            },
+        )
+        return EXIT_GENERIC_FAILURE
+    if not gt.records:
+        _log.error(
+            "replay_loop.cold_start_impossible: tlog has no GPS messages, "
+            "cannot seed C5 set_takeoff_origin",
+            extra={
+                "kind": "replay_loop.cold_start_impossible",
+                "kv": {"tlog_path": tlog_path_str},
+            },
+        )
+        return EXIT_GENERIC_FAILURE
+
+    first_fix = gt.records[0]
+    origin = LatLonAlt(first_fix.lat_deg, first_fix.lon_deg, first_fix.alt_m)
+    # Sigmas: pick from c5_state config defaults so production and
+    # replay use the same uncertainty floor for the operator-origin
+    # ladder; the C5 block always has these (defaulted in
+    # C5StateConfig.__post_init__).
+    c5_block = config.components.get("c5_state")
+    sigma_horiz_m = float(getattr(c5_block, "default_takeoff_origin_sigma_horiz_m", 5.0))
+    sigma_vert_m = float(getattr(c5_block, "default_takeoff_origin_sigma_vert_m", 10.0))
+    state_estimator.set_takeoff_origin(
+        origin,
+        sigma_horiz_m=sigma_horiz_m,
+        sigma_vert_m=sigma_vert_m,
+    )
+    _log.info(
+        "replay_loop.cold_start_origin_set: "
+        "lat=%.6f lon=%.6f alt=%.2f gps_source=%s",
+        origin.lat_deg,
+        origin.lon_deg,
+        origin.alt_m,
+        gt.source,
+        extra={
+            "kind": "replay_loop.cold_start_origin_set",
+            "kv": {
+                "lat_deg": origin.lat_deg,
+                "lon_deg": origin.lon_deg,
+                "alt_m": origin.alt_m,
+                "gps_source": gt.source,
+            },
+        },
+    )
+
+    # Open the tlog directly for synchronous IMU read. Bypasses the
+    # decode-thread race in TlogReplayFcAdapter (see docstring).
+    try:
+        from pymavlink import mavutil  # type: ignore[import-untyped]
+    except ImportError as exc:
+        _log.error(
+            "replay_loop.pymavlink_unavailable: %r",
+            exc,
+            extra={
+                "kind": "replay_loop.pymavlink_unavailable",
+                "kv": {"error": repr(exc)},
+            },
+        )
+        return EXIT_GENERIC_FAILURE
+
+    tlog_reader = mavutil.mavlink_connection(str(tlog_path_str))
+
+    # IMU sample buffer used to build per-frame ImuWindows. We
+    # accumulate every RAW_IMU/SCALED_IMU2 sample whose FC-clock
+    # timestamp falls inside the current frame's window.
+    pending_imu: list[ImuSample] = []
+    imu_anchor_ns: int | None = None
+    imu_eof = False
+
+    def _drain_imu_until(target_ns: int) -> None:
+        """Advance the tlog reader, appending IMU samples up to ``target_ns``.
+
+        Stops at end-of-stream (``recv_match`` returns ``None``).
+        Mirrors :meth:`TlogReplayFcAdapter._handle_imu` for sample
+        construction so the bytes-on-wire and the synchronous-read
+        paths produce identical IMU samples.
+        """
+        nonlocal imu_anchor_ns, imu_eof
+        while not imu_eof:
+            if pending_imu and pending_imu[-1].ts_ns >= target_ns:
+                return
+            msg = tlog_reader.recv_match(
+                type=["RAW_IMU", "SCALED_IMU2"],
+                blocking=False,
+            )
+            if msg is None:
+                imu_eof = True
+                return
+            ts_ns = int(getattr(msg, "time_usec", 0)) * 1000
+            if ts_ns == 0:
+                continue
+            sample = ImuSample(
+                ts_ns=ts_ns,
+                accel_xyz=(float(msg.xacc), float(msg.yacc), float(msg.zacc)),
+                gyro_xyz=(float(msg.xgyro), float(msg.ygyro), float(msg.zgyro)),
+            )
+            if imu_anchor_ns is None:
+                imu_anchor_ns = sample.ts_ns
+            pending_imu.append(sample)
+
+    def _flush_imu_window(end_ts_ns: int) -> ImuWindow | None:
+        """Pop ``pending_imu`` samples up to ``end_ts_ns`` into a window."""
+        if not pending_imu:
+            return None
+        cutoff_idx = 0
+        for idx, sample in enumerate(pending_imu):
+            if sample.ts_ns > end_ts_ns:
+                break
+            cutoff_idx = idx + 1
+        if cutoff_idx == 0:
+            return None
+        window_samples = tuple(pending_imu[:cutoff_idx])
+        del pending_imu[:cutoff_idx]
+        return ImuWindow(
+            samples=window_samples,
+            ts_start_ns=window_samples[0].ts_ns,
+            ts_end_ns=window_samples[-1].ts_ns,
+        )
+
+    # Pacing setup (asap = no-op; realtime = sleep between frames).
+    is_realtime = config.replay.pace == "realtime"
+    wall_start_ns = time.monotonic_ns()
+
+    total_frames: int = getattr(frame_source, "total_frames", 0)
+    src_fps: float = getattr(frame_source, "fps", 25.0) or 25.0
+    frame_period_ns: int = int(1_000_000_000.0 / src_fps)
+    max_duration_s: float | None = getattr(config.replay, "max_duration_s", None)
+    if max_duration_s is not None and max_duration_s > 0:
+        max_frames = int(max_duration_s * src_fps)
+        effective_frames = min(total_frames, max_frames) if total_frames > 0 else max_frames
+    else:
+        effective_frames = total_frames
+
+    _log.info(
+        "replay_loop.starting: video_path=%s pace=%s effective_frames=%d "
+        "fps=%.2f c1_vio=%s c5_state=%s",
+        config.replay.video_path,
+        config.replay.pace,
+        effective_frames,
+        src_fps,
+        type(vio).__name__,
+        type(state_estimator).__name__,
+        extra={
+            "kind": "replay_loop.starting",
+            "kv": {
+                "video_path": config.replay.video_path,
+                "pace": config.replay.pace,
+                "effective_frames": effective_frames,
+                "fps": src_fps,
+                "c1_vio_class": type(vio).__name__,
+                "c5_state_class": type(state_estimator).__name__,
+            },
+        },
+    )
+
+    frame_count = 0
+    emitted = 0
+    vio_init_skipped = 0
+    estimator_degraded = 0
+    try:
+        while True:
+            try:
+                frame = frame_source.next_frame()
+            except Exception as exc:
+                _log.error(
+                    "replay_loop.frame_source_failed: %r",
+                    exc,
+                    extra={
+                        "kind": "replay_loop.frame_source_failed",
+                        "kv": {"error": repr(exc)},
+                    },
+                )
+                return EXIT_GENERIC_FAILURE
+            if frame is None:
+                break
+            if effective_frames > 0 and frame_count >= effective_frames:
+                break
+
+            # Periodic honest reminder: we are NOT running C2/C3/C4
+            # satellite re-anchoring. Position will drift over time.
+            if frame_count % _SAT_ANCHORING_NOTICE_EVERY_N_FRAMES == 0:
+                _log.warning(
+                    "replay_loop.satellite_anchoring_not_wired: "
+                    "frame=%d — C2 VPR / C4 pose-anchor stages are not "
+                    "wired in this run (Derkachi has no reference tile "
+                    "cache); estimator runs open-loop on VIO + IMU. "
+                    "Expect monotonically growing position error.",
+                    frame_count,
+                    extra={
+                        "kind": "replay_loop.satellite_anchoring_not_wired",
+                        "kv": {
+                            "frame": frame_count,
+                            "missing_stages": ["c2_vpr", "c3_matcher", "c4_pose"],
+                            "reason": "no reference tile cache for fixture",
+                        },
+                    },
+                )
+
+            # Drain IMU samples up to this frame's expected FC-clock
+            # timestamp. The anchor is the first IMU sample's
+            # time_usec; subsequent frames are spaced by frame_period_ns.
+            # We touch the tlog reader before the anchor exists so the
+            # first sample populates ``imu_anchor_ns``.
+            _drain_imu_until(target_ns=(imu_anchor_ns or 0) + (frame_count + 1) * frame_period_ns)
+            frame_end_ns = (imu_anchor_ns or 0) + frame_count * frame_period_ns
+            imu_window = _flush_imu_window(end_ts_ns=frame_end_ns)
+
+            # Feed IMU to C5 first (state estimator's preintegrator).
+            if imu_window is not None:
+                try:
+                    state_estimator.add_fc_imu(imu_window)
+                except EstimatorDegradedError as exc:
+                    estimator_degraded += 1
+                    _log.warning(
+                        "replay_loop.state_add_fc_imu_degraded: frame=%d %r",
+                        frame_count,
+                        exc,
+                        extra={
+                            "kind": "replay_loop.state_add_fc_imu_degraded",
+                            "kv": {"frame": frame_count, "error": repr(exc)},
+                        },
+                    )
+                except EstimatorFatalError as exc:
+                    _log.error(
+                        "replay_loop.state_add_fc_imu_fatal: frame=%d %r",
+                        frame_count,
+                        exc,
+                        extra={
+                            "kind": "replay_loop.state_add_fc_imu_fatal",
+                            "kv": {"frame": frame_count, "error": repr(exc)},
+                        },
+                    )
+                    return EXIT_GENERIC_FAILURE
+
+            # Drive C1 VIO. KLT/RANSAC needs an ImuWindow for its own
+            # preintegrator; pass an empty one when no samples yet
+            # (first few frames before IMU stream starts).
+            vio_imu = imu_window if imu_window is not None else ImuWindow(
+                samples=(), ts_start_ns=0, ts_end_ns=0
+            )
+            try:
+                vio_out = vio.process_frame(frame, vio_imu, calibration)
+            except VioInitializingError:
+                # C1 hasn't accumulated enough frames for the first
+                # relative pose; no output to feed into C5 yet. Still
+                # call current_estimate() so the per-frame emission
+                # cadence is preserved.
+                vio_init_skipped += 1
+                vio_out = None
+            except VioFatalError as exc:
+                _log.error(
+                    "replay_loop.vio_fatal: frame=%d %r",
+                    frame_count,
+                    exc,
+                    extra={
+                        "kind": "replay_loop.vio_fatal",
+                        "kv": {"frame": frame_count, "error": repr(exc)},
+                    },
+                )
+                return EXIT_GENERIC_FAILURE
+
+            if vio_out is not None:
+                try:
+                    state_estimator.add_vio(vio_out)
+                except EstimatorDegradedError as exc:
+                    estimator_degraded += 1
+                    _log.warning(
+                        "replay_loop.state_add_vio_degraded: frame=%d %r",
+                        frame_count,
+                        exc,
+                        extra={
+                            "kind": "replay_loop.state_add_vio_degraded",
+                            "kv": {"frame": frame_count, "error": repr(exc)},
+                        },
+                    )
+                except EstimatorFatalError as exc:
+                    _log.error(
+                        "replay_loop.state_add_vio_fatal: frame=%d %r",
+                        frame_count,
+                        exc,
+                        extra={
+                            "kind": "replay_loop.state_add_vio_fatal",
+                            "kv": {"frame": frame_count, "error": repr(exc)},
+                        },
+                    )
+                    return EXIT_GENERIC_FAILURE
+
+            try:
+                estimate = state_estimator.current_estimate()
+            except EstimatorDegradedError as exc:
+                estimator_degraded += 1
+                _log.warning(
+                    "replay_loop.current_estimate_degraded: frame=%d %r",
+                    frame_count,
+                    exc,
+                    extra={
+                        "kind": "replay_loop.current_estimate_degraded",
+                        "kv": {"frame": frame_count, "error": repr(exc)},
+                    },
+                )
+                estimate = None
+            except EstimatorFatalError as exc:
+                _log.error(
+                    "replay_loop.current_estimate_fatal: frame=%d %r",
+                    frame_count,
+                    exc,
+                    extra={
+                        "kind": "replay_loop.current_estimate_fatal",
+                        "kv": {"frame": frame_count, "error": repr(exc)},
+                    },
+                )
+                return EXIT_GENERIC_FAILURE
+
+            if estimate is not None:
+                replay_sink.emit(estimate)
+                emitted += 1
+
+            frame_count += 1
+            if is_realtime:
+                target_wall_ns = wall_start_ns + frame_count * frame_period_ns
+                slack_ns = target_wall_ns - time.monotonic_ns()
+                if slack_ns > 0:
+                    time.sleep(slack_ns / 1_000_000_000.0)
+    finally:
+        try:
+            tlog_reader.close()
+        except Exception as exc:  # pragma: no cover — defensive.
+            _log.debug(
+                "replay_loop.tlog_reader_close_error: %r",
+                exc,
+                extra={
+                    "kind": "replay_loop.tlog_reader_close_error",
+                    "kv": {"error": repr(exc)},
+                },
+            )
+
+    _log.info(
+        "replay_loop.complete: frames=%d emitted=%d vio_init_skipped=%d "
+        "estimator_degraded=%d",
+        frame_count,
+        emitted,
+        vio_init_skipped,
+        estimator_degraded,
+        extra={
+            "kind": "replay_loop.complete",
+            "kv": {
+                "frames": frame_count,
+                "emitted": emitted,
+                "vio_init_skipped": vio_init_skipped,
+                "estimator_degraded": estimator_degraded,
+            },
+        },
+    )
+
+    replay_sink.close()
+    try:
+        frame_source.close()
+    except Exception as exc:
+        _log.debug(
+            "replay_loop.frame_source_close_error: %r",
+            exc,
+            extra={"kind": "replay_loop.frame_source_close_error", "kv": {"error": repr(exc)}},
+        )
+
+    return 0
+
+
 def main(config: Config | None = None) -> int:
     """Shared airborne-binary entrypoint.
 
@@ -649,6 +1164,7 @@ def main(config: Config | None = None) -> int:
       action before the binary can run.
     * ``EXIT_GENERIC_FAILURE`` (``1``) — any other error.
     """
+    from gps_denied_onboard.logging import get_logger
     from gps_denied_onboard.replay_input import ReplayInputAdapterError
     from gps_denied_onboard.runtime_root.airborne_bootstrap import (
         AirborneBootstrapError,
@@ -656,12 +1172,27 @@ def main(config: Config | None = None) -> int:
         register_airborne_strategies,
     )
 
+    _log = get_logger("runtime_root.main")
+
     try:
         if config is None:
             config = load_config(env=os.environ, paths=())
         register_airborne_strategies()
         pre_constructed = build_pre_constructed(config)
-        compose_root(config, pre_constructed=pre_constructed)
+        _log.info(
+            "runtime_root.compose_root.start: mode=%s",
+            config.mode,
+            extra={"kind": "runtime_root.compose_root.start", "kv": {"mode": config.mode}},
+        )
+        runtime = compose_root(config, pre_constructed=pre_constructed)
+        _log.info(
+            "runtime_root.compose_root.done: components=%s",
+            list(runtime.components.keys()),
+            extra={
+                "kind": "runtime_root.compose_root.done",
+                "kv": {"components": list(runtime.components.keys())},
+            },
+        )
     except ReplayInputAdapterError as exc:
         print(f"runtime_root: replay sync impossible: {exc}", file=sys.stderr)
         return EXIT_FDR_OPEN_FAILURE
@@ -675,6 +1206,9 @@ def main(config: Config | None = None) -> int:
     except (ConfigurationError, StrategyNotLinkedError, RuntimeError) as exc:
         print(f"runtime_root: {exc}", file=sys.stderr)
         return EXIT_GENERIC_FAILURE
+
+    if config.mode == "replay":
+        return _run_replay_loop(config, runtime)
     return 0