@agentunion/kite 1.0.0

package/core/launcher/entry.py

@@ -0,0 +1,965 @@
+"""
+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
+- (Windows) keyboard listener thread: polls for 'q' key
+"""
+
+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 fastapi.responses import JSONResponse
+
+from .module_scanner import ModuleScanner, ModuleInfo, _parse_frontmatter
+from .process_manager import ProcessManager
+
+IS_WINDOWS = sys.platform == "win32"
+
+
+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)
+        self.module_scanner = ModuleScanner(
+            self.project_root,
+            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
+        # 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._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]] = {}
+
+        self._lifecycle_log = os.path.join(
+            self.project_root, "core", "launcher", "data", "log", "lifecycle.jsonl",
+        )
+        self._app = self._create_api_app()
+
+    # ── 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}")
+
+        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 _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()
+        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."""
+        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()
+                        return
+                time.sleep(0.1)
+        t = threading.Thread(target=_listen, daemon=True)
+        t.start()
+
+    # ── Async main ──
+
+    async def _async_main(self):
+        """Full startup sequence, then monitor loop."""
+        self._loop = asyncio.get_running_loop()
+
+        # Step 1: cleanup leftovers
+        self.process_manager.cleanup_leftovers()
+
+        # Step 2: start Registry
+        await self._start_registry()
+
+        # Step 3: start Launcher API in a separate thread
+        self._start_api_thread()
+
+        # Step 4: register Launcher to Registry
+        await self._register_self()
+
+        # Step 5: scan modules
+        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)'}")
+
+        # Step 5.5: 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"
+
+        # 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()
+
+        # Step 8: persist records
+        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)")
+        await self._monitor_loop()
+
+        # Graceful shutdown all modules before event loop closes
+        await self._graceful_shutdown_all()
+
+    # ── Event Hub connection ──
+
+    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}"
+        headers = {"Authorization": f"Bearer {self.kite_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)
+
+        if not self._event_hub_ws_url:
+            print("[launcher] WARNING: Could not discover Event Hub WS, events disabled")
+            return
+
+        print(f"[launcher] Event Hub discovered: {self._event_hub_ws_url}")
+        self._ws_task = asyncio.create_task(self._ws_loop())
+
+    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 connection error: {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:
+            self._ws = ws
+            print("[launcher] Connected to 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 error: {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] Failed to publish event: {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)
+        # 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)
+        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)]
+        if not running:
+            return
+        print(f"[launcher] Graceful shutdown: {', '.join(running)}")
+        # Broadcast shutdown event
+        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)]
+            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
+
+    # ── 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}")
+
+        # Clean our instance's port file before starting
+        port_file = os.path.join(registry_dir, "data", 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]:
+        """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 event, start process, wait for ready."""
+        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",
+        }
+        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] Module '{info.name}' is ready")
+        else:
+            print(f"[launcher] WARNING: '{info.name}' did not send module.ready within {timeout}s")
+
+        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)
+
+    async def _register_module_tokens(self):
+        """Generate per-module tokens and register the mapping to Registry."""
+        for name in self.modules:
+            self._module_tokens[name] = secrets.token_hex(32)
+
+        if not self._module_tokens:
+            return
+
+        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)
+                if resp.status_code == 200:
+                    print(f"[launcher] Registered {len(self._module_tokens)} module token(s)")
+                else:
+                    print(f"[launcher] WARNING: token registration returned {resp.status_code}")
+        except Exception as e:
+            print(f"[launcher] WARNING: failed to register module tokens: {e}")
+
+    # ── 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()
+
+        # 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(f"[launcher] API server started on port {self.api_port}")
+
+    # ── Monitor loop ──
+
+    async def _monitor_loop(self):
+        """Check child processes every second. Handle crashes."""
+        MAX_FAIL = 3
+        MAX_FAILED_MODULES = 3
+
+        while not self._thread_shutdown.is_set():
+            exited = self.process_manager.check_exited()
+
+            for name, rc in exited:
+                print(f"[launcher] Module '{name}' exited with code {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 info and info.is_core(self.project_root):
+                    print(f"[launcher] CRITICAL: core module '{name}' crashed, restarting all...")
+                    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] Restarting '{name}' (attempt {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")
+
+            # 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")
+                return
+
+            if exited:
+                self.process_manager.persist_records()
+
+            await asyncio.sleep(1)
+
+    async def _full_restart(self):
+        """Stop all modules, then re-run the startup sequence."""
+        print("[launcher] Full restart: stopping all modules...")
+
+        # Disconnect Event Hub
+        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
+
+        await self._graceful_shutdown_all()
+        self._fail_counts.clear()
+
+        self._module_tokens.clear()
+
+        print("[launcher] Full restart: re-running startup sequence...")
+        try:
+            await self._start_registry()
+            await self._register_self()
+            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()
+            self.process_manager.persist_records()
+            await self._connect_event_hub()
+            print("[launcher] Full restart complete, resuming monitor loop")
+            await self._monitor_loop()
+        except Exception as e:
+            print(f"[launcher] Full restart failed: {e}")
+
+    # ── Shutdown ──
+
+    def _final_cleanup(self):
+        """Called on exit — stop all processes, stop API, clear records."""
+        print("[launcher] Shutting down...")
+
+        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
+        port_file = os.path.join(self.project_root, "core", "registry", "data", f"port_{self.instance_id}.txt")
+        try:
+            os.remove(port_file)
+        except OSError:
+            pass
+        print("[launcher] Goodbye.")
+
+        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(self.project_root, "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())}")
+                return discovery
+        except Exception as e:
+            print(f"[launcher] WARNING: failed to read discovery config: {e}")
+        return None
+
+    def _log_lifecycle(self, event: str, module: str, **extra):
+        """Append one JSONL line to core/launcher/data/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  # closure reference
+
+        @app.get("/launcher/modules")
+        async def list_modules():
+            """List all modules and their current status (three-layer state model)."""
+            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. Generates token and passes boot_info via stdin."""
+            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(
+                            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] WARNING: failed to register token for {name}: {e}")
+
+            token = launcher._module_tokens[name]
+            boot_info = {
+                "token": token,
+                "registry_port": launcher.registry_port,
+                "preferred_port": info.preferred_port,
+            }
+            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. Accepts optional reason."""
+            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)
+            # Re-generate token
+            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,
+                "registry_port": launcher.registry_port,
+                "preferred_port": info.preferred_port,
+            }
+            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)
+            # 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:
+                    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")
+
+            # Core modules cannot be disabled
+            if info.is_core(launcher.project_root) 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:
+                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()
+
+        # Replace state: xxx in frontmatter
+        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] WARNING: failed to update module.md state: {e}")