langbot-plugin 0.7.14__tar.gz → 0.7.16__tar.gz

langbot_plugin-0.7.16/.github/workflows/box-docker.yml

@@ -0,0 +1,34 @@
+name: Box Docker Acceptance
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  box-docker:
+    name: Real Docker socket mounts
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Build acceptance image
+        run: |
+          docker build -f tests/e2e/Dockerfile.box-socket \
+            -t langbot-box-socket-test .
+          docker pull alpine:3.21
+      - name: Verify private tmp and shared artifact cache
+        shell: bash
+        run: |
+          shared_root=$(mktemp -d "${RUNNER_TEMP}/box-socket.XXXXXX")
+          docker run --rm --init --name langbot-box-socket-test \
+            --volume /var/run/docker.sock:/var/run/docker.sock \
+            --volume "$shared_root:$shared_root" \
+            --env LANGBOT_TEST_BOX_SHARED_ROOT="$shared_root" \
+            langbot-box-socket-test

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/ARCHITECTURE.md

@@ -458,7 +458,10 @@ values. Ordinary fixed mounts include `content_digest` and `manifest_path` in
 the session signature; supported digest-addressed packages are excluded from it.
 Digest-addressed packages use the reserved
 `/opt/langbot-artifacts/<digest>` namespace. Docker/Podman pre-mount a read-only
-cache and atomically populate verified revisions before execution. E2B seals and
+cache and atomically populate verified revisions before execution. Caches live
+under the configured `box.local.host_root`, outside the default writable Workspace,
+and are removed with their session. Containerized Box must share this root at the
+same absolute path as the host daemon. E2B seals and
 verifies packages before publishing stable digest projections. These packages can
 be added after a Box is acquired, without replacing the session. nsjail applies
 all mounts independently per execution. Fixed ordinary host mounts still reject

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langbot-plugin
-Version: 0.7.14
+Version: 0.7.16
 Summary: This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins
 Project-URL: Homepage, https://langbot.app
 Project-URL: Repository, https://github.com/langbot-app/langbot-plugin-sdk

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.7.14"
+version = "0.7.16"
 description = "This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins"
 readme = "README.md"
 authors = [

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/src/langbot_plugin/api/agent_tools/asset_gateway.py

@@ -37,6 +37,8 @@ LANGBOT_AGENT_GATEWAY_INSTRUCTIONS = (
     "when reply permission is available."
 )
 DEFAULT_RUN_TOKEN_TTL_SECONDS = 3600.0
+MAX_HTTP_MCP_BODY_BYTES = 1024 * 1024
+_HTTP_BODY_TOO_LARGE = object()
 
 
 class _GatewayMCPResolver:
@@ -137,6 +139,12 @@ class AgentAssetGateway:
         self._thread: threading.Thread | None = None
         self._registrations: dict[str, AgentAssetGatewayRegistration] = {}
         self._lock = threading.RLock()
+        self._active_handlers = 0
+
+    @property
+    def active_handler_count(self) -> int:
+        with self._lock:
+            return self._active_handlers
 
     @property
     def endpoint(self) -> str:
@@ -156,6 +164,19 @@ class AgentAssetGateway:
         gateway = self
 
         class Handler(BaseHTTPRequestHandler):
+            def setup(self) -> None:
+                super().setup()
+                self.connection.settimeout(gateway.request_timeout)
+                with gateway._lock:
+                    gateway._active_handlers += 1
+
+            def finish(self) -> None:
+                try:
+                    super().finish()
+                finally:
+                    with gateway._lock:
+                        gateway._active_handlers -= 1
+
             def log_message(self, _format: str, *_args: typing.Any) -> None:
                 return
 
@@ -170,7 +191,13 @@ class AgentAssetGateway:
                     self.send_error(404)
                     return
 
-                payload = self._read_json_payload()
+                try:
+                    payload = self._read_json_payload()
+                except OSError:
+                    self.close_connection = True
+                    return
+                if payload is _HTTP_BODY_TOO_LARGE:
+                    return
                 if isinstance(payload, Exception):
                     self._write_json(
                         400, {"ok": False, "error": f"invalid JSON: {payload}"}
@@ -190,6 +217,12 @@ class AgentAssetGateway:
                     return
                 self._write_json(200, result)
 
+            def handle_one_request(self) -> None:
+                try:
+                    super().handle_one_request()
+                except (TimeoutError, OSError):
+                    self.close_connection = True
+
             def do_DELETE(self) -> None:
                 if self.path not in {"/mcp", "/mcp/http"}:
                     self.send_error(404)
@@ -216,10 +249,18 @@ class AgentAssetGateway:
                 try:
                     length = int(self.headers.get("Content-Length", "0"))
                 except ValueError:
-                    length = 0
+                    return ValueError("invalid Content-Length")
+                if length < 0:
+                    return ValueError("invalid Content-Length")
+                if length > MAX_HTTP_MCP_BODY_BYTES:
+                    self._write_empty(413)
+                    self.close_connection = True
+                    return _HTTP_BODY_TOO_LARGE
                 try:
                     body = self.rfile.read(length).decode("utf-8")
                     return json.loads(body) if body else {}
+                except TimeoutError:
+                    raise
                 except Exception as e:
                     return e
 

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/src/langbot_plugin/box/backend.py

@@ -169,6 +169,7 @@ class CLISandboxBackend(BaseSandboxBackend):
         self.command = command
         self.name = backend_name
         self.cpu_limit_enabled = True
+        self.artifact_cache_parent: str | None = None
         self._artifact_roots: dict[str, str] = {}
 
     async def is_available(self) -> bool:
@@ -224,7 +225,13 @@ class CLISandboxBackend(BaseSandboxBackend):
             )
             args.extend(["-v", mount_spec])
 
-        artifact_root = tempfile.mkdtemp(prefix="langbot-box-artifacts-")
+        # Bind sources are resolved by the daemon, not this process. When a
+        # shared host root is configured, the cache must live there as well.
+        if self.artifact_cache_parent is not None:
+            os.makedirs(self.artifact_cache_parent, exist_ok=True)
+        artifact_root = tempfile.mkdtemp(
+            prefix="langbot-box-artifacts-", dir=self.artifact_cache_parent
+        )
         os.chmod(artifact_root, 0o755)
         self._artifact_roots[container_name] = artifact_root
         args.extend(["-v", f"{artifact_root}:{ARTIFACT_MOUNT_ROOT}:ro"])

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/src/langbot_plugin/box/host_backend.py

@@ -329,21 +329,25 @@ class HostProcessBackend(BaseSandboxBackend):
             stderr=asyncio.subprocess.PIPE,
             start_new_session=True,
         )
-        stdout_task = asyncio.create_task(self._read_stream(process.stdout))
-        stderr_task = asyncio.create_task(self._read_stream(process.stderr))
+        completion = asyncio.gather(
+            process.wait(),
+            self._read_stream(process.stdout),
+            self._read_stream(process.stderr),
+        )
         timed_out = False
         try:
-            await asyncio.wait_for(process.wait(), timeout=timeout_sec)
+            # Descendants can keep output pipes open after the shell exits.
+            # Keep readers alive during cleanup to preserve captured output.
+            await asyncio.wait_for(asyncio.shield(completion), timeout=timeout_sec)
         except asyncio.TimeoutError:
             timed_out = True
             await self._terminate_process_group(process)
         except asyncio.CancelledError:
             await self._terminate_process_group(process)
-            await asyncio.gather(stdout_task, stderr_task, return_exceptions=True)
+            await completion
             raise
 
-        stdout_bytes, stdout_total = await stdout_task
-        stderr_bytes, stderr_total = await stderr_task
+        _, (stdout_bytes, stdout_total), (stderr_bytes, stderr_total) = await completion
         return _CommandResult(
             return_code=process.returncode if process.returncode is not None else -1,
             stdout=self._clip_captured_bytes(stdout_bytes, stdout_total),
@@ -357,20 +361,22 @@ class HostProcessBackend(BaseSandboxBackend):
         *,
         timeout_sec: float = 2.0,
     ) -> None:
-        if process.returncode is not None:
-            return
+        """Terminate the isolated group even if its shell has already exited."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout_sec
         try:
             os.killpg(process.pid, signal.SIGTERM)
+            # A shell exit does not mean descendants exited or closed their pipes.
+            while True:
+                os.killpg(process.pid, 0)
+                remaining = deadline - loop.time()
+                if remaining <= 0:
+                    break
+                await asyncio.sleep(min(0.05, remaining))
+            os.killpg(process.pid, signal.SIGKILL)
         except ProcessLookupError:
             pass
-        try:
-            await asyncio.wait_for(process.wait(), timeout=timeout_sec)
-        except asyncio.TimeoutError:
-            try:
-                os.killpg(process.pid, signal.SIGKILL)
-            except ProcessLookupError:
-                pass
-            await process.wait()
+        await process.wait()
 
     @staticmethod
     def _preview(command: str) -> str:

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/src/langbot_plugin/box/runtime.py

@@ -22,7 +22,7 @@ import pydantic
 from langbot_plugin.entities.io.context import ActionContext
 from langbot_plugin.runtime.event_loop_monitor import EventLoopLagMonitor
 
-from .backend import BaseSandboxBackend, DockerBackend
+from .backend import BaseSandboxBackend, CLISandboxBackend, DockerBackend
 from .host_backend import HostProcessBackend
 from .nsjail_backend import NsjailBackend
 from .errors import (
@@ -1220,6 +1220,8 @@ done
         for backend in self.backends:
             if backend is None:
                 continue
+            if isinstance(backend, CLISandboxBackend):
+                backend.artifact_cache_parent = self._host_root()
             backend_config = config.get(backend.name, {})
             if backend_config and hasattr(backend, "configure"):
                 backend.configure(backend_config)

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/src/langbot_plugin/runtime/plugin/mgr.py

@@ -41,6 +41,7 @@ from langbot_plugin.runtime import bounded_executor
 from langbot_plugin.runtime import ops_metrics as ops_metrics_module
 from langbot_plugin.api.entities.context import EventContext
 from langbot_plugin.api.definition.components.manifest import ComponentManifest
+from langbot_plugin.api.definition.components.common.event_listener import EventListener
 from langbot_plugin.api.definition.components.tool.tool import Tool
 from langbot_plugin.api.definition.components.command.command import Command
 from langbot_plugin.api.definition.components.knowledge_engine.engine import (
@@ -3194,6 +3195,12 @@ class PluginManager:
                 if plugin_id not in include_plugins:
                     continue
 
+            if not any(
+                component.manifest.kind == EventListener.__kind__
+                for component in plugin.components
+            ):
+                continue
+
             reply_message_chain_before = _dump_reply_message_chain(event_context)
             trusted_query_id = event_context.query_id
             trusted_query_uuid = event_context.query_uuid

langbot_plugin-0.7.16/src/langbot_plugin/version.py

@@ -0,0 +1 @@
+__version__ = "0.7.16"

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/tests/api/test_agent_tools_mcp_bridge.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import http.client
 import json
 import os
 import time
@@ -765,6 +766,44 @@ def test_asset_gateway_cleans_expired_registrations() -> None:
     asyncio.run(run_probe())
 
 
+def test_asset_gateway_http_rejects_oversized_and_times_out_slow_requests() -> None:
+    async def run_probe() -> None:
+        gateway = AgentAssetGateway(request_timeout=0.1)
+        registration = gateway.register_run(
+            FakeRunAPI(), _authorized_ctx(), token="bounded-token"
+        )
+        try:
+            assert gateway._server is not None
+            port = gateway._server.server_address[1]
+            connection = http.client.HTTPConnection("127.0.0.1", port, timeout=1)
+            try:
+                connection.putrequest("POST", "/mcp")
+                connection.putheader("Content-Length", str(1024 * 1024 + 1))
+                connection.endheaders()
+                assert connection.getresponse().status == 413
+            finally:
+                connection.close()
+
+            connection = http.client.HTTPConnection("127.0.0.1", port, timeout=1)
+            try:
+                connection.putrequest("POST", "/mcp")
+                connection.putheader("Content-Length", "100")
+                connection.endheaders()
+                connection.send(b"{")
+                with pytest.raises(http.client.RemoteDisconnected):
+                    connection.getresponse()
+            finally:
+                connection.close()
+
+            await asyncio.sleep(0.05)
+            assert gateway.active_handler_count == 0
+        finally:
+            registration.stop()
+            gateway.stop()
+
+    asyncio.run(run_probe())
+
+
 def test_daemon_config_and_mcp_payload_edges(monkeypatch) -> None:
     monkeypatch.setenv("LANGBOT_AGENT_RUNTIME_DAEMON_ENABLED", "true")
     monkeypatch.setenv("LANGBOT_AGENT_RUNTIME_DAEMON_HOST", "0.0.0.0")

langbot_plugin-0.7.16/tests/box/test_artifact_cache_root.py

@@ -0,0 +1,91 @@
+"""Docker/Podman bind sources must use the configured daemon-visible root."""
+
+import logging
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from langbot_plugin.box.backend import CLISandboxBackend, _CommandResult
+from langbot_plugin.box.errors import BoxError
+from langbot_plugin.box.models import ARTIFACT_MOUNT_ROOT, BoxSpec
+from langbot_plugin.box.runtime import BoxRuntime
+
+
+def configured_backend(tmp_path, monkeypatch, name):
+    monkeypatch.delenv("LANGBOT_BOX_CONFIG", raising=False)
+    logger = logging.getLogger(__name__)
+    backend = CLISandboxBackend(logger, name, name)
+    runtime = BoxRuntime(logger, backends=[backend])
+    # Relative host roots use the runtime's working directory, not the workspace.
+    monkeypatch.chdir(tmp_path)
+    runtime.init({"local": {"host_root": "shared", "default_workspace": "default"}})
+    return backend
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("name", ["docker", "podman"])
+@pytest.mark.parametrize("mode", ["rw", "ro", "none"])
+async def test_cache_mount_uses_shared_root_without_packages(
+    tmp_path, monkeypatch, name, mode
+):
+    backend = configured_backend(tmp_path, monkeypatch, name)
+    private_tmp = tmp_path / "container-private-tmp"
+    private_tmp.mkdir()
+    monkeypatch.setattr("tempfile.tempdir", str(private_tmp))
+    workspace = tmp_path / "shared" / "default"
+    command = mock.AsyncMock(return_value=_CommandResult(0, "", ""))
+    with mock.patch.object(backend, "_run_command", command):
+        first = await backend.start_session(
+            BoxSpec(session_id="first", host_path=str(workspace), host_path_mode=mode)
+        )
+        second = await backend.start_session(BoxSpec(session_id="second"))
+        roots = [Path(root) for root in backend._artifact_roots.values()]
+        assert len(set(roots)) == 2
+        assert all(
+            root.parent == tmp_path / "shared" and root.is_dir() for root in roots
+        )
+        assert not list(private_tmp.iterdir())
+        assert not list(workspace.iterdir())
+        for call, root in zip(command.call_args_list, roots):
+            args = call.args[0]
+            assert f"{root}:{ARTIFACT_MOUNT_ROOT}:ro" in args
+        await backend.stop_session(first)
+        assert not roots[0].exists() and roots[1].is_dir()
+        await backend.stop_session(second)
+    assert not backend._artifact_roots
+    assert not any(root.exists() for root in roots)
+
+
+@pytest.mark.asyncio
+async def test_failed_creation_cleans_shared_cache(tmp_path, monkeypatch):
+    backend = configured_backend(tmp_path, monkeypatch, "docker")
+    roots = []
+
+    async def run(args, **kwargs):
+        if args[1] == "run":
+            roots.extend(Path(root) for root in backend._artifact_roots.values())
+            assert roots[0].is_dir()
+            raise BoxError("creation failed")
+        return _CommandResult(0, "", "")
+
+    with mock.patch.object(backend, "_run_command", side_effect=run):
+        with pytest.raises(BoxError, match="creation failed"):
+            await backend.start_session(BoxSpec(session_id="failed"))
+    assert roots and not any(root.exists() for root in roots)
+    assert not backend._artifact_roots
+
+
+@pytest.mark.asyncio
+async def test_unusable_shared_root_does_not_retry_in_private_tmp(
+    tmp_path, monkeypatch
+):
+    backend = configured_backend(tmp_path, monkeypatch, "docker")
+    backend.artifact_cache_parent = str(tmp_path / "file")
+    Path(backend.artifact_cache_parent).write_text("not a directory")
+    command = mock.AsyncMock()
+    with mock.patch.object(backend, "_run_command", command):
+        with pytest.raises(FileExistsError):
+            await backend.start_session(BoxSpec(session_id="invalid"))
+    command.assert_not_called()
+    assert not backend._artifact_roots

{langbot_plugin-0.7.14 → langbot_plugin-0.7.16}/tests/box/test_host_backend.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import asyncio
 import logging
 import os
+import shlex
+import signal
 
 import pytest
 
@@ -209,3 +211,81 @@ async def test_host_backend_reports_no_isolation(backend):
     assert readiness["mount_isolation"] is False
     assert readiness["network_isolation"] is False
     assert readiness["cgroup_v2"] is False
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("trigger", ["timeout", "cancel"])
+@pytest.mark.parametrize("topology", ["closed_output", "exited_parent"])
+async def test_host_backend_kills_sigterm_resistant_descendants(
+    backend, tmp_path, trigger, topology
+):
+    child_script = (
+        "trap '' TERM\n"
+        + ("exec >/dev/null 2>&1\n" if topology == "closed_output" else "")
+        + 'printf %s "$$" > child.pid\nexec sleep 30'
+    )
+    command = (
+        "printf before-timeout; printf before-timeout-error >&2\n"
+        + 'printf %s "$$" > parent.pid\n'
+        + f"sh -c {shlex.quote(child_script)} &\n"
+        + "while [ ! -s child.pid ]; do sleep 0.01; done\n"
+        + ("exit 0" if topology == "exited_parent" else "wait")
+    )
+    spec = _spec(tmp_path, cmd=command, timeout_sec=1 if trigger == "timeout" else 30)
+    session = await backend.start_session(spec)
+    task = asyncio.create_task(backend.exec(session, spec))
+    parent_pid = None
+    try:
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + 5
+        pid_file = tmp_path / "child.pid"
+        while not pid_file.exists() or not pid_file.read_text().strip():
+            assert loop.time() < deadline, "child did not become ready"
+            await asyncio.sleep(0.01)
+        child_pid = int(pid_file.read_text())
+        parent_pid = int((tmp_path / "parent.pid").read_text())
+        assert os.getpgid(child_pid) == parent_pid
+
+        # Exercise cancellation only after the parent has already been reaped.
+        if topology == "exited_parent":
+            while True:
+                try:
+                    os.kill(parent_pid, 0)
+                except ProcessLookupError:
+                    break
+                assert loop.time() < deadline, "parent shell did not exit"
+                await asyncio.sleep(0.01)
+
+        if trigger == "cancel":
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await asyncio.wait_for(asyncio.shield(task), timeout=6)
+        else:
+            result = await asyncio.wait_for(asyncio.shield(task), timeout=6)
+            assert result.status == BoxExecutionStatus.TIMED_OUT
+            assert result.stdout == "before-timeout"
+            assert result.stderr == "before-timeout-error"
+
+        deadline = loop.time() + 1
+        while True:
+            try:
+                os.kill(child_pid, 0)
+            except ProcessLookupError:
+                break
+            assert loop.time() < deadline, "SIGTERM-resistant child survived cleanup"
+            await asyncio.sleep(0.01)
+    finally:
+        # A failing regression must not leave a live descendant in the runner.
+        if parent_pid is None:
+            pid_file = tmp_path / "parent.pid"
+            if pid_file.exists() and pid_file.read_text().strip():
+                parent_pid = int(pid_file.read_text())
+        if parent_pid is not None:
+            try:
+                os.killpg(parent_pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+        if not task.done():
+            task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+        await backend.stop_session(session)

langbot_plugin-0.7.16/tests/e2e/Dockerfile.box-socket

@@ -0,0 +1,8 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends docker.io && rm -rf /var/lib/apt/lists/*
+WORKDIR /sdk
+COPY pyproject.toml README.md ./
+COPY src ./src
+COPY tests/e2e/test_box_socket_mounts.py ./tests/e2e/test_box_socket_mounts.py
+RUN uv sync --dev
+CMD ["uv", "run", "--no-sync", "pytest", "-q", "tests/e2e/test_box_socket_mounts.py"]

langbot_plugin-0.7.16/tests/e2e/Dockerfile.box-socket.dockerignore

@@ -0,0 +1,10 @@
+**
+!pyproject.toml
+!README.md
+!src/
+!src/**
+!tests/
+!tests/e2e/
+!tests/e2e/test_box_socket_mounts.py
+**/__pycache__/
+**/*.pyc

langbot_plugin-0.7.16/tests/e2e/test_box_socket_mounts.py

@@ -0,0 +1,125 @@
+"""Run inside a container with only Docker socket and same-path host_root binds.
+
+Set LANGBOT_TEST_BOX_SHARED_ROOT to that shared root to enable this acceptance
+test. The runtime's private /tmp is deliberately not shared with the daemon.
+
+Manual acceptance on a disposable Docker host, from the repository root::
+
+    docker build -f tests/e2e/Dockerfile.box-socket -t langbot-box-socket-test .
+    docker pull alpine:3.21
+    shared_root=$(mktemp -d)
+    docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+        -v "$shared_root:$shared_root" \
+        -e LANGBOT_TEST_BOX_SHARED_ROOT="$shared_root" langbot-box-socket-test
+"""
+
+import asyncio
+import json
+import logging
+import os
+from pathlib import Path
+import tempfile
+
+import pytest
+
+from langbot_plugin.artifact import build_tree_manifest
+from langbot_plugin.box.backend import DockerBackend
+from langbot_plugin.box.models import ARTIFACT_MOUNT_ROOT, BoxMountSpec, BoxSpec
+from langbot_plugin.box.runtime import BoxRuntime
+
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("LANGBOT_TEST_BOX_SHARED_ROOT"),
+    reason="requires a container with host Docker socket and same-path shared root",
+)
+
+
+def test_private_tmp_and_shared_root_with_real_docker():
+    assert Path("/.dockerenv").exists(), "Run this test inside the Box container"
+    root = Path(os.environ["LANGBOT_TEST_BOX_SHARED_ROOT"])
+    root.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(dir=root, prefix="socket-test-") as shared:
+        asyncio.run(_exercise(Path(shared)))
+
+
+async def _exercise(shared):
+    logger = logging.getLogger(__name__)
+    backend = DockerBackend(logger)
+    runtime = BoxRuntime(logger, backends=[backend])
+    runtime.init(
+        {
+            "backend": "docker",
+            "local": {"host_root": str(shared)},
+            "docker": {"cpu_limit_enabled": False},
+        }
+    )
+    image = os.environ.get("LANGBOT_TEST_BOX_IMAGE", "alpine:3.21")
+    empty = BoxSpec(
+        session_id="socket-mounts",
+        image=image,
+        cmd="printf ready",
+        network="off",
+        host_path=str(shared / "workspace"),
+    )
+    cache = None
+    try:
+        # Creating a Box with no packages must still work with a private /tmp.
+        result = await runtime.execute(empty)
+        assert result.ok and result.stdout == "ready", result.stderr
+        session = runtime.get_sessions()[0]
+        backend_id = session["backend_session_id"]
+        cache = Path(backend._artifact_roots[backend_id])
+        assert cache.parent == shared and cache.is_dir()
+        inspection = await backend._run_command(
+            ["docker", "inspect", backend_id], timeout_sec=10, check=True
+        )
+        container = json.loads(inspection.stdout)[0]
+        assert container["HostConfig"]["ReadonlyRootfs"]
+        mounts = container["Mounts"]
+        workspace_mount = next(m for m in mounts if m["Destination"] == "/workspace")
+        assert workspace_mount["Source"] == empty.host_path and workspace_mount["RW"]
+        artifact_mount = next(
+            m for m in mounts if m["Destination"] == ARTIFACT_MOUNT_ROOT
+        )
+        assert artifact_mount["Source"] == str(cache) and not artifact_mount["RW"]
+
+        # Packages prepared in private /tmp are copied into the shared cache;
+        # adding one must preserve the already-created sandbox and its state.
+        state = await runtime.execute(
+            empty.model_copy(update={"cmd": "printf kept >/tmp/state"})
+        )
+        assert state.ok, state.stderr
+        with tempfile.TemporaryDirectory() as private:
+            package = Path(private) / "package"
+            package.mkdir()
+            (package / "value").write_text("package")
+            digest, manifest = build_tree_manifest(
+                str(package), max_files=10, max_total_bytes=1024
+            )
+            manifest_path = Path(private) / "manifest.json"
+            manifest_path.write_text(json.dumps(manifest))
+            mount = BoxMountSpec(
+                host_path=str(package),
+                mount_path=f"{ARTIFACT_MOUNT_ROOT}/{digest[7:]}",
+                mode="ro",
+                content_digest=digest,
+                manifest_path=str(manifest_path),
+            )
+            mounted = empty.model_copy(
+                update={
+                    "extra_mounts": [mount],
+                    "cmd": f"cat {mount.mount_path}/value /tmp/state",
+                }
+            )
+            result = await runtime.execute(mounted)
+            assert result.ok and result.stdout == "packagekept", result.stderr
+            assert runtime.get_sessions()[0]["backend_session_id"] == backend_id
+            denied = await runtime.execute(
+                mounted.model_copy(
+                    update={"cmd": f"printf changed >{mount.mount_path}/value"}
+                )
+            )
+            assert not denied.ok
+            assert (package / "value").read_text() == "package"
+    finally:
+        await runtime.shutdown()
+    assert cache is not None and not cache.exists()