feat(compute): let drivers declare gateway lifecycle

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

Author: drew

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

@@ -199,8 +199,9 @@ 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. An external driver configured under a
-different name is not included in the local gateway lifecycle sweep.
+not follow this local gateway lifecycle. Internal and external drivers follow
+the same rule: `GetCapabilities.gateway_managed_lifecycle` must be true for the
+gateway to run shutdown and startup sweeps.
 
 ### Step 5: Check Podman-Backed Gateways
 

architecture/compute-runtimes.md

@@ -24,11 +24,11 @@ references to gateway-internal types. The gateway owns the public
 implementing `ComputeDriver` out of tree.
 
 `compute_driver.proto` is the supported gateway/driver extension boundary.
-At initialization the gateway snapshots the driver's identity, version, and
-default image from `GetCapabilities`. Process-identity omissions are preserved
-across this boundary so every driver can apply its native image or runtime
-defaults. Driver-requested listeners are structurally validated and remain
-restricted to sandbox callback RPCs.
+At initialization the gateway snapshots the driver's identity, version,
+default image, and gateway-lifecycle preference from `GetCapabilities`.
+Process-identity omissions are preserved across this boundary so every driver
+can apply its native image or runtime defaults. 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
@@ -122,6 +122,11 @@ shared idempotent `StartSandbox` RPC before watch processing begins. Explicitly
 cluster-owned and continue running without gateway shutdown or startup
 lifecycle calls.
 
+The driver reports this behavior through
+`GetCapabilities.gateway_managed_lifecycle`. The same declaration works for
+in-process and external drivers. Older drivers omit the field and retain the
+conservative operator-managed behavior.
+
 ## Deletion Lifecycle
 
 Lifecycle requests use per-sandbox gates to serialize stop, start, and

crates/openshell-core/src/driver_utils.rs

@@ -380,11 +380,13 @@ pub fn build_capabilities_response(
     driver_name: &str,
     driver_version: impl Into<String>,
     default_image: impl Into<String>,
+    gateway_managed_lifecycle: bool,
 ) -> GetCapabilitiesResponse {
     GetCapabilitiesResponse {
         driver_name: driver_name.to_string(),
         driver_version: driver_version.into(),
         default_image: default_image.into(),
+        gateway_managed_lifecycle,
     }
 }
 

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

@@ -494,6 +494,7 @@ impl DockerComputeDriver {
             "docker",
             &self.config.daemon_version,
             &self.config.default_image,
+            true,
         )
     }
 

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

@@ -548,6 +548,7 @@ impl KubernetesComputeDriver {
             "kubernetes",
             openshell_core::VERSION,
             &self.config.default_image,
+            false,
         ))
     }
 

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

@@ -468,6 +468,7 @@ impl PodmanComputeDriver {
             "podman",
             openshell_core::VERSION,
             &self.config.default_image,
+            true,
         ))
     }
 

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

@@ -520,6 +520,7 @@ impl VmDriver {
             driver_name: DRIVER_NAME.to_string(),
             driver_version: openshell_core::VERSION.to_string(),
             default_image: self.config.default_image.clone(),
+            gateway_managed_lifecycle: true,
         }
     }
 

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

@@ -274,6 +274,8 @@ pub struct ComputeDriverInfoSnapshot {
     pub driver_name: String,
     /// Driver-reported implementation version from the startup capability snapshot.
     pub driver_version: String,
+    /// Whether the driver asks the gateway to reconcile compute across restarts.
+    pub gateway_managed_lifecycle: bool,
 }
 
 /// Interval between store-vs-backend reconciliation sweeps.
@@ -609,6 +611,7 @@ impl ComputeRuntime {
             name: driver_name.clone(),
             driver_name: capabilities.driver_name,
             driver_version: capabilities.driver_version,
+            gateway_managed_lifecycle: capabilities.gateway_managed_lifecycle,
         };
         let default_image = capabilities.default_image;
         let gateway_listener_requirements = match driver
@@ -2039,14 +2042,9 @@ 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 retained running intent. Kubernetes remains
-    /// cluster-owned.
+    /// Drivers request this sweep through their startup capability snapshot.
     async fn stop_persisted_sandboxes_on_shutdown(&self) -> Result<(), String> {
-        if !matches!(
-            self.driver_kind(),
-            Some(ComputeDriverKind::Docker | ComputeDriverKind::Podman | ComputeDriverKind::Vm)
-        ) {
+        if !self.driver_info.gateway_managed_lifecycle {
             return Ok(());
         }
 
@@ -2129,17 +2127,15 @@ impl ComputeRuntime {
     /// Reconcile running intent for local compute after a gateway restart.
     ///
     /// `StartSandbox` is idempotent, so call it for every persisted phase that
-    /// requires running compute on Docker, Podman, and VM. Stable stopped,
-    /// deleting, and error states are deliberately left alone.
+    /// requires running compute for drivers that request gateway-managed
+    /// lifecycle. Stable stopped, deleting, and error states are deliberately
+    /// left alone.
     ///
     /// Should be called once at gateway startup, before watchers spawn,
     /// 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 !matches!(
-            self.driver_kind(),
-            Some(ComputeDriverKind::Docker | ComputeDriverKind::Podman | ComputeDriverKind::Vm)
-        ) {
+        if !self.driver_info.gateway_managed_lifecycle {
             return Ok(());
         }
 
@@ -3910,6 +3906,7 @@ impl ComputeDriver for NoopTestDriver {
                 driver_name: "noop-test-driver".to_string(),
                 driver_version: "test".to_string(),
                 default_image: "openshell/sandbox:test".to_string(),
+                gateway_managed_lifecycle: false,
             },
         ))
     }
@@ -4050,6 +4047,7 @@ pub async fn new_test_runtime_with_driver(
             name: driver_name.to_string(),
             driver_name: driver_name.to_string(),
             driver_version: "test".to_string(),
+            gateway_managed_lifecycle: false,
         },
         driver_process: None,
         default_image: "openshell/sandbox:test".to_string(),
@@ -4212,6 +4210,7 @@ mod tests {
                 driver_name: "test-driver".to_string(),
                 driver_version: "test".to_string(),
                 default_image: "openshell/sandbox:test".to_string(),
+                gateway_managed_lifecycle: false,
             }))
         }
 
@@ -4529,6 +4528,7 @@ mod tests {
                 driver_name: "controlled-test-driver".to_string(),
                 driver_version: "test".to_string(),
                 default_image: "openshell/sandbox:test".to_string(),
+                gateway_managed_lifecycle: false,
             }))
         }
 
@@ -4731,6 +4731,7 @@ mod tests {
                 name: driver_name.to_string(),
                 driver_name: driver_name.to_string(),
                 driver_version: "test".to_string(),
+                gateway_managed_lifecycle: false,
             },
             driver_process: None,
             default_image: "openshell/sandbox:test".to_string(),
@@ -4746,6 +4747,15 @@ mod tests {
         }
     }
 
+    async fn test_runtime_with_gateway_managed_lifecycle(
+        driver: SharedComputeDriver,
+        driver_name: &str,
+    ) -> ComputeRuntime {
+        let mut runtime = test_runtime_for_driver(driver, driver_name).await;
+        runtime.driver_info.gateway_managed_lifecycle = true;
+        runtime
+    }
+
     fn register_test_supervisor_session(runtime: &ComputeRuntime, sandbox_id: &str) {
         let (tx, _rx) = mpsc::channel(1);
         let (shutdown_tx, _shutdown_rx) = oneshot::channel();
@@ -8126,7 +8136,8 @@ 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_with_gateway_managed_lifecycle(driver.clone(), "arbitrary").await;
 
         for (id, name, phase) in [
             ("sb-unspecified", "unspecified", SandboxPhase::Unspecified),
@@ -8185,7 +8196,8 @@ 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_with_gateway_managed_lifecycle(driver.clone(), "arbitrary").await;
         for (id, name) in [("sb-1", "one"), ("sb-2", "two")] {
             runtime
                 .store
@@ -8204,10 +8216,11 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn shutdown_stop_sweep_runs_for_each_local_driver() {
-        for driver_name in ["docker", "podman", "vm"] {
+    async fn shutdown_stop_sweep_runs_for_any_capable_driver() {
+        for driver_name in ["arbitrary", "docker"] {
             let driver = ControlledDriver::new();
-            let runtime = test_runtime_for_driver(driver.clone(), driver_name).await;
+            let runtime =
+                test_runtime_with_gateway_managed_lifecycle(driver.clone(), driver_name).await;
             runtime
                 .store
                 .put_message(&sandbox_record("sb-1", "sandbox", SandboxPhase::Ready))
@@ -8228,8 +8241,8 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn shutdown_stop_sweep_skips_kubernetes_and_extension_drivers() {
-        for driver_name in ["kubernetes", "extension"] {
+    async fn shutdown_stop_sweep_skips_drivers_without_capability() {
+        for driver_name in ["docker", "kubernetes", "extension"] {
             let driver = ControlledDriver::new();
             let runtime = test_runtime_for_driver(driver.clone(), driver_name).await;
             runtime
@@ -8254,7 +8267,8 @@ mod tests {
     #[tokio::test]
     async fn start_persisted_sandboxes_starts_running_phases() {
         let driver = ControlledDriver::new();
-        let runtime = test_runtime_for_driver(driver.clone(), "docker").await;
+        let runtime =
+            test_runtime_with_gateway_managed_lifecycle(driver.clone(), "arbitrary").await;
 
         for (id, name, phase) in [
             ("sb-unspecified", "unspecified", SandboxPhase::Unspecified),
@@ -8293,7 +8307,7 @@ mod tests {
     async fn start_persisted_sandboxes_marks_missing_backend_as_error() {
         let driver = ControlledDriver::new();
         driver.set_start_outcome(ControlledLifecycleOutcome::NotFound);
-        let runtime = test_runtime_for_driver(driver, "podman").await;
+        let runtime = test_runtime_with_gateway_managed_lifecycle(driver, "arbitrary").await;
 
         let sandbox = sandbox_record("sb-1", "missing", SandboxPhase::Ready);
         runtime.store.put_message(&sandbox).await.unwrap();
@@ -8323,7 +8337,7 @@ mod tests {
     async fn start_persisted_sandboxes_marks_failed_start_as_error() {
         let driver = ControlledDriver::new();
         driver.set_start_outcome(ControlledLifecycleOutcome::Error("runtime angry"));
-        let runtime = test_runtime_for_driver(driver, "vm").await;
+        let runtime = test_runtime_with_gateway_managed_lifecycle(driver, "arbitrary").await;
 
         let sandbox = sandbox_record("sb-1", "broken", SandboxPhase::Provisioning);
         runtime.store.put_message(&sandbox).await.unwrap();
@@ -8350,10 +8364,11 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn start_persisted_sandboxes_runs_for_each_local_driver() {
-        for driver_name in ["docker", "podman", "vm"] {
+    async fn start_persisted_sandboxes_runs_for_any_capable_driver() {
+        for driver_name in ["arbitrary", "docker"] {
             let driver = ControlledDriver::new();
-            let runtime = test_runtime_for_driver(driver.clone(), driver_name).await;
+            let runtime =
+                test_runtime_with_gateway_managed_lifecycle(driver.clone(), driver_name).await;
             let sandbox = sandbox_record("sb-1", "local", SandboxPhase::Ready);
             runtime.store.put_message(&sandbox).await.unwrap();
 
@@ -8368,8 +8383,8 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn start_persisted_sandboxes_skips_kubernetes_and_extension_drivers() {
-        for driver_name in ["kubernetes", "extension"] {
+    async fn start_persisted_sandboxes_skips_drivers_without_capability() {
+        for driver_name in ["docker", "kubernetes", "extension"] {
             let driver = ControlledDriver::new();
             let runtime = test_runtime_for_driver(driver.clone(), driver_name).await;
             let sandbox = sandbox_record("sb-1", "remote", SandboxPhase::Ready);
@@ -8596,6 +8611,7 @@ mod tests {
         let driver = FakeComputeDriver::new()
             .with_driver_name("fake-remote-driver")
             .with_default_image("openshell/sandbox:remote")
+            .with_gateway_managed_lifecycle()
             .with_gateway_listener_requirement(
                 "172.19.0.1:17670",
                 "external driver managed bridge",

crates/openshell-server/src/test_support.rs

@@ -74,6 +74,7 @@ struct FakeComputeDriverState {
     driver_name: String,
     driver_version: String,
     default_image: String,
+    gateway_managed_lifecycle: bool,
     gateway_listener_requirements: Vec<GatewayListenerRequirement>,
     gateway_listener_requirements_supported: bool,
     sandboxes: HashMap<String, DriverSandbox>,
@@ -95,6 +96,7 @@ impl FakeComputeDriver {
                 driver_name: "fake-compute-driver".to_string(),
                 driver_version: "test".to_string(),
                 default_image: "openshell/sandbox:test".to_string(),
+                gateway_managed_lifecycle: false,
                 gateway_listener_requirements: Vec::new(),
                 gateway_listener_requirements_supported: true,
                 sandboxes: HashMap::new(),
@@ -122,6 +124,12 @@ impl FakeComputeDriver {
         self
     }
 
+    #[must_use]
+    pub fn with_gateway_managed_lifecycle(self) -> Self {
+        self.with_state(|state| state.gateway_managed_lifecycle = true);
+        self
+    }
+
     #[must_use]
     pub fn with_gateway_listener_requirement(
         self,
@@ -241,6 +249,7 @@ impl ComputeDriver for FakeComputeDriver {
                 driver_name: state.driver_name.clone(),
                 driver_version: state.driver_version.clone(),
                 default_image: state.default_image.clone(),
+                gateway_managed_lifecycle: state.gateway_managed_lifecycle,
             }
         });
         Ok(Response::new(response))

proto/compute_driver.proto

@@ -75,6 +75,9 @@ message GetCapabilitiesResponse {
   string driver_version = 2;
   // Default sandbox image recommended by the driver.
   string default_image = 3;
+  // Whether the gateway should stop running sandbox compute during graceful
+  // shutdown and restart the retained running intent on startup.
+  bool gateway_managed_lifecycle = 6;
 }
 
 message GetGatewayListenerRequirementsRequest {}