microsandbox-rb 0.15.0 → 0.17.0

data/DESIGN.md

@@ -184,7 +184,7 @@ extension.
 
 `ext/microsandbox/Cargo.toml` depends on the core crate via a **pinned git tag**
 (`microsandbox` / `microsandbox-network`, pinned to the same tag as
-`Microsandbox::RUNTIME_VERSION` — currently `v0.6.14`), so the gem builds anywhere
+`Microsandbox::RUNTIME_VERSION` — currently `v0.6.18`), so the gem builds anywhere
 — CI, `rake-compiler-dock` release containers, and end-user source installs —
 without an adjacent checkout. For fast local development against a sibling
 microsandbox checkout, copy `.cargo/config.toml.example` to `.cargo/config.toml`

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`/
@@ -212,6 +245,47 @@ Microsandbox::Sandbox.create(
 end
 ```
 
+**Outbound proxy** (runtime `v0.6.17`) — route the sandbox's egress through a
+SOCKS4 (TCP) or SOCKS5 (TCP + non-DNS UDP) proxy with `proxy:`. The proxy is
+dialed by the runtime's host-side network stack, so its address is resolved
+from the host (`127.0.0.1` is the host's loopback), and the egress policy
+(`network:`) still governs which destinations may be reached. A SOCKS5 password
+comes from a host environment variable via `SecretSource.env` — only the
+variable's *name* is handed to the runtime. Local backend only.
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks5("127.0.0.1:1080"))
+
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks5("10.0.0.5:1080")
+    .credentials("sandbox", Microsandbox::SecretSource.env("PROXY_PASSWORD")))
+
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks4("127.0.0.1:1080", user_id: "ci"))
+
+# The equivalent plain Hash works too:
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: { protocol: :socks5, address: "10.0.0.5:1080",
+           credentials: { username: "sandbox", password: { env: "PROXY_PASSWORD" } } })
+```
+
+**Strict hostname policy** (runtime `v0.6.18`) — `strict: true` makes a
+hostname-rule allow fail closed unless the runtime can actually see the request
+authority (plain-HTTP `Host`, or SNI/`:authority` under TLS interception); a
+bypassed or non-intercepted HTTPS flow allowed only by a hostname rule is then
+denied before the upstream dial. Default `false`; create-only. Independently of
+`strict:`, any policy with domain rules now checks plain-HTTP `Host` headers
+against it.
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  network: Microsandbox::NetworkPolicy.custom(default_egress: :deny,
+    rules: [{ action: :allow, direction: :egress, protocol: :tcp, port: 443,
+              destination: Microsandbox::Destination.domain("api.example.com") }]),
+  strict: true)
+```
+
 ### Executing commands
 
 ```ruby
@@ -430,7 +504,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 +600,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.15.0"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.6.14" (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.17.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.18" (the embedded upstream runtime tag)
 ```
 
 The companion [`microsandbox-rb-binaries`](#the-runtime-binaries) gem is
@@ -558,6 +634,8 @@ stale.
 | `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` |
+| `0.17.0` | `v0.6.18` | adopts upstream `v0.6.17`+`v0.6.18` step by step: outbound SOCKS4/SOCKS5 proxies (SOCKS5 UDP + credentials), migration-order fix for databases last opened by a `v0.6.15` `msb`, security hardening — plain-HTTP `Host`/`:authority` now checked against domain-rule policies even in non-strict mode, plus fail-closed strict hostname mode. Parity: `proxy:` (`Microsandbox::OutboundProxy` / `SecretSource`), `strict:` |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:
@@ -672,7 +750,8 @@ image-pull progress (`Sandbox.create_with_progress` → `PullSession`),
 (`root_disk:` managed/tmpfs/disk via `Microsandbox::RootDisk`), **network
 configuration** (composable profiles, custom per-rule
 `Microsandbox::NetworkPolicy`/`Rule`/`Destination`, plus DNS, TLS interception,
-IPv4/IPv6 pools, `max_connections`, `trust_host_cas`), **secrets** (multi-host /
+IPv4/IPv6 pools, `max_connections`, `trust_host_cas`, `strict` hostname mode,
+outbound SOCKS4/SOCKS5 `proxy:`), **secrets** (multi-host /
 wildcard allow-lists, injection toggles, per-secret + sandbox-level violation
 policy), **SSH** (`Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`), and the
 **raw agent client** (`Microsandbox::AgentClient`). Create options span

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.14).
-version = "0.15.0"
+# The core-crate dependency below stays pinned at its own tag (v0.6.16).
+version = "0.17.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.14", default-features = false, features = ["keyring", "net", "ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.14" }
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.18", default-features = false, features = ["keyring", "net", "ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.18" }
 # 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.14", default-features = false, features = ["prebuilt"] }
+microsandbox-runtime = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.18", 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

@@ -7,6 +7,7 @@
 
 use magnus::{value::ReprValue, Error, ExceptionClass, Module, RClass, RModule, Ruby};
 use microsandbox::{AgentClientError, MicrosandboxError, Operation, UnsupportedReason};
+use microsandbox_network::policy::BuildError;
 
 /// The Ruby class (relative to the `Microsandbox` module) for a core error.
 /// `"Error"` is the base class; anything else is a named subclass.
@@ -17,6 +18,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
@@ -55,6 +61,12 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         // migration (run at backend connect / artifact open) failed and needs
         // repair. Mirrors the Python `SnapshotMigrationError`.
         SnapshotMigration { .. } => "SnapshotMigrationError",
+        // v0.6.17: a malformed `proxy:` (unparseable `IP:port`, invalid SOCKS4
+        // user ID, ...) also arrives as a `NetworkBuilder` error, but it is a
+        // *configuration* mistake, not a policy one — route it to
+        // `InvalidConfigError` like every other bad create option. Matched on
+        // the variant, never on the message text.
+        NetworkBuilder(BuildError::InvalidOutboundProxy { .. }) => "InvalidConfigError",
         // Give the already-defined-but-orphaned `NetworkPolicyError` a mapping:
         // a builder parse/validation error from `network(|n| ...)`. The gem
         // unconditionally enables the core's `net` feature (default-features),

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);
                 }
@@ -378,12 +390,22 @@ impl Sandbox {
             .transpose()?;
         let max_connections = conv::opt::<usize>(opts, "max_connections")?;
         let trust_host_cas = conv::opt::<bool>(opts, "trust_host_cas")?;
+        // strict: fail-closed hostname-policy enforcement (v0.6.18). A
+        // hostname-rule allow must be backed by an inspectable request
+        // authority (plain-HTTP Host, or SNI/authority under TLS interception);
+        // otherwise the flow is denied before the upstream dial. Mirrors the
+        // Python SDK's `Network(strict=...)`. Create-only here to match the
+        // Python SDK's `modify` surface, which does not expose `strict`; the
+        // core's generated network config patch (ConfigPatch derive) does
+        // carry a `strict` field, so this is SDK parity, not a core limit.
+        let strict = conv::opt::<bool>(opts, "strict")?;
         if dns.is_some()
             || tls.is_some()
             || ipv4_pool.is_some()
             || ipv6_pool.is_some()
             || max_connections.is_some()
             || trust_host_cas.is_some()
+            || strict.is_some()
         {
             b = b.network(move |mut n| {
                 if let Some(dns) = dns {
@@ -438,6 +460,9 @@ impl Sandbox {
                 if let Some(t) = trust_host_cas {
                     n = n.trust_host_cas(t);
                 }
+                if let Some(s) = strict {
+                    n = n.strict(s);
+                }
                 n
             });
         }
@@ -463,6 +488,18 @@ impl Sandbox {
                 })
             });
         }
+        // proxy: outbound SOCKS4/SOCKS5 proxy for egress traffic (v0.6.17,
+        // upstream #1234/#1507). The Ruby layer (`OutboundProxy.coerce`) has
+        // already validated the shape and normalized it to the Python SDK's
+        // `_to_dict()` wire form: {protocol:, address:, user_id?:,
+        // credentials?: {username:, password: {kind: "env", var:}}}. Only the
+        // password's env var NAME travels; the core resolves it host-side.
+        // Applied exactly as sdk/python/src/helpers.rs does; the address is
+        // parsed by the core's proxy builder (an invalid one surfaces as
+        // NetworkBuilder(InvalidOutboundProxy) → InvalidConfigError, see error.rs).
+        if let Some(proxy) = conv::opt::<RHash>(opts, "proxy")? {
+            b = apply_outbound_proxy(b, proxy)?;
+        }
         // init: hand guest PID 1 to an init system. The Ruby layer normalizes
         // `init:` to a Hash { cmd:, args?:, env?: }. `init_with` with empty
         // args/env builds the same HandoffInit as the plain `init(cmd)`, so route
@@ -509,6 +546,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 +627,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 +698,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 +740,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)?;
@@ -1362,6 +1445,63 @@ fn parse_dns(d: RHash) -> Result<DnsSpec, Error> {
     })
 }
 
+/// Apply the normalized `proxy` create option (v0.6.17) to the builder.
+/// Mirrors `sdk/python/src/helpers.rs`: `socks4` takes an optional `user_id`,
+/// `socks5` optional `credentials` whose password is an env-backed
+/// [`SecretSource`] (the only kind). Unknown protocols and non-env password
+/// sources are rejected here (the Ruby layer already does, so these are
+/// belt-and-braces for callers of the native API).
+fn apply_outbound_proxy(b: SandboxBuilder, proxy: RHash) -> Result<SandboxBuilder, Error> {
+    let protocol = conv::opt_string(proxy, "protocol")?
+        .ok_or_else(|| error::base_error("proxy requires protocol:"))?;
+    let address = conv::opt_string(proxy, "address")?
+        .ok_or_else(|| error::base_error("proxy requires address:"))?;
+    match protocol.as_str() {
+        "socks4" => {
+            let user_id = conv::opt_string(proxy, "user_id")?;
+            Ok(b.proxy(move |p| {
+                let p = p.socks4(address);
+                match user_id {
+                    Some(user_id) => p.user_id(user_id),
+                    None => p,
+                }
+            }))
+        }
+        "socks5" => {
+            let credentials = match conv::opt::<RHash>(proxy, "credentials")? {
+                None => None,
+                Some(c) => {
+                    let username = conv::opt_string(c, "username")?
+                        .ok_or_else(|| error::base_error("SOCKS5 credentials require username:"))?;
+                    let password = conv::opt::<RHash>(c, "password")?
+                        .ok_or_else(|| error::base_error("SOCKS5 credentials require password:"))?;
+                    let kind = conv::opt_string(password, "kind")?.ok_or_else(|| {
+                        error::base_error("SOCKS5 password source requires kind:")
+                    })?;
+                    if kind != "env" {
+                        return Err(error::base_error(format!(
+                            "unsupported SOCKS5 password source {kind:?}; only env is supported"
+                        )));
+                    }
+                    let var = conv::opt_string(password, "var")?
+                        .ok_or_else(|| error::base_error("SOCKS5 password source requires var:"))?;
+                    Some((username, SecretSource::env(var)))
+                }
+            };
+            Ok(b.proxy(move |p| {
+                let p = p.socks5(address);
+                match credentials {
+                    Some((username, password)) => p.credentials(username, password),
+                    None => p,
+                }
+            }))
+        }
+        other => Err(error::base_error(format!(
+            "unsupported outbound proxy protocol {other:?}; expected socks4 or socks5"
+        ))),
+    }
+}
+
 /// One token bucket of the `rate_limiter` create option (v0.6.9):
 /// `(size, refill_time_ms, one_time_burst)`. Size is bytes for bandwidth
 /// buckets, frames for ops buckets.
@@ -2096,6 +2236,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 {
@@ -2422,6 +2611,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()
@@ -2470,6 +2666,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> {
@@ -2607,6 +2842,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))?;
@@ -2614,6 +2853,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))?;
@@ -2628,6 +2868,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))?;
@@ -2667,6 +2910,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))?;
@@ -2674,6 +2918,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")