test(conformance): add sandbox environment capability

Signed-off-by: Evan Lezar <elezar@nvidia.com>

Author: elezar

crates/openshell-conformance/src/lib.rs

@@ -27,7 +27,8 @@ pub use scenarios::{
     FILE_TRANSFER_GIT_FILTERING_SCENARIO, FILE_TRANSFER_PATH_SAFETY_SCENARIO,
     FILE_TRANSFER_ROUND_TRIP_SCENARIO, FILE_TRANSFER_SCENARIO, MECHANISTIC_PROPOSAL_SCENARIO,
     NEW_HOSTNAME_PROPOSAL_SCENARIO, POLICY_LOCAL_SCENARIO, SANDBOX_CANONICAL_MAIN_SCENARIO,
-    SANDBOX_LIFECYCLE_SCENARIO, SANDBOX_STOP_START_SCENARIO, SMOKE_SCENARIO,
+    SANDBOX_ENVIRONMENT_SCENARIO, SANDBOX_LIFECYCLE_SCENARIO, SANDBOX_STOP_START_SCENARIO,
+    SMOKE_SCENARIO,
 };
 
 /// An installed conformance scenario.
@@ -49,6 +50,7 @@ impl Scenario {
 const SCENARIOS: &[Scenario] = &[
     SMOKE_SCENARIO,
     SANDBOX_LIFECYCLE_SCENARIO,
+    SANDBOX_ENVIRONMENT_SCENARIO,
     FILE_TRANSFER_SCENARIO,
     MECHANISTIC_PROPOSAL_SCENARIO,
     NEW_HOSTNAME_PROPOSAL_SCENARIO,

crates/openshell-conformance/src/scenarios/mod.rs

@@ -5,6 +5,7 @@
 
 mod file_transfer;
 mod policy_behavior;
+mod sandbox_environment;
 mod sandbox_lifecycle;
 mod smoke;
 
@@ -15,6 +16,7 @@ pub use file_transfer::{
 pub use policy_behavior::{
     MECHANISTIC_PROPOSAL_SCENARIO, NEW_HOSTNAME_PROPOSAL_SCENARIO, POLICY_LOCAL_SCENARIO,
 };
+pub use sandbox_environment::SANDBOX_ENVIRONMENT_SCENARIO;
 pub use sandbox_lifecycle::{
     SANDBOX_CANONICAL_MAIN_SCENARIO, SANDBOX_LIFECYCLE_SCENARIO, SANDBOX_STOP_START_SCENARIO,
 };

crates/openshell-conformance/src/scenarios/sandbox_environment.rs

@@ -0,0 +1,221 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Portable sandbox environment conformance scenarios.
+
+use std::time::Duration;
+
+use serde::Deserialize;
+
+use crate::{OpenShellRunner, Poll, Scenario, ScenarioFuture};
+
+const CREATE_TIMEOUT: Duration = Duration::from_mins(10);
+const COMMAND_TIMEOUT: Duration = Duration::from_mins(2);
+const TRANSITION_TIMEOUT: Duration = Duration::from_mins(4);
+const TRANSITION_INTERVAL: Duration = Duration::from_secs(2);
+
+#[derive(Debug, Deserialize)]
+struct SandboxState {
+    name: String,
+    phase: String,
+}
+
+/// Certify declared environment propagation to the canonical main and exec.
+pub const SANDBOX_ENVIRONMENT_SCENARIO: Scenario = Scenario {
+    name: "sandbox-environment",
+    description: "Verify declared environment propagation to canonical-main and exec processes.",
+    run: run_sandbox_environment,
+};
+
+fn run_sandbox_environment(runner: &mut OpenShellRunner) -> ScenarioFuture<'_> {
+    Box::pin(async move {
+        let sandbox_name = format!("ct-{}-env", runner.id());
+        let sentinel_path = "/sandbox/.openshell-declared-environment";
+        let main = format!(
+            "printf '%s\\n' \"${{REPRO_SENTINEL:-missing}}\" > '{sentinel_path}'; exec sleep infinity"
+        );
+
+        create_sandbox(runner, &sandbox_name, &main).await?;
+        exec_expect_exact(
+            runner,
+            &sandbox_name,
+            "read-main-environment",
+            &[
+                "sh",
+                "-c",
+                &format!(
+                    "while [ ! -f '{sentinel_path}' ]; do sleep 0.05; done; cat '{sentinel_path}'"
+                ),
+            ],
+            "present\n",
+        )
+        .await?;
+        let exec_environment = format!("printf '%s\\n' \"${{{}:-missing}}\"", "REPRO_SENTINEL");
+        exec_expect_exact(
+            runner,
+            &sandbox_name,
+            "read-exec-environment",
+            &["sh", "-c", &exec_environment],
+            "present\n",
+        )
+        .await?;
+        delete_and_confirm_absent(runner, &sandbox_name).await
+    })
+}
+
+async fn create_sandbox(
+    runner: &mut OpenShellRunner,
+    sandbox_name: &str,
+    main: &str,
+) -> Result<(), String> {
+    runner.track_sandbox(sandbox_name);
+    let create = runner
+        .step("create")
+        .description(format!(
+            "sandbox '{sandbox_name}' is created with a declared environment"
+        ))
+        .with_timeout(CREATE_TIMEOUT)
+        .run(&[
+            "sandbox",
+            "create",
+            "--name",
+            sandbox_name,
+            "--detach",
+            "--no-tty",
+            "--no-auto-providers",
+            "--env",
+            "REPRO_SENTINEL=present",
+            "--",
+            "sh",
+            "-lc",
+            main,
+        ])
+        .await
+        .map_err(|error| error.to_string())?;
+    create.require_success()?;
+    wait_for_phase(runner, sandbox_name, "Ready", "ready").await
+}
+
+async fn exec_expect_exact(
+    runner: &OpenShellRunner,
+    sandbox_name: &str,
+    step: &str,
+    command: &[&str],
+    expected_stdout: &str,
+) -> Result<(), String> {
+    let mut args = vec!["sandbox", "exec", "--name", sandbox_name, "--no-tty", "--"];
+    args.extend_from_slice(command);
+    let result = runner
+        .step(step)
+        .description(format!("sandbox '{sandbox_name}' exec {step} succeeds"))
+        .with_timeout(COMMAND_TIMEOUT)
+        .run(&args)
+        .await
+        .map_err(|error| error.to_string())?;
+    result.require_success()?;
+    if result.stdout() == expected_stdout {
+        Ok(())
+    } else {
+        Err(result.failure_diagnostic(&format!("stdout is exactly {expected_stdout:?}")))
+    }
+}
+
+async fn delete_and_confirm_absent(
+    runner: &mut OpenShellRunner,
+    sandbox_name: &str,
+) -> Result<(), String> {
+    let delete = runner
+        .step("delete")
+        .description(format!("sandbox '{sandbox_name}' deletion succeeds"))
+        .with_timeout(COMMAND_TIMEOUT)
+        .run(&["sandbox", "delete", sandbox_name])
+        .await
+        .map_err(|error| error.to_string())?;
+    delete.require_success()?;
+    wait_for_absence(runner, sandbox_name, "deleted").await?;
+    runner.forget_sandbox(sandbox_name);
+    Ok(())
+}
+
+async fn wait_for_phase(
+    runner: &mut OpenShellRunner,
+    sandbox_name: &str,
+    expected_phase: &str,
+    step: &str,
+) -> Result<(), String> {
+    let sandbox_name = sandbox_name.to_string();
+    let expected_phase = expected_phase.to_string();
+    let step = step.to_string();
+    let poll_step = step.clone();
+    runner
+        .poll_until(
+            &poll_step,
+            TRANSITION_TIMEOUT,
+            TRANSITION_INTERVAL,
+            async move |runner| {
+                let result = runner
+                    .step(format!("{step}/get"))
+                    .description(format!(
+                        "sandbox '{sandbox_name}' reaches phase {expected_phase}"
+                    ))
+                    .with_timeout(COMMAND_TIMEOUT)
+                    .run(&["sandbox", "get", &sandbox_name, "--output", "json"])
+                    .await;
+                match result {
+                    Ok(result) if !result.success() => {
+                        Poll::Pending(result.failure_diagnostic(&format!(
+                            "sandbox '{sandbox_name}' can be retrieved"
+                        )))
+                    }
+                    Ok(result) => match result.json::<SandboxState>() {
+                        Ok(state) if state.name != sandbox_name => Poll::Failed(format!(
+                            "sandbox get returned {:?}; expected '{sandbox_name}'",
+                            state.name
+                        )),
+                        Ok(state) if state.phase == expected_phase => Poll::Ready(()),
+                        Ok(state) => Poll::Pending(format!(
+                            "sandbox '{sandbox_name}' phase is {:?}; expected {expected_phase:?}",
+                            state.phase
+                        )),
+                        Err(error) => Poll::Failed(error.to_string()),
+                    },
+                    Err(error) => Poll::Pending(error.to_string()),
+                }
+            },
+        )
+        .await
+        .map_err(|error| error.to_string())
+}
+
+async fn wait_for_absence(
+    runner: &mut OpenShellRunner,
+    sandbox_name: &str,
+    step: &str,
+) -> Result<(), String> {
+    let sandbox_name = sandbox_name.to_string();
+    let step = step.to_string();
+    let poll_step = step.clone();
+    runner
+        .poll_until(
+            &poll_step,
+            TRANSITION_TIMEOUT,
+            TRANSITION_INTERVAL,
+            async move |runner| {
+                let result = runner
+                    .step(format!("{step}/get"))
+                    .description(format!("sandbox '{sandbox_name}' is no longer retrievable"))
+                    .with_timeout(COMMAND_TIMEOUT)
+                    .run(&["sandbox", "get", &sandbox_name, "--output", "json"])
+                    .await;
+                match result {
+                    Ok(result) if !result.success() => Poll::Ready(()),
+                    Ok(_) => {
+                        Poll::Pending(format!("sandbox '{sandbox_name}' is still retrievable"))
+                    }
+                    Err(error) => Poll::Pending(error.to_string()),
+                }
+            },
+        )
+        .await
+        .map_err(|error| error.to_string())
+}

e2e/rust/tests/sandbox_lifecycle.rs

@@ -736,41 +736,41 @@ async fn canonical_main_nonzero_exit_preserves_status() {
 
 #[tokio::test]
 #[serial(sandbox_lifecycle)]
-async fn canonical_main_and_exec_receive_declared_environment() {
-    for mode in ["--tty", "--no-tty"] {
-        let script = r#"printf 'declared_env=%s\n' "${REPRO_SENTINEL:-missing}"; while true; do sleep 1; done"#;
-        let mut sandbox = SandboxGuard::create_keep_with_args(
-            &[
-                mode,
-                "--no-auto-providers",
-                "--env",
-                "REPRO_SENTINEL=present",
-            ],
-            &["sh", "-c", script],
-            "declared_env=",
-        )
+async fn canonical_tty_main_and_exec_receive_declared_environment() {
+    let script =
+        r#"printf 'declared_env=%s\n' "${REPRO_SENTINEL:-missing}"; while true; do sleep 1; done"#;
+    let mut sandbox = SandboxGuard::create_keep_with_args(
+        &[
+            "--tty",
+            "--no-auto-providers",
+            "--env",
+            "REPRO_SENTINEL=present",
+        ],
+        &["sh", "-c", script],
+        "declared_env=",
+    )
+    .await
+    .expect("create canonical TTY process with declared environment");
+    let initial = normalize_output(&sandbox.create_output);
+    let later = sandbox
+        .exec(&[
+            "sh",
+            "-c",
+            r#"printf 'declared_env=%s\n' "${REPRO_SENTINEL:-missing}""#,
+        ])
         .await
-        .expect("create canonical process with declared environment");
-        let initial = normalize_output(&sandbox.create_output);
-        let later = sandbox
-            .exec(&[
-                "sh",
-                "-c",
-                r#"printf 'declared_env=%s\n' "${REPRO_SENTINEL:-missing}""#,
-            ])
-            .await;
-        sandbox.cleanup().await;
+        .expect("exec environment probe");
+    sandbox.cleanup().await;
 
-        assert!(
-            initial.lines().any(|line| line == "declared_env=present"),
-            "initial process must receive declared environment ({mode}): {initial}"
-        );
-        let later = normalize_output(&later.expect("exec environment probe"));
-        assert!(
-            later.lines().any(|line| line == "declared_env=present"),
-            "exec must receive the same declared environment ({mode}): {later}"
-        );
-    }
+    assert!(
+        initial.lines().any(|line| line == "declared_env=present"),
+        "initial TTY process must receive declared environment: {initial}"
+    );
+    let later = normalize_output(&later);
+    assert!(
+        later.lines().any(|line| line == "declared_env=present"),
+        "exec must receive the same declared environment as the TTY main: {later}"
+    );
 }
 
 #[tokio::test]

tests/artifacts.nix

@@ -129,10 +129,11 @@ let
     "proxy_egress_pipeline"
     # Conformance covers stop/start workspace preservation, deletion while
     # stopped, and detached canonical-main terminal state, fast-exit
-    # classification, persistence, and deletion. TTY streaming and CLI
-    # exit-code propagation, environment, attachment replay/recovery, signals,
-    # and no-keep cases remain. Nextest archive filters cannot select individual
-    # tests, so keep the complete binary in the follow-up bucket.
+    # classification, environment propagation, persistence, and deletion. TTY
+    # streaming/environment and CLI exit-code propagation, attachment
+    # replay/recovery, signals, and no-keep cases remain. Nextest archive
+    # filters cannot select individual tests, so keep the complete binary in
+    # the follow-up bucket.
     "sandbox_lifecycle"
     # Needs a prebuilt musl DNS probe in guest artifact mode; tracked in #3009.
     "transparent_tcp"

tests/suites/conformance/cli/tests/environment.rs

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Driver-agnostic sandbox environment conformance tests.
+
+use openshell_conformance::{OpenShellRunner, SANDBOX_ENVIRONMENT_SCENARIO};
+
+/// Exercise declared environment propagation through the candidate CLI.
+#[tokio::test]
+async fn declared_environment() {
+    let mut runner = OpenShellRunner::from_env(SANDBOX_ENVIRONMENT_SCENARIO.name)
+        .expect("candidate openshell CLI is available");
+
+    let result = async {
+        runner.check_gateway_status().await?;
+        SANDBOX_ENVIRONMENT_SCENARIO.run(&mut runner).await
+    }
+    .await;
+    if let Err(error) = runner.finish(result).await {
+        panic!("sandbox environment conformance scenario failed:\n{error}");
+    }
+}