@agentunion/kite 1.0.7 → 1.3.0

package/launcher/entry.py

@@ -0,0 +1,1778 @@
+"""
+Launcher — the core of Kite. Manages module lifecycle, monitors processes.
+
+Thread model:
+- Main thread: asyncio event loop (process management + monitor loop)
+- stdout threads: one daemon thread per child process (ProcessManager)
+- (Windows) keyboard listener thread: polls for 'q' key
+
+2-Phase startup:
+  Phase 1: Start Kernel → wait port → connect WS → register self → module.ready
+  Phase 2: start remaining enabled modules in topo order (each connects to Kernel WS)
+"""
+
+import asyncio
+import json
+import os
+import secrets
+import signal
+import sys
+import threading
+import time
+import uuid
+
+import websockets
+
+from .module_scanner import ModuleScanner, ModuleInfo, LaunchConfig, _parse_frontmatter
+from .process_manager import ProcessManager
+
+IS_WINDOWS = sys.platform == "win32"
+
+# Shutdown timeout constants (seconds)
+SHUTDOWN_TIMEOUT_NON_GRACEFUL = 5  # Non-graceful modules or no ack response
+SHUTDOWN_TIMEOUT_PARTIAL = 3       # Graceful module ack'd but no ready
+SHUTDOWN_TIMEOUT_READY = 1         # Graceful module sent ready (cleanup done)
+SHUTDOWN_TIMEOUT_BULK = 3          # Bulk stop_all() safety net
+
+# Core module names that are started in Phase 1 (not Phase 2)
+CORE_MODULE_NAMES = {"kernel"}
+
+WATCHDOG_MODULE_NAME = "watchdog"
+
+
+class Launcher:
+    """Kite system entry point. Starts Kernel, manages modules."""
+
+    def __init__(self, kite_token: str):
+        self.kite_token = kite_token
+        self.instance_id = str(os.getpid())
+        os.environ["KITE_INSTANCE"] = self.instance_id
+
+        # Resolve instance workspace (must happen before ProcessManager init)
+        self._resolve_instance_dir()
+        os.environ["KITE_MODULE_DATA"] = os.path.join(
+            os.environ["KITE_INSTANCE_DIR"], "launcher",
+        )
+
+        self.process_manager = ProcessManager(
+            kite_token, self.instance_id,
+            on_kite_message=self._on_kite_message,
+        )
+        self.module_scanner = ModuleScanner(
+            discovery=self._load_discovery(),
+        )
+
+        self.kernel_port: int = 0
+        self.modules: dict[str, ModuleInfo] = {}
+        self._shutdown_event = asyncio.Event()
+        self._thread_shutdown = threading.Event()
+        self._shutdown_complete = threading.Event()  # Set when normal shutdown finishes
+        self._module_tokens: dict[str, str] = {}  # module_name -> per-module token
+
+        # Three-layer state model: desired_state per module
+        self._desired_states: dict[str, str] = {}  # module_name -> "running" | "stopped"
+
+        # Kernel WebSocket client
+        self._ws: object | None = None
+        self._ws_task: asyncio.Task | None = None
+        self._ws_connected: asyncio.Event | None = None  # Created in _async_main, set when WS ready
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+        # JSON-RPC 2.0 infrastructure
+        self._rpc_waiters: dict[str, asyncio.Event] = {}   # rpc_id -> Event
+        self._rpc_results: dict[str, dict] = {}             # rpc_id -> response dict
+
+        # Event waiters: {event_key: (asyncio.Event, data_dict)}
+        self._event_waiters: dict[str, tuple[asyncio.Event, dict]] = {}
+
+        # Module ready times: module_name -> seconds from start to ready
+        self._ready_times: dict[str, float] = {}
+
+        # Shutdown timing
+        self._shutdown_start_time: float = 0.0
+
+        # Module exit reasons: module_name -> reason string (for modules that sent module.exiting)
+        self._exit_reasons: dict[str, str] = {}
+
+        # Graceful shutdown capability: module_name -> True if module declared support
+        # Kernel defaults to True (it starts before Watchdog can observe)
+        self._graceful_modules: dict[str, bool] = {"kernel": True}
+
+        # System-wide shutdown flag: prevents Watchdog restart during shutdown
+        self._system_shutting_down = False
+
+        # Kite stdout message waiters: {waiter_key: (threading.Event, data_dict)}
+        # Used by ProcessManager stdout callback (cross-thread)
+        self._msg_waiters: dict[str, tuple[threading.Event, dict]] = {}
+
+        suffix = self.process_manager.instance_suffix
+        state_dir = os.path.join(os.environ["KITE_INSTANCE_DIR"], "launcher", "state")
+        os.makedirs(state_dir, exist_ok=True)
+        self._lifecycle_log = os.path.join(state_dir, f"lifecycle{suffix}.jsonl")
+        # Clear lifecycle log on startup (like latest.log)
+        try:
+            with open(self._lifecycle_log, "w", encoding="utf-8") as f:
+                pass
+        except Exception:
+            pass
+        os.environ["KITE_INSTANCE_SUFFIX"] = suffix
+
+    @staticmethod
+    def _fmt_elapsed(seconds: float) -> str:
+        """Format elapsed seconds: <1s → 'NNNms', >=1s → 'N.Ns', >=10s → 'NNs'."""
+        if seconds < 1:
+            return f"{seconds * 1000:.0f}ms"
+        if seconds < 10:
+            return f"{seconds:.1f}s"
+        return f"{seconds:.0f}s"
+
+    # ── Instance workspace resolution ──
+
+    @staticmethod
+    def _resolve_instance_dir():
+        """Resolve KITE_INSTANCE_DIR from KITE_WORKSPACE + KITE_CWD.
+        Algorithm: take CWD basename, find matching dir in workspace via .cwd file,
+        or create new one. Sets KITE_INSTANCE_DIR env var.
+        """
+        if os.environ.get("KITE_INSTANCE_DIR"):
+            return  # already set (e.g. by tests or parent)
+
+        cwd = os.environ.get("KITE_CWD", os.getcwd())
+        workspace = os.environ.get("KITE_WORKSPACE", "")
+        if not workspace:
+            home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
+            workspace = os.path.join(home, ".kite", "workspace")
+            os.environ["KITE_WORKSPACE"] = workspace
+
+        basename = os.path.basename(cwd.rstrip(os.sep)) or "default"
+        suffix = 0
+
+        while True:
+            name = basename if suffix == 0 else f"{basename}~{suffix}"
+            candidate = os.path.join(workspace, name)
+            cwd_file = os.path.join(candidate, ".cwd")
+
+            if not os.path.exists(candidate):
+                # Empty slot — create new workspace
+                os.makedirs(candidate, exist_ok=True)
+                with open(cwd_file, "w", encoding="utf-8") as f:
+                    f.write(cwd)
+                os.environ["KITE_INSTANCE_DIR"] = candidate
+                return
+
+            if os.path.isfile(cwd_file):
+                try:
+                    with open(cwd_file, "r", encoding="utf-8") as f:
+                        if f.read().strip() == cwd:
+                            os.environ["KITE_INSTANCE_DIR"] = candidate
+                            return
+                except Exception:
+                    pass
+
+            suffix += 1
+
+    # ── Kite stdout message callback ──
+
+    def _on_kite_message(self, module_name: str, msg: dict):
+        """Called by ProcessManager stdout reader thread when a kite message is detected.
+        Thread-safe: only touches _msg_waiters (dict + threading.Event).
+        """
+        kite_type = msg.get("kite", "")
+        key = f"{module_name}:{kite_type}"
+        waiter = self._msg_waiters.get(key)
+        if waiter:
+            waiter[1].update(msg)
+            waiter[0].set()
+
+    async def _wait_kite_message(self, module_name: str, kite_type: str,
+                                  timeout: float) -> dict | None:
+        """Wait for a kite stdout message from a module. Returns msg dict or None on timeout.
+        Checks shutdown flag every 0.5s so Ctrl+C is responsive even during Phase 1-2 waits.
+        """
+        key = f"{module_name}:{kite_type}"
+        evt = threading.Event()
+        data = {}
+        self._msg_waiters[key] = (evt, data)
+        shutdown = self._thread_shutdown
+        try:
+            def _wait():
+                deadline = time.monotonic() + timeout
+                while time.monotonic() < deadline:
+                    if evt.wait(timeout=0.5):
+                        return True
+                    if shutdown.is_set():
+                        return False
+                return False
+            got = await asyncio.get_running_loop().run_in_executor(None, _wait)
+            return data if got else None
+        finally:
+            self._msg_waiters.pop(key, None)
+
+    # ── Public entry ──
+
+    def run(self):
+        """Synchronous entry point. Sets up signals, runs the async main loop."""
+        print("[launcher] ── 环境 ──")
+        for key in sorted(k for k in os.environ if k.startswith("KITE_")):
+            print(f"[launcher]   {key} = {os.environ[key]}")
+        print(f"[launcher]   PID = {os.getpid()}")
+        print(f"[launcher]   PYTHON = {sys.executable}")
+        print(f"[launcher]   PLATFORM = {sys.platform}")
+
+        if IS_WINDOWS:
+            self._setup_windows_exit()
+        else:
+            self._setup_unix_signals()
+
+        try:
+            asyncio.run(self._async_main())
+        except KeyboardInterrupt:
+            pass
+        except RuntimeError as e:
+            # Don't print "启动失败" if user requested shutdown
+            if not self._thread_shutdown.is_set():
+                print(f"[launcher] 启动失败: {e}")
+        finally:
+            self._final_cleanup()
+
+    def _request_shutdown(self, reason: str = ""):
+        """Request graceful shutdown. Thread-safe — can be called from signal handler or any thread."""
+        if self._thread_shutdown.is_set():
+            return  # already shutting down
+        print(f"[launcher] {reason or '收到关闭请求'}")
+        self._shutdown_start_time = time.monotonic()  # Record shutdown start time
+        self._thread_shutdown.set()
+        # Wake up asyncio event loop immediately (so _monitor_loop / wait_for exits)
+        loop = self._loop
+        if loop and not loop.is_closed():
+            try:
+                loop.call_soon_threadsafe(self._shutdown_event.set)
+            except RuntimeError:
+                pass
+        # Safety net: force exit after 10s only if normal shutdown hasn't completed
+        def _force():
+            if self._shutdown_complete.wait(timeout=10):
+                return  # Normal shutdown completed — no need to force
+            try:
+                pm = self.process_manager
+                still = [n for n in pm._processes if pm.is_running(n)]
+            except Exception:
+                still = []
+            if still:
+                print(f"\033[91m[launcher] 关闭超时，以下模块仍在运行: {', '.join(still)}，强制退出\033[0m")
+            else:
+                print("\033[91m[launcher] 关闭超时，强制退出\033[0m")
+            os._exit(1)
+        threading.Thread(target=_force, daemon=True).start()
+
+    def _setup_unix_signals(self):
+        """Register SIGTERM/SIGINT handlers on Linux/macOS."""
+        def _handler(signum, frame):
+            self._request_shutdown(f"收到信号 {signum}，正在关闭...")
+        signal.signal(signal.SIGTERM, _handler)
+        signal.signal(signal.SIGINT, _handler)
+
+    def _setup_windows_exit(self):
+        """SetConsoleCtrlHandler for Ctrl+C + daemon thread for 'q' key.
+
+        Why not signal.signal(SIGINT)?
+        Python's signal delivery requires the main thread to be executing bytecode.
+        When the main thread is blocked in C code (asyncio ProactorEventLoop →
+        GetQueuedCompletionStatus), SIGINT is never delivered.
+        SetConsoleCtrlHandler runs its callback in a separate OS thread, so it
+        always works regardless of what the main thread is doing.
+        """
+        import ctypes
+
+        @ctypes.WINFUNCTYPE(ctypes.c_int, ctypes.c_uint)
+        def _ctrl_handler(ctrl_type):
+            if ctrl_type in (0, 1):  # CTRL_C_EVENT, CTRL_BREAK_EVENT
+                self._request_shutdown("收到 Ctrl+C，正在关闭...")
+                return 1  # handled — prevent default (which kills the process)
+            return 0
+
+        # prevent GC of the C callback
+        self._ctrl_handler_ref = _ctrl_handler
+        ctypes.windll.kernel32.SetConsoleCtrlHandler(_ctrl_handler, 1)
+
+        # 'q' key: handle via msvcrt polling
+        def _listen():
+            import msvcrt
+            while not self._thread_shutdown.is_set():
+                if msvcrt.kbhit():
+                    ch = msvcrt.getch()
+                    if ch == b'\x1b':  # ESC - force exit immediately
+                        print("[launcher] ESC 强制退出")
+                        os._exit(0)
+                    elif ch in (b'q', b'Q'):  # q/Q - graceful shutdown
+                        self._request_shutdown("收到退出请求，正在关闭...")
+                        return
+                time.sleep(0.1)
+        threading.Thread(target=_listen, daemon=True).start()
+
+    # ── Async main (2-Phase startup) ──
+
+    async def _async_main(self):
+        """Full 2-phase startup sequence, then monitor loop."""
+        self._loop = asyncio.get_running_loop()
+        self._ws_connected = asyncio.Event()  # Create event in async context
+        t_start = time.monotonic()
+        self._start_unix = time.time()
+        phase_times = {}
+        G = "\033[32m"
+        R = "\033[0m"
+
+        # Validate core modules exist
+        self._validate_core_modules()
+
+        # Cleanup leftovers from previous instances (current instance dir)
+        local_cleaned = self.process_manager.cleanup_leftovers()
+
+        # Cross-directory leftover cleanup (background, non-blocking)
+        self._global_cleanup_task = asyncio.ensure_future(
+            asyncio.get_running_loop().run_in_executor(
+                None, self.process_manager.cleanup_global_leftovers
+            )
+        )
+
+        try:
+            # Phase 1: Start Kernel + connect WS
+            t0 = time.monotonic()
+            await self._phase1_start_kernel()
+            elapsed_p1 = time.monotonic() - t0
+            phase_times["Phase 1: Kernel"] = elapsed_p1
+            print(f"{G}[launcher] ✓ Phase 1 完成: Kernel 已就绪 ({elapsed_p1:.2f}s){R}")
+            if self._shutdown_event.is_set(): return
+
+            # Initialize desired_state from config_state
+            for name, info in self.modules.items():
+                if info.state == "enabled":
+                    self._desired_states[name] = "running"
+                else:  # manual, disabled
+                    self._desired_states[name] = "stopped"
+            # Core modules are already running
+            for cn in CORE_MODULE_NAMES:
+                self._desired_states[cn] = "running"
+
+            # Phase 1.5: Watchdog
+            watchdog_info = self.modules.get(WATCHDOG_MODULE_NAME)
+            if watchdog_info and self._desired_states.get(WATCHDOG_MODULE_NAME) == "running":
+                t0 = time.monotonic()
+                print(f"[launcher] Phase 1.5: 启动 Watchdog...")
+                await self._start_one_module(watchdog_info)
+                elapsed = time.monotonic() - t0
+                print(f"{G}[launcher] ✓ Phase 1.5 完成: Watchdog ({elapsed:.2f}s){R}")
+                if self._shutdown_event.is_set(): return
+
+            # Phase 2: Start remaining enabled modules
+            t0 = time.monotonic()
+            await self._phase2_start_modules()
+            elapsed = time.monotonic() - t0
+            phase_times["Phase 2: Extensions"] = elapsed
+            print(f"{G}[launcher] ✓ Phase 2 完成: 扩展模块已启动 ({elapsed:.2f}s){R}")
+            if self._shutdown_event.is_set(): return
+
+            # Post-startup
+            self.process_manager.persist_records()
+
+            # Wait for global leftover cleanup to finish (non-blocking with timeout)
+            global_cleaned = {}
+            if hasattr(self, '_global_cleanup_task'):
+                try:
+                    global_cleaned = await asyncio.wait_for(self._global_cleanup_task, timeout=5) or {}
+                except asyncio.TimeoutError:
+                    print("[launcher] 警告: 全局遗留清理超时 (5s)，跳过")
+                except Exception as e:
+                    print(f"[launcher] 警告: 全局遗留清理出错: {e}")
+            # Merge local + global cleanup stats
+            cleaned_stats: dict[str, int] = {}
+            for d in (local_cleaned, global_cleaned):
+                for k, v in d.items():
+                    cleaned_stats[k] = cleaned_stats.get(k, 0) + v
+
+            # Global instance scan (via executor to avoid blocking)
+            global_instances = await asyncio.get_running_loop().run_in_executor(
+                None, self.process_manager.get_global_instances
+            )
+
+            # ── Startup report ──
+            total_time = time.monotonic() - t_start
+            await self._print_startup_report(total_time, phase_times,
+                                             global_instances=global_instances,
+                                             cleaned_stats=cleaned_stats)
+            # Notify all modules that system startup is complete
+            await self._publish_event("system.ready", {
+                "startup_time": round(total_time, 2),
+            })
+
+            print("[launcher] 进入监控循环 (按 Ctrl+C 或 'q' 优雅退出，ESC 强制退出)")
+            await self._monitor_loop()
+        finally:
+            try:
+                await self._graceful_shutdown_all()
+            except Exception as e:
+                print(f"[launcher] 优雅关闭出错: {e}")
+
+    # ── Phase 1: Start Kernel ──
+
+    async def _phase1_start_kernel(self):
+        """Start Kernel process, connect WS, register self, wait for module.ready.
+
+        Flow:
+        1. Start Kernel subprocess
+        2. Wait Kernel stdout port → set KITE_KERNEL_PORT env
+        3. Scan modules + connect WS + generate tokens (parallel)
+        4. Wait module.ready event from Kernel
+        """
+        t_kernel = time.monotonic()
+
+        # ── Step 1: Start Kernel process ──
+        kernel_dir = os.path.join(os.environ["KITE_PROJECT"], "kernel")
+        kernel_info = ModuleInfo(
+            name="kernel",
+            display_name="Kernel",
+            type="infrastructure",
+            state="enabled",
+            runtime="python",
+            entry="entry.py",
+            module_dir=kernel_dir,
+        )
+        # Kernel does NOT receive boot_info via stdin
+        self._log_lifecycle("starting", "kernel")
+        ok = self.process_manager.start_module(kernel_info, boot_info=None)
+        if not ok:
+            self._log_lifecycle("start_failed", "kernel")
+            raise RuntimeError("启动 Kernel 失败")
+
+        print(f"[launcher] Kernel 进程已启动，等待 Kernel 端口...")
+
+        # Persist immediately after starting core processes
+        self.process_manager.persist_records()
+
+        # ── Step 2: Wait for Kernel port + launcher_token ──
+        msg = await self._wait_kite_message("kernel", "port", timeout=6)
+        if self._thread_shutdown.is_set():
+            # User requested shutdown during startup
+            raise RuntimeError("启动被用户中断")
+        if not msg or not msg.get("port") or not msg.get("token"):
+            raise RuntimeError("致命错误: Kernel 在 6s 内未报告端口和 token")
+        self.kernel_port = int(msg["port"])
+        launcher_token = msg["token"]
+        self._module_tokens["launcher"] = launcher_token
+        _wait_s = time.monotonic() - t_kernel
+        print(f"[launcher] Kernel 端口: {self.kernel_port} (等待 {self._fmt_elapsed(_wait_s)})")
+
+        # ── Step 3: Set env (but don't send kernel_port to modules yet) ──
+        os.environ["KITE_KERNEL_PORT"] = str(self.kernel_port)
+
+        # ── Step 4: Scan modules + connect WS + generate tokens (parallel) ──
+        async def _scan_and_generate_tokens():
+            t_scan = time.monotonic()
+            self.modules = self.module_scanner.scan()
+            for name, info in self.modules.items():
+                self._log_lifecycle("scanned", name, state=info.state, module_dir=info.module_dir)
+            _scan_s = time.monotonic() - t_scan
+            print(f"[launcher] 发现 {len(self.modules)} 个模块: {', '.join(self.modules.keys()) or '(无)'} (扫描 {self._fmt_elapsed(_scan_s)})")
+            # Generate tokens via Kernel RPC (after WS connection is ready)
+            t_gen = time.monotonic()
+            await self._generate_module_tokens()
+            _gen_s = time.monotonic() - t_gen
+            print(f"[launcher] 令牌生成完成 ({self._fmt_elapsed(_gen_s)})")
+
+        async def _connect_kernel_ws():
+            t_ws = time.monotonic()
+            self._ws_task = asyncio.create_task(self._ws_loop())
+            # Wait for WebSocket connection to be established and ready
+            try:
+                await asyncio.wait_for(self._ws_connected.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                print("[launcher] 警告: WebSocket 连接超时")
+                return
+
+            # Now wait for Kernel module.ready event
+            # (waiter is registered inside _ws_connect before _ws_receiver starts)
+            ready = await self._wait_event("module.ready", "kernel", timeout=15)
+            if ready:
+                self._graceful_modules["kernel"] = bool(ready.get("graceful_shutdown"))
+                print("[launcher] Kernel 已就绪")
+            else:
+                print("\033[91m[launcher] 警告: Kernel 在 15s 内未发送 module.ready\033[0m")
+            self._ready_times["kernel"] = time.monotonic() - t_ws
+
+        await asyncio.gather(
+            _scan_and_generate_tokens(),
+            _connect_kernel_ws(),
+        )
+        if self._shutdown_event.is_set():
+            return
+
+        self._log_lifecycle("started", "kernel")
+        await self._publish_event("module.started", {"module_id": "kernel"})
+        self.process_manager.close_stdio("kernel")
+
+        # Store kernel_info in modules dict if not already present (from scan)
+        if "kernel" not in self.modules:
+            self.modules["kernel"] = kernel_info
+
+    # ── Phase 2: Start remaining modules ──
+
+    async def _phase2_start_modules(self):
+        """Start enabled modules (excluding core) in dependency order."""
+        to_start = [m for m in self.modules.values()
+                     if self._desired_states.get(m.name) == "running"
+                     and m.name not in CORE_MODULE_NAMES
+                     and m.name != WATCHDOG_MODULE_NAME]
+        if not to_start:
+            print("[launcher] 没有额外模块需要启动")
+            return
+
+        # Auto-start manual modules if depended upon
+        needed = set(m.name for m in to_start)
+        for m in list(to_start):
+            for dep in m.depends_on:
+                if dep not in needed and dep not in CORE_MODULE_NAMES:
+                    dep_info = self.modules.get(dep)
+                    if dep_info and dep_info.state != "disabled":
+                        needed.add(dep)
+                        to_start.append(dep_info)
+                        self._desired_states[dep] = "running"
+                        print(f"[launcher] 自动启动 '{dep}' (被依赖)")
+                    elif dep_info and dep_info.state == "disabled":
+                        print(f"[launcher] 错误: '{m.name}' 依赖已禁用的模块 '{dep}'")
+
+        try:
+            layers = self._topo_layers(to_start)
+        except RuntimeError as e:
+            print(f"[launcher] 错误: {e}")
+            return
+
+        total = sum(len(layer) for layer in layers)
+        print(f"[launcher] 正在启动 {total} 个模块...")
+        for layer in layers:
+            if len(layer) == 1:
+                await self._start_one_module(layer[0])
+            else:
+                await asyncio.gather(*(self._start_one_module(info) for info in layer))
+
+    # ── Kernel WebSocket connection (JSON-RPC 2.0) ──
+
+    async def _ws_loop(self):
+        """Connect to Kernel, reconnect on failure."""
+        while not self._thread_shutdown.is_set():
+            try:
+                await self._ws_connect()
+            except asyncio.CancelledError:
+                return
+            except Exception as e:
+                if not self._system_shutting_down:
+                    print(f"[launcher] Kernel 连接错误: {e}")
+            self._ws = None
+            await asyncio.sleep(5)
+
+    async def _ws_connect(self):
+        """Single WebSocket session with JSON-RPC 2.0 protocol."""
+        launcher_token = self._module_tokens.get("launcher", "")
+        ws_url = f"ws://127.0.0.1:{self.kernel_port}/ws?token={launcher_token}&id=launcher"
+        t_ws_connect = time.monotonic()
+        async with websockets.connect(ws_url, open_timeout=3, ping_interval=None, ping_timeout=None, close_timeout=10) as ws:
+            self._ws = ws
+            _ws_s = time.monotonic() - t_ws_connect
+            print(f"[launcher] 已连接到 Kernel ({self._fmt_elapsed(_ws_s)})")
+
+            # Start receive loop in background task BEFORE making any RPC calls
+            # This prevents deadlock where RPC waits for response but receive loop hasn't started
+            receiver_task = asyncio.create_task(self._ws_receiver(ws))
+
+            try:
+                # Register kernel module.ready waiter BEFORE subscribing to events
+                # This prevents race condition where event arrives before waiter is registered
+                ready_key = "module.ready:kernel"
+                ready_evt = asyncio.Event()
+                ready_data = {}
+                self._event_waiters[ready_key] = (ready_evt, ready_data)
+
+                # Subscribe to all events
+                await self._rpc_call(ws, "event.subscribe", {"events": [">"]})
+
+                # Register Launcher itself in the Registry
+                await self._rpc_call(ws, "registry.register", {
+                    "module_id": "launcher",
+                    "module_type": "infrastructure",
+                    "events_publish": {
+                        "module.started": {},
+                        "module.stopped": {},
+                        "module.state_changed": {},
+                    },
+                    "events_subscribe": [">"],
+                })
+                print("[launcher] 已注册到 Kernel")
+
+                # Signal that connection is ready (after subscription and registration)
+                if self._ws_connected:
+                    self._ws_connected.set()
+
+                # Wait for receiver task to complete (connection closed)
+                await receiver_task
+            except asyncio.CancelledError:
+                receiver_task.cancel()
+                raise
+
+    async def _ws_receiver(self, ws):
+        """Receive loop: classify incoming messages."""
+        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
+                    has_result = "result" in msg
+                    has_error = "error" in msg
+
+                    if has_method and not has_id:
+                        # Event Notification (no id)
+                        await self._handle_event_notification(msg)
+                    elif has_method and has_id:
+                        # Incoming RPC request (forwarded by Kernel)
+                        await self._handle_rpc_request(ws, msg)
+                    elif has_id and (has_result or has_error):
+                        # RPC response (to our own call)
+                        self._handle_rpc_response(msg)
+                except Exception as e:
+                    print(f"[launcher] 消息处理异常（已忽略）: {e}")
+        except asyncio.CancelledError:
+            pass
+
+    # ── JSON-RPC 2.0 infrastructure ──
+
+    async def _rpc_call(self, ws, method: str, params: dict = None, timeout: float = 5) -> dict:
+        """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()
+        self._rpc_waiters[rpc_id] = evt
+        self._rpc_results[rpc_id] = {}
+
+        try:
+            await ws.send(json.dumps(msg))
+            await asyncio.wait_for(evt.wait(), timeout=timeout)
+            return self._rpc_results.get(rpc_id, {})
+        except asyncio.TimeoutError:
+            print(f"[launcher] RPC 超时: {method}")
+            return {"error": {"code": -32002, "message": f"RPC timeout: {method}"}}
+        finally:
+            self._rpc_waiters.pop(rpc_id, None)
+            self._rpc_results.pop(rpc_id, None)
+
+    def _handle_rpc_response(self, msg: dict):
+        """Match an incoming RPC response to a pending waiter."""
+        rpc_id = msg.get("id", "")
+        waiter = self._rpc_waiters.get(rpc_id)
+        if waiter:
+            self._rpc_results[rpc_id] = msg
+            waiter.set()
+
+    async def _handle_event_notification(self, msg: dict):
+        """Handle an event notification (JSON-RPC 2.0 Notification with method='event')."""
+        params = msg.get("params", {})
+        source = params.get("source", "unknown")
+        event = params.get("event", "")
+        data = params.get("data") if isinstance(params.get("data"), dict) else {}
+        ts = params.get("timestamp", "")
+
+        # Trigger event waiters
+        module_id = data.get("module_id", "")
+        waiter_key = f"{event}:{module_id}"
+        waiter = self._event_waiters.get(waiter_key)
+        if waiter:
+            waiter[1].update(data)
+            waiter[0].set()
+
+        # module.exiting also wakes module.ready waiter
+        if event == "module.exiting" and module_id:
+            ready_key = f"module.ready:{module_id}"
+            ready_waiter = self._event_waiters.get(ready_key)
+            if ready_waiter:
+                ready_waiter[1].update(data)
+                ready_waiter[1]["_exited"] = True
+                ready_waiter[0].set()
+
+        # module.crash → print red crash summary
+        if event == "module.crash" and module_id:
+            RED = "\033[91m"
+            RESET = "\033[0m"
+            exc_type = data.get("exception_type", "Unknown")
+            preview = data.get("traceback_preview", "")
+            print(f"[launcher] {RED}模块 '{module_id}' 崩溃: {exc_type} — {preview}{RESET}")
+            _suffix = os.environ.get("KITE_INSTANCE_SUFFIX", "")
+            crash_log = os.path.join(
+                os.environ.get("KITE_INSTANCE_DIR", ""),
+                module_id, "log", f"crashes{_suffix}.jsonl"
+            )
+            print(f"[launcher] 崩溃日志: {crash_log}")
+
+        # Only log system events (module.*, watchdog.*) to avoid flooding
+        if not (event.startswith("module.") or event.startswith("watchdog.")):
+            return
+        latency_str = ""
+        if ts:
+            try:
+                from datetime import datetime, timezone
+                sent = datetime.fromisoformat(ts)
+                delay_ms = (datetime.now(timezone.utc) - sent).total_seconds() * 1000
+                latency_str = f" ({delay_ms:.1f}ms)"
+                local_ts = sent.astimezone().strftime("%H:%M:%S")
+            except Exception:
+                local_ts = ts[11:19] if len(ts) >= 19 else ts
+            print(f"[{source}] {local_ts} {event}{latency_str}: {json.dumps(data, ensure_ascii=False)}")
+        else:
+            print(f"[{source}] {event}: {json.dumps(data, ensure_ascii=False)}")
+
+    async def _handle_rpc_request(self, ws, msg: dict):
+        """Handle an incoming RPC request forwarded by Kernel (launcher.* methods)."""
+        rpc_id = msg.get("id", "")
+        method = msg.get("method", "")
+        params = msg.get("params", {})
+
+        handlers = {
+            "list_modules":   self._rpc_list_modules,
+            "start_module":   self._rpc_start_module,
+            "stop_module":    self._rpc_stop_module,
+            "restart_module": self._rpc_restart_module,
+            "rescan":         self._rpc_rescan,
+            "shutdown":       self._rpc_shutdown,
+        }
+        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}"},
+            }))
+
+    # ── Launcher RPC method handlers ──
+
+    async def _rpc_list_modules(self, params: dict) -> dict:
+        """List all modules and their current status."""
+        result = []
+        for name, info in self.modules.items():
+            running = self.process_manager.is_running(name)
+            rec = self.process_manager.get_record(name)
+            result.append({
+                "name": name,
+                "display_name": info.display_name,
+                "type": info.type,
+                "config_state": info.state,
+                "desired_state": self._desired_states.get(name, "stopped"),
+                "actual_state": f"running({rec.pid})" if running and rec else "stopped",
+                "pid": rec.pid if running and rec else None,
+                "monitor": info.monitor,
+            })
+        return {"modules": result}
+
+    async def _rpc_start_module(self, params: dict) -> dict:
+        """Start a module by name."""
+        name = params.get("name", "")
+        info = self.modules.get(name)
+        if not info:
+            raise RuntimeError(f"Module '{name}' not found")
+        if info.state == "disabled":
+            raise RuntimeError(f"Module '{name}' is disabled")
+
+        if name not in self._module_tokens:
+            self._module_tokens[name] = secrets.token_hex(32)
+            await self._register_new_tokens({name: self._module_tokens[name]})
+
+        token = self._module_tokens[name]
+        boot_info = {"token": token}
+        ok = self.process_manager.start_module(info, boot_info=boot_info)
+        if ok:
+            self._desired_states[name] = "running"
+            self.process_manager.persist_records()
+            rec = self.process_manager.get_record(name)
+            self._log_lifecycle("started", name, pid=rec.pid if rec else None, via="rpc")
+            await self._publish_event("module.started", {"module_id": name})
+            return {"status": "started", "name": name}
+        self._log_lifecycle("start_failed", name, via="rpc")
+        raise RuntimeError(f"Failed to start '{name}'")
+
+    async def _rpc_stop_module(self, params: dict) -> dict:
+        """Stop a module with graceful shutdown."""
+        name = params.get("name", "")
+        info = self.modules.get(name)
+        if not info:
+            raise RuntimeError(f"Module '{name}' not found")
+        reason = params.get("reason", "stop_requested")
+        self._desired_states[name] = "stopped"
+        await self._graceful_stop(name, reason)
+        self.process_manager.persist_records()
+        return {"status": "stopped", "name": name}
+
+    async def _rpc_restart_module(self, params: dict) -> dict:
+        """Restart a module (stop + start)."""
+        name = params.get("name", "")
+        info = self.modules.get(name)
+        if not info:
+            raise RuntimeError(f"Module '{name}' not found")
+        if info.state == "disabled":
+            raise RuntimeError(f"Module '{name}' is disabled")
+        reason = params.get("reason", "restart")
+        await self._graceful_stop(name, reason)
+        self._module_tokens[name] = secrets.token_hex(32)
+        await self._register_new_tokens({name: self._module_tokens[name]})
+        token = self._module_tokens[name]
+        boot_info = {"token": token}
+        ok = self.process_manager.start_module(info, boot_info=boot_info)
+        if ok:
+            self._desired_states[name] = "running"
+            self.process_manager.persist_records()
+            rec = self.process_manager.get_record(name)
+            self._log_lifecycle("started", name, pid=rec.pid if rec else None, via="rpc_restart")
+            await self._publish_event("module.started", {"module_id": name})
+            return {"status": "restarted", "name": name}
+        self._log_lifecycle("start_failed", name, via="rpc_restart")
+        raise RuntimeError(f"Failed to restart '{name}'")
+
+    async def _rpc_rescan(self, params: dict) -> dict:
+        """Rescan module directories for new/removed modules."""
+        old_names = set(self.modules.keys())
+        self.modules = self.module_scanner.scan()
+        new_names = set(self.modules.keys())
+        added = list(new_names - old_names)
+        removed = list(old_names - new_names)
+        for name in added:
+            info = self.modules[name]
+            self._log_lifecycle("scanned", name, state=info.state, module_dir=info.module_dir)
+            self._desired_states[name] = "running" if info.state == "enabled" else "stopped"
+        if added:
+            new_tokens = {}
+            for name in added:
+                self._module_tokens[name] = secrets.token_hex(32)
+                new_tokens[name] = self._module_tokens[name]
+            await self._register_new_tokens(new_tokens)
+        return {"added": added, "removed": removed, "total": len(self.modules)}
+
+    async def _rpc_shutdown(self, params: dict) -> dict:
+        """Shutdown the entire Kite system."""
+        reason = params.get("reason", "rpc_request")
+        self._request_shutdown(f"RPC shutdown request: {reason}")
+        return {"status": "shutting_down", "reason": reason}
+
+    # ── Event publishing via RPC ──
+
+    async def _publish_event(self, event_type: str, data: dict):
+        """Publish an event via RPC event.publish through Kernel WS."""
+        if not self._ws:
+            return
+        msg = json.dumps({
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": "event.publish",
+            "params": {
+                "event_id": str(uuid.uuid4()),
+                "event": event_type,
+                "data": data,
+            },
+        })
+
+        async def _send():
+            try:
+                await self._ws.send(msg)
+            except Exception as e:
+                print(f"[launcher] 发布事件失败: {e}")
+
+        asyncio.create_task(_send())
+
+    async def _wait_event(self, event_type: str, module_id: str, timeout: float) -> dict | None:
+        """Wait for a specific event from a module. Returns data dict or None on timeout."""
+        key = f"{event_type}:{module_id}"
+        evt = asyncio.Event()
+        data = {}
+        self._event_waiters[key] = (evt, data)
+        try:
+            await asyncio.wait_for(evt.wait(), timeout=timeout)
+            return data
+        except asyncio.TimeoutError:
+            return None
+        finally:
+            self._event_waiters.pop(key, None)
+
+    async def _graceful_stop(self, name: str, reason: str = "stop_requested", timeout: float = 10):
+        """Graceful shutdown: check capability → send event → wait ack → wait ready → kill.
+        Modules that did not declare graceful_shutdown in module.ready are terminated directly.
+        """
+        self._log_lifecycle("stopping", name, reason=reason)
+
+        if not self._graceful_modules.get(name):
+            self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_NON_GRACEFUL)
+            self._log_lifecycle("stopped", name, reason=reason)
+            await self._publish_event("module.stopped", {
+                "module_id": name,
+                "graceful_shutdown": False,
+            })
+            return
+
+        # Register waiters BEFORE sending shutdown event
+        ack_key = f"module.shutdown.ack:{name}"
+        ack_evt = asyncio.Event()
+        ack_data = {}
+        self._event_waiters[ack_key] = (ack_evt, ack_data)
+
+        ready_key = f"module.shutdown.ready:{name}"
+        ready_evt = asyncio.Event()
+        ready_data = {}
+        self._event_waiters[ready_key] = (ready_evt, ready_data)
+
+        await self._publish_event("module.shutdown", {
+            "module_id": name, "reason": reason, "timeout": timeout,
+        })
+
+        # Wait for ack
+        try:
+            await asyncio.wait_for(ack_evt.wait(), timeout=3)
+            ack = ack_data
+        except asyncio.TimeoutError:
+            ack = None
+        finally:
+            self._event_waiters.pop(ack_key, None)
+
+        if not ack:
+            self._event_waiters.pop(ready_key, None)
+            self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_NON_GRACEFUL)
+            await self._publish_event("module.stopped", {
+                "module_id": name,
+                "graceful_shutdown": self._graceful_modules.get(name, False),
+            })
+            return
+
+        estimated = min(ack.get("estimated_cleanup", timeout), timeout)
+
+        # Wait for ready
+        try:
+            await asyncio.wait_for(ready_evt.wait(), timeout=estimated)
+            ready = ready_data
+        except asyncio.TimeoutError:
+            ready = None
+        finally:
+            self._event_waiters.pop(ready_key, None)
+        if ready:
+            self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_READY)
+        else:
+            self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_PARTIAL)
+
+        self._log_lifecycle("stopped", name, reason=reason)
+        await self._publish_event("module.stopped", {
+            "module_id": name,
+            "graceful_shutdown": self._graceful_modules.get(name, False),
+        })
+
+    async def _graceful_shutdown_all(self):
+        """Shut down all modules. Order:
+        1. Send shutdown to graceful modules (excl. Kernel) — let them start cleanup
+        2. Terminate non-graceful modules (fast, runs during graceful cleanup)
+        3. Wait for graceful modules to exit (process monitoring)
+        4. Shut down Kernel last (keeps event routing alive throughout)
+        """
+        self._system_shutting_down = True
+        running = [n for n in self.modules if self.process_manager.is_running(n)]
+        # Also check core modules
+        for cn in CORE_MODULE_NAMES:
+            if self.process_manager.is_running(cn) and cn not in running:
+                running.append(cn)
+        if not running:
+            print("[launcher] 没有运行中的模块需要关闭")
+            return
+
+        graceful = [n for n in running if self._graceful_modules.get(n)]
+        non_graceful = [n for n in running if not self._graceful_modules.get(n)]
+
+        # Defer Kernel — it must stay alive to route shutdown events
+        kernel_deferred = "kernel" in graceful
+        graceful_batch = [n for n in graceful if n != "kernel"] if kernel_deferred else graceful
+
+        print(f"[launcher] 正在关闭 {len(running)} 个模块: {', '.join(running)}")
+
+        # Phase 1: Notify graceful modules first (they start cleanup immediately)
+        for name in graceful_batch:
+            self._log_lifecycle("stopping", name, reason="system_shutdown")
+            await self._publish_event("module.shutdown", {
+                "module_id": name, "reason": "system_shutdown", "timeout": 5,
+            })
+
+        # Phase 2: While graceful modules are cleaning up, terminate non-graceful ones
+        if non_graceful:
+            print(f"[launcher] 直接终止 {len(non_graceful)} 个不支持优雅退出的模块: {', '.join(non_graceful)}")
+        for name in non_graceful:
+            self._log_lifecycle("stopping", name, reason="system_shutdown")
+            self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_PARTIAL)
+            self._log_lifecycle("stopped", name, reason="system_shutdown")
+
+        # Phase 3: Wait for graceful modules to exit (process monitoring)
+        if graceful_batch:
+            deadline = time.time() + 5
+            while time.time() < deadline:
+                still_running = [n for n in graceful_batch if self.process_manager.is_running(n)]
+                if not still_running:
+                    print("[launcher] 所有优雅退出模块已自行退出")
+                    break
+                remaining = max(0, deadline - time.time())
+                print(f"[launcher] 等待 {len(still_running)} 个模块退出 ({remaining:.0f}s): {', '.join(still_running)}")
+                await asyncio.sleep(1)
+            # Force kill survivors
+            for name in graceful_batch:
+                if self.process_manager.is_running(name):
+                    self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_PARTIAL)
+                    self._log_lifecycle("stopped", name, reason="system_shutdown")
+
+        # Phase 4: All other modules exited — now shut down Kernel
+        if kernel_deferred and self.process_manager.is_running("kernel"):
+            self._log_lifecycle("stopping", "kernel", reason="system_shutdown")
+            print("[launcher] 正在关闭 Kernel...")
+
+            # Call kernel.shutdown RPC (not event)
+            rpc_sent = False
+            try:
+                if self._ws:
+                    await self._rpc_call(self._ws, "kernel.shutdown", {})
+                    print("[launcher] Kernel shutdown RPC 已发送")
+                    rpc_sent = True
+                else:
+                    print("[launcher] WebSocket 未连接，跳过 RPC 调用")
+            except Exception as e:
+                print(f"[launcher] Kernel shutdown RPC 失败: {e}")
+
+            # Wait for kernel to exit
+            if rpc_sent:
+                # RPC sent: wait up to 5s for graceful exit
+                proc = self.process_manager._processes.get("kernel")
+                if proc:
+                    try:
+                        loop = asyncio.get_event_loop()
+                        await asyncio.wait_for(
+                            loop.run_in_executor(None, proc.wait),
+                            timeout=5
+                        )
+                        print("[launcher] Kernel 已退出")
+                    except asyncio.TimeoutError:
+                        print("[launcher] Kernel 5秒内未退出，强制停止")
+                        self.process_manager.stop_module("kernel", timeout=SHUTDOWN_TIMEOUT_PARTIAL)
+            else:
+                # No RPC (WS not connected): use shorter timeout for terminate
+                self.process_manager.stop_module("kernel", timeout=2)
+
+            self._log_lifecycle("stopped", "kernel", reason="system_shutdown")
+
+        # Final safety net
+        try:
+            self.process_manager.stop_all(timeout=SHUTDOWN_TIMEOUT_BULK)
+        except Exception as e:
+            print(f"[launcher] stop_all 出错: {e}")
+
+    # ── Module startup ──
+
+    def _topo_sort(self, modules: list[ModuleInfo]) -> list[ModuleInfo]:
+        """Topological sort by depends_on. Raises RuntimeError on cycle."""
+        name_map = {m.name: m for m in modules}
+        visited = set()
+        in_stack = set()
+        order = []
+
+        def visit(name):
+            if name in in_stack:
+                raise RuntimeError(f"Circular dependency detected involving '{name}'")
+            if name in visited:
+                return
+            in_stack.add(name)
+            info = name_map.get(name)
+            if info:
+                for dep in info.depends_on:
+                    visit(dep)
+            in_stack.remove(name)
+            visited.add(name)
+            if info:
+                order.append(info)
+
+        for m in modules:
+            visit(m.name)
+        return order
+
+    def _topo_layers(self, modules: list[ModuleInfo]) -> list[list[ModuleInfo]]:
+        """Topological sort into layers. Modules in the same layer have no
+        inter-dependencies and can be started in parallel."""
+        name_map = {m.name: m for m in modules}
+        all_names = set(name_map.keys())
+
+        # Compute depth (longest path from root) for each module
+        depth: dict[str, int] = {}
+        in_stack: set[str] = set()
+
+        def get_depth(name: str) -> int:
+            if name in depth:
+                return depth[name]
+            if name in in_stack:
+                raise RuntimeError(f"Circular dependency detected involving '{name}'")
+            in_stack.add(name)
+            info = name_map.get(name)
+            d = 0
+            if info:
+                for dep in info.depends_on:
+                    if dep in all_names:
+                        d = max(d, get_depth(dep) + 1)
+            in_stack.remove(name)
+            depth[name] = d
+            return d
+
+        for name in all_names:
+            get_depth(name)
+
+        # Group by depth
+        max_depth = max(depth.values()) if depth else 0
+        layers: list[list[ModuleInfo]] = [[] for _ in range(max_depth + 1)]
+        for name, d in depth.items():
+            layers[d].append(name_map[name])
+        return layers
+
+    async def _start_one_module(self, info: ModuleInfo):
+        """Start a single module: publish starting → start process → send kernel_port → wait ready → started → close stdio."""
+        self._log_lifecycle("starting", info.name)
+        await self._publish_event("module.starting", {"module_id": info.name})
+
+        token = self._module_tokens.get(info.name, "")
+        boot_info = {"token": token}
+        t0 = time.monotonic()
+        ok = self.process_manager.start_module(info, boot_info=boot_info)
+        if not ok:
+            self._log_lifecycle("start_failed", info.name)
+            return
+
+        # Register waiter BEFORE sending kernel_port
+        # This prevents race condition where module connects and sends module.ready before waiter is registered
+        ready_key = f"module.ready:{info.name}"
+        ready_evt = asyncio.Event()
+        ready_data = {}
+        self._event_waiters[ready_key] = (ready_evt, ready_data)
+
+        # Send kernel_port via stdin so module can connect to Kernel WS
+        self.process_manager.write_stdin(info.name, {
+            "kite": "kernel_port",
+            "kernel_port": self.kernel_port,
+        })
+
+        # Persist immediately after starting to ensure PID is recorded
+        self.process_manager.persist_records()
+
+        # Wait for module.ready or module.exiting (whichever comes first)
+        timeout = info.launch.timeout
+        try:
+            await asyncio.wait_for(ready_evt.wait(), timeout=timeout)
+            ready = ready_data
+        except asyncio.TimeoutError:
+            ready = None
+        finally:
+            self._event_waiters.pop(ready_key, None)
+
+        elapsed = time.monotonic() - t0
+        if ready and ready.get("_exited"):
+            # Module sent module.exiting before ready — it chose to quit
+            reason = ready.get("reason", "unknown")
+            self._exit_reasons[info.name] = reason
+            print(f"[launcher] 模块 '{info.name}' 主动退出: {reason} ({elapsed:.2f}s)")
+        elif ready:
+            self._graceful_modules[info.name] = bool(ready.get("graceful_shutdown"))
+            self._ready_times[info.name] = elapsed
+            print(f"[launcher] 模块 '{info.name}' 已就绪 ({elapsed:.2f}s)")
+        else:
+            print(f"\033[91m[launcher] 警告: '{info.name}' 在 {timeout}s 内未发送 module.ready\033[0m")
+
+        rec = self.process_manager.get_record(info.name)
+        self._log_lifecycle("started", info.name, pid=rec.pid if rec else None)
+        await self._publish_event("module.started", {"module_id": info.name})
+        self.process_manager.close_stdio(info.name)
+
+    async def _register_module_tokens(self):
+        """Generate per-module tokens and register the mapping to Kernel via RPC."""
+        # Include all scanned modules
+    async def _generate_module_tokens(self):
+        """Request Kernel to generate tokens for all scanned modules via RPC."""
+        # Collect module names that need tokens
+        module_names = [name for name in self.modules if name not in self._module_tokens]
+
+        if not module_names:
+            return
+
+        # Wait for WebSocket connection to be ready
+        if self._ws_connected:
+            try:
+                await asyncio.wait_for(self._ws_connected.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                print(f"[launcher] 警告: WebSocket 未就绪，无法生成令牌")
+                return
+        else:
+            print(f"[launcher] 警告: _ws_connected 未初始化")
+            return
+
+        # Call Kernel RPC to generate tokens
+        try:
+            result = await self._rpc_call(self._ws, "kernel.generate_tokens", {"modules": module_names})
+            if result.get("result", {}).get("ok"):
+                tokens = result["result"].get("tokens", {})
+                self._module_tokens.update(tokens)
+                print(f"[launcher] Kernel 已生成 {len(tokens)} 个模块令牌")
+            elif "error" in result:
+                print(f"[launcher] 警告: 令牌生成失败: {result['error'].get('message', '')}")
+        except Exception as e:
+            print(f"[launcher] 警告: 生成模块令牌失败: {e}")
+
+    async def _register_new_tokens(self, tokens: dict):
+        """Register new token mapping to Kernel via RPC kernel.register_tokens."""
+        if not self._ws or not tokens:
+            return
+        try:
+            result = await self._rpc_call(self._ws, "kernel.register_tokens", tokens)
+            if result.get("result", {}).get("ok"):
+                print(f"[launcher] 已注册 {len(tokens)} 个模块令牌")
+            elif "error" in result:
+                print(f"[launcher] 警告: 令牌注册失败: {result['error'].get('message', '')}")
+        except Exception as e:
+            print(f"[launcher] 警告: 注册模块令牌失败: {e}")
+
+    # ── Validation ──
+
+    def _validate_core_modules(self):
+        """Validate core modules exist."""
+        project_root = os.environ["KITE_PROJECT"]
+        mod_dir = os.path.join(project_root, "kernel")
+        md_path = os.path.join(mod_dir, "module.md")
+        if not os.path.isdir(mod_dir):
+            print(f"[launcher] 致命: 核心模块 'kernel' 目录未找到: {mod_dir}")
+            sys.exit(1)
+        if not os.path.isfile(md_path):
+            print(f"[launcher] 致命: 核心模块 'kernel' 缺少 module.md: {md_path}")
+            sys.exit(1)
+        try:
+            with open(md_path, "r", encoding="utf-8") as f:
+                fm = _parse_frontmatter(f.read())
+            if not fm:
+                print(f"[launcher] 致命: 核心模块 'kernel' module.md 没有有效的 frontmatter")
+                sys.exit(1)
+        except Exception as e:
+            print(f"[launcher] 致命: 核心模块 'kernel' module.md 解析错误: {e}")
+            sys.exit(1)
+
+    # ── Module crash summary ──
+
+    def _print_module_crash_summary(self, name: str):
+        """Read module's crashes.jsonl last record and print red summary to console.
+        Complement to module.crash event — reliable even if event was never sent."""
+        RED = "\033[91m"
+        RESET = "\033[0m"
+        _suffix = os.environ.get("KITE_INSTANCE_SUFFIX", "")
+        crash_log = os.path.join(
+            os.environ.get("KITE_INSTANCE_DIR", ""), name, "log", f"crashes{_suffix}.jsonl"
+        )
+        if not os.path.isfile(crash_log):
+            return
+        try:
+            with open(crash_log, "rb") as f:
+                f.seek(0, 2)
+                size = f.tell()
+                if size == 0:
+                    return
+                f.seek(max(0, size - 4096))
+                lines = f.read().decode("utf-8").strip().split("\n")
+                last = json.loads(lines[-1])
+                exc_type = last.get("exception_type", "Unknown")
+                ctx = last.get("context", {})
+                file_name = ctx.get("file", "unknown")
+                line_no = ctx.get("line", "?")
+                print(f"[launcher] {RED}崩溃: "
+                      f"{exc_type} in {file_name}:{line_no}{RESET}")
+                print(f"[launcher] 崩溃日志: {crash_log}")
+        except Exception:
+            pass
+
+    # ── Monitor loop ──
+
+    async def _monitor_loop(self):
+        """Check child processes every second. Handle crashes.
+        Uses _shutdown_event (asyncio.Event) so Ctrl+C wakes us immediately.
+
+        Responsibility split:
+        - Core module crash → full restart (Launcher handles)
+        - Watchdog crash → Launcher restarts directly (up to 3 times)
+        - Other module exit → publish module.stopped event only; Watchdog decides restart
+        """
+        WATCHDOG_MAX_FAIL = 3
+        watchdog_fail_count = 0
+
+        while not self._shutdown_event.is_set():
+            exited = self.process_manager.check_exited()
+
+            for name, rc in exited:
+                print(f"[launcher] 模块 '{name}' 退出，返回码 {rc}")
+                if rc != 0:
+                    self._print_module_crash_summary(name)
+                self._log_lifecycle("exited", name, exit_code=rc)
+                await self._publish_event("module.stopped", {
+                    "module_id": name, "exit_code": rc,
+                    "graceful_shutdown": self._graceful_modules.get(name, False),
+                })
+                info = self.modules.get(name)
+
+                # 1) Core module crash → full restart
+                if name in CORE_MODULE_NAMES or (info and info.is_core()):
+                    print(f"[launcher] 严重: 核心模块 '{name}' 崩溃，正在全部重启...")
+                    self._log_lifecycle("core_crash", name, exit_code=rc)
+                    await self._full_restart()
+                    return
+
+                # 2) Watchdog crash → Launcher restarts directly
+                if name == WATCHDOG_MODULE_NAME:
+                    if self._system_shutting_down:
+                        print(f"[launcher] Watchdog 退出（系统关闭中），跳过重启")
+                        continue
+                    watchdog_fail_count += 1
+                    if watchdog_fail_count <= WATCHDOG_MAX_FAIL and info:
+                        print(f"[launcher] Watchdog 崩溃，正在重启 (第 {watchdog_fail_count}/{WATCHDOG_MAX_FAIL} 次)...")
+                        await self._start_one_module(info)
+                    else:
+                        self._desired_states[name] = "stopped"
+                        self._log_lifecycle("failed", name, reason=f"exceeded {WATCHDOG_MAX_FAIL} retries")
+                        print(f"[launcher] Watchdog 失败 {WATCHDOG_MAX_FAIL} 次，已放弃")
+                    continue
+
+                # 3) Other modules → event already published above; Watchdog decides restart
+                #    (no restart logic here — Watchdog handles it via module.stopped event)
+
+            if exited:
+                self.process_manager.persist_records()
+
+            # Wait 1s but wake immediately on shutdown signal
+            try:
+                await asyncio.wait_for(self._shutdown_event.wait(), timeout=1)
+                return  # shutdown requested
+            except asyncio.TimeoutError:
+                pass
+
+    async def _full_restart(self):
+        """Stop all modules, regenerate tokens, re-run Phase 1-2."""
+        print("[launcher] 全量重启: 正在停止所有模块...")
+
+        # Persist records before shutdown so cleanup_leftovers can find survivors
+        self.process_manager.persist_records()
+
+        # Disconnect Kernel WS
+        if self._ws_task:
+            self._ws_task.cancel()
+            self._ws_task = None
+        self._ws = None
+        self._rpc_waiters.clear()
+        self._rpc_results.clear()
+
+        await self._graceful_shutdown_all()
+
+        # Cleanup any leftover processes that survived graceful shutdown.
+        self.process_manager.cleanup_leftovers()
+
+        self._module_tokens.clear()
+
+        # Regenerate kite_token
+        self.kite_token = secrets.token_hex(32)
+        self.process_manager.kite_token = self.kite_token
+
+        print("[launcher] 全量重启: 重新执行 Phase 1-2...")
+        try:
+            await self._phase1_start_kernel()
+            await self._phase2_start_modules()
+            self.process_manager.persist_records()
+            print("[launcher] 全量重启完成，恢复监控循环")
+            await self._monitor_loop()
+        except Exception as e:
+            print(f"[launcher] 全量重启失败: {e}")
+
+    # ── Shutdown ──
+
+    def _final_cleanup(self):
+        """Called on exit — stop all processes, clear records."""
+        try:
+            print("[launcher] 正在执行最终清理...")
+
+            if self._ws_task:
+                self._ws_task.cancel()
+
+            # Note: _graceful_shutdown_all() already called stop_all() in _async_main finally block.
+            # This is just a safety check — should normally find nothing.
+            remaining = [n for n in self.process_manager._processes
+                         if self.process_manager.is_running(n)]
+            if remaining:
+                print(f"[launcher] 警告: 仍有残留进程 (不应出现): {', '.join(remaining)}")
+                self.process_manager.stop_all(timeout=SHUTDOWN_TIMEOUT_BULK)
+            else:
+                print("[launcher] 无残留进程")
+
+            # Clear instance runtime files
+            try:
+                os.remove(self.process_manager.records_path)
+            except OSError:
+                pass
+        except Exception as e:
+            print(f"[launcher] 最终清理出错: {e}")
+        finally:
+            # Signal the safety-net thread that normal shutdown has completed
+            self._shutdown_complete.set()
+
+            # Calculate and display shutdown time
+            if self._shutdown_start_time > 0:
+                shutdown_elapsed = time.monotonic() - self._shutdown_start_time
+                print(f"[launcher] 再见。(退出耗时: {shutdown_elapsed:.2f}s)")
+            else:
+                print("[launcher] 再见。")
+
+            if IS_WINDOWS:
+                os._exit(0)
+
+    # ── Startup report ──
+
+    async def _print_startup_report(self, total_time: float, phase_times: dict[str, float], *,
+                                     global_instances=None, cleaned_stats: dict[str, int] | None = None):
+        """Print a green startup summary with module list and timing."""
+        G = "\033[32m"  # green
+        Y = "\033[33m"  # yellow
+        R = "\033[0m"   # reset
+        B = "\033[1;32m"  # bold green
+
+        running = []
+        exited = []
+        stopped = []
+        for name, info in self.modules.items():
+            rec = self.process_manager.get_record(name)
+            is_running = self.process_manager.is_running(name)
+            if is_running and rec:
+                running.append((name, info, rec))
+            elif self._desired_states.get(name) == "running" and not is_running:
+                # Was started but already exited (e.g. module.exiting)
+                exited.append((name, info))
+            else:
+                stopped.append((name, info))
+
+        # Calculate kernel startup time (Phase 1)
+        kernel_time = phase_times.get("Phase 1: Kernel", 0)
+
+        lines = [
+            "",
+            f"{B}{'=' * 60}",
+            f"  Kite 内核启动完成   耗时 {kernel_time:.2f}s",
+            f"  Kite 全部模块启动完成   总耗时 {total_time:.2f}s",
+            f"{'=' * 60}{R}",
+        ]
+
+        # Phase breakdown
+        lines.append(f"{G}  阶段耗时:{R}")
+
+        # Kernel modules section
+        lines.append(f"{G}    内核模块:{R}")
+        if "Phase 1: Kernel" in phase_times:
+            elapsed = phase_times["Phase 1: Kernel"]
+            lines.append(f"{G}      {'Phase 1: Kernel':<26s} {elapsed:>6.2f}s{R}")
+
+        # Extension modules section
+        lines.append(f"{G}    扩展模块:{R}")
+        if "Phase 2: Extensions" in phase_times:
+            elapsed = phase_times["Phase 2: Extensions"]
+            lines.append(f"{G}      {'Phase 2: Extensions':<26s} {elapsed:>6.2f}s{R}")
+
+        # Sort running modules by ready time
+        running_sorted = sorted(running, key=lambda x: self._ready_times.get(x[0], float('inf')))
+
+        # Running modules with ready time and elapsed from Kite start
+        DIM = "\033[90m"
+        lines.append(f"{G}  运行中 ({len(running)}):{R}")
+
+        # CJK-aware display width helpers
+        def _dw(s):
+            """Display width: CJK chars count as 2, others as 1."""
+            w = 0
+            for c in str(s):
+                w += 2 if '\u4e00' <= c <= '\u9fff' or '\u3000' <= c <= '\u303f' or '\uff00' <= c <= '\uffef' else 1
+            return w
+
+        def _rpad(s, width):
+            """Left-align s in a field of given display width."""
+            return str(s) + ' ' * max(0, width - _dw(s))
+
+        def _lpad(s, width):
+            """Right-align s in a field of given display width."""
+            return ' ' * max(0, width - _dw(s)) + str(s)
+
+        # Column definitions: (header, align, min_width)
+        headers = ['模块', 'PID', '启动耗时', '进程启动时长', '类型']
+        aligns = ['left', 'right', 'right', 'right', 'left']  # alignment per column
+
+        # Build data rows first to calculate column widths
+        rows = []
+        for name, info, rec in running_sorted:
+            label = info.display_name or name
+            ready_t = self._ready_times.get(name)
+            time_str = f"{ready_t:.2f}s" if ready_t is not None else "—"
+            if ready_t is not None and hasattr(self, '_start_unix'):
+                elapsed_from_start = (rec.started_at + ready_t) - self._start_unix
+                es_str = f"{elapsed_from_start:.2f}s"
+            else:
+                es_str = "—"
+
+            # Check if module timed out (ready_t >= 15s for kernel, >= timeout for others)
+            is_timeout = False
+            if ready_t is not None:
+                if name == "kernel" and ready_t >= 15:
+                    is_timeout = True
+                elif name != "kernel" and ready_t >= 15:  # Default timeout for other modules
+                    is_timeout = True
+
+            rows.append([label, str(rec.pid), time_str, es_str, f"[{info.type}]", is_timeout])
+
+        # Calculate column widths: max of header and all data display widths
+        col_widths = [_dw(h) for h in headers]
+        for row in rows:
+            for i, cell in enumerate(row[:5]):  # Only first 5 columns (exclude is_timeout flag)
+                col_widths[i] = max(col_widths[i], _dw(cell))
+
+        # Render header
+        hdr_parts = []
+        for i, h in enumerate(headers):
+            if aligns[i] == 'left':
+                hdr_parts.append(_rpad(h, col_widths[i]))
+            else:
+                hdr_parts.append(_lpad(h, col_widths[i]))
+        lines.append(f"{DIM}      {'  '.join(hdr_parts)}{R}")
+
+        # Render data rows
+        RED = "\033[91m"
+        for row in rows:
+            is_timeout = row[5]  # Last element is the timeout flag
+            parts = []
+            for i, cell in enumerate(row[:5]):  # Only first 5 columns
+                if aligns[i] == 'left':
+                    parts.append(_rpad(cell, col_widths[i]))
+                else:
+                    parts.append(_lpad(cell, col_widths[i]))
+            if is_timeout:
+                lines.append(f"{RED}    ✓ {'  '.join(parts)}{R}")
+            else:
+                lines.append(f"{G}    ✓ {'  '.join(parts)}{R}")
+
+        # Exited modules (started but already quit)
+        if exited:
+            lines.append(f"{Y}  已退出 ({len(exited)}):{R}")
+            for name, info in exited:
+                label = info.display_name or name
+                reason = self._exit_reasons.get(name, "")
+                reason_str = f": {reason}" if reason else ""
+                lines.append(f"{Y}    ↗ {label:<20s} (主动退出{reason_str}){R}")
+
+        # Stopped modules
+        if stopped:
+            lines.append(f"{G}  未启动 ({len(stopped)}):{R}")
+            for name, info in stopped:
+                label = info.display_name or name
+                lines.append(f"{G}    - {label:<20s} ({info.state}){R}")
+
+        lines.append(f"{G}  Kernel WS: ws://127.0.0.1:{self.kernel_port}/ws   实例: {self.instance_id}{R}")
+
+        # Query Kernel for web module's api_endpoint via RPC
+        web_url = ""
+        if self._ws:
+            try:
+                resp = await self._rpc_call(self._ws, "registry.get", {"path": "web.api_endpoint"}, timeout=3)
+                val = resp.get("result", {}).get("value")
+                if val and isinstance(val, str):
+                    web_url = val.replace("://127.0.0.1:", "://localhost:")
+            except Exception:
+                pass
+        if web_url:
+            lines.append(f"{B}  Web 管理后台: {web_url}{R}")
+
+        # Instance info
+        instances = self.process_manager.get_alive_instances()
+        inst_num = self.process_manager.instance_num
+        suffix_display = self.process_manager.instance_suffix or "(无)"
+        inst_dir = os.environ.get("KITE_INSTANCE_DIR", "")
+        cwd = os.environ.get("KITE_CWD", "")
+        debug_flag = " [DEBUG]" if os.environ.get("KITE_DEBUG") == "1" else ""
+        lines.append(f"{G}  当前实例: #{inst_num}  后缀: {suffix_display}  PID: {os.getpid()}{debug_flag}{R}")
+        lines.append(f"{G}  实例目录: {inst_dir}{R}")
+        lines.append(f"{G}  工作目录: {cwd}{R}")
+        if len(instances) > 1:
+            lines.append(f"{G}  所有实例:{R}")
+            for i in instances:
+                s = "" if i["num"] == 1 else f"~{i['num']}"
+                debug_tag = " [DEBUG]" if i.get("debug", False) else ""
+                current_tag = " (当前)" if i["is_self"] else ""
+                lines.append(f"{G}    #{i['num']}  PID {i['launcher_pid']}  "
+                             f"模块数 {i['module_count']}  (processes{s}.json){debug_tag}{current_tag}{R}")
+
+        # Cross-directory instances from other projects
+        if global_instances:
+            my_inst_basename = os.path.basename(os.environ.get("KITE_INSTANCE_DIR", ""))
+            other_instances = [i for i in global_instances
+                               if not i["is_self"] and i["instance_dir"] != my_inst_basename]
+            if other_instances:
+                lines.append(f"{G}  其他项目实例:{R}")
+                for i in other_instances:
+                    debug_tag = " [DEBUG]" if i.get("debug", False) else ""
+                    cwd_display = f"  {i['cwd']}" if i["cwd"] else ""
+                    lines.append(
+                        f"{G}    {i['instance_dir']:<20s}  "
+                        f"#{i['num']}  PID {i['launcher_pid']}  "
+                        f"模块数 {i['module_count']}"
+                        f"{cwd_display}{debug_tag}{R}"
+                    )
+
+        if cleaned_stats:
+            total = sum(cleaned_stats.values())
+            if len(cleaned_stats) == 1:
+                inst, count = next(iter(cleaned_stats.items()))
+                lines.append(f"{Y}  已清理残留进程: {inst} ({count} 个){R}")
+            else:
+                lines.append(f"{Y}  已清理残留进程 (共 {total} 个):{R}")
+                for inst, count in cleaned_stats.items():
+                    lines.append(f"{Y}    {inst}: {count} 个{R}")
+
+        lines.append(f"{B}{'=' * 60}{R}")
+        lines.append("")
+
+        print("\n".join(lines))
+
+    # ── Utilities ──
+
+    def _load_discovery(self) -> dict | None:
+        """Read discovery config from launcher's own module.md."""
+        md_path = os.path.join(os.environ["KITE_PROJECT"], "launcher", "module.md")
+        try:
+            with open(md_path, "r", encoding="utf-8") as f:
+                fm = _parse_frontmatter(f.read())
+            discovery = fm.get("discovery")
+            if isinstance(discovery, dict) and discovery:
+                return discovery
+        except Exception as e:
+            print(f"[launcher] 警告: 读取发现配置失败: {e}")
+        return None
+
+    def _log_lifecycle(self, event: str, module: str, **extra):
+        """Append one JSONL line to lifecycle.jsonl."""
+        from datetime import datetime, timezone
+        record = {"ts": datetime.now(timezone.utc).isoformat(), "event": event, "module": module}
+        record.update(extra)
+        try:
+            os.makedirs(os.path.dirname(self._lifecycle_log), exist_ok=True)
+            with open(self._lifecycle_log, "a", encoding="utf-8") as f:
+                f.write(json.dumps(record, ensure_ascii=False) + "\n")
+        except Exception:
+            pass
+
+
+
+def _update_module_md_state(module_dir: str, new_state: str):
+    """Update the state field in a module's module.md frontmatter."""
+    import re
+    md_path = os.path.join(module_dir, "module.md")
+    if not os.path.isfile(md_path):
+        return
+
+    try:
+        with open(md_path, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        updated = re.sub(
+            r'^(state:\s*)(\S+)',
+            rf'\g<1>{new_state}',
+            content,
+            count=1,
+            flags=re.MULTILINE,
+        )
+
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write(updated)
+    except Exception as e:
+        print(f"[launcher] 警告: 更新 module.md 状态失败: {e}")
+
+
+def start_launcher():
+    """Entry point called from main.py. Sets up environment and starts launcher."""
+    # Load .env (development convenience)
+    try:
+        from dotenv import load_dotenv
+        load_dotenv()
+    except ImportError:
+        pass
+
+    # Resolve project root
+    project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+    # Home base for Kite data
+    home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    kite_home = os.path.join(home, ".kite")
+
+    # Set KITE_* defaults
+    defaults = {
+        "KITE_PROJECT": project_root,
+        "KITE_CWD": os.getcwd(),
+        "KITE_WORKSPACE": os.path.join(kite_home, "workspace"),
+        "KITE_DATA": os.path.join(kite_home, "data"),
+        "KITE_MODULES": os.path.join(kite_home, "modules"),
+        "KITE_REPO": os.path.join(kite_home, "repo"),
+        "KITE_ENV": "development",
+    }
+    for key, value in defaults.items():
+        if not os.environ.get(key):
+            os.environ[key] = value
+
+    # Parse CLI args
+    if "--debug" in sys.argv:
+        os.environ["KITE_DEBUG"] = "1"
+        sys.argv.remove("--debug")
+
+    # Setup logging
+    from .logging_setup import (
+        setup_timestamped_print,
+        init_log_files,
+        setup_exception_hooks,
+        reset_time_baseline,
+        write_crash_handled
+    )
+    setup_timestamped_print()
+    reset_time_baseline()
+
+    print("[launcher] Kite 启动中...")
+
+    # Create and run launcher
+    token = secrets.token_hex(32)
+    launcher = Launcher(kite_token=token)
+    print("[launcher] 启动器实例已创建")
+
+    # Initialize log files (KITE_MODULE_DATA is now set)
+    init_log_files()
+    setup_exception_hooks()
+
+    log_dir = os.path.join(os.environ.get("KITE_MODULE_DATA", ""), "log")
+    suffix = launcher.process_manager.instance_suffix
+    latest_log = os.path.join(log_dir, f"latest{suffix}.log")
+    print(f"[launcher] 日志: {latest_log}")
+
+    try:
+        launcher.run()
+    except Exception as e:
+        write_crash_handled(type(e), e, e.__traceback__)
+        sys.exit(1)