@agentunion/kite 1.5.0 → 1.6.0

package/extensions/services/watchdog/entry.py

@@ -1,793 +1,1258 @@
-"""
-Watchdog entry point.
-Connects to Kernel via WebSocket JSON-RPC 2.0, registers, subscribes to events,
-runs health monitor loop, handles incoming RPC requests.
-"""
-
-import asyncio
-import builtins
-import json
-import os
-import re
-import sys
-import threading
-import time
-import traceback
-import uuid
-from datetime import datetime, timezone
-
-import websockets
-
-
-# ── Module configuration ──
-
-def _load_module_config() -> dict:
-    """Load module configuration from module.md frontmatter.
-
-    Returns:
-        Dict with keys: name, preferred_port, advertise_ip
-
-    Raises:
-        SystemExit: If module.md is invalid or name is non-compliant
-    """
-    _this_dir = os.path.dirname(os.path.abspath(__file__))
-    module_md = os.path.join(_this_dir, "module.md")
-
-    # Calculate relative path for error messages
-    project_root = os.environ.get("KITE_PROJECT", "")
-    if project_root and _this_dir.startswith(project_root):
-        rel_path = os.path.relpath(_this_dir, project_root)
-    else:
-        rel_path = _this_dir
-
-    # Default values (will be overridden if valid config exists)
-    result = {
-        "name": "",
-        "preferred_port": 0,
-        "advertise_ip": "0.0.0.0"
-    }
-
-    # Check if module.md exists
-    if not os.path.exists(module_md):
-        print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
-        print(f"  Path: {rel_path}/module.md")
-        print(f"  Reason: File not found")
-        sys.exit(1)
-
-    try:
-        with open(module_md, encoding="utf-8") as f:
-            text = f.read()
-
-        # Extract YAML frontmatter (between --- markers)
-        import re
-        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
-        if not m:
-            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
-            print(f"  Path: {rel_path}/module.md")
-            print(f"  Reason: Missing YAML frontmatter")
-            sys.exit(1)
-
-        # Parse YAML frontmatter
-        try:
-            import yaml
-            fm = yaml.safe_load(m.group(1)) or {}
-        except ImportError:
-            print(f"[{rel_path}] ERROR: PyYAML not installed, cannot parse module.md")
-            sys.exit(1)
-        except Exception as e:
-            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
-            print(f"  Path: {rel_path}/module.md")
-            print(f"  Reason: YAML parse error: {e}")
-            sys.exit(1)
-
-        # Validate 'name' field (required)
-        if "name" not in fm:
-            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
-            print(f"  Path: {rel_path}/module.md")
-            print(f"  Reason: Missing 'name' field")
-            sys.exit(1)
-
-        raw_name = str(fm["name"]).strip()
-
-        if not raw_name:
-            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
-            print(f"  Path: {rel_path}/module.md")
-            print(f"  Reason: Empty module name")
-            sys.exit(1)
-
-        # Validate name characters
-        sanitized = re.sub(r'[^a-zA-Z0-9_\-]', '', raw_name)
-
-        if sanitized != raw_name:
-            invalid_chars = ''.join(sorted(set(c for c in raw_name if c not in sanitized)))
-            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
-            print(f"  Path: {rel_path}/module.md")
-            print(f"  Reason: Invalid characters in name '{raw_name}': {repr(invalid_chars)}")
-            sys.exit(1)
-
-        result["name"] = sanitized
-
-        # Extract optional fields
-        if "preferred_port" in fm:
-            try:
-                result["preferred_port"] = int(fm["preferred_port"])
-            except (ValueError, TypeError):
-                pass
-
-        if "advertise_ip" in fm:
-            result["advertise_ip"] = str(fm["advertise_ip"])
-
-    except SystemExit:
-        raise  # Re-raise exit to prevent catching by outer except
-    except Exception as e:
-        print(f"[{rel_path}] ERROR: Failed to read module.md: {e}")
-        sys.exit(1)
-
-    return result
-
-_module_config = _load_module_config()
-MODULE_NAME = _module_config["name"]
-
-
-def _fmt_elapsed(t0: float) -> str:
-    """Format elapsed time since t0: <1s → 'NNNms', >=1s → 'N.Ns', >=10s → 'NNs'."""
-    d = time.monotonic() - t0
-    if d < 1:
-        return f"{d * 1000:.0f}ms"
-    if d < 10:
-        return f"{d:.1f}s"
-    return f"{d:.0f}s"
-
-
-# ── Safe stdout/stderr: ignore BrokenPipeError after Launcher closes stdio ──
-
-class _SafeWriter:
-    """Wraps a stream to silently swallow BrokenPipeError on write/flush."""
-    def __init__(self, stream):
-        self._stream = stream
-
-    def write(self, s):
-        try:
-            self._stream.write(s)
-        except (BrokenPipeError, OSError):
-            pass
-
-    def flush(self):
-        try:
-            self._stream.flush()
-        except (BrokenPipeError, OSError):
-            pass
-
-    def __getattr__(self, name):
-        return getattr(self._stream, name)
-
-sys.stdout = _SafeWriter(sys.stdout)
-sys.stderr = _SafeWriter(sys.stderr)
-
-
-# ── Timestamped print + log file writer ──
-
-_builtin_print = builtins.print
-_start_ts = time.monotonic()
-_last_ts = time.monotonic()
-_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
-_log_lock = threading.Lock()
-_log_latest_path = None
-_log_daily_path = None
-_log_daily_date = ""
-_log_dir = None
-_crash_log_path = None
-
-def _strip_ansi(s: str) -> str:
-    return _ANSI_RE.sub("", s)
-
-def _resolve_daily_log_path():
-    """Resolve daily log path based on current date."""
-    global _log_daily_path, _log_daily_date
-    if not _log_dir:
-        return
-    today = datetime.now().strftime("%Y-%m-%d")
-    if today == _log_daily_date and _log_daily_path:
-        return
-    month_dir = os.path.join(_log_dir, today[:7])
-    os.makedirs(month_dir, exist_ok=True)
-    _log_daily_path = os.path.join(month_dir, f"{today}.log")
-    _log_daily_date = today
-
-def _write_log(plain_line: str):
-    """Write a plain-text line to both latest.log and daily log."""
-    with _log_lock:
-        if _log_latest_path:
-            try:
-                with open(_log_latest_path, "a", encoding="utf-8") as f:
-                    f.write(plain_line)
-            except Exception:
-                pass
-        _resolve_daily_log_path()
-        if _log_daily_path:
-            try:
-                with open(_log_daily_path, "a", encoding="utf-8") as f:
-                    f.write(plain_line)
-            except Exception:
-                pass
-
-
-def _write_crash(exc_type, exc_value, exc_tb, thread_name=None, severity="critical", handled=False):
-    """Write crash record to crashes.jsonl + daily crash archive."""
-    record = {
-        "timestamp": datetime.now(timezone.utc).isoformat(),
-        "module": MODULE_NAME,
-        "thread": thread_name or threading.current_thread().name,
-        "exception_type": exc_type.__name__ if exc_type else "Unknown",
-        "exception_message": str(exc_value),
-        "traceback": "".join(traceback.format_exception(exc_type, exc_value, exc_tb)),
-        "severity": severity,
-        "handled": handled,
-        "process_id": os.getpid(),
-        "platform": sys.platform,
-        "runtime_version": f"Python {sys.version.split()[0]}",
-    }
-
-    if exc_tb:
-        tb_entries = traceback.extract_tb(exc_tb)
-        if tb_entries:
-            last = tb_entries[-1]
-            record["context"] = {
-                "function": last.name,
-                "file": os.path.basename(last.filename),
-                "line": last.lineno,
-            }
-
-    line = json.dumps(record, ensure_ascii=False) + "\n"
-
-    if _crash_log_path:
-        try:
-            with open(_crash_log_path, "a", encoding="utf-8") as f:
-                f.write(line)
-        except Exception:
-            pass
-
-    if _log_dir:
-        try:
-            today = datetime.now().strftime("%Y-%m-%d")
-            archive_dir = os.path.join(_log_dir, "crashes", today[:7])
-            os.makedirs(archive_dir, exist_ok=True)
-            archive_path = os.path.join(archive_dir, f"{today}.jsonl")
-            with open(archive_path, "a", encoding="utf-8") as f:
-                f.write(line)
-        except Exception:
-            pass
-
-
-def _print_crash_summary(exc_type, exc_tb, thread_name=None):
-    """Print crash summary to console (red highlight)."""
-    RED = "\033[91m"
-    RESET = "\033[0m"
-
-    if exc_tb:
-        tb_entries = traceback.extract_tb(exc_tb)
-        if tb_entries:
-            last = tb_entries[-1]
-            location = f"{os.path.basename(last.filename)}:{last.lineno}"
-        else:
-            location = "unknown"
-    else:
-        location = "unknown"
-
-    prefix = f"[{MODULE_NAME}]"
-    if thread_name:
-        _builtin_print(f"{prefix} {RED}线程 {thread_name} 崩溃: "
-                       f"{exc_type.__name__} in {location}{RESET}")
-    else:
-        _builtin_print(f"{prefix} {RED}崩溃: {exc_type.__name__} in {location}{RESET}")
-    if _crash_log_path:
-        _builtin_print(f"{prefix} 崩溃日志: {_crash_log_path}")
-
-def _setup_exception_hooks():
-    """Set up global exception hooks."""
-    _orig_excepthook = sys.excepthook
-
-    def _excepthook(exc_type, exc_value, exc_tb):
-        _write_crash(exc_type, exc_value, exc_tb, severity="critical", handled=False)
-        _print_crash_summary(exc_type, exc_tb)
-        _orig_excepthook(exc_type, exc_value, exc_tb)
-
-    sys.excepthook = _excepthook
-
-    if hasattr(threading, "excepthook"):
-        def _thread_excepthook(args):
-            _write_crash(args.exc_type, args.exc_value, args.exc_traceback,
-                        thread_name=args.thread.name if args.thread else "unknown",
-                        severity="error", handled=False)
-            _print_crash_summary(args.exc_type, args.exc_traceback,
-                                thread_name=args.thread.name if args.thread else None)
-
-        threading.excepthook = _thread_excepthook
-
-def _tprint(*args, **kwargs):
-    """Timestamped print that adds [timestamp] HH:MM:SS.mmm +delta prefix."""
-    global _last_ts
-    now = time.monotonic()
-    elapsed = now - _start_ts
-    delta = now - _last_ts
-    _last_ts = now
-
-    if elapsed < 1:
-        elapsed_str = f"{elapsed * 1000:.0f}ms"
-    elif elapsed < 100:
-        elapsed_str = f"{elapsed:.1f}s"
-    else:
-        elapsed_str = f"{elapsed:.0f}s"
-
-    if delta < 0.001:
-        delta_str = ""
-    elif delta < 1:
-        delta_str = f"+{delta * 1000:.0f}ms"
-    elif delta < 100:
-        delta_str = f"+{delta:.1f}s"
-    else:
-        delta_str = f"+{delta:.0f}s"
-
-    ts = datetime.now().strftime("%H:%M:%S.%f")[:-3]
-
-    _builtin_print(*args, **kwargs)
-
-    if _log_latest_path or _log_daily_path:
-        sep = kwargs.get("sep", " ")
-        end = kwargs.get("end", "\n")
-        text = sep.join(str(a) for a in args)
-        prefix = f"[{elapsed_str:>6}] {ts} {delta_str:>8} "
-        _write_log(prefix + _strip_ansi(text) + end)
-
-builtins.print = _tprint
-
-# Ensure project root is on sys.path
-_project_root = os.environ.get("KITE_PROJECT") or os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
-if _project_root not in sys.path:
-    sys.path.insert(0, _project_root)
-
-from extensions.services.watchdog.monitor import HealthMonitor
-
-
-def _read_stdin_kite_message(expected_type: str, timeout: float = 10) -> dict | None:
-    """Read a single kite message of expected type from stdin with timeout."""
-    result = [None]
-
-    def _read():
-        try:
-            line = sys.stdin.readline().strip()
-            if line:
-                msg = json.loads(line)
-                if isinstance(msg, dict) and msg.get("kite") == expected_type:
-                    result[0] = msg
-        except Exception:
-            pass
-
-    t = threading.Thread(target=_read, daemon=True)
-    t.start()
-    t.join(timeout=timeout)
-    return result[0]
-
-
-# Global WS reference for publish_event callback
-_ws_global = None
-_shutting_down = False
-_exit_code = 0  # Exit code for main() to use
-_monitor = None
-_monitor_task = None
-
-# RPC request-response infrastructure
-_rpc_waiters: dict[str, asyncio.Event] = {}   # rpc_id -> Event
-_rpc_results: dict[str, dict] = {}             # rpc_id -> response dict
-
-
-def _is_auth_failure(e: Exception) -> bool:
-    """Check if a WebSocket exception indicates authentication failure."""
-    if hasattr(e, 'rcvd') and e.rcvd is not None:
-        code = e.rcvd.code if hasattr(e.rcvd, 'code') else 0
-        return code in (4001, 4003)
-    return False
-
-
-async def main():
-    global _ws_global, _shutting_down, _monitor
-    # Initialize log file paths
-    global _log_dir, _log_latest_path, _crash_log_path
-    module_data = os.environ.get("KITE_MODULE_DATA")
-    if module_data:
-        _log_dir = os.path.join(module_data, "log")
-        os.makedirs(_log_dir, exist_ok=True)
-        suffix = os.environ.get("KITE_INSTANCE_SUFFIX", "")
-
-        _log_latest_path = os.path.join(_log_dir, f"latest{suffix}.log")
-        try:
-            with open(_log_latest_path, "w", encoding="utf-8") as f:
-                pass
-        except Exception:
-            _log_latest_path = None
-
-        _crash_log_path = os.path.join(_log_dir, f"crashes{suffix}.jsonl")
-        try:
-            with open(_crash_log_path, "w", encoding="utf-8") as f:
-                pass
-        except Exception:
-            _crash_log_path = None
-
-        _resolve_daily_log_path()
-
-    _setup_exception_hooks()
-
-    _t0 = time.monotonic()
-
-    # Read boot_info from stdin (only token)
-    token = ""
-    try:
-        line = sys.stdin.readline().strip()
-        if line:
-            boot_info = json.loads(line)
-            token = boot_info.get("token", "")
-    except Exception:
-        pass
-
-    # Read kernel_port: env first (fast path), stdin fallback (parallel start)
-    kernel_port = int(os.environ.get("KITE_KERNEL_PORT", "0"))
-    if not kernel_port:
-        msg = _read_stdin_kite_message("kernel_port", timeout=10)
-        if msg:
-            kernel_port = int(msg.get("kernel_port", 0))
-
-    if not token or not kernel_port:
-        print("[watchdog] ERROR: Missing token or kernel_port")
-        sys.exit(1)
-
-    print(f"[watchdog] Token received ({len(token)} chars), kernel port: {kernel_port} ({_fmt_elapsed(_t0)})")
-
-    # Create monitor (once, persists across reconnects)
-    _monitor = HealthMonitor(
-        own_token=token,
-        kernel_port=kernel_port,
-    )
-
-    # Start reconnect loop
-    await _ws_loop(token, kernel_port, _t0)
-
-
-async def _ws_loop(token: str, kernel_port: int, _t0: float):
-    """Connect to Kernel with exponential backoff reconnection."""
-    global _shutting_down, _exit_code
-    retry_delay = 0.3
-    max_delay = 5.0
-    max_retries = 10
-    attempt = 0
-    while not _shutting_down:
-        try:
-            await _ws_connect(token, kernel_port, _t0)
-            retry_delay = 0.3
-            attempt = 0
-        except asyncio.CancelledError:
-            return
-        except Exception as e:
-            attempt += 1
-            if _is_auth_failure(e):
-                print(f"[watchdog] Kernel 认证失败，退出")
-                _exit_code = 1
-                _shutting_down = True
-                return
-            if attempt >= max_retries:
-                print(f"[watchdog] 重连失败 {max_retries} 次，退出")
-                _exit_code = 1
-                _shutting_down = True
-                return
-            _write_crash(type(e), e, e.__traceback__, severity="error", handled=True)
-            print(f"[watchdog] 连接错误: {e}, {retry_delay:.1f}s 后重试 ({attempt}/{max_retries})")
-            if attempt == 5:
-                print(f"\033[33m[watchdog] 提示: 已连续 {attempt} 次无法连接 Kernel (端口 {kernel_port})")
-                if kernel_port < 1024:
-                    print(f"[watchdog] ⚠ 端口 {kernel_port} 异常偏低，可能是 Kernel 端口绑定失败或配置错误")
-                print(f"[watchdog] 请检查: 1) Kernel 进程是否存活  2) kernel/module.md 中 preferred_port 配置是否正确\033[0m")
-        _ws_global_clear()
-        if _shutting_down:
-            return
-        await asyncio.sleep(retry_delay)
-        retry_delay = min(retry_delay * 2, max_delay)
-
-
-def _ws_global_clear():
-    global _ws_global
-    _ws_global = None
-
-
-async def _ws_connect(token: str, kernel_port: int, _t0: float):
-    """Single WebSocket session: connect → subscribe → register → ready → receive loop."""
-    global _ws_global, _monitor, _monitor_task
-
-    ws_url = f"ws://127.0.0.1:{kernel_port}/ws?token={token}&id=watchdog"
-    print(f"[watchdog] Connecting to Kernel: {ws_url}")
-
-    async with websockets.connect(ws_url, open_timeout=5, ping_interval=None, close_timeout=10) as ws:
-        _ws_global = ws
-        print(f"[watchdog] Connected to Kernel ({_fmt_elapsed(_t0)})")
-
-        # Subscribe to events
-        await _rpc_call(ws, "event.subscribe", {
-            "events": [
-                "system.ready",
-                "module.started",
-                "module.stopped",
-                "module.exiting",
-                "module.ready",
-                "module.shutdown",
-                "module.offline",
-            ],
-        })
-        print(f"[watchdog] Subscribed to events ({_fmt_elapsed(_t0)})")
-
-        # Register to Kernel Registry via RPC
-        await _rpc_call(ws, "registry.register", {
-            "module_id": "watchdog",
-            "module_type": "service",
-            "tools": {
-                "rpc": {
-                    "module": {
-                        "health": {"method": "health", "description": "健康检查"},
-                        "status": {"method": "status", "description": "状态查询"}
-                    }
-                }
-            },
-            "events_publish": {
-                "watchdog": {
-                    "module": {
-                        "unhealthy": {"description": "模块不健康"},
-                        "recovered": {"description": "模块恢复"},
-                        "resource_critical": {"description": "资源严重不足"},
-                        "resource_warning": {"description": "资源警告"},
-                        "resource_recovered": {"description": "资源恢复正常"}
-                    },
-                    "alert": {"description": "监控告警"}
-                }
-            },
-            "events_subscribe": [
-                "system.ready",
-                "module.started",
-                "module.stopped",
-                "module.exiting",
-                "module.ready",
-                "module.shutdown",
-                "module.offline",
-            ],
-        })
-        print(f"[watchdog] Registered to Kernel ({_fmt_elapsed(_t0)})")
-
-        # Set up monitor callbacks (reconnect-safe)
-        _monitor.publish_event = lambda event: asyncio.create_task(_publish_event(ws, event))
-        _monitor.rpc_call = lambda method, params: _rpc_call_with_response(ws, method, params)
-
-        # Publish module.ready (every reconnect)
-        if not _shutting_down:
-            startup_time = time.monotonic() - _t0
-            await _rpc_call(ws, "event.publish", {
-                "event_id": str(uuid.uuid4()),
-                "event": "module.ready",
-                "data": {
-                    "module_id": "watchdog",
-                    "graceful_shutdown": True,
-                    "startup_time": startup_time,
-                },
-            })
-            print(f"[watchdog] module.ready published ({_fmt_elapsed(_t0)})")
-
-        # Start monitor loop if not already running
-        if _monitor_task is None or _monitor_task.done():
-            _monitor_task = asyncio.create_task(_monitor.run())
-
-        # Message loop: handle incoming RPC + events
-        # CRITICAL: RPC 死锁防范
-        # - 入站 RPC 请求必须用 create_task() 异步执行，不可 await
-        # - 原因：如果 handler 内部调用 rpc_call_with_response() 发出站请求，出站响应需要本接收循环来分发
-        # - 如果接收循环被 await handler 阻塞，出站响应永远收不到 → 超时死锁
-        # - 事件通知和 RPC 响应可以同步处理（它们不会反向调用 rpc_call）
-        async for raw in ws:
-            try:
-                msg = json.loads(raw)
-            except (json.JSONDecodeError, TypeError):
-                continue
-
-            try:
-                has_method = "method" in msg
-                has_id = "id" in msg
-
-                if has_method and not has_id:
-                    # Event Notification
-                    await _handle_event_notification(msg, _monitor)
-                elif has_method and has_id:
-                    # Incoming RPC request — run in background to prevent deadlock
-                    asyncio.create_task(_handle_rpc_request(ws, msg, _monitor))
-                elif has_id and not has_method:
-                    # RPC response — route to waiter
-                    msg_id = msg["id"]
-                    if msg_id in _rpc_waiters:
-                        _rpc_results[msg_id] = msg
-                        _rpc_waiters[msg_id].set()
-            except Exception as e:
-                print(f"[watchdog] 消息处理异常（已忽略）: {e}")
-
-
-
-async def _rpc_call(ws, method: str, params: dict = None):
-    """Send a JSON-RPC 2.0 request (fire-and-forget, no response awaited)."""
-    msg = {"jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": method}
-    if params:
-        msg["params"] = params
-    await ws.send(json.dumps(msg))
-
-
-async def _publish_event(ws, event: dict):
-    """Publish an event via RPC event.publish."""
-    await _rpc_call(ws, "event.publish", {
-        "event_id": str(uuid.uuid4()),
-        "event": event.get("event", ""),
-        "data": event.get("data", {}),
-    })
-
-
-async def _rpc_call_with_response(ws, method: str, params: dict = None, timeout: float = 5):
-    """Send a JSON-RPC 2.0 request and await the response."""
-    rpc_id = str(uuid.uuid4())
-    msg = {"jsonrpc": "2.0", "id": rpc_id, "method": method}
-    if params:
-        msg["params"] = params
-
-    evt = asyncio.Event()
-    _rpc_waiters[rpc_id] = evt
-
-    await ws.send(json.dumps(msg))
-
-    try:
-        await asyncio.wait_for(evt.wait(), timeout=timeout)
-        return _rpc_results.pop(rpc_id, {})
-    except asyncio.TimeoutError:
-        return {"error": {"code": -32000, "message": f"RPC timeout: {method}"}}
-    finally:
-        _rpc_waiters.pop(rpc_id, None)
-        _rpc_results.pop(rpc_id, None)
-
-
-async def _publish_event(ws, event: dict):
-    """Publish an event via RPC event.publish."""
-    await _rpc_call(ws, "event.publish", {
-        "event_id": str(uuid.uuid4()),
-        "event": event.get("event", ""),
-        "data": event.get("data", {}),
-    })
-
-
-async def _handle_ping_event(data: dict):
-    """Handle system.ping event and reply with system.pong."""
-    t1 = data.get("ping_time")
-    t2 = time.time()
-
-    await _publish_event(_ws_global, {
-        "event": "system.pong",
-        "data": {
-            "module_id": MODULE_NAME,
-            "ping_time": t1,
-            "pong_time": t2,
-        },
-    })
-
-
-async def _handle_event_notification(msg: dict, monitor: HealthMonitor):
-    """Handle an event notification (JSON-RPC 2.0 Notification with method='event')."""
-    params = msg.get("params", {})
-    event_type = params.get("event", "")
-    data = params.get("data", {})
-
-    # Handle system.ping event
-    if event_type == "system.ping":
-        await _handle_ping_event(data)
-        return
-
-    # Debug: log all shutdown events
-    if event_type == "module.shutdown":
-        target = data.get("module_id", "")
-        reason = data.get("reason", "")
-        # Handle both targeted shutdown (module_id == "watchdog") and broadcast shutdown (no module_id or launcher_lost)
-        if target == "watchdog" or not target or reason == "launcher_lost":
-            await _handle_shutdown(monitor)
-            return
-
-    # Forward to monitor (extract params from JSON-RPC notification)
-    await monitor.handle_event(params)
-
-
-async def _handle_rpc_request(ws, msg: dict, monitor: HealthMonitor):
-    """Handle an incoming RPC request (watchdog.* methods)."""
-    rpc_id = msg.get("id", "")
-    method = msg.get("method", "")
-    params = msg.get("params", {})
-
-    handlers = {
-        "health": lambda p: _rpc_health(monitor),
-        "status": lambda p: _rpc_status(monitor),
-    }
-    handler = handlers.get(method)
-    if handler:
-        try:
-            result = await handler(params)
-            await ws.send(json.dumps({"jsonrpc": "2.0", "id": rpc_id, "result": result}))
-        except Exception as e:
-            await ws.send(json.dumps({
-                "jsonrpc": "2.0", "id": rpc_id,
-                "error": {"code": -32603, "message": str(e)},
-            }))
-    else:
-        await ws.send(json.dumps({
-            "jsonrpc": "2.0", "id": rpc_id,
-            "error": {"code": -32601, "message": f"Method not found: {method}"},
-        }))
-
-
-async def _rpc_health(monitor: HealthMonitor) -> dict:
-    """RPC handler for watchdog.health."""
-    # 统计不健康的模块数量
-    unhealthy_count = sum(1 for s in monitor.modules.values() if s.state == "unhealthy")
-    # 统计资源严重不足的模块数量
-    critical_resources = sum(1 for s in monitor.modules.values() if s.resource_state == "critical")
-    # 统计总重启次数
-    total_restarts = sum(s.restarted_count for s in monitor.modules.values())
-
-    return {
-        "status": "healthy",
-        "uptime_seconds": round(time.time() - _start_ts),
-        "details": {
-            "monitored_modules": len(monitor.modules),
-            "unhealthy_modules": unhealthy_count,
-            "critical_resources": critical_resources,
-            "total_restarts": total_restarts,
-        },
-    }
-
-
-async def _rpc_status(monitor: HealthMonitor) -> dict:
-    """RPC handler for watchdog.status."""
-    return monitor.get_status()
-
-
-async def _handle_shutdown(monitor: HealthMonitor):
-    """Handle module.shutdown event — ack → exiting → cleanup → ready → exit."""
-    global _shutting_down
-    print("[watchdog] Received shutdown request")
-    _shutting_down = True
-    # Step 1: Send ack (立即确认收到)
-    await _publish_event(_ws_global, {
-        "event": "module.shutdown.ack",
-        "data": {"module_id": "watchdog"},
-    })
-    # Step 2: Send module.exiting (开始清理)
-    await _publish_event(_ws_global, {
-        "event": "module.exiting",
-        "data": {
-            "module_id": "watchdog",
-            "type": "passive",
-            "reason": "shutdown_requested",
-            "restart": "auto",
-            "action": "none",
-            "timeout": 2.0,
-            "restart_delay": 0.0,
-        },
-    })
-    # Step 3: Cleanup
-    monitor.stop()
-    # Step 4: Send ready (清理完成)
-    await _publish_event(_ws_global, {
-        "event": "module.shutdown.ready",
-        "data": {"module_id": "watchdog"},
-    })
-    print("[watchdog] Shutdown ready, exiting")
-    # Step 5: Exit
-    sys.exit(_exit_code)
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
-
+"""
+Watchdog entry point.
+Connects to Kernel via WebSocket JSON-RPC 2.0, registers, subscribes to events,
+runs health monitor loop, handles incoming RPC requests.
+"""
+
+import asyncio
+import builtins
+import json
+import os
+import re
+import sys
+import threading
+import time
+import traceback
+import uuid
+import random
+from datetime import datetime, timezone
+
+import websockets
+
+
+# ── Module configuration ──
+
+def _load_module_config() -> dict:
+    """Load module configuration from module.md frontmatter.
+
+    Returns:
+        Dict with keys: name, preferred_port, advertise_ip
+
+    Raises:
+        SystemExit: If module.md is invalid or name is non-compliant
+    """
+    _this_dir = os.path.dirname(os.path.abspath(__file__))
+    module_md = os.path.join(_this_dir, "module.md")
+
+    # Calculate relative path for error messages
+    project_root = os.environ.get("KITE_PROJECT", "")
+    if project_root and _this_dir.startswith(project_root):
+        rel_path = os.path.relpath(_this_dir, project_root)
+    else:
+        rel_path = _this_dir
+
+    # Default values (will be overridden if valid config exists)
+    result = {
+        "name": "",
+        "preferred_port": 0,
+        "advertise_ip": "0.0.0.0"
+    }
+
+    # Check if module.md exists
+    if not os.path.exists(module_md):
+        print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+        print(f"  Path: {rel_path}/module.md")
+        print(f"  Reason: File not found")
+        sys.exit(1)
+
+    try:
+        with open(module_md, encoding="utf-8") as f:
+            text = f.read()
+
+        # Extract YAML frontmatter (between --- markers)
+        import re
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if not m:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing YAML frontmatter")
+            sys.exit(1)
+
+        # Parse YAML frontmatter
+        try:
+            import yaml
+            fm = yaml.safe_load(m.group(1)) or {}
+        except ImportError:
+            print(f"[{rel_path}] ERROR: PyYAML not installed, cannot parse module.md")
+            sys.exit(1)
+        except Exception as e:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: YAML parse error: {e}")
+            sys.exit(1)
+
+        # Validate 'name' field (required)
+        if "name" not in fm:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing 'name' field")
+            sys.exit(1)
+
+        raw_name = str(fm["name"]).strip()
+
+        if not raw_name:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Empty module name")
+            sys.exit(1)
+
+        # Validate name characters
+        sanitized = re.sub(r'[^a-zA-Z0-9_\-]', '', raw_name)
+
+        if sanitized != raw_name:
+            invalid_chars = ''.join(sorted(set(c for c in raw_name if c not in sanitized)))
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Invalid characters in name '{raw_name}': {repr(invalid_chars)}")
+            sys.exit(1)
+
+        result["name"] = sanitized
+
+        # Extract optional fields
+        if "preferred_port" in fm:
+            try:
+                result["preferred_port"] = int(fm["preferred_port"])
+            except (ValueError, TypeError):
+                pass
+
+        if "advertise_ip" in fm:
+            result["advertise_ip"] = str(fm["advertise_ip"])
+
+        # max_connections（弹性连接上限）
+        try:
+            result["max_connections"] = max(1, min(10, int(fm.get("max_connections", 1))))
+        except (ValueError, TypeError):
+            result["max_connections"] = 1
+
+    except SystemExit:
+        raise  # Re-raise exit to prevent catching by outer except
+    except Exception as e:
+        print(f"[{rel_path}] ERROR: Failed to read module.md: {e}")
+        sys.exit(1)
+
+    return result
+
+_module_config = _load_module_config()
+MODULE_NAME = _module_config["name"]
+
+
+def _fmt_elapsed(t0: float) -> str:
+    """Format elapsed time since t0: <1s → 'NNNms', >=1s → 'N.Ns', >=10s → 'NNs'."""
+    d = time.monotonic() - t0
+    if d < 1:
+        return f"{d * 1000:.0f}ms"
+    if d < 10:
+        return f"{d:.1f}s"
+    return f"{d:.0f}s"
+
+
+# ── Safe stdout/stderr: ignore BrokenPipeError after Launcher closes stdio ──
+
+class _SafeWriter:
+    """Wraps a stream to silently swallow BrokenPipeError on write/flush."""
+    def __init__(self, stream):
+        self._stream = stream
+
+    def write(self, s):
+        try:
+            self._stream.write(s)
+        except (BrokenPipeError, OSError):
+            pass
+
+    def flush(self):
+        try:
+            self._stream.flush()
+        except (BrokenPipeError, OSError):
+            pass
+
+    def __getattr__(self, name):
+        return getattr(self._stream, name)
+
+sys.stdout = _SafeWriter(sys.stdout)
+sys.stderr = _SafeWriter(sys.stderr)
+
+
+# ── Timestamped print + log file writer ──
+
+_builtin_print = builtins.print
+_start_ts = time.monotonic()
+_last_ts = time.monotonic()
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+_log_lock = threading.Lock()
+_log_latest_path = None
+_log_daily_path = None
+_log_daily_date = ""
+_log_dir = None
+_crash_log_path = None
+
+def _strip_ansi(s: str) -> str:
+    return _ANSI_RE.sub("", s)
+
+def _resolve_daily_log_path():
+    """Resolve daily log path based on current date."""
+    global _log_daily_path, _log_daily_date
+    if not _log_dir:
+        return
+    today = datetime.now().strftime("%Y-%m-%d")
+    if today == _log_daily_date and _log_daily_path:
+        return
+    month_dir = os.path.join(_log_dir, today[:7])
+    os.makedirs(month_dir, exist_ok=True)
+    _log_daily_path = os.path.join(month_dir, f"{today}.log")
+    _log_daily_date = today
+
+def _write_log(plain_line: str):
+    """Write a plain-text line to both latest.log and daily log."""
+    with _log_lock:
+        if _log_latest_path:
+            try:
+                with open(_log_latest_path, "a", encoding="utf-8") as f:
+                    f.write(plain_line)
+            except Exception:
+                pass
+        _resolve_daily_log_path()
+        if _log_daily_path:
+            try:
+                with open(_log_daily_path, "a", encoding="utf-8") as f:
+                    f.write(plain_line)
+            except Exception:
+                pass
+
+
+def _write_crash(exc_type, exc_value, exc_tb, thread_name=None, severity="critical", handled=False):
+    """Write crash record to crashes.jsonl + daily crash archive."""
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "module": MODULE_NAME,
+        "thread": thread_name or threading.current_thread().name,
+        "exception_type": exc_type.__name__ if exc_type else "Unknown",
+        "exception_message": str(exc_value),
+        "traceback": "".join(traceback.format_exception(exc_type, exc_value, exc_tb)),
+        "severity": severity,
+        "handled": handled,
+        "process_id": os.getpid(),
+        "platform": sys.platform,
+        "runtime_version": f"Python {sys.version.split()[0]}",
+    }
+
+    if exc_tb:
+        tb_entries = traceback.extract_tb(exc_tb)
+        if tb_entries:
+            last = tb_entries[-1]
+            record["context"] = {
+                "function": last.name,
+                "file": os.path.basename(last.filename),
+                "line": last.lineno,
+            }
+
+    line = json.dumps(record, ensure_ascii=False) + "\n"
+
+    if _crash_log_path:
+        try:
+            with open(_crash_log_path, "a", encoding="utf-8") as f:
+                f.write(line)
+        except Exception:
+            pass
+
+    if _log_dir:
+        try:
+            today = datetime.now().strftime("%Y-%m-%d")
+            archive_dir = os.path.join(_log_dir, "crashes", today[:7])
+            os.makedirs(archive_dir, exist_ok=True)
+            archive_path = os.path.join(archive_dir, f"{today}.jsonl")
+            with open(archive_path, "a", encoding="utf-8") as f:
+                f.write(line)
+        except Exception:
+            pass
+
+
+def _print_crash_summary(exc_type, exc_tb, thread_name=None):
+    """Print crash summary to console (red highlight)."""
+    RED = "\033[91m"
+    RESET = "\033[0m"
+
+    if exc_tb:
+        tb_entries = traceback.extract_tb(exc_tb)
+        if tb_entries:
+            last = tb_entries[-1]
+            location = f"{os.path.basename(last.filename)}:{last.lineno}"
+        else:
+            location = "unknown"
+    else:
+        location = "unknown"
+
+    prefix = f"[{MODULE_NAME}]"
+    if thread_name:
+        _builtin_print(f"{prefix} {RED}线程 {thread_name} 崩溃: "
+                       f"{exc_type.__name__} in {location}{RESET}")
+    else:
+        _builtin_print(f"{prefix} {RED}崩溃: {exc_type.__name__} in {location}{RESET}")
+    if _crash_log_path:
+        _builtin_print(f"{prefix} 崩溃日志: {_crash_log_path}")
+
+def _setup_exception_hooks():
+    """Set up global exception hooks."""
+    _orig_excepthook = sys.excepthook
+
+    def _excepthook(exc_type, exc_value, exc_tb):
+        _write_crash(exc_type, exc_value, exc_tb, severity="critical", handled=False)
+        _print_crash_summary(exc_type, exc_tb)
+        _orig_excepthook(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _excepthook
+
+    if hasattr(threading, "excepthook"):
+        def _thread_excepthook(args):
+            _write_crash(args.exc_type, args.exc_value, args.exc_traceback,
+                        thread_name=args.thread.name if args.thread else "unknown",
+                        severity="error", handled=False)
+            _print_crash_summary(args.exc_type, args.exc_traceback,
+                                thread_name=args.thread.name if args.thread else None)
+
+        threading.excepthook = _thread_excepthook
+
+def _tprint(*args, **kwargs):
+    """Timestamped print that adds [timestamp] HH:MM:SS.mmm +delta prefix."""
+    global _last_ts
+    now = time.monotonic()
+    elapsed = now - _start_ts
+    delta = now - _last_ts
+    _last_ts = now
+
+    if elapsed < 1:
+        elapsed_str = f"{elapsed * 1000:.0f}ms"
+    elif elapsed < 100:
+        elapsed_str = f"{elapsed:.1f}s"
+    else:
+        elapsed_str = f"{elapsed:.0f}s"
+
+    if delta < 0.001:
+        delta_str = ""
+    elif delta < 1:
+        delta_str = f"+{delta * 1000:.0f}ms"
+    elif delta < 100:
+        delta_str = f"+{delta:.1f}s"
+    else:
+        delta_str = f"+{delta:.0f}s"
+
+    ts = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+
+    _builtin_print(*args, **kwargs)
+
+    if _log_latest_path or _log_daily_path:
+        sep = kwargs.get("sep", " ")
+        end = kwargs.get("end", "\n")
+        text = sep.join(str(a) for a in args)
+        prefix = f"[{elapsed_str:>6}] {ts} {delta_str:>8} "
+        _write_log(prefix + _strip_ansi(text) + end)
+
+builtins.print = _tprint
+
+# Ensure project root is on sys.path
+_project_root = os.environ.get("KITE_PROJECT") or os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+if _project_root not in sys.path:
+    sys.path.insert(0, _project_root)
+
+from extensions.services.watchdog.monitor import HealthMonitor
+
+
+def _read_stdin_kite_message(expected_type: str, timeout: float = 10) -> dict | None:
+    """Read a single kite message of expected type from stdin with timeout."""
+    result = [None]
+
+    def _read():
+        try:
+            line = sys.stdin.readline().strip()
+            if line:
+                msg = json.loads(line)
+                if isinstance(msg, dict) and msg.get("kite") == expected_type:
+                    result[0] = msg
+        except Exception:
+            pass
+
+    t = threading.Thread(target=_read, daemon=True)
+    t.start()
+    t.join(timeout=timeout)
+    return result[0]
+
+
+# Global WS reference for publish_event callback
+_ws_global = None
+_shutting_down = False
+_exit_code = 0  # Exit code for main() to use
+_monitor = None
+_monitor_task = None
+_has_registered = False  # 是否已完成过注册（用于判断 reason: startup vs recovery）
+_init_start_time = 0.0  # 进程启动时间（用于 startup_time 计算）
+
+# 弹性多连接
+_extra_ws: dict = {}           # slot → WebSocket（附加连接）
+_extra_ws_tasks: dict = {}     # slot → recv loop Task
+_kernel_port = ""              # 缓存 kernel_port，供 offer handler 使用
+
+# RPC request-response infrastructure
+_pending_rpc: dict[str, asyncio.Future] = {}   # rpc_id -> Future
+
+
+def _handle_rpc_response(msg: dict):
+    """Route an RPC response to its pending Future."""
+    rpc_id = msg.get("id")
+    future = _pending_rpc.pop(rpc_id, None)
+    if future and not future.done():
+        future.set_result(msg)
+
+
+def _is_auth_failure(e: Exception) -> bool:
+    """Check if a WebSocket exception indicates authentication failure."""
+    if hasattr(e, 'rcvd') and e.rcvd is not None:
+        code = e.rcvd.code if hasattr(e.rcvd, 'code') else 0
+        return code in (4001, 4003)
+    return False
+
+
+async def _main_with_monitor(token: str, kernel_port: int, _t0: float):
+    global _ws_global, _shutting_down, _monitor, _init_start_time
+
+    _init_start_time = _t0  # 记录进程启动时间
+
+    # Create monitor (once, persists across reconnects)
+    _monitor = HealthMonitor(
+        own_token=token,
+        kernel_port=kernel_port,
+    )
+
+    # 注册 request_exit 回调，让 monitor 能请求进程退出
+    def _request_exit(code: int = 0):
+        global _shutting_down, _exit_code
+        _exit_code = code
+        _shutting_down = True
+        # 关闭 WebSocket 以中断 _ws_loop
+        if _ws_global:
+            asyncio.ensure_future(_ws_global.close(code=1000, reason="Monitor requested exit"))
+    _monitor.request_exit = _request_exit
+
+    # Start reconnect loop
+    await _ws_loop(token, kernel_port, _t0)
+
+
+async def _ws_loop(token: str, kernel_port: int, _t0: float):
+    """Connect to Kernel with exponential backoff reconnection."""
+    global _shutting_down, _exit_code
+    retry_delay = 0.5
+    max_delay = 10.0
+    attempt = 0
+    cooldown_attempts = 0
+
+    while not _shutting_down:
+        try:
+            await _ws_connect(token, kernel_port, _t0)
+            retry_delay = 0.5
+            attempt = 0
+            cooldown_attempts = 0
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            if _shutting_down:
+                return
+
+            code = _get_close_code(e)
+
+            # never: 永不重连
+            if code in (4001, 4003, 4004, 1008, 4010):
+                print(f"[watchdog] 致命错误 (code {code})，退出")
+                _exit_code = 1
+                _shutting_down = True
+                return
+
+            # cooldown: 速率限制
+            if code == 4020:
+                cooldown_attempts += 1
+                if cooldown_attempts >= 5:
+                    print(f"[watchdog] 速率限制重试 5 次，退出")
+                    _exit_code = 1
+                    _shutting_down = True
+                    return
+                print(f"[watchdog] 速率限制，10.0s 后重试 ({cooldown_attempts}/5)")
+                await asyncio.sleep(10.0)
+                continue
+
+            # 连接被拒绝/重置 — Kernel 可能正在关闭，不记录崩溃日志
+            # Windows 的 [WinError 1225] 是 OSError 不是 ConnectionRefusedError
+            _is_conn_refused = isinstance(e, (ConnectionRefusedError, ConnectionResetError))
+            if not _is_conn_refused and isinstance(e, OSError) and getattr(e, 'winerror', None) == 1225:
+                _is_conn_refused = True
+            if _is_conn_refused:
+                attempt += 1
+                if attempt >= 3:
+                    print(f"[watchdog] Kernel 持续不可达 ({attempt} 次)，正常退出")
+                    _exit_code = 0
+                    _shutting_down = True
+                    return
+                jitter = retry_delay * 0.2 * random.random()
+                sleep_time = retry_delay + jitter
+                print(f"[watchdog] Kernel 连接失败: {type(e).__name__}, {sleep_time:.1f}s 后重试 (attempt {attempt})")
+            else:
+                # standard: 指数退避 + jitter
+                attempt += 1
+                jitter = retry_delay * 0.2 * random.random()
+                sleep_time = retry_delay + jitter
+                _write_crash(type(e), e, e.__traceback__, severity="error", handled=True)
+                print(f"[watchdog] 连接错误: {e}, {sleep_time:.1f}s 后重试 (attempt {attempt})")
+                if attempt >= 10:
+                    print(f"[watchdog] 连续 {attempt} 次连接失败，正常退出")
+                    _exit_code = 0
+                    _shutting_down = True
+                    return
+                if attempt == 5:
+                    print(f"\033[33m[watchdog] 提示: 已连续 {attempt} 次无法连接 Kernel (端口 {kernel_port})")
+                    if kernel_port < 1024:
+                        print(f"[watchdog] ⚠ 端口 {kernel_port} 异常偏低，可能是 Kernel 端口绑定失败或配置错误")
+                    print(f"[watchdog] 请检查: 1) Kernel 进程是否存活  2) kernel/module.md 中 preferred_port 配置是否正确\033[0m")
+
+        _ws_global_clear()
+        if _shutting_down:
+            return
+        await asyncio.sleep(sleep_time if 'sleep_time' in locals() else retry_delay)
+        retry_delay = min(retry_delay * 2, max_delay)
+
+
+def _get_close_code(e: Exception) -> int:
+    """从 websockets 异常中提取关闭码"""
+    if hasattr(e, 'rcvd') and e.rcvd is not None:
+        return getattr(e.rcvd, 'code', 0)
+    return 0
+
+
+def _ws_global_clear():
+    global _ws_global
+    _ws_global = None
+    # 断开时清理所有等待中的 RPC Future，避免泄漏
+    for rpc_id, future in list(_pending_rpc.items()):
+        if not future.done():
+            future.set_result({"error": {"code": -32000, "message": "WebSocket disconnected"}})
+    _pending_rpc.clear()
+
+
+async def _ws_connect(token: str, kernel_port: int, _t0: float):
+    """Single WebSocket session: connect → auth → receiver → wait require_init → subscribe → register → ready → receive loop."""
+    global _ws_global, _monitor, _monitor_task, _kernel_port, _has_registered
+
+    _kernel_port = kernel_port
+    ws_url = f"ws://127.0.0.1:{kernel_port}/ws?id=watchdog"
+    print(f"[watchdog] Connecting to Kernel: {ws_url}")
+
+    async with websockets.connect(ws_url, open_timeout=5, ping_interval=None, close_timeout=10) as ws:
+        # Send auth message first
+        auth_req = {
+            "jsonrpc": "2.0",
+            "id": "auth",
+            "method": "auth",
+            "params": {"token": token}
+        }
+        await ws.send(json.dumps(auth_req))
+
+        # Wait for auth response
+        auth_resp_raw = await asyncio.wait_for(ws.recv(), timeout=5)
+        auth_resp = json.loads(auth_resp_raw)
+        if "error" in auth_resp:
+            raise Exception(f"Auth failed: {auth_resp['error']}")
+
+        _ws_global = ws
+        print(f"[watchdog] Connected to Kernel ({_fmt_elapsed(_t0)})")
+
+        # 启动接收循环（先于 RPC 调用，防止 wait_response 死锁）
+        # system.require_init 会在 receiver 中被识别并触发异步注册
+        receiver_task = asyncio.create_task(_ws_receiver(ws, _monitor))
+
+        try:
+            # Set up monitor callbacks (reconnect-safe, 在 require_init 之前设置好)
+            _monitor.publish_event = lambda event: asyncio.create_task(
+                _publish_event(ws, event.get("event", ""), event.get("data", {}))
+            )
+            _monitor.rpc_call = lambda method, params: _rpc_call(ws, method, params)
+            _monitor.rpc_call_kernel = lambda method, params: _rpc_call(ws, method, params)
+
+            # Start monitor loop if not already running
+            if _monitor_task is None or _monitor_task.done():
+                _monitor_task = asyncio.create_task(_monitor.run())
+
+            # 等待接收循环结束（连接关闭时自然退出）
+            # system.require_init 到达后会在 receiver 中触发 _do_init 异步任务
+            await receiver_task
+        finally:
+            receiver_task.cancel()
+
+
+
+async def _ws_receiver(ws, monitor):
+    """接收循环：分发 RPC 响应、事件通知、入站 RPC 请求。
+    必须在 subscribe/register 之前启动，否则 _rpc_call 的 wait_response 会死锁。
+    识别 system.require_init 系统消息，触发异步注册任务。"""
+    try:
+        async for raw in ws:
+            try:
+                msg = json.loads(raw)
+            except (json.JSONDecodeError, TypeError):
+                continue
+
+            try:
+                has_method = "method" in msg
+                has_id = "id" in msg
+
+                if has_method and not has_id:
+                    # 检查 system.require_init 系统消息（不走 EventHub 订阅）
+                    params = msg.get("params", {})
+                    event_type = params.get("event", "")
+                    if event_type == "system.require_init":
+                        asyncio.create_task(_do_init(ws))
+                        continue
+                    asyncio.create_task(_handle_event_notification(msg, monitor))
+                elif has_method and has_id:
+                    asyncio.create_task(_handle_rpc_request(ws, msg, monitor))
+                elif has_id and not has_method:
+                    _handle_rpc_response(msg)
+            except Exception as e:
+                print(f"[watchdog] 消息处理异常（已忽略）: {e}")
+    except websockets.exceptions.ConnectionClosed:
+        pass  # Kernel 连接关闭，正常退出接收循环
+
+
+async def _rpc_call(ws, method: str, params: dict = None,
+                    wait_response: bool = True, timeout: float = 3.0) -> dict:
+    """JSON-RPC 2.0 request。默认等待响应。"""
+    rpc_id = str(uuid.uuid4())
+    msg = {"jsonrpc": "2.0", "id": rpc_id, "method": method}
+    if params:
+        msg["params"] = params
+    if not wait_response:
+        await ws.send(json.dumps(msg))
+        return {}
+    future = asyncio.get_event_loop().create_future()
+    _pending_rpc[rpc_id] = future
+    await ws.send(json.dumps(msg))
+    try:
+        return await asyncio.wait_for(future, timeout=timeout)
+    except asyncio.TimeoutError:
+        _pending_rpc.pop(rpc_id, None)
+        return {"error": {"code": -32000, "message": f"RPC timeout: {method} ({timeout}s)"}}
+
+
+async def _do_init(ws):
+    """收到 system.require_init 后执行：subscribe → register → module.ready。
+    异步任务，不阻塞 receiver。"""
+    global _has_registered
+
+    # 判断 reason
+    if not _has_registered:
+        reason = "startup"
+    else:
+        reason = "recovery"
+
+    print(f"[watchdog] Received system.require_init, performing init (reason={reason})")
+
+    try:
+        # Subscribe to events
+        await _rpc_call(ws, "event.subscribe", {
+            "events": [
+                "system.ready",
+                "module.started",
+                "module.stopped",
+                "module.exiting",
+                "module.ready",
+                "module.shutdown",
+                "module.offline",
+                "module.degraded",
+                "module.recovered",
+            ],
+        })
+        print(f"[watchdog] Subscribed to events (reason={reason})")
+
+        # Register to Kernel Registry via RPC
+        await _rpc_call(ws, "registry.register", {
+            "module_id": "watchdog",
+            "module_type": "service",
+            "tools": {
+                "rpc": {
+                    "module": {
+                        "health": {"method": "health", "description": "健康检查"},
+                        "status": {"method": "status", "description": "状态查询"},
+                        "start_monitor": {"method": "start_monitor", "description": "开启监控（由 Launcher 调用）"},
+                        "stop_monitor": {"method": "stop_monitor", "description": "关闭监控（由 Launcher 调用）"},
+                        "health_events": {"method": "health_events", "description": "查询健康事件记录"},
+                    }
+                }
+            },
+            "events_publish": {
+                "watchdog": {
+                    "module": {
+                        "unhealthy": {"description": "模块不健康"},
+                        "recovered": {"description": "模块恢复"},
+                        "resource_critical": {"description": "资源严重不足"},
+                        "resource_warning": {"description": "资源警告"},
+                        "resource_recovered": {"description": "资源恢复正常"},
+                        "degraded_timeout": {"description": "模块超长降级告警"},
+                    },
+                    "alert": {"description": "监控告警"}
+                }
+            },
+            "events_subscribe": [
+                "system.ready",
+                "module.started",
+                "module.stopped",
+                "module.exiting",
+                "module.ready",
+                "module.shutdown",
+                "module.offline",
+                "module.degraded",
+                "module.recovered",
+            ],
+        })
+        print(f"[watchdog] Registered to Kernel (reason={reason})")
+
+        # Publish module.ready with reason
+        if not _shutting_down:
+            startup_time = time.monotonic() - _init_start_time if _init_start_time else 0
+            await _publish_event(ws, "module.ready", {
+                "module_id": "watchdog",
+                "graceful_shutdown": True,
+                "startup_time": startup_time,
+                "reason": reason,
+            })
+            print(f"[watchdog] module.ready published (reason={reason})")
+
+        _has_registered = True
+    except Exception as e:
+        print(f"[watchdog] _do_init failed: {e}")
+
+
+async def _publish_event(ws, event: str, data: dict = None):
+    """Publish event via event.publish RPC (fire-and-forget)."""
+    await _rpc_call(ws, "event.publish", {
+        "event_id": str(uuid.uuid4()),
+        "event": event,
+        "data": data or {},
+    }, wait_response=False)
+
+
+async def _handle_ping_event(data: dict):
+    """Handle system.ping event and reply with system.pong."""
+    t1 = data.get("ping_time")
+    t2 = time.time()
+
+    await _publish_event(_ws_global, "system.pong", {
+        "module_id": MODULE_NAME,
+        "ping_time": t1,
+        "pong_time": t2,
+    })
+
+
+async def _handle_event_notification(msg: dict, monitor: HealthMonitor):
+    """Handle an event notification (JSON-RPC 2.0 Notification with method='event')."""
+    params = msg.get("params", {})
+    event_type = params.get("event", "")
+    data = params.get("data", {})
+
+    # Handle system.ping event
+    if event_type == "system.ping":
+        await _handle_ping_event(data)
+        return
+
+    # 弹性连接 offer/release
+    if event_type == "system.connection.offer":
+        asyncio.create_task(_handle_connection_offer(data))
+        return
+    if event_type == "system.connection.release":
+        asyncio.create_task(_handle_connection_release(data))
+        return
+
+    # Debug: log all shutdown events
+    if event_type == "module.shutdown":
+        target = data.get("module_id", "")
+        reason = data.get("reason", "")
+        # Handle both targeted shutdown (module_id == "watchdog") and broadcast shutdown (no module_id or launcher_lost)
+        if target == "watchdog" or not target or reason == "launcher_lost":
+            await _handle_shutdown(monitor)
+            return
+
+    # Forward to monitor (extract params from JSON-RPC notification)
+    await monitor.handle_event(params)
+
+
+async def _handle_rpc_request(ws, msg: dict, monitor: HealthMonitor):
+    """Handle an incoming RPC request (watchdog.* methods)."""
+    rpc_id = msg.get("id", "")
+    method = msg.get("method", "")
+    params = msg.get("params", {})
+
+    handlers = {
+        "health": lambda p: _rpc_health(monitor),
+        "status": lambda p: _rpc_status(monitor),
+        "start_monitor": lambda p: _rpc_start_monitor(monitor),
+        "stop_monitor": lambda p: _rpc_stop_monitor(monitor),
+        "health_events": lambda p: _rpc_health_events(monitor, p),
+    }
+    handler = handlers.get(method)
+    if handler:
+        try:
+            result = await handler(params)
+            await ws.send(json.dumps({"jsonrpc": "2.0", "id": rpc_id, "result": result}))
+        except Exception as e:
+            await ws.send(json.dumps({
+                "jsonrpc": "2.0", "id": rpc_id,
+                "error": {"code": -32603, "message": str(e)},
+            }))
+    else:
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0", "id": rpc_id,
+            "error": {"code": -32601, "message": f"Method not found: {method}"},
+        }))
+
+
+async def _rpc_health(monitor: HealthMonitor) -> dict:
+    """RPC handler for watchdog.health."""
+    # 统计不健康的模块数量
+    unhealthy_count = sum(1 for s in monitor.modules.values() if s.state == "unhealthy")
+    # 统计资源严重不足的模块数量
+    critical_resources = sum(1 for s in monitor.modules.values() if s.resource_state == "critical")
+    # 统计总重启次数
+    total_restarts = sum(s.restarted_count for s in monitor.modules.values())
+
+    return {
+        "status": "healthy",
+        "uptime_seconds": round(time.time() - _start_ts),
+        "details": {
+            "monitored_modules": len(monitor.modules),
+            "unhealthy_modules": unhealthy_count,
+            "critical_resources": critical_resources,
+            "total_restarts": total_restarts,
+        },
+    }
+
+
+async def _rpc_status(monitor: HealthMonitor) -> dict:
+    """RPC handler for watchdog.status."""
+    return monitor.get_status()
+
+
+async def _rpc_start_monitor(monitor: HealthMonitor) -> dict:
+    """RPC handler for watchdog.start_monitor — 由 Launcher 调用开启监控。"""
+    return monitor.start_monitor()
+
+
+async def _rpc_stop_monitor(monitor: HealthMonitor) -> dict:
+    """RPC handler for watchdog.stop_monitor — 由 Launcher 调用关闭监控。"""
+    return monitor.stop_monitor()
+
+
+async def _rpc_health_events(monitor: HealthMonitor, params: dict) -> dict:
+    """RPC handler for watchdog.health_events — 查询健康事件记录。"""
+    limit = params.get("limit", 50)
+    since = params.get("since")
+    if not isinstance(limit, int):
+        try:
+            limit = int(limit)
+        except (ValueError, TypeError):
+            limit = 50
+    return monitor.get_health_events(limit=limit, since=since)
+
+
+async def _handle_connection_offer(data):
+    """处理 Kernel 下发的 slot token，建立附加连接。"""
+    slots = data.get("slots", {})
+    for slot_str, info in slots.items():
+        slot = int(slot_str)
+        token = info.get("token", "")
+        if not token or slot in _extra_ws:
+            continue
+        asyncio.create_task(_connect_slot(slot, token))
+
+
+async def _connect_slot(slot, token):
+    """建立单个 slot 附加连接。"""
+    ws_url = f"ws://127.0.0.1:{_kernel_port}/ws"
+    try:
+        ws = await websockets.connect(ws_url, open_timeout=5, ping_interval=None, close_timeout=5)
+        auth_req = {"jsonrpc": "2.0", "id": f"auth-slot-{slot}", "method": "auth", "params": {"token": token}}
+        await ws.send(json.dumps(auth_req))
+        resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=5))
+        if "error" in resp:
+            await ws.close()
+            return
+        _extra_ws[slot] = ws
+        _extra_ws_tasks[slot] = asyncio.create_task(_slot_recv_loop(slot, ws))
+        print(f"[watchdog] Slot {slot} connected")
+    except Exception as e:
+        print(f"[watchdog] Slot {slot} connect failed: {e}")
+
+
+async def _slot_recv_loop(slot, ws):
+    """附加连接的接收循环：与主连接平等处理所有消息。"""
+    try:
+        async for raw in ws:
+            try:
+                msg = json.loads(raw)
+            except (json.JSONDecodeError, TypeError):
+                continue
+            try:
+                has_method = "method" in msg
+                has_id = "id" in msg
+                if has_method and not has_id:
+                    asyncio.create_task(_handle_event_notification(msg, _monitor))
+                elif has_method and has_id:
+                    asyncio.create_task(_handle_rpc_request(ws, msg, _monitor))
+                elif has_id and not has_method:
+                    _handle_rpc_response(msg)
+            except Exception as e:
+                print(f"[watchdog] Slot {slot} 消息处理异常（已忽略）: {e}")
+    except Exception:
+        pass
+    finally:
+        _extra_ws.pop(slot, None)
+        _extra_ws_tasks.pop(slot, None)
+
+
+async def _handle_connection_release(data):
+    """Kernel 请求释放 slot，优雅关闭。"""
+    for slot in data.get("slots", []):
+        ws = _extra_ws.pop(slot, None)
+        task = _extra_ws_tasks.pop(slot, None)
+        if ws:
+            try:
+                await ws.close(code=1000, reason="release")
+            except Exception:
+                pass
+        if task:
+            task.cancel()
+
+
+async def _handle_shutdown(monitor: HealthMonitor):
+    """Handle module.shutdown event — ack → exiting → cleanup → ready → exit."""
+    global _shutting_down
+    print("[watchdog] Received shutdown request")
+    _shutting_down = True
+    # Step 1: Send ack (立即确认收到)
+    await _publish_event(_ws_global, "module.shutdown.ack", {
+        "module_id": "watchdog",
+    })
+    # Step 2: Send module.exiting (开始清理)
+    await _publish_event(_ws_global, "module.exiting", {
+        "module_id": "watchdog",
+        "type": "passive",
+        "reason": "shutdown_requested",
+        "restart": "auto",
+        "action": "none",
+        "timeout": 2.0,
+        "restart_delay": 0.0,
+    })
+    # Step 3: Cleanup
+    monitor.stop()
+    # 关闭所有附加连接
+    for _s, _w in list(_extra_ws.items()):
+        try:
+            await _w.close(code=1000, reason="shutdown")
+        except Exception:
+            pass
+    for _t in _extra_ws_tasks.values():
+        _t.cancel()
+    _extra_ws.clear()
+    _extra_ws_tasks.clear()
+    # Step 4: Send ready (清理完成)
+    await _publish_event(_ws_global, "module.shutdown.ready", {
+        "module_id": "watchdog",
+    })
+    print("[watchdog] Shutdown ready, exiting")
+
+    # 等待 Kernel 处理 shutdown.ready（防止 Close 帧抢先）
+    await asyncio.sleep(0.1)
+
+    # Step 5: Close WebSocket connection gracefully
+    if _ws_global:
+        try:
+            await _ws_global.close(code=1000, reason="Graceful shutdown")
+            print("[watchdog] WebSocket closed")
+        except Exception as e:
+            print(f"[watchdog] Failed to close WebSocket: {e}")
+
+    # Note: Do NOT call sys.exit() in async context
+    # Let the event loop naturally complete
+
+
+def _init_logs(log_base_dir: str = None, suffix: str = ""):
+    """初始化日志系统（本地/远程共用）。"""
+    global _log_dir, _log_latest_path, _crash_log_path
+
+    if log_base_dir:
+        _log_dir = os.path.join(log_base_dir, "log")
+        os.makedirs(_log_dir, exist_ok=True)
+        _log_latest_path = os.path.join(_log_dir, f"latest{suffix}.log")
+        try:
+            with open(_log_latest_path, "w", encoding="utf-8") as f: pass
+        except Exception: _log_latest_path = None
+        _crash_log_path = os.path.join(_log_dir, f"crashes{suffix}.jsonl")
+        try:
+            with open(_crash_log_path, "w", encoding="utf-8") as f: pass
+        except Exception: _crash_log_path = None
+        _resolve_daily_log_path()
+
+    _setup_exception_hooks()
+
+
+def _run_local_mode(kernel_port: int):
+    """本地模式：从 stdin 读 boot_info，连接 Kernel。"""
+    module_data = os.environ.get("KITE_MODULE_DATA")
+    suffix = os.environ.get("KITE_INSTANCE_SUFFIX", "")
+    _init_logs(log_base_dir=module_data, suffix=suffix)
+
+    _t0 = time.monotonic()
+    line = sys.stdin.readline().strip()
+    if not line:
+        print(f"[{MODULE_NAME}] ERROR: stdin closed"); sys.exit(1)
+    try: msg = json.loads(line)
+    except json.JSONDecodeError as e:
+        print(f"[{MODULE_NAME}] ERROR: Invalid JSON: {e}"); sys.exit(1)
+    if "error" in msg:
+        print(f"[{MODULE_NAME}] 启动失败: {msg.get('message')}"); sys.exit(1)
+    token = msg.get("token", "")
+    if not token:
+        print(f"[{MODULE_NAME}] ERROR: No token"); sys.exit(1)
+
+    print(f"[{MODULE_NAME}] Local mode: port={kernel_port}")
+    try:
+        asyncio.run(_main_with_monitor(token, kernel_port, _t0))
+    except (ConnectionRefusedError, ConnectionResetError):
+        # Kernel 已关闭，正常退出
+        print(f"[{MODULE_NAME}] Kernel 不可达，正常退出")
+        sys.exit(0)
+    except Exception as e:
+        _write_crash(type(e), e, e.__traceback__, severity="critical", handled=True)
+        _print_crash_summary(type(e), e.__traceback__)
+        sys.exit(1)
+    sys.exit(_exit_code)
+
+
+def _run_remote_mode(gateway_url: str):
+    """远程模式：通过 Gateway 连接 Kernel。"""
+    home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    data_dir = os.path.join(home, ".kite", "remote", MODULE_NAME)
+    os.makedirs(data_dir, exist_ok=True)
+    _init_logs(log_base_dir=data_dir)
+
+    _t0 = time.monotonic()
+    kite_token = _get_kite_token(MODULE_NAME, gateway_url)
+    print(f"[{MODULE_NAME}] Remote mode: gateway={gateway_url}")
+
+    try:
+        asyncio.run(_remote_ws_loop(gateway_url, kite_token, _t0))
+    except Exception as e:
+        _write_crash(type(e), e, e.__traceback__, severity="critical", handled=True)
+        _print_crash_summary(type(e), e.__traceback__)
+        sys.exit(1)
+    sys.exit(_exit_code)
+
+
+async def _remote_ws_loop(gateway_url: str, kite_token: str, _t0: float):
+    """远程模式重连循环。"""
+    global _shutting_down, _exit_code, _monitor
+    retry_delay = 0.5
+    max_delay = 10.0
+
+    # Create monitor for remote mode (no own_token / kernel_port needed for remote)
+    _monitor = HealthMonitor(own_token="", kernel_port=0)
+
+    def _request_exit(code: int = 0):
+        global _shutting_down, _exit_code
+        _exit_code = code
+        _shutting_down = True
+        if _ws_global:
+            asyncio.ensure_future(_ws_global.close(code=1000, reason="Monitor requested exit"))
+    _monitor.request_exit = _request_exit
+
+    while not _shutting_down:
+        try:
+            await _remote_connect(gateway_url, kite_token, _t0)
+            retry_delay = 0.5
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            if _shutting_down: return
+            _write_crash(type(e), e, e.__traceback__, severity="error", handled=True)
+            jitter = retry_delay * 0.2 * random.random()
+            print(f"[{MODULE_NAME}] 远程连接错误: {e}, {retry_delay + jitter:.1f}s 后重试")
+            await asyncio.sleep(retry_delay + jitter)
+            retry_delay = min(retry_delay * 2, max_delay)
+
+        _ws_global_clear()
+        if _shutting_down: return
+
+
+async def _remote_connect(gateway_url: str, kite_token: str, _t0: float):
+    """远程模式：连接 Gateway 并走认证+注册流程。"""
+    global _ws_global, _monitor_task
+
+    print(f"[{MODULE_NAME}] Connecting to Gateway: {gateway_url}")
+    async with websockets.connect(gateway_url, open_timeout=10, ping_interval=None, close_timeout=10) as ws:
+        # 1. 接收 challenge
+        challenge = json.loads(await asyncio.wait_for(ws.recv(), timeout=10))
+        nonce = challenge.get("params", {}).get("nonce", "")
+
+        # 2. 发送 auth.connect
+        await ws.send(json.dumps({
+            "jsonrpc": "2.0", "id": "auth-connect",
+            "method": "auth.connect",
+            "params": {
+                "nonce": nonce,
+                "module_id": MODULE_NAME,
+                "auth": {"method": "kite_token", "token": kite_token},
+                "client": {"type": "module"}
+            }
+        }))
+
+        # 3. 等待认证响应
+        resp = json.loads(await asyncio.wait_for(ws.recv(), timeout=10))
+        if "error" in resp:
+            error = resp["error"]
+            code = error.get("code", 0)
+            if code in (4001, 4010, 4011):
+                _clear_token_cache(MODULE_NAME, gateway_url)
+                print(f"[{MODULE_NAME}] Token 无效，请重新配对")
+                sys.exit(1)
+            raise Exception(f"Gateway 认证失败: {error}")
+
+        _ws_global = ws
+        print(f"[{MODULE_NAME}] Connected via Gateway ({_fmt_elapsed(_t0)})")
+
+        # 启动接收循环（先于 RPC 调用，防止 wait_response 死锁）
+        receiver_task = asyncio.create_task(_ws_receiver(ws, _monitor))
+
+        try:
+            # 4. 订阅事件
+            await _rpc_call(ws, "event.subscribe", {
+                "events": [
+                    "system.ready",
+                    "module.started",
+                    "module.stopped",
+                    "module.exiting",
+                    "module.ready",
+                    "module.shutdown",
+                    "module.offline",
+                    "module.degraded",
+                    "module.recovered",
+                ],
+            })
+
+            # 5. 注册
+            await _rpc_call(ws, "registry.register", {
+                "module_id": "watchdog",
+                "module_type": "service",
+                "tools": {
+                    "rpc": {
+                        "module": {
+                            "health": {"method": "health", "description": "健康检查"},
+                            "status": {"method": "status", "description": "状态查询"},
+                            "start_monitor": {"method": "start_monitor", "description": "开启监控（由 Launcher 调用）"},
+                            "stop_monitor": {"method": "stop_monitor", "description": "关闭监控（由 Launcher 调用）"},
+                            "health_events": {"method": "health_events", "description": "查询健康事件记录"},
+                        }
+                    }
+                },
+                "events_publish": {
+                    "watchdog": {
+                        "module": {
+                            "unhealthy": {"description": "模块不健康"},
+                            "recovered": {"description": "模块恢复"},
+                            "resource_critical": {"description": "资源严重不足"},
+                            "resource_warning": {"description": "资源警告"},
+                            "resource_recovered": {"description": "资源恢复正常"},
+                            "degraded_timeout": {"description": "模块超长降级告警"},
+                        },
+                        "alert": {"description": "监控告警"}
+                    }
+                },
+                "events_subscribe": [
+                    "system.ready",
+                    "module.started",
+                    "module.stopped",
+                    "module.exiting",
+                    "module.ready",
+                    "module.shutdown",
+                    "module.offline",
+                    "module.degraded",
+                    "module.recovered",
+                ],
+            })
+            print(f"[{MODULE_NAME}] Registered via Gateway ({_fmt_elapsed(_t0)})")
+
+            # Set up monitor callbacks (reconnect-safe)
+            _monitor.publish_event = lambda event: asyncio.create_task(
+                _publish_event(ws, event.get("event", ""), event.get("data", {}))
+            )
+            _monitor.rpc_call = lambda method, params: _rpc_call(ws, method, params)
+            _monitor.rpc_call_kernel = lambda method, params: _rpc_call(ws, method, params)
+
+            # 6. module.ready
+            if not _shutting_down:
+                await _publish_event(ws, "module.ready", {
+                    "module_id": "watchdog",
+                    "graceful_shutdown": True,
+                    "startup_time": time.monotonic() - _t0,
+                })
+                print(f"[{MODULE_NAME}] module.ready via Gateway ({_fmt_elapsed(_t0)})")
+
+            # Start monitor loop if not already running
+            if _monitor_task is None or _monitor_task.done():
+                _monitor_task = asyncio.create_task(_monitor.run())
+
+            # 等待接收循环结束（连接关闭时自然退出）
+            await receiver_task
+        finally:
+            receiver_task.cancel()
+
+
+# ── Token 管理（远程模式）──
+
+def _gateway_to_filename(gateway_url: str) -> str:
+    try:
+        from urllib.parse import urlparse
+        parsed = urlparse(gateway_url)
+        host = parsed.hostname or "unknown"
+        port = parsed.port or (443 if parsed.scheme == "wss" else 80)
+        return f"{host}-{port}.json".replace(":", "-").replace("/", "-")
+    except Exception: return "default.json"
+
+def _load_token_cache(module_name: str, gateway_url: str) -> dict | None:
+    home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    token_file = os.path.join(home, ".kite", "remote", module_name, "tokens", _gateway_to_filename(gateway_url))
+    if not os.path.exists(token_file): return None
+    try:
+        with open(token_file, "r") as f: return json.load(f)
+    except Exception: return None
+
+def _clear_token_cache(module_name: str, gateway_url: str):
+    home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    token_file = os.path.join(home, ".kite", "remote", module_name, "tokens", _gateway_to_filename(gateway_url))
+    try: os.remove(token_file)
+    except Exception: pass
+
+def _get_kite_token(module_name: str, gateway_url: str) -> str:
+    token = os.environ.get("KITE_TOKEN")
+    if token: return token
+    cache = _load_token_cache(module_name, gateway_url)
+    if cache: return cache["token"]
+    print(f"[{module_name}] No token for {gateway_url}")
+    print(f"  export KITE_TOKEN=<token>")
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    kernel_port = os.environ.get("KITE_KERNEL_PORT")
+    if kernel_port:
+        _run_local_mode(int(kernel_port))
+    else:
+        config = _load_module_config()
+        gateway_url = config.get("gateway_url") or os.environ.get("KITE_GATEWAY_URL")
+        if gateway_url:
+            _run_remote_mode(gateway_url)
+        else:
+            print(f"[{MODULE_NAME}] ERROR: No KITE_KERNEL_PORT and no gateway_url")
+            sys.exit(1)
+