@agentunion/kite 1.0.6 → 1.2.0

package/core/launcher/process_manager.py

@@ -1,16 +1,27 @@
 """
 Manage child process lifecycle: start, stop, monitor, cleanup leftovers.
 Cross-platform support for Windows, Linux, and macOS.
+
+stdio lifecycle:
+- stdin: write boot_info → keep open (Launcher may send more messages) → close after module.ready
+- stdout: read structured messages + log lines → close after module.ready
+- Structured messages: JSON lines with "kite" field, dispatched via callback
 """
 
+import glob
 import json
 import os
+import re
 import subprocess
 import sys
 import threading
 import time
 from dataclasses import dataclass, asdict
+from typing import Callable
 
+if sys.platform == "win32":
+    import ctypes
+    from ctypes import wintypes
 
 IS_WINDOWS = sys.platform == "win32"
 IS_MACOS = sys.platform == "darwin"
@@ -28,105 +39,322 @@ class ProcessRecord:
 class ProcessManager:
     """Manage child processes for all Kite modules."""
 
-    def __init__(self, project_root: str, kite_token: str, instance_id: str = ""):
-        self.project_root = project_root
+    def __init__(self, kite_token: str, instance_id: str = "",
+                 on_kite_message: Callable[[str, dict], None] | None = None):
+        """
+        Args:
+            on_kite_message: callback(module_name, msg_dict) for structured stdout messages.
+                             Called from stdout reader thread — must be thread-safe.
+        """
         self.kite_token = kite_token
         self.instance_id = instance_id or str(os.getpid())
-        # Use centralized data directory management
-        sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-        from data_dir import get_launcher_data_dir
-        self.data_dir = get_launcher_data_dir()
-        self.records_path = os.path.join(self.data_dir, f"processes_{self.instance_id}.json")
+        self._on_kite_message = on_kite_message
+        # Use KITE_MODULE_DATA (set by Launcher for itself)
+        launcher_dir = os.environ.get("KITE_MODULE_DATA") or os.path.join(os.environ["KITE_INSTANCE_DIR"], "launcher")
+        self.data_dir = os.path.join(launcher_dir, "state")
+        os.makedirs(self.data_dir, exist_ok=True)
+        self._instance_num = self._allocate_instance_num()
+        suffix = "" if self._instance_num == 1 else f"~{self._instance_num}"
+        self._instance_suffix = suffix
+        self.records_path = os.path.join(self.data_dir, f"processes{suffix}.json")
         self._processes: dict[str, subprocess.Popen] = {}   # name -> Popen
         self._records: dict[str, ProcessRecord] = {}         # name -> record
-        os.makedirs(self.data_dir, exist_ok=True)
 
-    # ── Leftover cleanup ──
+    @property
+    def instance_suffix(self) -> str:
+        """Return the instance suffix (empty string for instance 1, '~N' for N>1)."""
+        return self._instance_suffix
 
-    def cleanup_leftovers(self):
-        """Scan all processes_*.json files, kill leftovers from dead instances, preserve live ones."""
-        import glob
-
-        # Also clean legacy processes.json (pre-multi-instance)
-        legacy = os.path.join(self.data_dir, "processes.json")
-        patterns = [
-            os.path.join(self.data_dir, "processes_*.json"),
-        ]
-        files = []
-        for p in patterns:
-            files.extend(glob.glob(p))
-        if os.path.isfile(legacy):
-            files.append(legacy)
-
-        registry_data_dir = os.path.join(self.project_root, "core", "registry", "data")
-        # Also check user home registry data dir
-        sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-        from data_dir import get_registry_data_dir
-        registry_data_dir_alt = get_registry_data_dir()
-
-        for path in files:
-            if path == self.records_path:
-                continue  # skip our own instance
-
-            # If this is an instance file, check if that Launcher is still alive
-            basename = os.path.basename(path)
-            if basename.startswith("processes_") and basename.endswith(".json"):
-                inst_id = basename[len("processes_"):-len(".json")]
-                try:
-                    if self._is_pid_alive(int(inst_id)):
-                        continue  # that Launcher is still running, skip
-                except (ValueError, TypeError):
-                    pass
+    @property
+    def instance_num(self) -> int:
+        """Return the instance number (1-based)."""
+        return self._instance_num
 
+    def get_alive_instances(self) -> list[dict]:
+        """Scan processes*.json and return info about all alive instances (including self).
+
+        Returns list of dicts: {"num": int, "launcher_pid": int, "module_count": int, "is_self": bool, "debug": bool, "cwd": str}.
+        """
+        instances = []
+        pattern = os.path.join(self.data_dir, "processes*.json")
+        for filepath in glob.glob(pattern):
+            basename = os.path.basename(filepath)
+            num = self._parse_instance_num(basename)
+            if num is None:
+                continue
+            pid = self._read_launcher_pid(filepath)
+            is_self = (pid == os.getpid())
+            if not is_self and (not pid or not self._is_pid_alive(pid)):
+                continue
+            # Read module count, debug flag, and cwd
+            module_count = 0
+            debug = False
+            cwd = ""
             try:
-                with open(path, "r", encoding="utf-8") as f:
-                    saved = json.load(f)
+                with open(filepath, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                if isinstance(data, dict):
+                    module_count = len(data.get("records", []))
+                    debug = data.get("debug", False)
+                    cwd = data.get("cwd", "")
+                elif isinstance(data, list):
+                    module_count = len(data)
             except Exception:
-                os.remove(path)
+                pass
+            instances.append({
+                "num": num,
+                "launcher_pid": pid or 0,
+                "module_count": module_count,
+                "is_self": is_self,
+                "debug": debug,
+                "cwd": cwd,
+            })
+        instances.sort(key=lambda x: x["num"])
+        return instances
+
+    def get_global_instances(self) -> list[dict]:
+        """Scan all instance dirs under KITE_WORKSPACE for alive launcher instances.
+
+        Returns list of dicts:
+            {"instance_dir": str, "cwd": str, "num": int, "launcher_pid": int,
+             "module_count": int, "is_self": bool, "debug": bool}
+        """
+        workspace = os.environ.get("KITE_WORKSPACE", "")
+        if not workspace or not os.path.isdir(workspace):
+            return []
+
+        my_pid = os.getpid()
+        my_instance_dir = os.environ.get("KITE_INSTANCE_DIR", "")
+        results = []
+
+        try:
+            entries = os.listdir(workspace)
+        except OSError:
+            return []
+
+        for entry in entries:
+            inst_path = os.path.join(workspace, entry)
+            if not os.path.isdir(inst_path):
+                continue
+            state_dir = os.path.join(inst_path, "launcher", "state")
+            if not os.path.isdir(state_dir):
                 continue
 
-            for entry in saved:
-                pid = entry.get("pid", 0)
-                cmd = entry.get("cmd", [])
-                name = entry.get("name", "?")
-                if not pid:
+            # Read .cwd for display (fallback if processes.json lacks cwd)
+            cwd_from_file = ""
+            cwd_file = os.path.join(inst_path, ".cwd")
+            try:
+                with open(cwd_file, "r", encoding="utf-8") as f:
+                    cwd_from_file = f.read().strip()
+            except Exception:
+                pass
+
+            # Scan processes*.json in this instance's state dir
+            pattern = os.path.join(state_dir, "processes*.json")
+            for filepath in glob.glob(pattern):
+                basename = os.path.basename(filepath)
+                num = self._parse_instance_num(basename)
+                if num is None:
                     continue
-                if self._is_pid_alive(pid) and self._cmd_matches(pid, cmd):
-                    print(f"[launcher] Killing leftover process: {name} (PID {pid})")
-                    self._force_kill(pid)
-                else:
-                    print(f"[launcher] Leftover {name} (PID {pid}) already gone")
-
-            os.remove(path)
-
-            # Remove corresponding port file
-            basename = os.path.basename(path)
-            if basename.startswith("processes_") and basename.endswith(".json"):
-                inst_id = basename[len("processes_"):-len(".json")]
-                port_file = os.path.join(registry_data_dir, f"port_{inst_id}.txt")
-                if os.path.isfile(port_file):
-                    os.remove(port_file)
-                # Also check alt location
-                port_file_alt = os.path.join(registry_data_dir_alt, f"port_{inst_id}.txt")
-                if os.path.isfile(port_file_alt):
-                    os.remove(port_file_alt)
-
-            # Also clean legacy port.txt
-            legacy_port = os.path.join(registry_data_dir, "port.txt")
-            if os.path.isfile(legacy_port):
-                os.remove(legacy_port)
+                pid = self._read_launcher_pid(filepath)
+                is_self_dir = (os.path.normcase(os.path.normpath(inst_path))
+                               == os.path.normcase(os.path.normpath(my_instance_dir)))
+                is_self = (pid == my_pid and is_self_dir)
+                if not is_self and (not pid or not self._is_pid_alive(pid)):
+                    continue
+
+                # Read metadata
+                module_count = 0
+                debug = False
+                cwd = ""
+                try:
+                    with open(filepath, "r", encoding="utf-8") as f:
+                        data = json.load(f)
+                    if isinstance(data, dict):
+                        module_count = len(data.get("records", []))
+                        debug = data.get("debug", False)
+                        cwd = data.get("cwd", "")
+                    elif isinstance(data, list):
+                        module_count = len(data)
+                except Exception:
+                    pass
+
+                results.append({
+                    "instance_dir": entry,  # basename of instance dir
+                    "cwd": cwd or cwd_from_file,
+                    "num": num,
+                    "launcher_pid": pid or 0,
+                    "module_count": module_count,
+                    "is_self": is_self,
+                    "debug": debug,
+                })
+
+        results.sort(key=lambda x: (x["instance_dir"], x["num"]))
+        return results
+
+    def _allocate_instance_num(self) -> int:
+        """Scan processes*.json in data_dir and allocate the smallest available instance number.
+
+        An instance number is "available" if:
+        - No corresponding processes file exists, OR
+        - The file exists but its launcher_pid is dead (stale file from a crashed instance).
+        """
+        # Collect occupied instance numbers (whose launcher is still alive)
+        occupied: set[int] = set()
+        pattern = os.path.join(self.data_dir, "processes*.json")
+        for filepath in glob.glob(pattern):
+            basename = os.path.basename(filepath)
+            num = self._parse_instance_num(basename)
+            if num is None:
+                continue
+            pid = self._read_launcher_pid(filepath)
+            if pid and pid != os.getpid() and self._is_pid_alive(pid):
+                occupied.add(num)
+
+        # Allocate smallest available number starting from 1
+        num = 1
+        while num in occupied:
+            num += 1
+        return num
+
+    @staticmethod
+    def _parse_instance_num(basename: str) -> int | None:
+        """Extract instance number from a processes filename.
+
+        'processes.json' -> 1, 'processes~3.json' -> 3, other -> None.
+        """
+        if basename == "processes.json":
+            return 1
+        m = re.match(r"^processes~(\d+)\.json$", basename)
+        return int(m.group(1)) if m else None
+
+    @staticmethod
+    def _read_launcher_pid(filepath: str) -> int | None:
+        """Read launcher_pid from a processes JSON file. Returns None on error or old format."""
+        try:
+            with open(filepath, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            if isinstance(data, dict):
+                return data.get("launcher_pid")
+        except Exception:
+            pass
+        return None
+
+    # ── Leftover cleanup ──
+
+    def cleanup_leftovers(self) -> dict[str, int]:
+        """Scan all processes*.json in data_dir (current instance dir only), clean up dead instances' child processes.
+
+        Returns dict: {instance_dir_basename: killed_count}.
+        """
+        my_pid = os.getpid()
+        inst_name = os.path.basename(os.environ.get("KITE_INSTANCE_DIR", "")) or "unknown"
+        killed = 0
+        pattern = os.path.join(self.data_dir, "processes*.json")
+        for filepath in glob.glob(pattern):
+            killed += self._cleanup_one_leftover_file(filepath, my_pid)
+        return {inst_name: killed} if killed else {}
+
+    def cleanup_global_leftovers(self) -> dict[str, int]:
+        """Scan all instance dirs under KITE_WORKSPACE for dead launcher files.
+
+        Same logic as cleanup_leftovers() but across all workspace instances.
+        Designed to run via run_in_executor (synchronous, blocking I/O).
+        Returns dict: {instance_dir_basename: killed_count}.
+        """
+        workspace = os.environ.get("KITE_WORKSPACE", "")
+        if not workspace or not os.path.isdir(workspace):
+            return {}
+
+        my_pid = os.getpid()
+        result: dict[str, int] = {}
+
+        try:
+            entries = os.listdir(workspace)
+        except OSError:
+            return {}
+
+        for entry in entries:
+            state_dir = os.path.join(workspace, entry, "launcher", "state")
+            if not os.path.isdir(state_dir):
+                continue
+            pattern = os.path.join(state_dir, "processes*.json")
+            for filepath in glob.glob(pattern):
+                killed = self._cleanup_one_leftover_file(filepath, my_pid)
+                if killed:
+                    result[entry] = result.get(entry, 0) + killed
+        return result
+
+    def _cleanup_one_leftover_file(self, filepath: str, my_pid: int) -> int:
+        """Process a single processes*.json file for leftover cleanup.
+
+        - Skip if launcher_pid matches my_pid (our own records).
+        - Skip if launcher_pid is still alive (parallel instance).
+        - Otherwise clean up child processes and delete the file.
+        Returns number of processes killed.
+        """
+        try:
+            with open(filepath, "r", encoding="utf-8") as f:
+                saved = json.load(f)
+        except Exception:
+            try:
+                os.remove(filepath)
+            except OSError:
+                pass
+            return 0
+
+        # New format: {"launcher_pid": N, "records": [...]}
+        # Old format: plain array [...]
+        if isinstance(saved, dict):
+            launcher_pid = saved.get("launcher_pid")
+            records = saved.get("records", [])
+        elif isinstance(saved, list):
+            launcher_pid = None
+            records = saved
+        else:
+            try:
+                os.remove(filepath)
+            except OSError:
+                pass
+            return 0
+
+        # Skip our own records (written by current process)
+        if launcher_pid == my_pid:
+            return 0
+
+        # If the owning launcher is still alive, skip this file (parallel instance)
+        if launcher_pid and self._is_pid_alive(launcher_pid):
+            return 0
+
+        # Dead launcher (or old format) — clean up its child processes
+        killed = 0
+        for entry in records:
+            pid = entry.get("pid", 0)
+            cmd = entry.get("cmd", [])
+            name = entry.get("name", "?")
+            if not pid:
+                continue
+            if self._is_pid_alive(pid) and self._cmd_matches(pid, cmd):
+                print(f"[launcher] 正在清理残留进程: {name} (PID {pid}) [{os.path.basename(filepath)}]")
+                self._force_kill(pid)
+                killed += 1
+            else:
+                print(f"[launcher] 残留进程 {name} (PID {pid}) 已不存在")
+
+        try:
+            os.remove(filepath)
+        except OSError:
+            pass
+        return killed
 
     def _is_pid_alive(self, pid: int) -> bool:
-        """Check if a process with given PID exists."""
+        """Check if a process with given PID exists.
+
+        Windows: Uses OpenProcess API via ctypes (fast, ~0.1ms per check).
+        Linux/macOS: Uses os.kill(pid, 0) signal check.
+        """
         if IS_WINDOWS:
-            try:
-                result = subprocess.run(
-                    ["tasklist", "/FI", f"PID eq {pid}", "/NH"],
-                    capture_output=True, text=True, timeout=5,
-                )
-                return str(pid) in result.stdout
-            except Exception:
-                return False
+            return self._win_is_pid_alive_ctypes(pid)
         else:
             try:
                 os.kill(pid, 0)
@@ -134,6 +362,95 @@ class ProcessManager:
             except OSError:
                 return False
 
+    def _win_get_all_alive_pids(self) -> set:
+        """Windows: Get all alive PIDs in one batch call (fallback optimization).
+
+        Returns set of PIDs. Returns empty set on failure.
+        """
+        if not IS_WINDOWS:
+            return set()
+
+        try:
+            result = subprocess.run(
+                ["tasklist", "/FO", "CSV", "/NH"],
+                capture_output=True, timeout=10,
+            )
+            # Use errors='replace' to handle any encoding (GBK, UTF-8, etc.)
+            stdout = result.stdout.decode(errors='replace')
+            pids = set()
+            for line in stdout.strip().split('\n'):
+                if not line:
+                    continue
+                # CSV format: "image_name","pid","session_name","session#","mem_usage"
+                parts = line.split(',')
+                if len(parts) >= 2:
+                    try:
+                        pid_str = parts[1].strip('" \r')
+                        pids.add(int(pid_str))
+                    except (ValueError, IndexError):
+                        continue
+            return pids
+        except Exception:
+            return set()
+
+    def _win_is_pid_alive_ctypes(self, pid: int) -> bool:
+        """Windows: Check if PID exists and is still running using OpenProcess API.
+
+        Returns True only if process exists AND has not exited.
+        Handles zombie processes (exited but handle still open) correctly
+        by checking GetExitCodeProcess after OpenProcess succeeds.
+
+        Falls back to batch tasklist on ctypes failure (rare).
+        """
+        if not IS_WINDOWS:
+            return False
+
+        # Constants from Windows API
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        ERROR_INVALID_PARAMETER = 87
+        ERROR_ACCESS_DENIED = 5
+        STILL_ACTIVE = 259
+
+        try:
+            # Try to open the process with minimal permissions
+            handle = ctypes.windll.kernel32.OpenProcess(
+                PROCESS_QUERY_LIMITED_INFORMATION,
+                False,  # bInheritHandle
+                pid
+            )
+
+            if handle:
+                try:
+                    # OpenProcess succeeds even for zombie processes (exited but handle
+                    # not yet closed by parent). Check actual exit status.
+                    exit_code = wintypes.DWORD()
+                    if ctypes.windll.kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+                        return exit_code.value == STILL_ACTIVE
+                    # GetExitCodeProcess failed — assume alive to be safe
+                    return True
+                finally:
+                    ctypes.windll.kernel32.CloseHandle(handle)
+
+            # OpenProcess failed, check why
+            error_code = ctypes.windll.kernel32.GetLastError()
+
+            if error_code == ERROR_ACCESS_DENIED:
+                # Process exists but we don't have permission (e.g., SYSTEM process)
+                # For our use case, this means it's NOT our child process
+                return False
+            elif error_code == ERROR_INVALID_PARAMETER:
+                # Invalid PID (process doesn't exist)
+                return False
+            else:
+                # Other errors (e.g., process exited between check and open)
+                return False
+
+        except Exception:
+            # Fallback: batch tasklist (fetch once, cache for subsequent calls)
+            if not hasattr(self, '_alive_pids_cache'):
+                self._alive_pids_cache = self._win_get_all_alive_pids()
+            return pid in self._alive_pids_cache
+
     def _cmd_matches(self, pid: int, expected_cmd: list) -> bool:
         """Verify the process command line matches what we expect (prevent killing recycled PIDs).
         Uses multi-strategy fallback per platform for robustness.
@@ -181,9 +498,9 @@ class ProcessManager:
             r = subprocess.run(
                 ["powershell", "-NoProfile", "-Command",
                  f"(Get-CimInstance Win32_Process -Filter 'ProcessId={pid}').CommandLine"],
-                capture_output=True, text=True, timeout=8,
+                capture_output=True, timeout=8,
             )
-            return r.stdout.strip()
+            return r.stdout.decode(errors='replace').strip()
         except Exception:
             return ""
 
@@ -193,22 +510,31 @@ class ProcessManager:
             r = subprocess.run(
                 ["wmic", "process", "where", f"ProcessId={pid}",
                  "get", "CommandLine", "/value"],
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, timeout=5,
             )
-            return r.stdout.strip()
+            return r.stdout.decode(errors='replace').strip()
         except Exception:
             return ""
 
     def _exe_name_matches(self, pid: int, expected_cmd: list) -> bool:
-        """Last resort: check if process image name matches expected executable."""
+        """Last resort: check if process image name matches expected executable.
+
+        Windows: Uses OpenProcess + QueryFullProcessImageName for fast check.
+        Falls back to tasklist if ctypes fails.
+        """
         exe = os.path.basename(expected_cmd[0]).lower()
         if exe.endswith(".exe"):
             exe = exe[:-4]
         if IS_WINDOWS:
+            # Try fast ctypes method first
+            image_name = self._win_get_image_name_ctypes(pid)
+            if image_name:
+                return exe in image_name.lower()
+            # Fallback to tasklist
             try:
                 r = subprocess.run(["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"],
-                                   capture_output=True, text=True, timeout=5)
-                return exe in r.stdout.lower()
+                                   capture_output=True, timeout=5)
+                return exe in r.stdout.decode(errors='replace').lower()
             except Exception:
                 return False
         else:
@@ -219,6 +545,50 @@ class ProcessManager:
             except Exception:
                 return False
 
+    def _win_get_image_name_ctypes(self, pid: int) -> str:
+        """Windows: Get process image name using OpenProcess + QueryFullProcessImageName.
+
+        Returns empty string on failure.
+        """
+        if not IS_WINDOWS:
+            return ""
+
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+
+        try:
+            handle = ctypes.windll.kernel32.OpenProcess(
+                PROCESS_QUERY_LIMITED_INFORMATION,
+                False,
+                pid
+            )
+
+            if not handle:
+                return ""
+
+            try:
+                # Buffer for image name (MAX_PATH = 260)
+                buffer_size = wintypes.DWORD(260)
+                buffer = ctypes.create_unicode_buffer(buffer_size.value)
+
+                # QueryFullProcessImageNameW
+                success = ctypes.windll.kernel32.QueryFullProcessImageNameW(
+                    handle,
+                    0,  # dwFlags (0 = Win32 path format)
+                    buffer,
+                    ctypes.byref(buffer_size)
+                )
+
+                if success:
+                    return os.path.basename(buffer.value)
+                else:
+                    return ""
+
+            finally:
+                ctypes.windll.kernel32.CloseHandle(handle)
+
+        except Exception:
+            return ""
+
     def _force_kill(self, pid: int):
         """Force kill a process by PID."""
         try:
@@ -229,13 +599,14 @@ class ProcessManager:
                 import signal
                 os.kill(pid, signal.SIGKILL)
         except Exception as e:
-            print(f"[launcher] WARNING: failed to kill PID {pid}: {e}")
+            print(f"[launcher] 警告: 强制终止 PID {pid} 失败: {e}")
 
     # ── Start module ──
 
     def start_module(self, info, boot_info: dict = None) -> bool:
         """Start a module as a subprocess. Returns True on success.
         If boot_info is provided, it is written as JSON to the child's stdin pipe.
+        stdin is kept open after boot_info for Launcher to send additional messages.
         """
         from .module_scanner import ModuleInfo
         info: ModuleInfo
@@ -243,17 +614,18 @@ class ProcessManager:
         if info.name in self._processes:
             proc = self._processes[info.name]
             if proc.poll() is None:
-                print(f"[launcher] {info.name} already running (PID {proc.pid})")
+                print(f"[launcher] {info.name} 已在运行 (PID {proc.pid})")
                 return True
 
         cmd = self._build_cmd(info)
         if not cmd:
-            print(f"[launcher] ERROR: cannot build command for {info.name}")
+            print(f"[launcher] 错误: 无法构建 {info.name} 的启动命令")
             return False
 
         env = os.environ.copy()
         env["PYTHONUTF8"] = "1"           # Force UTF-8 in child Python processes
         env["PYTHONUNBUFFERED"] = "1"     # Disable output buffering for real-time logs
+        env["KITE_MODULE_DATA"] = os.path.join(os.environ["KITE_INSTANCE_DIR"], info.name)
         if info.launch.env:
             env.update(info.launch.env)
 
@@ -278,17 +650,16 @@ class ProcessManager:
                 creationflags=creation_flags,
             )
         except Exception as e:
-            print(f"[launcher] ERROR: failed to start {info.name}: {e}")
+            print(f"[launcher] 错误: 启动 {info.name} 失败: {e}")
             return False
 
-        # Write boot_info to stdin then close
+        # Write boot_info to stdin — keep stdin open for additional messages
         if use_stdin and proc.stdin:
             try:
                 proc.stdin.write(json.dumps(boot_info).encode() + b"\n")
                 proc.stdin.flush()
-                proc.stdin.close()
             except Exception as e:
-                print(f"[launcher] WARNING: failed to write boot_info to {info.name}: {e}")
+                print(f"[launcher] 警告: 向 {info.name} 写入 boot_info 失败: {e}")
 
         self._processes[info.name] = proc
         self._records[info.name] = ProcessRecord(
@@ -299,16 +670,47 @@ class ProcessManager:
             started_at=time.time(),
         )
 
-        # Daemon thread to read stdout and prefix with module name
+        # Daemon thread to read stdout: structured messages + log lines
         t = threading.Thread(
             target=self._read_stdout, args=(info.name, proc),
             daemon=True,
         )
         t.start()
 
-        print(f"[launcher] Started {info.name} (PID {proc.pid})")
+        print(f"[launcher] 已启动 {info.name} (PID {proc.pid})")
         return True
 
+    def write_stdin(self, name: str, data: dict) -> bool:
+        """Write a structured JSON message to a module's stdin.
+        Used by Launcher to send additional messages after boot_info (e.g. launcher_ws_token).
+        Returns True on success.
+        """
+        proc = self._processes.get(name)
+        if not proc or not proc.stdin or proc.stdin.closed:
+            return False
+        try:
+            proc.stdin.write(json.dumps(data).encode() + b"\n")
+            proc.stdin.flush()
+            return True
+        except Exception as e:
+            print(f"[launcher] 警告: 向 {name} 写入 stdin 失败: {e}")
+            return False
+
+    def close_stdio(self, name: str):
+        """Close stdin for a module. Called by Launcher after module.ready → module.started.
+        Only closes stdin (no more messages to send). stdout is left open so the reader
+        thread can continue relaying logs — it exits naturally when the process dies.
+        On Windows, closing stdout while a reader thread is blocked on readline() can deadlock.
+        """
+        proc = self._processes.get(name)
+        if not proc:
+            return
+        if proc.stdin and not proc.stdin.closed:
+            try:
+                proc.stdin.close()
+            except Exception:
+                pass
+
     def _build_cmd(self, info) -> list:
         """Build the command list based on module runtime.
 
@@ -329,16 +731,32 @@ class ProcessManager:
         elif info.runtime == "binary":
             return [os.path.join(info.module_dir, info.entry)]
         else:
-            print(f"[launcher] WARNING: unknown runtime '{info.runtime}' for {info.name}")
+            print(f"[launcher] 警告: 未知运行时 '{info.runtime}'，模块 {info.name}")
             return []
 
-    @staticmethod
-    def _read_stdout(name: str, proc: subprocess.Popen):
-        """Read subprocess stdout line by line, prefix with module name."""
+    def _read_stdout(self, name: str, proc: subprocess.Popen):
+        """Read subprocess stdout line by line.
+        Lines containing a JSON object with "kite" field are dispatched as structured messages.
+        All other lines are printed as log output with module name prefix.
+        """
         try:
             for line in iter(proc.stdout.readline, b""):
                 text = line.decode("utf-8", errors="replace").rstrip()
-                if text:
+                if not text:
+                    continue
+                # Try to parse as structured kite message
+                if self._on_kite_message and text.startswith("{"):
+                    try:
+                        msg = json.loads(text)
+                        if isinstance(msg, dict) and "kite" in msg:
+                            self._on_kite_message(name, msg)
+                            continue
+                    except (json.JSONDecodeError, KeyError):
+                        pass
+                # Regular log line — avoid double prefix if module already added [name]
+                if text.startswith(f"[{name}]"):
+                    print(text)
+                else:
                     print(f"[{name}] {text}")
         except Exception:
             pass
@@ -353,12 +771,15 @@ class ProcessManager:
             self._records.pop(name, None)
             return True
 
-        print(f"[launcher] Stopping {name} (PID {proc.pid})...")
+        # Close stdio before terminating
+        self.close_stdio(name)
+
+        print(f"[launcher] 正在停止 {name} (PID {proc.pid})...")
         proc.terminate()
         try:
             proc.wait(timeout=timeout)
         except subprocess.TimeoutExpired:
-            print(f"[launcher] {name} did not exit in {timeout}s, force killing")
+            print(f"[launcher] {name} 在 {timeout}s 内未退出，强制终止")
             proc.kill()
             try:
                 proc.wait(timeout=3)
@@ -367,7 +788,7 @@ class ProcessManager:
 
         self._processes.pop(name, None)
         self._records.pop(name, None)
-        print(f"[launcher] Stopped {name}")
+        print(f"[launcher] 已停止 {name}")
         return True
 
     def stop_all(self, timeout: float = 10):
@@ -375,18 +796,26 @@ class ProcessManager:
         if not self._processes:
             return
 
-        names = list(self._processes.keys())
-        print(f"[launcher] Stopping all modules: {', '.join(names)}")
+        # Filter to only still-running processes
+        alive = [n for n, p in self._processes.items() if p.poll() is None]
+        if not alive:
+            # All already exited — just clean up bookkeeping
+            self._processes.clear()
+            self._records.clear()
+            return
+
+        print(f"[launcher] 正在停止所有模块: {', '.join(alive)}")
 
-        # Phase 1: send terminate to all
-        for name in names:
+        # Phase 1: close stdio and send terminate to all
+        for name in alive:
+            self.close_stdio(name)
             proc = self._processes.get(name)
             if proc and proc.poll() is None:
                 proc.terminate()
 
         # Phase 2: wait for all to exit
         deadline = time.time() + timeout
-        for name in names:
+        for name in alive:
             proc = self._processes.get(name)
             if not proc:
                 continue
@@ -397,10 +826,10 @@ class ProcessManager:
                 pass
 
         # Phase 3: force kill survivors
-        for name in names:
+        for name in alive:
             proc = self._processes.get(name)
             if proc and proc.poll() is None:
-                print(f"[launcher] Force killing {name} (PID {proc.pid})")
+                print(f"[launcher] 强制终止 {name} (PID {proc.pid})")
                 proc.kill()
                 try:
                     proc.wait(timeout=3)
@@ -409,13 +838,18 @@ class ProcessManager:
 
         self._processes.clear()
         self._records.clear()
-        print("[launcher] All modules stopped")
+        print("[launcher] 所有模块已停止")
 
     # ── Persistence & monitoring ──
 
     def persist_records(self):
-        """Write current process records to processes.json."""
-        data = [asdict(r) for r in self._records.values()]
+        """Write current process records to processes.json (with launcher_pid for multi-instance)."""
+        data = {
+            "launcher_pid": os.getpid(),
+            "debug": os.environ.get("KITE_DEBUG") == "1",
+            "cwd": os.environ.get("KITE_CWD", ""),
+            "records": [asdict(r) for r in self._records.values()],
+        }
         self._write_records_file(data)
 
     def check_exited(self) -> list[tuple[str, int]]:
@@ -437,10 +871,10 @@ class ProcessManager:
         proc = self._processes.get(name)
         return proc is not None and proc.poll() is None
 
-    def _write_records_file(self, data: list):
-        """Write data list to processes.json."""
+    def _write_records_file(self, data):
+        """Write data to the instance's processes JSON file."""
         try:
             with open(self.records_path, "w", encoding="utf-8") as f:
                 json.dump(data, f, indent=2)
         except Exception as e:
-            print(f"[launcher] WARNING: failed to write processes.json: {e}")
+            print(f"[launcher] 警告: 写入 {os.path.basename(self.records_path)} 失败: {e}")