fix: Add timeout wrapper for uvicorn launch and health monitor stage reader

- Add SIGALRM timeout wrapper (30s) to prevent indefinite hanging on port bind failure
- Add websockets>=12.0 to requirements.txt
- Add read_current_stage() function to health_monitor.py for Cain stage detection

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.openclaw/health_monitor.py

@@ -806,6 +806,20 @@ def reset_health_monitor():
         _global_monitor = None
 
 
+def read_current_stage() -> str:
+    """
+    Read Cain's current stage from cain_status.json.
+    Returns a simple status string.
+    """
+    try:
+        status_file = Path.home() / ".openclaw" / "agents" / "cain_status.json"
+        with open(status_file) as f:
+            data = json.load(f)
+        return data.get('stage', data.get('current_state', 'UNKNOWN'))
+    except Exception:
+        return 'UNKNOWN'
+
+
 if __name__ == "__main__":
     # Test the health monitor
     print("=== Health Monitor Test ===\n")

app.py

@@ -2286,6 +2286,22 @@ if __name__ == "__main__":
         }
 
         # Explicit crash log for uvicorn launch failures
+        # Add timeout wrapper to prevent indefinite hanging on port binding failure
+        import signal
+        _server_started = False
+        _launch_timeout = 30  # seconds
+
+        def timeout_handler(signum, frame):
+            if not _server_started:
+                crash_msg = f"[{datetime.utcnow().isoformat()}] FATAL: uvicorn launch timeout after {_launch_timeout}s - likely port bind failure\n"
+                with open(_crash_log_path, "a") as f:
+                    f.write(crash_msg)
+                print(f"[FATAL] Launch timeout - port {server_port} may be in use", file=sys.stderr)
+                sys.exit(1)
+
+        signal.signal(signal.SIGALRM, timeout_handler)
+        signal.alarm(_launch_timeout)
+
         try:
             uvicorn.run(
                 app,
@@ -2294,8 +2310,11 @@ if __name__ == "__main__":
                 log_config=log_config,
                 log_level="debug"
             )
+            _server_started = True
+            signal.alarm(0)  # Cancel timeout
             log_startup("Uvicorn server stopped normally")
         except Exception as launch_error:
+            signal.alarm(0)  # Cancel timeout
             # Write to crash.log immediately
             crash_msg = f"[{datetime.utcnow().isoformat()}] FATAL: uvicorn.run() failed: {launch_error}\n"
             with open(_crash_log_path, "a") as f:

requirements.txt

@@ -4,3 +4,4 @@ uvicorn[standard]>=0.24.0
 requests>=2.31.0
 gradio>=4.0.0
 psutil>=5.9.0
+websockets>=12.0