msdev 0.9.0__py3-none-any.whl

msdev/daemon.py

@@ -0,0 +1,1322 @@
+"""User-level msdev daemon and Unix-socket JSON RPC."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import platform
+import select
+import shlex
+import shutil
+import signal
+import socket
+import socketserver
+import subprocess
+import sys
+import threading
+import time
+import traceback
+from pathlib import Path
+from typing import Any, Callable
+
+from . import __version__
+from .core.config import (
+    wrap_conda_activation_command,
+    data_home,
+    default_socket_path,
+    parse_environment_spec,
+    wrap_conda_command,
+)
+from .core.inventory import Inventory
+from .core.limits import (
+    DEFAULT_EXEC_TIMEOUT_SECONDS,
+    MAX_JSON_RPC_REQUEST_BYTES,
+    MAX_RPC_ERROR_BYTES,
+    MAX_RPC_RESPONSE_BYTES,
+    validate_exec_timeout_seconds,
+)
+from .core.resources import parse_variable_assignment
+from .core.workspace.access import (
+    atomic_write,
+    delete_file,
+    glob_paths,
+    list_directory,
+    read_file,
+    resolve_path,
+    search,
+    stat_path,
+    workspace_root,
+)
+
+
+MAX_REQUEST_BYTES = MAX_JSON_RPC_REQUEST_BYTES
+MAX_EXEC_OUTPUT_BYTES = 4 * 1024 * 1024
+EXEC_PIPE_DRAIN_GRACE_SECONDS = 0.25
+_EXEC_READ_CHUNK_BYTES = 64 * 1024
+_EXEC_FORCE_CLEANUP_SECONDS = 0.25
+_EXEC_THREAD_JOIN_SECONDS = 0.05
+
+
+def _bounded_utf8(value: Any, maximum: int) -> str:
+    text = str(value)
+    retained = bytearray()
+    for offset in range(0, len(text), 4096):
+        chunk = text[offset : offset + 4096].encode(
+            "utf-8",
+            errors="replace",
+        )
+        remaining = maximum - len(retained)
+        if remaining <= 0:
+            break
+        retained.extend(chunk[:remaining])
+    return bytes(retained).decode("utf-8", errors="ignore")
+
+
+def _encode_json_response(value: Any, maximum: int) -> bytes | None:
+    retained = bytearray()
+    encoder = json.JSONEncoder(ensure_ascii=False)
+    for fragment in encoder.iterencode(value):
+        encoded = fragment.encode("utf-8")
+        if len(retained) + len(encoded) + 1 > maximum:
+            return None
+        retained.extend(encoded)
+    retained.extend(b"\n")
+    return bytes(retained)
+
+
+def _write_proxy_error(error_type: str, message: Any) -> None:
+    value = {
+        "id": None,
+        "error": {
+            "type": _bounded_utf8(error_type, 128),
+            "message": _bounded_utf8(message, MAX_RPC_ERROR_BYTES),
+        },
+    }
+    raw = _encode_json_response(value, MAX_RPC_RESPONSE_BYTES)
+    if raw is not None:
+        sys.stdout.buffer.write(raw)
+        sys.stdout.buffer.flush()
+
+
+def _drain_exec_stream(
+    stream: Any,
+    retained: bytearray,
+    truncated: list[bool],
+    lock: threading.Lock,
+    done: threading.Event,
+    stream_name: str,
+    output_callback: Callable[[str, bytes], None] | None,
+    retain_output: bool,
+) -> None:
+    try:
+        while True:
+            try:
+                chunk = os.read(stream.fileno(), _EXEC_READ_CHUNK_BYTES)
+            except (OSError, ValueError):
+                return
+            if not chunk:
+                return
+            if output_callback is not None:
+                output_callback(stream_name, chunk)
+            if retain_output:
+                with lock:
+                    remaining = MAX_EXEC_OUTPUT_BYTES - len(retained)
+                    if remaining > 0:
+                        retained.extend(chunk[:remaining])
+                    if len(chunk) > remaining:
+                        truncated[0] = True
+    finally:
+        try:
+            stream.close()
+        except (OSError, ValueError):
+            pass
+        done.set()
+
+
+def _kill_exec_process_group(process: subprocess.Popen[bytes]) -> None:
+    """Kill only the isolated child group, never the daemon's process group."""
+    group_killed = False
+    if os.name == "posix" and hasattr(os, "killpg"):
+        child_group = process.pid
+        if child_group != os.getpgrp():
+            try:
+                os.killpg(child_group, signal.SIGKILL)
+                group_killed = True
+            except (ProcessLookupError, PermissionError):
+                pass
+    if not group_killed and process.poll() is None:
+        process.kill()
+
+
+def _wait_for_exec_drainers(
+    done: list[threading.Event],
+    deadline: float,
+) -> bool:
+    for event in done:
+        if event.is_set():
+            continue
+        remaining = deadline - time.monotonic()
+        if remaining <= 0 or not event.wait(remaining):
+            return False
+    return True
+
+
+def _close_exec_pipes(process: subprocess.Popen[bytes]) -> None:
+    for stream in (process.stdout, process.stderr):
+        if stream is None:
+            continue
+        try:
+            os.close(stream.fileno())
+        except (OSError, ValueError):
+            pass
+
+
+def _reap_exec_process(
+    process: subprocess.Popen[bytes],
+    deadline: float,
+) -> None:
+    remaining = max(0.0, deadline - time.monotonic())
+    try:
+        process.wait(timeout=remaining)
+    except subprocess.TimeoutExpired:
+        if process.poll() is None:
+            process.kill()
+        remaining = max(0.0, deadline - time.monotonic())
+        try:
+            process.wait(timeout=remaining)
+        except subprocess.TimeoutExpired:
+            pass
+
+
+def _execute_bounded(
+    command: list[str],
+    *,
+    cwd: str | None,
+    env: dict[str, str],
+    timeout: float | None,
+    cancellation_requested: Callable[[], bool] | None = None,
+    output_callback: Callable[[str, bytes], None] | None = None,
+    retain_output: bool = True,
+) -> tuple[int, str, str, bool, bool, bool, bool, bool]:
+    """Execute while retaining bounded output.
+
+    ``timeout=None`` intentionally permits long-running same-user commands.
+    Once the direct child exits, inherited output pipes receive only a bounded
+    drain grace so detached descendants cannot hold the RPC open forever.
+    """
+    started = time.monotonic()
+    deadline = started + timeout if timeout is not None else None
+    process = subprocess.Popen(
+        command,
+        cwd=cwd,
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        start_new_session=(os.name == "posix"),
+    )
+    assert process.stdout is not None
+    assert process.stderr is not None
+    stdout = bytearray()
+    stderr = bytearray()
+    stdout_truncated = [False]
+    stderr_truncated = [False]
+    stdout_lock = threading.Lock()
+    stderr_lock = threading.Lock()
+    drain_done = [threading.Event(), threading.Event()]
+    drainers = [
+        threading.Thread(
+            target=_drain_exec_stream,
+            args=(
+                process.stdout,
+                stdout,
+                stdout_truncated,
+                stdout_lock,
+                drain_done[0],
+                "stdout",
+                output_callback,
+                retain_output,
+            ),
+            daemon=True,
+        ),
+        threading.Thread(
+            target=_drain_exec_stream,
+            args=(
+                process.stderr,
+                stderr,
+                stderr_truncated,
+                stderr_lock,
+                drain_done[1],
+                "stderr",
+                output_callback,
+                retain_output,
+            ),
+            daemon=True,
+        ),
+    ]
+    for drainer in drainers:
+        drainer.start()
+    timed_out = False
+    cancelled = False
+    output_drain_truncated = False
+    cleanup_deadline: float | None = None
+    try:
+        while True:
+            if (
+                cancellation_requested is not None
+                and cancellation_requested()
+            ):
+                cancelled = True
+                cleanup_deadline = (
+                    time.monotonic() + _EXEC_FORCE_CLEANUP_SECONDS
+                )
+                _kill_exec_process_group(process)
+                _reap_exec_process(process, cleanup_deadline)
+                returncode = 130
+                break
+            remaining = (
+                None
+                if deadline is None
+                else deadline - time.monotonic()
+            )
+            if remaining is not None and remaining <= 0:
+                timed_out = True
+                cleanup_deadline = (
+                    time.monotonic() + _EXEC_FORCE_CLEANUP_SECONDS
+                )
+                _kill_exec_process_group(process)
+                _reap_exec_process(process, cleanup_deadline)
+                returncode = 124
+                break
+            wait_timeout = remaining
+            if cancellation_requested is not None:
+                wait_timeout = (
+                    0.1
+                    if remaining is None
+                    else min(0.1, remaining)
+                )
+            try:
+                returncode = process.wait(timeout=wait_timeout)
+                break
+            except subprocess.TimeoutExpired:
+                if cancellation_requested is not None:
+                    continue
+                timed_out = True
+                cleanup_deadline = (
+                    time.monotonic() + _EXEC_FORCE_CLEANUP_SECONDS
+                )
+                _kill_exec_process_group(process)
+                _reap_exec_process(process, cleanup_deadline)
+                returncode = 124
+                break
+
+        drain_deadline = time.monotonic() + EXEC_PIPE_DRAIN_GRACE_SECONDS
+        if deadline is not None:
+            drain_deadline = min(drain_deadline, deadline)
+        drained = all(event.is_set() for event in drain_done)
+        if not drained and drain_deadline > time.monotonic():
+            drained = _wait_for_exec_drainers(drain_done, drain_deadline)
+        if not drained:
+            output_drain_truncated = True
+            if deadline is not None and time.monotonic() >= deadline:
+                timed_out = True
+                returncode = 124
+            cleanup_deadline = cleanup_deadline or (
+                time.monotonic() + _EXEC_FORCE_CLEANUP_SECONDS
+            )
+            _kill_exec_process_group(process)
+            _reap_exec_process(process, cleanup_deadline)
+            _close_exec_pipes(process)
+            _wait_for_exec_drainers(
+                drain_done,
+                cleanup_deadline,
+            )
+    except BaseException:
+        cleanup_deadline = cleanup_deadline or (
+            time.monotonic() + _EXEC_FORCE_CLEANUP_SECONDS
+        )
+        _kill_exec_process_group(process)
+        _reap_exec_process(process, cleanup_deadline)
+        _close_exec_pipes(process)
+        raise
+    finally:
+        join_deadline = cleanup_deadline or (
+            time.monotonic() + _EXEC_THREAD_JOIN_SECONDS
+        )
+        for drainer in drainers:
+            drainer.join(max(0.0, join_deadline - time.monotonic()))
+
+    with stdout_lock:
+        stdout_value = bytes(stdout).decode("utf-8", errors="replace")
+        stdout_was_truncated = stdout_truncated[0]
+    with stderr_lock:
+        stderr_value = bytes(stderr).decode("utf-8", errors="replace")
+        stderr_was_truncated = stderr_truncated[0]
+    return (
+        returncode,
+        stdout_value,
+        stderr_value,
+        stdout_was_truncated,
+        stderr_was_truncated,
+        timed_out,
+        cancelled,
+        output_drain_truncated,
+    )
+
+
+class RpcDispatcher:
+    def __init__(self, inventory: Inventory):
+        self.inventory = inventory
+        self._activation_cache: dict[
+            tuple[
+                str,
+                str | None,
+                tuple[tuple[str, str], ...],
+                tuple[tuple[str, str], ...],
+            ],
+            tuple[tuple[tuple[str, int | None, int | None], ...] | None, dict[str, str]],
+        ] = {}
+        self._activation_cache_lock = threading.Lock()
+
+    def dispatch(
+        self,
+        method: str,
+        params: dict[str, Any],
+        cancellation_requested: Callable[[], bool] | None = None,
+    ) -> Any:
+        if method == "exec":
+            return self.exec_command(params, cancellation_requested)
+        if method == "workspace.git_status":
+            return self.workspace_git_status(params, cancellation_requested)
+        if method == "workspace.git_diff":
+            return self.workspace_git_diff(params, cancellation_requested)
+        handlers = {
+            "ping": self.ping,
+            "node.info": self.node_info,
+            "npu.list": self.npu_list,
+            "model.register": self.model_register,
+            "model.discover": self.model_discover,
+            "model.list": self.model_list,
+            "model.inspect": self.model_inspect,
+            "model.update": self.model_update,
+            "model.delete": self.model_delete,
+            "model.restore": self.model_restore,
+            "model.refresh": self.model_refresh,
+            "model.validate": self.model_validate,
+            "model.audit": self.model_audit,
+            "model.verify": self.model_verify,
+            "model.unregister": self.model_unregister,
+            "replica.list": self.replica_list,
+            "replica.add": self.replica_add,
+            "replica.remove": self.replica_remove,
+            "model.export": self.model_export,
+            "model.import": self.model_import,
+            "model.rebind": self.model_rebind,
+            "exec": self.exec_command,
+            "workspace.stat": self.workspace_stat,
+            "workspace.read": self.workspace_read,
+            "workspace.list": self.workspace_list,
+            "workspace.glob": self.workspace_glob,
+            "workspace.search": self.workspace_search,
+            "workspace.write": self.workspace_write,
+            "workspace.delete": self.workspace_delete,
+        }
+        handler = handlers.get(method)
+        if handler is None:
+            raise KeyError(f"unknown RPC method: {method}")
+        return handler(params)
+
+    def ping(self, _params: dict[str, Any]) -> dict[str, Any]:
+        return {"ok": True, "version": __version__, "node_id": self.inventory.node_id}
+
+    @staticmethod
+    def _runtime(params: dict[str, Any]) -> dict[str, str]:
+        runtime = params.get("_runtime") or {"type": "host"}
+        if not isinstance(runtime, dict):
+            raise ValueError("runtime must be an object")
+        runtime_type = str(runtime.get("type", "host"))
+        if runtime_type == "host":
+            return {"type": "host"}
+        if runtime_type != "docker":
+            raise ValueError(f"unsupported runtime: {runtime_type}")
+        container = runtime.get("container")
+        if not isinstance(container, str) or not container:
+            raise ValueError("docker runtime requires a container name")
+        return {"type": "docker", "container": container}
+
+    @staticmethod
+    def _environments(params: dict[str, Any]) -> list[tuple[str, str]]:
+        values = params.get("_environments") or []
+        if not isinstance(values, list) or not all(isinstance(item, str) for item in values):
+            raise ValueError("environments must be a string array")
+        return [parse_environment_spec(item) for item in values]
+
+    @staticmethod
+    def _node_environment(params: dict[str, Any]) -> dict[str, str]:
+        values = params.get("_node_env") or {}
+        if not isinstance(values, dict):
+            raise ValueError("node environment must be an object")
+        environment: dict[str, str] = {}
+        for key, value in values.items():
+            if not isinstance(key, str) or not isinstance(value, str):
+                raise ValueError(
+                    "node environment names and values must be strings"
+                )
+            parsed_key, parsed_value = parse_variable_assignment(
+                f"{key}={value}"
+            )
+            environment[parsed_key] = parsed_value
+        return environment
+
+    @staticmethod
+    def _wrap_environment_command(
+        command: list[str],
+        environments: list[tuple[str, str]],
+    ) -> list[str]:
+        """Wrap an argv from the innermost environment to the outermost."""
+        wrapped = list(command)
+        for kind, value in reversed(environments):
+            if kind == "uv":
+                wrapped = ["uv", "run", "--project", value, "--", *wrapped]
+            elif kind == "venv":
+                activate = f"{value.rstrip('/')}/bin/activate"
+                script = f". {shlex.quote(activate)} && exec \"$@\""
+                wrapped = ["sh", "-c", script, "msdev-venv", *wrapped]
+            elif kind == "conda":
+                wrapped = wrap_conda_command(wrapped, value)
+        return wrapped
+
+    @staticmethod
+    def _wrap_activation_probe(
+        command: list[str],
+        environments: list[tuple[str, str]],
+    ) -> list[str]:
+        wrapped = list(command)
+        for kind, value in reversed(environments):
+            if kind == "uv":
+                wrapped = ["uv", "run", "--project", value, "--", *wrapped]
+            elif kind == "venv":
+                activate = f"{value.rstrip('/')}/bin/activate"
+                script = f". {shlex.quote(activate)} && exec \"$@\""
+                wrapped = ["sh", "-c", script, "msdev-venv", *wrapped]
+            elif kind == "conda":
+                wrapped = wrap_conda_activation_command(wrapped, value)
+        return wrapped
+
+    @staticmethod
+    def _activation_fingerprint(
+        runtime: dict[str, str],
+        environments: list[tuple[str, str]],
+        activated: dict[str, str],
+    ) -> tuple[tuple[str, int | None, int | None], ...] | None:
+        if runtime["type"] != "host":
+            return None
+        watched: set[Path] = set()
+        for kind, value in environments:
+            if kind == "conda":
+                prefix = (
+                    value
+                    if "/" in value
+                    else activated.get("CONDA_PREFIX", "")
+                )
+                if prefix:
+                    root = Path(prefix).expanduser()
+                    watched.add(root / "conda-meta" / "history")
+                    hooks = root / "etc" / "conda" / "activate.d"
+                    watched.add(hooks)
+                    if hooks.is_dir():
+                        watched.update(hooks.iterdir())
+            elif kind == "venv":
+                root = Path(value).expanduser()
+                watched.add(root / "pyvenv.cfg")
+                watched.add(root / "bin" / "activate")
+            elif kind == "uv":
+                root = Path(value).expanduser()
+                watched.add(root / "pyproject.toml")
+                watched.add(root / "uv.lock")
+                watched.add(root / ".venv" / "pyvenv.cfg")
+        fingerprint: list[tuple[str, int | None, int | None]] = []
+        for path in sorted(watched, key=str):
+            try:
+                stat = path.stat()
+                fingerprint.append((str(path), stat.st_mtime_ns, stat.st_size))
+            except FileNotFoundError:
+                fingerprint.append((str(path), None, None))
+        return tuple(fingerprint)
+
+    def _load_activation_environment(
+        self,
+        runtime: dict[str, str],
+        environments: list[tuple[str, str]],
+        base_environment: dict[str, str],
+    ) -> dict[str, str]:
+        command = self._wrap_activation_probe(["env", "-0"], environments)
+        if runtime["type"] == "docker":
+            command = ["docker", "exec", runtime["container"], *command]
+        probe_environment = os.environ.copy()
+        probe_environment.update(base_environment)
+        (
+            returncode,
+            stdout,
+            stderr,
+            stdout_truncated,
+            stderr_truncated,
+            timed_out,
+            _cancelled,
+            output_drain_truncated,
+        ) = _execute_bounded(
+            command,
+            cwd=None,
+            env=probe_environment,
+            timeout=30.0,
+        )
+        if (
+            returncode != 0
+            or timed_out
+            or stdout_truncated
+            or stderr_truncated
+            or output_drain_truncated
+        ):
+            detail = stderr.strip() or f"exit code {returncode}"
+            raise RuntimeError(
+                f"failed to activate execution environment: {detail}"
+            )
+        activated: dict[str, str] = {}
+        for item in stdout.split("\0"):
+            key, separator, value = item.partition("=")
+            if separator and key and "\0" not in key:
+                activated[key] = value
+        for transient in ("_", "PWD", "OLDPWD", "SHLVL"):
+            activated.pop(transient, None)
+        if "PATH" not in activated:
+            raise RuntimeError("activated environment did not provide PATH")
+        return activated
+
+    def _activation_environment(
+        self,
+        runtime: dict[str, str],
+        environments: list[tuple[str, str]],
+        base_environment: dict[str, str] | None = None,
+    ) -> dict[str, str]:
+        if not environments:
+            return {}
+        base_environment = dict(base_environment or {})
+        key = (
+            runtime["type"],
+            runtime.get("container"),
+            tuple(environments),
+            tuple(sorted(base_environment.items())),
+        )
+        with self._activation_cache_lock:
+            cached = self._activation_cache.get(key)
+            if cached is not None:
+                fingerprint, activated = cached
+                current = self._activation_fingerprint(
+                    runtime,
+                    environments,
+                    activated,
+                )
+                if current == fingerprint:
+                    return dict(activated)
+            activated = self._load_activation_environment(
+                runtime,
+                environments,
+                base_environment,
+            )
+            fingerprint = self._activation_fingerprint(
+                runtime,
+                environments,
+                activated,
+            )
+            self._activation_cache[key] = (fingerprint, dict(activated))
+            return activated
+
+    @staticmethod
+    def _docker_info(container: str) -> dict[str, Any]:
+        try:
+            completed = subprocess.run(
+                ["docker", "inspect", container],
+                capture_output=True,
+                text=True,
+                timeout=20,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise RuntimeError("docker command not found on node host") from exc
+        if completed.returncode != 0:
+            raise RuntimeError(
+                completed.stderr.strip() or f"docker container not found: {container}"
+            )
+        values = json.loads(completed.stdout)
+        if not values:
+            raise RuntimeError(f"docker inspect returned no data for {container}")
+        value = values[0]
+        state = value.get("State") or {}
+        return {
+            "type": "docker",
+            "container": container,
+            "id": str(value.get("Id", ""))[:12],
+            "image": (value.get("Config") or {}).get("Image"),
+            "status": state.get("Status"),
+            "running": bool(state.get("Running")),
+            "pid": state.get("Pid"),
+        }
+
+    def node_info(self, params: dict[str, Any]) -> dict[str, Any]:
+        usage = shutil.disk_usage(self.inventory.data_dir)
+        value = {
+            "node_id": self.inventory.node_id,
+            "hostname": platform.node(),
+            "architecture": platform.machine(),
+            "platform": platform.platform(),
+            "python": platform.python_version(),
+            "daemon_version": __version__,
+            "uid": os.getuid(),
+            "data_dir": str(self.inventory.data_dir),
+            "disk": {
+                "total": usage.total,
+                "used": usage.used,
+                "free": usage.free,
+            },
+        }
+        runtime = self._runtime(params)
+        environments = self._environments(params)
+        value["runtime"] = (
+            self._docker_info(runtime["container"])
+            if runtime["type"] == "docker"
+            else runtime
+        )
+        value["environments"] = [
+            {"type": kind, "value": item}
+            for kind, item in environments
+        ]
+        return value
+
+    def npu_list(self, params: dict[str, Any]) -> dict[str, Any]:
+        runtime = self._runtime(params)
+        environments = self._environments(params)
+        node_environment = self._node_environment(params)
+        command = self._wrap_environment_command(
+            ["npu-smi", "info"],
+            environments,
+        )
+        if runtime["type"] == "docker":
+            command = ["docker", "exec", runtime["container"], *command]
+        run_environment = os.environ.copy()
+        if runtime["type"] == "host":
+            run_environment.update(node_environment)
+        try:
+            completed = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                timeout=20,
+                check=False,
+                env=run_environment,
+            )
+        except FileNotFoundError:
+            return {
+                "available": False,
+                "reason": f"{command[0]} not found",
+                "output": "",
+                "runtime": runtime,
+                "environments": environments,
+            }
+        except subprocess.TimeoutExpired:
+            return {
+                "available": False,
+                "reason": "npu-smi timed out",
+                "output": "",
+                "runtime": runtime,
+                "environments": environments,
+            }
+        output = (completed.stdout or "") + (completed.stderr or "")
+        return {
+            "available": completed.returncode == 0,
+            "returncode": completed.returncode,
+            "output": output,
+            "runtime": runtime,
+            "environments": environments,
+        }
+
+    def model_register(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.register_model(
+            ref=str(params["ref"]),
+            path=str(params["path"]),
+            scope=str(params.get("scope", "user")),
+            format_name=params.get("format"),
+            full_checksum=bool(params.get("full_checksum", False)),
+        )
+
+    def model_discover(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.discover_models(
+            root=str(params["root"]),
+            max_depth=int(params.get("max_depth", 5)),
+            register=bool(params.get("register", False)),
+            namespace=str(params.get("namespace", "discovered")),
+        )
+
+    def model_list(self, params: dict[str, Any]) -> list[dict[str, Any]]:
+        return self.inventory.list_models(
+            format_name=params.get("format"),
+            model_type=params.get("model_type"),
+            state=params.get("state"),
+            tag=params.get("tag"),
+            name=params.get("name"),
+            include_deleted=bool(params.get("include_deleted", False)),
+        )
+
+    def model_inspect(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.inspect_model(str(params["ref"]))
+
+    def model_update(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.update_model(
+            str(params["ref"]),
+            add_aliases=params.get("add_aliases") or [],
+            remove_aliases=params.get("remove_aliases") or [],
+            add_tags=params.get("add_tags") or [],
+            remove_tags=params.get("remove_tags") or [],
+            description=params.get("description"),
+            clear_description=bool(params.get("clear_description", False)),
+        )
+
+    def model_delete(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.delete_model(str(params["ref"]))
+
+    def model_restore(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.restore_model(str(params["ref"]))
+
+    def model_refresh(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.refresh_model(
+            str(params["ref"]),
+            path=params.get("path"),
+            full_checksum=bool(params.get("full_checksum", False)),
+        )
+
+    def model_validate(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.validate_model(
+            str(params["ref"]),
+            path=params.get("path"),
+        )
+
+    def model_audit(self, params: dict[str, Any]) -> list[dict[str, Any]]:
+        return self.inventory.audit_records(
+            ref=params.get("ref"),
+            limit=int(params.get("limit", 100)),
+        )
+
+    def model_verify(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.verify_model(
+            str(params["ref"]),
+            full_checksum=bool(params.get("full_checksum", False)),
+        )
+
+    def model_unregister(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.unregister_model(
+            str(params["ref"]),
+            path=params.get("path"),
+        )
+
+    def replica_list(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.list_replicas(str(params["ref"]))
+
+    def replica_add(self, params: dict[str, Any]) -> dict[str, Any]:
+        model = self.inventory.inspect_model(str(params["ref"]))
+        return self.inventory.register_model(
+            ref=model["ref"],
+            path=str(params["path"]),
+            format_name=model.get("format"),
+            full_checksum=bool(params.get("full_checksum", False)),
+        )
+
+    def replica_remove(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.remove_replica(
+            str(params["ref"]),
+            str(params["path"]),
+        )
+
+    def model_export(self, _params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.export_records()
+
+    def model_import(self, params: dict[str, Any]) -> dict[str, Any]:
+        root_maps = [tuple(item) for item in params.get("root_maps", [])]
+        return self.inventory.import_records(params["payload"], root_maps=root_maps)
+
+    def model_rebind(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self.inventory.register_model(
+            ref=str(params["ref"]),
+            path=str(params["path"]),
+            scope=str(params.get("scope", "user")),
+            full_checksum=bool(params.get("full_checksum", False)),
+        )
+
+    def workspace_stat(self, params: dict[str, Any]) -> dict[str, Any]:
+        return stat_path(params.get("root"), params.get("path", "."))
+
+    def workspace_read(self, params: dict[str, Any]) -> dict[str, Any]:
+        return read_file(
+            params.get("root"),
+            params.get("path"),
+            params.get("max_bytes", 1024 * 1024),
+        )
+
+    def workspace_list(self, params: dict[str, Any]) -> dict[str, Any]:
+        return list_directory(params.get("root"), params.get("path", "."))
+
+    def workspace_glob(self, params: dict[str, Any]) -> dict[str, Any]:
+        return glob_paths(
+            params.get("root"),
+            params.get("pattern"),
+            params.get("max_results", 1000),
+        )
+
+    def workspace_search(self, params: dict[str, Any]) -> dict[str, Any]:
+        return search(
+            params.get("root"),
+            params.get("pattern"),
+            params.get("paths"),
+            params.get("glob"),
+            params.get("max_results", 1000),
+        )
+
+    def workspace_write(self, params: dict[str, Any]) -> dict[str, Any]:
+        return atomic_write(
+            params.get("root"),
+            params.get("path"),
+            params.get("content_base64"),
+            params.get("expected_sha256"),
+        )
+
+    def workspace_delete(self, params: dict[str, Any]) -> dict[str, Any]:
+        return delete_file(params.get("root"), params.get("path"))
+
+    def _workspace_git(
+        self,
+        params: dict[str, Any],
+        command: list[str],
+        cancellation_requested: Callable[[], bool] | None = None,
+    ) -> dict[str, Any]:
+        root = workspace_root(params.get("root"))
+        runtime = self._runtime(params)
+        execution_root = params.get("execution_root")
+        if not isinstance(execution_root, str) or not execution_root:
+            execution_root = str(root)
+        if runtime["type"] == "host":
+            candidate = Path(execution_root).expanduser()
+            if candidate.is_absolute():
+                execution_path = candidate.resolve(strict=True)
+                try:
+                    execution_path.relative_to(root)
+                except ValueError as exc:
+                    raise PermissionError(
+                        "host workspace execution root must stay under workspace root"
+                    ) from exc
+            else:
+                _, execution_path = resolve_path(str(root), execution_root)
+            if not execution_path.is_dir():
+                raise NotADirectoryError(
+                    f"workspace execution root is not a directory: {execution_path}"
+                )
+            execution_root = str(execution_path)
+        forwarded = dict(params)
+        forwarded["cwd"] = execution_root
+        forwarded["command"] = command
+        forwarded["env"] = {}
+        forwarded["timeout_seconds"] = min(
+            DEFAULT_EXEC_TIMEOUT_SECONDS,
+            60.0,
+        )
+        result = self.exec_command(forwarded, cancellation_requested)
+        result["workspace_root"] = str(root)
+        result["execution_root"] = execution_root
+        return result
+
+    def workspace_git_status(
+        self,
+        params: dict[str, Any],
+        cancellation_requested: Callable[[], bool] | None = None,
+    ) -> dict[str, Any]:
+        return self._workspace_git(
+            params,
+            ["git", "status", "--short", "--branch"],
+            cancellation_requested,
+        )
+
+    def workspace_git_diff(
+        self,
+        params: dict[str, Any],
+        cancellation_requested: Callable[[], bool] | None = None,
+    ) -> dict[str, Any]:
+        argv = params.get("argv") or []
+        if not isinstance(argv, list) or not all(
+            isinstance(item, str) for item in argv
+        ):
+            raise ValueError("workspace Git diff argv must be a string array")
+        return self._workspace_git(
+            params,
+            ["git", "diff", *argv],
+            cancellation_requested,
+        )
+
+    def exec_command(
+        self,
+        params: dict[str, Any],
+        cancellation_requested: Callable[[], bool] | None = None,
+        output_callback: Callable[[str, bytes], None] | None = None,
+        retain_output: bool = True,
+    ) -> dict[str, Any]:
+        command = params.get("command")
+        if not isinstance(command, list) or not command or not all(isinstance(x, str) for x in command):
+            raise ValueError("exec command must be a non-empty string array")
+        runtime = self._runtime(params)
+        environments = self._environments(params)
+        node_environment = self._node_environment(params)
+        cwd = params.get("cwd")
+        if cwd is not None and runtime["type"] == "host":
+            cwd = str(Path(str(cwd)).expanduser().resolve(strict=True))
+        additions = params.get("env") or {}
+        if not isinstance(additions, dict):
+            raise ValueError("exec env must be an object")
+        additions = {str(key): str(value) for key, value in additions.items()}
+        if "timeout" in params:
+            raise ValueError("timeout is unsupported; use timeout_seconds")
+        timeout_seconds = validate_exec_timeout_seconds(params.get(
+            "timeout_seconds",
+            DEFAULT_EXEC_TIMEOUT_SECONDS,
+        ))
+        timeout = None if timeout_seconds == -1 else timeout_seconds
+        run_command = list(command)
+        run_cwd = cwd
+        run_env = os.environ.copy()
+        if runtime["type"] == "docker":
+            docker_info = self._docker_info(runtime["container"])
+            if not docker_info["running"]:
+                raise RuntimeError(
+                    f"docker container is not running: {runtime['container']}"
+                )
+            activated = self._activation_environment(
+                runtime,
+                environments,
+            )
+            run_command = ["docker", "exec"]
+            if cwd:
+                run_command += ["--workdir", str(cwd)]
+            for key, value in activated.items():
+                run_command += ["--env", f"{key}={value}"]
+            for key, value in additions.items():
+                run_command += ["--env", f"{key}={value}"]
+            run_command += [
+                runtime["container"],
+                *command,
+            ]
+            run_cwd = None
+        else:
+            run_env.update(node_environment)
+            run_env.update(
+                self._activation_environment(
+                    runtime,
+                    environments,
+                    node_environment,
+                )
+            )
+            run_env.update(additions)
+        (
+            returncode,
+            stdout,
+            stderr,
+            stdout_truncated,
+            stderr_truncated,
+            timed_out,
+            cancelled,
+            output_drain_truncated,
+        ) = _execute_bounded(
+            run_command,
+            cwd=run_cwd,
+            env=run_env,
+            timeout=timeout,
+            cancellation_requested=cancellation_requested,
+            output_callback=output_callback,
+            retain_output=retain_output,
+        )
+        result: dict[str, Any] = {
+            "returncode": returncode,
+            "output_drain_truncated": output_drain_truncated,
+            "cwd": cwd,
+            "runtime": runtime,
+            "environments": environments,
+        }
+        if retain_output:
+            result.update(
+                {
+                    "stdout": stdout,
+                    "stderr": stderr,
+                    "stdout_truncated": stdout_truncated,
+                    "stderr_truncated": stderr_truncated,
+                }
+            )
+        if timed_out:
+            result["timed_out"] = True
+        if cancelled:
+            result["cancelled"] = True
+        return result
+
+
+class RpcHandler(socketserver.StreamRequestHandler):
+    def _connection_closed(self) -> bool:
+        try:
+            readable, _, _ = select.select([self.connection], [], [], 0)
+            if not readable:
+                return False
+            return (
+                self.connection.recv(
+                    1,
+                    socket.MSG_PEEK | socket.MSG_DONTWAIT,
+                )
+                == b""
+            )
+        except BlockingIOError:
+            return False
+        except OSError:
+            return True
+
+    def _handle_exec_stream(
+        self,
+        request_id: Any,
+        params: dict[str, Any],
+    ) -> None:
+        write_lock = threading.Lock()
+        writer_failed = threading.Event()
+        sequence = [0]
+
+        def emit(event: dict[str, Any]) -> None:
+            with write_lock:
+                if writer_failed.is_set():
+                    return
+                sequence[0] += 1
+                value = {
+                    "id": request_id,
+                    "seq": sequence[0],
+                    **event,
+                }
+                raw = _encode_json_response(value, MAX_RPC_RESPONSE_BYTES)
+                if raw is None:
+                    writer_failed.set()
+                    return
+                try:
+                    self.wfile.write(raw)
+                    self.wfile.flush()
+                except (BrokenPipeError, ConnectionResetError, OSError):
+                    writer_failed.set()
+
+        def output_callback(stream_name: str, chunk: bytes) -> None:
+            emit(
+                {
+                    "event": stream_name,
+                    "data_base64": base64.b64encode(chunk).decode("ascii"),
+                }
+            )
+
+        def cancellation_requested() -> bool:
+            return writer_failed.is_set() or self._connection_closed()
+
+        try:
+            result = self.server.dispatcher.exec_command(  # type: ignore[attr-defined]
+                params,
+                cancellation_requested,
+                output_callback,
+                False,
+            )
+            emit({"event": "result", "result": result})
+        except Exception as exc:
+            emit(
+                {
+                    "event": "error",
+                    "error": {
+                        "type": type(exc).__name__,
+                        "message": _bounded_utf8(exc, MAX_RPC_ERROR_BYTES),
+                    },
+                }
+            )
+
+    def handle(self) -> None:
+        raw = self.rfile.readline(MAX_REQUEST_BYTES + 1)
+        if not raw:
+            return
+        if len(raw) > MAX_REQUEST_BYTES:
+            self._write({"id": None, "error": {"type": "RequestTooLarge", "message": "request too large"}})
+            return
+        request_id = None
+        try:
+            request = json.loads(raw)
+            request_id = request.get("id")
+            method = request.get("method")
+            params = request.get("params") or {}
+            if not isinstance(method, str) or not isinstance(params, dict):
+                raise ValueError("request requires string method and object params")
+            if method == "exec.stream":
+                self._handle_exec_stream(request_id, params)
+                return
+            result = self.server.dispatcher.dispatch(  # type: ignore[attr-defined]
+                method,
+                params,
+                self._connection_closed,
+            )
+            response = {"id": request_id, "result": result}
+        except Exception as exc:  # RPC boundary must return structured errors.
+            response = {
+                "id": request_id,
+                "error": {
+                    "type": type(exc).__name__,
+                    "message": str(exc),
+                },
+            }
+            if os.environ.get("MSDEVD_DEBUG") == "1":
+                traceback.print_exc(file=sys.stderr)
+        self._write(response)
+
+    def _write(self, value: dict[str, Any]) -> None:
+        prepared = dict(value)
+        error = prepared.get("error")
+        if isinstance(error, dict):
+            bounded_error = dict(error)
+            bounded_error["message"] = _bounded_utf8(
+                bounded_error.get("message", ""),
+                MAX_RPC_ERROR_BYTES,
+            )
+            prepared["error"] = bounded_error
+
+        raw = _encode_json_response(prepared, MAX_RPC_RESPONSE_BYTES)
+        if raw is None:
+            raw = _encode_json_response(
+                {
+                    "id": prepared.get("id"),
+                    "error": {
+                        "type": "ResponseTooLarge",
+                        "message": "RPC response exceeded the configured byte limit",
+                    },
+                },
+                MAX_RPC_RESPONSE_BYTES,
+            )
+        if raw is None:
+            return
+        try:
+            self.wfile.write(raw)
+            self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            return
+
+
+class ThreadingUnixServer(socketserver.ThreadingMixIn, socketserver.UnixStreamServer):
+    daemon_threads = True
+
+    def __init__(self, path: str, dispatcher: RpcDispatcher):
+        self.dispatcher = dispatcher
+        super().__init__(path, RpcHandler)
+
+
+def serve(socket_path: Path, daemon_data_home: Path) -> None:
+    socket_path = socket_path.expanduser()
+    socket_path.parent.mkdir(parents=True, exist_ok=True)
+    if socket_path.exists():
+        try:
+            with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as probe:
+                probe.settimeout(0.5)
+                probe.connect(str(socket_path))
+            raise RuntimeError(f"daemon already running at {socket_path}")
+        except (ConnectionRefusedError, FileNotFoundError, socket.timeout):
+            socket_path.unlink(missing_ok=True)
+
+    inventory = Inventory(daemon_data_home)
+    server = ThreadingUnixServer(str(socket_path), RpcDispatcher(inventory))
+    os.chmod(socket_path, 0o600)
+    try:
+        server.serve_forever()
+    finally:
+        server.server_close()
+        socket_path.unlink(missing_ok=True)
+
+
+def proxy_rpc(socket_path: Path) -> int:
+    raw = sys.stdin.buffer.readline(MAX_REQUEST_BYTES + 1)
+    if not raw:
+        print(json.dumps({"id": None, "error": {"type": "EmptyRequest", "message": "empty request"}}))
+        return 2
+    try:
+        request = json.loads(raw)
+        cancel_on_disconnect = (
+            isinstance(request, dict)
+            and request.get("cancel_on_disconnect") is True
+        )
+        stream_response = (
+            isinstance(request, dict)
+            and request.get("method") == "exec.stream"
+        )
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        cancel_on_disconnect = False
+        stream_response = False
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+            client.connect(str(socket_path.expanduser()))
+            client.sendall(raw if raw.endswith(b"\n") else raw + b"\n")
+            response = bytearray()
+            while stream_response or not response.endswith(b"\n"):
+                if cancel_on_disconnect:
+                    readable, _, _ = select.select(
+                        [client, sys.stdin.buffer],
+                        [],
+                        [],
+                    )
+                    if sys.stdin.buffer in readable:
+                        if os.read(sys.stdin.fileno(), 1) == b"":
+                            return 130
+                        continue
+                chunk = client.recv(65536)
+                if not chunk:
+                    break
+                if stream_response:
+                    try:
+                        sys.stdout.buffer.write(chunk)
+                        sys.stdout.buffer.flush()
+                    except (BrokenPipeError, OSError):
+                        return 130
+                    continue
+                if len(response) + len(chunk) > MAX_RPC_RESPONSE_BYTES:
+                    _write_proxy_error(
+                        "ResponseTooLarge",
+                        "RPC response exceeded the configured byte limit",
+                    )
+                    return 1
+                response.extend(chunk)
+    except OSError as exc:
+        _write_proxy_error(type(exc).__name__, exc)
+        return 1
+    if not stream_response:
+        sys.stdout.buffer.write(bytes(response))
+        sys.stdout.buffer.flush()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="msdevd", description="User-level msdev node daemon")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve_parser = sub.add_parser("serve", help="run the Unix-socket daemon")
+    serve_parser.add_argument("--socket", type=Path, default=default_socket_path())
+    serve_parser.add_argument("--data-dir", type=Path, default=data_home())
+
+    rpc_parser = sub.add_parser("rpc", help="proxy one JSON RPC request over stdin/stdout")
+    rpc_parser.add_argument("--socket", type=Path, default=default_socket_path())
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    if args.command == "serve":
+        serve(args.socket, args.data_dir)
+    elif args.command == "rpc":
+        raise SystemExit(proxy_rpc(args.socket))
+
+
+if __name__ == "__main__":
+    main()