msdev 0.9.0__py3-none-any.whl

msdev/cli.py

@@ -0,0 +1,1460 @@
+"""msdev client CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import signal
+import sys
+import threading
+import time
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from .core.guides import (
+    EnvironmentGuideStore,
+    MAX_GUIDE_BYTES,
+    NodeGuideStore,
+)
+from .core.limits import DEFAULT_EXEC_TIMEOUT_SECONDS, MAX_INVENTORY_CONTENT_BYTES
+from .core.services import (
+    EnvironmentAddRequest,
+    EnvironmentService,
+    ExecRequest,
+    ExecutionService,
+    ModelAuditRequest,
+    ModelDiscoverRequest,
+    ModelImportRequest,
+    ModelListRequest,
+    ModelRefRequest,
+    ModelRegisterRequest,
+    ModelRebindRequest,
+    ModelRefreshRequest,
+    ModelReplicaAddRequest,
+    ModelReplicaRemoveRequest,
+    ModelService,
+    ModelUnregisterRequest,
+    ModelUpdateRequest,
+    ModelValidateRequest,
+    ModelVerifyRequest,
+    NpuService,
+    ServiceContext,
+    NodeAddRequest,
+    NodeService,
+    WorkspaceAddRequest,
+    WorkspaceService,
+)
+from .core.resources import EnvironmentStore, NodeStore
+from .core.transport import (
+    RpcError,
+    SshRpcTransport,
+    UnixRpcTransport,
+    bootstrap_node,
+)
+from .core.workspace import WorkspaceStore
+from .session.log import CliOperationLogger, begin_session, monotonic_ms
+
+
+class _StrictArgumentParser(argparse.ArgumentParser):
+    def __init__(self, *args: Any, **kwargs: Any):
+        kwargs.setdefault("allow_abbrev", False)
+        super().__init__(*args, **kwargs)
+
+
+def _print_json(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def _human_size(value: int | None) -> str:
+    size = float(value or 0)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if size < 1024 or unit == "TiB":
+            return f"{size:.1f}{unit}"
+        size /= 1024
+    return f"{size:.1f}TiB"
+
+
+def _service_context(
+    node_store: NodeStore,
+    environment_store: EnvironmentStore,
+    workspace_store: WorkspaceStore | None = None,
+) -> ServiceContext:
+    values: dict[str, Any] = {
+        "node_store": node_store,
+        "environment_store": environment_store,
+        "create_transport": lambda node, environment=None: (
+            UnixRpcTransport()
+            if node is None
+            else SshRpcTransport(node, environment)
+        ),
+        "bootstrap": bootstrap_node,
+    }
+    if workspace_store is not None:
+        values["workspace_store"] = workspace_store
+    return ServiceContext(
+        **values,
+    )
+
+
+def _parse_root_maps(values: list[str]) -> tuple[tuple[str, str], ...]:
+    result: list[tuple[str, str]] = []
+    for value in values:
+        old, separator, new = value.partition("=")
+        if not separator or not old or not new:
+            raise ValueError(f"invalid root mapping {value!r}; expected OLD=NEW")
+        result.append((old, new))
+    return tuple(result)
+
+
+def _read_inventory(path: Path) -> str:
+    with path.open("rb") as handle:
+        raw = handle.read(MAX_INVENTORY_CONTENT_BYTES + 1)
+    if len(raw) > MAX_INVENTORY_CONTENT_BYTES:
+        raise ValueError(
+            f"inventory export exceeds {MAX_INVENTORY_CONTENT_BYTES} bytes: "
+            f"{path}"
+        )
+    content = raw.decode("utf-8")
+    if not content.splitlines():
+        raise ValueError(f"empty inventory export: {path}")
+    return content
+
+
+def _write_inventory(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _command_guide(
+    args: argparse.Namespace,
+    guide_store: NodeGuideStore | EnvironmentGuideStore,
+    resource_type: str,
+) -> int:
+    if args.write is not None:
+        if args.write == "-":
+            raw = sys.stdin.buffer.read(MAX_GUIDE_BYTES + 1)
+        else:
+            with Path(args.write).open("rb") as handle:
+                raw = handle.read(MAX_GUIDE_BYTES + 1)
+        guide_store.write_bytes(args.name, raw)
+        print(f"updated guide for {resource_type} {args.name}")
+        return 0
+    if args.delete:
+        deleted = guide_store.delete(args.name)
+        action = "deleted guide for" if deleted else "no guide configured for"
+        print(f"{action} {resource_type} {args.name}")
+        return 0
+    content = guide_store.read(args.name)
+    if content is None:
+        print(f"no guide configured for {resource_type} {args.name}")
+    else:
+        print(content, end="" if content.endswith("\n") else "\n")
+    return 0
+
+
+def command_node(
+    args: argparse.Namespace,
+    node_store: NodeStore,
+    environment_store: EnvironmentStore,
+) -> int:
+    service = NodeService(_service_context(node_store, environment_store))
+    action = args.node_command
+    if action == "guide":
+        if args.name != "local":
+            node_store.get(args.name)
+        return _command_guide(args, NodeGuideStore(), "node")
+    if action == "env":
+        node = (
+            service.update_variables(
+                args.name,
+                set_values=tuple(args.set_values),
+                unset_keys=tuple(args.unset_keys),
+            )
+            if args.set_values or args.unset_keys
+            else node_store.get(args.name)
+        )
+        for assignment in node.variables:
+            print(assignment)
+        return 0
+    if action == "add":
+        node = service.add(
+            NodeAddRequest(
+                name=args.name,
+                ssh_host=args.ssh_host,
+                remote_bin=args.remote_bin,
+                auto_bootstrap=not args.no_auto_bootstrap,
+                force=args.force,
+            )
+        )
+        print(
+            f"added node {node.name} (SSH Host {node.ssh_host}); "
+            f"created host environment {node.name}"
+        )
+        return 0
+    if action == "list":
+        print("local")
+        for node in service.list().nodes:
+            print(
+                f"{node.name}\tssh={node.ssh_host}\t"
+                f"auto-bootstrap={'on' if node.auto_bootstrap else 'off'}\t"
+                f"bin={node.remote_bin}"
+            )
+        return 0
+    if action == "remove":
+        removed = service.remove(args.name, cascade=args.cascade)
+        print(f"removed node {args.name}")
+        if removed:
+            print("removed environments: " + ", ".join(removed))
+        return 0
+    if action == "status":
+        print(f"node: {args.name}")
+        _print_json(service.status(args.name))
+        return 0
+    if action == "bootstrap":
+        result = service.bootstrap(args.name, args.package_path)
+        print(f"bootstrapped node {args.name}")
+        _print_json(result)
+        return 0
+    if action in {"connect", "disconnect"}:
+        result = (
+            service.connect(args.name, all_nodes=args.all)
+            if action == "connect"
+            else service.disconnect(args.name, all_nodes=args.all)
+        )
+        for item in result.items:
+            if item.error is not None:
+                print(f"{item.node}: error: {item.error}", file=sys.stderr)
+            elif action == "connect":
+                print(
+                    f"{item.node}: {item.state} to {item.ssh_host} "
+                    f"(persist={item.persist})"
+                )
+            else:
+                print(f"{item.node}: {item.state}")
+        return result.exit_code
+    raise ValueError(f"unsupported node command: {action}")
+
+
+def command_environment(
+    args: argparse.Namespace,
+    node_store: NodeStore,
+    environment_store: EnvironmentStore,
+) -> int:
+    service = EnvironmentService(_service_context(node_store, environment_store))
+    action = args.environment_command
+    if action == "guide":
+        environment_store.get(args.name)
+        return _command_guide(args, EnvironmentGuideStore(), "environment")
+    if action == "shell":
+        if not sys.stdin.isatty() or not sys.stdout.isatty():
+            raise ValueError("environment shell requires an interactive terminal")
+        return service.shell(args.name, cwd=args.cwd)
+    if action == "add":
+        environment = service.add(
+            EnvironmentAddRequest(
+                name=args.name,
+                node=args.node,
+                docker_container=args.docker_container,
+                layers=tuple(args.layer),
+                force=args.force,
+            )
+        )
+        print(f"added environment {environment.name} on node {environment.node}")
+        return 0
+    if action == "list":
+        print("local")
+        for environment in service.list().environments:
+            runtime = (
+                f"docker:{environment.container}"
+                if environment.runtime == "docker"
+                else "host"
+            )
+            layers = ">".join(environment.layers) if environment.layers else "-"
+            print(
+                f"{environment.name}\tnode={environment.node}\t"
+                f"runtime={runtime}\tlayers={layers}"
+            )
+        return 0
+    if action == "inspect":
+        _print_json(asdict(service.inspect(args.name)))
+        return 0
+    if action == "remove":
+        service.remove(args.name)
+        print(f"removed environment {args.name}")
+        return 0
+    raise ValueError(f"unsupported environment command: {action}")
+
+
+def command_npu(
+    args: argparse.Namespace,
+    node_store: NodeStore,
+    environment_store: EnvironmentStore,
+) -> int:
+    service = NpuService(_service_context(node_store, environment_store))
+    if args.all:
+        service_result = service.list(all_nodes=True)
+        results = {
+            item.node: {
+                "ssh_host": item.ssh_host,
+                **(
+                    {"error": item.error}
+                    if item.error is not None
+                    else {"result": item.result}
+                ),
+            }
+            for item in service_result.items
+        }
+        if args.json:
+            _print_json(results)
+        else:
+            for item in service_result.items:
+                value = results[item.node]
+                print(f"===== {item.node} ({item.ssh_host}) =====")
+                if "error" in value:
+                    print(f"error: {value['error']}", file=sys.stderr)
+                    continue
+                result = value["result"]
+                if result.get("reason"):
+                    print(result["reason"], file=sys.stderr)
+                print(result.get("output", ""), end="")
+        return service_result.exit_code
+
+    service_result = service.list(node=args.node)
+    item = service_result.items[0]
+    result = item.result or {}
+    if args.json:
+        _print_json({"node": item.node, **result})
+    else:
+        print(f"node: {item.node}")
+        if result.get("reason"):
+            print(result["reason"], file=sys.stderr)
+        print(result.get("output", ""), end="")
+    return service_result.exit_code
+
+
+def command_model(
+    args: argparse.Namespace,
+    node_store: NodeStore,
+    environment_store: EnvironmentStore,
+) -> int:
+    service = ModelService(_service_context(node_store, environment_store))
+    if args.model_command == "register":
+        result = service.register(
+            ModelRegisterRequest(
+                node=args.node,
+                ref=args.ref,
+                path=args.path,
+                scope="user",
+                format_name=args.format,
+                full_checksum=args.full_checksum,
+            )
+        )
+        print(f"registered on {result.node}: {args.ref}")
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "discover":
+        result = service.discover(
+            ModelDiscoverRequest(
+                node=args.node,
+                root=args.root,
+                max_depth=args.max_depth,
+                register=args.register,
+                namespace=args.namespace,
+            )
+        )
+        if args.json:
+            _print_json(result.value)
+            return result.exit_code
+        models = result.value["models"]
+        action = "registered" if args.register else "found"
+        print(
+            f"{action} {len(models)} model(s) under {result.value['root']} "
+            f"on {result.node}"
+        )
+        if models:
+            print("REF\tFORMAT\tSIZE\tFILES\tPATH")
+            for item in models:
+                print(
+                    f"{item['ref']}\t{item['format']}\t"
+                    f"{_human_size(item['size_bytes'])}\t"
+                    f"{item['file_count']}\t{item['path']}"
+                )
+        return result.exit_code
+    if args.model_command == "list":
+        result = service.list(
+            ModelListRequest(
+                node=args.node,
+                all_nodes=args.all,
+                format_name=args.format_filter,
+                model_type=args.model_type,
+                state=args.state,
+                tag=args.tag_filter,
+                name=args.name_filter,
+                include_deleted=args.include_deleted,
+            )
+        )
+        if args.all:
+            nodes = [
+                {
+                    "node": item.node,
+                    "ssh_host": item.ssh_host,
+                    "models": list(item.models),
+                }
+                for item in result.nodes
+            ]
+            errors = [
+                {
+                    "node": item.node,
+                    "ssh_host": item.ssh_host,
+                    "error": item.error,
+                }
+                for item in result.errors
+            ]
+            if args.json:
+                _print_json({"nodes": nodes, "errors": errors})
+            else:
+                rows = [
+                    (node.node, model)
+                    for node in result.nodes
+                    for model in node.models
+                ]
+                if rows:
+                    print("NODE\tREF\tSTATE\tVERIFY\tSIZE\tTAGS\tPATH")
+                    for node_name, item in rows:
+                        print(
+                            f"{node_name}\t{item['ref']}\t"
+                            f"{item.get('state') or '-'}\t"
+                            f"{item.get('verification_level') or '-'}\t"
+                            f"{_human_size(item.get('size_bytes'))}\t"
+                            f"{','.join(item.get('tags') or []) or '-'}\t"
+                            f"{item.get('path') or '-'}"
+                        )
+                else:
+                    print("no models registered across SSH nodes")
+                for error in result.errors:
+                    print(
+                        f"{error.node} ({error.ssh_host}): "
+                        f"error: {error.error}",
+                        file=sys.stderr,
+                    )
+            return result.exit_code
+
+        node = result.nodes[0]
+        models = node.models
+        if args.json:
+            _print_json(list(models))
+            return result.exit_code
+        if not models:
+            print(f"no models registered on {node.node}")
+            return result.exit_code
+        print("REF\tSTATE\tVERIFY\tSIZE\tTAGS\tPATH")
+        for item in models:
+            print(
+                f"{item['ref']}\t{item.get('state') or '-'}\t"
+                f"{item.get('verification_level') or '-'}\t"
+                f"{_human_size(item.get('size_bytes'))}\t"
+                f"{','.join(item.get('tags') or []) or '-'}\t"
+                f"{item.get('path') or '-'}"
+            )
+        return result.exit_code
+    if args.model_command == "inspect":
+        result = service.inspect(ModelRefRequest(args.node, args.ref))
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "update":
+        result = service.update(
+            ModelUpdateRequest(
+                node=args.node,
+                ref=args.ref,
+                add_aliases=tuple(args.add_alias),
+                remove_aliases=tuple(args.remove_alias),
+                add_tags=tuple(args.add_tag),
+                remove_tags=tuple(args.remove_tag),
+                description=args.description,
+                clear_description=args.clear_description,
+            )
+        )
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "delete":
+        result = service.delete(ModelRefRequest(args.node, args.ref))
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "restore":
+        result = service.restore(ModelRefRequest(args.node, args.ref))
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "refresh":
+        result = service.refresh(
+            ModelRefreshRequest(
+                node=args.node,
+                ref=args.ref,
+                path=args.path,
+                full_checksum=args.full_checksum,
+            )
+        )
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "validate":
+        result = service.validate(
+            ModelValidateRequest(
+                node=args.node,
+                ref=args.ref,
+                path=args.path,
+            )
+        )
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "audit":
+        result = service.audit(
+            ModelAuditRequest(
+                node=args.node,
+                ref=args.ref,
+                limit=args.limit,
+            )
+        )
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "replica":
+        if args.replica_command == "list":
+            result = service.replica_list(
+                ModelRefRequest(args.node, args.ref)
+            )
+            _print_json(result.value)
+            return result.exit_code
+        if args.replica_command == "add":
+            result = service.replica_add(
+                ModelReplicaAddRequest(
+                    node=args.node,
+                    ref=args.ref,
+                    path=args.path,
+                    full_checksum=args.full_checksum,
+                )
+            )
+            _print_json(result.value)
+            return result.exit_code
+        if args.replica_command == "remove":
+            result = service.replica_remove(
+                ModelReplicaRemoveRequest(
+                    node=args.node,
+                    ref=args.ref,
+                    path=args.path,
+                )
+            )
+            _print_json(result.value)
+            return result.exit_code
+    if args.model_command == "verify":
+        result = service.verify(
+            ModelVerifyRequest(
+                node=args.node,
+                ref=args.ref,
+                full_checksum=args.full_checksum,
+            )
+        )
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "unregister":
+        result = service.unregister(
+            ModelUnregisterRequest(
+                node=args.node,
+                ref=args.ref,
+                path=args.path,
+            )
+        )
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "export":
+        result = service.export(args.node)
+        _write_inventory(args.output, result.jsonl)
+        print(
+            f"exported {len(result.payload.get('artifacts', []))} artifacts "
+            f"from {result.node} to {args.output}"
+        )
+        return result.exit_code
+    if args.model_command == "import":
+        result = service.import_records(
+            ModelImportRequest(
+                node=args.node,
+                jsonl=_read_inventory(args.input),
+                root_maps=_parse_root_maps(args.map_root),
+            )
+        )
+        _print_json(result.value)
+        return result.exit_code
+    if args.model_command == "rebind":
+        result = service.rebind(
+            ModelRebindRequest(
+                node=args.node,
+                ref=args.ref,
+                path=args.path,
+                scope="user",
+                full_checksum=args.full_checksum,
+            )
+        )
+        _print_json(result.value)
+        return result.exit_code
+    raise ValueError(f"unsupported model command: {args.model_command}")
+
+
+def command_exec(
+    args: argparse.Namespace,
+    node_store: NodeStore,
+    environment_store: EnvironmentStore,
+) -> int:
+    command = list(args.argv)
+    if command and command[0] == "--":
+        command = command[1:]
+    if not command:
+        raise ValueError("missing command after `msdev exec --`")
+    env: dict[str, str] = {}
+    for value in args.env_var:
+        key, separator, item = value.partition("=")
+        if not separator or not key:
+            raise ValueError(f"invalid environment assignment: {value!r}")
+        env[key] = item
+    request = ExecRequest(
+        environment=args.environment,
+        argv=tuple(command),
+        cwd=args.cwd,
+        env=env,
+        timeout_seconds=args.timeout_seconds,
+    )
+    service = ExecutionService(_service_context(node_store, environment_store))
+    if args.result_json:
+        result = service.run(request)
+        _print_json(result.to_dict())
+    else:
+        def on_output(stream_name: str, chunk: bytes) -> None:
+            destination = (
+                sys.stdout if stream_name == "stdout" else sys.stderr
+            )
+            binary = getattr(destination, "buffer", None)
+            if binary is not None:
+                binary.write(chunk)
+                binary.flush()
+            else:
+                destination.write(chunk.decode("utf-8", errors="replace"))
+                destination.flush()
+
+        result = service.stream(request, on_output)
+    return result.returncode
+
+
+def _print_workspace_git_result(
+    result: Any,
+    *,
+    result_json: bool = False,
+) -> int:
+    if result.stdout:
+        print(result.stdout, end="")
+    if result.stderr:
+        print(result.stderr, end="", file=sys.stderr)
+    if result.stdout_truncated or result.stderr_truncated:
+        print(
+            "warning: remote command output was truncated at the daemon limit",
+            file=sys.stderr,
+        )
+    if result_json:
+        _print_json(result.to_dict())
+    return result.returncode
+
+
+def _workspace_write_content(args: argparse.Namespace) -> bytes:
+    if args.content is not None:
+        return args.content.encode("utf-8")
+    if args.file is not None:
+        return args.file.read_bytes()
+    return sys.stdin.buffer.read()
+
+
+def command_workspace(
+    args: argparse.Namespace,
+    node_store: NodeStore,
+    environment_store: EnvironmentStore,
+    workspace_store: WorkspaceStore,
+) -> int:
+    action = args.workspace_command
+    service = WorkspaceService(
+        _service_context(node_store, environment_store, workspace_store)
+    )
+    if action == "add":
+        workspace = service.add(
+            WorkspaceAddRequest(
+                name=args.name,
+                environment=args.environment,
+                root=args.root,
+                execution_root=args.execution_root,
+                force=args.force,
+            )
+        )
+        print(
+            f"added workspace {workspace.name} "
+            f"(environment={workspace.environment}, root={workspace.root})"
+        )
+        return 0
+    if action == "list" and args.name is None:
+        workspaces = service.list().workspaces
+        if args.json:
+            _print_json([workspace.__dict__ for workspace in workspaces])
+        else:
+            for workspace in workspaces:
+                print(
+                    f"{workspace.name}\tenvironment={workspace.environment}\t"
+                    f"root={workspace.root}\t"
+                    f"execution-root={workspace.execution_root or workspace.root}"
+                )
+        return 0
+    if action == "inspect":
+        _print_json(service.inspect(args.name).to_dict())
+        return 0
+    if action == "remove":
+        result = service.remove(args.name)
+        print(f"removed workspace {result.name}")
+        return 0
+
+    if action == "stat":
+        _print_json(service.stat(args.name, args.path).raw)
+        return 0
+    if action == "read":
+        result = service.read(
+            args.name,
+            args.path,
+            max_bytes=args.max_bytes,
+        )
+        if args.json:
+            _print_json(result.raw)
+        elif args.output:
+            args.output.write_bytes(result.content)
+        else:
+            sys.stdout.buffer.write(result.content)
+            sys.stdout.buffer.flush()
+        return 0
+    if action in {"list", "list-files"}:
+        result = service.list_directory(args.name, args.path).raw
+        if args.json:
+            _print_json(result)
+        else:
+            for item in result["entries"]:
+                print(f"{item['type']}\t{item['size'] if item['size'] is not None else '-'}\t{item['path']}")
+        return 0
+    if action == "glob":
+        result = service.glob(
+            args.name,
+            args.pattern,
+            max_results=args.max_results,
+        )
+        if args.json:
+            _print_json(result.raw)
+        else:
+            for path in result.matches:
+                print(path)
+        return 0
+    if action == "search":
+        result = service.search(
+            args.name,
+            args.pattern,
+            paths=args.paths,
+            glob=args.glob_filter,
+            max_results=args.max_results,
+        )
+        if args.json:
+            _print_json(result.raw)
+        else:
+            for item in result.matches:
+                print(f"{item['path']}:{item['line']}:{item['text']}")
+        return 0
+    if action in {"write", "apply-patch"}:
+        content = _workspace_write_content(args)
+        if action == "apply-patch":
+            result = service.apply_patch(
+                args.name,
+                args.path,
+                content,
+                expected_sha256=args.expected_sha256,
+            )
+        else:
+            result = service.write(args.name, args.path, content)
+        _print_json(result.raw)
+        return 0
+    if action == "delete":
+        _print_json(service.delete(args.name, args.path).raw)
+        return 0
+    if action == "git-status":
+        return _print_workspace_git_result(
+            service.git_status(args.name),
+            result_json=args.result_json,
+        )
+    if action == "git-diff":
+        return _print_workspace_git_result(
+            service.git_diff(args.name, args.argv),
+            result_json=args.result_json,
+        )
+    raise ValueError(f"unsupported workspace command: {action}")
+
+
+def command_session(args: argparse.Namespace) -> int:
+    from .session.export import (
+        iter_events,
+        list_sessions,
+        reject_output_alias,
+        render_markdown,
+        resolve_session_sources,
+        session_log_location,
+        write_markdown_atomic,
+    )
+
+    if args.session_command == "begin":
+        session = begin_session(args.name)
+        value = {
+            "session_id": session.session_id,
+            "path": str(session.path),
+        }
+        if args.json:
+            _print_json(value)
+        else:
+            print(session.session_id)
+            print(session.path)
+        return 0
+    if args.session_command == "list":
+        sessions = list_sessions(session_log_location())
+        if not sessions:
+            print("no CLI session logs found")
+            return 0
+        for session in sessions:
+            print(f"{session.name}\t{session.size} bytes\tmtime_ns={session.mtime_ns}")
+        return 0
+    if args.session_command == "export":
+        sources = resolve_session_sources(
+            latest=args.latest,
+            inputs=args.input,
+            session_id=args.export_session_id,
+        )
+        chunks = render_markdown(iter_events(sources), args.detail)
+        if args.output is None:
+            for chunk in chunks:
+                sys.stdout.write(chunk)
+            sys.stdout.flush()
+        else:
+            reject_output_alias(args.output, sources)
+            write_markdown_atomic(args.output, chunks)
+            print(f"exported session runbook to {args.output}")
+        return 0
+    raise ValueError(f"unsupported session command: {args.session_command}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = _StrictArgumentParser(
+        prog="msdev",
+        description="Manage msdev nodes and execution environments",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help="override local node/environment registry path",
+    )
+    parser.add_argument(
+        "--workspace-config",
+        type=Path,
+        default=None,
+        help="override local workspace registry path",
+    )
+    parser.add_argument(
+        "--session-id",
+        default=os.environ.get("MSDEV_SESSION_ID"),
+        help="explicit CLI session used for operation logs",
+    )
+    parser.add_argument(
+        "--intent-kind",
+        choices=("execution", "verification", "diagnostic", "exploration"),
+        default=os.environ.get("MSDEV_INTENT_KIND"),
+    )
+    parser.add_argument(
+        "--intent-summary",
+        default=os.environ.get("MSDEV_INTENT_SUMMARY"),
+    )
+    parser.add_argument(
+        "--intent-phase",
+        default=os.environ.get("MSDEV_INTENT_PHASE"),
+    )
+    parser.add_argument(
+        "--intent-step-id",
+        default=os.environ.get("MSDEV_INTENT_STEP_ID"),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    node = sub.add_parser("node", help="manage SSH connection nodes")
+    node_sub = node.add_subparsers(dest="node_command", required=True)
+    node_add = node_sub.add_parser("add")
+    node_add.add_argument("name")
+    node_add.add_argument("--ssh-host", help="OpenSSH Host alias; defaults to name")
+    node_add.add_argument("--remote-bin", default="~/.local/bin/msdevd")
+    node_add.add_argument(
+        "--force",
+        action="store_true",
+        help="replace an existing node and its same-named host environment",
+    )
+    node_add.add_argument(
+        "--no-auto-bootstrap",
+        action="store_true",
+        help="do not install/start msdevd automatically on first use",
+    )
+    node_sub.add_parser("list")
+    node_env = node_sub.add_parser(
+        "env",
+        help="read or update persistent host environment variables",
+    )
+    node_env.add_argument("name")
+    node_env.add_argument(
+        "--set",
+        dest="set_values",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+    )
+    node_env.add_argument(
+        "--unset",
+        dest="unset_keys",
+        action="append",
+        default=[],
+        metavar="KEY",
+    )
+    node_guide = node_sub.add_parser(
+        "guide",
+        help="read or maintain the local Markdown guide for a node",
+    )
+    node_guide.add_argument("name")
+    node_guide_action = node_guide.add_mutually_exclusive_group()
+    node_guide_action.add_argument(
+        "--write",
+        metavar="FILE",
+        help="replace the guide from FILE, or - for stdin",
+    )
+    node_guide_action.add_argument(
+        "--delete",
+        action="store_true",
+        help="delete the local guide without removing the node",
+    )
+    node_remove = node_sub.add_parser("remove")
+    node_remove.add_argument("name")
+    node_remove.add_argument(
+        "--cascade",
+        action="store_true",
+        help="also remove every environment on this node",
+    )
+    node_status = node_sub.add_parser("status")
+    node_status.add_argument("name")
+    node_bootstrap = node_sub.add_parser("bootstrap")
+    node_bootstrap.add_argument("name")
+    node_bootstrap.add_argument("--package-path", type=Path)
+    node_connect = node_sub.add_parser(
+        "connect",
+        help="open a persistent SSH master and prompt once for authentication",
+    )
+    node_connect.add_argument("name", nargs="?")
+    node_connect.add_argument("--all", action="store_true")
+    node_disconnect = node_sub.add_parser(
+        "disconnect",
+        help="close a persistent SSH master",
+    )
+    node_disconnect.add_argument("name", nargs="?")
+    node_disconnect.add_argument("--all", action="store_true")
+
+    environment = sub.add_parser(
+        "env",
+        help="manage host, Docker, conda, venv, and uv execution environments",
+    )
+    environment_sub = environment.add_subparsers(
+        dest="environment_command",
+        required=True,
+    )
+    environment_add = environment_sub.add_parser("add")
+    environment_add.add_argument("name")
+    environment_add.add_argument("--node", required=True)
+    environment_add.add_argument("--docker-container")
+    environment_add.add_argument(
+        "--layer",
+        action="append",
+        default=[],
+        metavar="TYPE:VALUE",
+        help=(
+            "append an environment layer; repeat for nesting "
+            "(conda:<name-or-prefix>, venv:<path>, uv:<project-path>)"
+        ),
+    )
+    environment_add.add_argument("--force", action="store_true")
+    environment_sub.add_parser("list")
+    environment_inspect = environment_sub.add_parser("inspect")
+    environment_inspect.add_argument("name")
+    environment_guide = environment_sub.add_parser("guide")
+    environment_guide.add_argument("name")
+    environment_guide_action = environment_guide.add_mutually_exclusive_group()
+    environment_guide_action.add_argument("--write", metavar="FILE")
+    environment_guide_action.add_argument("--delete", action="store_true")
+    environment_shell = environment_sub.add_parser("shell")
+    environment_shell.add_argument("name")
+    environment_shell.add_argument("--cwd")
+    environment_remove = environment_sub.add_parser("remove")
+    environment_remove.add_argument("name")
+
+    workspace = sub.add_parser(
+        "workspace",
+        help="manage and access explicit remote workspaces",
+    )
+    workspace_sub = workspace.add_subparsers(
+        dest="workspace_command",
+        required=True,
+    )
+    workspace_add = workspace_sub.add_parser("add")
+    workspace_add.add_argument("name")
+    workspace_add.add_argument("--env", dest="environment", required=True)
+    workspace_add.add_argument("--root", required=True)
+    workspace_add.add_argument(
+        "--execution-root",
+        help="command cwd in the environment runtime",
+    )
+    workspace_add.add_argument("--force", action="store_true")
+
+    workspace_list = workspace_sub.add_parser(
+        "list",
+        help="list registered workspaces, or list a named workspace directory",
+    )
+    workspace_list.add_argument("name", nargs="?")
+    workspace_list.add_argument("path", nargs="?", default=".")
+    workspace_list.add_argument("--json", action="store_true")
+
+    workspace_inspect = workspace_sub.add_parser("inspect")
+    workspace_inspect.add_argument("name")
+    workspace_remove = workspace_sub.add_parser("remove")
+    workspace_remove.add_argument("name")
+
+    workspace_stat = workspace_sub.add_parser("stat")
+    workspace_stat.add_argument("name")
+    workspace_stat.add_argument("path", nargs="?", default=".")
+
+    workspace_read = workspace_sub.add_parser("read")
+    workspace_read.add_argument("name")
+    workspace_read.add_argument("path")
+    workspace_read.add_argument("--max-bytes", type=int, default=1024 * 1024)
+    workspace_read.add_argument("--output", type=Path)
+    workspace_read.add_argument("--json", action="store_true")
+
+    workspace_glob = workspace_sub.add_parser("glob")
+    workspace_glob.add_argument("name")
+    workspace_glob.add_argument("pattern")
+    workspace_glob.add_argument("--max-results", type=int, default=1000)
+    workspace_glob.add_argument("--json", action="store_true")
+
+    workspace_search = workspace_sub.add_parser("search")
+    workspace_search.add_argument("name")
+    workspace_search.add_argument("pattern")
+    workspace_search.add_argument("paths", nargs="*", default=["."])
+    workspace_search.add_argument("--glob", dest="glob_filter")
+    workspace_search.add_argument("--max-results", type=int, default=1000)
+    workspace_search.add_argument("--json", action="store_true")
+
+    for command_name, help_text in (
+        ("write", "atomically replace a workspace file"),
+        (
+            "apply-patch",
+            "compare-and-swap a workspace file using its expected SHA256",
+        ),
+    ):
+        write_parser = workspace_sub.add_parser(command_name, help=help_text)
+        write_parser.add_argument("name")
+        write_parser.add_argument("path")
+        content_source = write_parser.add_mutually_exclusive_group()
+        content_source.add_argument("--content")
+        content_source.add_argument("--file", type=Path)
+        if command_name == "apply-patch":
+            write_parser.add_argument("--expected-sha256", required=True)
+
+    workspace_delete = workspace_sub.add_parser("delete")
+    workspace_delete.add_argument("name")
+    workspace_delete.add_argument("path")
+
+    workspace_git_status = workspace_sub.add_parser("git-status")
+    workspace_git_status.add_argument("name")
+    workspace_git_status.add_argument("--result-json", action="store_true")
+    workspace_git_diff = workspace_sub.add_parser("git-diff")
+    workspace_git_diff.add_argument("name")
+    workspace_git_diff.add_argument("--result-json", action="store_true")
+    workspace_git_diff.add_argument("argv", nargs=argparse.REMAINDER)
+
+    npu = sub.add_parser("npu", help="inspect NPU state")
+    npu_sub = npu.add_subparsers(dest="npu_command", required=True)
+    npu_list = npu_sub.add_parser("list")
+    npu_scope = npu_list.add_mutually_exclusive_group(required=True)
+    npu_scope.add_argument("--node")
+    npu_scope.add_argument(
+        "--all",
+        action="store_true",
+        help="query every registered SSH node",
+    )
+    npu_list.add_argument("--json", action="store_true")
+
+    model = sub.add_parser("model", help="manage model inventory")
+    model_sub = model.add_subparsers(dest="model_command", required=True)
+    register = model_sub.add_parser("register")
+    register.add_argument("--node", required=True)
+    register.add_argument("--ref", required=True)
+    register.add_argument("--path", required=True)
+    register.add_argument("--format")
+    register.add_argument("--full-checksum", action="store_true")
+
+    discover = model_sub.add_parser(
+        "discover",
+        help="find model snapshots under a remote directory",
+    )
+    discover.add_argument("--node", required=True)
+    discover.add_argument("--root", required=True)
+    discover.add_argument("--max-depth", type=int, default=5)
+    discover.add_argument("--namespace", default="discovered")
+    discover.add_argument(
+        "--register",
+        action="store_true",
+        help="register discovered snapshots after scanning",
+    )
+    discover.add_argument("--json", action="store_true")
+
+    model_list = model_sub.add_parser("list")
+    model_list_scope = model_list.add_mutually_exclusive_group(required=True)
+    model_list_scope.add_argument("--node")
+    model_list_scope.add_argument(
+        "--all",
+        action="store_true",
+        help="aggregate inventories from every registered SSH node",
+    )
+    model_list.add_argument("--format", dest="format_filter")
+    model_list.add_argument("--model-type")
+    model_list.add_argument(
+        "--state",
+        choices=["ready", "dirty", "missing", "broken"],
+    )
+    model_list.add_argument("--tag", dest="tag_filter")
+    model_list.add_argument("--name", dest="name_filter")
+    model_list.add_argument("--include-deleted", action="store_true")
+    model_list.add_argument("--json", action="store_true")
+
+    inspect = model_sub.add_parser("inspect")
+    inspect.add_argument("ref")
+    inspect.add_argument("--node", required=True)
+
+    update = model_sub.add_parser("update")
+    update.add_argument("ref")
+    update.add_argument("--node", required=True)
+    update.add_argument("--add-alias", action="append", default=[])
+    update.add_argument("--remove-alias", action="append", default=[])
+    update.add_argument("--add-tag", action="append", default=[])
+    update.add_argument("--remove-tag", action="append", default=[])
+    description_group = update.add_mutually_exclusive_group()
+    description_group.add_argument("--description")
+    description_group.add_argument("--clear-description", action="store_true")
+
+    delete = model_sub.add_parser("delete", help="soft-delete model metadata")
+    delete.add_argument("ref")
+    delete.add_argument("--node", required=True)
+
+    restore = model_sub.add_parser("restore")
+    restore.add_argument("ref")
+    restore.add_argument("--node", required=True)
+
+    refresh = model_sub.add_parser("refresh")
+    refresh.add_argument("ref")
+    refresh.add_argument("--node", required=True)
+    refresh.add_argument("--path")
+    refresh.add_argument("--full-checksum", action="store_true")
+
+    validate = model_sub.add_parser("validate")
+    validate.add_argument("ref")
+    validate.add_argument("--node", required=True)
+    validate.add_argument("--path")
+
+    audit = model_sub.add_parser("audit")
+    audit.add_argument("--ref")
+    audit.add_argument("--node", required=True)
+    audit.add_argument("--limit", type=int, default=100)
+
+    replica = model_sub.add_parser("replica")
+    replica_sub = replica.add_subparsers(dest="replica_command", required=True)
+    replica_list = replica_sub.add_parser("list")
+    replica_list.add_argument("ref")
+    replica_list.add_argument("--node", required=True)
+    replica_add = replica_sub.add_parser("add")
+    replica_add.add_argument("ref")
+    replica_add.add_argument("--node", required=True)
+    replica_add.add_argument("--path", required=True)
+    replica_add.add_argument("--full-checksum", action="store_true")
+    replica_remove = replica_sub.add_parser("remove")
+    replica_remove.add_argument("ref")
+    replica_remove.add_argument("--node", required=True)
+    replica_remove.add_argument("--path", required=True)
+
+    verify = model_sub.add_parser("verify")
+    verify.add_argument("ref")
+    verify.add_argument("--node", required=True)
+    verify.add_argument("--full-checksum", action="store_true")
+
+    unregister = model_sub.add_parser("unregister")
+    unregister.add_argument("ref")
+    unregister.add_argument("--path")
+    unregister.add_argument("--node", required=True)
+
+    export = model_sub.add_parser("export")
+    export.add_argument("--output", type=Path, required=True)
+    export.add_argument("--node", required=True)
+
+    import_parser = model_sub.add_parser("import")
+    import_parser.add_argument("input", type=Path)
+    import_parser.add_argument("--map-root", action="append", default=[], metavar="OLD=NEW")
+    import_parser.add_argument("--node", required=True)
+
+    rebind = model_sub.add_parser("rebind")
+    rebind.add_argument("ref")
+    rebind.add_argument("--path", required=True)
+    rebind.add_argument("--full-checksum", action="store_true")
+    rebind.add_argument("--node", required=True)
+
+    execute = sub.add_parser(
+        "exec",
+        help="execute a command in an explicit environment",
+    )
+    execute.add_argument("--env", dest="environment", required=True)
+    execute.add_argument("--cwd")
+    execute.add_argument(
+        "--env-var",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+    )
+    execute.add_argument(
+        "--timeout-seconds",
+        type=float,
+        default=DEFAULT_EXEC_TIMEOUT_SECONDS,
+        help="positive timeout in seconds; -1 waits indefinitely",
+    )
+    execute.add_argument("--result-json", action="store_true")
+    execute.add_argument("argv", nargs=argparse.REMAINDER)
+
+    session = sub.add_parser(
+        "session",
+        help="manage and export explicit CLI operation sessions",
+    )
+    session_sub = session.add_subparsers(dest="session_command", required=True)
+    session_begin = session_sub.add_parser(
+        "begin",
+        help="create an explicit CLI operation session",
+    )
+    session_begin.add_argument("--name")
+    session_begin.add_argument("--json", action="store_true")
+    session_sub.add_parser(
+        "list",
+        help="list discoverable CLI session logs",
+    )
+    session_export = session_sub.add_parser(
+        "export",
+        help="export CLI operation logs as a Markdown runbook",
+    )
+    session_source = session_export.add_mutually_exclusive_group(required=True)
+    session_source.add_argument(
+        "--input",
+        type=Path,
+        action="append",
+        default=[],
+        metavar="PATH",
+        help="JSONL session input; repeat to merge multiple files",
+    )
+    session_source.add_argument(
+        "--latest",
+        action="store_true",
+        help="use the latest CLI operation session log",
+    )
+    session_source.add_argument(
+        "--session-id",
+        dest="export_session_id",
+        help="export the log for an explicit msdev session ID",
+    )
+    session_export.add_argument(
+        "--output", type=Path,
+        help="output file path (default: stdout)",
+    )
+    session_export.add_argument(
+        "--detail", choices=("brief", "normal", "full"), default="normal",
+        help="brief one-line calls, normal runbook, or full sanitized events",
+    )
+
+    return parser
+
+
+def _operation_name(args: argparse.Namespace) -> str:
+    parts = [args.command]
+    for attribute in (
+        "node_command",
+        "environment_command",
+        "workspace_command",
+        "npu_command",
+        "model_command",
+        "replica_command",
+        "session_command",
+    ):
+        value = getattr(args, attribute, None)
+        if value:
+            parts.append(value)
+    return ".".join(parts)
+
+
+def _replay_argv(argv: list[str]) -> list[str]:
+    metadata = {
+        "--session-id",
+        "--intent-kind",
+        "--intent-summary",
+        "--intent-phase",
+        "--intent-step-id",
+    }
+    result: list[str] = []
+    skip_next = False
+    for value in argv:
+        if skip_next:
+            skip_next = False
+            continue
+        option = value.partition("=")[0]
+        if option in metadata:
+            skip_next = "=" not in value
+            continue
+        result.append(value)
+    return result
+
+
+def _intent_from_args(args: argparse.Namespace) -> dict[str, str] | None:
+    values = {
+        "kind": args.intent_kind,
+        "summary": args.intent_summary,
+        "phase": args.intent_phase,
+        "step_id": args.intent_step_id,
+    }
+    if not any(values.values()):
+        return None
+    if not values["kind"]:
+        raise ValueError("--intent-kind is required when intent metadata is used")
+    if not values["summary"]:
+        raise ValueError("--intent-summary is required when intent metadata is used")
+    return {key: value for key, value in values.items() if value}
+
+
+def _watch_parent_exit(
+    parent_pid: int,
+    stop_event: threading.Event,
+    *,
+    poll_seconds: float = 0.1,
+) -> None:
+    while not stop_event.wait(poll_seconds):
+        if os.getppid() != parent_pid:
+            os.kill(os.getpid(), signal.SIGTERM)
+            return
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    node_store = NodeStore(args.config)
+    environment_store = EnvironmentStore(args.config)
+    workspace_store = WorkspaceStore(args.workspace_config)
+    started = time.monotonic()
+    intent: dict[str, str] | None = None
+    previous_sigterm = signal.getsignal(signal.SIGTERM)
+
+    def cancel_on_sigterm(_signum: int, _frame: Any) -> None:
+        raise KeyboardInterrupt
+
+    signal.signal(signal.SIGTERM, cancel_on_sigterm)
+    parent_watch_stop: threading.Event | None = None
+    parent_watch_thread: threading.Thread | None = None
+    if args.command == "exec":
+        parent_watch_stop = threading.Event()
+        parent_watch_thread = threading.Thread(
+            target=_watch_parent_exit,
+            args=(os.getppid(), parent_watch_stop),
+            daemon=True,
+        )
+        parent_watch_thread.start()
+    try:
+        intent = _intent_from_args(args)
+        if args.command == "node":
+            code = command_node(args, node_store, environment_store)
+        elif args.command == "env":
+            code = command_environment(args, node_store, environment_store)
+        elif args.command == "npu" and args.npu_command == "list":
+            code = command_npu(args, node_store, environment_store)
+        elif args.command == "model":
+            code = command_model(args, node_store, environment_store)
+        elif args.command == "exec":
+            code = command_exec(args, node_store, environment_store)
+        elif args.command == "workspace":
+            code = command_workspace(
+                args,
+                node_store,
+                environment_store,
+                workspace_store,
+            )
+        elif args.command == "session":
+            code = command_session(args)
+        else:
+            parser.error("unsupported command")
+            return
+    except (KeyError, ValueError, RuntimeError, RpcError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        code = 2
+    except KeyboardInterrupt:
+        print("cancelled", file=sys.stderr)
+        code = 130
+    finally:
+        if parent_watch_stop is not None:
+            parent_watch_stop.set()
+        if parent_watch_thread is not None:
+            parent_watch_thread.join(timeout=0.2)
+        signal.signal(signal.SIGTERM, previous_sigterm)
+    if args.session_id and args.command != "session":
+        try:
+            node = getattr(args, "node", None)
+            if not isinstance(node, str):
+                node = (
+                    getattr(args, "name", None)
+                    if args.command == "node"
+                    else None
+                )
+            environment = getattr(args, "environment", None)
+            if not isinstance(environment, str):
+                environment = (
+                    getattr(args, "name", None)
+                    if args.command == "env"
+                    else None
+                )
+            workspace = (
+                getattr(args, "name", None)
+                if args.command == "workspace"
+                else None
+            )
+            CliOperationLogger(args.session_id).record(
+                argv=_replay_argv(sys.argv[1:]),
+                command=_operation_name(args),
+                node=node if isinstance(node, str) else None,
+                environment=(
+                    environment if isinstance(environment, str) else None
+                ),
+                workspace=workspace if isinstance(workspace, str) else None,
+                intent=intent,
+                exit_code=code,
+                elapsed_ms=monotonic_ms(started),
+            )
+        except (OSError, ValueError) as exc:
+            print(
+                f"warning: CLI operation log was not written: {exc}",
+                file=sys.stderr,
+            )
+    raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()