microsandbox-rb 0.17.0 → 0.17.1

data/ext/microsandbox/src/sandbox.rs

@@ -7,6 +7,7 @@
 //! as a plain Ruby `Hash`/`Array`/`String` and shaped into value objects by the
 //! Ruby layer.
 
+use std::path::PathBuf;
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -39,6 +40,7 @@ use tokio::task::JoinHandle;
 use crate::conv;
 use crate::error;
 use crate::exec::ExecHandle;
+use crate::host_path::{self, HostPaths};
 use crate::runtime::{block_on, ruby};
 use crate::stream::{LogStream, MetricsStream};
 
@@ -75,6 +77,9 @@ impl Sandbox {
     /// Shared by `create` (blocking) and `create_with_progress` (streaming pull).
     fn build_builder(name: String, opts: RHash) -> Result<SandboxBuilder, Error> {
         let mut b = microsandbox::Sandbox::builder(name);
+        // Relative host paths are anchored to the current directory here, once,
+        // before the core persists them (see host_path.rs).
+        let host_paths = HostPaths::for_default_backend();
 
         if let Some(v) = conv::opt_string(opts, "image")? {
             if let Some(fstype) = conv::opt_string(opts, "fstype")? {
@@ -83,13 +88,17 @@ impl Sandbox {
                 // image_with(disk().fstype()). (A bare `image` string otherwise
                 // auto-detects OCI vs disk by extension.) Errors in disk()/fstype()
                 // are captured on the builder and surface at create().
-                b = b.image_with(move |i| i.disk(v).fstype(fstype));
+                let path = host_paths.pin(v, "root disk image path")?;
+                b = b.image_with(move |i| i.disk(path).fstype(fstype));
             } else {
-                b = b.image(v);
+                b = match host_paths.pin_image(v)? {
+                    host_path::Image::Text(text) => b.image(text),
+                    host_path::Image::Path(path) => b.image(path),
+                };
             }
         }
         if let Some(v) = conv::opt_string(opts, "from_snapshot")? {
-            b = b.from_snapshot(v);
+            b = b.from_snapshot(host_paths.pin_snapshot(v)?);
         }
         if let Some(v) = conv::opt_u8(opts, "cpus")? {
             b = b.cpus(v);
@@ -208,27 +217,35 @@ impl Sandbox {
             // the per-mount opt-out. Valid for bind/named-directory mounts —
             // the core rejects it elsewhere at build().
             let follow_root_symlinks = conv::opt::<bool>(m, "follow_root_symlinks")?;
-            // bind/named/disk require a source; tmpfs must not have one.
-            match kind.as_str() {
-                "bind" | "named" | "disk" if source.is_some() => {}
-                "bind" | "named" | "disk" => {
+            // bind/named/disk require a source; tmpfs must not have one. A
+            // bind or disk source is a host path; a named source is a volume
+            // name and is never resolved.
+            let backing = match (kind.as_str(), source) {
+                ("bind", Some(host)) => {
+                    MountBacking::Bind(host_paths.pin(host, "bind mount host path")?)
+                }
+                ("disk", Some(host)) => {
+                    MountBacking::Disk(host_paths.pin(host, "disk mount host path")?)
+                }
+                ("named", Some(name)) => MountBacking::Named(name),
+                ("bind" | "named" | "disk", None) => {
                     return Err(error::base_error(format!(
                         "volume mount kind {kind:?} requires a source"
                     )))
                 }
-                "tmpfs" => {}
-                other => {
+                ("tmpfs", _) => MountBacking::Tmpfs,
+                (other, _) => {
                     return Err(error::base_error(format!(
                         "unknown volume mount kind {other:?} (expected bind/named/tmpfs/disk)"
                     )))
                 }
-            }
+            };
             b = b.volume(guest, move |mut mb| {
-                mb = match kind.as_str() {
-                    "named" => mb.named(source.unwrap()),
-                    "tmpfs" => mb.tmpfs(),
-                    "disk" => mb.disk(source.unwrap()),
-                    _ => mb.bind(source.unwrap()), // "bind"
+                mb = match backing {
+                    MountBacking::Named(name) => mb.named(name),
+                    MountBacking::Tmpfs => mb.tmpfs(),
+                    MountBacking::Disk(host) => mb.disk(host),
+                    MountBacking::Bind(host) => mb.bind(host),
                 };
                 if let Some(n) = size_mib {
                     mb = mb.size(n);
@@ -272,7 +289,7 @@ impl Sandbox {
         // patches: rootfs modifications applied before boot. The Ruby layer
         // normalizes each `Microsandbox::Patch.*` into a string-keyed Hash with
         // a `kind` discriminator; mirrors the Python binding's `apply_patch`.
-        for patch in parse_patches(opts)? {
+        for patch in parse_patches(opts, host_paths)? {
             b = b.add_patch(patch);
         }
         if let Some(net) = conv::opt_string(opts, "network")? {
@@ -326,7 +343,7 @@ impl Sandbox {
         // layer maps the deprecated `oci_upper_size:` kwarg to the managed kind
         // before it reaches the wire.
         if let Some(v) = conv::opt::<Value>(opts, "root_disk")? {
-            let spec = parse_root_disk(v)?;
+            let spec = parse_root_disk(v, host_paths)?;
             b = b.root_disk_with(move |d| spec.apply(d));
         }
         // Registry connection settings, for private / non-default registries:
@@ -374,7 +391,7 @@ impl Sandbox {
             .map(parse_dns)
             .transpose()?;
         let tls = conv::opt::<RHash>(opts, "tls")?
-            .map(parse_tls)
+            .map(|t| parse_tls(t, host_paths))
             .transpose()?;
         let ipv4_pool = conv::opt_string(opts, "ipv4_pool")?
             .map(|s| {
@@ -1217,7 +1234,7 @@ fn patch_bytes(h: RHash, key: &str) -> Result<Vec<u8>, Error> {
 /// Parse the `patches` option into core `Patch` operations. The Ruby layer
 /// normalizes each `Microsandbox::Patch.*` into a string-keyed Hash carrying a
 /// `kind` discriminator plus the variant-specific fields.
-fn parse_patches(opts: RHash) -> Result<Vec<Patch>, Error> {
+fn parse_patches(opts: RHash, host_paths: HostPaths) -> Result<Vec<Patch>, Error> {
     let mut out = Vec::new();
     for h in conv::opt_hash_vec(opts, "patches")? {
         let kind = patch_str(h, "kind")?;
@@ -1241,13 +1258,13 @@ fn parse_patches(opts: RHash) -> Result<Vec<Patch>, Error> {
                 content: patch_str(h, "content")?,
             },
             "copy_file" => Patch::CopyFile {
-                src: patch_str(h, "src")?.into(),
+                src: host_paths.pin(patch_str(h, "src")?, "patch source path")?,
                 dst: patch_str(h, "dst")?,
                 mode,
                 replace,
             },
             "copy_dir" => Patch::CopyDir {
-                src: patch_str(h, "src")?.into(),
+                src: host_paths.pin(patch_str(h, "src")?, "patch source path")?,
                 dst: patch_str(h, "dst")?,
                 replace,
             },
@@ -1584,20 +1601,25 @@ struct TlsSpec {
     verify_upstream: Option<bool>,
     intercepted_ports: Option<Vec<u16>>,
     block_quic: Option<bool>,
-    upstream_ca_cert: Option<String>,
-    intercept_ca_cert: Option<String>,
-    intercept_ca_key: Option<String>,
+    upstream_ca_cert: Option<PathBuf>,
+    intercept_ca_cert: Option<PathBuf>,
+    intercept_ca_key: Option<PathBuf>,
 }
 
-fn parse_tls(t: RHash) -> Result<TlsSpec, Error> {
+fn parse_tls(t: RHash, host_paths: HostPaths) -> Result<TlsSpec, Error> {
+    let pin = |key: &str, label: &str| {
+        conv::opt_string(t, key)?
+            .map(|path| host_paths.pin(path, label))
+            .transpose()
+    };
     Ok(TlsSpec {
         bypass: conv::opt_string_vec(t, "bypass")?,
         verify_upstream: conv::opt::<bool>(t, "verify_upstream")?,
         intercepted_ports: conv::opt::<Vec<u16>>(t, "intercepted_ports")?,
         block_quic: conv::opt::<bool>(t, "block_quic")?,
-        upstream_ca_cert: conv::opt_string(t, "upstream_ca_cert")?,
-        intercept_ca_cert: conv::opt_string(t, "intercept_ca_cert")?,
-        intercept_ca_key: conv::opt_string(t, "intercept_ca_key")?,
+        upstream_ca_cert: pin("upstream_ca_cert", "upstream CA certificate path")?,
+        intercept_ca_cert: pin("intercept_ca_cert", "interception CA certificate path")?,
+        intercept_ca_key: pin("intercept_ca_key", "interception CA key path")?,
     })
 }
 
@@ -1711,6 +1733,14 @@ fn network_profile_from_str(s: &str) -> Result<NetworkProfile, Error> {
     }
 }
 
+/// What backs a volume mount, with any host path already pinned.
+enum MountBacking {
+    Bind(PathBuf),
+    Disk(PathBuf),
+    Named(String),
+    Tmpfs,
+}
+
 /// Parsed `root_disk` create option. Integer shorthand = managed upper of N
 /// MiB (mirrors Python's `root_disk=8192` and the CLI bare-size form); Hash =
 /// explicit kind. Kind/field cross-validation (size on a disk image, etc.)
@@ -1726,7 +1756,7 @@ struct RootDiskSpec {
 enum RootDiskKindSpec {
     Managed,
     Tmpfs,
-    Disk(String),
+    Disk(PathBuf),
     Flat,
 }
 
@@ -1754,7 +1784,7 @@ impl RootDiskSpec {
     }
 }
 
-fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
+fn parse_root_disk(v: Value, host_paths: HostPaths) -> Result<RootDiskSpec, Error> {
     if let Ok(mib) = u32::try_convert(v) {
         return Ok(RootDiskSpec {
             kind: RootDiskKindSpec::Managed,
@@ -1777,7 +1807,7 @@ fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
             let Some(path) = conv::opt_string(h, "path")? else {
                 return Err(error::base_error("root_disk disk kind requires path:"));
             };
-            RootDiskKindSpec::Disk(path)
+            RootDiskKindSpec::Disk(host_paths.pin(path, "root disk image path")?)
         }
         Some("flat") => RootDiskKindSpec::Flat,
         Some(other) => {

data/ext/microsandbox/src/volume.rs

@@ -3,11 +3,12 @@
 //! Mirrors `sdk/python/src/volume.rs`. Static async CRUD over the volume store;
 //! results are returned as plain Ruby Hashes/Arrays.
 
+use std::path::{Component, Path};
 use std::sync::Arc;
 
 use magnus::{function, method, prelude::*, Error, RArray, RHash, RModule, RString, Ruby};
 use microsandbox::volume::VolumeHandle;
-use microsandbox::Backend;
+use microsandbox::{Backend, MicrosandboxError};
 
 use crate::conv;
 use crate::error;
@@ -104,6 +105,23 @@ fn remove(name: String) -> Result<(), Error> {
     block_on(microsandbox::Volume::remove(&name)).map_err(error::to_ruby)
 }
 
+/// Volume paths are relative to the volume root and never need a `..` segment,
+/// so one is refused before the path reaches the core's resolver (which keeps
+/// its own containment check). Enforced here rather than only in the Ruby
+/// wrapper because `Microsandbox::Native::VolumeFs` is callable directly.
+fn contained(path: &str) -> Result<&str, Error> {
+    if Path::new(path)
+        .components()
+        .any(|part| matches!(part, Component::ParentDir))
+    {
+        return Err(error::to_ruby(MicrosandboxError::SandboxFsOps(
+            "path traversal outside volume root (`..` segments are not allowed in volume paths)"
+                .into(),
+        )));
+    }
+    Ok(path)
+}
+
 /// A host-side filesystem view over a named volume — read/write its contents
 /// without a running sandbox. Mirrors the Python `VolumeFs` / Node `VolumeFs`.
 /// The core `VolumeFs<'a>` borrows the volume name, so (like the Python binding)
@@ -131,26 +149,30 @@ impl VolumeFs {
     }
 
     fn read(&self, path: String) -> Result<RString, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        let bytes = block_on(fs.read(&path)).map_err(error::to_ruby)?;
+        let bytes = block_on(fs.read(path)).map_err(error::to_ruby)?;
         Ok(ruby().str_from_slice(bytes.as_ref()))
     }
 
     fn read_text(&self, path: String) -> Result<String, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.read_to_string(&path)).map_err(error::to_ruby)
+        block_on(fs.read_to_string(path)).map_err(error::to_ruby)
     }
 
     fn write(&self, path: String, data: RString) -> Result<(), Error> {
         // Copy the bytes out while the GVL is held (GC.compact could move them).
         let bytes = unsafe { data.as_slice() }.to_vec();
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.write(&path, &bytes)).map_err(error::to_ruby)
+        block_on(fs.write(path, &bytes)).map_err(error::to_ruby)
     }
 
     fn list(&self, path: String) -> Result<RArray, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        let entries = block_on(fs.list(&path)).map_err(error::to_ruby)?;
+        let entries = block_on(fs.list(path)).map_err(error::to_ruby)?;
         let arr = ruby().ary_new();
         for entry in &entries {
             arr.push(fs_entry_to_hash(entry))?;
@@ -159,38 +181,47 @@ impl VolumeFs {
     }
 
     fn mkdir(&self, path: String) -> Result<(), Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.mkdir(&path)).map_err(error::to_ruby)
+        block_on(fs.mkdir(path)).map_err(error::to_ruby)
     }
 
     fn remove_file(&self, path: String) -> Result<(), Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.remove(&path)).map_err(error::to_ruby)
+        block_on(fs.remove(path)).map_err(error::to_ruby)
     }
 
     fn remove_dir(&self, path: String) -> Result<(), Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.remove_dir(&path)).map_err(error::to_ruby)
+        block_on(fs.remove_dir(path)).map_err(error::to_ruby)
     }
 
     fn exists(&self, path: String) -> Result<bool, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        block_on(fs.exists(&path)).map_err(error::to_ruby)
+        block_on(fs.exists(path)).map_err(error::to_ruby)
     }
 
     fn copy(&self, from: String, to: String) -> Result<(), Error> {
+        let from = contained(&from)?;
+        let to = contained(&to)?;
         let fs = self.fs();
-        block_on(fs.copy(&from, &to)).map_err(error::to_ruby)
+        block_on(fs.copy(from, to)).map_err(error::to_ruby)
     }
 
     fn rename(&self, from: String, to: String) -> Result<(), Error> {
+        let from = contained(&from)?;
+        let to = contained(&to)?;
         let fs = self.fs();
-        block_on(fs.rename(&from, &to)).map_err(error::to_ruby)
+        block_on(fs.rename(from, to)).map_err(error::to_ruby)
     }
 
     fn stat(&self, path: String) -> Result<RHash, Error> {
+        let path = contained(&path)?;
         let fs = self.fs();
-        let meta = block_on(fs.stat(&path)).map_err(error::to_ruby)?;
+        let meta = block_on(fs.stat(path)).map_err(error::to_ruby)?;
         Ok(fs_metadata_to_hash(&meta))
     }
 }

data/lib/microsandbox/fs.rb

@@ -27,7 +27,7 @@ module Microsandbox
 
     # @return [Time, nil] last-modified time, if known
     def modified
-      @modified_ms && Time.at(@modified_ms / 1000.0)
+      Microsandbox.time_from_ms(@modified_ms)
     end
 
     def file? = @type == :file
@@ -64,12 +64,12 @@ module Microsandbox
 
     # @return [Time, nil] last-modified time, if known
     def modified
-      @modified_ms && Time.at(@modified_ms / 1000.0)
+      Microsandbox.time_from_ms(@modified_ms)
     end
 
     # @return [Time, nil] creation time, if known
     def created
-      @created_ms && Time.at(@created_ms / 1000.0)
+      Microsandbox.time_from_ms(@created_ms)
     end
 
     def inspect
@@ -188,11 +188,7 @@ module Microsandbox
       sink = FsWriteSink.new(@native.fs_write_stream(path.to_s))
       return sink unless block_given?
 
-      begin
-        yield sink
-      ensure
-        sink.close
-      end
+      Microsandbox.close_after(sink) { yield sink }
     end
   end
 

data/lib/microsandbox/image.rb

@@ -18,12 +18,12 @@ module Microsandbox
 
     # @return [Time, nil]
     def created_at
-      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+      Microsandbox.time_from_ms(@created_at_ms)
     end
 
     # @return [Time, nil]
     def last_used_at
-      @last_used_at_ms && Time.at(@last_used_at_ms / 1000.0)
+      Microsandbox.time_from_ms(@last_used_at_ms)
     end
 
     def inspect

data/lib/microsandbox/log_entry.rb

@@ -22,7 +22,7 @@ module Microsandbox
 
     # @return [Time] wall-clock capture time
     def timestamp
-      Time.at(@timestamp_ms / 1000.0)
+      Microsandbox.time_from_ms(@timestamp_ms)
     end
 
     # @return [String] the captured bytes decoded as UTF-8 (lossy — invalid byte

data/lib/microsandbox/metrics.rb

@@ -53,7 +53,7 @@ module Microsandbox
 
     # @return [Time] when this snapshot was captured
     def timestamp
-      Time.at(@timestamp_ms / 1000.0)
+      Microsandbox.time_from_ms(@timestamp_ms)
     end
 
     def inspect

data/lib/microsandbox/outbound_proxy.rb

@@ -246,6 +246,14 @@ module Microsandbox
       if address.empty?
         raise ArgumentError, "proxy address must be a non-empty \"IP:port\" String (got \"\")"
       end
+      # A URL-style address (`socks5://user:pass@host:1080`) is never valid, and
+      # the core would quote it back in its error. Refuse it by shape, without
+      # echoing it, so the embedded credentials stay out of logs.
+      if address.match?(%r{@|://|\s})
+        raise ArgumentError,
+          "proxy address must be \"IP:port\" with no scheme, credentials or whitespace " \
+          "(pass SOCKS5 credentials as username:/password:)"
+      end
       # Same rules as the Python SDK's OutboundProxy.__post_init__; the address
       # itself is parsed by the core (which reports e.g. "invalid SOCKS5 proxy
       # address" as an InvalidConfigError at create time).

data/lib/microsandbox/sandbox.rb

@@ -42,13 +42,13 @@ module Microsandbox
     # @return [Time, nil]
     def created_at
       ms = @native.created_at_ms
-      ms && Time.at(ms / 1000.0)
+      Microsandbox.time_from_ms(ms)
     end
 
     # @return [Time, nil]
     def updated_at
       ms = @native.updated_at_ms
-      ms && Time.at(ms / 1000.0)
+      Microsandbox.time_from_ms(ms)
     end
 
     # Gracefully stop the sandbox (SIGTERM→SIGKILL escalation, 10s default).
@@ -263,7 +263,7 @@ module Microsandbox
 
     # @return [Time] when the stopped state was observed
     def observed_at
-      Time.at(@observed_at_ms / 1000.0)
+      Microsandbox.time_from_ms(@observed_at_ms)
     end
 
     def inspect
@@ -495,6 +495,7 @@ module Microsandbox
       # @return [Sandbox, Object] the sandbox, or the block's return value
       def create(name, **kwargs, &block)
         opts = build_create_opts(**kwargs)
+        Microsandbox.ensure_runtime!
         sandbox = new(Native::Sandbox.create(name.to_s, opts))
         return sandbox unless block_given?
 
@@ -551,6 +552,7 @@ module Microsandbox
       # @return [Sandbox, Object] the live sandbox, or the block's return value
       def connect_or_create(name, **kwargs, &block)
         opts = build_create_opts(**kwargs)
+        Microsandbox.ensure_runtime!
         sandbox = new(Native::Sandbox.connect_or_create(name.to_s, opts))
         return sandbox unless block_given?
 
@@ -582,11 +584,15 @@ module Microsandbox
             "for progress, then call #sandbox and stop it when done"
         end
         opts = build_create_opts(**kwargs)
+        Microsandbox.ensure_runtime!
         PullSession.new(Native::Sandbox.create_with_progress(name.to_s, opts))
       end
 
       # @api private
-      # Shared keyword-option builder for {create}/{create_with_progress}.
+      # Shared keyword-option builder for {create}/{connect_or_create}/
+      # {create_with_progress}. Pure validation and normalization: the callers
+      # provision the runtime ({Microsandbox.ensure_runtime!}) only after this
+      # returns, so a rejected option never triggers a runtime download.
       def build_create_opts(image: nil, cpus: nil, max_cpus: nil, memory: nil, max_memory: nil,
         env: nil, workdir: nil,
         shell: nil, user: nil, hostname: nil, labels: nil, scripts: nil,
@@ -610,7 +616,14 @@ module Microsandbox
         if root_disk && oci_upper_size
           raise ArgumentError, "pass either root_disk: or oci_upper_size:, not both"
         end
-        Microsandbox.ensure_runtime!
+        # The core refuses patches on a snapshot-booted sandbox, but only after
+        # it has claimed the sandbox name on disk. Refuse the pair before any
+        # side effect.
+        if from_snapshot && patches && !Array(patches).empty?
+          raise ArgumentError,
+            "patches: cannot be combined with from_snapshot: (a snapshot restores its own " \
+            "root disk; apply changes after boot with sandbox.fs instead)"
+        end
         # `fstype:` names the inner filesystem of a disk-image rootfs, so it only
         # applies when `image:` is a disk-image path (a local path ending in
         # .raw/.qcow2/.vmdk). Routing an OCI ref (e.g. "python") through the
@@ -779,7 +792,16 @@ module Microsandbox
       end
 
       def stringify(hash)
-        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
+        # Anything that converts to pairs is fine (a Hash, ENV, an Array of
+        # pairs). For the rest, name the type, not the value: env values are
+        # often credentials.
+        pairs = begin
+          hash.to_h if hash.respond_to?(:to_h)
+        rescue TypeError
+          nil
+        end
+        raise ArgumentError, "expected a Hash of names to values (got #{hash.class})" unless pairs
+        pairs.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
       end
 
       # Wrap a native page Hash ({"sandboxes" => [...], "next_cursor" => ...})
@@ -844,7 +866,21 @@ module Microsandbox
       # :inject_basic_auth / :inject_query / :inject_body, and :on_violation (see
       # {#normalize_violation}).
       def normalize_secrets(secrets)
-        Array(secrets).map { |spec| normalize_secret(spec) }
+        if secrets.is_a?(Hash)
+          # One spec given bare is fine. A Hash keyed by variable name is the
+          # shape {Sandbox#modify} takes, where `env:` also means something
+          # else (the HOST variable to read); it is not a create-time spec.
+          unless secrets.key?(:env) || secrets.key?("env")
+            raise ArgumentError,
+              "secrets: takes an Array of Hashes like { env:, value:, host: } at create time; " \
+              "the { \"NAME\" => { ... } } form belongs to #modify"
+          end
+          secrets = [secrets]
+        end
+        Array(secrets).map do |spec|
+          raise ArgumentError, "secret spec must be a Hash (got #{spec.class})" unless spec.is_a?(Hash)
+          normalize_secret(spec)
+        end
       end
 
       # @api private
@@ -1409,9 +1445,11 @@ module Microsandbox
       # plain Hash) into string-keyed Hashes for the native layer. Values are
       # passed through unchanged (mode stays Integer, content stays String).
       def normalize_patches(patches)
+        patches = [patches] if patches.is_a?(Hash) # a single patch, not a list of pairs
         Array(patches).map do |p|
           unless p.is_a?(Hash)
-            raise ArgumentError, "patch must be a Hash (use Microsandbox::Patch.*): #{p.inspect}"
+            # Name the type, not the value: a patch can carry file content.
+            raise ArgumentError, "patch must be a Hash (use Microsandbox::Patch.*), got #{p.class}"
           end
           p.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
         end
@@ -1957,10 +1995,16 @@ module Microsandbox
 
     # The booted sandbox. Joins the create task (draining any remaining pull
     # progress first), so call it after iterating progress. The returned
-    # {Sandbox} is live — stop it when done. Memoized; callable once.
+    # {Sandbox} is live — stop it when done. Memoized: the native result can be
+    # taken only once, so a later call returns the same {Sandbox}, or re-raises
+    # the same error if the create failed.
     # @return [Sandbox]
     def sandbox
+      raise @failure if @failure
       @sandbox ||= Sandbox.new(@native.result)
+    rescue Microsandbox::Error => e
+      @failure ||= e
+      raise
     end
   end
 end

data/lib/microsandbox/snapshot.rb

@@ -92,7 +92,7 @@ module Microsandbox
 
     # @return [Time, nil]
     def created_at
-      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+      Microsandbox.time_from_ms(@created_at_ms)
     end
 
     # Re-open this snapshot's artifact (cheap metadata validation), returning a

data/lib/microsandbox/ssh.rb

@@ -173,11 +173,7 @@ module Microsandbox
       session = SftpClient.new(@native.sftp)
       return session unless block_given?
 
-      begin
-        yield session
-      ensure
-        session.close
-      end
+      Microsandbox.close_after(session) { yield session }
     end
 
     # Close the SSH client session. Idempotent. Sends the graceful protocol
@@ -245,11 +241,7 @@ module Microsandbox
       client = SshClient.new(@native.ssh_open_client(opts))
       return client unless block_given?
 
-      begin
-        yield client
-      ensure
-        client.close
-      end
+      Microsandbox.close_after(client) { yield client }
     end
 
     # Prepare a reusable SSH server endpoint for the sandbox.

data/lib/microsandbox/streams.rb

@@ -2,17 +2,20 @@
 
 module Microsandbox
   # A live stream of {LogEntry}s, returned by {Sandbox#log_stream}. Enumerable:
-  # iterate to consume entries as they are appended. With `follow: true` the
-  # iteration blocks for new entries until the sandbox stops; otherwise it ends
-  # once the historical log is drained.
+  # iterate to consume entries as they are appended. Without `follow:` the
+  # iteration ends once the historical log is drained. With `follow: true` it
+  # keeps waiting for new entries and does NOT end when the sandbox stops: the
+  # runtime follows the log file, not the sandbox, and there is no way to
+  # cancel the wait.
   #
   # @note **Single-pass, forward-only, single-consumer.** `each` drains a
   #   one-shot native channel, so it is *not* rewindable: a second `each` — or
   #   any `Enumerable` combinator after a partial drain (`to_a` twice, `count`
   #   then `each`, `first(n)` then `each`) — silently yields nothing. Iterate
   #   exactly once, from one thread. With `follow: true`, `each` blocks the
-  #   calling thread uninterruptibly until the sandbox stops (see DESIGN.md on
-  #   GVL release).
+  #   calling thread uninterruptibly and indefinitely (see DESIGN.md on GVL
+  #   release); a thread blocked there also keeps the process from exiting
+  #   normally, so follow from a process you are prepared to kill.
   #
   # @example
   #   sb.log_stream(follow: true).each { |entry| print entry.text }

data/lib/microsandbox/version.rb

@@ -8,7 +8,7 @@ module Microsandbox
   # Versioning section of the README for the full gem-to-runtime map. Must equal
   # the native ext's Cargo crate version (`Native.version`), enforced by
   # spec/unit/version_spec.rb.
-  VERSION = "0.17.0"
+  VERSION = "0.17.1"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in