@andespindola/crow-skills 0.25.0 → 0.26.1

package/skills/crow-uny-mcp/scripts/crow_mcp.py

@@ -0,0 +1,744 @@
+#!/usr/bin/env python3
+"""POSIX stdio MCP lifecycle proxy. No arbitrary process adoption or payload logs.
+
+Session profile preserves application state with owned-tree SIGSTOP standby after
+its first tools/call (memory retained). Restartable profile is opt-in: termination
+releases child memory but does not preserve application state.
+"""
+from __future__ import annotations
+
+import argparse
+import ctypes
+import hashlib
+import json
+import os
+import selectors
+import signal
+import stat
+import subprocess
+import sys
+import time
+import uuid
+from pathlib import Path
+
+MAX_LINE = 16 * 1024 * 1024
+MAX_OUTPUT = 32 * 1024 * 1024
+
+
+def canonical(value):
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def id_key(value):
+    return (type(value).__name__, value)
+
+
+def valid_id(value):
+    return value is None or (isinstance(value, (str, int)) and not isinstance(value, bool))
+
+
+def valid_message(value):
+    if not isinstance(value, dict) or value.get("jsonrpc") != "2.0":
+        return False
+    if "id" in value and not valid_id(value["id"]):
+        return False
+    if "method" in value:
+        return (isinstance(value["method"], str) and "result" not in value
+                and "error" not in value and ("params" not in value
+                or isinstance(value["params"], (dict, list))))
+    return ("id" in value and (("result" in value) != ("error" in value)))
+
+
+class PrivateStore:
+    """Directory-relative, no-follow I/O; atomic private cache/registry writes."""
+    def __init__(self, path):
+        path = os.path.abspath(os.path.expanduser(path))
+        fd = os.open("/", os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            for component in path.split("/"):
+                if not component:
+                    continue
+                try:
+                    nxt = os.open(component, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                                  dir_fd=fd)
+                except FileNotFoundError:
+                    os.mkdir(component, 0o700, dir_fd=fd)
+                    nxt = os.open(component, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                                  dir_fd=fd)
+                os.close(fd)
+                fd = nxt
+            os.fchmod(fd, 0o700)
+            self.fd = fd
+        except BaseException:
+            os.close(fd)
+            raise
+
+    def read(self, name):
+        try:
+            fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=self.fd)
+            with os.fdopen(fd, "rb") as stream:
+                info = os.fstat(stream.fileno())
+                if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_LINE:
+                    return None
+                return json.loads(stream.read(MAX_LINE + 1))
+        except (OSError, ValueError):
+            return None
+
+    def write(self, name, value):
+        # Reject an existing symlink, including before replacement.
+        def check_target():
+            try:
+                info = os.stat(name, dir_fd=self.fd, follow_symlinks=False)
+                if not stat.S_ISREG(info.st_mode):
+                    raise OSError("unsafe cache target")
+            except FileNotFoundError:
+                pass
+        check_target()
+        temp = ".tmp-" + uuid.uuid4().hex
+        fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                     0o600, dir_fd=self.fd)
+        try:
+            with os.fdopen(fd, "wb") as stream:
+                stream.write(canonical(value).encode())
+                stream.flush()
+                os.fsync(stream.fileno())
+            check_target()
+            os.replace(temp, name, src_dir_fd=self.fd, dst_dir_fd=self.fd)
+        finally:
+            try:
+                os.unlink(temp, dir_fd=self.fd)
+            except FileNotFoundError:
+                pass
+
+    def close(self):
+        os.close(self.fd)
+
+
+class _DarwinBSDInfo(ctypes.Structure):
+    # SDK sys/proc_info.h proc_bsdinfo; no third-party dependency.
+    _fields_ = [("prefix", ctypes.c_uint32 * 12),
+                ("comm", ctypes.c_char * 16), ("name", ctypes.c_char * 32),
+                ("middle", ctypes.c_uint32 * 6),
+                ("start_sec", ctypes.c_uint64), ("start_usec", ctypes.c_uint64)]
+
+
+_DARWIN_PROC = None
+if sys.platform == "darwin":
+    try:
+        _DARWIN_PROC = ctypes.CDLL("/usr/lib/libproc.dylib").proc_pidinfo
+        _DARWIN_PROC.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_uint64,
+                                ctypes.c_void_p, ctypes.c_int]
+        _DARWIN_PROC.restype = ctypes.c_int
+    except OSError:
+        pass
+
+
+def process_identity(pid):
+    """Kernel start identity, not PID alone or second-granularity ps time."""
+    try:
+        if sys.platform == "darwin" and _DARWIN_PROC is not None:
+            info = _DarwinBSDInfo()
+            if _DARWIN_PROC(pid, 3, 0, ctypes.byref(info), ctypes.sizeof(info)) == ctypes.sizeof(info):
+                return ("darwin", info.start_sec, info.start_usec)
+        elif sys.platform.startswith("linux"):
+            fields = Path("/proc").joinpath(str(pid), "stat").read_text().rsplit(") ", 1)[1].split()
+            return ("linux", fields[19])
+    except (OSError, ValueError, IndexError):
+        pass
+    return None  # Fail closed: an unverifiable process is never signaled.
+
+
+def process_snapshot():
+    """Read ancestry and attach precise start identities to each candidate PID."""
+    try:
+        out = subprocess.run(["ps", "-axo", "pid=,ppid=,lstart="],
+                             stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                             timeout=1, check=True, text=True).stdout
+        result = {}
+        for line in out.splitlines():
+            parts = line.split(None, 2)
+            if len(parts) == 3:
+                pid = int(parts[0])
+                identity = process_identity(pid)
+                if identity is not None:
+                    result[pid] = (int(parts[1]), identity)
+        return result
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return {}
+
+
+class Proxy:
+    def __init__(self, options, command, input_fd=0, output_fd=1):
+        self.options, self.command = options, command
+        self.input_fd, self.output_fd = input_fd, output_fd
+        self.store = PrivateStore(options.state_dir)
+        self.registry = "runtime-" + str(os.getpid()) + "-" + uuid.uuid4().hex + ".json"
+        self.sel = selectors.DefaultSelector()
+        self.sel.register(input_fd, selectors.EVENT_READ, "host")
+        os.set_blocking(output_fd, False)
+        self.outputs = {"host": bytearray(), "child": bytearray()}
+        self.write_fds = {"host": output_fd}
+        self.transport_failed = False
+        self.buffers = {"host": bytearray(), "child": bytearray()}
+        self.dropping = {"host": False, "child": False}
+        self.child = None
+        self.owned = {}
+        self.pending = {}
+        self.server_pending = set()
+        self.queue = []
+        self.initialized = False
+        self.init_params = None
+        self.init_request = None
+        self.cache = None
+        self.cache_name = None
+        self.ready = False
+        self.handshake_id = None
+        self.cold_id = None
+        self.started = 0.0
+        self.startup_ms = None
+        self.last_activity = time.monotonic()
+        self.last_snapshot = 0.0
+        self.pinned = False
+        self.suspended = False
+        self.resume_ms = None
+        self.subscriptions = set()
+        self.session_lost = False
+        self.stopping = False
+        self.last_telemetry = 0.0
+        self.telemetry("cold")
+
+    def telemetry(self, state=None):
+        if state is not None:
+            self.state = state
+        try:
+            self.store.write(self.registry, {
+                "state": self.state, "pid": os.getpid(),
+                "pid_identity": process_identity(os.getpid()),
+                "child_pid": self.child.pid if self.child else None,
+                "child_identity": process_identity(self.child.pid) if self.child else None,
+                "descendant_pids": sorted(self.owned),
+                "pending_client": len(self.pending),
+                "pending_server": len(self.server_pending),
+                "subscriptions": len(self.subscriptions),
+                "startup_ms": self.startup_ms,
+                "profile": self.options.profile,
+                "retainedMemory": bool(self.suspended),
+                "resume_ms": self.resume_ms,
+            })
+        except OSError:
+            pass  # Telemetry cannot break an otherwise valid protocol exchange.
+        self.last_telemetry = time.monotonic()
+
+    def queue_output(self, sink, message):
+        data = (canonical(message) + "\n").encode()
+        buffer = self.outputs[sink]
+        if len(buffer) + len(data) > MAX_OUTPUT:
+            if sink == "child":
+                self.crashed("MCP server input buffer exceeded; request was not retried")
+            else:
+                # The peer cannot receive even a bounded error. Close deterministically.
+                self.transport_failed = True
+                self.stopping = True
+            return False
+        was_empty = not buffer
+        buffer.extend(data)
+        if was_empty:
+            self.sel.register(self.write_fds[sink], selectors.EVENT_WRITE, sink + "_write")
+        return True
+
+    def flush_output(self, sink):
+        buffer = self.outputs[sink]
+        if not buffer or sink not in self.write_fds:
+            return
+        try:
+            size = os.write(self.write_fds[sink], memoryview(buffer)[:65536])
+            del buffer[:size]
+        except BlockingIOError:
+            return
+        except OSError:
+            if sink == "child":
+                self.crashed()
+            else:
+                self.transport_failed = True
+                self.stopping = True
+            return
+        if not buffer:
+            try:
+                self.sel.unregister(self.write_fds[sink])
+            except KeyError:
+                pass
+
+    def send(self, message):
+        return self.queue_output("host", message)
+
+    def error(self, ident, code, message):
+        self.send({"jsonrpc": "2.0", "id": ident,
+                   "error": {"code": code, "message": message}})
+
+    def child_send(self, message):
+        if self.child is None or self.child.stdin is None:
+            return False
+        return self.queue_output("child", message)
+
+    def cache_save(self):
+        if self.cache_name and self.cache:
+            try:
+                self.store.write(self.cache_name, self.cache)
+            except OSError:
+                pass
+
+    def cache_prepare(self, params):
+        material = {"command": self.command, "cwd": os.getcwd(),
+                    "env_hash": hashlib.sha256(canonical(dict(os.environ)).encode()).hexdigest(),
+                    "initialize": params}
+        self.cache_name = "metadata-" + hashlib.sha256(canonical(material).encode()).hexdigest() + ".json"
+        candidate = self.store.read(self.cache_name)
+        if (isinstance(candidate, dict) and candidate.get("schema") == 1
+                and isinstance(candidate.get("initialize"), dict)
+                and isinstance(candidate.get("tools"), dict)):
+            self.cache = candidate
+        else:
+            self.cache = {"schema": 1, "tools": {}}
+
+    def capture_owned(self):
+        if not self.child:
+            return
+        snapshot = process_snapshot()
+        root = self.child.pid
+        if root in snapshot and root not in self.owned:
+            self.owned[root] = snapshot[root][1]
+        # Only extend ancestry from still-matching owned identities.
+        parents = {p for p, identity in self.owned.items()
+                   if p in snapshot and snapshot[p][1] == identity}
+        changed = True
+        while changed:
+            changed = False
+            for pid, (ppid, identity) in snapshot.items():
+                if ppid in parents and pid not in parents:
+                    self.owned[pid] = identity
+                    parents.add(pid)
+                    changed = True
+        self.last_snapshot = time.monotonic()
+
+    def resume_child(self):
+        if not self.suspended:
+            return
+        began = time.monotonic()
+        snapshot = process_snapshot()
+        for pid, identity in self.owned.items():
+            if pid in snapshot and snapshot[pid][1] == identity and process_identity(pid) == identity:
+                try:
+                    os.kill(pid, signal.SIGCONT)
+                except ProcessLookupError:
+                    pass
+        self.suspended = False
+        self.resume_ms = round((time.monotonic() - began) * 1000)
+        self.last_activity = time.monotonic()
+        self.telemetry("active")
+
+    def standby_child(self):
+        self.capture_owned()
+        snapshot = process_snapshot()
+        if not self.child or self.child.pid not in self.owned:
+            self.telemetry("pinned")
+            return
+        # Only verified descendants, never an externally connected shared browser.
+        live = [pid for pid, identity in self.owned.items()
+                if pid in snapshot and snapshot[pid][1] == identity]
+        if self.child.pid not in live:
+            self.telemetry("pinned")
+            return
+        stopped = []
+        try:
+            for pid in sorted(live, key=lambda p: p == self.child.pid):
+                if process_identity(pid) != self.owned[pid]:
+                    raise ProcessLookupError("owned process identity changed")
+                os.kill(pid, signal.SIGSTOP)
+                stopped.append(pid)
+        except OSError:
+            for pid in stopped:
+                current = process_snapshot()
+                if pid in current and current[pid][1] == self.owned[pid]:
+                    try:
+                        os.kill(pid, signal.SIGCONT)
+                    except ProcessLookupError:
+                        pass
+            self.telemetry("pinned")
+            return
+        self.suspended = True
+        self.telemetry("standby")
+
+    def stop_child(self):
+        if self.child is None:
+            return
+        child = self.child
+        self.resume_child()
+        self.capture_owned()  # Photograph descendants BEFORE first signal.
+        for sig, grace in [(signal.SIGTERM, .25), (signal.SIGKILL, .15)]:
+            snapshot = process_snapshot()
+            live = [p for p, identity in self.owned.items()
+                    if p in snapshot and snapshot[p][1] == identity]
+            # Root last; descendants may use different process groups.
+            for pid in sorted(live, key=lambda p: p == child.pid):
+                try:
+                    if process_identity(pid) == self.owned[pid]:
+                        os.kill(pid, sig)
+                except ProcessLookupError:
+                    pass
+            deadline = time.monotonic() + grace
+            while time.monotonic() < deadline:
+                if child.poll() is not None and not live:
+                    break
+                time.sleep(.01)
+                snapshot = process_snapshot()
+                live = [p for p, identity in self.owned.items()
+                        if p in snapshot and snapshot[p][1] == identity]
+                if not live:
+                    break
+        try:
+            self.sel.unregister(child.stdout)
+        except (KeyError, ValueError):
+            pass
+        if "child" in self.write_fds:
+            try:
+                self.sel.unregister(self.write_fds.pop("child"))
+            except KeyError:
+                pass
+        self.outputs["child"].clear()
+        for stream in (child.stdin, child.stdout):
+            if stream:
+                stream.close()
+        try:
+            child.wait(timeout=.2)
+        except subprocess.TimeoutExpired:
+            pass
+        self.child = None
+        self.owned = {}
+        self.ready = False
+        self.handshake_id = None
+        self.cold_id = None
+        self.buffers["child"].clear()
+        self.dropping["child"] = False
+
+    def start_child(self, cold_request=None):
+        if self.session_lost:
+            return False
+        self.started = time.monotonic()
+        try:
+            self.child = subprocess.Popen(self.command, stdin=subprocess.PIPE,
+                                          stdout=subprocess.PIPE,
+                                          stderr=subprocess.DEVNULL,
+                                          start_new_session=True, bufsize=0)
+        except OSError:
+            self.child = None
+            return False
+        os.set_blocking(self.child.stdin.fileno(), False)
+        self.write_fds["child"] = self.child.stdin.fileno()
+        self.sel.register(self.child.stdout, selectors.EVENT_READ, "child")
+        self.capture_owned()
+        self.ready = False
+        self.last_activity = self.started
+        self.telemetry("starting")
+        if cold_request is not None:
+            self.cold_id = id_key(cold_request["id"])
+            self.pending[self.cold_id] = cold_request
+            self.child_send(cold_request)
+            return True  # A send failure already emitted the pending request error.
+        self.handshake_id = "__crow_uny_initialize_" + uuid.uuid4().hex
+        return self.child_send({"jsonrpc": "2.0", "id": self.handshake_id,
+                                "method": "initialize", "params": self.init_params})
+
+    def fail_pending(self, text):
+        requests = list(self.pending.values()) + [m for m in self.queue if "id" in m and "method" in m]
+        self.pending.clear()
+        self.queue.clear()
+        seen = set()
+        for message in requests:
+            key = id_key(message["id"])
+            if key not in seen:
+                self.error(message["id"], -32001, text)
+                seen.add(key)
+        for key in list(self.server_pending):
+            ident = key[1]
+            self.send({"jsonrpc": "2.0", "method": "notifications/cancelled",
+                       "params": {"requestId": ident, "reason": "MCP server disconnected"}})
+        self.server_pending.clear()
+
+    def crashed(self, text="MCP server disconnected; request was not retried"):
+        self.fail_pending(text)
+        if self.pinned or self.subscriptions:
+            self.session_lost = True
+        self.subscriptions.clear()
+        self.stop_child()
+        self.telemetry("session_lost" if self.session_lost else "hibernated")
+
+    def forward_request(self, message):
+        if "method" not in message:  # Host response to a server-originated request.
+            self.server_pending.discard(id_key(message.get("id")))
+            self.child_send(message)
+            return
+        if "id" in message:
+            key = id_key(message["id"])
+            if key in self.pending:
+                self.error(message["id"], -32600, "Duplicate outstanding request id")
+                return
+            self.pending[key] = message
+            if message["method"] == "tools/call" and self.options.profile == "session":
+                self.pinned = True
+        self.last_activity = time.monotonic()
+        self.child_send(message)
+        self.telemetry("active")
+
+    def from_host(self, message):
+        method = message.get("method")
+        if method == "initialize" and "id" in message:
+            if self.init_request is not None:
+                self.error(message["id"], -32600, "Already initialized")
+                return
+            self.init_request = message
+            self.init_params = message.get("params", {})
+            self.cache_prepare(self.init_params)
+            if "initialize" in self.cache:
+                self.send({"jsonrpc": "2.0", "id": message["id"],
+                           "result": self.cache["initialize"]})
+                self.telemetry("hibernated")
+            elif not self.start_child(message):
+                if id_key(message["id"]) in self.pending:
+                    self.fail_pending("MCP server could not start")
+                else:
+                    self.error(message["id"], -32001, "MCP server could not start")
+            return
+        if method == "notifications/initialized":
+            self.initialized = True
+            if self.child and self.ready:
+                self.child_send(message)
+            return
+        if method == "ping" and "id" in message:
+            self.send({"jsonrpc": "2.0", "id": message["id"], "result": {}})
+            return
+        if method is None:
+            # A server can request ping/roots/etc DURING initialize. Its response
+            # must bypass the readiness queue or initialization deadlocks.
+            if self.child and id_key(message.get("id")) in self.server_pending:
+                self.forward_request(message)
+                self.telemetry("starting" if not self.ready else "active")
+            return
+        if self.init_request is None:
+            if "id" in message and method:
+                self.error(message["id"], -32002, "Initialize required")
+            return
+        if method == "tools/list" and "id" in message and (self.child is None or self.suspended):
+            result = self.cache["tools"].get(canonical(message.get("params", {})))
+            if result is not None:
+                self.send({"jsonrpc": "2.0", "id": message["id"], "result": result})
+                return
+        if self.session_lost:
+            if "id" in message and method:
+                self.error(message["id"], -32003, "MCP session state was lost; reconnect required")
+            return
+        # A cancellation/host response while hibernating cannot have an active peer.
+        if self.child is None and (method == "notifications/cancelled" or method is None):
+            return
+        if self.child is None and not self.start_child():
+            if "id" in message and method:
+                self.error(message["id"], -32001, "MCP server could not start")
+            return
+        self.resume_child()
+        if not self.ready:
+            self.queue.append(message)
+            return
+        self.forward_request(message)
+
+    def from_child(self, message):
+        self.last_activity = time.monotonic()
+        if "method" in message:
+            if "id" in message:
+                self.server_pending.add(id_key(message["id"]))
+                self.telemetry("active")
+            if message["method"] == "notifications/tools/list_changed":
+                self.cache["tools"].clear()
+                self.cache_save()
+            self.send(message)
+            return
+        key = id_key(message.get("id"))
+        if self.handshake_id is not None and key == id_key(self.handshake_id):
+            self.handshake_id = None
+            if "result" not in message or not isinstance(message["result"], dict):
+                self.crashed("MCP reinitialization failed; request was not retried")
+                return
+            changed = self.cache.get("initialize") != message["result"]
+            self.cache["initialize"] = message["result"]
+            if changed:
+                self.cache["tools"].clear()
+            self.cache_save()
+            self.child_send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+            self.ready = True
+            self.startup_ms = round((time.monotonic() - self.started) * 1000)
+            if changed and self.initialized:
+                self.send({"jsonrpc": "2.0", "method": "notifications/tools/list_changed"})
+            queued, self.queue = self.queue, []
+            for request in queued:
+                if self.child is None:
+                    if "id" in request and "method" in request:
+                        self.error(request["id"], -32001, "MCP server disconnected; request was not retried")
+                else:
+                    self.forward_request(request)
+            self.telemetry("active")
+            return
+        request = self.pending.pop(key, None)
+        if request is None:
+            return  # Late/unknown responses must not collide with an internal handshake.
+        if key == self.cold_id:
+            self.cold_id = None
+            if "result" in message and isinstance(message["result"], dict):
+                self.cache["initialize"] = message["result"]
+                self.cache_save()
+                self.ready = True
+                self.startup_ms = round((time.monotonic() - self.started) * 1000)
+            else:
+                self.send(message)
+                self.crashed("MCP initialization failed")
+                return
+        if "result" in message:
+            method = request["method"]
+            params = request.get("params", {})
+            if method == "tools/list":
+                self.cache["tools"][canonical(params)] = message["result"]
+                self.cache_save()
+            if method == "resources/subscribe" and isinstance(params, dict):
+                self.subscriptions.add(canonical(params.get("uri")))
+            if method == "resources/unsubscribe" and isinstance(params, dict):
+                self.subscriptions.discard(canonical(params.get("uri")))
+        self.send(message)
+        if self.ready and self.queue:
+            queued, self.queue = self.queue, []
+            for request in queued:
+                self.forward_request(request)
+        self.telemetry("active")
+
+    def consume(self, source, data):
+        buffer = self.buffers[source]
+        for fragment in data.splitlines(keepends=True):
+            complete = fragment.endswith(b"\n")
+            if self.dropping[source]:
+                if complete:
+                    self.dropping[source] = False
+                continue
+            buffer.extend(fragment)
+            if len(buffer) > MAX_LINE:
+                buffer.clear()
+                self.dropping[source] = not complete
+                if source == "child":
+                    self.crashed("MCP server sent an oversized message")
+                    return
+                self.error(None, -32700, "Message too large")
+                continue
+            if not complete:
+                continue
+            raw = bytes(buffer)
+            buffer.clear()
+            try:
+                message = json.loads(raw)
+            except (ValueError, UnicodeError):
+                if source == "child":
+                    self.crashed("MCP server sent invalid JSON")
+                    return
+                self.error(None, -32700, "Invalid JSON")
+                continue
+            if not valid_message(message):
+                if source == "child":
+                    self.crashed("MCP server sent an invalid message")
+                    return
+                self.error(None, -32600, "Invalid JSON-RPC message")
+                continue
+            if source == "host":
+                self.from_host(message)
+            else:
+                self.from_child(message)
+                if self.child is None:
+                    return
+
+    def run(self):
+        previous = {}
+        def stop(signum, frame):
+            self.stopping = True
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            previous[sig] = signal.signal(sig, stop)
+        try:
+            while not self.stopping:
+                for key, _ in self.sel.select(.04):
+                    source = key.data
+                    if source.endswith("_write"):
+                        self.flush_output(source[:-6])
+                        continue
+                    if source == "child" and (self.child is None or self.child.stdout.fileno() != key.fd):
+                        continue
+                    try:
+                        data = os.read(key.fd, 65536)
+                    except OSError:
+                        data = b""
+                    if not data:
+                        if source == "host":
+                            self.stopping = True
+                            break
+                        self.crashed()
+                    else:
+                        self.consume(source, data)
+                now = time.monotonic()
+                if self.child:
+                    if now - self.last_snapshot > .2:
+                        self.capture_owned()
+                    if self.child.poll() is not None:
+                        self.crashed()
+                    elif not self.ready and now - self.started > self.options.startup_timeout:
+                        self.crashed("MCP startup timed out; request was not retried")
+                    elif (self.ready and not self.pending and not self.server_pending
+                          and not self.queue and not self.outputs["child"]
+                          and not self.subscriptions and not self.suspended
+                          and now - self.last_activity >= self.options.idle_seconds):
+                        if self.pinned:
+                            self.standby_child()
+                        else:
+                            self.stop_child()
+                            self.telemetry("hibernated")
+                if now - self.last_telemetry > .5:
+                    self.telemetry()
+        except (BrokenPipeError, KeyboardInterrupt):
+            pass
+        finally:
+            self.stop_child()
+            self.telemetry("stopped")
+            self.sel.close()
+            self.store.close()
+            for sig, handler in previous.items():
+                signal.signal(sig, handler)
+        return 2 if self.transport_failed else 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="action", required=True)
+    serve = sub.add_parser("serve")
+    serve.add_argument("--name", required=True)
+    serve.add_argument("--idle-seconds", type=float, default=120)
+    serve.add_argument("--startup-timeout", type=float, default=30)
+    serve.add_argument("--state-dir", default=str(Path.home() / ".local/state/crow-uny-mcp"))
+    serve.add_argument("--profile", choices=["restartable", "session"], default="session")
+    serve.add_argument("command", nargs=argparse.REMAINDER)
+    options = parser.parse_args(argv)
+    command = options.command
+    if command and command[0] == "--":
+        command = command[1:]
+    if not command or options.idle_seconds <= 0 or options.startup_timeout <= 0:
+        parser.error("command and positive timeouts are required")
+    if os.name != "posix" or not (sys.platform == "darwin" or sys.platform.startswith("linux")):
+        parser.error("this runtime currently requires macOS or Linux kernel process identities")
+    try:
+        return Proxy(options, command).run()
+    except (OSError, ValueError):
+        print("crow-uny-mcp: runtime setup or transport failure", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())