refactor(compute): negotiate gateway-managed lifecycle

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -199,7 +199,8 @@ running intent should stop before the gateway exits and restart after it
 returns. Check for `Stopped sandbox during gateway shutdown` and `Started
 sandbox during gateway startup` in gateway logs. A sandbox explicitly stopped
 through the CLI remains stopped. Kubernetes sandboxes are cluster-owned and do
-not follow this local gateway lifecycle.
+not follow this local gateway lifecycle. An external driver follows it only
+when `GetCapabilities` advertises `GATEWAY_MANAGED_LIFECYCLE`.
 
 ### Step 5: Check Podman-Backed Gateways
 

architecture/compute-runtimes.md

@@ -27,9 +27,10 @@ implementing `ComputeDriver` out of tree.
 At initialization the gateway snapshots additive feature values from
 `GetCapabilities`; unknown values are ignored. Post-initialization lifecycle
 and policy behavior does not depend on the configured or advertised driver
-name. Startup intent reconciliation and native process-identity defaults are
-enabled only by their corresponding features. Driver-requested listeners are
-structurally validated and remain restricted to sandbox callback RPCs.
+name. Gateway-managed shutdown/start lifecycle and native process-identity
+defaults are enabled only by their corresponding features. Driver-requested
+listeners are structurally validated and remain restricted to sandbox callback
+RPCs.
 
 Drivers own runtime-specific platform event interpretation. When an event should
 drive client provisioning UI, the driver attaches the shared

crates/openshell-core/src/driver_utils.rs

@@ -589,15 +589,15 @@ mod tests {
             "1.0.0",
             "sandbox:latest",
             [
-                ComputeDriverFeature::GatewayStartReconciliation,
+                ComputeDriverFeature::GatewayManagedLifecycle,
                 ComputeDriverFeature::PreserveUnspecifiedProcessIdentity,
             ],
         );
 
         assert_eq!(
             capabilities.features,
             vec![
-                i32::from(ComputeDriverFeature::GatewayStartReconciliation),
+                i32::from(ComputeDriverFeature::GatewayManagedLifecycle),
                 i32::from(ComputeDriverFeature::PreserveUnspecifiedProcessIdentity),
             ]
         );

crates/openshell-driver-docker/src/lib.rs

@@ -495,7 +495,7 @@ impl DockerComputeDriver {
             &self.config.daemon_version,
             &self.config.default_image,
             [
-                openshell_core::proto::compute::v1::ComputeDriverFeature::GatewayStartReconciliation,
+                openshell_core::proto::compute::v1::ComputeDriverFeature::GatewayManagedLifecycle,
                 openshell_core::proto::compute::v1::ComputeDriverFeature::PreserveUnspecifiedProcessIdentity,
             ],
         )

crates/openshell-driver-podman/src/driver.rs

@@ -469,7 +469,7 @@ impl PodmanComputeDriver {
             openshell_core::VERSION,
             &self.config.default_image,
             [
-                openshell_core::proto::compute::v1::ComputeDriverFeature::GatewayStartReconciliation,
+                openshell_core::proto::compute::v1::ComputeDriverFeature::GatewayManagedLifecycle,
                 openshell_core::proto::compute::v1::ComputeDriverFeature::PreserveUnspecifiedProcessIdentity,
             ],
         ))

crates/openshell-driver-vm/src/driver.rs

@@ -520,7 +520,7 @@ impl VmDriver {
             driver_name: DRIVER_NAME.to_string(),
             driver_version: openshell_core::VERSION.to_string(),
             default_image: self.config.default_image.clone(),
-            features: vec![ComputeDriverFeature::GatewayStartReconciliation.into()],
+            features: vec![ComputeDriverFeature::GatewayManagedLifecycle.into()],
         }
     }
 

crates/openshell-server/src/compute/mod.rs

@@ -837,6 +837,11 @@ impl ComputeRuntime {
         self.driver_info.features.contains(&i32::from(feature))
     }
 
+    #[must_use]
+    pub(crate) fn uses_gateway_managed_lifecycle(&self) -> bool {
+        self.supports_feature(ComputeDriverFeature::GatewayManagedLifecycle)
+    }
+
     #[must_use]
     pub(crate) fn preserves_unspecified_process_identity(&self) -> bool {
         self.supports_feature(ComputeDriverFeature::PreserveUnspecifiedProcessIdentity)
@@ -2055,14 +2060,10 @@ impl ComputeRuntime {
     /// persisted lifecycle intent.
     ///
     /// An explicit sandbox stop persists `Stopped`; gateway shutdown does not.
-    /// Docker, Podman, and VM compute is stopped through the same public driver
-    /// RPC and restarted from the retained running-intent phase on gateway
-    /// startup. Kubernetes compute remains cluster-owned and is excluded.
+    /// Drivers opt into stop/start ownership through their public capability
+    /// snapshot. Kubernetes and legacy extension drivers omit that capability.
     async fn stop_persisted_sandboxes_on_shutdown(&self) -> Result<(), String> {
-        if !matches!(
-            self.driver_kind(),
-            Some(ComputeDriverKind::Docker | ComputeDriverKind::Podman | ComputeDriverKind::Vm)
-        ) {
+        if !self.uses_gateway_managed_lifecycle() {
             return Ok(());
         }
 
@@ -2158,7 +2159,7 @@ impl ComputeRuntime {
 
     /// Reconcile running intent for local compute after a gateway restart.
     ///
-    /// Drivers opt into this sweep through their startup capability snapshot.
+    /// Drivers opt into this sweep through their lifecycle capability snapshot.
     /// `StartSandbox` is idempotent, so call it for every persisted phase that
     /// requires running compute. Stable stopped, deleting, and error states are
     /// deliberately left alone.
@@ -2167,7 +2168,7 @@ impl ComputeRuntime {
     /// so the watch loop sees the post-start state on its first poll.
     pub async fn start_persisted_sandboxes(&self) -> Result<(), String> {
         self.recover_persisted_lifecycle_transitions().await?;
-        if !self.supports_feature(ComputeDriverFeature::GatewayStartReconciliation) {
+        if !self.uses_gateway_managed_lifecycle() {
             return Ok(());
         }
 
@@ -4075,11 +4076,11 @@ pub async fn new_test_runtime_with_driver(
 ) -> ComputeRuntime {
     let features = match driver_name.parse::<ComputeDriverKind>().ok() {
         Some(ComputeDriverKind::Docker | ComputeDriverKind::Podman) => vec![
-            i32::from(ComputeDriverFeature::GatewayStartReconciliation),
+            i32::from(ComputeDriverFeature::GatewayManagedLifecycle),
             i32::from(ComputeDriverFeature::PreserveUnspecifiedProcessIdentity),
         ],
         Some(ComputeDriverKind::Vm) => {
-            vec![i32::from(ComputeDriverFeature::GatewayStartReconciliation)]
+            vec![i32::from(ComputeDriverFeature::GatewayManagedLifecycle)]
         }
         _ => Vec::new(),
     };
@@ -8177,7 +8178,12 @@ mod tests {
     #[tokio::test]
     async fn shutdown_stops_running_intent_without_changing_persisted_phase() {
         let driver = ControlledDriver::new();
-        let runtime = test_runtime_for_driver(driver.clone(), "docker").await;
+        let runtime = test_runtime_for_driver_with_features(
+            driver.clone(),
+            "extension",
+            vec![ComputeDriverFeature::GatewayManagedLifecycle],
+        )
+        .await;
 
         for (id, name, phase) in [
             ("sb-unspecified", "unspecified", SandboxPhase::Unspecified),
@@ -8236,7 +8242,12 @@ mod tests {
     async fn shutdown_stop_sweep_continues_after_driver_errors() {
         let driver = ControlledDriver::new();
         driver.set_stop_outcome(ControlledLifecycleOutcome::Error("runtime angry"));
-        let runtime = test_runtime_for_driver(driver.clone(), "podman").await;
+        let runtime = test_runtime_for_driver_with_features(
+            driver.clone(),
+            "extension",
+            vec![ComputeDriverFeature::GatewayManagedLifecycle],
+        )
+        .await;
         for (id, name) in [("sb-1", "one"), ("sb-2", "two")] {
             runtime
                 .store
@@ -8258,7 +8269,12 @@ mod tests {
     async fn shutdown_stop_sweep_uses_bounded_concurrency() {
         let driver = ControlledDriver::new();
         driver.block_stop();
-        let runtime = test_runtime_for_driver(driver.clone(), "docker").await;
+        let runtime = test_runtime_for_driver_with_features(
+            driver.clone(),
+            "extension",
+            vec![ComputeDriverFeature::GatewayManagedLifecycle],
+        )
+        .await;
         let sandbox_count = SHUTDOWN_STOP_CONCURRENCY + 1;
         for index in 0..sandbox_count {
             runtime
@@ -8296,16 +8312,15 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn shutdown_stop_sweep_runs_for_each_local_driver_only() {
-        for (driver_name, expected_calls) in [
-            ("docker", 1),
-            ("podman", 1),
-            ("vm", 1),
-            ("kubernetes", 0),
-            ("extension", 0),
-        ] {
+    async fn shutdown_stop_sweep_runs_for_any_capable_driver() {
+        for driver_name in ["docker", "podman", "vm", "extension"] {
             let driver = ControlledDriver::new();
-            let runtime = test_runtime_for_driver(driver.clone(), driver_name).await;
+            let runtime = test_runtime_for_driver_with_features(
+                driver.clone(),
+                driver_name,
+                vec![ComputeDriverFeature::GatewayManagedLifecycle],
+            )
+            .await;
             runtime
                 .store
                 .put_message(&sandbox_record("sb-1", "sandbox", SandboxPhase::Ready))
@@ -8319,19 +8334,43 @@ mod tests {
 
             assert_eq!(
                 driver.stop_calls(),
-                expected_calls,
+                1,
                 "unexpected shutdown behavior for {driver_name}"
             );
         }
     }
 
+    #[tokio::test]
+    async fn shutdown_stop_sweep_skips_drivers_without_feature() {
+        for driver_name in ["kubernetes", "docker", "extension"] {
+            let driver = ControlledDriver::new();
+            let runtime = test_runtime_for_driver(driver.clone(), driver_name).await;
+            runtime
+                .store
+                .put_message(&sandbox_record("sb-1", "sandbox", SandboxPhase::Ready))
+                .await
+                .unwrap();
+
+            runtime
+                .stop_persisted_sandboxes_on_shutdown()
+                .await
+                .unwrap();
+
+            assert_eq!(
+                driver.stop_calls(),
+                0,
+                "{driver_name} should retain operator-owned lifecycle"
+            );
+        }
+    }
+
     #[tokio::test]
     async fn start_persisted_sandboxes_starts_running_phases() {
         let driver = ControlledDriver::new();
         let runtime = test_runtime_for_driver_with_features(
             driver.clone(),
             "extension",
-            vec![ComputeDriverFeature::GatewayStartReconciliation],
+            vec![ComputeDriverFeature::GatewayManagedLifecycle],
         )
         .await;
 
@@ -8375,7 +8414,7 @@ mod tests {
         let runtime = test_runtime_for_driver_with_features(
             driver,
             "extension",
-            vec![ComputeDriverFeature::GatewayStartReconciliation],
+            vec![ComputeDriverFeature::GatewayManagedLifecycle],
         )
         .await;
 
@@ -8410,7 +8449,7 @@ mod tests {
         let runtime = test_runtime_for_driver_with_features(
             driver,
             "extension",
-            vec![ComputeDriverFeature::GatewayStartReconciliation],
+            vec![ComputeDriverFeature::GatewayManagedLifecycle],
         )
         .await;
 
@@ -8445,7 +8484,7 @@ mod tests {
             let runtime = test_runtime_for_driver_with_features(
                 driver.clone(),
                 driver_name,
-                vec![ComputeDriverFeature::GatewayStartReconciliation],
+                vec![ComputeDriverFeature::GatewayManagedLifecycle],
             )
             .await;
             let sandbox = sandbox_record("sb-1", "local", SandboxPhase::Ready);
@@ -8691,7 +8730,7 @@ mod tests {
             .with_driver_name("fake-remote-driver")
             .with_default_image("openshell/sandbox:remote")
             .with_features([
-                ComputeDriverFeature::GatewayStartReconciliation,
+                ComputeDriverFeature::GatewayManagedLifecycle,
                 ComputeDriverFeature::PreserveUnspecifiedProcessIdentity,
             ])
             .with_gateway_listener_requirement(
@@ -8767,6 +8806,17 @@ mod tests {
         assert!(driver_config.fields.contains_key("pool"));
         assert!(!driver_config.fields.contains_key("network_mode"));
 
+        driver.clear_calls();
+        runtime
+            .stop_persisted_sandboxes_on_shutdown()
+            .await
+            .unwrap();
+        assert!(matches!(
+            driver.calls().as_slice(),
+            [FakeComputeDriverCall::StopSandbox { sandbox_id, sandbox_name }]
+                if sandbox_id == "sb-uds" && sandbox_name == "uds-sandbox"
+        ));
+
         driver.clear_calls();
         runtime.start_persisted_sandboxes().await.unwrap();
         assert!(matches!(

proto/compute_driver.proto

@@ -82,9 +82,9 @@ message GetCapabilitiesResponse {
 
 enum ComputeDriverFeature {
   COMPUTE_DRIVER_FEATURE_UNSPECIFIED = 0;
-  // Reconcile persisted running intent by calling StartSandbox when the
-  // gateway starts.
-  COMPUTE_DRIVER_FEATURE_GATEWAY_START_RECONCILIATION = 1;
+  // Let the gateway stop persisted running intent during graceful shutdown
+  // and restart that intent when the gateway starts.
+  COMPUTE_DRIVER_FEATURE_GATEWAY_MANAGED_LIFECYCLE = 1;
   // Preserve omitted process user/group fields so the runtime can apply its
   // native image or OCI identity defaults.
   COMPUTE_DRIVER_FEATURE_PRESERVE_UNSPECIFIED_PROCESS_IDENTITY = 2;