feat(podman): honor OCI image working directories

[matthewgrossman]

Summary

Add Podman OCI WORKDIR support with the persistent workspace volume mounted at the resolved image workdir. This is a simpler alternative to #2563: Docker and Podman use the same structural workspace validation contract, with no separate Podman probe or final-identity writability protocol.

Related Issue

Closes #2526

Supersedes #2563.

Changes

• Inspect and pin Podman images, resolve OCI USER and WorkingDir, and mount the named workspace volume at the resolved workdir
• Share OCI workdir, control-path, and forbidden-root validation between Docker and Podman
• Continue validating explicit driver-config mounts against the resolved WORKDIR and OpenShell control paths
• Reject workspace overlap in either direction with the known kernel-managed OCI roots and the supervisor's minimal executable/library roots, while allowing application paths such as /usr/src/app
• Make every local non-default OCI workdir receive an early no-follow structural check before policy, credential, TLS, and networking initialization, independent of explicit run_as_user or run_as_group values
• Limit structural validation to existing directory components with no symlink traversal; do not infer policy from filesystem magic or reject unrelated tmpfs mounts
• Leave non-default workdir ownership and permissions to the image author; neither Docker nor Podman tests final-identity writability or repairs an unusable image
• Preserve managed creation and ownership preparation for the /sandbox compatibility workspace
• Resolve the supervisor's dmesg helper only from protected absolute system paths instead of the image's PATH
• Document the long-term goal of removing the supervisor's dependency on executable and library paths shared with the sandbox image
• Add focused unit/E2E coverage and update architecture, driver, published, and agent documentation
• Avoid the probe container, gateway/protobuf identity plumbing, identity attestation, privilege-drop subprocess, and write-probe logic from feat(podman): honor OCI image working directories #2563

Testing

• mise run pre-commit
• mise run test
• cargo test -p openshell-supervisor-process
• cargo test -p openshell-driver-docker
• cargo test -p openshell-driver-podman
• cargo test -p openshell-sandbox
• cargo test -p openshell-core driver_mounts
• Current-head required E2E: Docker, rootless Podman, Kubernetes, and VM paths
• Podman 6.0.2 rootful named-volume copy-up tested on Fedora 44 with SELinux enabled; ownership and modes were preserved for usable and unusable workdirs and copied files

Podman volume initialization can vary across rootless, rootful, user-namespace, and SELinux configurations. The documentation calls out that image authors remain responsible for a usable USER/WORKDIR combination and OpenShell does not request ownership-changing options such as :U or repair the result.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)

[github-actions]

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

[github-actions]

Label test:e2e applied for 91ec914. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[matthewgrossman]

gator-agent

PR Review Status

Validation: This PR is project-valid because it implements maintainer-authored, agent-ready issue #2526 and explicitly supersedes #2563 with a simpler Podman OCI WorkingDir design.
Head SHA: 91ec914db17f7fce81789d384d931672ad371df1
Base SHA: dd2b4e3bc0688bdd59f90030f7c1d52511d6e354
Merge base SHA: dd2b4e3bc0688bdd59f90030f7c1d52511d6e354
Patch ID: 04b32d7237ac5106b69432b00e9c21a9720c45e6
Gator payload: 3
Review mode: initial
Previous reviewed SHA: none

Blocking findings:

• No blocking findings remain.

Carried findings:

• None.

Non-blocking suggestions:

• None.

Docs: Fern compute-driver documentation, architecture guidance, Podman driver documentation, and companion agent guidance cover the user-visible OCI WorkingDir behavior.

E2E: test:e2e is applied because the change affects Podman sandbox lifecycle and persistent workspace behavior.

Next state: gator:watch-pipeline

[matthewgrossman]

gator-agent

PR Review Status

Validation: This PR remains project-valid because it implements maintainer-authored issue #2526 and supersedes #2563 with the requested simpler Podman OCI WorkingDir design.
Head SHA: 8e70faeeffe62daa4d88ecb12be998d129474768
Base SHA: c4b500a7de64d0b66e3ee8098f58d14299092162
Merge base SHA: dd2b4e3bc0688bdd59f90030f7c1d52511d6e354
Patch ID: 499fe2c87443b3ca0796e08cef3a965c295fe945
Gator payload: 4
Review mode: follow_up
Previous reviewed SHA: 91ec914db17f7fce81789d384d931672ad371df1
Review budget exhausted: no
Maintainer decision required: no

I re-reviewed the non-equivalent effective diff after the history rewrite.

Blocking findings:

• No blocking findings remain.

Carried findings:

• None.

Non-blocking findings:

• None.

Docs: Fern compute-driver documentation, architecture guidance, Podman driver documentation, and companion agent guidance cover the user-visible OCI WorkingDir behavior.

CI/E2E: Branch Checks and Helm Lint are green for this head. The required test:e2e workflow is running for this head; build and manifest jobs are progressing and the required OpenShell / E2E gate remains pending.

Next state: gator:watch-pipeline