feat(sandbox): honor OCI image working directories

[matthewgrossman]

Summary

Docker and Podman now honor a usable OCI Config.WorkingDir as the sandbox workspace, with an OpenShell-created /sandbox fallback for empty or root declarations. The resolved workspace is used consistently by drivers, the supervisor, filesystem policy, SSH transfers, and editor launch while Kubernetes/OpenShift and VM retain /sandbox.

This is a stacked PR on top of #2509.

Related Issue

Closes #2526

Changes

• inspect WorkingDir with User from the same immutable Docker/Podman image and pass the resolved root through the existing supervisor workdir argument
• prepare and chown only the workspace root for the final local-container identity, without recursively changing image content or nested mounts
• mount Podman persistence at the resolved root and reserve that exact root from driver-config mounts
• use filesystem.include_workdir instead of automatically granting literal /sandbox
• discover the canonical remote workspace over SSH for upload defaults, download containment, and editor launch
• preserve fixed /sandbox behavior for Kubernetes/OpenShift and VM
• update architecture, driver, policy, CLI, and agent guidance

Testing

• mise run pre-commit passes
• mise run test passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)
• Docker custom_image E2E passes (OCI WorkingDir, fallback, direct/SSH, transfers)
• Docker driver_config_volume E2E passes (nested volume ownership)
• Podman inspect/spec/copy-up behavior covered by unit tests; live Podman was unavailable locally

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2530.docs.buildwithfern.com/openshell

[drew]

gator-agent

Blocked

Gator is blocked because PR #2530 currently has merge conflicts (mergeStateStatus: DIRTY) against its base branch.

Next action: @matthewgrossman, please rebase or merge the base branch and resolve the conflicts, then push an updated head SHA so gator can run the independent review.

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements linked issue #2526, which is already marked state:agent-ready / state:pr-opened, and the current head is open, ready for review, and no longer conflict-blocked.
Head SHA: 493abe06869d41a5b161a1a97abc21c0c3ce6436

Review findings:

• Warning: Docker/Podman pass the resolved workspace to the supervisor, but the create specs still appear to inherit the image process cwd. For hand-crafted OCI images where Config.WorkingDir is missing on disk or is not a directory, the container runtime may fail before the supervisor can run the intended workspace validation/preparation path. Please consider starting the supervisor from a known-safe cwd such as / while passing --workdir <resolved-root> separately, and add coverage for missing/non-directory WorkingDir.
• See the inline warning about accepting whitespace/control-character OCI WorkingDir values before SSH discovery and shell-text flows consume the path.

Docs: Fern docs and relevant agent skill guidance were updated; no docs navigation change appears required because no new page was added.

Next state: gator:in-review

[drew]

gator-agent

Warning: resolve_oci_workspace_root accepts paths with trailing whitespace or control characters, but SSH workspace discovery later trims stdout and uses shell text protocols. A WorkingDir such as /workspace or one containing a newline can be accepted by the driver and then discovered as a different root or fail transfer/editor flows. Please reject these as malformed here, or change discovery to use an unambiguous encoding before accepting them. This is CWE-20 input validation.