@agentunion/kite 1.0.6 → 1.0.7

package/core/launcher/entry.py

@@ -4,8 +4,14 @@ Launcher — the core of Kite. Manages module lifecycle, exposes API, monitors p
 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
+- 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
@@ -22,25 +28,35 @@ import httpx
 import uvicorn
 import websockets
 from fastapi import FastAPI, HTTPException
-from fastapi.responses import JSONResponse
 
-from .module_scanner import ModuleScanner, ModuleInfo, _parse_frontmatter
+from .module_scanner import ModuleScanner, ModuleInfo, LaunchConfig, _parse_frontmatter
 from .process_manager import ProcessManager
-from core.data_dir import get_launcher_data_dir
 
 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.project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
         self.instance_id = str(os.getpid())
-        self.process_manager = ProcessManager(self.project_root, kite_token, self.instance_id)
+        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(
-            self.project_root,
             discovery=self._load_discovery(),
         )
 
@@ -55,30 +71,122 @@ class Launcher:
         self._module_tokens: dict[str, str] = {}  # module_name -> per-module token
 
         # Three-layer state model: desired_state per module
-        # Initialized from config_state: enabled→running, manual→stopped, disabled→stopped
         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)}
-        # event_key format: "event_type:module_id"
         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(
-            get_launcher_data_dir(), "lifecycle.jsonl",
+            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 starting...")
-        print(f"[launcher] Project root: {self.project_root}")
+        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()
@@ -92,113 +200,303 @@ class Launcher:
         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):
-            print(f"\n[launcher] Received signal {signum}, shutting down...")
-            self._thread_shutdown.set()
+            self._request_shutdown(f"收到信号 {signum}，正在关闭...")
         signal.signal(signal.SIGTERM, _handler)
         signal.signal(signal.SIGINT, _handler)
 
     def _setup_windows_exit(self):
-        """Start a daemon thread that listens for 'q' or Ctrl+C on Windows."""
+        """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', b'\x03'):  # q or Ctrl+C
-                        print("\n[launcher] Exit requested, shutting down...")
-                        self._thread_shutdown.set()
+                    if ch in (b'q', b'Q'):
+                        self._request_shutdown("收到退出请求，正在关闭...")
                         return
                 time.sleep(0.1)
-        t = threading.Thread(target=_listen, daemon=True)
-        t.start()
+        threading.Thread(target=_listen, daemon=True).start()
 
-    # ── Async main ──
+    # ── Async main (4-Phase startup) ──
 
     async def _async_main(self):
-        """Full startup sequence, then monitor loop."""
+        """Full 4-phase startup sequence, then monitor loop."""
         self._loop = asyncio.get_running_loop()
 
-        # Step 1: cleanup leftovers
-        self.process_manager.cleanup_leftovers()
+        # Validate core modules exist (mechanism 12)
+        self._validate_core_modules()
 
-        # Step 2: start Registry
-        await self._start_registry()
+        # Cleanup leftovers from previous instances
+        self.process_manager.cleanup_leftovers()
 
-        # Step 3: start Launcher API in a separate thread
-        self._start_api_thread()
+        # Phase 1: Registry bootstrap
+        await self._phase1_registry()
+        if self._shutdown_event.is_set(): return
 
-        # Step 4: register Launcher to Registry
-        await self._register_self()
-
-        # Step 5: scan modules
+        # 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] Found {len(self.modules)} module(s): {', '.join(self.modules.keys()) or '(none)'}")
+        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
 
-        # Step 5.5: initialize desired_state from config_state
+        # 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"
 
-        # Step 6: generate per-module tokens and register to Registry
-        await self._register_module_tokens()
-
-        # Step 7: start enabled modules
-        await self._start_enabled_modules()
+        await self._phase4_start_modules()
+        if self._shutdown_event.is_set(): return
 
-        # Step 8: persist records
+        # Post-startup
         self.process_manager.persist_records()
-
-        # Step 9: connect to Event Hub (best-effort, non-blocking)
-        await self._connect_event_hub()
-
-        # Step 10: start heartbeat to Registry
         self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
 
-        # Step 11: monitor loop
-        print("[launcher] Entering monitor loop (press Ctrl+C or 'q' to exit)")
+        print("[launcher] 进入监控循环 (按 Ctrl+C 或 'q' 退出)")
         await self._monitor_loop()
 
-        # Graceful shutdown all modules before event loop closes
         await self._graceful_shutdown_all()
 
-    # ── Event Hub connection ──
+    # ── 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()
 
-    async def _connect_event_hub(self):
-        """Discover Event Hub WS endpoint (with retry) and start background client."""
-        url = f"http://127.0.0.1:{self.registry_port}"
+        # 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,
+        })
 
-        # Event Hub needs time to start and register itself to Registry
-        print("[launcher] Waiting for Event Hub to register...")
-        deadline = time.time() + 15
-        while time.time() < deadline:
-            try:
-                async with httpx.AsyncClient() as client:
-                    resp = await client.get(
-                        f"{url}/get/event_hub.metadata.ws_endpoint",
-                        headers=headers, timeout=3,
-                    )
-                    if resp.status_code == 200:
-                        self._event_hub_ws_url = resp.json()
-                        if self._event_hub_ws_url:
-                            break
-            except Exception:
-                pass
-            await asyncio.sleep(1)
+        # 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 ──
 
-        if not self._event_hub_ws_url:
-            print("[launcher] WARNING: Could not discover Event Hub WS, events disabled")
+    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
 
-        print(f"[launcher] Event Hub discovered: {self._event_hub_ws_url}")
-        self._ws_task = asyncio.create_task(self._ws_loop())
+        # 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."""
@@ -208,16 +506,16 @@ class Launcher:
             except asyncio.CancelledError:
                 return
             except Exception as e:
-                print(f"[launcher] Event Hub connection error: {e}")
+                print(f"[launcher] Event Hub 连接错误: {e}")
             self._ws = None
             await asyncio.sleep(5)
 
     async def _ws_connect(self):
-        """Single WebSocket session: connect, subscribe to all events, display them."""
-        ws_url = f"{self._event_hub_ws_url}?token={self.kite_token}"
-        async with websockets.connect(ws_url) as ws:
+        """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] Connected to Event Hub")
+            print("[launcher] 已连接到 Event Hub")
 
             # Subscribe to all events
             await ws.send(json.dumps({
@@ -258,7 +556,7 @@ class Launcher:
                     else:
                         print(f"[{source}] {event}: {json.dumps(data, ensure_ascii=False)}")
                 elif msg_type == "error":
-                    print(f"[launcher] Event Hub error: {msg.get('message')}")
+                    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."""
@@ -276,7 +574,7 @@ class Launcher:
         try:
             await self._ws.send(json.dumps(msg))
         except Exception as e:
-            print(f"[launcher] Failed to publish event: {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."""
@@ -303,27 +601,21 @@ class Launcher:
     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)
-        # Step 1: send module.shutdown event
         await self._publish_event("module.shutdown", {
             "module_id": name, "reason": reason, "timeout": timeout,
         })
 
-        # Step 2: wait for ack (3s)
         ack = await self._wait_event("module.shutdown.ack", name, timeout=3)
         if not ack:
-            # No ack — fallback to direct terminate
             self.process_manager.stop_module(name, timeout=5)
             await self._publish_event("module.stopped", {"module_id": name})
             return
 
-        # Step 3: wait for ready
         estimated = min(ack.get("estimated_cleanup", timeout), timeout)
         ready = await self._wait_event("module.shutdown.ready", name, timeout=estimated)
         if ready:
-            # Module is ready to die — kill immediately
             self.process_manager.stop_module(name, timeout=1)
         else:
-            # Timeout — force stop
             self.process_manager.stop_module(name, timeout=3)
 
         self._log_lifecycle("stopped", name, reason=reason)
@@ -332,16 +624,18 @@ class Launcher:
     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] Graceful shutdown: {', '.join(running)}")
-        # Broadcast shutdown event
+        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,
             })
-        # Wait up to 10s total, then force-kill
         deadline = time.time() + 10
         while time.time() < deadline:
             still_running = [n for n in running if self.process_manager.is_running(n)]
@@ -369,100 +663,6 @@ class Launcher:
             except Exception:
                 pass
 
-    # ── Registry startup ──
-
-    async def _start_registry(self):
-        """Start Registry as a subprocess, wait for it to write port.txt and /health to respond."""
-        registry_dir = os.path.join(self.project_root, "core", "registry")
-        if not os.path.isdir(registry_dir):
-            raise RuntimeError(f"Registry module not found at {registry_dir}")
-
-        # Use centralized data directory
-        from core.data_dir import get_registry_data_dir
-        registry_data_dir = get_registry_data_dir()
-
-        # Clean our instance's port file before starting
-        port_file = os.path.join(registry_data_dir, f"port_{self.instance_id}.txt")
-        if os.path.isfile(port_file):
-            os.remove(port_file)
-
-        registry_info = ModuleInfo(
-            name="registry",
-            display_name="Registry",
-            type="infrastructure",
-            state="enabled",
-            runtime="python",
-            entry="entry.py",
-            module_dir=registry_dir,
-        )
-
-        # Pass launcher_token + bind config via stdin
-        boot_info = {"token": self.kite_token, "registry_port": 0, "bind": "127.0.0.1", "instance_id": self.instance_id}
-        ok = self.process_manager.start_module(registry_info, boot_info=boot_info)
-        if not ok:
-            raise RuntimeError("Failed to start Registry")
-
-        # Wait for Registry to write port.txt
-        print("[launcher] Waiting for Registry to report its port...")
-        deadline = time.time() + 10
-        while time.time() < deadline:
-            if os.path.isfile(port_file):
-                try:
-                    with open(port_file, "r") as f:
-                        self.registry_port = int(f.read().strip())
-                    break
-                except (ValueError, OSError):
-                    pass
-            await asyncio.sleep(0.2)
-        else:
-            raise RuntimeError("Registry failed to write port.txt within 10s")
-
-        # Poll /health until ready
-        url = f"http://127.0.0.1:{self.registry_port}/health"
-        print(f"[launcher] Registry on port {self.registry_port}, waiting for health check...")
-
-        deadline = time.time() + 10
-        async with httpx.AsyncClient() as client:
-            while time.time() < deadline:
-                try:
-                    resp = await client.get(url, timeout=1)
-                    if resp.status_code == 200:
-                        print("[launcher] Registry is ready")
-                        return
-                except Exception:
-                    pass
-                await asyncio.sleep(0.2)
-
-        raise RuntimeError("Registry failed to become ready within 10s")
-
-    async def _register_self(self):
-        """Register Launcher itself to Registry using new API."""
-        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] Registered self to Registry")
-                else:
-                    print(f"[launcher] WARNING: Registry registration returned {resp.status_code}")
-        except Exception as e:
-            print(f"[launcher] WARNING: failed to register to Registry: {e}")
-
     # ── Module startup ──
 
     def _topo_sort(self, modules: list[ModuleInfo]) -> list[ModuleInfo]:
@@ -492,17 +692,12 @@ class Launcher:
         return order
 
     async def _start_one_module(self, info: ModuleInfo):
-        """Start a single module: publish starting event, start process, wait for ready."""
+        """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,
-            "registry_port": self.registry_port,
-            "preferred_port": info.preferred_port,
-            "advertise_ip": "127.0.0.1",
-        }
+        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)
@@ -512,65 +707,68 @@ class Launcher:
         timeout = info.launch.timeout
         ready = await self._wait_event("module.ready", info.name, timeout=timeout)
         if ready:
-            print(f"[launcher] Module '{info.name}' is ready")
+            print(f"[launcher] 模块 '{info.name}' 已就绪")
         else:
-            print(f"[launcher] WARNING: '{info.name}' did not send module.ready within {timeout}s")
+            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})
-
-    async def _start_enabled_modules(self):
-        """Start modules in dependency order, auto-starting manual deps if needed."""
-        to_start = [m for m in self.modules.values()
-                     if self._desired_states.get(m.name) == "running"]
-        if not to_start:
-            print("[launcher] No modules to start")
-            return
-
-        # Auto-start manual modules if depended upon
-        needed = set(m.name for m in to_start)
-        for m in to_start:
-            for dep in m.depends_on:
-                if dep not in needed:
-                    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] Auto-starting '{dep}' (dependency)")
-                    elif dep_info and dep_info.state == "disabled":
-                        print(f"[launcher] ERROR: '{m.name}' depends on disabled module '{dep}'")
-
-        try:
-            sorted_modules = self._topo_sort(to_start)
-        except RuntimeError as e:
-            print(f"[launcher] ERROR: {e}")
-            return
-
-        print(f"[launcher] Starting {len(sorted_modules)} module(s)...")
-        for info in sorted_modules:
-            await self._start_one_module(info)
+        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:
-            self._module_tokens[name] = secrets.token_hex(32)
+            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=self._module_tokens, headers=headers, timeout=5)
+                resp = await client.post(url, json=tokens, headers=headers, timeout=5)
                 if resp.status_code == 200:
-                    print(f"[launcher] Registered {len(self._module_tokens)} module token(s)")
+                    print(f"[launcher] 已注册 {len(tokens)} 个模块令牌")
                 else:
-                    print(f"[launcher] WARNING: token registration returned {resp.status_code}")
+                    print(f"[launcher] 警告: 令牌注册返回 {resp.status_code}")
         except Exception as e:
-            print(f"[launcher] WARNING: failed to register module tokens: {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 ──
 
@@ -591,29 +789,30 @@ class Launcher:
         t = threading.Thread(target=_run, daemon=True)
         t.start()
 
-        # Wait for API server to actually be ready before proceeding
         deadline = time.time() + 5
         while time.time() < deadline:
             if self._api_server.started:
                 break
             time.sleep(0.05)
         else:
-            print("[launcher] WARNING: API server may not be fully ready")
+            print("[launcher] 警告: API 服务器可能尚未完全就绪")
 
-        print(f"[launcher] API server started on port {self.api_port}")
+        print(f"[launcher] API 服务器已启动，端口 {self.api_port}")
 
     # ── Monitor loop ──
 
     async def _monitor_loop(self):
-        """Check child processes every second. Handle crashes."""
+        """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._thread_shutdown.is_set():
+        while not self._shutdown_event.is_set():
             exited = self.process_manager.check_exited()
 
             for name, rc in exited:
-                print(f"[launcher] Module '{name}' exited with code {rc}")
+                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,
@@ -621,8 +820,8 @@ class Launcher:
                 info = self.modules.get(name)
 
                 # Core module crash → full restart
-                if info and info.is_core(self.project_root):
-                    print(f"[launcher] CRITICAL: core module '{name}' crashed, restarting all...")
+                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
@@ -632,29 +831,33 @@ class Launcher:
                 count = self._fail_counts[name]
 
                 if count < MAX_FAIL and self._desired_states.get(name) == "running" and info:
-                    print(f"[launcher] Restarting '{name}' (attempt {count}/{MAX_FAIL})...")
+                    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] Module '{name}' failed {MAX_FAIL} times, giving up")
+                    print(f"[launcher] 模块 '{name}' 失败 {MAX_FAIL} 次，已放弃")
 
-            # Too many failed modules → exit
             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} modules permanently failed, Launcher exiting")
+                print(f"[launcher] {failed_count} 个模块永久失败，启动器退出")
                 return
 
             if exited:
                 self.process_manager.persist_records()
 
-            await asyncio.sleep(1)
+            # 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, then re-run the startup sequence."""
-        print("[launcher] Full restart: stopping all modules...")
+        """Stop all modules, regenerate tokens, re-run Phase 1-4 (mechanism 10)."""
+        print("[launcher] 全量重启: 正在停止所有模块...")
 
-        # Disconnect Event Hub
+        # Disconnect Event Hub WS
         if self._ws_task:
             self._ws_task.cancel()
             self._ws_task = None
@@ -662,33 +865,39 @@ class Launcher:
             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()
 
-        print("[launcher] Full restart: re-running startup sequence...")
+        # 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._start_registry()
-            await self._register_self()
+            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._start_enabled_modules()
+            await self._phase2_event_hub()
+            await self._phase3_registry_ready()
+            await self._phase4_start_modules()
             self.process_manager.persist_records()
-            await self._connect_event_hub()
-            print("[launcher] Full restart complete, resuming monitor loop")
+            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+            print("[launcher] 全量重启完成，恢复监控循环")
             await self._monitor_loop()
         except Exception as e:
-            print(f"[launcher] Full restart failed: {e}")
+            print(f"[launcher] 全量重启失败: {e}")
 
     # ── Shutdown ──
 
     def _final_cleanup(self):
         """Called on exit — stop all processes, stop API, clear records."""
-        print("[launcher] Shutting down...")
+        print("[launcher] 正在关闭...")
 
         if self._ws_task:
             self._ws_task.cancel()
@@ -706,13 +915,7 @@ class Launcher:
             os.remove(self.process_manager.records_path)
         except OSError:
             pass
-        from core.data_dir import get_registry_data_dir
-        port_file = os.path.join(get_registry_data_dir(), f"port_{self.instance_id}.txt")
-        try:
-            os.remove(port_file)
-        except OSError:
-            pass
-        print("[launcher] Goodbye.")
+        print("[launcher] 再见。")
 
         if IS_WINDOWS:
             os._exit(0)
@@ -721,20 +924,20 @@ class Launcher:
 
     def _load_discovery(self) -> dict | None:
         """Read discovery config from launcher's own module.md."""
-        md_path = os.path.join(self.project_root, "core", "launcher", "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] Discovery sources: {', '.join(discovery.keys())}")
+                print(f"[launcher] 发现来源: {', '.join(discovery.keys())}")
                 return discovery
         except Exception as e:
-            print(f"[launcher] WARNING: failed to read discovery config: {e}")
+            print(f"[launcher] 警告: 读取发现配置失败: {e}")
         return None
 
     def _log_lifecycle(self, event: str, module: str, **extra):
-        """Append one JSONL line to core/launcher/data/lifecycle.jsonl."""
+        """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)
@@ -758,11 +961,11 @@ class Launcher:
     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  # closure reference
+        launcher = self
 
         @app.get("/launcher/modules")
         async def list_modules():
-            """List all modules and their current status (three-layer state model)."""
+            """List all modules and their current status."""
             result = []
             for name, info in launcher.modules.items():
                 running = launcher.process_manager.is_running(name)
@@ -781,17 +984,15 @@ class Launcher:
 
         @app.post("/launcher/modules/{name}/start")
         async def start_module(name: str):
-            """Start a module by name. Generates token and passes boot_info via stdin."""
+            """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")
 
-            # Generate token if not already present
             if name not in launcher._module_tokens:
                 launcher._module_tokens[name] = secrets.token_hex(32)
-                # Register the new token to Registry
                 try:
                     async with httpx.AsyncClient() as client:
                         await client.post(
@@ -801,14 +1002,10 @@ class Launcher:
                             timeout=5,
                         )
                 except Exception as e:
-                    print(f"[launcher] WARNING: failed to register token for {name}: {e}")
+                    print(f"[launcher] 警告: 注册 {name} 的令牌失败: {e}")
 
             token = launcher._module_tokens[name]
-            boot_info = {
-                "token": token,
-                "registry_port": launcher.registry_port,
-                "preferred_port": info.preferred_port,
-            }
+            boot_info = {"token": token}
             ok = launcher.process_manager.start_module(info, boot_info=boot_info)
             if ok:
                 launcher._desired_states[name] = "running"
@@ -823,7 +1020,7 @@ class Launcher:
 
         @app.post("/launcher/modules/{name}/stop")
         async def stop_module(name: str, body: dict = None):
-            """Stop a module with graceful shutdown. Accepts optional reason."""
+            """Stop a module with graceful shutdown."""
             info = launcher.modules.get(name)
             if not info:
                 raise HTTPException(404, f"Module '{name}' not found")
@@ -843,7 +1040,6 @@ class Launcher:
                 raise HTTPException(403, f"Module '{name}' is disabled")
             reason = (body or {}).get("reason", "restart")
             await launcher._graceful_stop(name, reason)
-            # Re-generate token
             launcher._module_tokens[name] = secrets.token_hex(32)
             try:
                 async with httpx.AsyncClient() as client:
@@ -856,11 +1052,7 @@ class Launcher:
             except Exception:
                 pass
             token = launcher._module_tokens[name]
-            boot_info = {
-                "token": token,
-                "registry_port": launcher.registry_port,
-                "preferred_port": info.preferred_port,
-            }
+            boot_info = {"token": token}
             ok = launcher.process_manager.start_module(info, boot_info=boot_info)
             if ok:
                 launcher._desired_states[name] = "running"
@@ -884,11 +1076,9 @@ class Launcher:
             for name in added:
                 info = launcher.modules[name]
                 launcher._log_lifecycle("scanned", name, state=info.state, module_dir=info.module_dir)
-            # Initialize desired_state for new modules
             for name in added:
                 info = launcher.modules[name]
                 launcher._desired_states[name] = "running" if info.state == "enabled" else "stopped"
-            # Register tokens for new modules
             if added:
                 new_tokens = {}
                 for name in added:
@@ -917,14 +1107,12 @@ class Launcher:
             if new_state not in ("enabled", "manual", "disabled"):
                 raise HTTPException(400, "state must be enabled, manual, or disabled")
 
-            # Core modules cannot be disabled
-            if info.is_core(launcher.project_root) and new_state == "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
 
-            # Update desired_state to match new config_state
             if new_state == "enabled":
                 launcher._desired_states[name] = "running"
             else:
@@ -956,7 +1144,6 @@ def _update_module_md_state(module_dir: str, new_state: str):
         with open(md_path, "r", encoding="utf-8") as f:
             content = f.read()
 
-        # Replace state: xxx in frontmatter
         updated = re.sub(
             r'^(state:\s*)(\S+)',
             rf'\g<1>{new_state}',
@@ -968,4 +1155,4 @@ def _update_module_md_state(module_dir: str, new_state: str):
         with open(md_path, "w", encoding="utf-8") as f:
             f.write(updated)
     except Exception as e:
-        print(f"[launcher] WARNING: failed to update module.md state: {e}")
+        print(f"[launcher] 警告: 更新 module.md 状态失败: {e}")