fix(cloudxr): show OOB setup progress to embedded operators

docs/source/references/oob_teleop_control.rst

@@ -46,6 +46,14 @@ change opens a fresh 60-second recovery episode. Override the positive,
 finite values with ``TELEOP_OOB_RECOVERY_TIMEOUT_SEC`` and
 ``TELEOP_OOB_RETRY_INTERVAL_SEC``; invalid values fail host preflight.
 
+At INFO, OOB progress reports headset waiting and connection, browser readiness,
+and streaming loss or recovery. ADB authorization, missing headset Wi-Fi, and
+USB-health blocks remain visible with operator action. An unchanged wait for
+an absent headset is announced once; routine setup steps are DEBUG messages.
+Progress uses the ``isaaccapture.cloudxr.oob_teleop_env.progress`` logger.
+It remains visible through filters selecting its parent logger, while embedded
+applications can also select progress alone.
+
 To start the hub **without** any ``adb`` interaction — useful in containers,
 CI, or wireless-only environments — set ``TELEOP_OOB_HUB_ONLY=1`` and open
 the teleop URL on the headset manually. This mode supports WiFi setup only

src/python/isaaccapture/cloudxr/oob_teleop_adb.py

@@ -373,7 +373,7 @@ def assert_headset_awake(*, timeout: float = 15.0, require_awake: bool = False)
     except (FileNotFoundError, subprocess.TimeoutExpired):
         pass
 
-    log.warning(
+    log.debug(
         "Headset appears asleep (wakefulness=%s). Put it on or cover the "
         "proximity sensor; waiting up to %.0fs for it to wake.",
         wake or "?",
@@ -2036,14 +2036,15 @@ def _is_candidate_tab(tab: dict) -> bool:
 
         if not am_start_retried and time.monotonic() >= retry_at:
             am_start_retried = True
-            log.warning(
+            log.debug(
                 "CDP: tab not found after %.1fs — re-firing am start (cold-launch race)",
                 timeout / 2,
             )
             oob_progress(
                 "setup-oob",
                 "tab not found yet — re-firing am start (browser may have "
                 "swallowed the first intent on cold launch) ...",
+                level=logging.DEBUG,
             )
             try:
                 rc, diag = await asyncio.to_thread(
@@ -2069,6 +2070,7 @@ def _is_candidate_tab(tab: dict) -> bool:
         "setup-oob",
         "teleop tab found — accepting cert, waiting for CONNECT button, "
         "then auto-clicking it ...",
+        level=logging.DEBUG,
     )
 
     # cert interstitial + bring to front + readiness + click
@@ -2146,6 +2148,7 @@ async def run_oob_connect(
         oob_progress(
             "setup-oob",
             f"closed {closed} stale teleop tab(s) from a prior session",
+            level=logging.DEBUG,
         )
         # Brief pause so the browser actually releases WebXR / media
         # resources before the new page tries to acquire them.
@@ -2168,6 +2171,7 @@ async def run_oob_connect(
     oob_progress(
         "setup-oob",
         "headset browser launched — discovering DevTools socket ...",
+        level=logging.DEBUG,
     )
 
     # --- Step 2: wait for DevTools socket ------------------------------------

src/python/isaaccapture/cloudxr/oob_teleop_env.py

@@ -22,6 +22,7 @@
 from .oob_teleop_hub import OOB_WS_PATH
 
 log = logging.getLogger("isaaccapture.cloudxr.oob_teleop_env")
+progress_log = logging.getLogger("isaaccapture.cloudxr.oob_teleop_env.progress")
 
 WSS_PROXY_DEFAULT_PORT = 48322
 
@@ -565,15 +566,14 @@ def resolve_lan_host_for_oob() -> str:
     return h
 
 
-def oob_progress(stage: str, msg: str) -> None:
-    """One-line progress update for ``--setup-oob`` / ``--usb-local`` steps.
+def oob_progress(stage: str, msg: str, *, level: int = logging.INFO) -> None:
+    """Log OOB progress on its own filterable logger at the requested level.
 
-    Logged at INFO as ``[<stage>] <msg>``; printed to stderr instead when
-    ``ISAACCAPTURE_LOGGING=off``, where no handler of ours would show it.
+    With logging off, retain operator messages on stderr but omit DEBUG detail.
     """
     if logging_enabled():
-        log.info("[%s] %s", stage, msg)
-    else:
+        progress_log.log(level, "[%s] %s", stage, msg)
+    elif level >= logging.INFO:
         print(f"\033[36m[{stage}]\033[0m {msg}", file=sys.stderr, flush=True)
 
 
@@ -817,7 +817,9 @@ def ss_listeners_on_port(port: int) -> list[str]:
     return out
 
 
-def print_host_preflight_warnings(*, usb_local: bool) -> None:
+def print_host_preflight_warnings(
+    *, usb_local: bool, emit_console: bool = True
+) -> None:
     """Best-effort host preflight (port conflicts + ufw).
 
     In ``--usb-local`` mode this is fail-fast: a port conflict on any of
@@ -830,6 +832,8 @@ def print_host_preflight_warnings(*, usb_local: bool) -> None:
     ufw findings are always warn-only (best-effort: ``status`` parsing
     can yield false positives on permissive rulesets), and ufw is only
     checked in WiFi mode (USB-local is loopback, not firewalled).
+    Shared service callers use ``emit_console=False`` to avoid duplicating
+    logger warnings in embedded operator terminals.
 
     The WSS proxy binds the wildcard address (``host=""`` in
     :mod:`websockets`, i.e. ``0.0.0.0``), but we probe via loopback
@@ -860,19 +864,21 @@ def print_host_preflight_warnings(*, usb_local: bool) -> None:
                 "then retry."
             )
         log.warning("preflight: port(s) already in use: %s", busy)
-        print(
-            f"\n\033[33m[preflight] port(s) {busy} already in use; kill the "
-            f"holder (`ss -tulpn | grep -E '{ports_re}'`) or override via "
-            "PROXY_PORT.\033[0m\n"
-        )
+        if emit_console:
+            print(
+                f"\n\033[33m[preflight] port(s) {busy} already in use; kill the "
+                f"holder (`ss -tulpn | grep -E '{ports_re}'`) or override via "
+                "PROXY_PORT.\033[0m\n"
+            )
     # ufw is only meaningful in WiFi mode (USB-local is loopback, not firewalled).
     if not usb_local:
         unallowed = _ufw_unallowed_ports([wss_proxy_port()])
         if unallowed:
             cmd = "; ".join(f"sudo ufw allow {p}/tcp" for p in unallowed)
             log.warning("preflight: ufw blocks port(s) %s", unallowed)
-            print(
-                f"\n\033[33m[preflight] ufw is active and may block port(s) "
-                f"{unallowed} from reaching the headset. Allow with: {cmd}"
-                "\033[0m\n"
-            )
+            if emit_console:
+                print(
+                    f"\n\033[33m[preflight] ufw is active and may block port(s) "
+                    f"{unallowed} from reaching the headset. Allow with: {cmd}"
+                    "\033[0m\n"
+                )

src/python/isaaccapture/cloudxr/oob_teleop_lifecycle.py

@@ -588,6 +588,7 @@ async def _close_teleop_tab(self) -> None:
             oob_progress(
                 "usb-local" if self.usb_local else "setup-oob",
                 f"closed {closed} teleop tab(s) on the headset; session ended",
+                level=logging.DEBUG,
             )
 
     async def _shielded_cleanup(self) -> None:

src/python/isaaccapture/cloudxr/oob_teleop_progress.py

@@ -0,0 +1,151 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Sparse operator progress derived from OOB lifecycle snapshots."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class OobProgressEvent:
+    level: int
+    message: str
+
+
+class OobProgressReporter:
+    """Describe setup transitions for foreground and embedded service owners."""
+
+    def __init__(self, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
+        self._adb_ready = False
+        self._ever_adb_ready = False
+        self._last_stage: tuple | None = None
+        self._last_health: str | None = None
+        self._last_wait: tuple | None = None
+        self._last_delay_at: dict[str, float] = {}
+
+    def observe(self, snapshot: dict) -> list[OobProgressEvent]:
+        """Return leveled progress on meaningful state changes."""
+        if snapshot.get("health") == "starting":
+            return []
+
+        state = snapshot.get("state")
+        health = snapshot.get("health")
+        reason = snapshot.get("reason") or "unknown reason"
+        serial = snapshot.get("selectedSerial")
+        ready = bool(snapshot.get("adbReady"))
+        stage = (
+            state,
+            reason,
+            snapshot.get("episodeStartedAt"),
+            snapshot.get("generation"),
+        )
+        entered = stage != self._last_stage
+        state_changed = self._last_stage is None or state != self._last_stage[0]
+        now = self._clock()
+        messages: list[OobProgressEvent] = []
+
+        def emit(level: int, message: str) -> None:
+            messages.append(OobProgressEvent(level, message))
+
+        if ready and not self._adb_ready:
+            verb = "reconnected" if self._ever_adb_ready else "detected"
+            emit(
+                logging.INFO,
+                f"USB-attached HMD {verb} (serial {serial}); continuing OOB setup.",
+            )
+            self._ever_adb_ready = True
+        self._adb_ready = ready
+
+        if state == "WAITING_FOR_ADB" and not ready:
+            diagnostic = snapshot.get("adbDiagnostic")
+            lower_reason = reason.lower()
+            # ADB authorization needs operator action even when raw diagnostics exist.
+            if "unauthorized" in lower_reason:
+                wait = ("unauthorized", serial)
+                level = logging.WARNING
+                message = (
+                    "ADB authorization required: unlock the headset and accept "
+                    "the USB debugging prompt."
+                )
+            elif "offline" in lower_reason:
+                wait = ("offline", serial)
+                level = logging.INFO
+                message = f"Waiting for USB-attached HMD: {reason}"
+            elif "multiple" in lower_reason:
+                wait = ("multiple", serial)
+                level = logging.WARNING
+                message = f"Waiting for USB-attached HMD: {reason}"
+            elif diagnostic:
+                wait = ("adb_diagnostic", diagnostic)
+                level = logging.WARNING
+                message = f"ADB diagnostic: {diagnostic}"
+            elif serial is None:
+                wait = ("no_headset",)
+                level = logging.INFO
+                message = "No USB-attached HMD detected; connect a headset to continue."
+            else:
+                wait = ("selected_missing", serial)
+                level = logging.INFO
+                message = f"Waiting for USB-attached HMD: {reason}"
+            if wait != self._last_wait:
+                emit(level, message)
+            self._last_wait = wait
+        else:
+            self._last_wait = None
+
+        if entered:
+            if state == "PREPARING_DEVICE":
+                emit(
+                    logging.DEBUG,
+                    f"Waiting for headset transport: {reason}"
+                    if snapshot.get("networkPresent") is False
+                    else f"Preparing headset {serial} for OOB setup.",
+                )
+            elif state == "REBUILDING_USB":
+                emit(logging.DEBUG, "Configuring USB reverse rules and TURN.")
+            elif state == "AUTOMATING_BROWSER":
+                emit(
+                    logging.DEBUG,
+                    "USB reverse rules and TURN verified; opening headset browser."
+                    if reason == "TURN and reverse rules verified"
+                    else "Opening headset browser and connecting OOB client.",
+                )
+            elif state == "VERIFYING_EXISTING_BROWSER":
+                emit(
+                    logging.DEBUG, "USB transport restored; checking existing browser."
+                )
+            elif state == "VERIFYING_BROWSER":
+                emit(logging.DEBUG, "Waiting for headset browser health report.")
+            elif state == "WAITING_FOR_AWAKE" and state_changed:
+                emit(logging.INFO, f"Waiting for selected headset to wake: {reason}")
+            elif state == "WAITING_FOR_NETWORK" and state_changed:
+                emit(
+                    logging.WARNING,
+                    "Headset network unavailable; connect it to Wi-Fi to continue.",
+                )
+            elif state == "USB_HEALTH_BLOCKED" and state_changed:
+                emit(
+                    logging.WARNING,
+                    f"USB health policy blocked browser launch: {reason}",
+                )
+            elif state == "DEGRADED" or "Recovery episode expired" in reason:
+                if now - self._last_delay_at.get(reason, float("-inf")) >= 30:
+                    emit(logging.WARNING, f"OOB recovery delayed: {reason}")
+                    self._last_delay_at[reason] = now
+
+        if health == "browser_ready" and health != self._last_health:
+            emit(
+                logging.INFO,
+                "OOB browser ready; waiting for fresh stream metrics."
+                if snapshot.get("streaming")
+                else "OOB browser ready; waiting for OpenXR stream.",
+            )
+        self._last_stage = stage
+        self._last_health = health
+        return messages