refactor(podman): trim OCI workdir change set

Drop image-volume admission (split to a follow-up), the Docker and core
mount-validation refactor, redundant per-arm Podman mount checks, and
unrelated doc and test churn. Keep image VOLUME masking validation for
custom workdirs.

Signed-off-by: Matthew Grossman <mgrossman@nvidia.com>

Author: matthewgrossman

architecture/compute-runtimes.md

@@ -9,12 +9,10 @@ Podman provisions a paired workload and supervisor container using its native
 libpod API. The workload uses `network=none`; the external supervisor alone joins
 the configured network. A per-sandbox named volume carries their mutually
 authenticated gRPC Unix socket, with supervisor credentials kept in its separate
-filesystem. The supervisor and final sandbox runtime run as the resolved non-root
-identity with all capabilities dropped. Only the managed `/sandbox` fallback uses
-a trusted root bootstrap to prepare its driver-owned workspace before dropping
-irreversibly to that identity. The containers do not share PID, mount, or network
-namespaces. Podman owns paired lifecycle and health; the common protocol owns
-process, identity, TCP, DNS, and forwarding semantics.
+filesystem. Both containers run as the resolved non-root identity with all
+capabilities dropped. They share only a user namespace for volume ownership,
+not PID, mount, or network namespaces. Podman owns paired lifecycle and health;
+the common protocol owns process, identity, TCP, DNS, and forwarding semantics.
 
 ## Driver Contract
 
@@ -307,7 +305,7 @@ delete, reconciliation removes the row; otherwise it can remain `Deleting`.
 | Runtime | Best fit | Sandbox boundary | Notes |
 |---|---|---|---|
 | Docker | Local development with Docker available. | Capability-free workload container. | Uses `network_mode=none`; a separate capability-free supervisor container mediates egress and access over a private daemon-local Unix socket volume. |
-| Podman | Local development with Podman available. | Capability-free workload container. | Uses `network=none`; a separate capability-free supervisor container mediates egress and access over a private Unix socket volume. |
+| Podman | Existing rootless driver. | Container. | Not converted by this isolation stack. |
 | Kubernetes | Cluster deployment through Helm. | Capability-free sandbox Pod. | Always creates a namespace-wide empty-egress workload NetworkPolicy and a separate capability-free supervisor Pod over mutually authenticated TLS. It requires an enforcing CNI and trusted sandbox namespace; the Kubernetes API does not attest policy enforcement. |
 | VM | Experimental microVM isolation. | Per-sandbox libkrun or QEMU VM. | The NIC-less guest runs `openshell-sandbox` as PID 1; host `openshell-supervisor` owns gateway networking and reaches the guest over vsock. |
 | Extension | Out-of-tree drivers operated alongside the gateway. | Whatever boundary the driver implements. | Selected by a custom `compute_drivers = ["<name>"]` entry with `[openshell.drivers.<name>].socket_path`, or at launch time by pairing `--drivers <name>` with `--compute-driver-socket=<path>`. A launch-time endpoint may use a canonical built-in name to preserve its driver-config key while replacing in-process construction. The gateway connects to an operator-provisioned UDS, snapshots `GetCapabilities`, and dispatches all sandbox lifecycle calls through `compute_driver.proto`. The driver process and socket lifecycle are operator-owned; the gateway does not spawn, supervise, or remove unmanaged extension drivers. The trust boundary is the socket's filesystem permissions: the operator must ensure only the gateway uid can read/write it. |
@@ -392,7 +390,7 @@ Drivers deliver the two binaries to separate trust domains:
 | Runtime | Delivery model |
 |---|---|
 | Docker | A digest-pinned daemon-local volume supplies `openshell-sandbox`; the companion image runs `openshell-supervisor`. |
-| Podman | The driver pins `sandbox_runtime_image` and `supervisor_image` to image IDs. The former supplies `openshell-sandbox`; the latter is passed as the companion container's image and runs `openshell-supervisor`. |
+| Podman | Existing driver behavior; not converted by this stack. |
 | Kubernetes | A non-root init container stages `openshell-sandbox` into a memory volume; a directly managed Pod runs `openshell-supervisor`. |
 | VM | `openshell-sandbox` is embedded in the guest rootfs; a separately digest-checked native `openshell-supervisor` runs on the host. |
 | Extension | Defined by the out-of-tree driver. |
@@ -408,33 +406,24 @@ The gateway preserves whether each policy process field was omitted and passes
 the admitted selectors to the driver. The driver resolves one exact UID, GID,
 and supplementary-group set before creating the immutable workload:
 
-- Docker pins the image ID, resolves policy selectors against the image's
-  `/etc/passwd` and `/etc/group`, and validates its OCI working directory.
-- Podman pins the image ID, resolves policy selectors against the image's
-  `/etc/passwd` and `/etc/group`, and validates its OCI working directory.
+- Docker and Podman pin the image ID, resolve policy selectors against the
+  image's `/etc/passwd` and `/etc/group`, and validate its OCI working
+  directory.
 - Kubernetes uses platform-resolved numeric values, including OpenShift
   namespace ranges.
 - VM uses the configured numeric guest identity.
 
-UID/GID zero and `u32::MAX` are invalid. Agent commands run as the resolved
-non-root user. For Podman's managed `/sandbox` workspace, trusted setup briefly
-starts as root to prepare the workspace, then switches to that user before
-reading bootstrap material or accepting commands. Identity-changing policy
-updates require sandbox recreation, while other policy updates remain live.
-
-Docker uses an absolute OCI working directory as the workspace. Empty, root,
-and explicit `/sandbox` values select `/sandbox`; other paths must already
-exist without symlink or reserved-mount collisions and must be usable by the
-resolved identity.
-
-Podman reads the image user and working directory from one pinned image. Empty,
-`/`, and explicit `/sandbox` values use the managed `/sandbox` workspace. A
-custom path must be absolute, normalized, and outside system and OpenShell
-reserved paths. Image and driver mounts cannot cover the workspace. Custom
-paths use the image's container filesystem directly; the final non-root user
-must be able to write the existing directory. The managed `/sandbox` fallback
-uses a driver-owned workspace volume.
-Kubernetes and VM use `/sandbox`.
+UID/GID zero and `u32::MAX` are invalid. The sandbox and every child start with
+the resolved identity and zero capability masks; neither process performs an
+in-workload UID transition. Identity-changing policy updates require sandbox
+recreation, while other policy updates remain live.
+
+Docker and Podman use an absolute OCI working directory as the workspace.
+Empty, root, and explicit `/sandbox` values select `/sandbox`; other paths must
+already exist without symlink or reserved-mount collisions and must be usable
+by the resolved identity. Podman keeps a custom workspace in the container
+filesystem and uses a driver-owned volume only for `/sandbox`. Kubernetes and
+VM use `/sandbox`.
 
 ### Executable Identity Binding
 

crates/openshell-core/src/driver_mounts.rs

@@ -98,18 +98,6 @@ pub fn validate_container_mount_target(target: &str) -> Result<(), String> {
     Ok(())
 }
 
-/// Validate a mount target against shared and driver-specific control paths.
-pub fn validate_container_mount_target_with_control_paths(
-    target: &str,
-    control_paths: &[&str],
-) -> Result<(), String> {
-    validate_container_mount_target(target)?;
-    for control_path in control_paths {
-        validate_mount_control_path(target, control_path)?;
-    }
-    Ok(())
-}
-
 /// Resolve an OCI image working directory to the internal workspace root used
 /// by local container drivers.
 ///
@@ -372,27 +360,6 @@ mod tests {
         validate_mount_control_path("/custom-other", "/custom/ssh.sock").unwrap();
     }
 
-    #[test]
-    fn container_target_checks_shared_and_driver_control_paths() {
-        let control_paths = &["/.openshell/channel"];
-        assert!(
-            validate_container_mount_target_with_control_paths(
-                "/etc/openshell/tls/client",
-                control_paths,
-            )
-            .is_err()
-        );
-        assert!(
-            validate_container_mount_target_with_control_paths(
-                "/.openshell/channel/sandbox",
-                control_paths,
-            )
-            .is_err()
-        );
-        validate_container_mount_target_with_control_paths("/workspace/cache", control_paths)
-            .unwrap();
-    }
-
     #[test]
     fn workspace_rejects_malformed_runtime_control_paths() {
         for control_path in [

crates/openshell-core/src/resource_admission.rs

@@ -93,7 +93,6 @@ impl std::str::FromStr for DriverAdmissionConfig {
 /// Reserved driver-owned runtime metadata; caller labels must never override it.
 pub const CONFIG_USED_LABEL: &str = "openshell.ai/caller-driver-config-used";
 pub const IDENTITIES_LABEL: &str = "openshell.ai/resource-admission-identities";
-pub const PRIVATE_IMAGE_VOLUME_TARGETS_LABEL: &str = "openshell.ai/private-image-volume-targets";
 
 pub fn check_config_provenance(allowed: bool, recorded: Option<&str>) -> Result<(), tonic::Status> {
     match recorded {

crates/openshell-driver-docker/src/lib.rs

@@ -1215,7 +1215,7 @@ impl DockerComputeDriver {
             .ok_or_else(|| Status::failed_precondition("sandbox lacks resource identity record"))?;
         let mut actual = std::collections::BTreeMap::new();
         let anonymous_targets: Vec<String> = labels
-            .get(openshell_core::resource_admission::PRIVATE_IMAGE_VOLUME_TARGETS_LABEL)
+            .get("openshell.ai/private-image-volume-targets")
             .and_then(|value| serde_json::from_str(value).ok())
             .unwrap_or_default();
         for mount in container.mounts.as_deref().unwrap_or_default() {
@@ -5657,11 +5657,7 @@ fn build_container_create_body_for_image(
     driver_mounts::validate_workspace_control_path(&workspace_root, BOUNDARY_MOUNT_PATH)
         .map_err(Status::failed_precondition)?;
     for volume in &image.volumes {
-        driver_mounts::validate_container_mount_target_with_control_paths(
-            volume,
-            &[BOUNDARY_MOUNT_PATH],
-        )
-        .map_err(|error| {
+        driver_mounts::validate_container_mount_target(volume).map_err(|error| {
             Status::failed_precondition(format!(
                 "invalid image-declared volume '{volume}': {error}"
             ))
@@ -5671,6 +5667,8 @@ fn build_container_create_body_for_image(
                 "image-declared volume '{volume}' masks OCI WorkingDir '{workspace_root}' before workspace validation"
             ))
         })?;
+        driver_mounts::validate_mount_control_path(volume, BOUNDARY_MOUNT_PATH)
+            .map_err(Status::failed_precondition)?;
     }
     for mount in &driver_config.mounts {
         let target = match mount {
@@ -5681,11 +5679,8 @@ fn build_container_create_body_for_image(
         };
         driver_mounts::validate_workspace_mount_target(target, &workspace_root)
             .map_err(Status::failed_precondition)?;
-        driver_mounts::validate_container_mount_target_with_control_paths(
-            target,
-            &[BOUNDARY_MOUNT_PATH],
-        )
-        .map_err(Status::failed_precondition)?;
+        driver_mounts::validate_mount_control_path(target, BOUNDARY_MOUNT_PATH)
+            .map_err(Status::failed_precondition)?;
     }
     let mut user_mounts = docker_driver_mounts(driver_config)?;
     user_mounts.push(Mount {
@@ -5709,7 +5704,7 @@ fn build_container_create_body_for_image(
     });
     let mut labels = template.labels.clone();
     labels.insert(
-        openshell_core::resource_admission::PRIVATE_IMAGE_VOLUME_TARGETS_LABEL.into(),
+        "openshell.ai/private-image-volume-targets".into(),
         serde_json::to_string(&image.volumes)
             .map_err(|error| Status::internal(error.to_string()))?,
     );

crates/openshell-driver-podman/README.md

@@ -37,12 +37,13 @@ The supervisor joins the workload's **user namespace only** to preserve UID/GID
 mapping for shared-volume access. PID, mount, and network namespaces remain
 separate. The channel volume uses shared SELinux relabeling (`:z`).
 
-Before starting either container, the driver uploads bootstrap files to the
-channel volume. For managed `/sandbox`, it also prepares the workspace volume;
-custom image workspaces need no upload. Restart restores only the channel
-bootstrap, preserving the workspace. The workload starts before the supervisor
-so its user namespace exists when the supervisor joins it; a stopped supervisor
-resolves that namespace again on its next start.
+Before starting either container, the driver uploads volume-relative archives
+directly to the channel and workspace volume destinations. A rootfs upload on a
+stopped Podman container does not populate nested named volumes. Restart restores
+only the channel bootstrap into the existing channel volume, preserving the
+workspace. The workload starts before the supervisor so its user namespace exists
+when the supervisor joins it; a stopped supervisor resolves that namespace again
+on its next start. Custom image workspaces have no workspace volume or upload.
 
 The runtime must pass the sandbox's unprivileged enforcement probe, including
 nested seccomp notification and Landlock. Unsupported runtime defaults fail
@@ -92,22 +93,16 @@ environment belong to agent children, never the supervisor process.
 ## OCI working directory
 
 OpenShell reads `WORKDIR` from the workload image. If it is unset, `/`, or
-`/sandbox`, OpenShell uses its managed `/sandbox` workspace. A custom path must
-be absolute, with no `.` or `..` segments. It cannot overlap `/proc`, `/sys`,
+`/sandbox`, OpenShell uses its managed `/sandbox` workspace volume. A custom
+path must be absolute and normalized, and cannot overlap `/proc`, `/sys`,
 `/dev`, OpenShell-reserved paths, or the workload's private control and CA
-mounts. For a custom path, image volumes and driver mounts cannot cover the
-workspace or one of its parents; mounts nested below it remain valid. Podman
-creates a private volume for each image-declared path nested below it.
+mounts. Image volumes and driver mounts cannot cover it; mounts nested below it
+remain valid.
 
-For a custom path, Podman uses the image's container filesystem directly.
-OpenShell keeps the image directory's ownership and permissions, starts as the
-final non-root user, and rejects the image if that user cannot reach and write
-the directory. Agent commands use the path as their working directory;
-`filesystem.include_workdir` grants access to it when enabled.
-
-For `/sandbox`, OpenShell creates a workspace volume and prepares it before
-switching to the non-root user. The separate supervisor receives the path but
-does not mount the workspace.
+A custom path stays in the image's container filesystem with its ownership and
+permissions. The workload starts as the final non-root user, which must be able
+to reach and write the directory. Agent commands use the path as their working
+directory.
 
 ## Lifecycle and readiness
 
@@ -135,8 +130,8 @@ User `bind`, `volume`, `tmpfs`, and `image` mounts and CDI GPU selection remain
 native Podman features and apply only to the workload. Bind mounts require the
 operator's `enable_bind_mounts` opt-in and disabled label admission. Supplemental
 image mounts also require disabled admission. Driver JSON requires
-`allow_driver_config = true`. The workload's private mounts cannot be
-replaced. User-owned volumes are never created or deleted.
+`allow_driver_config = true`. Reserved control paths and the workspace
+root cannot be replaced. User-owned volumes are never created or deleted.
 
 See [gateway configuration](../../docs/how-it-works/gateways/configuration.mdx) for
 operator settings and [NETWORKING.md](NETWORKING.md) for supervisor networking.