refactor(supervisor): name hosted lifetimes sandbox instances

A sandbox instance is one running generation of a stable Sandbox
resource. Gateway transport connections and the gateway supervisor
sessions they carry can reconnect within one instance, so the hosted
object, its configuration, controls, host, and per-instance network,
denial, and token-grant state now use the sandbox instance name.

Rename session_host to sandbox_instance_host, run_session to
run_sandbox_instance, and SessionConfig, SessionControls, SessionHost,
and related hosted types to their SandboxInstance equivalents. Gateway
supervisor sessions, SSH sessions, and authentication session types
keep their names. No wire, configuration, or lifecycle behavior
changes.

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

Author: drew

crates/openshell-core/src/grpc_client.rs

@@ -5,7 +5,7 @@
 //! `OpenShell` server.
 //!
 //! Every request carries a sandbox bearer credential in the `Authorization`
-//! header. Each supervisor session owns its [`GatewayCredentials`], usually
+//! header. Each sandbox instance owns its [`GatewayCredentials`], usually
 //! built from the trusted launch bundle with
 //! [`GatewayCredentials::from_auth_bundle`]. Diagnostic tools can instead
 //! resolve a token with [`GatewayCredentials::from_environment`] from one of:
@@ -16,8 +16,8 @@
 //!    caller exchanges it for a gateway JWT via `IssueSandboxToken`.
 //!
 //! Callers reach the gateway through a [`GatewayEndpoint`], which pairs the
-//! URL with one session's credentials. No credential is installed
-//! process-wide, so sessions hosted by one supervisor process cannot use or
+//! URL with one sandbox instance's credentials. No credential is installed
+//! process-wide, so instances hosted by one supervisor process cannot use or
 //! rotate each other's identity.
 
 use std::collections::HashMap;
@@ -65,7 +65,7 @@ pub const MAX_SUPERVISOR_STREAM_MESSAGE_BYTES: usize = 9 * 1024 * 1024;
 
 /// Shared, refreshable Bearer header. All [`AuthInterceptor`] clones read
 /// the same slot, so the renewal task can replace the token in place without
-/// rebuilding the channel. `None` means the owning session revoked it.
+/// rebuilding the channel. `None` means the owning sandbox instance revoked it.
 type TokenSlot = Arc<RwLock<Option<AsciiMetadataValue>>>;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -75,7 +75,7 @@ enum TokenSource {
     K8sServiceAccount,
 }
 
-/// Gateway credentials owned by one supervisor session.
+/// Gateway credentials owned by one sandbox instance.
 ///
 /// Clients built from a [`GatewayEndpoint`] read only these slots, and the
 /// renewal task started by the first connection updates only them. Dropping
@@ -200,7 +200,7 @@ impl GatewayCredentials {
     }
 
     /// Start the renewal task once for these credentials, on the caller's
-    /// runtime, so a hosted session's renewal stops with that session.
+    /// runtime, so a hosted sandbox instance's renewal stops with that instance.
     fn start_renewal(&self, channel: &AuthedChannel, plain_channel: &Channel, endpoint: &str) {
         let mut renewal = self
             .inner
@@ -239,14 +239,16 @@ impl GatewayCredentials {
             .bearer
             .write()
             .unwrap_or_else(std::sync::PoisonError::into_inner);
-        // A revoked session must not be revived by an in-flight response.
+        // Revoked instance credentials must not be revived by an in-flight
+        // response.
         if slot.is_some() {
             *slot = Some(bearer);
         }
     }
 }
 
-/// The gateway URL a session uses, paired with that session's credentials.
+/// The gateway URL a sandbox instance uses, paired with that instance's
+/// credentials.
 #[derive(Clone)]
 pub struct GatewayEndpoint {
     url: Arc<str>,
@@ -271,7 +273,7 @@ impl GatewayEndpoint {
         &self.credentials
     }
 
-    /// Reach another gateway address with the same session credentials.
+    /// Reach another gateway address with the same sandbox instance credentials.
     #[must_use]
     pub fn with_url(&self, url: impl Into<Arc<str>>) -> Self {
         Self::new(url, self.credentials.clone())
@@ -357,7 +359,9 @@ impl tonic::service::Interceptor for AuthInterceptor {
             .read()
             .unwrap_or_else(std::sync::PoisonError::into_inner)
             .clone()
-            .ok_or_else(|| Status::unauthenticated("gateway session credentials were revoked"))?;
+            .ok_or_else(|| {
+                Status::unauthenticated("sandbox instance gateway credentials were revoked")
+            })?;
         req.metadata_mut().insert("authorization", bearer);
         #[cfg(feature = "trace-context")]
         let req =
@@ -458,11 +462,14 @@ impl Drop for ClientSpanStatus {
     }
 }
 
-/// Build a Bearer-authenticated channel to the gateway with one session's
-/// credentials. The first connection starts that session's renewal task.
+/// Build a Bearer-authenticated channel to the gateway with one sandbox
+/// instance's credentials. The first connection starts that instance's
+/// renewal task.
 async fn connect_channel(gateway: &GatewayEndpoint) -> Result<AuthedChannel> {
     if gateway.credentials.is_revoked() {
-        return Err(miette::miette!("gateway session credentials were revoked"));
+        return Err(miette::miette!(
+            "sandbox instance gateway credentials were revoked"
+        ));
     }
     let channel = build_plain_channel(gateway.url()).await?;
     let intercepted = InterceptedService::new(
@@ -577,8 +584,9 @@ pub async fn report_provider_readiness(
         .into_diagnostic()
 }
 
-/// Slots and transport retained by one session's renewal task. It holds no
-/// reference to [`GatewayCredentials`], so dropping them still stops it.
+/// Slots and transport retained by one sandbox instance's renewal task. It
+/// holds no reference to [`GatewayCredentials`], so dropping them still stops
+/// it.
 struct RenewalTarget {
     channel: AuthedChannel,
     bearer: TokenSlot,
@@ -590,10 +598,10 @@ struct RenewalTarget {
 }
 
 /// Background task that renews the sandbox JWT at ~80% of its remaining
-/// lifetime. The new token replaces the value in the session's slot, so all
-/// in-flight and future clients of that session pick it up on their next
-/// request. The loop never panics: every failure is logged and re-attempted
-/// after a bounded backoff.
+/// lifetime. The new token replaces the value in the sandbox instance's slot,
+/// so all in-flight and future clients of that instance pick it up on their
+/// next request. The loop never panics: every failure is logged and
+/// re-attempted after a bounded backoff.
 async fn refresh_token_loop(target: RenewalTarget) {
     let RenewalTarget {
         channel,
@@ -832,7 +840,7 @@ fn compute_refresh_delay(slot: &TokenSlot) -> Option<Duration> {
         let current = slot
             .read()
             .unwrap_or_else(std::sync::PoisonError::into_inner);
-        // A revoked session has nothing to renew.
+        // Revoked instance credentials have nothing to renew.
         current.as_ref()?.to_str().ok().map(str::to_string)
     }
     .unwrap_or_default();
@@ -1058,7 +1066,7 @@ mod workspace_tests {
     }
 }
 
-/// Connect to the `OpenShell` server with one session's credentials.
+/// Connect to the `OpenShell` server with one sandbox instance's credentials.
 async fn connect(gateway: &GatewayEndpoint) -> Result<OpenShellClient<AuthedChannel>> {
     let channel = connect_channel(gateway).await?;
     Ok(OpenShellClient::new(channel))
@@ -1711,7 +1719,8 @@ mod token_grant_exchange_tests {
 #[derive(Clone)]
 pub struct CachedOpenShellClient {
     client: OpenShellClient<AuthedChannel>,
-    /// Session credentials rotated alongside extension credentials.
+    /// Sandbox instance gateway credentials rotated alongside extension
+    /// credentials.
     credentials: GatewayCredentials,
     workspace: Arc<tokio::sync::OnceCell<String>>,
     /// Extension credentials for this supervisor. Cloning the client shares

crates/openshell-ocsf/src/builders/mod.rs

@@ -200,10 +200,11 @@ pub struct EventContext {
     pub origin: EventOrigin,
 }
 
-/// Event context borrowed from the caller or shared by a hosted session.
+/// Event context borrowed from the caller or shared by a hosted sandbox
+/// instance.
 ///
-/// Builders accept either form, so events attributed to a hosted supervisor
-/// session need not leak a `'static` context for each session.
+/// Builders accept either form, so events attributed to a hosted sandbox
+/// instance need not leak a `'static` context for each instance.
 #[derive(Debug, Clone)]
 pub enum ContextRef<'a> {
     Borrowed(&'a EventContext),

crates/openshell-ocsf/src/ctx.rs

@@ -1,11 +1,11 @@
 // SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-//! Process-wide and session-bound [`EventContext`].
+//! Process-wide and sandbox-instance-bound [`EventContext`].
 //!
 //! A dedicated supervisor initialises the process-wide context once via
-//! [`set_ctx`]. A process hosting several supervisor sessions instead binds
-//! each session's context to the threads of that session's runtime with
+//! [`set_ctx`]. A process hosting several sandbox instances instead binds
+//! each instance's context to the threads of that instance's runtime with
 //! [`bind_thread_ctx`]; a bound context takes precedence. [`ctx`] falls back
 //! to a default context when neither is set (e.g. unit tests that exercise
 //! builders without booting the sandbox).
@@ -28,7 +28,7 @@ static OCSF_CTX_FALLBACK: LazyLock<EventContext> = LazyLock::new(|| EventContext
 });
 
 std::thread_local! {
-    /// Context of the hosted session whose runtime owns this thread.
+    /// Context of the hosted sandbox instance whose runtime owns this thread.
     static THREAD_CTX: RefCell<Option<Arc<EventContext>>> = const { RefCell::new(None) };
 }
 
@@ -40,16 +40,17 @@ pub fn set_ctx(ctx: EventContext) -> bool {
     OCSF_CTX.set(ctx).is_ok()
 }
 
-/// Attribute events emitted on the calling thread to one hosted session.
+/// Attribute events emitted on the calling thread to one hosted sandbox
+/// instance.
 ///
-/// Session runtimes bind every thread they start; `None` unbinds it.
+/// Instance runtimes bind every thread they start; `None` unbinds it.
 pub fn bind_thread_ctx(ctx: Option<Arc<EventContext>>) {
     THREAD_CTX.with(|current| *current.borrow_mut() = ctx);
 }
 
 /// Return the context for events emitted on the calling thread.
 ///
-/// A session-bound context wins over the process-wide one. Falls back to a
+/// An instance-bound context wins over the process-wide one. Falls back to a
 /// default context if neither is set.
 #[must_use]
 pub fn ctx() -> ContextRef<'static> {

crates/openshell-ocsf/src/tracing_layers/jsonl_layer.rs

@@ -16,10 +16,10 @@ use tracing_subscriber::layer::Context;
 use crate::format::downgrade::downgrade_event;
 use crate::tracing_layers::event_bridge::{OCSF_TARGET, clone_current_event};
 
-/// OCSF JSON output settings owned by one hosted supervisor session.
+/// OCSF JSON output settings owned by one hosted sandbox instance.
 ///
-/// Sessions apply their own `ocsf_json_enabled` and schema-version settings
-/// to these values. Binding them to the session's runtime threads makes every
+/// Instances apply their own `ocsf_json_enabled` and schema-version settings
+/// to these values. Binding them to the instance's runtime threads makes every
 /// [`OcsfJsonlLayer`] use them for events those threads emit.
 #[derive(Clone, Debug, Default)]
 pub struct OcsfJsonSettings {
@@ -32,7 +32,8 @@ std::thread_local! {
         const { std::cell::RefCell::new(None) };
 }
 
-/// Apply one hosted session's JSON settings to events emitted on this thread.
+/// Apply one hosted sandbox instance's JSON settings to events emitted on this
+/// thread.
 pub fn bind_thread_json_settings(settings: Option<OcsfJsonSettings>) {
     THREAD_JSON_SETTINGS.with(|current| *current.borrow_mut() = settings);
 }
@@ -111,9 +112,9 @@ where
             return;
         }
 
-        // A hosted session's settings replace the process-wide ones.
-        let session = THREAD_JSON_SETTINGS.with(|current| current.borrow().clone());
-        let (enabled, target_version) = session.as_ref().map_or(
+        // A hosted sandbox instance's settings replace the process-wide ones.
+        let instance = THREAD_JSON_SETTINGS.with(|current| current.borrow().clone());
+        let (enabled, target_version) = instance.as_ref().map_or(
             (self.enabled.as_ref(), self.target_version.as_ref()),
             |settings| (Some(&settings.enabled), Some(&settings.target_version)),
         );

crates/openshell-otel/src/propagation.rs

@@ -124,8 +124,8 @@ pub fn set_parent_from_environment(span: &tracing::Span) {
 /// Parent `span` under an explicit W3C `traceparent` and `tracestate`.
 ///
 /// A process supervising several sandboxes receives each launch's context
-/// with its session instead of through process environment. Leaves `span`
-/// unchanged when the values carry no valid context.
+/// with its sandbox instance instead of through process environment. Leaves
+/// `span` unchanged when the values carry no valid context.
 pub fn set_parent_from_trace_context(
     span: &tracing::Span,
     traceparent: Option<&str>,

crates/openshell-supervisor-network/README.md

@@ -15,14 +15,14 @@ default features, so this instrumentation does not
 require the compute runtime or Unix-only sandbox library. It is a development
 dependency only.
 
-## Session inputs
+## Sandbox instance inputs
 
-`run_networking` takes a `NetworkSession` with the sandbox identity, the
-session's `GatewayEndpoint`, the SPIFFE Workload API socket for provider token
-grants, the `policy.local` denial source, and proxy CA files. None of these
-are read from the process environment, so one process can run several
-sessions. Each session owns its provider token cache and HTTP client; a token
-acquired for one sandbox is never served to another. Without a Workload API
-socket, token grants fail closed. A process hosting several sessions serves
-`/v1/denials` from a per-session `SessionDenialLog` instead of the shared
-shorthand log files.
+`run_networking` takes a `SandboxInstanceNetwork` with the sandbox identity,
+the sandbox instance's `GatewayEndpoint`, the SPIFFE Workload API socket for
+provider token grants, the `policy.local` denial source, and proxy CA files.
+None of these are read from the process environment, so one process can run
+several sandbox instances. Each instance owns its provider token cache and
+HTTP client; a token acquired for one sandbox is never served to another.
+Without a Workload API socket, token grants fail closed. A process hosting
+several instances serves `/v1/denials` from a per-instance
+`SandboxInstanceDenialLog` instead of the shared shorthand log files.

crates/openshell-supervisor-network/src/l7/token_grant_injection.rs

@@ -53,14 +53,14 @@ pub trait TokenGrantResolver: Send + Sync {
     ) -> Pin<Box<dyn Future<Output = Result<String, TokenGrantFailure>> + Send + 'a>>;
 }
 
-/// Resolves provider tokens through one session's authenticated grant flow.
+/// Resolves provider tokens through one sandbox instance's authenticated grant flow.
 pub struct SpiffeTokenGrantResolver {
-    grants: crate::token_grant::SessionTokenGrants,
+    grants: crate::token_grant::SandboxInstanceTokenGrants,
 }
 
 impl SpiffeTokenGrantResolver {
     #[must_use]
-    pub fn new(grants: crate::token_grant::SessionTokenGrants) -> Self {
+    pub fn new(grants: crate::token_grant::SandboxInstanceTokenGrants) -> Self {
         Self { grants }
     }
 }

crates/openshell-supervisor-network/src/policy_local.rs

@@ -84,18 +84,18 @@ const SHORTHAND_LOG_PREFIX: &str = "openshell.";
 /// log entry (very long URL path, etc.) cannot blow up the response.
 const MAX_DENIAL_LINE_BYTES: usize = 4096;
 
-/// Most recent denial lines retained for one hosted session.
-const MAX_SESSION_DENIAL_LINES: usize = 256;
+/// Most recent denial lines retained for one hosted sandbox instance.
+const MAX_INSTANCE_DENIAL_LINES: usize = 256;
 
 /// Where `/v1/denials` reads this sandbox's recent denials.
 #[derive(Clone, Debug)]
 pub enum DenialLogSource {
     /// Shorthand log files written by a supervisor process that serves one
     /// sandbox.
     ShorthandFiles(PathBuf),
-    /// Denials recorded for this session alone. A process hosting several
+    /// Denials recorded for this sandbox instance alone. A process hosting several
     /// sandboxes cannot expose its shared log files to any one of them.
-    Session(SessionDenialLog),
+    SandboxInstance(SandboxInstanceDenialLog),
 }
 
 impl Default for DenialLogSource {
@@ -104,27 +104,27 @@ impl Default for DenialLogSource {
     }
 }
 
-/// Bounded recent OCSF denial lines recorded for one hosted session.
+/// Bounded recent OCSF denial lines recorded for one hosted sandbox instance.
 #[derive(Clone, Default)]
-pub struct SessionDenialLog {
+pub struct SandboxInstanceDenialLog {
     lines: Arc<std::sync::Mutex<std::collections::VecDeque<String>>>,
 }
 
-impl std::fmt::Debug for SessionDenialLog {
+impl std::fmt::Debug for SandboxInstanceDenialLog {
     fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         let retained = self
             .lines
             .lock()
             .unwrap_or_else(std::sync::PoisonError::into_inner)
             .len();
         formatter
-            .debug_struct("SessionDenialLog")
+            .debug_struct("SandboxInstanceDenialLog")
             .field("retained", &retained)
             .finish()
     }
 }
 
-impl SessionDenialLog {
+impl SandboxInstanceDenialLog {
     /// Retain `line` when it is a rendered OCSF denial; ignore anything else.
     pub fn record(&self, line: &str) {
         let line = line.trim_end();
@@ -135,7 +135,7 @@ impl SessionDenialLog {
             .lines
             .lock()
             .unwrap_or_else(std::sync::PoisonError::into_inner);
-        if lines.len() == MAX_SESSION_DENIAL_LINES {
+        if lines.len() == MAX_INSTANCE_DENIAL_LINES {
             lines.pop_front();
         }
         lines.push_back(line.to_string());
@@ -227,7 +227,7 @@ impl PolicyLocalContext {
         self
     }
 
-    /// The session's provider token grant resolver, absent when grants are
+    /// The sandbox instance's provider token grant resolver, absent when grants are
     /// unavailable and must fail closed.
     pub(crate) fn token_grant_resolver(&self) -> Option<Arc<dyn TokenGrantResolver>> {
         self.token_grants.clone()
@@ -425,7 +425,7 @@ async fn recent_denials_response(
     let limit = parse_last_query(query).unwrap_or(DEFAULT_DENIALS_LIMIT);
     let log_dir = match &ctx.denials {
         DenialLogSource::ShorthandFiles(log_dir) => log_dir.clone(),
-        DenialLogSource::Session(log) => {
+        DenialLogSource::SandboxInstance(log) => {
             return (
                 200,
                 serde_json::json!({