@agentunion/kite 1.3.2 → 1.4.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"}
@@ -101,6 +112,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 +131,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'."""
@@ -597,6 +614,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 +630,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=20, ping_timeout=20, 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,10 +654,38 @@ 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": "关闭系统"},
+                            },
+                            "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": [">"],
                 })
@@ -658,7 +708,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 +733,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)
@@ -728,6 +786,7 @@ class Launcher:
         # 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)
@@ -742,6 +801,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 +851,43 @@ 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)
+                if code:
+                    print(f"[launcher] {GREEN}配对码: {code}{RESET}")
+                    print(f"[launcher] {GREEN}有效期: {expires_in} 秒{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 +912,16 @@ 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,
         }
         handler = handlers.get(method)
         if handler:
@@ -815,11 +951,14 @@ class Launcher:
                 "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,
                 "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}
 
@@ -911,30 +1050,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 +1308,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 +1608,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:
@@ -1282,7 +1899,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 +1914,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 +1998,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
@@ -1691,7 +2317,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:
@@ -1760,6 +2397,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):