feat(podman): honor OCI image working directories

[matthewgrossman]

Summary

Add Podman OCI WORKDIR support and simplify the local-container workspace contract shared by Docker and Podman. This supersedes #2563 without its probe container or identity-attestation protocol.

Related Issue

Closes #2526

Supersedes #2563.

Changes

1. Add OCI WORKDIR support to Podman

• Inspect and pin the selected image, resolve its OCI USER and WorkingDir, and mount the persistent named workspace volume at the resolved workdir.
• Start the supervisor independently from the image workdir, then use the resolved workspace as HOME and the cwd for direct and SSH workload processes.
• Preserve /sandbox as the managed compatibility workspace for an empty, root (/), or explicit /sandbox workdir.

2. Remove final-user workdir writability enforcement

• Docker previously performed an additional startup validation to prove that the image's final USER could traverse and write WORKDIR.
• Remove that validation rather than reproduce it for Podman. OpenShell validates workspace structure and mount placement, but image usability is the image author's responsibility. If an image supplies an unusable USER/WORKDIR combination, its workload fails naturally when it changes directory or writes.
• Remove Docker's final-identity validator subprocess, UID/GID and supplementary-group permission model, and temporary write probe. Neither driver creates, chowns, chmods, or otherwise repairs a non-default OCI workdir.
• Avoid feat(podman): honor OCI image working directories #2563's separate Podman probe container, gateway/protobuf identity plumbing, identity attestation, and privilege-drop probe logic.

3. Harden workspace mount placement

• Share normalized-path, no-follow structural validation between Docker and Podman, rejecting missing components, symlinks, non-directories, and collisions with concrete OpenShell control paths.
• Validate explicit driver-config mounts against the resolved workspace and OpenShell control paths.
• Reject overlap in either direction with kernel-managed roots and the supervisor's minimal executable/library roots, while continuing to allow application paths such as /usr/src/app.
• Run local non-default workspace validation before policy, credential, TLS, or networking initialization, independent of explicit run_as_user or run_as_group settings.

4. Document and test the resulting contract

• Update architecture, Docker, Podman, published, and agent documentation without changing Kubernetes or VM workspace behavior.
• Add focused unit and E2E coverage for OCI workdirs, /sandbox compatibility, mount collisions, protected roots, and image-author-owned permissions.
• Verify that normal Podman named-volume copy-up preserves ownership and modes; OpenShell does not request ownership-changing options such as :U.

Follow-up

The privileged supervisor still uses executables and libraries supplied by the workload image. #2750 tracks making that functionality self-contained, replacing external helpers such as dmesg with direct kernel interfaces, and eventually removing the executable/library workspace-root restrictions that exist for supervisor safety.

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 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

[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: feb15b4dfed12c721d200eaece5d7bfc498da584
Base SHA: c4b500a7de64d0b66e3ee8098f58d14299092162
Merge base SHA: dd2b4e3bc0688bdd59f90030f7c1d52511d6e354
Patch ID: f7351594599ae0ee641e61e797226c3d0b408d40
Gator payload: 4
Review mode: follow_up
Previous reviewed SHA: 8e70faeeffe62daa4d88ecb12be998d129474768
Review budget exhausted: no
Maintainer decision required: no

I reviewed the author-only delta that defers the separate dmesg hardening and clarifies the Podman supervisor startup working directory.

Blocking findings:

• No blocking findings remain.

Carried findings:

• None.

Non-blocking findings:

• None.

Docs: No additional Fern update is needed for this follow-up delta; the existing compute-driver documentation continues to cover the user-visible OCI WorkingDir behavior.

CI/E2E: The prior requested head 8e70faeeffe62daa4d88ecb12be998d129474768 completed Branch Checks, Helm Lint, and required E2E successfully. For this current head, Helm Lint is green, Branch Checks is running, and the required test:e2e workflow is queued.

Next state: gator:watch-pipeline