@agentunion/kite 1.3.2 → 1.5.0

package/launcher/entry.py

@@ -29,10 +29,21 @@ 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
+
+# 不支持优雅关闭
+SHUTDOWN_TIMEOUT_NON_GRACEFUL = 0.3  # SIGTERM 后等待时间
+
+# 支持优雅关闭 - 等待响应
+SHUTDOWN_TIMEOUT_ACK = 3.0           # 等待 shutdown.ack
+SHUTDOWN_TIMEOUT_EXITING = 3.0       # 等待 module.exiting
+
+# 清理超时（从 exiting 事件获取）
+CLEANUP_TIMEOUT_DEFAULT = 5.0        # 默认清理时间
+CLEANUP_TIMEOUT_MIN = 0.0            # 最小清理时间
+CLEANUP_TIMEOUT_MAX = 30.0           # 最大清理时间
+
+# 批量关闭安全网
+SHUTDOWN_TIMEOUT_BULK = 3.0
 
 # Core module names that are started in Phase 1 (not Phase 2)
 CORE_MODULE_NAMES = {"kernel"}
@@ -62,16 +73,25 @@ class Launcher:
             discovery=self._load_discovery(),
         )
 
+        # Load relay configuration
+        relay_config = self._load_relay_config()
+        self._relay_modules = relay_config.get("modules", [])
+        self._relay_token_limits = relay_config.get("token_limits", {})
+
         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
+        self._client_tokens: dict[str, str] = {}  # virtual module_id -> kernel_token (for relay modules)
 
         # Three-layer state model: desired_state per module
         self._desired_states: dict[str, str] = {}  # module_name -> "running" | "stopped"
 
+        # Relay module configuration (already loaded above, don't reinitialize)
+        # self._relay_modules and self._relay_token_limits are set in lines 78-79
+
         # Kernel WebSocket client
         self._ws: object | None = None
         self._ws_task: asyncio.Task | None = None
@@ -101,6 +121,9 @@ class Launcher:
         # System-wide shutdown flag: prevents Watchdog restart during shutdown
         self._system_shutting_down = False
 
+        # 模块退出状态跟踪（防止 stopped 事件重复发送）
+        self._module_states: dict[str, dict] = {}
+
         # 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]] = {}
@@ -117,6 +140,9 @@ class Launcher:
             pass
         os.environ["KITE_INSTANCE_SUFFIX"] = suffix
 
+        # Record launcher startup
+        self._record_launcher_startup()
+
     @staticmethod
     def _fmt_elapsed(seconds: float) -> str:
         """Format elapsed seconds: <1s → 'NNNms', >=1s → 'N.Ns', >=10s → 'NNs'."""
@@ -509,10 +535,14 @@ class Launcher:
             ready = await self._wait_event("module.ready", "kernel", timeout=15)
             if ready:
                 self._graceful_modules["kernel"] = bool(ready.get("graceful_shutdown"))
-                print("[launcher] Kernel 已就绪")
+                # Use startup_time from module.ready event
+                startup_time = ready.get("startup_time", time.monotonic() - t_ws)
+                self._ready_times["kernel"] = startup_time
+                startup_str = f"{startup_time:.3f}s" if startup_time < 10 else f"{startup_time:.2f}s"
+                print(f"[launcher] Kernel 已就绪 ({startup_str})")
             else:
                 print("\033[91m[launcher] 警告: Kernel 在 15s 内未发送 module.ready\033[0m")
-            self._ready_times["kernel"] = time.monotonic() - t_ws
+                self._ready_times["kernel"] = time.monotonic() - t_ws
 
         await asyncio.gather(
             _scan_and_generate_tokens(),
@@ -597,6 +627,11 @@ class Launcher:
                         print(f"[launcher] Kernel 重连失败 {max_retries} 次，退出")
                         sys.exit(1)
                     print(f"[launcher] Kernel 连接错误: {e}, {retry_delay:.1f}s 后重试 ({attempt}/{max_retries})")
+                    if attempt == 5:
+                        print(f"\033[33m[launcher] 提示: 已连续 {attempt} 次无法连接 Kernel (端口 {self.kernel_port})")
+                        if self.kernel_port < 1024:
+                            print(f"[launcher] ⚠ 端口 {self.kernel_port} 异常偏低，可能是 Kernel 端口绑定失败或配置错误")
+                        print(f"[launcher] 请检查: 1) Kernel 进程是否存活  2) kernel/module.md 中 preferred_port 配置是否正确\033[0m")
             self._ws = None
             if self._thread_shutdown.is_set():
                 return
@@ -608,7 +643,7 @@ class Launcher:
         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:
+        async with websockets.connect(ws_url, open_timeout=3, ping_interval=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)})")
@@ -632,20 +667,53 @@ class Launcher:
                 await self._rpc_call(ws, "registry.register", {
                     "module_id": "launcher",
                     "module_type": "infrastructure",
+                    "tools": {
+                        "rpc": {
+                            "launcher": {
+                                "list_modules": {"method": "list_modules", "description": "列出所有模块"},
+                                "start_module": {"method": "start_module", "description": "启动模块"},
+                                "stop_module": {"method": "stop_module", "description": "停止模块"},
+                                "restart_module": {"method": "restart_module", "description": "重启模块"},
+                                "restart_launcher": {"method": "restart_launcher", "description": "重启 Launcher"},
+                                "rescan": {"method": "rescan", "description": "重新扫描模块"},
+                                "shutdown": {"method": "shutdown", "description": "关闭系统"},
+                                "request_client_token": {"method": "request_client_token", "description": "为 Web 客户端申请 Kernel Token"},
+                            },
+                            "module": {
+                                "config": {
+                                    "get": {"method": "get_module_config", "description": "获取模块配置"},
+                                    "update": {"method": "update_module_config", "description": "更新模块配置"},
+                                    "reset": {"method": "reset_module_config", "description": "恢复默认配置"},
+                                }
+                            }
+                        }
+                    },
                     "events_publish": {
-                        "module.started": {},
-                        "module.stopped": {},
-                        "module.state_changed": {},
+                        "system": {
+                            "ready": {"description": "系统启动完成"}
+                        },
+                        "module": {
+                            "starting": {"description": "模块启动中"},
+                            "started": {"description": "模块已启动"},
+                            "ready": {"description": "模块就绪"},
+                            "stopped": {"description": "模块已停止"},
+                            "exiting": {"description": "模块退出中"},
+                            "shutdown": {"description": "模块关闭"}
+                        }
                     },
                     "events_subscribe": [">"],
                 })
                 print("[launcher] 已注册到 Kernel")
 
                 # Publish module.ready for Launcher itself (every reconnect)
+                startup_time = time.monotonic() - self._t_start
                 await self._publish_event("module.ready", {
                     "module_id": "launcher",
                     "graceful_shutdown": True,
+                    "startup_time": startup_time,
                 })
+                # Record launcher's own startup time
+                self._ready_times["launcher"] = startup_time
 
                 # Signal that connection is ready (after subscription and registration)
                 if self._ws_connected:
@@ -658,7 +726,14 @@ class Launcher:
                 raise
 
     async def _ws_receiver(self, ws):
-        """Receive loop: classify incoming messages."""
+        """Receive loop: classify incoming messages.
+
+        CRITICAL: RPC 死锁防范
+        - 入站 RPC 请求必须用 create_task() 异步执行，不可 await
+        - 原因：如果 handler 内部调用 rpc_call() 发出站请求，出站响应需要本接收循环来分发
+        - 如果接收循环被 await handler 阻塞，出站响应永远收不到 → 超时死锁
+        - 事件通知和 RPC 响应可以同步处理（它们不会反向调用 rpc_call）
+        """
         try:
             async for raw in ws:
                 try:
@@ -676,7 +751,8 @@ class Launcher:
                         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)
+                        # Run in background so receiver loop continues processing responses
+                        asyncio.create_task(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)
@@ -717,6 +793,17 @@ class Launcher:
             self._rpc_results[rpc_id] = msg
             waiter.set()
 
+    async def _handle_ping_event(self, data: dict):
+        """Handle system.ping event and reply with system.pong."""
+        t1 = data.get("ping_time")
+        t2 = time.time()
+
+        await self._publish_event("system.pong", {
+            "module_id": "launcher",
+            "ping_time": t1,
+            "pong_time": t2,
+        })
+
     async def _handle_event_notification(self, msg: dict):
         """Handle an event notification (JSON-RPC 2.0 Notification with method='event')."""
         params = msg.get("params", {})
@@ -725,9 +812,15 @@ class Launcher:
         data = params.get("data") if isinstance(params.get("data"), dict) else {}
         ts = params.get("timestamp", "")
 
+        # Handle system.ping event
+        if event == "system.ping":
+            await self._handle_ping_event(data)
+            return
+
         # 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)
@@ -735,6 +828,14 @@ class Launcher:
 
         # module.exiting also wakes module.ready waiter
         if event == "module.exiting" and module_id:
+            # 处理 token 释放（如果是虚拟模块且标记了 token_revoked）
+            token_revoked = data.get("token_revoked", False)
+            if token_revoked and module_id in self._client_tokens:
+                del self._client_tokens[module_id]
+                print(f"[launcher] Token revoked for {module_id}")
+                # 记录审计日志
+                self._log_token_request("system", module_id, "revoke", True)
+
             ready_key = f"module.ready:{module_id}"
             ready_waiter = self._event_waiters.get(ready_key)
             if ready_waiter:
@@ -742,6 +843,42 @@ class Launcher:
                 ready_waiter[1]["_exited"] = True
                 ready_waiter[0].set()
 
+            # 处理主动退出场景（没有 shutdown 的情况）
+            if module_id not in self._module_states:
+                self._init_module_state(module_id)
+            state = self._module_states[module_id]
+
+            if not state.get("shutdown_sent"):
+                # 主动退出：记录信息
+                if not state.get("exiting_received"):
+                    state["exiting_received"] = True
+                    state["reason"] = data.get("reason", "active_exit")
+                    state["restart"] = data.get("restart", False)
+                    cleanup_timeout = data.get("cleanup_timeout", CLEANUP_TIMEOUT_DEFAULT)
+                    cleanup_timeout = max(CLEANUP_TIMEOUT_MIN, min(cleanup_timeout, CLEANUP_TIMEOUT_MAX))
+                    state["cleanup_timeout"] = cleanup_timeout
+
+                    # 启动清理超时任务
+                    async def cleanup_timeout_handler():
+                        await asyncio.sleep(state["cleanup_timeout"])
+                        if not state.get("stopped_sent"):
+                            state["stopped_sent"] = True
+                            self._kill_process(module_id)
+
+                            # 发送 stopped 事件
+                            await self._publish_event("module.stopped", {
+                                "module_id": module_id,
+                                "exit_code": -1,  # 超时强制终止，退出码未知
+                                "exit_type": "timeout",
+                                "reason": state.get("reason", "cleanup_timeout"),
+                                "restart": state.get("restart", False),
+                                "ready_received": False,
+                            })
+
+                            self._log_lifecycle("stopped", module_id, reason=state["reason"])
+
+                    state["cleanup_task"] = asyncio.create_task(cleanup_timeout_handler())
+
         # module.crash → print red crash summary
         if event == "module.crash" and module_id:
             RED = "\033[91m"
@@ -756,6 +893,45 @@ class Launcher:
             )
             print(f"[launcher] 崩溃日志: {crash_log}")
 
+        # pairing.status → handle all pairing flow events
+        if event == "pairing.status":
+            GREEN = "\033[92m"
+            RED = "\033[91m"
+            RESET = "\033[0m"
+
+            step = data.get("step", "")
+            success = data.get("success", True)
+
+            if step == "code_generated":
+                code = data.get("code", "")
+                expires_in = data.get("expires_in", 300)
+                module_id = data.get("module_id", "unknown")
+                if code:
+                    print(f"[launcher] {GREEN}配对码: {code}{RESET}")
+                    print(f"[launcher] {GREEN}有效期: {expires_in} 秒{RESET}")
+                    print(f"[launcher] {GREEN}来源模块: {module_id}{RESET}")
+                    print(f"[launcher] {GREEN}访问 Web 界面时使用此配对码进行配对{RESET}")
+
+            elif step == "pairing":
+                if success:
+                    print(f"[launcher] {GREEN}正在配对...{RESET}")
+                else:
+                    reason = data.get("reason", "Unknown error")
+                    print(f"[launcher] {RED}✗ 配对失败: {reason}{RESET}")
+
+            elif step == "completed":
+                if success:
+                    module_id = data.get("module_id", "")
+                    role = data.get("role", "")
+                    print(f"[launcher] {GREEN}✓ 配对成功！{RESET}")
+                    print(f"[launcher] {GREEN}  模块 ID: {module_id}{RESET}")
+                    print(f"[launcher] {GREEN}  角色: {role}{RESET}")
+                else:
+                    reason = data.get("reason", "Unknown error")
+                    print(f"[launcher] {RED}✗ 配对失败: {reason}{RESET}")
+
+            return
+
         # Only log system events (module.*, watchdog.*) to avoid flooding
         if not (event.startswith("module.") or event.startswith("watchdog.")):
             return
@@ -780,12 +956,18 @@ class Launcher:
         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,
+            "list_modules":     self._rpc_list_modules,
+            "start_module":     self._rpc_start_module,
+            "stop_module":      self._rpc_stop_module,
+            "restart_module":   self._rpc_restart_module,
+            "restart_launcher": self._rpc_restart_launcher,
+            "rescan":           self._rpc_rescan,
+            "shutdown":         self._rpc_shutdown,
+            "get_module_config":    self._rpc_get_module_config,
+            "update_module_config": self._rpc_update_module_config,
+            "reset_module_config":  self._rpc_reset_module_config,
+            "request_client_token": self._rpc_request_client_token,
+            "release_client_token": self._rpc_release_client_token,
         }
         handler = handlers.get(method)
         if handler:
@@ -807,20 +989,53 @@ class Launcher:
 
     async def _rpc_list_modules(self, params: dict) -> dict:
         """List all modules and their current status."""
+        # Get ping/pong latencies from Kernel
+        latencies = {}
+        try:
+            latencies_resp = await self._rpc_call(self._ws, "kernel.latencies", {}, timeout=2)
+            if "result" in latencies_resp:
+                latencies = latencies_resp["result"].get("latencies", {})
+        except Exception as e:
+            print(f"[launcher] Failed to get latencies: {e}")
+
+        current_time = time.time()
         result = []
         for name, info in self.modules.items():
             running = self.process_manager.is_running(name)
             rec = self.process_manager.get_record(name)
+
+            # Get latency info for this module
+            latency_info = latencies.get(name, {})
+            ping_status = latency_info.get("status", "never")
+
+            # Calculate uptime (running time in seconds)
+            uptime_seconds = None
+            if running and rec and rec.started_at:
+                uptime_seconds = current_time - rec.started_at
+
             result.append({
                 "name": name,
                 "display_name": info.display_name,
                 "type": info.type,
-                "config_state": info.state,
+                "state": info.state,  # 改名为 state（与 /api/modules 一致）
+                "version": info.version,
+                "runtime": info.runtime,
+                "preferred_port": info.preferred_port,
+                "monitor": info.monitor,
+                "display_order": info.display_order,
                 "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,
+                "startup_time": self._ready_times.get(name),  # Module startup time in seconds
+                "uptime_seconds": uptime_seconds,  # Running time in seconds
+                "ping_status": ping_status,
+                "ping_outbound_ms": latency_info.get("outbound"),
+                "ping_inbound_ms": latency_info.get("inbound"),
             })
+
+        # Sort by display_order (descending), then by name (ascending)
+        result.sort(key=lambda m: (-m["display_order"], m["name"]))
+
         return {"modules": result}
 
     async def _rpc_start_module(self, params: dict) -> dict:
@@ -911,30 +1126,243 @@ class Launcher:
         self._request_shutdown(f"RPC shutdown request: {reason}")
         return {"status": "shutting_down", "reason": reason}
 
+    async def _rpc_get_module_config(self, params: dict) -> dict:
+        """获取指定模块的配置（通用降级方案）"""
+        import re
+        import yaml
+        from pathlib import Path
+
+        module_name = params.get("module_name")
+        if not module_name:
+            raise ValueError("module_name required")
+
+        # 查找模块信息
+        info = self.modules.get(module_name)
+        if not info:
+            raise RuntimeError(f"Module '{module_name}' not found")
+
+        # 读取 module.md
+        md_path = Path(info.module_dir) / "module.md"
+        if not md_path.exists():
+            raise RuntimeError(f"module.md not found for '{module_name}'")
+
+        text = md_path.read_text(encoding="utf-8")
+        m = re.match(r'^---\s*\n(.*?)\n---\s*\n?(.*)', text, re.DOTALL)
+        if not m:
+            frontmatter = {}
+        else:
+            frontmatter = yaml.safe_load(m.group(1)) or {}
+
+        # 读取 config.yaml（如果存在）
+        config_path = Path(info.module_dir) / "config.yaml"
+        config = None
+        if config_path.exists():
+            config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+
+        return {
+            "name": frontmatter.get("name", module_name),
+            "display_name": frontmatter.get("display_name", ""),
+            "type": frontmatter.get("type", ""),
+            "state": frontmatter.get("state", "enabled"),
+            "version": frontmatter.get("version", ""),
+            "runtime": frontmatter.get("runtime", ""),
+            "entry": frontmatter.get("entry", ""),
+            "preferred_port": frontmatter.get("preferred_port"),
+            "advertise_ip": frontmatter.get("advertise_ip"),
+            "monitor": frontmatter.get("monitor"),
+            "events": frontmatter.get("events"),
+            "subscriptions": frontmatter.get("subscriptions"),
+            "depends_on": frontmatter.get("depends_on"),
+            "source_path": str(info.module_dir),  # 添加模块路径
+            "has_config": config is not None,
+            "config": config,
+        }
+
+    async def _rpc_update_module_config(self, params: dict) -> dict:
+        """更新指定模块的配置（通用降级方案）"""
+        import yaml
+        from pathlib import Path
+
+        module_name = params.get("module_name")
+        metadata = params.get("metadata", {})
+        config = params.get("config", {})
+
+        if not module_name:
+            raise ValueError("module_name required")
+
+        info = self.modules.get(module_name)
+        if not info:
+            raise RuntimeError(f"Module '{module_name}' not found")
+
+        md_path = Path(info.module_dir) / "module.md"
+        if not md_path.exists():
+            raise RuntimeError(f"module.md not found for '{module_name}'")
+
+        # 更新 module.md frontmatter
+        if metadata:
+            frontmatter, body = _parse_frontmatter(md_path.read_text(encoding="utf-8"))
+            for key, value in metadata.items():
+                frontmatter[key] = value
+            fm_str = yaml.dump(frontmatter, allow_unicode=True, sort_keys=False, default_flow_style=False).rstrip()
+            content = f"---\n{fm_str}\n---\n{body}"
+            md_path.write_text(content, encoding="utf-8")
+
+        # 更新 config.yaml
+        if config:
+            config_path = Path(info.module_dir) / "config.yaml"
+            existing = {}
+            if config_path.exists():
+                existing = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+            # Deep merge
+            self._deep_merge(existing, config)
+            config_path.write_text(
+                yaml.dump(existing, allow_unicode=True, sort_keys=False, default_flow_style=False),
+                encoding="utf-8"
+            )
+
+        # 重新扫描以更新缓存
+        await self._rescan_modules()
+
+        # 返回更新后的配置
+        return await self._rpc_get_module_config({"module_name": module_name})
+
+    async def _rpc_reset_module_config(self, params: dict) -> dict:
+        """恢复指定模块的默认配置（通用降级方案）"""
+        import yaml
+        from pathlib import Path
+
+        module_name = params.get("module_name")
+        fields = params.get("fields", [])
+        reset_all = params.get("all", False)
+
+        if not module_name:
+            raise ValueError("module_name required")
+
+        info = self.modules.get(module_name)
+        if not info:
+            raise RuntimeError(f"Module '{module_name}' not found")
+
+        md_path = Path(info.module_dir) / "module.md"
+        if not md_path.exists():
+            raise RuntimeError(f"module.md not found for '{module_name}'")
+
+        # 默认值定义（通用）
+        defaults = {
+            "state": "enabled",
+            "monitor": True,
+        }
+
+        frontmatter, body = _parse_frontmatter(md_path.read_text(encoding="utf-8"))
+
+        if reset_all:
+            for key, value in defaults.items():
+                frontmatter[key] = value
+        else:
+            for field in fields:
+                if field in defaults:
+                    frontmatter[field] = defaults[field]
+                elif field == "preferred_port":
+                    frontmatter.pop(field, None)  # 恢复为 null
+                elif field == "advertise_ip":
+                    frontmatter[field] = "127.0.0.1"
+
+        fm_str = yaml.dump(frontmatter, allow_unicode=True, sort_keys=False, default_flow_style=False).rstrip()
+        content = f"---\n{fm_str}\n---\n{body}"
+        md_path.write_text(content, encoding="utf-8")
+
+        # 重新扫描以更新缓存
+        await self._rescan_modules()
+
+        return await self._rpc_get_module_config({"module_name": module_name})
+
+    @staticmethod
+    def _deep_merge(base: dict, overlay: dict) -> dict:
+        """递归合并字典"""
+        for k, v in overlay.items():
+            if k in base and isinstance(base[k], dict) and isinstance(v, dict):
+                Launcher._deep_merge(base[k], v)
+            else:
+                base[k] = v
+        return base
+
+
+    async def _rpc_restart_launcher(self, params: dict) -> dict:
+        """Restart Launcher process via Watchdog.
+
+        Simply notify watchdog and exit. Watchdog will start a new instance.
+
+        Args:
+            params: {
+                "reason": str (optional) - Restart reason
+            }
+
+        Returns:
+            {"status": "restarting", "reason": str}
+            or {"error": "watchdog offline"}
+        """
+        reason = params.get("reason", "user_request")
+        O = "\033[33m"  # orange/yellow
+        R = "\033[0m"   # reset
+        print(f"{O}[launcher] 收到 Launcher 重启请求{R}")
+        print(f"[launcher] 原因: {reason}")
+
+        # Check if watchdog is running
+        watchdog_running = self.process_manager.is_running("watchdog")
+        print(f"[launcher] 检查 watchdog 状态: {'running' if watchdog_running else 'stopped'}")
+
+        if not watchdog_running:
+            error_msg = "watchdog 未运行, 无法重启"
+            print(f"[launcher] ❌ {error_msg}")
+            return {"error": error_msg}
+
+        print(f"[launcher] ✓ watchdog 状态正常，准备重启流程")
+
+        # Schedule restart in background (don't block RPC response)
+        async def _do_restart():
+            await asyncio.sleep(0.3)  # 确保 RPC 响应已发送
+
+            print(f"[launcher] 发送 module.exiting 事件给 watchdog...")
+
+            # Collect startup info for watchdog to restart with same environment
+            startup_info = {
+                "python": sys.executable,
+                "argv": sys.argv,
+                "cwd": os.getcwd(),
+                "env": dict(os.environ),  # 所有环境变量
+            }
+
+            # Notify watchdog: this is a planned restart, not a crash
+            await self._publish_event("module.exiting", {
+                "module_id": "launcher",
+                "action": "restart_launcher",
+                "reason": reason,
+                "startup_info": startup_info,
+            })
+
+            print(f"[launcher] 已通知 watchdog 计划内重启")
+            print(f"[launcher] 退出进程，等待 watchdog 重启")
+            print(f"[launcher] 原因: {reason}")
+
+            os._exit(0)
+
+        asyncio.create_task(_do_restart())
+
+        return {"status": "restarting", "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": {
+        try:
+            await self._rpc_call(self._ws, "event.publish", {
                 "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())
+            }, timeout=2.0)
+        except Exception as e:
+            print(f"[launcher] 发布事件失败 ({event_type}): {e}")
 
     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."""
@@ -956,90 +1384,299 @@ class Launcher:
         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)
+    # ── 退出机制辅助方法 ──
+
+    def _init_module_state(self, name: str):
+        """初始化模块状态跟踪字典"""
+        self._module_states[name] = {
+            "shutdown_sent": False,
+            "ack_received": False,
+            "exiting_received": False,
+            "ready_received": False,
+            "stopped_sent": False,
+            "exit_type": None,  # "graceful" | "non_graceful" | "active"
+            "reason": None,
+            "restart": None,
+            "cleanup_timeout": None,
+            "cleanup_task": None,
+        }
 
-        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,
-            })
+    def _kill_process(self, name: str):
+        """统一的进程杀死方法"""
+        record = self.process_manager.get_record(name)
+        if record and record.proc and record.proc.poll() is None:
+            print(f"[launcher] 强制终止 {name} (PID {record.proc.pid})")
+            self.process_manager.kill_process(name)
+        elif record:
+            # 进程已经退出，只是清理记录
+            pass
+        else:
+            # 没有记录，可能已经被清理
+            pass
+
+    def _determine_exit_type(self, name: str) -> str:
+        """判断退出类型: graceful | non_graceful | active"""
+        state = self._module_states.get(name, {})
+        if state.get("exiting_received"):
+            return "graceful"
+        elif state.get("shutdown_sent"):
+            return "non_graceful"
+        else:
+            return "active"
+
+    def _resolve_reason(self, name: str) -> str:
+        """解析最终原因（优先级：exiting > shutdown > 默认）"""
+        state = self._module_states.get(name, {})
+        if state.get("reason"):
+            return state["reason"]
+        return "unknown"
+
+    def _resolve_restart(self, name: str) -> bool:
+        """解析重启决策（优先级：exiting > shutdown > 默认）"""
+        state = self._module_states.get(name, {})
+        if state.get("restart") is not None:
+            return state["restart"]
+        # 默认：主动退出不重启，被动关闭看 desired_state
+        if self._determine_exit_type(name) == "active":
+            return False
+        return self._desired_states.get(name) == "running"
+
+    async def _send_stopped_event(self, name: str, exit_code: int):
+        """发送 module.stopped 事件（防重复）"""
+        state = self._module_states.get(name, {})
+        if state.get("stopped_sent"):
             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)
+        # 立即设置标记（防止竞态条件）
+        if name in self._module_states:
+            self._module_states[name]["stopped_sent"] = True
 
-        ready_key = f"module.shutdown.ready:{name}"
-        ready_evt = asyncio.Event()
-        ready_data = {}
-        self._event_waiters[ready_key] = (ready_evt, ready_data)
+        exit_type = self._determine_exit_type(name)
+        reason = self._resolve_reason(name)
+        restart = self._resolve_restart(name)
 
-        await self._publish_event("module.shutdown", {
-            "module_id": name, "reason": reason, "timeout": timeout,
+        await self._publish_event("module.stopped", {
+            "module_id": name,
+            "exit_code": exit_code,
+            "exit_type": exit_type,
+            "reason": reason,
+            "restart": restart,
+            "ready_received": state.get("ready_received", False),
         })
 
-        # Wait for ack
+    # ── 优雅关闭 ──
+
+    async def _graceful_stop(self, name: str, reason: str = "stop_requested", timeout: float = 10):
+        """优雅关闭单个模块：
+        1. 初始化状态跟踪
+        2. 非优雅模块直接 SIGTERM
+        3. 优雅模块：发送 shutdown → 等待 ack → 等待 exiting → 启动清理超时 → 杀死
+        """
         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)
+            self._log_lifecycle("stopping", name, reason=reason)
 
-        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", {
+            # 初始化状态
+            self._init_module_state(name)
+            state = self._module_states[name]
+
+            # 非优雅模块：直接 SIGTERM
+            if not self._graceful_modules.get(name):
+                state["shutdown_sent"] = True  # 标记：Launcher 主动关闭
+                state["stopped_sent"] = True   # 防重复标记
+                state["reason"] = reason
+                state["restart"] = self._desired_states.get(name) == "running"
+
+                self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_NON_GRACEFUL)
+
+                # 发送 stopped 事件
+                await self._publish_event("module.stopped", {
+                    "module_id": name,
+                    "exit_code": 0,
+                    "exit_type": "non_graceful",
+                    "reason": reason,
+                    "restart": state["restart"],
+                    "ready_received": False,
+                })
+
+                self._log_lifecycle("stopped", name, reason=reason)
+                return
+
+            # 优雅模块：提前注册所有三个 waiter（ack、exiting、ready）
+            # 这样可以避免事件到达时 waiter 还没注册的竞争条件
+            ack_key = f"module.shutdown.ack:{name}"
+            ack_evt = asyncio.Event()
+            ack_data = {}
+            self._event_waiters[ack_key] = (ack_evt, ack_data)
+
+            exiting_key = f"module.exiting:{name}"
+            exiting_evt = asyncio.Event()
+            exiting_data = {}
+            self._event_waiters[exiting_key] = (exiting_evt, exiting_data)
+
+            ready_key = f"module.shutdown.ready:{name}"
+            ready_evt = asyncio.Event()
+            ready_data = {}
+            self._event_waiters[ready_key] = (ready_evt, ready_data)
+
+            # 发送 shutdown 事件
+            state["shutdown_sent"] = True
+            state["reason"] = reason
+            state["restart"] = self._desired_states.get(name) == "running"
+
+            await self._publish_event("module.shutdown", {
                 "module_id": name,
-                "graceful_shutdown": self._graceful_modules.get(name, False),
+                "reason": reason,
+                "timeout": timeout,
+                "restart": state["restart"],
             })
-            return
 
-        estimated = min(ack.get("estimated_cleanup", timeout), timeout)
+            # 等待 ack
+            try:
+                await asyncio.wait_for(ack_evt.wait(), timeout=SHUTDOWN_TIMEOUT_ACK)
+                state["ack_received"] = True
+            except asyncio.TimeoutError:
+                pass
+            finally:
+                self._event_waiters.pop(ack_key, None)
 
-        # 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)
+            if not state["ack_received"]:
+                # 没有 ack，直接杀死
+                self._event_waiters.pop(exiting_key, None)
+                self._event_waiters.pop(ready_key, None)
+                state["stopped_sent"] = True
+                self._kill_process(name)
 
-        self._log_lifecycle("stopped", name, reason=reason)
-        await self._publish_event("module.stopped", {
-            "module_id": name,
-            "graceful_shutdown": self._graceful_modules.get(name, False),
-        })
+                # 发送 stopped 事件
+                await self._publish_event("module.stopped", {
+                    "module_id": name,
+                    "exit_code": -1,  # 未收到 ack，退出码未知
+                    "exit_type": "timeout",
+                    "reason": state["reason"],
+                    "restart": state["restart"],
+                    "ready_received": False,
+                })
+
+                self._log_lifecycle("stopped", name, reason=reason)
+                return
+
+            # 等待 exiting 事件
+            try:
+                await asyncio.wait_for(exiting_evt.wait(), timeout=SHUTDOWN_TIMEOUT_EXITING)
+                state["exiting_received"] = True
+                # 从 exiting 事件中提取信息
+                if exiting_data.get("reason"):
+                    state["reason"] = exiting_data["reason"]
+                if "restart" in exiting_data:
+                    state["restart"] = exiting_data["restart"]
+                cleanup_timeout = exiting_data.get("cleanup_timeout", CLEANUP_TIMEOUT_DEFAULT)
+                cleanup_timeout = max(CLEANUP_TIMEOUT_MIN, min(cleanup_timeout, CLEANUP_TIMEOUT_MAX))
+                state["cleanup_timeout"] = cleanup_timeout
+            except asyncio.TimeoutError:
+                pass
+            finally:
+                self._event_waiters.pop(exiting_key, None)
+
+            if not state["exiting_received"]:
+                # 没有 exiting，直接杀死
+                self._event_waiters.pop(ready_key, None)
+                state["stopped_sent"] = True
+                self._kill_process(name)
+
+                # 发送 stopped 事件
+                await self._publish_event("module.stopped", {
+                    "module_id": name,
+                    "exit_code": -1,  # 未收到 exiting，退出码未知
+                    "exit_type": "timeout",
+                    "reason": state["reason"],
+                    "restart": state["restart"],
+                    "ready_received": False,
+                })
+
+                self._log_lifecycle("stopped", name, reason=state["reason"])
+                return
+
+            # ready waiter 已经在前面注册好了，直接启动清理超时任务
+            # 启动清理超时任务（兜底机制）
+            async def cleanup_timeout_handler():
+                await asyncio.sleep(state["cleanup_timeout"])
+                if not state.get("stopped_sent"):
+                    print(f"[launcher] {name} 清理超时 ({state['cleanup_timeout']}s)，强制终止")
+                    state["stopped_sent"] = True
+                    self._kill_process(name)
+
+                    # 发送 stopped 事件
+                    await self._publish_event("module.stopped", {
+                        "module_id": name,
+                        "exit_code": -1,  # 清理超时，退出码未知
+                        "exit_type": "timeout",
+                        "reason": state["reason"],
+                        "restart": state["restart"],
+                        "ready_received": False,
+                    })
+
+                    self._log_lifecycle("stopped", name, reason=state["reason"])
+
+            state["cleanup_task"] = asyncio.create_task(cleanup_timeout_handler())
+
+            # 等待 ready 事件（主路径）
+            try:
+                await asyncio.wait_for(ready_evt.wait(), timeout=state["cleanup_timeout"])
+                state["ready_received"] = True
+                print(f"[launcher] {name} 清理完成，准备退出")
+            except asyncio.TimeoutError:
+                # 超时由 cleanup_timeout_handler 处理
+                pass
+            finally:
+                self._event_waiters.pop(ready_key, None)
+
+            # 取消清理超时任务（如果 ready 先到达）
+            if state.get("ready_received") and state["cleanup_task"] and not state["cleanup_task"].done():
+                state["cleanup_task"].cancel()
+
+            # 如果收到 ready，立即杀死进程
+            if state.get("ready_received") and not state.get("stopped_sent"):
+                state["stopped_sent"] = True
+                self._kill_process(name)
+
+                # 发送 stopped 事件
+                await self._publish_event("module.stopped", {
+                    "module_id": name,
+                    "exit_code": 0,  # 正常退出
+                    "exit_type": "graceful",
+                    "reason": state["reason"],
+                    "restart": state["restart"],
+                    "ready_received": True,
+                })
+
+                self._log_lifecycle("stopped", name, reason=state["reason"])
+
+        except Exception as e:
+            # 优雅关闭出错，强制终止进程
+            print(f"[launcher] 优雅关闭出错: {e}")
+            if not state.get("stopped_sent"):
+                state["stopped_sent"] = True
+                self._kill_process(name)
+                # 清理所有 waiters
+                self._event_waiters.pop(f"module.shutdown.ack:{name}", None)
+                self._event_waiters.pop(f"module.exiting:{name}", None)
+                self._event_waiters.pop(f"module.shutdown.ready:{name}", None)
 
     async def _graceful_shutdown_all(self):
-        """Shut down all modules. Order:
-        1. Send module.exiting for Launcher itself (so Watchdog knows it's intentional)
-        2. Send shutdown to graceful modules (excl. Kernel) — let them start cleanup
-        3. Terminate non-graceful modules (fast, runs during graceful cleanup)
-        4. Wait for graceful modules to exit (process monitoring)
-        5. Shut down Kernel last (keeps event routing alive throughout)
+        """全量优雅退出：三阶段关闭
+
+        Phase 1: 先关闭 Watchdog（防止它监控到其他模块退出后触发重启）
+        Phase 2: 关闭其他所有模块（除 Kernel）
+        Phase 3: 最后关闭 Kernel（保证事件路由畅通）
         """
         self._system_shutting_down = True
 
-        # Send module.exiting for Launcher before anything else
+        # 发送 Launcher 自己的 exiting 事件
         await self._publish_event("module.exiting", {
             "module_id": "launcher",
+            "type": "active",
             "reason": "system_shutdown",
             "action": "none",
+            "timeout": 0,
         })
 
         running = [n for n in self.modules if self.process_manager.is_running(n)]
@@ -1047,88 +1684,144 @@ class Launcher:
         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)]
+        # 分组：Watchdog、Kernel、其他模块
+        watchdog_running = WATCHDOG_MODULE_NAME in running
+        kernel_running = "kernel" in running
+        other_modules = [n for n in running if n not in (WATCHDOG_MODULE_NAME, "kernel")]
+
+        graceful_others = [n for n in other_modules if self._graceful_modules.get(n)]
+        non_graceful_others = [n for n in other_modules if not self._graceful_modules.get(n)]
+
+        print(f"[launcher] 正在关闭 {len(running)} 个模块（三阶段）")
+
+        # ═══════════════════════════════════════════════════════════
+        # Phase 1: 先关闭 Watchdog（防止重启其他模块）
+        # ═══════════════════════════════════════════════════════════
+        if watchdog_running and self.process_manager.is_running(WATCHDOG_MODULE_NAME):
+            print(f"[launcher] Phase 1: 通知 Watchdog 退出（防止重启其他模块）")
+
+            if self._graceful_modules.get(WATCHDOG_MODULE_NAME):
+                # Watchdog 支持优雅退出
+                self._init_module_state(WATCHDOG_MODULE_NAME)
+                state = self._module_states[WATCHDOG_MODULE_NAME]
+                state["shutdown_sent"] = True
+                state["reason"] = "system_shutdown"
+                state["restart"] = False
+                self._log_lifecycle("stopping", WATCHDOG_MODULE_NAME, reason="system_shutdown")
+
+                await self._publish_event("module.shutdown", {
+                    "module_id": WATCHDOG_MODULE_NAME,
+                    "reason": "system_shutdown",
+                    "timeout": 5,
+                    "restart": False,
+                })
+
+                # 等待 0.2 秒确保事件送达（不需要等待进程退出）
+                await asyncio.sleep(0.2)
+                print(f"[launcher] Watchdog shutdown 事件已发送")
+            else:
+                # 直接终止
+                self._init_module_state(WATCHDOG_MODULE_NAME)
+                state = self._module_states[WATCHDOG_MODULE_NAME]
+                state["shutdown_sent"] = True
+                state["stopped_sent"] = True
+                state["reason"] = "system_shutdown"
+                state["restart"] = False
+                self._log_lifecycle("stopping", WATCHDOG_MODULE_NAME, reason="system_shutdown")
 
-        # 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
+                self.process_manager.stop_module(WATCHDOG_MODULE_NAME, timeout=SHUTDOWN_TIMEOUT_NON_GRACEFUL)
 
-        print(f"[launcher] 正在关闭 {len(running)} 个模块: {', '.join(running)}")
+                await self._publish_event("module.stopped", {
+                    "module_id": WATCHDOG_MODULE_NAME,
+                    "exit_code": 0,
+                    "exit_type": "non_graceful",
+                    "reason": "system_shutdown",
+                    "restart": False,
+                    "ready_received": False,
+                })
 
-        # Phase 1: Notify graceful modules first (they start cleanup immediately)
-        for name in graceful_batch:
+                self._log_lifecycle("stopped", WATCHDOG_MODULE_NAME, reason="system_shutdown")
+
+        # ═══════════════════════════════════════════════════════════
+        # Phase 2: 关闭其他所有模块（除 Kernel）
+        # ═══════════════════════════════════════════════════════════
+        if graceful_others or non_graceful_others:
+            print(f"[launcher] Phase 2: 关闭其他模块（{len(graceful_others)} 优雅 + {len(non_graceful_others)} 非优雅）")
+
+        # 通知优雅模块
+        for name in graceful_others:
+            self._init_module_state(name)
+            state = self._module_states[name]
+            state["shutdown_sent"] = True
+            state["reason"] = "system_shutdown"
+            state["restart"] = False
             self._log_lifecycle("stopping", name, reason="system_shutdown")
             await self._publish_event("module.shutdown", {
-                "module_id": name, "reason": "system_shutdown", "timeout": 5,
+                "module_id": name,
+                "reason": "system_shutdown",
+                "timeout": 5,
+                "restart": False,
             })
 
-        # 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:
+        # 终止非优雅模块
+        for name in non_graceful_others:
+            self._init_module_state(name)
+            state = self._module_states[name]
+            state["shutdown_sent"] = True
+            state["stopped_sent"] = True
+            state["reason"] = "system_shutdown"
+            state["restart"] = False
             self._log_lifecycle("stopping", name, reason="system_shutdown")
-            self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_PARTIAL)
+
+            self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_NON_GRACEFUL)
+
+            await self._publish_event("module.stopped", {
+                "module_id": name,
+                "exit_code": 0,
+                "exit_type": "non_graceful",
+                "reason": "system_shutdown",
+                "restart": False,
+                "ready_received": False,
+            })
+
             self._log_lifecycle("stopped", name, reason="system_shutdown")
 
-        # Phase 3: Wait for graceful modules to exit (process monitoring)
-        if graceful_batch:
+        # 等待优雅模块退出（包括 Watchdog）
+        all_graceful = graceful_others + ([WATCHDOG_MODULE_NAME] if watchdog_running and self._graceful_modules.get(WATCHDOG_MODULE_NAME) else [])
+        if all_graceful:
             deadline = time.time() + 5
             while time.time() < deadline:
-                still_running = [n for n in graceful_batch if self.process_manager.is_running(n)]
+                still_running = [n for n in all_graceful if self.process_manager.is_running(n)]
                 if not still_running:
-                    print("[launcher] 所有优雅退出模块已自行退出")
+                    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:
+
+            # 强杀未退出的
+            for name in all_graceful:
                 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")
+                    print(f"[launcher] {name} 超时，强制终止")
+                    self.process_manager.stop_module(name, timeout=SHUTDOWN_TIMEOUT_NON_GRACEFUL)
+                    self._log_lifecycle("stopped", name, reason="system_shutdown_timeout")
 
-        # 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...")
+        # ═══════════════════════════════════════════════════════════
+        # Phase 3: 最后关闭 Kernel（使用标准优雅退出流程）
+        # ═══════════════════════════════════════════════════════════
+        if kernel_running and self.process_manager.is_running("kernel"):
+            print("[launcher] Phase 3: 关闭 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._desired_states["kernel"] = "stopped"
 
-            self._log_lifecycle("stopped", "kernel", reason="system_shutdown")
+            # 使用标准优雅退出流程（内含等待 ack → exiting → ready → kill 完整逻辑）
+            await self._graceful_stop("kernel", reason="system_shutdown", timeout=5)
 
         # Final safety net
         try:
@@ -1247,8 +1940,11 @@ class Launcher:
             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)")
+            # Use startup_time from module.ready event (module's self-reported startup time)
+            startup_time = ready.get("startup_time", elapsed)
+            self._ready_times[info.name] = startup_time
+            startup_str = f"{startup_time:.3f}s" if startup_time < 10 else f"{startup_time:.2f}s"
+            print(f"[launcher] 模块 '{info.name}' 已就绪 ({startup_str})")
         else:
             print(f"\033[91m[launcher] 警告: '{info.name}' 在 {timeout}s 内未发送 module.ready\033[0m")
 
@@ -1282,7 +1978,7 @@ class Launcher:
         # 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"):
+            if "result" in result:
                 tokens = result["result"].get("tokens", {})
                 self._module_tokens.update(tokens)
                 print(f"[launcher] Kernel 已生成 {len(tokens)} 个模块令牌")
@@ -1297,7 +1993,7 @@ class Launcher:
             return
         try:
             result = await self._rpc_call(self._ws, "kernel.register_tokens", tokens)
-            if result.get("result", {}).get("ok"):
+            if "result" in result:
                 print(f"[launcher] 已注册 {len(tokens)} 个模块令牌")
             elif "error" in result:
                 print(f"[launcher] 警告: 令牌注册失败: {result['error'].get('message', '')}")
@@ -1381,10 +2077,19 @@ class Launcher:
                 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),
-                })
+
+                # 检查是否已发送 stopped 事件
+                state = self._module_states.get(name, {})
+                if not state.get("stopped_sent"):
+                    # 取消清理超时任务（如果有）
+                    if state.get("cleanup_task"):
+                        state["cleanup_task"].cancel()
+                    # 发送 stopped 事件
+                    await self._send_stopped_event(name, rc)
+
+                # 无论是否发送，都清理状态（防止内存泄漏）
+                self._module_states.pop(name, None)
+
                 info = self.modules.get(name)
 
                 # 1) Core module crash → full restart
@@ -1524,9 +2229,6 @@ class Launcher:
             started_at=self._start_unix,
         )
         running.append(("launcher", launcher_info, launcher_rec))
-        # Launcher is ready immediately (ready_time = 0)
-        if "launcher" not in self._ready_times:
-            self._ready_times["launcher"] = 0.0
 
         for name, info in self.modules.items():
             rec = self.process_manager.get_record(name)
@@ -1597,7 +2299,16 @@ class Launcher:
         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 "—"
+            # Format startup time with ms/s auto-switch
+            if ready_t is not None:
+                if ready_t < 1:
+                    time_str = f"{ready_t * 1000:.0f}ms"
+                elif ready_t < 10:
+                    time_str = f"{ready_t:.2f}s"
+                else:
+                    time_str = f"{ready_t:.1f}s"
+            else:
+                time_str = "—"
 
             # Calculate elapsed from start
             if ready_t is not None and hasattr(self, '_start_unix'):
@@ -1669,18 +2380,53 @@ class Launcher:
 
         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}")
+        # Check if web or evol modules are running and display their URLs
+        RED = "\033[91m"
+        running_names = {name for name, _, _ in running}
+
+        # Check web module
+        if "web" in running_names:
+            web_url = ""
+            web_error = ""
+            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:")
+                    else:
+                        web_error = "未注册到 Kernel Registry"
+                except Exception as e:
+                    web_error = f"查询失败: {str(e)}"
+            else:
+                web_error = "Kernel 连接不可用"
+
+            if web_url:
+                lines.append(f"{B}  Web 管理后台: {web_url}{R}")
+            else:
+                lines.append(f"{RED}  Web 管理后台: {web_error}{R}")
+
+        # Check evol module
+        if "evol" in running_names:
+            evol_url = ""
+            evol_error = ""
+            if self._ws:
+                try:
+                    resp = await self._rpc_call(self._ws, "registry.get", {"path": "evol.api_endpoint"}, timeout=3)
+                    val = resp.get("result", {}).get("value")
+                    if val and isinstance(val, str):
+                        evol_url = val.replace("://127.0.0.1:", "://localhost:")
+                    else:
+                        evol_error = "未注册到 Kernel Registry"
+                except Exception as e:
+                    evol_error = f"查询失败: {str(e)}"
+            else:
+                evol_error = "Kernel 连接不可用"
+
+            if evol_url:
+                lines.append(f"{B}  Evol: {evol_url}{R}")
+            else:
+                lines.append(f"{RED}  Evol: {evol_error}{R}")
 
         # Instance info
         instances = self.process_manager.get_alive_instances()
@@ -1691,7 +2437,18 @@ class Launcher:
         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}")
+
+        # Check for abnormal working directory
+        cwd_lower = cwd.lower()
+        is_abnormal_cwd = (
+            "windowsapps" in cwd_lower or
+            "appdata\\local\\temp" in cwd_lower or
+            not os.path.exists(os.path.join(cwd, "main.py"))
+        )
+        if is_abnormal_cwd:
+            lines.append(f"\033[91m  工作目录: {cwd} ⚠️ 异常路径{R}")
+        else:
+            lines.append(f"{G}  工作目录: {cwd}{R}")
         if len(instances) > 1:
             lines.append(f"{G}  所有实例:{R}")
             for i in instances:
@@ -1733,6 +2490,155 @@ class Launcher:
 
         print("\n".join(lines))
 
+    async def _rpc_request_client_token(self, params: dict) -> dict:
+        """为 relay 模块申请虚拟客户端 Token.
+
+        Args:
+            params: {
+                "module_id": str - 虚拟模块 ID (如 "web-client-a3f9e2")
+                "_caller_id": str - 调用者模块 ID (由 Kernel 注入)
+            }
+
+        Returns:
+            {
+                "token": str - Kernel Token (64 字符 hex)
+                "module_id": str - 虚拟模块 ID
+            }
+
+        Raises:
+            PermissionError: 调用者不在白名单中
+            ValueError: module_id 格式不合法或已存在
+            RuntimeError: Token 限额已满
+        """
+        import re
+
+        # 1. 获取调用者 ID
+        caller_id = params.get("_caller_id")
+        if not caller_id:
+            raise PermissionError("Missing _caller_id in params")
+
+        # 2. 权限检查
+        if caller_id not in self._relay_modules:
+            print(f"[launcher] DEBUG: 权限检查失败 - caller_id={caller_id}, relay_modules={self._relay_modules}")
+            raise PermissionError(f"Permission denied: {caller_id} not in relay_modules whitelist")
+
+        # 3. 参数验证
+        module_id = params.get("module_id")
+        if not module_id:
+            raise ValueError("module_id is required")
+
+        # 4. 命名规范验证
+        expected_prefix = f"{caller_id}-client-"
+        if not module_id.startswith(expected_prefix):
+            raise ValueError(f"module_id must start with {expected_prefix}")
+
+        suffix = module_id[len(expected_prefix):]
+        if not re.match(r'^[a-zA-Z0-9_-]+$', suffix):
+            raise ValueError("Invalid module_id suffix")
+
+        # 5. 检查是否已存在（幂等）
+        if module_id in self._client_tokens:
+            print(f"[launcher] Token already exists for {module_id}, returning existing token")
+            return {
+                "token": self._client_tokens[module_id],
+                "module_id": module_id
+            }
+
+        # 6. 检查限额
+        limit = self._relay_token_limits.get(caller_id, 100)
+        current_count = sum(1 for mid in self._client_tokens if mid.startswith(expected_prefix))
+        if current_count >= limit:
+            raise RuntimeError(f"Token limit reached: {current_count}/{limit}")
+
+        # 7. 生成 token
+        token = secrets.token_hex(32)
+
+        # 8. 注册到 Kernel
+        try:
+            result = await self._rpc_call(self._ws, "kernel.register_tokens", {module_id: token})
+            if "error" in result:
+                raise RuntimeError(f"Failed to register token: {result['error'].get('message', '')}")
+        except Exception as e:
+            raise RuntimeError(f"Failed to register token to Kernel: {e}")
+
+        # 9. 保存到本地映射
+        self._client_tokens[module_id] = token
+
+        # 10. 记录审计日志
+        self._log_token_request(caller_id, module_id, "request", True)
+
+        print(f"[launcher] Token generated for {module_id} (caller: {caller_id})")
+
+        return {
+            "token": token,
+            "module_id": module_id
+        }
+
+    async def _rpc_release_client_token(self, params: dict) -> dict:
+        """释放虚拟客户端 Token (可选).
+
+        Args:
+            params: {
+                "module_id": str - 虚拟模块 ID
+                "_caller_id": str - 调用者模块 ID (由 Kernel 注入)
+            }
+
+        Returns:
+            {}
+
+        Raises:
+            PermissionError: 调用者不在白名单中或 module_id 不属于调用者
+            ValueError: module_id 格式不合法
+        """
+        # 1. 获取调用者 ID
+        caller_id = params.get("_caller_id")
+        if not caller_id:
+            raise PermissionError("Missing _caller_id in params")
+
+        # 2. 权限检查
+        if caller_id not in self._relay_modules:
+            print(f"[launcher] DEBUG: 权限检查失败 - caller_id={caller_id}, relay_modules={self._relay_modules}")
+            raise PermissionError(f"Permission denied: {caller_id} not in relay_modules whitelist")
+
+        # 3. 参数验证
+        module_id = params.get("module_id")
+        if not module_id:
+            raise ValueError("module_id is required")
+
+        # 4. 验证所有权
+        expected_prefix = f"{caller_id}-client-"
+        if not module_id.startswith(expected_prefix):
+            raise ValueError(f"module_id does not belong to {caller_id}")
+
+        # 5. 删除 token
+        if module_id in self._client_tokens:
+            del self._client_tokens[module_id]
+            print(f"[launcher] Token released for {module_id} (caller: {caller_id})")
+
+        # 6. 记录审计日志
+        self._log_token_request(caller_id, module_id, "release", True)
+
+        return {}
+
+    def _log_token_request(self, caller_id: str, module_id: str, action: str, success: bool):
+        """记录 Token 申请/释放审计日志."""
+        from datetime import datetime, timezone
+        record = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "caller_id": caller_id,
+            "module_id": module_id,
+            "action": action,
+            "success": success
+        }
+        try:
+            log_dir = os.path.join(os.environ.get("KITE_MODULE_DATA", ""), "log")
+            os.makedirs(log_dir, exist_ok=True)
+            log_file = os.path.join(log_dir, "token_requests.jsonl")
+            with open(log_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(record, ensure_ascii=False) + "\n")
+        except Exception as e:
+            print(f"[launcher] 警告: 写入 token 审计日志失败: {e}")
+
     # ── Utilities ──
 
     def _load_discovery(self) -> dict | None:
@@ -1748,6 +2654,22 @@ class Launcher:
             print(f"[launcher] 警告: 读取发现配置失败: {e}")
         return None
 
+    def _load_relay_config(self) -> dict:
+        """Read relay 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())
+            relay = fm.get("relay")
+            if isinstance(relay, dict) and relay:
+                print(f"[launcher] Relay 配置已加载: modules={relay.get('modules')}, token_limits={relay.get('token_limits')}")
+                return relay
+            else:
+                print(f"[launcher] 警告: relay 配置为空或格式错误")
+        except Exception as e:
+            print(f"[launcher] 警告: 读取 relay 配置失败: {e}")
+        return {}
+
     def _log_lifecycle(self, event: str, module: str, **extra):
         """Append one JSONL line to lifecycle.jsonl."""
         from datetime import datetime, timezone
@@ -1760,6 +2682,30 @@ class Launcher:
         except Exception:
             pass
 
+    def _record_launcher_startup(self):
+        """Record launcher startup information to lifecycle.jsonl."""
+        import sys
+        from datetime import datetime, timezone
+
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "event": "launcher_startup",
+            "module": "launcher",
+            "pid": os.getpid(),
+            "cwd": os.getcwd(),
+            "argv": sys.argv,
+            "instance_dir": os.environ.get("KITE_INSTANCE_DIR", ""),
+            "instance_suffix": self.process_manager.instance_suffix,
+            "python": sys.executable,
+        }
+
+        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):