test(podman): run namespace stories against a shared gateway

.github/workflows/branch-checks.yml

@@ -143,6 +143,7 @@ jobs:
           cargo fmt --all -- --check
           cargo fmt --manifest-path e2e/support/rust/Cargo.toml --all -- --check
           cargo fmt --manifest-path e2e/suites/conformance/Cargo.toml --all -- --check
+          cargo fmt --manifest-path e2e/suites/drivers/Cargo.toml --all -- --check
           cargo fmt --manifest-path e2e/rust/Cargo.toml --all -- --check
           cargo fmt --manifest-path examples/governance-interceptor/Cargo.toml --all -- --check
           cargo fmt --manifest-path examples/supervisor-middleware-content-guard/Cargo.toml --all -- --check
@@ -200,6 +201,7 @@ jobs:
           cargo clippy --locked --workspace --all-targets -- -D warnings
           cargo clippy --locked --manifest-path e2e/support/rust/Cargo.toml --workspace --all-targets -- -D warnings
           cargo clippy --locked --manifest-path e2e/suites/conformance/Cargo.toml --workspace --all-targets -- -D warnings
+          cargo clippy --locked --manifest-path e2e/suites/drivers/Cargo.toml --workspace --all-targets -- -D warnings
           cargo clippy --locked --manifest-path e2e/rust/Cargo.toml --all-targets -- -D warnings
           cargo clippy --locked --manifest-path examples/governance-interceptor/Cargo.toml --all-targets -- -D warnings
           cargo clippy --locked --manifest-path examples/supervisor-middleware-content-guard/Cargo.toml --all-targets -- -D warnings
@@ -241,6 +243,7 @@ jobs:
           cargo nextest run --locked --profile ci --workspace --features openshell-server/test-support
           cargo nextest run --locked --config-file .config/nextest.toml --profile ci --manifest-path e2e/support/rust/Cargo.toml
           cargo nextest run --locked --config-file .config/nextest.toml --profile ci --manifest-path e2e/suites/conformance/Cargo.toml --package openshell-test-conformance-cli -E 'binary(policy_advisor) & test(draft_assertion::tests::)'
+          cargo nextest run --locked --config-file .config/nextest.toml --profile ci --manifest-path e2e/suites/drivers/Cargo.toml --package openshell-test-suite-podman -E 'test(::tests::)'
           cargo nextest run --locked --config-file .config/nextest.toml --profile ci --manifest-path examples/supervisor-middleware-content-guard/Cargo.toml
 
   rust-build-modes:

TESTING.md

@@ -336,7 +336,14 @@ The `e2e-podman` testsuite runs a nextest archive built with the corresponding
 Rust feature and preloads its Python workload image into the rootless Podman
 store. The separate `driver-podman` testsuite compares OpenShell and direct
 Podman user-namespace mappings for the default, `auto`, `keep-id`, and private
-profiles. The E2E archive excludes binaries that still depend on wrapper-owned
+profiles. Each profile is a named Rust test. The suite runs serially against
+the shared gateway; a guest-side file lock also protects separate invocations.
+The Rust fixture restores the original gateway configuration, restarts and
+checks gateway health, and verifies sandbox cleanup after each test, including
+assertion failures. A dirty marker stops later tests after interruption or failed
+restoration; start a fresh tmachine invocation to recover.
+
+The E2E archive excludes binaries that still depend on wrapper-owned
 gateway controls, host fixtures, missing guest tools, or nondeterministic relay
 setup. The `driver-podman` suite replaces the removed `podman_userns` E2E
 binary. `tests/artifacts.nix` keeps the follow-up exclusions explicit and uses

e2e/suites/drivers/podman/Cargo.toml

@@ -12,4 +12,11 @@ repository = "https://github.com/NVIDIA/OpenShell"
 [dependencies]
 openshell-e2e-support = { path = "../../../support/rust" }
 serde = { version = "1", features = ["derive"] }
-tokio = { version = "1.43", features = ["macros", "rt"] }
+tokio = { version = "1.43", features = ["macros", "rt", "process", "time", "io-util"] }
+
+[dev-dependencies]
+futures-util = { version = "0.3", default-features = false, features = ["std"] }
+toml_edit = "0.22"
+
+[features]
+fixture-validation = []

e2e/suites/drivers/podman/README.md

@@ -0,0 +1,56 @@
+# Podman driver tests
+
+These tests run inside a disposable tmachine guest against its shared Podman
+gateway. Rootful and rootless Podman are separate tmachine environments.
+
+The `user_namespaces` Cargo test target contains four story modules: `default`,
+`auto`, `keep_id`, and `private`. Each compares OpenShell's UID mapping with a
+direct Podman container in the gateway service user's execution context, and
+checks that the non-root workload owns and can write to its managed workspace.
+Both commands use the same workload image.
+
+## Gateway fixture
+
+The Rust fixture requires `/etc/openshell/gateway.toml`, the
+`openshell-gateway.service` systemd unit, a registered candidate CLI, and
+passwordless sudo in the guest. tmachine prepares the writable fixture directory
+at `/var/lib/openshell-driver-tests/podman`. This is a dedicated test gateway:
+its baseline must omit `userns`, `uidmap`, and `gidmap` and contain no sandboxes.
+
+Ansible installs the archive and invokes nextest once with `--test-threads 1`.
+A guest-side file lock also serializes separate Cargo or nextest invocations.
+Under the lock, Rust captures the original config, applies the selected profile,
+and restarts and checks gateway readiness. After success, an error, or an
+assertion panic, it deletes tracked sandboxes, restores the exact original
+configuration, restarts the gateway, and verifies health and sandbox absence.
+Scenario failures and restoration failures remain test failures.
+
+Before changing the gateway, the fixture writes a dirty marker. It removes that
+marker only after successful restoration. An interrupted process or failed
+restoration therefore prevents subsequent stories from treating modified state
+as their baseline. Start a fresh tmachine invocation to recover; each invocation
+uses a disposable overlay over the cached installed guest image.
+
+## Run
+
+Build the candidate runtime inputs and driver archive, then run either environment:
+
+```shell
+nix run .#build-podman-driver-test-archive
+nix run .#tmachine -- test fedora-podman-rootful binaries driver-podman
+nix run .#tmachine -- test fedora-podman-rootless binaries driver-podman
+```
+
+The tests may restart the gateway and require guest privileges. Run the pure
+configuration and UID-map assertions on the development host with:
+
+```shell
+cargo test --locked --manifest-path e2e/suites/drivers/Cargo.toml \
+  --package openshell-test-suite-podman --test user_namespaces ::tests::
+```
+
+Inside a prepared guest, a nextest test-name filter selects one profile. The
+`fixture-validation` Cargo feature adds a deliberately failing panic scenario
+for validating cleanup; it is excluded from normal archives. Execute that
+scenario explicitly, require failure and successful restoration, then run a
+normal profile in the same guest to verify recovery.