From 4de9de7d7d5ff8246a2663f894be42d6a6e5e676 Mon Sep 17 00:00:00 2001
From: John Myers <9696606+johntmyers@users.noreply.github.com>
Date: Thu, 17 Sep 2026 10:52:11 -0700
Subject: [PATCH] fix(dev): extract Docker sandbox runtime from sandbox image

Signed-off-by: John Myers <9696606+johntmyers@users.noreply.github.com>
---
 architecture/gateway.md                 | 4 ++++
 skills/debug-openshell-cluster/SKILL.md | 1 +
 tasks/scripts/gateway-docker.sh         | 4 ++--
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/architecture/gateway.md b/architecture/gateway.md
index 62eceed3eb..622b7b048e 100644
--- a/architecture/gateway.md
+++ b/architecture/gateway.md
@@ -37,6 +37,10 @@ immediately without a grace period. Finalization is persisted separately from
 the exit result; the gateway deletes an ephemeral sandbox only after the
 finalized supervisor session disconnects.
 
+Local Docker development builds the supervisor image separately from the
+`openshell-sandbox` workload runtime. Cross-platform runtime extraction uses
+the sandbox image, which exports `/openshell-sandbox`.
+
 ## Configuration Boundary
 
 The gateway accepts exactly schema version 2. Missing, legacy, and future
diff --git a/skills/debug-openshell-cluster/SKILL.md b/skills/debug-openshell-cluster/SKILL.md
index a6b54ec677..190f1aef63 100644
--- a/skills/debug-openshell-cluster/SKILL.md
+++ b/skills/debug-openshell-cluster/SKILL.md
@@ -240,6 +240,7 @@ Common findings:
 - Sandbox fails before readiness with an OCI workspace validation error: inspect the image's `WorkingDir` using the immutable image ID reported by the gateway. Empty, `/`, and explicit `/sandbox` use the managed `/sandbox` compatibility workspace. Any other workdir must be an absolute normalized directory with no symlink components; the final policy UID, primary GID, and supplementary groups must pass the kernel's effective traverse/write checks, including POSIX ACL and LSM decisions. OpenShell does not create, chown, or chmod a non-default image workdir.
 - Docker also rejects an image `VOLUME` that covers the workdir or one of its parents because the runtime would mask the immutable path before validation. Move the `VOLUME` below the workspace or remove the declaration.
 - A workdir rejected as a special filesystem or OpenShell control-path collision cannot be made valid with permissions. Move the image workdir away from kernel-backed mounts and the concrete supervisor, TLS, token, runtime, and socket paths named in the error.
+- Local Docker gateway setup cannot copy `openshell-sandbox` after exporting a supervisor image: the sandbox runtime and supervisor are separate artifacts. The runtime image must provide `/openshell-sandbox`; the supervisor image provides `/openshell-supervisor`.
 - Docker driver cannot initialize because it cannot find `openshell-sandbox`: verify the sibling binary next to `openshell-gateway`, or that the configured `sandbox_runtime_image` contains `/openshell-sandbox`.
 - Sandbox never registers: check gateway logs and supervisor callback endpoint.
 - Calls to an external tool server fail while the sandbox is Ready: inspect `Tool server connections` in `openshell sandbox get <name>`. For configured MCP-over-HTTP endpoints, JSON output exposes each address together with `last_result` and `last_reported_at` in `endpoint_statuses`. Select the endpoint by host, path, and ports, then check the reported failure boundary. `last_reported_at` records gateway acceptance time and can advance when retained evidence is accepted after a reset. Results do not expire or prove current availability; `HttpResponseReceived` can still contain a tool error. If several paths share a host and port, a failure before the path is known remains in logs. Verify the actual operation when current tool availability matters.
diff --git a/tasks/scripts/gateway-docker.sh b/tasks/scripts/gateway-docker.sh
index 0b3edca729..112319cca5 100644
--- a/tasks/scripts/gateway-docker.sh
+++ b/tasks/scripts/gateway-docker.sh
@@ -194,7 +194,7 @@ if [[ "${HOST_OS}" == "Linux" && "${HOST_ARCH}" == "${DAEMON_ARCH}" ]]; then
     "${ROOT}/target/${SUPERVISOR_TARGET}/debug/openshell-sandbox"
 else
   # Cross-compile through the prebuilt-binary staging helper, then use the
-  # supervisor stage to extract just the openshell-sandbox binary.
+  # sandbox stage to extract just the openshell-sandbox binary.
   #
   # This task is gated on a working Docker daemon above, so pin the
   # container-engine helper to docker — otherwise it auto-detects podman
@@ -204,7 +204,7 @@ else
   if ! CONTAINER_ENGINE=docker \
     DOCKER_PLATFORM="linux/${DAEMON_ARCH}" \
     DOCKER_OUTPUT="type=local,dest=${SUPERVISOR_BUILD_DIR}" \
-      bash "${ROOT}/tasks/scripts/docker-build-image.sh" supervisor-output; then
+      bash "${ROOT}/tasks/scripts/docker-build-image.sh" sandbox; then
     rm -rf -- "${SUPERVISOR_BUILD_DIR}"
     exit 1
   fi