fix: improve historical worker visibility and recent pagination

backend/app/rcon_historical_worker.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+from datetime import date, datetime
 import json
 import os
 import time
@@ -201,34 +202,52 @@ def run_periodic_rcon_historical_capture(
 ) -> None:
     """Run prospective RCON capture in a local loop."""
     completed_runs = 0
-    print(
-        json.dumps(
-            {
-                "event": "rcon-historical-capture-loop-started",
-                "interval_seconds": interval_seconds,
-                "max_retries": max_retries,
-                "retry_delay_seconds": retry_delay_seconds,
-                "target_scope": target_key or "all-configured-rcon-targets",
-            },
-            indent=2,
-        )
+    startup_targets = _describe_loop_targets(target_key)
+    _emit_worker_event(
+        "rcon-historical-capture-worker-started",
+        interval_seconds=interval_seconds,
+        max_retries=max_retries,
+        retry_delay_seconds=retry_delay_seconds,
+        target_scope=target_key or "all-configured-rcon-targets",
+        target_count=len(startup_targets),
+        targets=startup_targets,
     )
     print("Press Ctrl+C to stop.")
 
     try:
         while max_runs is None or completed_runs < max_runs:
             completed_runs += 1
+            _emit_worker_event(
+                "rcon-historical-capture-cycle-started",
+                run=completed_runs,
+            )
             payload = _run_capture_with_retries(
                 max_retries=max_retries,
                 retry_delay_seconds=retry_delay_seconds,
                 target_key=target_key,
             )
-            print(json.dumps({"run": completed_runs, **payload}, indent=2), flush=True)
+            _emit_worker_event(
+                "rcon-historical-capture-cycle-finished",
+                run=completed_runs,
+                result=payload,
+            )
             if max_runs is not None and completed_runs >= max_runs:
                 break
+            _emit_worker_event(
+                "rcon-historical-capture-sleep-started",
+                run=completed_runs,
+                sleep_seconds=interval_seconds,
+            )
             time.sleep(interval_seconds)
     except KeyboardInterrupt:
         print("\nRCON historical capture loop stopped by user.")
+    except Exception as exc:
+        _emit_worker_event(
+            "rcon-historical-capture-worker-exited-unexpectedly",
+            error_type=type(exc).__name__,
+            message=str(exc),
+        )
+        raise
 
 
 def _run_capture_with_retries(
@@ -248,12 +267,32 @@ def _run_capture_with_retries(
             }
         except Exception as exc:
             if attempt > max_retries:
+                _emit_worker_event(
+                    "rcon-historical-capture-attempt-failed",
+                    attempt=attempt,
+                    max_retries=max_retries,
+                    error_type=type(exc).__name__,
+                    message=str(exc),
+                    retries_exhausted=True,
+                )
                 return {
                     "status": "error",
                     "attempts_used": attempt,
                     "error": str(exc),
                 }
+            _emit_worker_event(
+                "rcon-historical-capture-attempt-failed",
+                attempt=attempt,
+                max_retries=max_retries,
+                error_type=type(exc).__name__,
+                message=str(exc),
+            )
             if retry_delay_seconds > 0:
+                _emit_worker_event(
+                    "rcon-historical-capture-retry-sleep-started",
+                    attempt=attempt,
+                    sleep_seconds=retry_delay_seconds,
+                )
                 time.sleep(retry_delay_seconds)
 
 
@@ -275,6 +314,42 @@ def _select_targets(target_key: str | None) -> list[object]:
     return selected
 
 
+def _describe_loop_targets(target_key: str | None) -> list[dict[str, str]]:
+    """Describe configured worker targets without exposing credentials."""
+    try:
+        targets = _select_targets(target_key)
+    except Exception as exc:  # noqa: BLE001 - startup logging must not hide capture error
+        return [
+            {
+                "status": "unavailable",
+                "error_type": type(exc).__name__,
+                "message": str(exc),
+            }
+        ]
+    return [
+        {
+            "target_key": build_rcon_target_key(target),
+            "external_server_id": str(target.external_server_id or ""),
+            "name": str(target.name or ""),
+        }
+        for target in targets
+    ]
+
+
+def _emit_worker_event(event: str, **fields: object) -> None:
+    """Print one JSON worker event using safe date/time serialization."""
+    print(
+        json.dumps({"event": event, **fields}, indent=2, default=_json_default),
+        flush=True,
+    )
+
+
+def _json_default(value: object) -> str:
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    return str(value)
+
+
 def get_rcon_admin_log_lookback_minutes() -> int:
     """Return the AdminLog lookback window used by periodic RCON capture."""
     configured_value = os.getenv("HLL_BACKEND_RCON_ADMIN_LOG_LOOKBACK_MINUTES", "60")