@agentunion/kite 1.0.7 → 1.3.0

package/core/launcher/entry.py

@@ -1,1158 +0,0 @@
-"""
-Launcher — the core of Kite. Manages module lifecycle, exposes API, monitors processes.
-
-Thread model:
-- Main thread: asyncio event loop (process management + monitor loop)
-- API thread: independent thread running uvicorn + FastAPI
-- stdout threads: one daemon thread per child process (ProcessManager)
-- (Windows) keyboard listener thread: polls for 'q' key
-
-4-Phase startup:
-  Phase 1: Registry → stdout port → KITE_REGISTRY_PORT → API → register self + tokens
-  Phase 2: Event Hub → stdin launcher_ws_token → stdout ws_endpoint → WS connect → module.ready
-  Phase 3: Event Hub → Registry → Registry → Event Hub WS → module.ready
-  Phase 4: start remaining enabled modules in topo order
-"""
-
-import asyncio
-import json
-import os
-import secrets
-import signal
-import sys
-import threading
-import time
-import uuid
-
-import httpx
-import uvicorn
-import websockets
-from fastapi import FastAPI, HTTPException
-
-from .module_scanner import ModuleScanner, ModuleInfo, LaunchConfig, _parse_frontmatter
-from .process_manager import ProcessManager
-
-IS_WINDOWS = sys.platform == "win32"
-
-# Core module names that are started in Phase 1-2 (not Phase 4)
-CORE_MODULE_NAMES = {"registry", "event_hub"}
-
-
-class Launcher:
-    """Kite system entry point. Starts Registry, manages modules, exposes API."""
-
-    def __init__(self, kite_token: str):
-        self.kite_token = kite_token
-        self.instance_id = str(os.getpid())
-        os.environ["KITE_INSTANCE"] = self.instance_id
-
-        # Resolve instance workspace (must happen before ProcessManager init)
-        self._resolve_instance_dir()
-        os.environ["KITE_MODULE_DATA"] = os.path.join(
-            os.environ["KITE_INSTANCE_DIR"], "launcher",
-        )
-
-        self.process_manager = ProcessManager(
-            kite_token, self.instance_id,
-            on_kite_message=self._on_kite_message,
-        )
-        self.module_scanner = ModuleScanner(
-            discovery=self._load_discovery(),
-        )
-
-        self.registry_port: int = 0
-        self.api_port: int = 0
-        self.modules: dict[str, ModuleInfo] = {}
-        self._shutdown_event = asyncio.Event()
-        self._thread_shutdown = threading.Event()
-        self._api_server: uvicorn.Server | None = None
-        self._api_ready = threading.Event()
-        self._fail_counts: dict[str, int] = {}  # module_name -> consecutive failure count
-        self._module_tokens: dict[str, str] = {}  # module_name -> per-module token
-
-        # Three-layer state model: desired_state per module
-        self._desired_states: dict[str, str] = {}  # module_name -> "running" | "stopped"
-
-        # Event Hub WebSocket client
-        self._event_hub_ws_url: str = ""
-        self._launcher_ws_token: str = ""
-        self._ws: object | None = None
-        self._ws_task: asyncio.Task | None = None
-        self._loop: asyncio.AbstractEventLoop | None = None
-
-        # Event waiters: {event_key: (asyncio.Event, data_dict)}
-        self._event_waiters: dict[str, tuple[asyncio.Event, 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]] = {}
-
-        self._lifecycle_log = os.path.join(
-            os.environ["KITE_INSTANCE_DIR"], "launcher", "lifecycle.jsonl",
-        )
-        self._app = self._create_api_app()
-
-    # ── Instance workspace resolution ──
-
-    @staticmethod
-    def _resolve_instance_dir():
-        """Resolve KITE_INSTANCE_DIR from KITE_WORKSPACE + KITE_CWD.
-        Algorithm: take CWD basename, find matching dir in workspace via .cwd file,
-        or create new one. Sets KITE_INSTANCE_DIR env var.
-        """
-        if os.environ.get("KITE_INSTANCE_DIR"):
-            return  # already set (e.g. by tests or parent)
-
-        cwd = os.environ.get("KITE_CWD", os.getcwd())
-        workspace = os.environ.get("KITE_WORKSPACE", "")
-        if not workspace:
-            home = os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~")
-            workspace = os.path.join(home, ".kite", "workspace")
-            os.environ["KITE_WORKSPACE"] = workspace
-
-        basename = os.path.basename(cwd.rstrip(os.sep)) or "default"
-        suffix = 0
-
-        while True:
-            name = basename if suffix == 0 else f"{basename}~{suffix}"
-            candidate = os.path.join(workspace, name)
-            cwd_file = os.path.join(candidate, ".cwd")
-
-            if not os.path.exists(candidate):
-                # Empty slot — create new workspace
-                os.makedirs(candidate, exist_ok=True)
-                with open(cwd_file, "w", encoding="utf-8") as f:
-                    f.write(cwd)
-                os.environ["KITE_INSTANCE_DIR"] = candidate
-                print(f"[launcher] 实例工作区已创建: {candidate}")
-                return
-
-            if os.path.isfile(cwd_file):
-                try:
-                    with open(cwd_file, "r", encoding="utf-8") as f:
-                        if f.read().strip() == cwd:
-                            os.environ["KITE_INSTANCE_DIR"] = candidate
-                            print(f"[launcher] 实例工作区已找到: {candidate}")
-                            return
-                except Exception:
-                    pass
-
-            suffix += 1
-
-    # ── Kite stdout message callback ──
-
-    def _on_kite_message(self, module_name: str, msg: dict):
-        """Called by ProcessManager stdout reader thread when a kite message is detected.
-        Thread-safe: only touches _msg_waiters (dict + threading.Event).
-        """
-        kite_type = msg.get("kite", "")
-        key = f"{module_name}:{kite_type}"
-        waiter = self._msg_waiters.get(key)
-        if waiter:
-            waiter[1].update(msg)
-            waiter[0].set()
-
-    async def _wait_kite_message(self, module_name: str, kite_type: str,
-                                  timeout: float) -> dict | None:
-        """Wait for a kite stdout message from a module. Returns msg dict or None on timeout.
-        Checks shutdown flag every 0.5s so Ctrl+C is responsive even during Phase 1-2 waits.
-        """
-        key = f"{module_name}:{kite_type}"
-        evt = threading.Event()
-        data = {}
-        self._msg_waiters[key] = (evt, data)
-        shutdown = self._thread_shutdown
-        try:
-            def _wait():
-                deadline = time.monotonic() + timeout
-                while time.monotonic() < deadline:
-                    if evt.wait(timeout=0.5):
-                        return True
-                    if shutdown.is_set():
-                        return False
-                return False
-            got = await asyncio.get_running_loop().run_in_executor(None, _wait)
-            return data if got else None
-        finally:
-            self._msg_waiters.pop(key, None)
-
-    # ── Public entry ──
-
-    def run(self):
-        """Synchronous entry point. Sets up signals, runs the async main loop."""
-        print("[launcher] Kite 启动中...")
-        print("[launcher] ── 环境变量 ──")
-        for key in sorted(k for k in os.environ if k.startswith("KITE_")):
-            print(f"[launcher]   {key} = {os.environ[key]}")
-        print(f"[launcher]   PID = {os.getpid()}")
-        print(f"[launcher]   PYTHON = {sys.executable}")
-        print(f"[launcher]   PLATFORM = {sys.platform}")
-
-        if IS_WINDOWS:
-            self._setup_windows_exit()
-        else:
-            self._setup_unix_signals()
-
-        try:
-            asyncio.run(self._async_main())
-        except KeyboardInterrupt:
-            pass
-        finally:
-            self._final_cleanup()
-
-    def _request_shutdown(self, reason: str = ""):
-        """Request graceful shutdown. Thread-safe — can be called from signal handler or any thread."""
-        if self._thread_shutdown.is_set():
-            return  # already shutting down
-        print(f"\n[launcher] {reason or '收到关闭请求'}")
-        self._thread_shutdown.set()
-        # Wake up asyncio event loop immediately (so _monitor_loop / wait_for exits)
-        loop = self._loop
-        if loop and not loop.is_closed():
-            try:
-                loop.call_soon_threadsafe(self._shutdown_event.set)
-            except RuntimeError:
-                pass
-        # Safety net: force exit after 15s no matter what
-        def _force():
-            time.sleep(15)
-            os._exit(1)
-        threading.Thread(target=_force, daemon=True).start()
-
-    def _setup_unix_signals(self):
-        """Register SIGTERM/SIGINT handlers on Linux/macOS."""
-        def _handler(signum, frame):
-            self._request_shutdown(f"收到信号 {signum}，正在关闭...")
-        signal.signal(signal.SIGTERM, _handler)
-        signal.signal(signal.SIGINT, _handler)
-
-    def _setup_windows_exit(self):
-        """SetConsoleCtrlHandler for Ctrl+C + daemon thread for 'q' key.
-
-        Why not signal.signal(SIGINT)?
-        Python's signal delivery requires the main thread to be executing bytecode.
-        When the main thread is blocked in C code (asyncio ProactorEventLoop →
-        GetQueuedCompletionStatus), SIGINT is never delivered.
-        SetConsoleCtrlHandler runs its callback in a separate OS thread, so it
-        always works regardless of what the main thread is doing.
-        """
-        import ctypes
-
-        @ctypes.WINFUNCTYPE(ctypes.c_int, ctypes.c_uint)
-        def _ctrl_handler(ctrl_type):
-            if ctrl_type in (0, 1):  # CTRL_C_EVENT, CTRL_BREAK_EVENT
-                self._request_shutdown("收到 Ctrl+C，正在关闭...")
-                return 1  # handled — prevent default (which kills the process)
-            return 0
-
-        # prevent GC of the C callback
-        self._ctrl_handler_ref = _ctrl_handler
-        ctypes.windll.kernel32.SetConsoleCtrlHandler(_ctrl_handler, 1)
-
-        # 'q' key: handle via msvcrt polling
-        def _listen():
-            import msvcrt
-            while not self._thread_shutdown.is_set():
-                if msvcrt.kbhit():
-                    ch = msvcrt.getch()
-                    if ch in (b'q', b'Q'):
-                        self._request_shutdown("收到退出请求，正在关闭...")
-                        return
-                time.sleep(0.1)
-        threading.Thread(target=_listen, daemon=True).start()
-
-    # ── Async main (4-Phase startup) ──
-
-    async def _async_main(self):
-        """Full 4-phase startup sequence, then monitor loop."""
-        self._loop = asyncio.get_running_loop()
-
-        # Validate core modules exist (mechanism 12)
-        self._validate_core_modules()
-
-        # Cleanup leftovers from previous instances
-        self.process_manager.cleanup_leftovers()
-
-        # Phase 1: Registry bootstrap
-        await self._phase1_registry()
-        if self._shutdown_event.is_set(): return
-
-        # Scan modules (can happen before Phase 2)
-        self.modules = self.module_scanner.scan()
-        for name, info in self.modules.items():
-            self._log_lifecycle("scanned", name, state=info.state, module_dir=info.module_dir)
-        print(f"[launcher] 发现 {len(self.modules)} 个模块: {', '.join(self.modules.keys()) or '(无)'}")
-
-        # Generate per-module tokens (including event_hub and registry)
-        await self._register_module_tokens()
-        if self._shutdown_event.is_set(): return
-
-        # Phase 2: Event Hub bootstrap
-        await self._phase2_event_hub()
-        if self._shutdown_event.is_set(): return
-
-        # Phase 3: Wait for Registry delayed ready
-        await self._phase3_registry_ready()
-        if self._shutdown_event.is_set(): return
-
-        # Phase 4: Start remaining enabled modules
-        # Initialize desired_state from config_state
-        for name, info in self.modules.items():
-            if info.state == "enabled":
-                self._desired_states[name] = "running"
-            else:  # manual, disabled
-                self._desired_states[name] = "stopped"
-        # Core modules are already running
-        for cn in CORE_MODULE_NAMES:
-            self._desired_states[cn] = "running"
-
-        await self._phase4_start_modules()
-        if self._shutdown_event.is_set(): return
-
-        # Post-startup
-        self.process_manager.persist_records()
-        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
-
-        print("[launcher] 进入监控循环 (按 Ctrl+C 或 'q' 退出)")
-        await self._monitor_loop()
-
-        await self._graceful_shutdown_all()
-
-    # ── Phase 1: Registry ──
-
-    async def _phase1_registry(self):
-        """Start Registry → capture port from stdout → set env → start API → register self."""
-        registry_dir = os.path.join(os.environ["KITE_PROJECT"], "core", "registry")
-        registry_info = ModuleInfo(
-            name="registry",
-            display_name="Registry",
-            type="infrastructure",
-            state="enabled",
-            runtime="python",
-            entry="entry.py",
-            module_dir=registry_dir,
-        )
-
-        boot_info = {"token": self.kite_token}
-        self._log_lifecycle("starting", "registry")
-        ok = self.process_manager.start_module(registry_info, boot_info=boot_info)
-        if not ok:
-            self._log_lifecycle("start_failed", "registry")
-            raise RuntimeError("启动 Registry 失败")
-
-        # Wait for Registry to output port via stdout (mechanism 2)
-        print("[launcher] 等待 Registry 端口...")
-        msg = await self._wait_kite_message("registry", "port", timeout=6)
-        if not msg or not msg.get("port"):
-            raise RuntimeError("致命错误: Registry 在 6s 内未报告端口")
-        self.registry_port = int(msg["port"])
-        print(f"[launcher] Registry 端口: {self.registry_port}")
-
-        # Set KITE_REGISTRY_PORT for all subsequent child processes
-        os.environ["KITE_REGISTRY_PORT"] = str(self.registry_port)
-
-        # Start Launcher API in a separate thread
-        self._start_api_thread()
-
-        # Register Launcher itself to Registry
-        await self._register_self()
-
-    async def _register_self(self):
-        """Register Launcher itself to Registry."""
-        url = f"http://127.0.0.1:{self.registry_port}/modules"
-        headers = {"Authorization": f"Bearer {self.kite_token}"}
-        payload = {
-            "action": "register",
-            "module_id": "launcher",
-            "module_type": "infrastructure",
-            "name": "Launcher",
-            "api_endpoint": f"http://127.0.0.1:{self.api_port}",
-            "health_endpoint": "/launcher/modules",
-            "events_publish": {
-                "module.started": {},
-                "module.stopped": {},
-                "module.state_changed": {},
-            },
-            "events_subscribe": [">"],
-        }
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(url, json=payload, headers=headers, timeout=5)
-                if resp.status_code == 200:
-                    print("[launcher] 已注册到 Registry")
-                else:
-                    print(f"[launcher] 警告: Registry 注册返回 {resp.status_code}")
-        except Exception as e:
-            print(f"[launcher] 警告: 注册到 Registry 失败: {e}")
-
-    # ── Phase 2: Event Hub ──
-
-    async def _phase2_event_hub(self):
-        """Start Event Hub → stdin launcher_ws_token → stdout ws_endpoint → WS connect → module.ready."""
-        # Find event_hub in scanned modules or build manually
-        eh_info = self.modules.get("event_hub")
-        if not eh_info:
-            eh_dir = os.path.join(os.environ["KITE_PROJECT"], "core", "event_hub")
-            eh_info = ModuleInfo(
-                name="event_hub",
-                display_name="Event Hub",
-                type="infrastructure",
-                state="enabled",
-                runtime="python",
-                entry="entry.py",
-                module_dir=eh_dir,
-            )
-
-        token = self._module_tokens.get("event_hub", "")
-        if not token:
-            token = secrets.token_hex(32)
-            self._module_tokens["event_hub"] = token
-            await self._register_tokens_to_registry({"event_hub": token})
-
-        boot_info = {"token": token}
-        self._log_lifecycle("starting", "event_hub")
-        ok = self.process_manager.start_module(eh_info, boot_info=boot_info)
-        if not ok:
-            self._log_lifecycle("start_failed", "event_hub")
-            raise RuntimeError("启动 Event Hub 失败")
-
-        # Send launcher_ws_token via stdin (mechanism 6)
-        self._launcher_ws_token = secrets.token_hex(32)
-        self.process_manager.write_stdin("event_hub", {
-            "kite": "launcher_ws_token",
-            "launcher_ws_token": self._launcher_ws_token,
-        })
-
-        # Wait for ws_endpoint from stdout (mechanism 5)
-        print("[launcher] 等待 Event Hub ws_endpoint...")
-        msg = await self._wait_kite_message("event_hub", "ws_endpoint", timeout=6)
-        if not msg or not msg.get("ws_endpoint"):
-            raise RuntimeError("致命错误: Event Hub 在 6s 内未报告 ws_endpoint")
-        self._event_hub_ws_url = msg["ws_endpoint"]
-        print(f"[launcher] Event Hub 已发现: {self._event_hub_ws_url}")
-
-        # Connect to Event Hub WebSocket with launcher_ws_token
-        self._ws_task = asyncio.create_task(self._ws_loop())
-
-        # Wait for Event Hub module.ready (sent when Launcher connects)
-        ready = await self._wait_event("module.ready", "event_hub", timeout=15)
-        if ready:
-            print("[launcher] Event Hub 已就绪")
-        else:
-            print("[launcher] 警告: Event Hub 在 15s 内未发送 module.ready")
-
-        self._log_lifecycle("started", "event_hub")
-        await self._publish_event("module.started", {"module_id": "event_hub"})
-        self.process_manager.close_stdio("event_hub")
-
-    # ── Phase 3: Registry delayed ready ──
-
-    async def _phase3_registry_ready(self):
-        """Wait for Registry module.ready (triggered after Event Hub registers to Registry
-        and Registry connects to Event Hub WS)."""
-        print("[launcher] 等待 Registry 延迟就绪...")
-        ready = await self._wait_event("module.ready", "registry", timeout=12)
-        if ready:
-            print("[launcher] Registry 已就绪")
-        else:
-            print("[launcher] 警告: Registry 在 12s 内未发送 module.ready (降级运行)")
-
-        self._log_lifecycle("started", "registry")
-        await self._publish_event("module.started", {"module_id": "registry"})
-        self.process_manager.close_stdio("registry")
-
-    # ── Phase 4: Start remaining modules ──
-
-    async def _phase4_start_modules(self):
-        """Start enabled modules (excluding core) in dependency order."""
-        to_start = [m for m in self.modules.values()
-                     if self._desired_states.get(m.name) == "running"
-                     and m.name not in CORE_MODULE_NAMES]
-        if not to_start:
-            print("[launcher] 没有额外模块需要启动")
-            return
-
-        # Auto-start manual modules if depended upon
-        needed = set(m.name for m in to_start)
-        for m in list(to_start):
-            for dep in m.depends_on:
-                if dep not in needed and dep not in CORE_MODULE_NAMES:
-                    dep_info = self.modules.get(dep)
-                    if dep_info and dep_info.state != "disabled":
-                        needed.add(dep)
-                        to_start.append(dep_info)
-                        self._desired_states[dep] = "running"
-                        print(f"[launcher] 自动启动 '{dep}' (被依赖)")
-                    elif dep_info and dep_info.state == "disabled":
-                        print(f"[launcher] 错误: '{m.name}' 依赖已禁用的模块 '{dep}'")
-
-        try:
-            sorted_modules = self._topo_sort(to_start)
-        except RuntimeError as e:
-            print(f"[launcher] 错误: {e}")
-            return
-
-        print(f"[launcher] 正在启动 {len(sorted_modules)} 个模块...")
-        for info in sorted_modules:
-            await self._start_one_module(info)
-
-    # ── Event Hub WebSocket connection ──
-
-    async def _ws_loop(self):
-        """Connect to Event Hub, reconnect on failure."""
-        while not self._thread_shutdown.is_set():
-            try:
-                await self._ws_connect()
-            except asyncio.CancelledError:
-                return
-            except Exception as e:
-                print(f"[launcher] Event Hub 连接错误: {e}")
-            self._ws = None
-            await asyncio.sleep(5)
-
-    async def _ws_connect(self):
-        """Single WebSocket session with launcher_ws_token auth."""
-        ws_url = f"{self._event_hub_ws_url}?token={self._launcher_ws_token}"
-        async with websockets.connect(ws_url, ping_interval=None, ping_timeout=None, close_timeout=10) as ws:
-            self._ws = ws
-            print("[launcher] 已连接到 Event Hub")
-
-            # Subscribe to all events
-            await ws.send(json.dumps({
-                "type": "subscribe",
-                "events": [">"],
-            }))
-
-            # Receive loop
-            async for raw in ws:
-                try:
-                    msg = json.loads(raw)
-                except (json.JSONDecodeError, TypeError):
-                    continue
-                msg_type = msg.get("type", "")
-                if msg_type == "event":
-                    source = msg.get("source", "unknown")
-                    event = msg.get("event", "")
-                    data = msg.get("data", {})
-                    # Trigger event waiters
-                    module_id = data.get("module_id", "")
-                    waiter_key = f"{event}:{module_id}"
-                    waiter = self._event_waiters.get(waiter_key)
-                    if waiter:
-                        waiter[1].update(data)
-                        waiter[0].set()
-                    ts = msg.get("timestamp", "")
-                    latency_str = ""
-                    if ts:
-                        try:
-                            from datetime import datetime, timezone
-                            sent = datetime.fromisoformat(ts)
-                            delay_ms = (datetime.now(timezone.utc) - sent).total_seconds() * 1000
-                            latency_str = f" ({delay_ms:.1f}ms)"
-                            local_ts = sent.astimezone().strftime("%H:%M:%S")
-                        except Exception:
-                            local_ts = ts[11:19] if len(ts) >= 19 else ts
-                        print(f"[{source}] {local_ts} {event}{latency_str}: {json.dumps(data, ensure_ascii=False)}")
-                    else:
-                        print(f"[{source}] {event}: {json.dumps(data, ensure_ascii=False)}")
-                elif msg_type == "error":
-                    print(f"[launcher] Event Hub 错误: {msg.get('message')}")
-
-    async def _publish_event(self, event_type: str, data: dict):
-        """Publish an event to Event Hub via WebSocket."""
-        if not self._ws:
-            return
-        from datetime import datetime, timezone
-        msg = {
-            "type": "event",
-            "event_id": str(uuid.uuid4()),
-            "event": event_type,
-            "source": "launcher",
-            "timestamp": datetime.now(timezone.utc).isoformat(),
-            "data": data,
-        }
-        try:
-            await self._ws.send(json.dumps(msg))
-        except Exception as e:
-            print(f"[launcher] 发布事件失败: {e}")
-
-    def _publish_event_threadsafe(self, event_type: str, data: dict):
-        """Publish event from non-async context (API thread). Fire-and-forget."""
-        if not self._ws or not self._loop:
-            return
-        asyncio.run_coroutine_threadsafe(
-            self._publish_event(event_type, data), self._loop,
-        )
-
-    async def _wait_event(self, event_type: str, module_id: str, timeout: float) -> dict | None:
-        """Wait for a specific event from a module. Returns data dict or None on timeout."""
-        key = f"{event_type}:{module_id}"
-        evt = asyncio.Event()
-        data = {}
-        self._event_waiters[key] = (evt, data)
-        try:
-            await asyncio.wait_for(evt.wait(), timeout=timeout)
-            return data
-        except asyncio.TimeoutError:
-            return None
-        finally:
-            self._event_waiters.pop(key, None)
-
-    async def _graceful_stop(self, name: str, reason: str = "stop_requested", timeout: float = 10):
-        """Graceful shutdown: send event → wait ack → wait ready → kill."""
-        self._log_lifecycle("stopping", name, reason=reason)
-        await self._publish_event("module.shutdown", {
-            "module_id": name, "reason": reason, "timeout": timeout,
-        })
-
-        ack = await self._wait_event("module.shutdown.ack", name, timeout=3)
-        if not ack:
-            self.process_manager.stop_module(name, timeout=5)
-            await self._publish_event("module.stopped", {"module_id": name})
-            return
-
-        estimated = min(ack.get("estimated_cleanup", timeout), timeout)
-        ready = await self._wait_event("module.shutdown.ready", name, timeout=estimated)
-        if ready:
-            self.process_manager.stop_module(name, timeout=1)
-        else:
-            self.process_manager.stop_module(name, timeout=3)
-
-        self._log_lifecycle("stopped", name, reason=reason)
-        await self._publish_event("module.stopped", {"module_id": name})
-
-    async def _graceful_shutdown_all(self):
-        """Broadcast module.shutdown to all running modules, then force-kill survivors."""
-        running = [n for n in self.modules if self.process_manager.is_running(n)]
-        # Also check core modules
-        for cn in CORE_MODULE_NAMES:
-            if self.process_manager.is_running(cn) and cn not in running:
-                running.append(cn)
-        if not running:
-            return
-        print(f"[launcher] 优雅关闭: {', '.join(running)}")
-        for name in running:
-            self._log_lifecycle("stopping", name, reason="system_shutdown")
-            await self._publish_event("module.shutdown", {
-                "module_id": name, "reason": "system_shutdown", "timeout": 10,
-            })
-        deadline = time.time() + 10
-        while time.time() < deadline:
-            still_running = [n for n in running if self.process_manager.is_running(n)]
-            if not still_running:
-                break
-            await asyncio.sleep(0.5)
-        self.process_manager.stop_all(timeout=3)
-        for name in running:
-            self._log_lifecycle("stopped", name, reason="system_shutdown")
-
-    # ── Heartbeat to Registry ──
-
-    async def _heartbeat_loop(self):
-        """Send heartbeat to Registry every 30 seconds."""
-        while not self._thread_shutdown.is_set():
-            await asyncio.sleep(30)
-            try:
-                async with httpx.AsyncClient() as client:
-                    await client.post(
-                        f"http://127.0.0.1:{self.registry_port}/modules",
-                        json={"action": "heartbeat", "module_id": "launcher"},
-                        headers={"Authorization": f"Bearer {self.kite_token}"},
-                        timeout=5,
-                    )
-            except Exception:
-                pass
-
-    # ── Module startup ──
-
-    def _topo_sort(self, modules: list[ModuleInfo]) -> list[ModuleInfo]:
-        """Topological sort by depends_on. Raises RuntimeError on cycle."""
-        name_map = {m.name: m for m in modules}
-        visited = set()
-        in_stack = set()
-        order = []
-
-        def visit(name):
-            if name in in_stack:
-                raise RuntimeError(f"Circular dependency detected involving '{name}'")
-            if name in visited:
-                return
-            in_stack.add(name)
-            info = name_map.get(name)
-            if info:
-                for dep in info.depends_on:
-                    visit(dep)
-            in_stack.remove(name)
-            visited.add(name)
-            if info:
-                order.append(info)
-
-        for m in modules:
-            visit(m.name)
-        return order
-
-    async def _start_one_module(self, info: ModuleInfo):
-        """Start a single module: publish starting → start process → wait ready → started → close stdio."""
-        self._log_lifecycle("starting", info.name)
-        await self._publish_event("module.starting", {"module_id": info.name})
-
-        token = self._module_tokens.get(info.name, "")
-        boot_info = {"token": token}
-        ok = self.process_manager.start_module(info, boot_info=boot_info)
-        if not ok:
-            self._log_lifecycle("start_failed", info.name)
-            return
-
-        # Wait for module.ready (configurable timeout, degrade on timeout)
-        timeout = info.launch.timeout
-        ready = await self._wait_event("module.ready", info.name, timeout=timeout)
-        if ready:
-            print(f"[launcher] 模块 '{info.name}' 已就绪")
-        else:
-            print(f"[launcher] 警告: '{info.name}' 在 {timeout}s 内未发送 module.ready")
-
-        rec = self.process_manager.get_record(info.name)
-        self._log_lifecycle("started", info.name, pid=rec.pid if rec else None)
-        await self._publish_event("module.started", {"module_id": info.name})
-        self.process_manager.close_stdio(info.name)
-
-    async def _register_module_tokens(self):
-        """Generate per-module tokens and register the mapping to Registry."""
-        # Include all scanned modules + core modules
-        for name in self.modules:
-            if name not in self._module_tokens:
-                self._module_tokens[name] = secrets.token_hex(32)
-        # Ensure registry has a token
-        if "registry" not in self._module_tokens:
-            self._module_tokens["registry"] = secrets.token_hex(32)
-
-        if not self._module_tokens:
-            return
-
-        await self._register_tokens_to_registry(self._module_tokens)
-
-    async def _register_tokens_to_registry(self, tokens: dict):
-        """Register token mapping to Registry via POST /tokens."""
-        url = f"http://127.0.0.1:{self.registry_port}/tokens"
-        headers = {"Authorization": f"Bearer {self.kite_token}"}
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(url, json=tokens, headers=headers, timeout=5)
-                if resp.status_code == 200:
-                    print(f"[launcher] 已注册 {len(tokens)} 个模块令牌")
-                else:
-                    print(f"[launcher] 警告: 令牌注册返回 {resp.status_code}")
-        except Exception as e:
-            print(f"[launcher] 警告: 注册模块令牌失败: {e}")
-
-    # ── Validation ──
-
-    def _validate_core_modules(self):
-        """Validate core modules exist (mechanism 12)."""
-        project_root = os.environ["KITE_PROJECT"]
-        for name in ("registry", "event_hub"):
-            mod_dir = os.path.join(project_root, "core", name)
-            md_path = os.path.join(mod_dir, "module.md")
-            if not os.path.isdir(mod_dir):
-                print(f"[launcher] 致命: 核心模块 '{name}' 目录未找到: {mod_dir}")
-                sys.exit(1)
-            if not os.path.isfile(md_path):
-                print(f"[launcher] 致命: 核心模块 '{name}' 缺少 module.md: {md_path}")
-                sys.exit(1)
-            # Try to parse frontmatter
-            try:
-                with open(md_path, "r", encoding="utf-8") as f:
-                    fm = _parse_frontmatter(f.read())
-                if not fm:
-                    print(f"[launcher] 致命: 核心模块 '{name}' module.md 没有有效的 frontmatter")
-                    sys.exit(1)
-            except Exception as e:
-                print(f"[launcher] 致命: 核心模块 '{name}' module.md 解析错误: {e}")
-                sys.exit(1)
-
-    # ── API thread ──
-
-    def _start_api_thread(self):
-        """Start the Launcher API server in a separate thread with OS-assigned port."""
-        self.api_port = self._get_free_port()
-        config = uvicorn.Config(
-            self._app,
-            host="127.0.0.1",
-            port=self.api_port,
-            log_level="warning",
-        )
-        self._api_server = uvicorn.Server(config)
-
-        def _run():
-            self._api_server.run()
-
-        t = threading.Thread(target=_run, daemon=True)
-        t.start()
-
-        deadline = time.time() + 5
-        while time.time() < deadline:
-            if self._api_server.started:
-                break
-            time.sleep(0.05)
-        else:
-            print("[launcher] 警告: API 服务器可能尚未完全就绪")
-
-        print(f"[launcher] API 服务器已启动，端口 {self.api_port}")
-
-    # ── Monitor loop ──
-
-    async def _monitor_loop(self):
-        """Check child processes every second. Handle crashes.
-        Uses _shutdown_event (asyncio.Event) so Ctrl+C wakes us immediately.
-        """
-        MAX_FAIL = 3
-        MAX_FAILED_MODULES = 3
-
-        while not self._shutdown_event.is_set():
-            exited = self.process_manager.check_exited()
-
-            for name, rc in exited:
-                print(f"[launcher] 模块 '{name}' 退出，返回码 {rc}")
-                self._log_lifecycle("exited", name, exit_code=rc)
-                await self._publish_event("module.stopped", {
-                    "module_id": name, "exit_code": rc,
-                })
-                info = self.modules.get(name)
-
-                # Core module crash → full restart
-                if name in CORE_MODULE_NAMES or (info and info.is_core()):
-                    print(f"[launcher] 严重: 核心模块 '{name}' 崩溃，正在全部重启...")
-                    self._log_lifecycle("core_crash", name, exit_code=rc)
-                    await self._full_restart()
-                    return
-
-                # Non-core: attempt restart if desired_state is "running"
-                self._fail_counts[name] = self._fail_counts.get(name, 0) + 1
-                count = self._fail_counts[name]
-
-                if count < MAX_FAIL and self._desired_states.get(name) == "running" and info:
-                    print(f"[launcher] 正在重启 '{name}' (第 {count}/{MAX_FAIL} 次)...")
-                    await self._start_one_module(info)
-                elif count >= MAX_FAIL:
-                    self._desired_states[name] = "stopped"
-                    self._log_lifecycle("failed", name, reason=f"exceeded {MAX_FAIL} retries")
-                    print(f"[launcher] 模块 '{name}' 失败 {MAX_FAIL} 次，已放弃")
-
-            failed_count = sum(1 for c in self._fail_counts.values() if c >= MAX_FAIL)
-            if failed_count >= MAX_FAILED_MODULES:
-                print(f"[launcher] {failed_count} 个模块永久失败，启动器退出")
-                return
-
-            if exited:
-                self.process_manager.persist_records()
-
-            # Wait 1s but wake immediately on shutdown signal
-            try:
-                await asyncio.wait_for(self._shutdown_event.wait(), timeout=1)
-                return  # shutdown requested
-            except asyncio.TimeoutError:
-                pass
-
-    async def _full_restart(self):
-        """Stop all modules, regenerate tokens, re-run Phase 1-4 (mechanism 10)."""
-        print("[launcher] 全量重启: 正在停止所有模块...")
-
-        # Disconnect Event Hub WS
-        if self._ws_task:
-            self._ws_task.cancel()
-            self._ws_task = None
-        if hasattr(self, '_heartbeat_task') and self._heartbeat_task:
-            self._heartbeat_task.cancel()
-            self._heartbeat_task = None
-        self._ws = None
-        self._event_hub_ws_url = ""
-        self._launcher_ws_token = ""
-
-        await self._graceful_shutdown_all()
-        self._fail_counts.clear()
-        self._module_tokens.clear()
-
-        # Regenerate kite_token
-        self.kite_token = secrets.token_hex(32)
-        self.process_manager.kite_token = self.kite_token
-
-        print("[launcher] 全量重启: 重新执行 Phase 1-4...")
-        try:
-            await self._phase1_registry()
-            self.modules = self.module_scanner.scan()
-            for n, info in self.modules.items():
-                self._log_lifecycle("scanned", n, state=info.state, module_dir=info.module_dir)
-            await self._register_module_tokens()
-            await self._phase2_event_hub()
-            await self._phase3_registry_ready()
-            await self._phase4_start_modules()
-            self.process_manager.persist_records()
-            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
-            print("[launcher] 全量重启完成，恢复监控循环")
-            await self._monitor_loop()
-        except Exception as e:
-            print(f"[launcher] 全量重启失败: {e}")
-
-    # ── Shutdown ──
-
-    def _final_cleanup(self):
-        """Called on exit — stop all processes, stop API, clear records."""
-        print("[launcher] 正在关闭...")
-
-        if self._ws_task:
-            self._ws_task.cancel()
-        if hasattr(self, '_heartbeat_task') and self._heartbeat_task:
-            self._heartbeat_task.cancel()
-
-        self.process_manager.stop_all(timeout=10)
-
-        if self._api_server:
-            self._api_server.should_exit = True
-
-        # Clear instance runtime files
-        self.process_manager._write_records_file([])
-        try:
-            os.remove(self.process_manager.records_path)
-        except OSError:
-            pass
-        print("[launcher] 再见。")
-
-        if IS_WINDOWS:
-            os._exit(0)
-
-    # ── Utilities ──
-
-    def _load_discovery(self) -> dict | None:
-        """Read discovery config from launcher's own module.md."""
-        md_path = os.path.join(os.environ["KITE_PROJECT"], "core", "launcher", "module.md")
-        try:
-            with open(md_path, "r", encoding="utf-8") as f:
-                fm = _parse_frontmatter(f.read())
-            discovery = fm.get("discovery")
-            if isinstance(discovery, dict) and discovery:
-                print(f"[launcher] 发现来源: {', '.join(discovery.keys())}")
-                return discovery
-        except Exception as e:
-            print(f"[launcher] 警告: 读取发现配置失败: {e}")
-        return None
-
-    def _log_lifecycle(self, event: str, module: str, **extra):
-        """Append one JSONL line to lifecycle.jsonl."""
-        from datetime import datetime, timezone
-        record = {"ts": datetime.now(timezone.utc).isoformat(), "event": event, "module": module}
-        record.update(extra)
-        try:
-            os.makedirs(os.path.dirname(self._lifecycle_log), exist_ok=True)
-            with open(self._lifecycle_log, "a", encoding="utf-8") as f:
-                f.write(json.dumps(record, ensure_ascii=False) + "\n")
-        except Exception:
-            pass
-
-    @staticmethod
-    def _get_free_port() -> int:
-        """Get a free port assigned by the OS (bind to port 0)."""
-        import socket
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            s.bind(("127.0.0.1", 0))
-            return s.getsockname()[1]
-
-    # ── API app ──
-
-    def _create_api_app(self) -> FastAPI:
-        """Create the FastAPI app with Launcher management routes."""
-        app = FastAPI(title="Kite Launcher", docs_url=None, redoc_url=None)
-        launcher = self
-
-        @app.get("/launcher/modules")
-        async def list_modules():
-            """List all modules and their current status."""
-            result = []
-            for name, info in launcher.modules.items():
-                running = launcher.process_manager.is_running(name)
-                rec = launcher.process_manager.get_record(name)
-                result.append({
-                    "name": name,
-                    "display_name": info.display_name,
-                    "type": info.type,
-                    "config_state": info.state,
-                    "desired_state": launcher._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 result
-
-        @app.post("/launcher/modules/{name}/start")
-        async def start_module(name: str):
-            """Start a module by name."""
-            info = launcher.modules.get(name)
-            if not info:
-                raise HTTPException(404, f"Module '{name}' not found")
-            if info.state == "disabled":
-                raise HTTPException(403, f"Module '{name}' is disabled")
-
-            if name not in launcher._module_tokens:
-                launcher._module_tokens[name] = secrets.token_hex(32)
-                try:
-                    async with httpx.AsyncClient() as client:
-                        await client.post(
-                            f"http://127.0.0.1:{launcher.registry_port}/tokens",
-                            json={name: launcher._module_tokens[name]},
-                            headers={"Authorization": f"Bearer {launcher.kite_token}"},
-                            timeout=5,
-                        )
-                except Exception as e:
-                    print(f"[launcher] 警告: 注册 {name} 的令牌失败: {e}")
-
-            token = launcher._module_tokens[name]
-            boot_info = {"token": token}
-            ok = launcher.process_manager.start_module(info, boot_info=boot_info)
-            if ok:
-                launcher._desired_states[name] = "running"
-                launcher._fail_counts.pop(name, None)
-                launcher.process_manager.persist_records()
-                rec = launcher.process_manager.get_record(name)
-                launcher._log_lifecycle("started", name, pid=rec.pid if rec else None, via="api")
-                launcher._publish_event_threadsafe("module.started", {"module_id": name})
-                return {"status": "started", "name": name}
-            launcher._log_lifecycle("start_failed", name, via="api")
-            raise HTTPException(500, f"Failed to start '{name}'")
-
-        @app.post("/launcher/modules/{name}/stop")
-        async def stop_module(name: str, body: dict = None):
-            """Stop a module with graceful shutdown."""
-            info = launcher.modules.get(name)
-            if not info:
-                raise HTTPException(404, f"Module '{name}' not found")
-            reason = (body or {}).get("reason", "stop_requested")
-            launcher._desired_states[name] = "stopped"
-            await launcher._graceful_stop(name, reason)
-            launcher.process_manager.persist_records()
-            return {"status": "stopped", "name": name}
-
-        @app.post("/launcher/modules/{name}/restart")
-        async def restart_module(name: str, body: dict = None):
-            """Restart a module (stop + start)."""
-            info = launcher.modules.get(name)
-            if not info:
-                raise HTTPException(404, f"Module '{name}' not found")
-            if info.state == "disabled":
-                raise HTTPException(403, f"Module '{name}' is disabled")
-            reason = (body or {}).get("reason", "restart")
-            await launcher._graceful_stop(name, reason)
-            launcher._module_tokens[name] = secrets.token_hex(32)
-            try:
-                async with httpx.AsyncClient() as client:
-                    await client.post(
-                        f"http://127.0.0.1:{launcher.registry_port}/tokens",
-                        json={name: launcher._module_tokens[name]},
-                        headers={"Authorization": f"Bearer {launcher.kite_token}"},
-                        timeout=5,
-                    )
-            except Exception:
-                pass
-            token = launcher._module_tokens[name]
-            boot_info = {"token": token}
-            ok = launcher.process_manager.start_module(info, boot_info=boot_info)
-            if ok:
-                launcher._desired_states[name] = "running"
-                launcher._fail_counts.pop(name, None)
-                launcher.process_manager.persist_records()
-                rec = launcher.process_manager.get_record(name)
-                launcher._log_lifecycle("started", name, pid=rec.pid if rec else None, via="restart_api")
-                launcher._publish_event_threadsafe("module.started", {"module_id": name})
-                return {"status": "restarted", "name": name}
-            launcher._log_lifecycle("start_failed", name, via="restart_api")
-            raise HTTPException(500, f"Failed to restart '{name}'")
-
-        @app.post("/launcher/rescan")
-        async def rescan_modules():
-            """Rescan module directories for new/removed modules."""
-            old_names = set(launcher.modules.keys())
-            launcher.modules = launcher.module_scanner.scan()
-            new_names = set(launcher.modules.keys())
-            added = list(new_names - old_names)
-            removed = list(old_names - new_names)
-            for name in added:
-                info = launcher.modules[name]
-                launcher._log_lifecycle("scanned", name, state=info.state, module_dir=info.module_dir)
-            for name in added:
-                info = launcher.modules[name]
-                launcher._desired_states[name] = "running" if info.state == "enabled" else "stopped"
-            if added:
-                new_tokens = {}
-                for name in added:
-                    launcher._module_tokens[name] = secrets.token_hex(32)
-                    new_tokens[name] = launcher._module_tokens[name]
-                try:
-                    async with httpx.AsyncClient() as client:
-                        await client.post(
-                            f"http://127.0.0.1:{launcher.registry_port}/tokens",
-                            json=new_tokens,
-                            headers={"Authorization": f"Bearer {launcher.kite_token}"},
-                            timeout=5,
-                        )
-                except Exception:
-                    pass
-            return {"added": added, "removed": removed, "total": len(launcher.modules)}
-
-        @app.put("/launcher/modules/{name}/state")
-        async def update_state(name: str, body: dict):
-            """Update module state (enabled/manual/disabled). Writes to module.md."""
-            info = launcher.modules.get(name)
-            if not info:
-                raise HTTPException(404, f"Module '{name}' not found")
-
-            new_state = body.get("state", "")
-            if new_state not in ("enabled", "manual", "disabled"):
-                raise HTTPException(400, "state must be enabled, manual, or disabled")
-
-            if info.is_core() and new_state == "disabled":
-                raise HTTPException(403, "Core modules cannot be disabled")
-
-            old_state = info.state
-            info.state = new_state
-
-            if new_state == "enabled":
-                launcher._desired_states[name] = "running"
-            else:
-                launcher._desired_states[name] = "stopped"
-
-            _update_module_md_state(info.module_dir, new_state)
-            launcher._publish_event_threadsafe("module.state_changed", {
-                "module_id": name,
-                "old_state": old_state,
-                "new_state": new_state,
-            })
-            return {
-                "name": name,
-                "old_state": old_state,
-                "new_state": new_state,
-            }
-
-        return app
-
-
-def _update_module_md_state(module_dir: str, new_state: str):
-    """Update the state field in a module's module.md frontmatter."""
-    import re
-    md_path = os.path.join(module_dir, "module.md")
-    if not os.path.isfile(md_path):
-        return
-
-    try:
-        with open(md_path, "r", encoding="utf-8") as f:
-            content = f.read()
-
-        updated = re.sub(
-            r'^(state:\s*)(\S+)',
-            rf'\g<1>{new_state}',
-            content,
-            count=1,
-            flags=re.MULTILINE,
-        )
-
-        with open(md_path, "w", encoding="utf-8") as f:
-            f.write(updated)
-    except Exception as e:
-        print(f"[launcher] 警告: 更新 module.md 状态失败: {e}")