pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/sandbox/remote/server.py

@@ -0,0 +1,984 @@
+"""Remote Sandbox Server.
+
+Exposes the RemoteWorker over an authenticated WebSocket protocol.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+import binascii
+import datetime
+import hmac
+import http
+import io
+import json
+import logging
+import os
+import re
+import shutil
+import sqlite3
+import tarfile
+from contextlib import suppress
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+import websockets
+
+from pulse import __version__
+from pulse.production import is_secure_remote_token
+from pulse.sandbox.errors import SandboxSecurityError
+from pulse.sandbox.remote.models import (
+    SubmitExecutionRequest,
+    SubmitExecutionResponse,
+    validate_execution_id,
+)
+from pulse.sandbox.remote.worker import RemoteWorker
+from pulse.storage import migrate_database
+
+REMOTE_EXECUTION_SCHEMA_VERSION = 2
+
+logger = logging.getLogger(__name__)
+
+MAX_ARTIFACT_COMPRESSED_BYTES = 32 * 1024 * 1024
+MAX_ARTIFACT_UNPACKED_BYTES = 512 * 1024 * 1024
+MAX_ARTIFACT_MEMBERS = 10_000
+_SAFE_REQUEST_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+
+
+def _request_id(value: object) -> str | None:
+    return value if isinstance(value, str) and _SAFE_REQUEST_ID.fullmatch(value) else None
+
+
+def _extract_remote_artifact(data: bytes, workspace: Path) -> None:
+    """Extract a bounded regular-file archive into a new workspace."""
+    if len(data) > MAX_ARTIFACT_COMPRESSED_BYTES:
+        raise SandboxSecurityError("Remote artifact exceeds the compressed size limit")
+    if workspace.exists():
+        raise SandboxSecurityError("Remote artifact workspace already exists")
+    workspace.mkdir(parents=True, exist_ok=False)
+    try:
+        with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as archive:
+            members = archive.getmembers()
+            if len(members) > MAX_ARTIFACT_MEMBERS:
+                raise SandboxSecurityError("Remote artifact contains too many members")
+            total_size = 0
+            root = workspace.resolve()
+            for member in members:
+                normalized = PurePosixPath(member.name.replace("\\", "/"))
+                if (
+                    normalized.is_absolute()
+                    or ".." in normalized.parts
+                    or member.issym()
+                    or member.islnk()
+                    or not (member.isfile() or member.isdir())
+                ):
+                    raise SandboxSecurityError("Unsafe remote artifact member")
+                target = (root / Path(*normalized.parts)).resolve()
+                try:
+                    target.relative_to(root)
+                except ValueError as error:
+                    raise SandboxSecurityError("Remote artifact path traversal detected") from error
+                if member.isfile():
+                    total_size += member.size
+                    if total_size > MAX_ARTIFACT_UNPACKED_BYTES:
+                        raise SandboxSecurityError("Remote artifact exceeds the unpacked size limit")
+            if hasattr(tarfile, "data_filter"):
+                archive.extractall(path=root, filter="data")
+            else:  # pragma: no cover - compatibility for early Python 3.11
+                archive.extractall(path=root)
+    except Exception:
+        shutil.rmtree(workspace, ignore_errors=True)
+        raise
+
+
+def _append_log_entry(path: Path, entry: str) -> None:
+    """Append a stream entry off the event loop."""
+    with path.open("a", encoding="utf-8") as stream_log:
+        stream_log.write(entry)
+
+
+def _read_log_entries(path: Path) -> list[str]:
+    """Read complete historical stream entries off the event loop."""
+    with path.open("r", encoding="utf-8") as stream_log:
+        return [line.strip() for line in stream_log if line.strip()]
+
+
+class RemoteExecutionStore:
+    def __init__(self, db_path: Path):
+        self.db_path = db_path.resolve()
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._ensure_schema()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path, timeout=10.0)
+        conn.execute("PRAGMA journal_mode=WAL")
+        return conn
+
+    def _ensure_schema(self) -> None:
+        def migration(conn: sqlite3.Connection, _current: int) -> None:
+            conn.execute("""CREATE TABLE IF NOT EXISTS executions (
+                    execution_id TEXT PRIMARY KEY,
+                    tenant_id TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    correlation_id TEXT,
+                    result_json TEXT,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )""")
+            columns = {
+                row[1] for row in conn.execute("PRAGMA table_info(executions)").fetchall()
+            }
+            if "correlation_id" not in columns:
+                conn.execute("ALTER TABLE executions ADD COLUMN correlation_id TEXT")
+
+        migrate_database(self.db_path, REMOTE_EXECUTION_SCHEMA_VERSION, migration)
+
+    def create(
+        self,
+        execution_id: str,
+        tenant_id: str,
+        correlation_id: str | None = None,
+    ) -> None:
+        now = datetime.datetime.now(datetime.UTC).isoformat()
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO executions (execution_id, tenant_id, status, correlation_id, created_at, updated_at) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (execution_id, tenant_id, "RUNNING", correlation_id, now, now),
+            )
+
+    def update(
+        self, execution_id: str, status: str, result_json: dict[str, Any] | None = None
+    ) -> None:
+        now = datetime.datetime.now(datetime.UTC).isoformat()
+        with self._connect() as conn:
+            if result_json:
+                conn.execute(
+                    "UPDATE executions SET status = ?, result_json = ?, updated_at = ? WHERE execution_id = ?",
+                    (status, json.dumps(result_json), now, execution_id),
+                )
+            else:
+                conn.execute(
+                    "UPDATE executions SET status = ?, updated_at = ? WHERE execution_id = ?",
+                    (status, now, execution_id),
+                )
+
+    def get(self, execution_id: str, tenant_id: str) -> dict[str, Any] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT status, result_json, created_at, updated_at, correlation_id FROM executions WHERE execution_id = ? AND tenant_id = ?",
+                (execution_id, tenant_id),
+            ).fetchone()
+            if not row:
+                return None
+            return {
+                "status": row[0],
+                "result": json.loads(row[1]) if row[1] else None,
+                "created_at": row[2],
+                "updated_at": row[3],
+                "correlation_id": row[4],
+            }
+
+    def exists(self, execution_id: str) -> bool:
+        with self._connect() as conn:
+            return conn.execute(
+                "SELECT 1 FROM executions WHERE execution_id = ?", (execution_id,)
+            ).fetchone() is not None
+
+    def cleanup_old(self, max_age_hours: int = 1) -> list[tuple[str, str]]:
+        threshold = (
+            datetime.datetime.now(datetime.UTC)
+            - datetime.timedelta(hours=max_age_hours)
+        ).isoformat()
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT execution_id, tenant_id FROM executions WHERE status IN ('COMPLETED', 'FAILED') AND updated_at < ?",
+                (threshold,),
+            ).fetchall()
+            for row in rows:
+                conn.execute("DELETE FROM executions WHERE execution_id = ?", (row[0],))
+            return rows
+
+    def mark_interrupted_running_unknown(self) -> int:
+        """Quarantine executions left RUNNING by a server restart.
+
+        A fresh server process has no proof that the old container completed
+        or that its side effects were not applied.  Reporting UNKNOWN makes
+        callers reconcile deliberately instead of replaying the command.
+        """
+        now = datetime.datetime.now(datetime.UTC).isoformat()
+        with self._connect() as conn:
+            cursor = conn.execute(
+                "UPDATE executions SET status = 'UNKNOWN', updated_at = ? WHERE status = 'RUNNING'",
+                (now,),
+            )
+            return cursor.rowcount
+
+
+class RemoteServer:
+    """Provides the network boundary for the remote worker."""
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 8080,
+        auth_token: str | None = None,
+        max_concurrent_executions: int = 10,
+        workspace_root: Path | None = None,
+        database_path: Path | None = None,
+        retention_hours: int = 24,
+        production_mode: bool = False,
+    ) -> None:
+        self.host = host
+        self.port = port
+        # Support multiple tokens via comma-separated string if provided
+        if not auth_token:
+            raise ValueError(
+                "PULSE_REMOTE_TOKEN must be configured; insecure default tokens are disabled."
+            )
+        self.valid_tokens = {token.strip() for token in auth_token.split(",") if token.strip()}
+        if production_mode and any(
+            not is_secure_remote_token(token) for token in self.valid_tokens
+        ):
+            raise ValueError(
+                "Every production PULSE_REMOTE_TOKEN must be random, non-placeholder, "
+                "and at least 32 characters."
+            )
+        if not self.valid_tokens:
+            raise ValueError("PULSE_REMOTE_TOKEN does not contain a usable token.")
+        if not 1 <= max_concurrent_executions <= 128:
+            raise ValueError("max_concurrent_executions must be between 1 and 128.")
+        if not 1 <= retention_hours <= 8760:
+            raise ValueError("retention_hours must be between 1 and 8760.")
+        self.max_concurrent_executions = max_concurrent_executions
+        self.retention_hours = retention_hours
+        self.worker = RemoteWorker(workspace_root)
+        self.store = RemoteExecutionStore(
+            database_path or Path(".remote_sandbox.db")
+        )
+        self._ready = False
+        self._ready_event = asyncio.Event()
+        self._active_executions: dict[str, asyncio.Task[Any]] = {}
+        # Track tenant for each execution
+        self._execution_tenants: dict[str, str] = {}
+        # Track attached clients per execution
+        self._attached_websockets: dict[
+            str, set[websockets.WebSocketServerProtocol]
+        ] = {}
+
+    async def _ttl_cleanup(self) -> None:
+        while True:
+            await asyncio.sleep(300)
+            try:
+                old = self.store.cleanup_old(max_age_hours=self.retention_hours)
+                for eid, tid in old:
+                    self.worker.cleanup_workspace(tid, eid)
+            except (OSError, RuntimeError) as e:
+                logger.error(f"TTL cleanup failed: {e}")
+
+    async def _process_request(self, connection, request) -> Any | None:
+        from websockets.http11 import Response
+
+        """Enforce authenticated transport (R3)."""
+        if request.path in {"/healthz", "/readyz"}:
+            ready = request.path == "/healthz" or self._ready
+            status = http.HTTPStatus.OK if ready else http.HTTPStatus.SERVICE_UNAVAILABLE
+            body = json.dumps(
+                {"status": "ok" if ready else "not_ready"}, separators=(",", ":")
+            ).encode("utf-8")
+            return Response(status, status.phrase, websockets.Headers(), body)
+
+        auth_header = request.headers.get("Authorization")
+        if not auth_header or not auth_header.startswith("Bearer "):
+            return Response(
+                http.HTTPStatus.UNAUTHORIZED,
+                "Unauthorized",
+                websockets.Headers(),
+                b"Unauthorized",
+            )
+
+        token = auth_header.split(" ", 1)[1]
+        if not any(hmac.compare_digest(token, valid) for valid in self.valid_tokens):
+            logger.warning("Unauthorized remote sandbox connection attempt.")
+            return Response(
+                http.HTTPStatus.UNAUTHORIZED,
+                "Unauthorized",
+                websockets.Headers(),
+                b"Unauthorized",
+            )
+
+        return None
+
+    async def start(self) -> None:
+        """Start the WebSocket server."""
+        await self.worker.initialize()
+        interrupted = self.store.mark_interrupted_running_unknown()
+        if interrupted:
+            logger.warning(
+                "Marked %s interrupted remote executions as UNKNOWN.", interrupted
+            )
+
+        # Phase 3: TLS Enforcement
+        import os
+        import ssl
+
+        ssl_context = None
+
+        tls_cert = os.environ.get("PULSE_TLS_CERT")
+        tls_key = os.environ.get("PULSE_TLS_KEY")
+        tls_ca = os.environ.get("PULSE_TLS_CA")
+
+        if tls_cert and tls_key and tls_ca:
+            try:
+                ssl_context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+                ssl_context.load_cert_chain(certfile=tls_cert, keyfile=tls_key)
+                ssl_context.load_verify_locations(cafile=tls_ca)
+                ssl_context.verify_mode = ssl.CERT_REQUIRED
+            except (ssl.SSLError, OSError) as e:
+                raise RuntimeError(f"Failed to load mTLS certificates: {e}")
+        elif self.host in ("127.0.0.1", "localhost", "::1"):
+            logger.warning("Starting in insecure loopback mode without mTLS.")
+        else:
+            raise RuntimeError(
+                "mTLS certificates (PULSE_TLS_CERT, PULSE_TLS_KEY, PULSE_TLS_CA) "
+                "are strictly required for non-loopback connections."
+            )
+
+        cleanup_task = asyncio.create_task(self._ttl_cleanup())
+        try:
+            async with websockets.serve(
+                self._handle_client,
+                self.host,
+                self.port,
+                process_request=self._process_request,
+                ping_interval=20,
+                ping_timeout=20,
+                max_size=1024 * 1024 * 50,  # Enforce 50MB max payload size (R7)
+                ssl=ssl_context,
+            ) as websocket_server:
+                sockets = websocket_server.sockets
+                if sockets:
+                    self.port = int(sockets[0].getsockname()[1])
+                self._ready = True
+                self._ready_event.set()
+                scheme = "wss" if ssl_context else "ws"
+                logger.info(
+                    "Remote Sandbox Server listening on %s://%s:%s",
+                    scheme,
+                    self.host,
+                    self.port,
+                )
+                await asyncio.Future()  # run forever
+        finally:
+            self._ready = False
+            self._ready_event.clear()
+            cleanup_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await cleanup_task
+
+    async def wait_until_ready(self, timeout: float = 5.0) -> None:
+        """Wait until the listening socket is bound and accepting connections."""
+        await asyncio.wait_for(self._ready_event.wait(), timeout=timeout)
+
+    async def _handle_client(
+        self, websocket: websockets.WebSocketServerProtocol
+    ) -> None:
+        """Handle incoming client WebSocket connections."""
+
+        # Derive tenant_id from auth header
+        auth_header = websocket.request.headers.get("Authorization", "")
+        tenant_id = (
+            auth_header.split(" ")[1]
+            if auth_header.startswith("Bearer ")
+            else "unknown"
+        )
+        import hashlib
+
+        tenant_hash = hashlib.sha256(tenant_id.encode()).hexdigest()[:12]
+
+        async def run_execution(req: SubmitExecutionRequest, tenant_id: str) -> None:
+            """Background task for running the execution."""
+
+            async def scoped_send_output(stream: str, data: bytes) -> None:
+                log_entry = (
+                    json.dumps(
+                        {
+                            "type": "stream",
+                            "payload": {
+                                "execution_id": req.execution_id,
+                                "stream": stream,
+                                "data": data.decode("utf-8", errors="replace"),
+                            },
+                        }
+                    )
+                    + "\n"
+                )
+
+                log_file = (
+                    self.worker.workspace_base_path
+                    / tenant_id
+                    / req.execution_id
+                    / ".pulse_stream.log"
+                )
+                try:
+                    if log_file.parent.exists():
+                        await asyncio.to_thread(_append_log_entry, log_file, log_entry)
+                except OSError:
+                    logger.warning(
+                        "Unable to persist remote stream for %s.", req.execution_id
+                    )
+
+                attached = self._attached_websockets.get(req.execution_id, set())
+                dead_ws = set()
+                for ws in attached:
+                    try:
+                        await ws.send(log_entry)
+                    except websockets.exceptions.ConnectionClosed:
+                        dead_ws.add(ws)
+                for ws in dead_ws:
+                    attached.discard(ws)
+
+            try:
+                self.store.create(
+                    req.execution_id, tenant_id, correlation_id=req.correlation_id
+                )
+                result = await self.worker.execute_request(
+                    req, tenant_id=tenant_id, output_callback=scoped_send_output
+                )
+                self.store.update(req.execution_id, "COMPLETED", result.to_dict())
+
+                res_msg = json.dumps({"type": "result", "payload": result.to_dict()})
+                attached = self._attached_websockets.get(req.execution_id, set())
+                dead_ws = set()
+                for ws in attached:
+                    try:
+                        await ws.send(res_msg)
+                    except websockets.exceptions.ConnectionClosed:
+                        dead_ws.add(ws)
+                for ws in dead_ws:
+                    attached.discard(ws)
+            except (OSError, RuntimeError, sqlite3.Error):
+                logger.error("Remote execution failed with an internal error.")
+                err_msg = "Remote execution failed with an internal error."
+                from pulse.sandbox.process import ProcessResult
+
+                fallback_res = ProcessResult(
+                    command=req.command,
+                    exit_code=-1,
+                    stdout="",
+                    stderr=err_msg,
+                    duration_ms=0,
+                    timed_out=False,
+                    truncated=False,
+                    pid=None,
+                    overlay_path=None,
+                    termination_reason="error",
+                )
+                self.store.update(req.execution_id, "FAILED", fallback_res.to_dict())
+
+                err_json = json.dumps(
+                    {"type": "result", "payload": fallback_res.to_dict()}
+                )
+                attached = self._attached_websockets.get(req.execution_id, set())
+                dead_ws = set()
+                for ws in attached:
+                    try:
+                        await ws.send(err_json)
+                    except websockets.exceptions.ConnectionClosed:
+                        dead_ws.add(ws)
+                for ws in dead_ws:
+                    attached.discard(ws)
+            finally:
+                self._active_executions.pop(req.execution_id, None)
+                self._execution_tenants.pop(req.execution_id, None)
+                self._attached_websockets.pop(req.execution_id, None)
+
+        client_executions: set[str] = set()
+
+        try:
+            async for message in websocket:
+                request_id: str | None = None
+                try:
+                    data = json.loads(message)
+                    if not isinstance(data, dict):
+                        raise TypeError("message must be an object")
+                    action = data.get("action")
+                    payload = data.get("payload", {})
+                    if not isinstance(action, str) or not isinstance(payload, dict):
+                        raise TypeError("action and payload have invalid types")
+                    request_id = _request_id(payload.get("request_id"))
+
+                    if action == "submit":
+                        if (
+                            len(self._active_executions)
+                            >= self.max_concurrent_executions
+                        ):
+                            logger.warning(
+                                "Concurrency limit reached, rejecting execution."
+                            )
+                            await websocket.send(
+                                json.dumps(
+                                    {
+                                        "type": "error",
+                                        "payload": {
+                                            "message": "Server is at maximum capacity, please try again later.",
+                                            "request_id": request_id,
+                                        },
+                                    }
+                                )
+                            )
+                            continue
+
+                        req = SubmitExecutionRequest.from_dict(payload)
+                        if req.execution_id in self._active_executions or self.store.exists(
+                            req.execution_id
+                        ):
+                            raise ValueError("execution_id is already in use")
+                        # Acknowledge submission
+                        ack = SubmitExecutionResponse(
+                            execution_id=req.execution_id, status="STARTING"
+                        )
+                        ack_payload = ack.to_dict() | {"request_id": request_id}
+                        await websocket.send(
+                            json.dumps({"type": "response", "payload": ack_payload})
+                        )
+
+                        # Execute in background for streaming (R4)
+                        task = asyncio.create_task(run_execution(req, tenant_hash))
+                        self._active_executions[req.execution_id] = task
+                        self._execution_tenants[req.execution_id] = tenant_hash
+                        if req.execution_id not in self._attached_websockets:
+                            self._attached_websockets[req.execution_id] = set()
+                        self._attached_websockets[req.execution_id].add(websocket)
+                        client_executions.add(req.execution_id)
+
+                    elif action == "cancel":
+                        execution_id = validate_execution_id(payload.get("execution_id"))
+                        if execution_id:
+                            # Cross-tenant prevention
+                            if self._execution_tenants.get(execution_id) != tenant_hash:
+                                await websocket.send(
+                                    json.dumps(
+                                        {"type": "error", "payload": "Unauthorized"}
+                                    )
+                                )
+                                continue
+
+                            # Cancel the worker execution
+                            await self.worker.cancel(execution_id)
+                            # The task will complete or raise CancelledError
+                            task = self._active_executions.get(execution_id)
+                            if task and not task.done():
+                                task.cancel()
+
+                            # Update store explicitly
+                            self.store.update(
+                                execution_id, "FAILED", {"error": "CANCELLED"}
+                            )
+
+                            await websocket.send(
+                                json.dumps(
+                                    {
+                                        "type": "response",
+                                        "payload": {
+                                            "status": "CANCELLED",
+                                            "request_id": request_id,
+                                        },
+                                    }
+                                )
+                            )
+
+                    elif action == "upload_artifact":
+                        execution_id = validate_execution_id(payload.get("execution_id"))
+                        b64_data = payload.get("data")
+                        if execution_id and isinstance(b64_data, str) and b64_data:
+                            try:
+                                data = base64.b64decode(b64_data, validate=True)
+                                workspace = (
+                                    self.worker.workspace_base_path
+                                    / tenant_hash
+                                    / execution_id
+                                )
+                                _extract_remote_artifact(data, workspace)
+                                await websocket.send(
+                                    json.dumps(
+                                        {
+                                            "type": "response",
+                                            "payload": {
+                                                "status": "UPLOADED",
+                                                "request_id": request_id,
+                                            },
+                                        }
+                                    )
+                                )
+                            except (
+                                OSError,
+                                ValueError,
+                                RuntimeError,
+                                tarfile.TarError,
+                                binascii.Error,
+                            ):
+                                logger.error("Remote artifact upload was rejected.")
+                                await websocket.send(
+                                    json.dumps(
+                                        {
+                                            "type": "error",
+                                            "payload": {
+                                                "message": "Upload failed.",
+                                                "request_id": request_id,
+                                            },
+                                        }
+                                    )
+                                )
+
+                    elif action == "download_artifact":
+                        execution_id = validate_execution_id(payload.get("execution_id"))
+                        if execution_id:
+                            if not self.store.get(execution_id, tenant_hash):
+                                await websocket.send(
+                                    json.dumps(
+                                        {
+                                            "type": "error",
+                                            "payload": {
+                                                "message": "NOT_FOUND",
+                                                "request_id": request_id,
+                                            },
+                                        }
+                                    )
+                                )
+                                continue
+                            overlay_path = self.worker.get_overlay_path(execution_id)
+                            if not overlay_path or not overlay_path.exists():
+                                await websocket.send(
+                                    json.dumps(
+                                        {
+                                            "type": "response",
+                                            "payload": {
+                                                "status": "NO_ARTIFACT",
+                                                "request_id": request_id,
+                                            },
+                                        }
+                                    )
+                                )
+                            else:
+                                bio = io.BytesIO()
+                                with tarfile.open(fileobj=bio, mode="w:gz") as tar:
+                                    for item in overlay_path.iterdir():
+                                        tar.add(item, arcname=item.name)
+                                b64_out = base64.b64encode(bio.getvalue()).decode(
+                                    "ascii"
+                                )
+                                await websocket.send(
+                                    json.dumps(
+                                        {
+                                            "type": "response",
+                                            "payload": {
+                                                "status": "DOWNLOADED",
+                                                "data": b64_out,
+                                                "request_id": request_id,
+                                            },
+                                        }
+                                    )
+                                )
+                                # Cleanup overlay after download
+                                self.worker.cleanup_overlay(execution_id)
+
+                    elif action == "reconcile":
+                        # Clean up orphaned workspaces not matching active executions for this tenant
+                        orphans = 0
+                        tenant_workspace_path = (
+                            self.worker.workspace_base_path / tenant_hash
+                        )
+                        if tenant_workspace_path.exists():
+                            for ws in tenant_workspace_path.iterdir():
+                                if (
+                                    ws.is_dir()
+                                    and ws.name not in self._active_executions
+                                ):
+                                    self.worker.cleanup_workspace(tenant_hash, ws.name)
+                                    orphans += 1
+                        await websocket.send(
+                            json.dumps(
+                                {
+                                    "type": "response",
+                                    "payload": {
+                                        "status": "RECONCILED",
+                                        "orphans_cleaned": orphans,
+                                        "request_id": request_id,
+                                    },
+                                }
+                            )
+                        )
+
+                    elif action == "status":
+                        execution_id = validate_execution_id(payload.get("execution_id"))
+                        state = self.store.get(execution_id, tenant_hash)
+                        if not state:
+                            await websocket.send(
+                                json.dumps(
+                                    {
+                                        "type": "response",
+                                        "payload": {
+                                            "status": "NOT_FOUND",
+                                            "request_id": request_id,
+                                        },
+                                    }
+                                )
+                            )
+                        elif (
+                            state["status"] in {"COMPLETED", "FAILED"}
+                            and state["result"]
+                        ):
+                            await websocket.send(
+                                json.dumps(
+                                    {
+                                        "type": "response",
+                                        "payload": {
+                                            "status": state["status"],
+                                            "request_id": request_id,
+                                        },
+                                    }
+                                )
+                            )
+
+                    elif action == "attach":
+                        execution_id = validate_execution_id(payload.get("execution_id"))
+                        state = self.store.get(execution_id, tenant_hash)
+                        if not state:
+                            await websocket.send(
+                                json.dumps(
+                                    {
+                                        "type": "error",
+                                        "payload": {
+                                            "message": "NOT_FOUND",
+                                            "request_id": request_id,
+                                        },
+                                    }
+                                )
+                            )
+                            continue
+
+                        # Dump historical logs
+                        log_file = (
+                            self.worker.workspace_base_path
+                            / tenant_hash
+                            / execution_id
+                            / ".pulse_stream.log"
+                        )
+                        if log_file.exists():
+                            try:
+                                for line in await asyncio.to_thread(
+                                    _read_log_entries, log_file
+                                ):
+                                    await websocket.send(line)
+                            except OSError:
+                                logger.warning(
+                                    "Unable to read remote stream history for %s.",
+                                    execution_id,
+                                )
+
+                        if state["status"] == "RUNNING":
+                            if execution_id not in self._attached_websockets:
+                                self._attached_websockets[execution_id] = set()
+                            if (
+                                len(self._attached_websockets[execution_id]) > 0
+                                and websocket
+                                not in self._attached_websockets[execution_id]
+                            ):
+                                await websocket.send(
+                                    json.dumps(
+                                        {
+                                            "type": "error",
+                                            "payload": {
+                                                "message": "Another client is already attached",
+                                                "request_id": request_id,
+                                            },
+                                        }
+                                    )
+                                )
+                                continue
+
+                            self._attached_websockets[execution_id].add(websocket)
+                            client_executions.add(execution_id)
+                            await websocket.send(
+                                json.dumps(
+                                    {
+                                        "type": "response",
+                                        "payload": {
+                                            "status": "ATTACHED",
+                                            "request_id": request_id,
+                                        },
+                                    }
+                                )
+                            )
+                        elif (
+                            state["status"] in {"COMPLETED", "FAILED"}
+                            and state["result"]
+                        ):
+                            await websocket.send(
+                                json.dumps(
+                                    {
+                                        "type": "response",
+                                        "payload": {
+                                            "status": state["status"],
+                                            "request_id": request_id,
+                                        },
+                                    }
+                                )
+                            )
+                            await websocket.send(
+                                json.dumps(
+                                    {"type": "result", "payload": state["result"]}
+                                )
+                            )
+                        else:
+                            await websocket.send(
+                                json.dumps(
+                                    {
+                                        "type": "response",
+                                        "payload": {
+                                            "status": state["status"],
+                                            "request_id": request_id,
+                                        },
+                                    }
+                                )
+                            )
+
+                    else:
+                        await websocket.send(
+                            json.dumps(
+                                {
+                                    "type": "error",
+                                    "payload": {
+                                        "message": "Unknown action.",
+                                        "request_id": request_id,
+                                    },
+                                }
+                            )
+                        )
+
+                except (
+                    KeyError,
+                    ValueError,
+                    OSError,
+                    RuntimeError,
+                    TypeError,
+                    RecursionError,
+                ):
+                    logger.error("Rejected an invalid remote protocol message.")
+                    await websocket.send(
+                        json.dumps(
+                            {
+                                "type": "error",
+                                "payload": {
+                                    "message": "Invalid remote protocol request.",
+                                    "request_id": request_id,
+                                },
+                            }
+                        )
+                    )
+        except websockets.exceptions.ConnectionClosed:
+            logger.info("Client disconnected.")
+        finally:
+            # R5/GAP-07: Detach client but do NOT cancel execution
+            for eid in client_executions:
+                if eid in self._attached_websockets:
+                    self._attached_websockets[eid].discard(websocket)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="pulse-remote",
+        description="Run Pulse's authenticated remote sandbox worker.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("PULSE_REMOTE_HOST", "127.0.0.1"),
+        help="Bind host (default: PULSE_REMOTE_HOST or 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        default=os.environ.get("PULSE_REMOTE_PORT", "8080"),
+        type=int,
+        help="Bind port (default: PULSE_REMOTE_PORT or 8080).",
+    )
+    parser.add_argument(
+        "--workspace-root",
+        type=Path,
+        default=Path(
+            os.environ.get("PULSE_REMOTE_WORKSPACE_ROOT", ".pulse/remote-workspaces")
+        ),
+        help="Tenant workspace root (default: PULSE_REMOTE_WORKSPACE_ROOT).",
+    )
+    parser.add_argument(
+        "--database",
+        type=Path,
+        default=Path(
+            os.environ.get("PULSE_REMOTE_DB", ".pulse/remote-executions.sqlite3")
+        ),
+        help="Durable execution database (default: PULSE_REMOTE_DB).",
+    )
+    parser.add_argument(
+        "--max-concurrency",
+        type=int,
+        default=os.environ.get("PULSE_REMOTE_MAX_CONCURRENCY", "10"),
+        help="Maximum active executions (1-128).",
+    )
+    parser.add_argument(
+        "--retention-hours",
+        type=int,
+        default=os.environ.get("PULSE_REMOTE_RETENTION_HOURS", "24"),
+        help="Retention for terminal execution records (1-8760 hours).",
+    )
+    parser.add_argument(
+        "--development",
+        action="store_true",
+        help="Allow short development tokens; only appropriate on loopback.",
+    )
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO)
+    token = os.environ.get("PULSE_REMOTE_TOKEN")
+    if args.development and args.host not in {"127.0.0.1", "localhost", "::1"}:
+        parser.error("--development is restricted to a loopback host")
+    if not args.development:
+        if not args.workspace_root.is_absolute() or not args.database.is_absolute():
+            parser.error(
+                "production remote paths must be absolute; set "
+                "PULSE_REMOTE_WORKSPACE_ROOT and PULSE_REMOTE_DB"
+            )
+        if args.host not in {"127.0.0.1", "localhost", "::1"}:
+            for variable in ("PULSE_TLS_CERT", "PULSE_TLS_KEY", "PULSE_TLS_CA"):
+                value = os.environ.get(variable, "")
+                path = Path(value) if value else None
+                if not path or not path.is_absolute() or not path.is_file():
+                    parser.error(
+                        f"{variable} must reference an existing absolute file "
+                        "for a non-loopback worker"
+                    )
+    try:
+        server = RemoteServer(
+            host=args.host,
+            port=args.port,
+            auth_token=token,
+            max_concurrent_executions=args.max_concurrency,
+            workspace_root=args.workspace_root,
+            database_path=args.database,
+            retention_hours=args.retention_hours,
+            production_mode=not args.development,
+        )
+        asyncio.run(server.start())
+    except KeyboardInterrupt:
+        logger.info("Server shutting down.")
+    except (OSError, RuntimeError, ValueError):
+        print(
+            "pulse-remote failed to start. Check host, port, token, TLS, and storage settings."
+        )
+        raise SystemExit(1) from None
+
+
+if __name__ == "__main__":
+    main()