microsandbox-rb 0.14.0 → 0.16.0

data/README.md

@@ -186,6 +186,39 @@ Microsandbox::Sandbox.start("box")    # restart a stopped sandbox
 Microsandbox::Sandbox.remove("box")   # remove a stopped sandbox
 ```
 
+**Convergent lifecycle** (runtime `v0.6.16`) — idempotent operations that take a
+name to the state you want, whatever state it is in now:
+
+```ruby
+# Create it, or connect to (and start) the one that is already there. The
+# keyword options are `create`'s and apply only when a create actually happens.
+sb = Microsandbox::Sandbox.connect_or_create("box", image: "public.ecr.aws/docker/library/alpine:latest")
+
+sb.id                     # opaque identity of the *persisted* sandbox — unlike
+                          # the reusable name, it changes on remove+recreate
+sb.wait_for_status(:running)  # => SandboxHandle (no built-in timeout)
+sb = sb.restart               # stop + start; => a new live Sandbox
+sb.destroy                    # stop + remove, in one step
+
+h = Microsandbox::Sandbox.get("box")
+h.connect_or_start        # connect if running, start if not => Sandbox
+h.restart(force: true, timeout: 5)
+h.destroy
+```
+
+Everything that acts on an *existing* receiver — `wait_for_status`, `restart`,
+`destroy`, `connect_or_start` — compares the identity it was bound to against
+the name's current owner first, raising `Microsandbox::SandboxReplacedError`
+rather than touching a sandbox someone else recreated under the same name.
+(`connect_or_create` is the entry point, so it has no prior identity to check:
+it simply converges on whichever sandbox now owns the name.)
+
+`connect_or_create`'s block form stops the sandbox only when the call owns its
+lifecycle — i.e. when it created it attached. A sandbox it merely connected to,
+or started with `detached: true`, is left running. And the stop it does issue is
+scoped to that sandbox's `id`, so a name removed and recreated while the block
+ran cannot be taken down by the teardown either.
+
 > **v0.5.8 lifecycle change.** Upstream split the lifecycle into the live
 > `Sandbox` and a controllable `SandboxHandle`, and the gem mirrors it. The live
 > `Sandbox#stop`/`#kill` no longer take a `timeout:`; `#request_stop`/
@@ -430,7 +463,9 @@ Microsandbox::Volume.remove("cache")
 ```
 
 `volumes:` accepts a host path String (bind mount) or `{ bind: "/host" }` /
-`{ named: "volume-name" }` per guest path. Boot from a snapshot with
+`{ named: "volume-name" }` per guest path. A bind or named mount may pin the
+fallback guest owner for host files with `uid:`/`gid:` (both required together,
+runtime `v0.6.15`). Boot from a snapshot with
 `Sandbox.create(name, from_snapshot: "snap-name-or-path")`.
 
 ### Error handling
@@ -524,8 +559,8 @@ change diverged the two numbers — the gem version is **not** a reliable indica
 of the embedded runtime version. To learn which runtime a build wraps, ask it:
 
 ```ruby
-Microsandbox::VERSION          # => "0.13.0"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.6.9"  (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.16.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.16" (the embedded upstream runtime tag)
 ```
 
 The companion [`microsandbox-rb-binaries`](#the-runtime-binaries) gem is
@@ -557,6 +592,8 @@ stale.
 | `0.12.0` | `v0.6.8` | adopts upstream `v0.6.8` (**breaking**): `Sandbox.list`/`.list_with` return a cursor-paginated `SandboxPage` (`limit:`/`cursor:` keywords), `UnsupportedError` re-keyed by structured operations with `#operation`/`#hint`; runtime adds a shared log registry for followed streams and cloud exec/ssh reconnects |
 | `0.13.0` | `v0.6.9` | adopts upstream `v0.6.9` (**breaking**): a bare `MSB_API_KEY` no longer selects the cloud backend (explicit `MSB_BACKEND=cloud` or a cloud profile required; invalid cloud config fails closed with `InvalidConfigError`); snapshot payload integrity becomes opt-in (`record_integrity:`, `verify` can report `:not_recorded`). Parity: default-workload execution (`exec_default`/`exec_default_stream`/`attach_default`, `cmd:`), flat root disks (`RootDisk.flat`), `modify(root_disk_size:)`, `rate_limiter:`, `vsock:`, `default_backend_info`, `Volume.get_default` |
 | `0.14.0` | `v0.6.9` | two-gem split: SDK-only gem (no build-time runtime download) + companion `microsandbox-rb-binaries` platform gems |
+| `0.15.0` | `v0.6.14` | adopts upstream `v0.6.10`–`v0.6.14` step by step: bind-mount correctness, guest bootstrap off the kernel command line, DNS pins for deferred domain allows, Linux glibc 2.28 baseline for the prebuilt runtime, legacy ext4 upper-disk resize, `msb_krun` 0.1.32. Parity: `ssh.open_client`/`prepare_server` accept `inactivity_timeout:` (seconds; `0` disables, `nil` inherits the 600s global default) |
+| `0.16.0` | `v0.6.16` | adopts upstream `v0.6.15`+`v0.6.16` step by step: mount fallback ownership, readonly-mount write-probe fix, log retrieval rerouted through the SDK backends, config overlaid by field presence, network-slot recycling. Parity: per-mount `uid:`/`gid:`, and the convergent lifecycle — `Sandbox.connect_or_create`, `#id`, `#wait_for_status`, `#restart`, `#destroy`, `SandboxHandle#connect_or_start`, `SandboxReplacedError` |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:

data/ext/microsandbox/Cargo.toml

@@ -6,8 +6,8 @@ name = "microsandbox_rb"
 description = "Ruby SDK native extension for microsandbox — secure, fast microVM-based sandboxing."
 # Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
-# The core-crate dependency below stays pinned at its own tag (v0.6.9).
-version = "0.14.0"
+# The core-crate dependency below stays pinned at its own tag (v0.6.16).
+version = "0.16.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -42,8 +42,8 @@ rb-sys = "0.9"
 # first-use download into ~/.microsandbox (`setup::install`, which is not
 # gated on "prebuilt"). "net"/"ssh"/"keyring" are the features the official
 # SDKs ship with.
-microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9", default-features = false, features = ["keyring", "net", "ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9" }
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.16", default-features = false, features = ["keyring", "net", "ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.16" }
 # The *guest* agent (`agentd`, PID 1 inside every microVM) is embedded into the
 # extension by microsandbox-filesystem's build.rs, which without its "prebuilt"
 # feature demands a locally built `build/agentd` (workspace-only, `just
@@ -52,7 +52,7 @@ microsandbox-network = { git = "https://github.com/superradcompany/microsandbox"
 # prebuilt agentd for the target arch is fetched (same behaviour as before)
 # while the SDK-level msb download above stays off. Feature unification means
 # this adds no new crates; keep it on the same tag as the deps above.
-microsandbox-runtime = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9", default-features = false, features = ["prebuilt"] }
+microsandbox-runtime = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.16", default-features = false, features = ["prebuilt"] }
 
 # Async core bridged to Ruby's synchronous API via a blocking tokio runtime.
 tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }

data/ext/microsandbox/src/error.rs

@@ -17,6 +17,11 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         SandboxNotFound(_) => "SandboxNotFoundError",
         SandboxAlreadyExists(_) => "SandboxAlreadyExistsError",
         SandboxStillRunning(_) => "SandboxStillRunningError",
+        // v0.6.16 (#1462): the receiver's captured identity no longer owns the
+        // name — it was removed and recreated. Raised by the identity-checked
+        // convergent lifecycle APIs instead of acting on the replacement.
+        // Mirrors the Python `SandboxReplacedError`.
+        SandboxReplaced { .. } => "SandboxReplacedError",
         // v0.6.6 (#1099): the sandbox exists but isn't running. Raised by the
         // handle's exec/attach/ping/touch not-running guards and the fs
         // agent-endpoint lookup. The `SandboxNotRunningError` class already

data/ext/microsandbox/src/sandbox.rs

@@ -18,11 +18,11 @@ use microsandbox::logs::{
     LogCursor, LogEntry, LogOptions, LogSource, LogStreamOptions, LogStreamStart,
 };
 use microsandbox::sandbox::{
-    AttachOptionsBuilder, DiskImageFormat, EnvVar, FlatClone, FsEntry, FsEntryKind, FsMetadata,
-    HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource,
-    RootDiskBuilder, SandboxBuilder, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
-    SandboxModificationPatch, SandboxStatus, SandboxStopResult, SecretBuilder,
-    SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
+    AttachOptionsBuilder, DestroyOptions, DiskImageFormat, EnvVar, FlatClone, FsEntry, FsEntryKind,
+    FsMetadata, HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle,
+    RestartOptions, RlimitResource, RootDiskBuilder, SandboxBuilder, SandboxHandle, SandboxMetrics,
+    SandboxModificationBuilder, SandboxModificationPatch, SandboxStatus, SandboxStopResult,
+    SecretBuilder, SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
 };
 use microsandbox::LogLevel;
 use microsandbox::MicrosandboxResult;
@@ -167,7 +167,8 @@ impl Sandbox {
         // Hash — guest (req), kind ("bind"/"named"/"tmpfs"/"disk"), source
         // (bind/named/disk), size_mib (tmpfs/disk), format + fstype (disk),
         // readonly/noexec/nosuid/nodev (bool), stat_virtualization,
-        // host_permissions. Enum-valued options are validated up front (the
+        // host_permissions, override_uid/override_gid (u32 pair).
+        // Enum-valued options are validated up front (the
         // volume closure can't return an error); the core validates the rest
         // (e.g. rejecting stat_virtualization on tmpfs/disk) at create().
         for m in conv::opt_hash_vec(opts, "volumes")? {
@@ -195,6 +196,14 @@ impl Sandbox {
             let host_perms = conv::opt_string(m, "host_permissions")?
                 .map(|s| host_permissions_from_str(&s))
                 .transpose()?;
+            // v0.6.15: the fallback guest owner presented for host files that
+            // carry no per-file stat override. The Ruby layer validates the pair
+            // (both-or-neither, u32 range, bind/named only, not with
+            // stat_virtualization=off); whether a *named* volume is directory-
+            // or disk-backed is known only to the core, which rejects the
+            // disk-backed case at build().
+            let override_uid = conv::opt_u32(m, "override_uid")?;
+            let override_gid = conv::opt_u32(m, "override_gid")?;
             // v0.6.7: mount-root symlink protection is on by default; this is
             // the per-mount opt-out. Valid for bind/named-directory mounts —
             // the core rejects it elsewhere at build().
@@ -251,6 +260,9 @@ impl Sandbox {
                 if let Some(hp) = host_perms {
                     mb = mb.host_permissions(hp);
                 }
+                if let (Some(uid), Some(gid)) = (override_uid, override_gid) {
+                    mb = mb.owner(uid, gid);
+                }
                 if let Some(follow) = follow_root_symlinks {
                     mb = mb.follow_root_symlinks(follow);
                 }
@@ -509,6 +521,16 @@ impl Sandbox {
         Ok(PullSession::new(handle, join))
     }
 
+    /// Converge on a live sandbox with this name: connect to (or start) the
+    /// persisted one when it already exists, otherwise create it from `opts`.
+    /// Concurrent callers converge on the winning identity. The core rejects
+    /// the combination with `replace`.
+    fn connect_or_create(name: String, opts: RHash) -> Result<Sandbox, Error> {
+        let b = Self::build_builder(name, opts)?;
+        let inner = block_on(b.connect_or_create()).map_err(error::to_ruby)?;
+        Ok(Sandbox::from_inner(inner))
+    }
+
     /// Restart a previously-defined sandbox by name.
     fn start(name: String, opts: RHash) -> Result<Sandbox, Error> {
         let detached = conv::opt_bool(opts, "detached")?;
@@ -580,6 +602,13 @@ impl Sandbox {
         self.inner.name().to_string()
     }
 
+    /// The opaque, backend-assigned identity of this persisted sandbox
+    /// (v0.6.16). Stable for the sandbox's lifetime, and different once the
+    /// same name is removed and recreated.
+    fn id(&self) -> String {
+        self.inner.id().to_string()
+    }
+
     /// Run a command (no shell). `args` is an Array of strings; `opts` is a
     /// string-keyed Hash (cwd, user, env, timeout, tty, stdin).
     fn exec(&self, cmd: String, args: Vec<String>, opts: RHash) -> Result<RHash, Error> {
@@ -644,17 +673,23 @@ impl Sandbox {
         Ok(ExecHandle::from_core(handle))
     }
 
-    /// 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`.
+    /// Graceful stop (SIGTERM→SIGKILL escalation with a 10s default), routed
+    /// straight through the live sandbox like every other lifecycle method here
+    /// and like both official bindings (`sdk/python/src/sandbox.rs`,
+    /// `sdk/ruby/ext/.../lib.rs`).
+    ///
+    /// This deliberately does NOT re-fetch a `SandboxHandle` by name first. It
+    /// used to, back when the core's live `stop` was not identity-scoped; as of
+    /// v0.6.16 the core routes `stop` → `request_stop` → `stop_identified(name,
+    /// self.identity())`, so going through `self.inner` is what makes the stop
+    /// refuse a same-name replacement (`SandboxReplacedError`) instead of
+    /// terminating whatever sandbox happens to own the name right now. The old
+    /// by-name refetch threw that identity away.
+    ///
+    /// 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)
+        block_on(self.inner.stop()).map_err(error::to_ruby)
     }
 
     /// Graceful stop, then wait for the process to exit. Returns an exit-status
@@ -680,6 +715,29 @@ impl Sandbox {
         Ok(exit_status_to_hash(status))
     }
 
+    /// Block until this exact sandbox reaches `status` (no built-in timeout),
+    /// returning a fresh handle. A same-name replacement raises
+    /// `SandboxReplacedError` instead of silently redirecting the wait.
+    fn wait_for_status(&self, status: String) -> Result<SbHandle, Error> {
+        let status = sandbox_status_from_str(&status)?;
+        let handle = block_on(self.inner.wait_for_status(status)).map_err(error::to_ruby)?;
+        Ok(SbHandle::from_inner(handle))
+    }
+
+    /// Stop and start this exact sandbox, returning the new live sandbox.
+    /// `opts` carries `force`/`timeout`/`detached`.
+    fn restart(&self, opts: RHash) -> Result<Sandbox, Error> {
+        let options = restart_options(opts)?;
+        let inner = block_on(self.inner.restart_with(options)).map_err(error::to_ruby)?;
+        Ok(Sandbox::from_inner(inner))
+    }
+
+    /// Stop and remove this exact sandbox. `opts` carries `force`/`timeout`.
+    fn destroy(&self, opts: RHash) -> Result<(), Error> {
+        let options = destroy_options(opts)?;
+        block_on(self.inner.destroy_with(options)).map_err(error::to_ruby)
+    }
+
     /// 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)?;
@@ -866,11 +924,14 @@ impl Sandbox {
     //----------------------------------------------------------------------
 
     /// Open a native in-process SSH client to this sandbox. `opts`: user, term,
-    /// sftp (bool, default true).
+    /// sftp (bool, default true), inactivity_timeout (seconds, f64; 0 disables).
     fn ssh_open_client(&self, opts: RHash) -> Result<crate::ssh::SshClient, Error> {
         let user = conv::opt_string(opts, "user")?;
         let term = conv::opt_string(opts, "term")?;
         let sftp = conv::opt::<bool>(opts, "sftp")?.unwrap_or(true);
+        let inactivity_timeout = conv::opt_f64(opts, "inactivity_timeout")?
+            .map(secs_to_duration)
+            .transpose()?;
         let ssh = self.inner.ssh();
         let client = block_on(ssh.open_client_with(move |mut b| {
             if let Some(u) = user {
@@ -879,6 +940,9 @@ impl Sandbox {
             if let Some(t) = term {
                 b = b.term(t);
             }
+            if let Some(t) = inactivity_timeout {
+                b = b.inactivity_timeout(t);
+            }
             b.sftp(sftp)
         }))
         .map_err(error::to_ruby)?;
@@ -886,12 +950,16 @@ impl Sandbox {
     }
 
     /// Prepare a reusable SSH server endpoint. `opts`: host_key_path,
-    /// authorized_keys_path, user, sftp (bool, default true).
+    /// authorized_keys_path, user, sftp (bool, default true),
+    /// inactivity_timeout (seconds, f64; 0 disables).
     fn ssh_prepare_server(&self, opts: RHash) -> Result<crate::ssh::SshServer, Error> {
         let host_key_path = conv::opt_string(opts, "host_key_path")?;
         let authorized_keys_path = conv::opt_string(opts, "authorized_keys_path")?;
         let user = conv::opt_string(opts, "user")?;
         let sftp = conv::opt::<bool>(opts, "sftp")?.unwrap_or(true);
+        let inactivity_timeout = conv::opt_f64(opts, "inactivity_timeout")?
+            .map(secs_to_duration)
+            .transpose()?;
         let ssh = self.inner.ssh();
         let server = block_on(ssh.prepare_server_with(move |mut b| {
             if let Some(p) = host_key_path {
@@ -903,6 +971,9 @@ impl Sandbox {
             if let Some(u) = user {
                 b = b.user(u);
             }
+            if let Some(t) = inactivity_timeout {
+                b = b.inactivity_timeout(t);
+            }
             b.sftp(sftp)
         }))
         .map_err(error::to_ruby)?;
@@ -2083,6 +2154,55 @@ fn sandbox_status_str(status: SandboxStatus) -> &'static str {
     }
 }
 
+/// Parse a Ruby-facing status name back into a core `SandboxStatus`. The Ruby
+/// layer already validates the seven names (raising `ArgumentError`, the repo's
+/// idiom for a bad argument value), so reaching the fallback here means the
+/// native layer was called directly; keep it exhaustive rather than silent.
+fn sandbox_status_from_str(status: &str) -> Result<SandboxStatus, Error> {
+    match status {
+        "created" => Ok(SandboxStatus::Created),
+        "starting" => Ok(SandboxStatus::Starting),
+        "running" => Ok(SandboxStatus::Running),
+        "draining" => Ok(SandboxStatus::Draining),
+        "paused" => Ok(SandboxStatus::Paused),
+        "stopped" => Ok(SandboxStatus::Stopped),
+        "crashed" => Ok(SandboxStatus::Crashed),
+        other => Err(error::base_error(format!(
+            "unknown sandbox status {other:?} (expected created/starting/running/draining/\
+             paused/stopped/crashed)"
+        ))),
+    }
+}
+
+/// Build the core's `RestartOptions` from a string-keyed Hash
+/// (`force`/`timeout`/`detached`). An absent `timeout` keeps the core's
+/// ten-second graceful-shutdown default.
+fn restart_options(opts: RHash) -> Result<RestartOptions, Error> {
+    let mut options = RestartOptions {
+        force: conv::opt_bool(opts, "force")?,
+        detached: conv::opt_bool(opts, "detached")?,
+        ..Default::default()
+    };
+    if let Some(secs) = conv::opt_f64(opts, "timeout")? {
+        options.timeout = secs_to_duration(secs)?;
+    }
+    Ok(options)
+}
+
+/// Build the core's `DestroyOptions` from a string-keyed Hash
+/// (`force`/`timeout`). An absent `timeout` keeps the core's ten-second
+/// graceful-shutdown default.
+fn destroy_options(opts: RHash) -> Result<DestroyOptions, Error> {
+    let mut options = DestroyOptions {
+        force: conv::opt_bool(opts, "force")?,
+        ..Default::default()
+    };
+    if let Some(secs) = conv::opt_f64(opts, "timeout")? {
+        options.timeout = secs_to_duration(secs)?;
+    }
+    Ok(options)
+}
+
 /// 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 {
@@ -2409,6 +2529,13 @@ impl SbHandle {
         self.inner.name().to_string()
     }
 
+    /// The opaque, backend-assigned identity of the persisted sandbox this
+    /// handle is bound to (v0.6.16). The lifecycle operations below refuse to
+    /// act on a same-name replacement by comparing against it.
+    fn id(&self) -> String {
+        self.inner.id().to_string()
+    }
+
     /// Status snapshot captured when the handle was fetched (synchronous).
     fn status(&self) -> String {
         sandbox_status_str(self.inner.status_snapshot()).to_string()
@@ -2457,6 +2584,45 @@ impl SbHandle {
         block_on(self.inner.request_drain()).map_err(error::to_ruby)
     }
 
+    /// Connect when this exact sandbox is running, wait while it is starting,
+    /// or start it when it is created/stopped/crashed. `opts` carries
+    /// `detached`, which applies only when a start is actually required.
+    fn connect_or_start(&self, opts: RHash) -> Result<Sandbox, Error> {
+        let detached = conv::opt_bool(opts, "detached")?;
+        let inner = block_on(async {
+            if detached {
+                self.inner.connect_or_start_detached().await
+            } else {
+                self.inner.connect_or_start().await
+            }
+        })
+        .map_err(error::to_ruby)?;
+        Ok(Sandbox::from_inner(inner))
+    }
+
+    /// Block until this exact sandbox reaches `status` (no built-in timeout),
+    /// returning a fresh handle. A same-name replacement raises
+    /// `SandboxReplacedError` instead of silently redirecting the wait.
+    fn wait_for_status(&self, status: String) -> Result<SbHandle, Error> {
+        let status = sandbox_status_from_str(&status)?;
+        let handle = block_on(self.inner.wait_for_status(status)).map_err(error::to_ruby)?;
+        Ok(SbHandle::from_inner(handle))
+    }
+
+    /// Stop and start this exact sandbox, returning the new live sandbox.
+    /// `opts` carries `force`/`timeout`/`detached`.
+    fn restart(&self, opts: RHash) -> Result<Sandbox, Error> {
+        let options = restart_options(opts)?;
+        let inner = block_on(self.inner.restart_with(options)).map_err(error::to_ruby)?;
+        Ok(Sandbox::from_inner(inner))
+    }
+
+    /// Stop and remove this exact sandbox. `opts` carries `force`/`timeout`.
+    fn destroy(&self, opts: RHash) -> Result<(), Error> {
+        let options = destroy_options(opts)?;
+        block_on(self.inner.destroy_with(options)).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> {
@@ -2594,6 +2760,10 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
         "create_with_progress",
         function!(Sandbox::create_with_progress, 2),
     )?;
+    class.define_singleton_method(
+        "connect_or_create",
+        function!(Sandbox::connect_or_create, 2),
+    )?;
     class.define_singleton_method("start", function!(Sandbox::start, 2))?;
     class.define_singleton_method("get", function!(Sandbox::get, 1))?;
     class.define_singleton_method("list", function!(Sandbox::list, 0))?;
@@ -2601,6 +2771,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_singleton_method("remove", function!(Sandbox::remove, 1))?;
 
     class.define_method("name", method!(Sandbox::name, 0))?;
+    class.define_method("id", method!(Sandbox::id, 0))?;
     class.define_method("exec", method!(Sandbox::exec, 3))?;
     class.define_method("shell", method!(Sandbox::shell, 2))?;
     class.define_method("exec_stream", method!(Sandbox::exec_stream, 3))?;
@@ -2615,6 +2786,9 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     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("wait_for_status", method!(Sandbox::wait_for_status, 1))?;
+    class.define_method("restart", method!(Sandbox::restart, 1))?;
+    class.define_method("destroy", method!(Sandbox::destroy, 1))?;
     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))?;
@@ -2654,6 +2828,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
 
     let handle = native.define_class("SandboxHandle", ruby.class_object())?;
     handle.define_method("name", method!(SbHandle::name, 0))?;
+    handle.define_method("id", method!(SbHandle::id, 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))?;
@@ -2661,6 +2836,10 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     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("connect_or_start", method!(SbHandle::connect_or_start, 1))?;
+    handle.define_method("wait_for_status", method!(SbHandle::wait_for_status, 1))?;
+    handle.define_method("restart", method!(SbHandle::restart, 1))?;
+    handle.define_method("destroy", method!(SbHandle::destroy, 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))?;

data/lib/microsandbox/errors.rb

@@ -35,6 +35,13 @@ module Microsandbox
   define_error(:SandboxNotRunningError, "sandbox-not-running")
   define_error(:SandboxAlreadyExistsError, "sandbox-already-exists")
   define_error(:SandboxStillRunningError, "sandbox-still-running")
+  # v0.6.16: a lifecycle operation was aimed at a sandbox identity that no
+  # longer owns the name — the name was removed and recreated behind the
+  # caller's back. Raised by the identity-checked convergent APIs
+  # (`wait_for_status`, `restart`, `destroy`, `connect_or_start`) rather than
+  # letting them act on the replacement. Mirrors the Python SDK's
+  # SandboxReplacedError.
+  define_error(:SandboxReplacedError, "sandbox-replaced")
 
   # Execution errors --------------------------------------------------------
   define_error(:ExecTimeoutError, "exec-timeout")