feat(sandbox): honor OCI image working directories

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -149,6 +149,8 @@ Common findings:
 - Gateway process stopped: inspect exit status and logs.
 - Sandbox image missing or pull denied: verify image reference and registry credentials.
 - Sandbox fails before readiness with an identity-resolution error: inspect the image's OCI `USER` and matching `/etc/passwd` and `/etc/group` entries, or explicitly set both process identity fields in policy. Root and missing identities are rejected.
+- 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, or supplementary groups must already be able to traverse every parent and write and enter the directory. OpenShell does not create, chown, or chmod a non-default image workdir.
+- 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.
 - Docker driver cannot initialize because it cannot find `openshell-sandbox`: verify `OPENSHELL_DOCKER_SUPERVISOR_BIN`, the sibling binary next to `openshell-gateway`, or the configured supervisor image contains `/openshell-sandbox`.
 - Sandbox never registers: check gateway logs and supervisor callback endpoint.
 - Supervisor image exits before printing `openshell-sandbox --version`: the image should be the scratch supervisor image from `deploy/docker/Dockerfile.supervisor` and must contain a static executable at `/openshell-sandbox`.
@@ -175,6 +177,8 @@ Common findings:
 - Rootless networking unavailable: inspect Podman network configuration.
 - Sandbox image missing or pull denied: verify image reference and registry credentials.
 - Sandbox fails before readiness with an identity-resolution error: inspect the image's OCI `USER` and matching `/etc/passwd` and `/etc/group` entries, or explicitly set both process identity fields in policy. Root and missing identities are rejected.
+- 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, or supplementary groups must already be able to traverse every parent and write and enter the directory. Podman checks the original image in a networkless temporary probe before attaching the workspace volume, so inspect the probe failure in gateway logs.
+- If Podman reports probe cleanup or timeout failures, inspect temporary containers with `podman ps -a --filter name=workdir-probe` and gateway logs. The driver force-removes the probe on every normal success or failure path.
 - Supervisor cannot call back: check callback endpoint and gateway logs.
 
 ### Step 6: Check Kubernetes Helm Gateways

.agents/skills/generate-sandbox-policy/SKILL.md

@@ -466,7 +466,6 @@ filesystem_policy:
     - /etc
     - /var/log
   read_write:
-    - /sandbox
     - /tmp
     - /dev/null
 

.agents/skills/generate-sandbox-policy/examples.md

@@ -823,7 +823,6 @@ filesystem_policy:
     - /etc
     - /var/log
   read_write:
-    - /sandbox
     - /tmp
     - /dev/null
 

.agents/skills/openshell-cli/SKILL.md

@@ -220,17 +220,23 @@ openshell sandbox ssh-config my-sandbox >> ~/.ssh/config
 ### Upload and download files
 
 ```bash
-# Upload local files to sandbox
-openshell sandbox upload my-sandbox ./src /sandbox/src
+# Upload local files to the sandbox working directory
+openshell sandbox upload my-sandbox ./src
 
-# Download files from sandbox
-openshell sandbox download my-sandbox /sandbox/output ./local-output
+# Download a path relative to the sandbox working directory
+openshell sandbox download my-sandbox output ./local-output
 ```
 
 Uploads honor `.gitignore` by default. Add `--no-git-ignore` only when ignored files are intentionally in scope.
 
 Uploads preserve symlinks, including dangling symlinks, instead of dereferencing their targets. A symlink source bypasses Git-aware filtering so the link itself is archived.
 
+When the upload destination is omitted, the CLI discovers the remote working
+directory. Uploading a named directory merges it into an existing directory of
+the same name, overwriting matching entries without deleting unrelated entries.
+Downloads accept paths relative to that working directory or absolute paths
+within it.
+
 ### Execute a non-interactive command
 
 ```bash

.agents/skills/openshell-cli/cli-reference.md

@@ -258,11 +258,11 @@ Open an interactive SSH shell. The name defaults to the last-used sandbox. `--ed
 
 ### `openshell sandbox upload <name> <path> [dest]`
 
-Upload files using tar-over-SSH. The destination defaults to the container working directory. `.gitignore` filtering is enabled unless `--no-git-ignore` is passed.
+Upload files using tar-over-SSH. The CLI discovers the canonical remote working directory when the destination is omitted. A named directory merges into an existing directory of the same name, overwriting matching entries without deleting unrelated entries. `.gitignore` filtering is enabled unless `--no-git-ignore` is passed.
 
 ### `openshell sandbox download <name> <path> [dest]`
 
-Download files using tar-over-SSH. The local destination defaults to `.`.
+Download files using tar-over-SSH. The sandbox source may be relative to the canonical remote working directory or an absolute path within it. The local destination defaults to `.`.
 
 ### `openshell sandbox ssh-config [name]`
 

.github/workflows/e2e-test.yml

@@ -131,10 +131,10 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          # Ubuntu 24.04 matches the environment reported in #2069 and ships
-          # Podman 4.x. The probe records whether AppArmor blocks the drop.
+          # Ubuntu 24.04 matches the AppArmor environment reported in #2069.
+          # GitHub's runner image now supplies the supported Podman 5.x line.
           - runner: ubuntu-24.04
-            podman_major: "4"
+            podman_major: "5"
           # Ubuntu 26.04 provides the supported Podman 5.x coverage for
           # comparison with the Ubuntu 24.04 environment.
           - runner: ubuntu-26.04

architecture/compute-runtimes.md

@@ -185,7 +185,8 @@ The gateway preserves whether each policy process field was omitted. The active
 driver then supplies one authoritative identity input to the supervisor:
 
 - Docker and Podman inspect the final sandbox image, pin container creation to
-  its immutable image ID, and pass its raw OCI `Config.User`.
+  its immutable image ID, and pass its raw OCI `Config.User`. They also resolve
+  the workspace from OCI `Config.WorkingDir` during that inspection.
 - Kubernetes passes its platform-resolved numeric UID/GID, including OpenShift
   SCC-derived values.
 - VM keeps its existing guest identity behavior.
@@ -198,6 +199,27 @@ and uses the same privilege-drop path for direct and SSH children. When a
 declaration omits the group, the supervisor fills it with the user's numeric
 primary GID. It does not rewrite the account files.
 
+Docker and Podman use an absolute OCI working directory as the workspace. An
+empty, root (`/`), or explicit `/sandbox` declaration uses `/sandbox`, which
+OpenShell creates and owns as a compatibility workspace. Any other workdir must already
+exist in the immutable image without symlink components. The completed
+identity, including supplementary groups, must already be able to traverse
+every parent and write and enter the workdir; OpenShell does not change that
+directory's ownership or mode. Filesystem metadata identifies kernel-managed
+mounts, while collision checks are derived from actual OpenShell control paths.
+Docker performs the check in the final container before workload launch.
+Podman performs it in a minimal networkless container from the same pinned
+image ID before its managed workspace volume covers the path. The probe retains
+only the capabilities needed to adopt the completed process identity, drops to
+that identity, and asks the kernel to validate access. It emits a normalized
+identity attestation that the final supervisor must match, including when the
+image supplies the default process policy. The driver captures a bounded,
+sanitized diagnostic before removing a failed probe. The resolved workspace is
+the child cwd and `HOME`; when `filesystem.include_workdir` is enabled, it
+becomes the automatic writable policy path. Kubernetes/OpenShift keep their
+`/sandbox` PVC and `fsGroup` behavior, and VM keeps its `/sandbox` guest
+initialization path.
+
 Sandbox creation fails before the workload becomes ready when a required image
 identity is absent, malformed, unknown, ambiguous, or resolves to UID/GID 0.
 The supervisor itself remains root so it can establish isolation before