fix(sandbox): finalize terminal delivery on disconnect

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

Author: drew

.agents/skills/openshell-cli/SKILL.md

@@ -260,8 +260,9 @@ Key flags:
 - `--editor vscode|cursor`: Open a remote editor after creation and keep the sandbox alive
 
 `--detach` adds no attachment grace period. When the canonical process exits,
-its terminal phase is reported immediately. A foreground create instead keeps
-ephemeral cleanup deferred until its active SSH connection closes naturally.
+its terminal phase is reported immediately. A foreground create declares one
+expected main-process SSH attachment; cleanup finalizes after that connection
+closes naturally.
 
 Do not combine `--upload` with a trailing main command. Uploads currently finish
 after the canonical process starts; create a scratch sandbox and use

.agents/skills/openshell-cli/cli-reference.md

@@ -226,8 +226,9 @@ previous runtime generation.
 | `--memory <QUANTITY>` | Memory limit (for example: `512Mi`, `4Gi`, `8G`) |
 
 `--detach` adds no attachment grace period: the sandbox reports the canonical
-process result immediately when it exits. Foreground creation defers ephemeral
-cleanup only while its active SSH connection drains and closes naturally.
+process result immediately when it exits. Foreground creation declares one
+expected main-process SSH attachment; cleanup finalizes after that connection
+drains and closes naturally.
 | `--driver-config-json <JSON>` | Experimental driver-keyed configuration object |
 | `--provider <NAME>` | Provider to attach (repeatable) |
 | `--policy <PATH>` | Custom policy YAML; overrides the built-in default and `OPENSHELL_SANDBOX_POLICY` |

architecture/gateway.md

@@ -28,12 +28,15 @@ identity.
 The live supervisor session is the readiness authority for its main-process
 instance. The supervisor reports its normalized result through the
 sandbox-authenticated `ReportMainProcessExit` RPC, and the gateway rejects
-results from stale instance IDs. The process supervisor keeps the main SSH
-session alive only when a foreground attachment is active at process exit. It
-durably reports the result immediately, sends the SSH exit status, and waits for
-the peer's SSH channel close before releasing deferred ephemeral cleanup.
-Detached commands have no attachment to drain, so they report their result and
-exit immediately without a grace period.
+results from stale instance IDs. Foreground creation carries a one-shot
+attachment intent to the process supervisor. The supervisor durably reports the
+result immediately, accepts that declared SSH attachment even when the process
+has already exited, sends the retained output and exit status, and waits for the
+peer's channel close before finalizing the result for ephemeral cleanup.
+Detached commands carry no attachment intent, so they finalize and exit
+immediately without a grace period. Finalization is persisted separately from
+the exit result; the gateway deletes an ephemeral sandbox only after the
+finalized supervisor session disconnects.
 
 ## Protocol and Auth
 

architecture/sandbox.md

@@ -482,10 +482,13 @@ engine with a gateway policy revision.
 - If the supervisor relay drops, the sandbox can keep running, but connect and
   exec operations fail until the supervisor registers again.
 - If the canonical main process exits, the supervisor durably reports the
-  normalized result immediately. When a foreground main attachment is active,
-  it sends the retained output and SSH exit status, waits for the peer's channel
-  close, and then releases deferred ephemeral cleanup. With no active
-  attachment, it exits without a grace period. Exit code 0 records
+  normalized result immediately. A foreground create declares a one-shot main
+  attachment, so the supervisor accepts it even after a fast process exits,
+  sends the retained output and SSH exit status, waits for the peer's channel
+  close, and then finalizes ephemeral cleanup. With no declared or active
+  attachment, it finalizes and exits without a grace period. The gateway waits
+  for that finalized supervisor session to disconnect before deleting an
+  ephemeral sandbox. Exit code 0 records
   `Completed/MainProcessCompleted`; nonzero and signal-normalized exits record
   `Error/MainProcessFailed`. Infrastructure failures also use `Error`, with a
   distinct condition reason and no fabricated canonical-process result. Runtime

crates/openshell-cli/src/run.rs

@@ -563,6 +563,11 @@ pub async fn sandbox_create(
         command.to_vec()
     };
     let persist = sandbox_should_persist(keep, forward.as_ref());
+    let create_detaches = detach
+        || (persist
+            && command.is_empty()
+            && (!std::io::stdin().is_terminal() || !std::io::stdout().is_terminal()));
+    let await_main_process_attachment = output == "table" && editor.is_none() && !create_detaches;
     let annotations = if persist {
         HashMap::new()
     } else {
@@ -586,6 +591,7 @@ pub async fn sandbox_create(
         labels,
         annotations,
         workspace: workspace.to_string(),
+        await_main_process_attachment,
     };
 
     let response = match client.create_sandbox(request).await {

crates/openshell-cli/tests/ensure_providers_integration.rs

@@ -88,6 +88,13 @@ impl OpenShell for TestOpenShell {
         Err(Status::unimplemented("not used by this test server"))
     }
 
+    async fn finalize_main_process_exit(
+        &self,
+        _request: tonic::Request<openshell_core::proto::FinalizeMainProcessExitRequest>,
+    ) -> Result<Response<openshell_core::proto::FinalizeMainProcessExitResponse>, Status> {
+        Err(Status::unimplemented("not used by this test server"))
+    }
+
     async fn get_current_user(
         &self,
         _request: tonic::Request<openshell_core::proto::GetCurrentUserRequest>,

crates/openshell-cli/tests/mtls_integration.rs

@@ -41,6 +41,13 @@ impl OpenShell for TestOpenShell {
         Err(Status::unimplemented("not used by this test server"))
     }
 
+    async fn finalize_main_process_exit(
+        &self,
+        _request: tonic::Request<openshell_core::proto::FinalizeMainProcessExitRequest>,
+    ) -> Result<Response<openshell_core::proto::FinalizeMainProcessExitResponse>, Status> {
+        Err(Status::unimplemented("not used by this test server"))
+    }
+
     async fn get_current_user(
         &self,
         _request: tonic::Request<openshell_core::proto::GetCurrentUserRequest>,

crates/openshell-cli/tests/provider_commands_integration.rs

@@ -106,6 +106,13 @@ impl OpenShell for TestOpenShell {
         Err(Status::unimplemented("not used by this test server"))
     }
 
+    async fn finalize_main_process_exit(
+        &self,
+        _request: tonic::Request<openshell_core::proto::FinalizeMainProcessExitRequest>,
+    ) -> Result<Response<openshell_core::proto::FinalizeMainProcessExitResponse>, Status> {
+        Err(Status::unimplemented("not used by this test server"))
+    }
+
     async fn get_current_user(
         &self,
         _request: tonic::Request<openshell_core::proto::GetCurrentUserRequest>,

crates/openshell-cli/tests/sandbox_create_lifecycle_integration.rs

@@ -69,6 +69,13 @@ impl OpenShell for TestOpenShell {
         Err(Status::unimplemented("not used by this test server"))
     }
 
+    async fn finalize_main_process_exit(
+        &self,
+        _request: tonic::Request<openshell_core::proto::FinalizeMainProcessExitRequest>,
+    ) -> Result<Response<openshell_core::proto::FinalizeMainProcessExitResponse>, Status> {
+        Err(Status::unimplemented("not used by this test server"))
+    }
+
     async fn get_current_user(
         &self,
         _request: tonic::Request<openshell_core::proto::GetCurrentUserRequest>,
@@ -1349,6 +1356,35 @@ async fn sandbox_create_persists_exact_trailing_argv_as_main_process() {
         .expect("sandbox spec should be persisted at create time");
     assert_eq!(spec.command, command);
     assert!(!spec.tty);
+    assert!(requests[0].await_main_process_attachment);
+}
+
+#[tokio::test]
+async fn detached_command_does_not_declare_main_process_attachment() {
+    let server = run_server().await;
+    let fake_ssh_dir = tempfile::tempdir().unwrap();
+    let xdg_dir = tempfile::tempdir().unwrap();
+    let _env = test_env(&fake_ssh_dir, &xdg_dir);
+    let tls = test_tls(&server);
+    install_fake_ssh(&fake_ssh_dir);
+
+    run::sandbox_create(
+        &server.endpoint,
+        "openshell",
+        run::SandboxCreateConfig {
+            name: Some("detached-main"),
+            command: &["echo".into(), "OK".into()],
+            detach: true,
+            ..test_config()
+        },
+        "default",
+        &tls,
+    )
+    .await
+    .expect("detached sandbox create should succeed");
+
+    let requests = create_requests(&server).await;
+    assert!(!requests[0].await_main_process_attachment);
 }
 
 #[tokio::test]

crates/openshell-cli/tests/sandbox_name_fallback_integration.rs

@@ -56,6 +56,13 @@ impl OpenShell for TestOpenShell {
         Err(Status::unimplemented("not used by this test server"))
     }
 
+    async fn finalize_main_process_exit(
+        &self,
+        _request: tonic::Request<openshell_core::proto::FinalizeMainProcessExitRequest>,
+    ) -> Result<Response<openshell_core::proto::FinalizeMainProcessExitResponse>, Status> {
+        Err(Status::unimplemented("not used by this test server"))
+    }
+
     async fn get_current_user(
         &self,
         _request: tonic::Request<openshell_core::proto::GetCurrentUserRequest>,