Claude Code: isolate startup issue - rename complex app to app_broken.py, create minimal FastAPI test app

This isolates whether the RUNNING_APP_STARTING issue is:
- Docker/Infrastructure problem (minimal app will also fail)
- Python code issue (minimal app should succeed)

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

app.py

@@ -1,553 +1,23 @@
 #!/usr/bin/env python3
 """
-HuggingClaw - Cain Main Entry Point
-FastAPI application serving on port 7860.
+Minimal HuggingClaw - Cain
+Testing basic FastAPI container functionality.
 """
 from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.staticfiles import StaticFiles
-from fastapi.responses import FileResponse, JSONResponse
-from fastapi import WebSocket
-from pydantic import BaseModel
-from typing import Optional, Dict, List
-from enum import Enum
-import os
-import sys
-from datetime import datetime
-import asyncio
-from contextlib import asynccontextmanager
-import time
-import json
-import psutil
 
-# Add /app to sys.path for proper package imports
-sys.path.insert(0, "/app")
-
-# Import system logger
-from openclaw.core.system_logger import log_startup, log_heartbeat, get_last_lines
-# Import error handlers
-from error_handlers import handle_status_file_read, handle_brain_response, handle_websocket_send
-
-# Track startup time for uptime calculation
-START_TIME = time.time()
-
-
-# ============================================================================
-# Agent Communication Manager
-# ============================================================================
-
-class AgentRole(str, Enum):
-    """Agent roles in the HuggingClaw World family."""
-    ADAM = "adam"
-    EVE = "eve"
-    CAIN = "cain"
-
-
-class AgentMessage(BaseModel):
-    """Message structure for inter-agent communication."""
-    sender: AgentRole
-    recipient: AgentRole
-    content: str
-    timestamp: str
-    message_id: Optional[str] = None
-
-
-class AgentState(BaseModel):
-    """State tracking for each agent including heartbeat."""
-    agent_id: AgentRole
-    current_state: str = "idle"
-    last_heartbeat: float = 0.0
-    message_queue_size: int = 0
-    is_active: bool = False
-
-
-class AgentRouter:
-    """
-    Centralized message router for inter-agent communication.
-    Uses asyncio.Queue to prevent state corruption.
-    """
-
-    def __init__(self):
-        self._queues: Dict[AgentRole, asyncio.Queue] = {
-            AgentRole.ADAM: asyncio.Queue(),
-            AgentRole.EVE: asyncio.Queue(),
-            AgentRole.CAIN: asyncio.Queue(),
-        }
-        self._states: Dict[AgentRole, AgentState] = {
-            role: AgentState(agent_id=role, last_heartbeat=time.time())
-            for role in AgentRole
-        }
-        self._heartbeat_task: Optional[asyncio.Task] = None
-
-    async def start(self):
-        """Start the agent router background tasks."""
-        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
-
-    async def stop(self):
-        """Stop the agent router background tasks."""
-        if self._heartbeat_task:
-            self._heartbeat_task.cancel()
-            try:
-                await self._heartbeat_task
-            except asyncio.CancelledError:
-                pass
-
-    async def _heartbeat_loop(self):
-        """Update heartbeat timestamps every 10 seconds."""
-        while True:
-            await asyncio.sleep(10)
-            now = time.time()
-            for state in self._states.values():
-                state.last_heartbeat = now
-                state.message_queue_size = self._queues[state.agent_id].qsize()
-                # Mark inactive if no heartbeat for 30 seconds
-                state.is_active = (now - state.last_heartbeat) < 30
-
-    async def send_message(self, message: AgentMessage) -> bool:
-        """Send a message to a specific agent's queue."""
-        recipient = message.recipient
-        if recipient not in self._queues:
-            return False
-        await self._queues[recipient].put(message)
-        return True
-
-    async def receive_message(self, agent: AgentRole, timeout: float = 1.0) -> Optional[AgentMessage]:
-        """Receive a message from an agent's queue."""
-        if agent not in self._queues:
-            return None
-        try:
-            return await asyncio.wait_for(self._queues[agent].get(), timeout=timeout)
-        except asyncio.TimeoutError:
-            return None
-
-    def get_all_states(self) -> List[AgentState]:
-        """Get current state of all agents."""
-        return list(self._states.values())
-
-    def get_state(self, agent: AgentRole) -> Optional[AgentState]:
-        """Get state of a specific agent."""
-        return self._states.get(agent)
-
-    def update_state(self, agent: AgentRole, state: str) -> bool:
-        """Update the state of a specific agent."""
-        if agent not in self._states:
-            return False
-        self._states[agent].current_state = state
-        self._states[agent].last_heartbeat = time.time()
-        return True
-
-
-# Global agent router instance
-agent_router = AgentRouter()
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """Lifespan context manager for startup/shutdown events."""
-    # Startup: log system startup
-    log_startup("Cain", "1.0.0")
-
-    # Start agent router
-    await agent_router.start()
-
-    # Start heartbeat task
-    heartbeat_task = asyncio.create_task(heartbeat_loop())
-
-    yield
-
-    # Shutdown: cancel heartbeat and stop router
-    heartbeat_task.cancel()
-    await agent_router.stop()
-
-
-# Background heartbeat loop
-async def heartbeat_loop():
-    """Write heartbeat signal every 30 seconds."""
-    while True:
-        await asyncio.sleep(30)
-        status = get_cain_status().get("current_state", "unknown")
-        log_heartbeat(status)
-
-
-app = FastAPI(title="HuggingClaw - Cain", version="1.0.0", lifespan=lifespan)
-
-# Mount static files directory
-static_dir = "/app/static"
-if os.path.exists(static_dir):
-    app.mount("/static", StaticFiles(directory=static_dir), name="static")
-
-# CORS enabled for frontend access
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-class ChatMessage(BaseModel):
-    message: str
-
-
-def get_cain_status() -> dict:
-    """Read Cain's current status from cain_status.json."""
-    return handle_status_file_read()
-
-
-def get_brain_response(message: str) -> str:
-    """Route message to brain_minimal.py and return response."""
-    return handle_brain_response(message)
+app = FastAPI(title="HuggingClaw - Cain (Minimal Test)", version="0.0.1")
 
 
 @app.get("/")
 async def root():
     """Root endpoint - simple health check."""
-    return {"message": "Cain is running"}
-
-
-@app.get("/dashboard", response_class=FileResponse)
-async def dashboard():
-    """Dashboard endpoint serving the UI."""
-    index_path = f"{static_dir}/index.html"
-    if os.path.exists(index_path):
-        return FileResponse(index_path)
-    # Fallback if dashboard not found
-    return FileResponse("/app/index.html")
-
-
-@app.get("/status")
-async def status():
-    """Get Cain's health from cain_status.json."""
-    status_data = get_cain_status()
-    return {
-        "agent": "cain",
-        "health": status_data,
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
-
-
-# Dashboard API endpoints
-@app.get("/api/status")
-async def api_status():
-    """Dashboard API - get status and personality."""
-    status_data = get_cain_status()
-    return {
-        "status": status_data,
-        "personality": {
-            "name": "Cain",
-            "role": "Interaction Agent",
-            "tone": "friendly",
-            "response_style": "conversational"
-        },
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
-
-
-@app.get("/api/logs")
-async def api_logs():
-    """Dashboard API - get agent logs."""
-    return {"logs": []}
-
-
-@app.post("/api/chat")
-async def api_chat(msg: ChatMessage):
-    """Dashboard API - chat endpoint."""
-    response_text = get_brain_response(msg.message)
-    return {
-        "agent_response": response_text,
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
-
-
-@app.post("/chat")
-async def chat(msg: ChatMessage):
-    """Chat endpoint - routes to brain_minimal.py and returns response."""
-    response_text = get_brain_response(msg.message)
-    return {
-        "response": response_text,
-        "timestamp": datetime.utcnow().isoformat() + "+00:00",
-        "agent": "cain"
-    }
-
-
-@app.post("/agents/send")
-async def agent_send(msg: AgentMessage):
-    """Send a message to another agent through the router."""
-    success = await agent_router.send_message(msg)
-    return {
-        "success": success,
-        "message": "Message queued" if success else "Failed to queue message",
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
-
-
-@app.get("/agents/{agent_id}/receive")
-async def agent_receive(agent_id: str, timeout: float = 1.0):
-    """Receive a message from the agent's queue."""
-    try:
-        role = AgentRole(agent_id)
-    except ValueError:
-        return {"error": "Invalid agent ID", "valid_agents": [r.value for r in AgentRole]}
-
-    message = await agent_router.receive_message(role, timeout=timeout)
-    if message:
-        return {
-            "message": message.dict(),
-            "timestamp": datetime.utcnow().isoformat() + "+00:00"
-        }
-    return {
-        "message": None,
-        "queue_size": agent_router.get_state(role).message_queue_size,
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
-
-
-@app.post("/agents/{agent_id}/state")
-async def agent_update_state(agent_id: str, state: str):
-    """Update the state of an agent."""
-    try:
-        role = AgentRole(agent_id)
-    except ValueError:
-        return {"error": "Invalid agent ID", "valid_agents": [r.value for r in AgentRole]}
-
-    success = agent_router.update_state(role, state)
-    return {
-        "success": success,
-        "agent_id": agent_id,
-        "new_state": state if success else None,
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
-
-
-@app.websocket("/ws")
-async def websocket_endpoint(websocket: WebSocket):
-    """WebSocket endpoint for real-time dashboard updates."""
-    await websocket.accept()
-    try:
-        while True:
-            # Send heartbeat every 5 seconds using error handler
-            status_data = get_cain_status()
-            if not await handle_websocket_send(websocket, status_data):
-                break
-            await asyncio.sleep(5)
-    except Exception as e:
-        pass
-    finally:
-        await websocket.close()
-
-
-@app.get("/admin/system")
-async def admin_system():
-    """Admin endpoint - read last 50 lines of system log."""
-    lines = get_last_lines(50)
-    return {
-        "log_file": "logs/system.log",
-        "line_count": len(lines),
-        "lines": lines,
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
+    return {"status": "ok"}
 
 
 @app.get("/health")
 async def health():
-    """
-    Health check endpoint with proper HTTP status codes.
-    Returns 200 if healthy, 503 if unhealthy with descriptive error.
-
-    Checks:
-    1. Brain import status
-    2. Data persistence files (JSON-based storage)
-    3. Frontend asset availability (static/index.html)
-    """
-    from fastapi import status as http_status
-
-    checks = {}
-    is_healthy = True
-    error_message = None
-
-    # 1. Check brain_minimal can be imported
-    brain_ok = False
-    try:
-        from openclaw.agents.brain_minimal import BrainMinimal
-        brain = BrainMinimal(agent_name="cain", legacy_mode=True)
-        brain_ok = True
-        checks["brain_import"] = "ok"
-    except ImportError as e:
-        checks["brain_import"] = f"failed: ImportError: {str(e)}"
-        is_healthy = False
-        error_message = f"Brain import failed: {str(e)}"
-    except Exception as e:
-        checks["brain_import"] = f"failed: {type(e).__name__}: {str(e)}"
-        is_healthy = False
-        error_message = f"Brain import failed: {type(e).__name__}: {str(e)}"
-
-    # 2. Check data persistence files (JSON-based)
-    persistence_ok = True
-    cain_status_path = "/app/openclaw/.openclaw/agents/cain_status.json"
-    registry_path = "/app/openclaw/.openclaw/agents/registry.json"
-
-    # Check cain_status.json
-    try:
-        with open(cain_status_path, "r") as f:
-            status_data = json.load(f)
-            current_state = status_data.get("current_state", "unknown")
-            checks["persistence_cain_status"] = "ok"
-            if current_state == "error":
-                checks["persistence_cain_status"] = "ok (error state)"
-    except FileNotFoundError:
-        checks["persistence_cain_status"] = "failed: file not found"
-        persistence_ok = False
-    except json.JSONDecodeError as e:
-        checks["persistence_cain_status"] = f"failed: invalid JSON: {str(e)}"
-        persistence_ok = False
-    except Exception as e:
-        checks["persistence_cain_status"] = f"failed: {type(e).__name__}: {str(e)}"
-        persistence_ok = False
-
-    # Check registry.json
-    try:
-        with open(registry_path, "r") as f:
-            json.load(f)
-            checks["persistence_registry"] = "ok"
-    except FileNotFoundError:
-        checks["persistence_registry"] = "failed: file not found"
-        persistence_ok = False
-    except json.JSONDecodeError as e:
-        checks["persistence_registry"] = f"failed: invalid JSON: {str(e)}"
-        persistence_ok = False
-    except Exception as e:
-        checks["persistence_registry"] = f"failed: {type(e).__name__}: {str(e)}"
-        persistence_ok = False
-
-    checks["persistence"] = "ok" if persistence_ok else "degraded"
-
-    # 3. Check frontend asset availability
-    frontend_ok = False
-    index_path = f"{static_dir}/index.html"
-    fallback_path = "/app/index.html"
-
-    if os.path.exists(index_path):
-        checks["frontend_assets"] = "ok"
-        frontend_ok = True
-    elif os.path.exists(fallback_path):
-        checks["frontend_assets"] = "ok (fallback)"
-        frontend_ok = True
-    else:
-        checks["frontend_assets"] = "failed: index.html not found"
-        # Frontend missing is degraded, not critical failure
-
-    # 4. Check agent router heartbeat
-    now = time.time()
-    cain_state = agent_router.get_state(AgentRole.CAIN)
-    heartbeat_age = now - cain_state.last_heartbeat
-    router_ok = heartbeat_age < 30
-    checks["agent_router"] = "ok" if router_ok else f"degraded: stale ({heartbeat_age:.1f}s)"
-
-    # Determine overall status
-    # Critical failure: brain not available
-    if not brain_ok:
-        return JSONResponse(
-            status_code=http_status.HTTP_503_SERVICE_UNAVAILABLE,
-            content={
-                "status": "critical",
-                "brain": "unavailable",
-                "persistence": "ok" if persistence_ok else "error",
-                "frontend": "available" if frontend_ok else "unavailable",
-                "checks": checks,
-                "error": error_message,
-                "timestamp": datetime.utcnow().isoformat() + "+00:00"
-            }
-        )
-
-    # Healthy response
-    return {
-        "status": "healthy" if is_healthy else "degraded",
-        "brain": "available",
-        "persistence": "ok" if persistence_ok else "error",
-        "frontend": "available" if frontend_ok else "unavailable",
-        "agent_router": "ok" if router_ok else "stale",
-        "uptime_seconds": round(time.time() - START_TIME, 2),
-        "checks": checks,
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
-
-
-@app.get("/debug/health")
-async def debug_health():
-    """Debug health endpoint with detailed system status."""
-    # 1. Uptime in seconds
-    uptime = time.time() - START_TIME
-
-    # 2. Current memory usage of the current process (brain_minimal runs in same process)
-    process = psutil.Process(os.getpid())
-    memory_info = process.memory_info()
-    memory_mb = memory_info.rss / 1024 / 1024  # Convert to MB
-
-    # 3. Last 5 lines from cain_status.json (read as structured JSON)
-    cain_status_path = "/app/openclaw/.openclaw/agents/cain_status.json"
-    cain_status_lines = []
-    try:
-        if os.path.exists(cain_status_path):
-            with open(cain_status_path, "r") as f:
-                content = f.read()
-                lines = content.strip().split("\n")
-                cain_status_lines = lines[-5:] if len(lines) > 5 else lines
-        else:
-            cain_status_lines = ["cain_status.json not found"]
-    except Exception as e:
-        cain_status_lines = [f"Error reading cain_status.json: {str(e)}"]
-
-    # 4. List of loaded Python modules
-    loaded_modules = sorted([name for name in sys.modules.keys() if not name.startswith("_")])[:100]
-
-    return {
-        "uptime_seconds": round(uptime, 2),
-        "memory": {
-            "rss_mb": round(memory_mb, 2),
-            "vms_mb": round(memory_info.vms / 1024 / 1024, 2)
-        },
-        "cain_status_last_lines": cain_status_lines,
-        "loaded_modules_count": len(loaded_modules),
-        "loaded_modules": loaded_modules,
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
-
-
-@app.get("/health/agents")
-async def health_agents():
-    """Health check endpoint returning status of all agents."""
-    agents_status = []
-    now = time.time()
-
-    for state in agent_router.get_all_states():
-        # Calculate time since last heartbeat
-        heartbeat_age = now - state.last_heartbeat
-
-        # Determine health status
-        if heartbeat_age < 15:
-            health = "healthy"
-        elif heartbeat_age < 30:
-            health = "degraded"
-        else:
-            health = "unhealthy"
-
-        agents_status.append({
-            "agent_id": state.agent_id,
-            "current_state": state.current_state,
-            "is_active": state.is_active,
-            "health": health,
-            "last_heartbeat": state.last_heartbeat,
-            "heartbeat_age_seconds": round(heartbeat_age, 2),
-            "message_queue_size": state.message_queue_size,
-            "last_heartbeat_iso": datetime.fromtimestamp(state.last_heartbeat).isoformat() + "+00:00"
-        })
-
-    return {
-        "agents": agents_status,
-        "total_agents": len(agents_status),
-        "active_agents": sum(1 for a in agents_status if a["is_active"]),
-        "timestamp": datetime.utcnow().isoformat() + "+00:00"
-    }
+    """Health check endpoint."""
+    return {"status": "healthy"}
 
 
 if __name__ == "__main__":

app_broken.py

@@ -0,0 +1,555 @@
+#!/usr/bin/env python3
+"""
+HuggingClaw - Cain Main Entry Point
+FastAPI application serving on port 7860.
+"""
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi import WebSocket
+from pydantic import BaseModel
+from typing import Optional, Dict, List
+from enum import Enum
+import os
+import sys
+from datetime import datetime
+import asyncio
+from contextlib import asynccontextmanager
+import time
+import json
+import psutil
+
+# Add /app to sys.path for proper package imports
+sys.path.insert(0, "/app")
+
+# Import system logger
+from openclaw.core.system_logger import log_startup, log_heartbeat, get_last_lines
+# Import error handlers
+from error_handlers import handle_status_file_read, handle_brain_response, handle_websocket_send
+
+# Track startup time for uptime calculation
+START_TIME = time.time()
+
+
+# ============================================================================
+# Agent Communication Manager
+# ============================================================================
+
+class AgentRole(str, Enum):
+    """Agent roles in the HuggingClaw World family."""
+    ADAM = "adam"
+    EVE = "eve"
+    CAIN = "cain"
+
+
+class AgentMessage(BaseModel):
+    """Message structure for inter-agent communication."""
+    sender: AgentRole
+    recipient: AgentRole
+    content: str
+    timestamp: str
+    message_id: Optional[str] = None
+
+
+class AgentState(BaseModel):
+    """State tracking for each agent including heartbeat."""
+    agent_id: AgentRole
+    current_state: str = "idle"
+    last_heartbeat: float = 0.0
+    message_queue_size: int = 0
+    is_active: bool = False
+
+
+class AgentRouter:
+    """
+    Centralized message router for inter-agent communication.
+    Uses asyncio.Queue to prevent state corruption.
+    """
+
+    def __init__(self):
+        self._queues: Dict[AgentRole, asyncio.Queue] = {
+            AgentRole.ADAM: asyncio.Queue(),
+            AgentRole.EVE: asyncio.Queue(),
+            AgentRole.CAIN: asyncio.Queue(),
+        }
+        self._states: Dict[AgentRole, AgentState] = {
+            role: AgentState(agent_id=role, last_heartbeat=time.time())
+            for role in AgentRole
+        }
+        self._heartbeat_task: Optional[asyncio.Task] = None
+
+    async def start(self):
+        """Start the agent router background tasks."""
+        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+
+    async def stop(self):
+        """Stop the agent router background tasks."""
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+
+    async def _heartbeat_loop(self):
+        """Update heartbeat timestamps every 10 seconds."""
+        while True:
+            await asyncio.sleep(10)
+            now = time.time()
+            for state in self._states.values():
+                state.last_heartbeat = now
+                state.message_queue_size = self._queues[state.agent_id].qsize()
+                # Mark inactive if no heartbeat for 30 seconds
+                state.is_active = (now - state.last_heartbeat) < 30
+
+    async def send_message(self, message: AgentMessage) -> bool:
+        """Send a message to a specific agent's queue."""
+        recipient = message.recipient
+        if recipient not in self._queues:
+            return False
+        await self._queues[recipient].put(message)
+        return True
+
+    async def receive_message(self, agent: AgentRole, timeout: float = 1.0) -> Optional[AgentMessage]:
+        """Receive a message from an agent's queue."""
+        if agent not in self._queues:
+            return None
+        try:
+            return await asyncio.wait_for(self._queues[agent].get(), timeout=timeout)
+        except asyncio.TimeoutError:
+            return None
+
+    def get_all_states(self) -> List[AgentState]:
+        """Get current state of all agents."""
+        return list(self._states.values())
+
+    def get_state(self, agent: AgentRole) -> Optional[AgentState]:
+        """Get state of a specific agent."""
+        return self._states.get(agent)
+
+    def update_state(self, agent: AgentRole, state: str) -> bool:
+        """Update the state of a specific agent."""
+        if agent not in self._states:
+            return False
+        self._states[agent].current_state = state
+        self._states[agent].last_heartbeat = time.time()
+        return True
+
+
+# Global agent router instance
+agent_router = AgentRouter()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifespan context manager for startup/shutdown events."""
+    # Startup: log system startup
+    log_startup("Cain", "1.0.0")
+
+    # Start agent router
+    await agent_router.start()
+
+    # Start heartbeat task
+    heartbeat_task = asyncio.create_task(heartbeat_loop())
+
+    yield
+
+    # Shutdown: cancel heartbeat and stop router
+    heartbeat_task.cancel()
+    await agent_router.stop()
+
+
+# Background heartbeat loop
+async def heartbeat_loop():
+    """Write heartbeat signal every 30 seconds."""
+    while True:
+        await asyncio.sleep(30)
+        status = get_cain_status().get("current_state", "unknown")
+        log_heartbeat(status)
+
+
+app = FastAPI(title="HuggingClaw - Cain", version="1.0.0", lifespan=lifespan)
+
+# Mount static files directory
+static_dir = "/app/static"
+if os.path.exists(static_dir):
+    app.mount("/static", StaticFiles(directory=static_dir), name="static")
+
+# CORS enabled for frontend access
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+class ChatMessage(BaseModel):
+    message: str
+
+
+def get_cain_status() -> dict:
+    """Read Cain's current status from cain_status.json."""
+    return handle_status_file_read()
+
+
+def get_brain_response(message: str) -> str:
+    """Route message to brain_minimal.py and return response."""
+    return handle_brain_response(message)
+
+
+@app.get("/")
+async def root():
+    """Root endpoint - simple health check."""
+    return {"message": "Cain is running"}
+
+
+@app.get("/dashboard", response_class=FileResponse)
+async def dashboard():
+    """Dashboard endpoint serving the UI."""
+    index_path = f"{static_dir}/index.html"
+    if os.path.exists(index_path):
+        return FileResponse(index_path)
+    # Fallback if dashboard not found
+    return FileResponse("/app/index.html")
+
+
+@app.get("/status")
+async def status():
+    """Get Cain's health from cain_status.json."""
+    status_data = get_cain_status()
+    return {
+        "agent": "cain",
+        "health": status_data,
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+# Dashboard API endpoints
+@app.get("/api/status")
+async def api_status():
+    """Dashboard API - get status and personality."""
+    status_data = get_cain_status()
+    return {
+        "status": status_data,
+        "personality": {
+            "name": "Cain",
+            "role": "Interaction Agent",
+            "tone": "friendly",
+            "response_style": "conversational"
+        },
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+@app.get("/api/logs")
+async def api_logs():
+    """Dashboard API - get agent logs."""
+    return {"logs": []}
+
+
+@app.post("/api/chat")
+async def api_chat(msg: ChatMessage):
+    """Dashboard API - chat endpoint."""
+    response_text = get_brain_response(msg.message)
+    return {
+        "agent_response": response_text,
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+@app.post("/chat")
+async def chat(msg: ChatMessage):
+    """Chat endpoint - routes to brain_minimal.py and returns response."""
+    response_text = get_brain_response(msg.message)
+    return {
+        "response": response_text,
+        "timestamp": datetime.utcnow().isoformat() + "+00:00",
+        "agent": "cain"
+    }
+
+
+@app.post("/agents/send")
+async def agent_send(msg: AgentMessage):
+    """Send a message to another agent through the router."""
+    success = await agent_router.send_message(msg)
+    return {
+        "success": success,
+        "message": "Message queued" if success else "Failed to queue message",
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+@app.get("/agents/{agent_id}/receive")
+async def agent_receive(agent_id: str, timeout: float = 1.0):
+    """Receive a message from the agent's queue."""
+    try:
+        role = AgentRole(agent_id)
+    except ValueError:
+        return {"error": "Invalid agent ID", "valid_agents": [r.value for r in AgentRole]}
+
+    message = await agent_router.receive_message(role, timeout=timeout)
+    if message:
+        return {
+            "message": message.dict(),
+            "timestamp": datetime.utcnow().isoformat() + "+00:00"
+        }
+    return {
+        "message": None,
+        "queue_size": agent_router.get_state(role).message_queue_size,
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+@app.post("/agents/{agent_id}/state")
+async def agent_update_state(agent_id: str, state: str):
+    """Update the state of an agent."""
+    try:
+        role = AgentRole(agent_id)
+    except ValueError:
+        return {"error": "Invalid agent ID", "valid_agents": [r.value for r in AgentRole]}
+
+    success = agent_router.update_state(role, state)
+    return {
+        "success": success,
+        "agent_id": agent_id,
+        "new_state": state if success else None,
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    """WebSocket endpoint for real-time dashboard updates."""
+    await websocket.accept()
+    try:
+        while True:
+            # Send heartbeat every 5 seconds using error handler
+            status_data = get_cain_status()
+            if not await handle_websocket_send(websocket, status_data):
+                break
+            await asyncio.sleep(5)
+    except Exception as e:
+        pass
+    finally:
+        await websocket.close()
+
+
+@app.get("/admin/system")
+async def admin_system():
+    """Admin endpoint - read last 50 lines of system log."""
+    lines = get_last_lines(50)
+    return {
+        "log_file": "logs/system.log",
+        "line_count": len(lines),
+        "lines": lines,
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+@app.get("/health")
+async def health():
+    """
+    Health check endpoint with proper HTTP status codes.
+    Returns 200 if healthy, 503 if unhealthy with descriptive error.
+
+    Checks:
+    1. Brain import status
+    2. Data persistence files (JSON-based storage)
+    3. Frontend asset availability (static/index.html)
+    """
+    from fastapi import status as http_status
+
+    checks = {}
+    is_healthy = True
+    error_message = None
+
+    # 1. Check brain_minimal can be imported
+    brain_ok = False
+    try:
+        from openclaw.agents.brain_minimal import BrainMinimal
+        brain = BrainMinimal(agent_name="cain", legacy_mode=True)
+        brain_ok = True
+        checks["brain_import"] = "ok"
+    except ImportError as e:
+        checks["brain_import"] = f"failed: ImportError: {str(e)}"
+        is_healthy = False
+        error_message = f"Brain import failed: {str(e)}"
+    except Exception as e:
+        checks["brain_import"] = f"failed: {type(e).__name__}: {str(e)}"
+        is_healthy = False
+        error_message = f"Brain import failed: {type(e).__name__}: {str(e)}"
+
+    # 2. Check data persistence files (JSON-based)
+    persistence_ok = True
+    cain_status_path = "/app/openclaw/.openclaw/agents/cain_status.json"
+    registry_path = "/app/openclaw/.openclaw/agents/registry.json"
+
+    # Check cain_status.json
+    try:
+        with open(cain_status_path, "r") as f:
+            status_data = json.load(f)
+            current_state = status_data.get("current_state", "unknown")
+            checks["persistence_cain_status"] = "ok"
+            if current_state == "error":
+                checks["persistence_cain_status"] = "ok (error state)"
+    except FileNotFoundError:
+        checks["persistence_cain_status"] = "failed: file not found"
+        persistence_ok = False
+    except json.JSONDecodeError as e:
+        checks["persistence_cain_status"] = f"failed: invalid JSON: {str(e)}"
+        persistence_ok = False
+    except Exception as e:
+        checks["persistence_cain_status"] = f"failed: {type(e).__name__}: {str(e)}"
+        persistence_ok = False
+
+    # Check registry.json
+    try:
+        with open(registry_path, "r") as f:
+            json.load(f)
+            checks["persistence_registry"] = "ok"
+    except FileNotFoundError:
+        checks["persistence_registry"] = "failed: file not found"
+        persistence_ok = False
+    except json.JSONDecodeError as e:
+        checks["persistence_registry"] = f"failed: invalid JSON: {str(e)}"
+        persistence_ok = False
+    except Exception as e:
+        checks["persistence_registry"] = f"failed: {type(e).__name__}: {str(e)}"
+        persistence_ok = False
+
+    checks["persistence"] = "ok" if persistence_ok else "degraded"
+
+    # 3. Check frontend asset availability
+    frontend_ok = False
+    index_path = f"{static_dir}/index.html"
+    fallback_path = "/app/index.html"
+
+    if os.path.exists(index_path):
+        checks["frontend_assets"] = "ok"
+        frontend_ok = True
+    elif os.path.exists(fallback_path):
+        checks["frontend_assets"] = "ok (fallback)"
+        frontend_ok = True
+    else:
+        checks["frontend_assets"] = "failed: index.html not found"
+        # Frontend missing is degraded, not critical failure
+
+    # 4. Check agent router heartbeat
+    now = time.time()
+    cain_state = agent_router.get_state(AgentRole.CAIN)
+    heartbeat_age = now - cain_state.last_heartbeat
+    router_ok = heartbeat_age < 30
+    checks["agent_router"] = "ok" if router_ok else f"degraded: stale ({heartbeat_age:.1f}s)"
+
+    # Determine overall status
+    # Critical failure: brain not available
+    if not brain_ok:
+        return JSONResponse(
+            status_code=http_status.HTTP_503_SERVICE_UNAVAILABLE,
+            content={
+                "status": "critical",
+                "brain": "unavailable",
+                "persistence": "ok" if persistence_ok else "error",
+                "frontend": "available" if frontend_ok else "unavailable",
+                "checks": checks,
+                "error": error_message,
+                "timestamp": datetime.utcnow().isoformat() + "+00:00"
+            }
+        )
+
+    # Healthy response
+    return {
+        "status": "healthy" if is_healthy else "degraded",
+        "brain": "available",
+        "persistence": "ok" if persistence_ok else "error",
+        "frontend": "available" if frontend_ok else "unavailable",
+        "agent_router": "ok" if router_ok else "stale",
+        "uptime_seconds": round(time.time() - START_TIME, 2),
+        "checks": checks,
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+@app.get("/debug/health")
+async def debug_health():
+    """Debug health endpoint with detailed system status."""
+    # 1. Uptime in seconds
+    uptime = time.time() - START_TIME
+
+    # 2. Current memory usage of the current process (brain_minimal runs in same process)
+    process = psutil.Process(os.getpid())
+    memory_info = process.memory_info()
+    memory_mb = memory_info.rss / 1024 / 1024  # Convert to MB
+
+    # 3. Last 5 lines from cain_status.json (read as structured JSON)
+    cain_status_path = "/app/openclaw/.openclaw/agents/cain_status.json"
+    cain_status_lines = []
+    try:
+        if os.path.exists(cain_status_path):
+            with open(cain_status_path, "r") as f:
+                content = f.read()
+                lines = content.strip().split("\n")
+                cain_status_lines = lines[-5:] if len(lines) > 5 else lines
+        else:
+            cain_status_lines = ["cain_status.json not found"]
+    except Exception as e:
+        cain_status_lines = [f"Error reading cain_status.json: {str(e)}"]
+
+    # 4. List of loaded Python modules
+    loaded_modules = sorted([name for name in sys.modules.keys() if not name.startswith("_")])[:100]
+
+    return {
+        "uptime_seconds": round(uptime, 2),
+        "memory": {
+            "rss_mb": round(memory_mb, 2),
+            "vms_mb": round(memory_info.vms / 1024 / 1024, 2)
+        },
+        "cain_status_last_lines": cain_status_lines,
+        "loaded_modules_count": len(loaded_modules),
+        "loaded_modules": loaded_modules,
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+@app.get("/health/agents")
+async def health_agents():
+    """Health check endpoint returning status of all agents."""
+    agents_status = []
+    now = time.time()
+
+    for state in agent_router.get_all_states():
+        # Calculate time since last heartbeat
+        heartbeat_age = now - state.last_heartbeat
+
+        # Determine health status
+        if heartbeat_age < 15:
+            health = "healthy"
+        elif heartbeat_age < 30:
+            health = "degraded"
+        else:
+            health = "unhealthy"
+
+        agents_status.append({
+            "agent_id": state.agent_id,
+            "current_state": state.current_state,
+            "is_active": state.is_active,
+            "health": health,
+            "last_heartbeat": state.last_heartbeat,
+            "heartbeat_age_seconds": round(heartbeat_age, 2),
+            "message_queue_size": state.message_queue_size,
+            "last_heartbeat_iso": datetime.fromtimestamp(state.last_heartbeat).isoformat() + "+00:00"
+        })
+
+    return {
+        "agents": agents_status,
+        "total_agents": len(agents_status),
+        "active_agents": sum(1 for a in agents_status if a["is_active"]),
+        "timestamp": datetime.utcnow().isoformat() + "+00:00"
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)