microsandbox-rb 0.5.9 → 0.5.10

data/ext/microsandbox/extconf.rb

@@ -13,12 +13,16 @@ MSRV = Gem::Version.new("1.91")
 rustc_version = begin
   out = `rustc --version 2>/dev/null`
   out[/\d+\.\d+(\.\d+)?/] && Gem::Version.new(out[/\d+\.\d+(\.\d+)?/])
-rescue StandardError
+rescue
   nil
 end
 
 if rustc_version && rustc_version < MSRV
-  which_rustc = (`which rustc 2>/dev/null`.strip rescue "")
+  which_rustc = begin
+    `which rustc 2>/dev/null`.strip
+  rescue
+    ""
+  end
   abort(<<~MSG)
 
     [microsandbox-rb] Rust #{rustc_version} is too old — the embedded core requires rustc >= #{MSRV}.

data/ext/microsandbox/src/backend.rs

@@ -0,0 +1,170 @@
+//! Backend routing: the ambient process-wide backend and its selection surface.
+//!
+//! Mirrors the official Python (`sdk/python/src/lib.rs`) and Node
+//! (`sdk/node-ts/native/runtime_config.rs`) bindings. As of upstream v0.5.8
+//! (PR #754) every operation routes through a [`microsandbox::Backend`]: the
+//! ambient default is a lazily-initialised [`microsandbox::LocalBackend`], and
+//! callers may install a different default process-wide or for a scoped block.
+//!
+//! Local-only operations (image cache, aggregate metrics, `msb` path) need a
+//! concrete `&LocalBackend`; [`local_backend`] resolves the ambient default and
+//! downcasts it, surfacing a clean [`MicrosandboxError::Unsupported`] under a
+//! cloud backend (exactly as the pyo3 `resolve_local` helper does). The backend
+//! selection setters (`set_default_backend` / `with_backend` push-pop /
+//! `default_backend_kind`) deliberately expose only a `kind`/`url`/`api_key`/
+//! `profile` facade — the raw `LocalBackend`/`CloudBackend` builders stay hidden,
+//! matching Python and Node.
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::{Arc, Mutex, OnceLock};
+
+use magnus::{function, prelude::*, Error, RModule, Ruby};
+use microsandbox::{Backend, MicrosandboxError};
+
+use crate::error;
+use crate::runtime::block_on;
+
+/// Resolve the ambient default backend, requiring it to be local.
+///
+/// Returns the `Arc<dyn Backend>` so the caller can keep it alive while
+/// borrowing `&LocalBackend` from it (`as_local()` borrows the `Arc`). Pure
+/// Rust — safe to call inside `block_on` (no Ruby C API), and it returns a raw
+/// `MicrosandboxError` so the Ruby-exception mapping happens *after* `block_on`
+/// re-acquires the GVL. Cloud backends yield `Unsupported`, mirroring pyo3's
+/// `resolve_local`.
+pub fn local_backend() -> Result<Arc<dyn Backend>, MicrosandboxError> {
+    let backend = microsandbox::default_backend();
+    if backend.as_local().is_some() {
+        Ok(backend)
+    } else {
+        Err(MicrosandboxError::Unsupported {
+            feature: "this operation requires a local backend".into(),
+            available_when: "with the local backend (the default)".into(),
+        })
+    }
+}
+
+/// Resolve the ambient backend (requiring it to be local), then run `op` with a
+/// borrowed `&LocalBackend` inside the blocking runtime, mapping any core error
+/// to a Ruby exception. Local-only operations (image cache, aggregate metrics)
+/// share this instead of repeating the resolve/downcast dance; the single
+/// `as_local()` unwrap is provably infallible — [`local_backend`] just checked
+/// it and returns the same `Arc` kept alive for the borrow — so it lives here
+/// once rather than at every call site.
+pub fn with_local_backend<T>(
+    op: impl AsyncFnOnce(&microsandbox::LocalBackend) -> Result<T, MicrosandboxError>,
+) -> Result<T, Error> {
+    block_on(async move {
+        let backend = local_backend()?;
+        let local = backend
+            .as_local()
+            .expect("local_backend() guarantees a local backend");
+        op(local).await
+    })
+    .map_err(error::to_ruby)
+}
+
+/// Build an `Arc<dyn Backend>` from the SDK facade. Ported from pyo3
+/// `build_backend` (`sdk/python/src/lib.rs`) / node `build_backend`. Synchronous
+/// (no network I/O): cloud construction only builds the HTTP client. Runs on the
+/// Ruby thread with the GVL held, so it may map errors to Ruby directly.
+fn build_backend(
+    kind: String,
+    url: Option<String>,
+    api_key: Option<String>,
+    profile: Option<String>,
+) -> Result<Arc<dyn Backend>, Error> {
+    match kind.trim().to_ascii_lowercase().as_str() {
+        "local" => Ok(Arc::new(microsandbox::LocalBackend::lazy())),
+        "cloud" => {
+            let cloud = match profile {
+                Some(profile) => microsandbox::CloudBackend::from_profile(&profile),
+                None => match (url, api_key) {
+                    (Some(url), Some(api_key)) => microsandbox::CloudBackend::new(url, api_key),
+                    _ => {
+                        return Err(error::to_ruby(MicrosandboxError::InvalidConfig(
+                            "cloud backend requires url + api_key or profile".into(),
+                        )))
+                    }
+                },
+            }
+            .map_err(error::to_ruby)?;
+            Ok(Arc::new(cloud))
+        }
+        other => Err(error::to_ruby(MicrosandboxError::InvalidConfig(format!(
+            "backend kind must be 'local' or 'cloud', got {other:?}"
+        )))),
+    }
+}
+
+/// Install a process-wide default backend. Synchronous (an `RwLock` write) — no
+/// `block_on`. Mirrors Python `set_default_backend` / Node `setDefaultBackend`.
+fn set_default_backend(
+    kind: String,
+    url: Option<String>,
+    api_key: Option<String>,
+    profile: Option<String>,
+) -> Result<(), Error> {
+    microsandbox::set_default_backend(build_backend(kind, url, api_key, profile)?);
+    Ok(())
+}
+
+// Scoped-override registry. `with_backend` in Ruby is a swap-and-restore around
+// a synchronous block, so it cannot use the core's async task-local
+// `with_backend`. We mirror Node's process-wide push/pop token registry: push
+// swaps the default and stores the previous backend under a fresh token; pop
+// restores it. The Ruby wrapper drives this through an `ensure` block.
+static NEXT_BACKEND_SCOPE: AtomicU32 = AtomicU32::new(1);
+static BACKEND_SCOPES: OnceLock<Mutex<HashMap<u32, Arc<dyn Backend>>>> = OnceLock::new();
+
+fn backend_scopes() -> &'static Mutex<HashMap<u32, Arc<dyn Backend>>> {
+    BACKEND_SCOPES.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// Swap in a new default backend and return a token for restoring the previous
+/// one via [`pop_default_backend`]. Process-wide while active (not task-local):
+/// concurrent Ruby threads observe the swapped default.
+fn push_default_backend(
+    kind: String,
+    url: Option<String>,
+    api_key: Option<String>,
+    profile: Option<String>,
+) -> Result<u32, Error> {
+    let previous = microsandbox::swap_default_backend(build_backend(kind, url, api_key, profile)?);
+    let token = NEXT_BACKEND_SCOPE.fetch_add(1, Ordering::Relaxed);
+    backend_scopes()
+        .lock()
+        .map_err(|_| error::base_error("backend scope registry poisoned"))?
+        .insert(token, previous);
+    Ok(token)
+}
+
+/// Restore the backend saved by [`push_default_backend`].
+fn pop_default_backend(token: u32) -> Result<(), Error> {
+    let previous = backend_scopes()
+        .lock()
+        .map_err(|_| error::base_error("backend scope registry poisoned"))?
+        .remove(&token)
+        .ok_or_else(|| error::base_error("unknown backend scope token"))?;
+    microsandbox::set_default_backend(previous);
+    Ok(())
+}
+
+/// The active default backend kind: `"local"` or `"cloud"`. First call lazily
+/// resolves the env/profile/config ladder. Synchronous (an `RwLock` read).
+fn default_backend_kind() -> String {
+    match microsandbox::default_backend().kind() {
+        microsandbox::BackendKind::Local => "local",
+        microsandbox::BackendKind::Cloud => "cloud",
+    }
+    .to_string()
+}
+
+pub fn define(_ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    native.define_singleton_method("set_default_backend", function!(set_default_backend, 4))?;
+    native.define_singleton_method("push_default_backend", function!(push_default_backend, 4))?;
+    native.define_singleton_method("pop_default_backend", function!(pop_default_backend, 1))?;
+    native.define_singleton_method("default_backend_kind", function!(default_backend_kind, 0))?;
+    Ok(())
+}

data/ext/microsandbox/src/error.rs

@@ -28,6 +28,12 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         MetricsDisabled(_) => "MetricsDisabledError",
         MetricsUnavailable(_) => "MetricsUnavailableError",
         AgentClient(AgentClientError::UnsupportedOperation { .. }) => "UnsupportedOperationError",
+        // Backend routing (v0.5.8 / PR #754). `Unsupported` is reachable on the
+        // local backend too (e.g. `Volume::path` on a cloud volume, snapshot
+        // ops), so it must map even for local-only use. Distinct from the agent
+        // client's `UnsupportedOperation` above.
+        CloudHttp { .. } => "CloudHttpError",
+        Unsupported { .. } => "UnsupportedError",
         _ => "Error",
     }
 }

data/ext/microsandbox/src/image.rs

@@ -8,8 +8,8 @@
 use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
 use microsandbox::image::{Image, ImageDetail, ImageHandle, ImagePruneReport};
 
-use crate::error;
-use crate::runtime::{block_on, ruby};
+use crate::backend::with_local_backend;
+use crate::runtime::ruby;
 
 fn handle_to_hash(h: &ImageHandle) -> RHash {
     let hash = ruby().hash_new();
@@ -76,12 +76,12 @@ fn report_to_hash(report: ImagePruneReport) -> RHash {
 }
 
 fn get(reference: String) -> Result<RHash, Error> {
-    let handle = block_on(Image::get(&reference)).map_err(error::to_ruby)?;
+    let handle = with_local_backend(async |local| Image::get(local, &reference).await)?;
     Ok(handle_to_hash(&handle))
 }
 
 fn list() -> Result<RArray, Error> {
-    let handles = block_on(Image::list()).map_err(error::to_ruby)?;
+    let handles = with_local_backend(async |local| Image::list(local).await)?;
     let arr = ruby().ary_new();
     for h in handles.iter() {
         arr.push(handle_to_hash(h))?;
@@ -90,16 +90,16 @@ fn list() -> Result<RArray, Error> {
 }
 
 fn inspect(reference: String) -> Result<RHash, Error> {
-    let detail = block_on(Image::inspect(&reference)).map_err(error::to_ruby)?;
+    let detail = with_local_backend(async |local| Image::inspect(local, &reference).await)?;
     Ok(detail_to_hash(detail))
 }
 
 fn remove(reference: String, force: bool) -> Result<(), Error> {
-    block_on(Image::remove(&reference, force)).map_err(error::to_ruby)
+    with_local_backend(async |local| Image::remove(local, &reference, force).await)
 }
 
 fn prune() -> Result<RHash, Error> {
-    let report = block_on(Image::prune()).map_err(error::to_ruby)?;
+    let report = with_local_backend(async |local| Image::prune(local).await)?;
     Ok(report_to_hash(report))
 }
 

data/ext/microsandbox/src/lib.rs

@@ -9,6 +9,7 @@
 //! surface is the pure-Ruby layer in `lib/microsandbox/`.
 
 mod agent;
+mod backend;
 mod conv;
 mod error;
 mod exec;
@@ -31,8 +32,9 @@ fn version() -> String {
 /// Ruby Hash. Mirrors the official `all_sandbox_metrics` / `allSandboxMetrics`
 /// helpers (Python/Node/Go).
 fn all_sandbox_metrics() -> Result<RHash, Error> {
-    let map =
-        runtime::block_on(microsandbox::sandbox::all_sandbox_metrics()).map_err(error::to_ruby)?;
+    let map = backend::with_local_backend(async |local| {
+        microsandbox::sandbox::all_sandbox_metrics(local).await
+    })?;
     let hash = runtime::ruby().hash_new();
     for (name, metrics) in &map {
         hash.aset(name.as_str(), sandbox::metrics_to_hash(metrics))?;
@@ -55,9 +57,25 @@ fn set_runtime_msb_path(path: String) {
     microsandbox::config::set_sdk_msb_path(path);
 }
 
-/// The currently-resolved `msb` runtime path.
+/// Override the resolved `libkrunfw` path (SDK tier of the resolver). Set-once
+/// per process; the `MSB_LIBKRUNFW_PATH` env var still takes precedence. Mirrors
+/// `set_runtime_msb_path` for the libkrunfw shared library.
+fn set_runtime_libkrunfw_path(path: String) {
+    microsandbox::config::set_sdk_libkrunfw_path(path);
+}
+
+/// The currently-resolved `msb` runtime path. Synchronous (filesystem probes,
+/// no async) — runs on the Ruby thread; resolves the path from the local
+/// backend's config.
 fn resolved_msb_path() -> Result<String, Error> {
-    let path = microsandbox::config::resolve_msb_path().map_err(error::to_ruby)?;
+    let backend = microsandbox::default_backend();
+    let local = backend.as_local().ok_or_else(|| {
+        error::to_ruby(microsandbox::MicrosandboxError::Unsupported {
+            feature: "resolved_msb_path requires a local backend".into(),
+            available_when: "with the local backend".into(),
+        })
+    })?;
+    let path = microsandbox::config::resolve_msb_path(local.config()).map_err(error::to_ruby)?;
     Ok(path.to_string_lossy().into_owned())
 }
 
@@ -72,9 +90,14 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     native.define_singleton_method("install", function!(install, 0))?;
     native.define_singleton_method("installed?", function!(is_installed, 0))?;
     native.define_singleton_method("set_runtime_msb_path", function!(set_runtime_msb_path, 1))?;
+    native.define_singleton_method(
+        "set_runtime_libkrunfw_path",
+        function!(set_runtime_libkrunfw_path, 1),
+    )?;
     native.define_singleton_method("resolved_msb_path", function!(resolved_msb_path, 0))?;
     native.define_singleton_method("all_sandbox_metrics", function!(all_sandbox_metrics, 0))?;
 
+    backend::define(ruby, &native)?;
     sandbox::define(ruby, &native)?;
     exec::define(ruby, &native)?;
     stream::define(ruby, &native)?;

data/ext/microsandbox/src/sandbox.rs

@@ -209,27 +209,36 @@ impl Sandbox {
         Ok(Sandbox::from_inner(inner))
     }
 
-    /// Lightweight metadata for a sandbox by name (running or not).
-    fn get(name: String) -> Result<RHash, Error> {
+    /// A controllable handle for a sandbox by name (running or not). Carries
+    /// metadata accessors and the full lifecycle surface (see `SbHandle`).
+    fn get(name: String) -> Result<SbHandle, Error> {
         let handle = block_on(microsandbox::Sandbox::get(&name)).map_err(error::to_ruby)?;
-        Ok(handle_to_hash(&handle))
+        Ok(SbHandle::from_inner(handle))
     }
 
-    /// All sandboxes as metadata hashes.
+    /// All sandboxes as controllable handles.
     fn list() -> Result<RArray, Error> {
         let handles = block_on(microsandbox::Sandbox::list()).map_err(error::to_ruby)?;
-        rhash_array(handles.iter().map(handle_to_hash))
+        let arr = ruby().ary_new();
+        for h in handles {
+            arr.push(SbHandle::from_inner(h))?;
+        }
+        Ok(arr)
     }
 
-    /// Sandboxes filtered by required `key=value` labels (AND-matched). `opts`
-    /// carries a string→string `labels` map.
+    /// Sandboxes filtered by required `key=value` labels (AND-matched), as
+    /// controllable handles. `opts` carries a string→string `labels` map.
     fn list_with(opts: RHash) -> Result<RArray, Error> {
         let mut filter = SandboxFilter::new();
         for (k, v) in conv::opt_string_map(opts, "labels")? {
             filter = filter.label(k, v);
         }
         let handles = block_on(microsandbox::Sandbox::list_with(filter)).map_err(error::to_ruby)?;
-        rhash_array(handles.iter().map(handle_to_hash))
+        let arr = ruby().ary_new();
+        for h in handles {
+            arr.push(SbHandle::from_inner(h))?;
+        }
+        Ok(arr)
     }
 
     /// Remove a (stopped) sandbox by name.
@@ -286,44 +295,46 @@ impl Sandbox {
         Ok(ExecHandle::from_core(handle))
     }
 
-    /// Graceful stop (+ wait). `timeout` is optional seconds.
-    fn stop(&self, timeout: Option<f64>) -> Result<(), Error> {
-        match timeout {
-            Some(secs) => block_on(self.inner.stop_with_timeout(Duration::from_secs_f64(secs))),
-            None => block_on(self.inner.stop()),
-        }
+    /// Graceful stop. Mirrors the official SDKs: the live handle routes through
+    /// a freshly fetched `SandboxHandle::stop` (SIGTERM→SIGKILL escalation with
+    /// a 10s default). Fine-grained control — a custom timeout or fire-and-
+    /// return `request_*` — lives on `SandboxHandle`, obtained via `Sandbox.get`.
+    fn stop(&self) -> Result<(), Error> {
+        let name = self.inner.name().to_string();
+        block_on(async move {
+            let handle = microsandbox::sandbox::Sandbox::get(&name).await?;
+            handle.stop().await
+        })
         .map_err(error::to_ruby)
     }
 
-    /// Force kill (SIGKILL). `timeout` is optional seconds.
-    fn kill(&self, timeout: Option<f64>) -> Result<(), Error> {
-        match timeout {
-            Some(secs) => block_on(self.inner.kill_with_timeout(Duration::from_secs_f64(secs))),
-            None => block_on(self.inner.kill()),
-        }
-        .map_err(error::to_ruby)
+    /// Graceful stop, then wait for the process to exit. Returns an exit-status
+    /// Hash (`exit_code`, `success`). Local backend only.
+    fn stop_and_wait(&self) -> Result<RHash, Error> {
+        let status = block_on(self.inner.stop_and_wait()).map_err(error::to_ruby)?;
+        Ok(exit_status_to_hash(status))
     }
 
-    /// Send the graceful-shutdown request and return without waiting.
-    fn request_stop(&self) -> Result<(), Error> {
-        block_on(self.inner.request_stop()).map_err(error::to_ruby)
+    /// Force kill (SIGKILL).
+    fn kill(&self) -> Result<(), Error> {
+        block_on(self.inner.kill()).map_err(error::to_ruby)
     }
 
-    /// Send the force-kill request and return without waiting.
-    fn request_kill(&self) -> Result<(), Error> {
-        block_on(self.inner.request_kill()).map_err(error::to_ruby)
+    /// Trigger a graceful drain (SIGUSR1 on local).
+    fn drain(&self) -> Result<(), Error> {
+        block_on(self.inner.drain()).map_err(error::to_ruby)
     }
 
-    /// Send the drain request and return without waiting.
-    fn request_drain(&self) -> Result<(), Error> {
-        block_on(self.inner.request_drain()).map_err(error::to_ruby)
+    /// Wait for the process to exit. Returns an exit-status Hash. Local only.
+    fn wait(&self) -> Result<RHash, Error> {
+        let status = block_on(self.inner.wait()).map_err(error::to_ruby)?;
+        Ok(exit_status_to_hash(status))
     }
 
-    /// Block until the sandbox is observed in a terminal state; returns a
-    /// stop-result Hash (name, status, exit_code, signal, observed_at_ms, source).
-    fn wait_until_stopped(&self) -> Result<RHash, Error> {
-        let result = block_on(self.inner.wait_until_stopped()).map_err(error::to_ruby)?;
-        Ok(stop_result_to_hash(&result))
+    /// Live status fetched from the backend (a round-trip per call).
+    fn status(&self) -> Result<String, Error> {
+        let status = block_on(self.inner.status()).map_err(error::to_ruby)?;
+        Ok(sandbox_status_str(status).to_string())
     }
 
     /// Whether this handle owns the sandbox process lifecycle (a synchronous,
@@ -1064,6 +1075,7 @@ struct ExecOpts {
     timeout: Option<Duration>,
     tty: bool,
     stdin: Option<Vec<u8>>,
+    stdin_pipe: bool,
     rlimits: Vec<(RlimitResource, u64, u64)>,
 }
 
@@ -1078,6 +1090,7 @@ impl ExecOpts {
             timeout: conv::opt_f64(opts, "timeout")?.map(Duration::from_secs_f64),
             tty: conv::opt_bool(opts, "tty")?,
             stdin,
+            stdin_pipe: conv::opt_bool(opts, "stdin_pipe")?,
             rlimits: parse_rlimits(opts)?,
         })
     }
@@ -1104,7 +1117,13 @@ impl ExecOpts {
         if self.tty {
             b = b.tty(true);
         }
-        if let Some(stdin) = self.stdin {
+        // Pipe mode opens a writable stdin sink (lifted out by ExecHandle via
+        // `take_stdin`); bytes mode feeds a fixed buffer and closes. The core's
+        // `StdinMode` is a single enum, so the two are mutually exclusive — pipe
+        // wins if a caller somehow sets both.
+        if self.stdin_pipe {
+            b = b.stdin_pipe();
+        } else if let Some(stdin) = self.stdin {
             b = b.stdin_bytes(stdin);
         }
         for (resource, soft, hard) in self.rlimits {
@@ -1195,7 +1214,13 @@ pub(crate) fn metrics_to_hash(m: &SandboxMetrics) -> RHash {
 }
 
 fn sandbox_status_str(status: SandboxStatus) -> &'static str {
+    // Lowercased `Debug` names, matching the official SDKs' `format!("{:?}")`.
+    // `Created`/`Starting` are new in v0.5.8 (cloud-only today). The match is
+    // intentionally exhaustive — no wildcard — so a future upstream variant
+    // surfaces as a compile error rather than a silent fallback.
     match status {
+        SandboxStatus::Created => "created",
+        SandboxStatus::Starting => "starting",
         SandboxStatus::Running => "running",
         SandboxStatus::Draining => "draining",
         SandboxStatus::Paused => "paused",
@@ -1204,6 +1229,15 @@ fn sandbox_status_str(status: SandboxStatus) -> &'static str {
     }
 }
 
+/// A `std::process::ExitStatus` as a Ruby Hash: `exit_code` (Integer or nil) and
+/// `success` (Boolean). Returned by the live `Sandbox#wait` / `#stop_and_wait`.
+fn exit_status_to_hash(status: std::process::ExitStatus) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("exit_code", status.code());
+    let _ = hash.aset("success", status.success());
+    hash
+}
+
 fn stop_result_to_hash(result: &SandboxStopResult) -> RHash {
     let hash = ruby().hash_new();
     let _ = hash.aset("name", result.name.clone());
@@ -1215,19 +1249,85 @@ fn stop_result_to_hash(result: &SandboxStopResult) -> RHash {
     hash
 }
 
-fn handle_to_hash(handle: &SandboxHandle) -> RHash {
-    let hash = ruby().hash_new();
-    let _ = hash.aset("name", handle.name().to_string());
-    let _ = hash.aset("status", sandbox_status_str(handle.status()));
-    let _ = hash.aset(
-        "created_at_ms",
-        handle.created_at().map(|dt| dt.timestamp_millis()),
-    );
-    let _ = hash.aset(
-        "updated_at_ms",
-        handle.updated_at().map(|dt| dt.timestamp_millis()),
-    );
-    hash
+//--------------------------------------------------------------------------------------------------
+// SandboxHandle — the controllable lightweight handle
+//--------------------------------------------------------------------------------------------------
+
+/// Wraps a core `microsandbox::sandbox::SandboxHandle` (returned by
+/// `Sandbox.get`/`list`/`list_with`). Carries metadata accessors plus the rich
+/// lifecycle surface that moved off the live `Sandbox` in v0.5.8 — mirroring the
+/// official Python (`PySandboxHandle`) and Node (`SandboxHandle`) SDKs. Status is
+/// a synchronous snapshot read off the handle (no round-trip).
+#[magnus::wrap(class = "Microsandbox::Native::SandboxHandle", free_immediately, size)]
+pub struct SbHandle {
+    inner: SandboxHandle,
+}
+
+impl SbHandle {
+    fn from_inner(inner: SandboxHandle) -> Self {
+        Self { inner }
+    }
+
+    fn name(&self) -> String {
+        self.inner.name().to_string()
+    }
+
+    /// Status snapshot captured when the handle was fetched (synchronous).
+    fn status(&self) -> String {
+        sandbox_status_str(self.inner.status_snapshot()).to_string()
+    }
+
+    fn created_at_ms(&self) -> Option<i64> {
+        self.inner.created_at().map(|dt| dt.timestamp_millis())
+    }
+
+    fn updated_at_ms(&self) -> Option<i64> {
+        self.inner.updated_at().map(|dt| dt.timestamp_millis())
+    }
+
+    /// Graceful stop (SIGTERM→SIGKILL escalation, 10s default) and wait.
+    fn stop(&self) -> Result<(), Error> {
+        block_on(self.inner.stop()).map_err(error::to_ruby)
+    }
+
+    /// Graceful stop with a custom escalation timeout (seconds).
+    fn stop_with_timeout(&self, secs: f64) -> Result<(), Error> {
+        block_on(self.inner.stop_with_timeout(Duration::from_secs_f64(secs)))
+            .map_err(error::to_ruby)
+    }
+
+    /// Force kill (SIGKILL) and wait.
+    fn kill(&self) -> Result<(), Error> {
+        block_on(self.inner.kill()).map_err(error::to_ruby)
+    }
+
+    /// Force kill, waiting up to `secs` for the process to disappear.
+    fn kill_with_timeout(&self, secs: f64) -> Result<(), Error> {
+        block_on(self.inner.kill_with_timeout(Duration::from_secs_f64(secs)))
+            .map_err(error::to_ruby)
+    }
+
+    /// Send the graceful-shutdown request and return without waiting.
+    fn request_stop(&self) -> Result<(), Error> {
+        block_on(self.inner.request_stop()).map_err(error::to_ruby)
+    }
+
+    /// Send the force-kill request and return without waiting.
+    fn request_kill(&self) -> Result<(), Error> {
+        block_on(self.inner.request_kill()).map_err(error::to_ruby)
+    }
+
+    /// Send the drain request (SIGUSR1) and return without waiting.
+    fn request_drain(&self) -> Result<(), Error> {
+        block_on(self.inner.request_drain()).map_err(error::to_ruby)
+    }
+
+    /// Block until the sandbox reaches a terminal state; returns a stop-result
+    /// Hash (name, status, exit_code, signal, observed_at_ms, source).
+    fn wait_until_stopped(&self) -> Result<RHash, Error> {
+        let result = block_on(self.inner.wait_until_stopped()).map_err(error::to_ruby)?;
+        Ok(stop_result_to_hash(&result))
+    }
 }
 
 //--------------------------------------------------------------------------------------------------
@@ -1328,15 +1428,12 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("shell", method!(Sandbox::shell, 2))?;
     class.define_method("exec_stream", method!(Sandbox::exec_stream, 3))?;
     class.define_method("shell_stream", method!(Sandbox::shell_stream, 2))?;
-    class.define_method("stop", method!(Sandbox::stop, 1))?;
-    class.define_method("kill", method!(Sandbox::kill, 1))?;
-    class.define_method("request_stop", method!(Sandbox::request_stop, 0))?;
-    class.define_method("request_kill", method!(Sandbox::request_kill, 0))?;
-    class.define_method("request_drain", method!(Sandbox::request_drain, 0))?;
-    class.define_method(
-        "wait_until_stopped",
-        method!(Sandbox::wait_until_stopped, 0),
-    )?;
+    class.define_method("stop", method!(Sandbox::stop, 0))?;
+    class.define_method("stop_and_wait", method!(Sandbox::stop_and_wait, 0))?;
+    class.define_method("kill", method!(Sandbox::kill, 0))?;
+    class.define_method("drain", method!(Sandbox::drain, 0))?;
+    class.define_method("wait", method!(Sandbox::wait, 0))?;
+    class.define_method("status", method!(Sandbox::status, 0))?;
     class.define_method("owns_lifecycle", method!(Sandbox::owns_lifecycle, 0))?;
     class.define_method("detach", method!(Sandbox::detach, 0))?;
     class.define_method("metrics", method!(Sandbox::metrics, 0))?;
@@ -1367,5 +1464,22 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("attach", method!(Sandbox::attach, 3))?;
     class.define_method("attach_shell", method!(Sandbox::attach_shell, 0))?;
 
+    let handle = native.define_class("SandboxHandle", ruby.class_object())?;
+    handle.define_method("name", method!(SbHandle::name, 0))?;
+    handle.define_method("status", method!(SbHandle::status, 0))?;
+    handle.define_method("created_at_ms", method!(SbHandle::created_at_ms, 0))?;
+    handle.define_method("updated_at_ms", method!(SbHandle::updated_at_ms, 0))?;
+    handle.define_method("stop", method!(SbHandle::stop, 0))?;
+    handle.define_method("stop_with_timeout", method!(SbHandle::stop_with_timeout, 1))?;
+    handle.define_method("kill", method!(SbHandle::kill, 0))?;
+    handle.define_method("kill_with_timeout", method!(SbHandle::kill_with_timeout, 1))?;
+    handle.define_method("request_stop", method!(SbHandle::request_stop, 0))?;
+    handle.define_method("request_kill", method!(SbHandle::request_kill, 0))?;
+    handle.define_method("request_drain", method!(SbHandle::request_drain, 0))?;
+    handle.define_method(
+        "wait_until_stopped",
+        method!(SbHandle::wait_until_stopped, 0),
+    )?;
+
     Ok(())
 }

data/ext/microsandbox/src/volume.rs

@@ -65,7 +65,12 @@ fn create(name: String, opts: RHash) -> Result<RHash, Error> {
     let vol = block_on(builder.create()).map_err(error::to_ruby)?;
     let hash = ruby().hash_new();
     hash.aset("name", vol.name().to_string())?;
-    hash.aset("path", vol.path().display().to_string())?;
+    // `path()` is fallible as of v0.5.8 (returns `Unsupported` for cloud
+    // volumes); the volume just created here is local, so this resolves.
+    hash.aset(
+        "path",
+        vol.path().map_err(error::to_ruby)?.display().to_string(),
+    )?;
     Ok(hash)
 }
 

data/lib/microsandbox/errors.rb

@@ -65,4 +65,10 @@ module Microsandbox
 
   # Runtime compatibility ---------------------------------------------------
   define_error(:UnsupportedOperationError, "unsupported-operation")
+
+  # Cloud / backend routing errors (v0.5.8) ---------------------------------
+  # `UnsupportedError` (a backend feature gap, e.g. an op not yet wired on the
+  # cloud backend) is distinct from `UnsupportedOperationError` above.
+  define_error(:CloudHttpError, "cloud-http")
+  define_error(:UnsupportedError, "unsupported")
 end