feat(sandbox): reserve namespaces for supervisor control state

[matthewgrossman]

Problem Statement

OpenShell currently protects a concrete list of in-container supervisor paths from OCI WorkingDir, image VOLUME, and driver-config mount overlap. This is a reasonable fail-closed starting point, but a per-file registry can drift when privileged supervisor state gains a new path. A missed path could let a workload-writable workspace or mount overlap state later trusted by the root supervisor.

The long-term boundary should not depend on guessing every sensitive Linux path. OpenShell needs a stable rule for where its own privileged control state may live, while separately handling kernel filesystems and explicitly untrusted image inputs.

This was identified while reviewing the Docker OCI workdir support in #2530, which currently uses OPENSHELL_CONTROL_PATHS and a separately validated runtime-configured SSH socket.

Proposed Design

Define and document an in-container filesystem contract with three classes:

1. OpenShell-owned privileged state must live beneath a small set of reserved namespaces:
   • /run/openshell for sockets, credentials, TLS material, and mutable runtime state.
   • /opt/openshell for the supervisor executable and immutable packaged assets.
2. Kernel interfaces such as /proc, /sys, and /dev are identified from filesystem metadata rather than a distro-path denylist. Keep /run/netns as a narrowly documented exception until network namespace handling can use an OpenShell-owned location or file descriptors exclusively.
3. Image-provided files such as /etc/passwd, /etc/group, /etc/hosts, and system CA bundles remain explicitly untrusted inputs. Privileged code should parse or snapshot required data before the workload starts and must not use workload-mutable image files as control state.

Workspace and mount validation should reject both ancestor and descendant overlap with the reserved namespaces and documented exceptions. Shared tests should prove that every OpenShell-generated container mount target and privileged runtime path falls within an approved namespace or exception.

Migrate existing container control resources under /etc/openshell and /etc/openshell-tls to /run/openshell where practical. Preserve /opt/openshell for executable content because /run may be volatile or mounted noexec.

Alternatives Considered

• Keep a file-by-file protected-path registry. This is simple but retains the drift risk.
• Derive protection only from generated container mounts. This catches mount collisions automatically but misses supervisor-created or otherwise accessed control paths, so it is useful only as defense-in-depth.
• Deny broad Linux system trees such as /etc, /usr, and /var. This is brittle, rejects legitimate application workdirs, and still cannot prove that every privileged dependency was covered.
• Move everything under /run/openshell. The supervisor executable is better kept under /opt/openshell, and Linux kernel interfaces cannot be relocated without deeper runtime changes.

Agent Investigation

• crates/openshell-core/src/driver_mounts.rs currently centralizes concrete supervisor, TLS, token, proxy-auth, Kubernetes TLS, and /run/netns collision paths.
• Docker validates OCI workdirs, image-declared volumes, and user mount targets with component-aware ancestor/descendant checks. Its configured SSH socket is validated separately against the workspace.
• Current OpenShell-owned paths span /opt/openshell, /etc/openshell, /etc/openshell-tls, /run/openshell, and /run/openshell-sidecar.
• The process and network supervisors necessarily access kernel interfaces under /proc, /sys, and /dev and currently use the conventional /var/run/netns namespace location.
• The supervisor also reads bounded image inputs including account files, hosts data, and CA bundles; those reads need an explicit untrusted-input contract rather than inclusion in the control-state namespace.
• Searches for existing issues about reserved supervisor namespaces and control-path/workdir collisions did not find a duplicate.

Definition of Done

• The reserved-namespace and untrusted-image-input invariants are documented in the sandbox architecture.
• OpenShell-owned privileged container state is under approved reserved namespaces, with documented exceptions.
• Workspace, image-volume, and driver-mount collision validation uses the namespace contract.
• Tests inventory generated control targets and fail when a target falls outside the contract.
• Existing /etc/openshell* container paths are migrated or explicitly tracked for staged migration.
• /run/netns is either eliminated through a namespace-handling refactor or retained as a documented kernel/runtime exception.