microsandbox-rb 0.17.3 → 0.17.5

data/DESIGN.md

@@ -105,13 +105,27 @@ reached once the result is a Ruby object. What happens to it then:
 
 - **`Sandbox.create`, `Sandbox.connect_or_create`, `Sandbox.start`, and
   `PullSession#sandbox`** mask interrupts (`Thread.handle_interrupt(Object =>
-  :never)`) around the native call plus the wrap, and an `ensure` **stops the
-  sandbox** when an exception or a kill cuts in before the caller has the
-  object — but only a sandbox the call owns (`Sandbox#owns_lifecycle?`, the
-  same predicate as `connect_or_create`'s block form): one that was already
-  running for someone else is left running. A `SIGINT` cannot be masked this
-  way; it can arrive before the wrapper is assigned, and then the next case
-  applies.
+  :never)`) around the native call only, so the bare `Native::Sandbox` is
+  bound to a local before a queued exception or kill can land; an `ensure`
+  then **stops the sandbox** when one cuts in before the caller has the
+  object — but only a sandbox the call owns (`owns_lifecycle`, the same
+  predicate as `connect_or_create`'s block form): one that was already
+  running for someone else is left running. The Ruby wrapper is constructed
+  *after* the mask, with normal interrupt handling, because `new` runs a
+  subclass's `initialize`: a constructor that blocks or runs long must not
+  hold a `Timeout.timeout` or `Thread#kill` back until it returns. So the
+  cleanup works on the native handle (its `owns_lifecycle` and `stop`), never
+  on the wrapper, and covers the window from the native handle's assignment
+  through the wrapper's construction: an interrupt delivered as the mask ends
+  (before `new` runs), one delivered inside a subclass's `initialize`, and an
+  exception that `initialize` raises itself. That cleanup is best-effort, not
+  a guarantee for every lost return: a *further* interrupt that arrives during
+  the cleanup itself, before the native `stop` has started, or one delivered
+  at the method's final return boundary, after the wrapper has been handed
+  off but before the caller has assigned it, leaves the teardown to GC (as it
+  did before construction moved out of the mask). A `SIGINT` cannot be masked
+  this way; it can arrive before the native handle is assigned, and then the
+  next case applies.
 - **Every other wrapper** (`ExecHandle`, streams, SSH clients, write sinks, …)
   and every plain result simply becomes garbage; GC frees the wrapper and the
   Rust value's `Drop` closes the session or connection.
@@ -129,7 +143,9 @@ for the thread's next blocking operation. The four acquisition methods are
 the exception: their own `Object => :never` mask sits on top of the caller's,
 so a deferred exception is not raised at the native call's entry there — the
 sandbox is returned and the exception is delivered at the next blocking
-operation after the acquisition.
+operation after the acquisition. (If that blocking operation is inside a
+subclass's `initialize`, the caller does not have the object yet, so the
+sandbox is stopped as above.)
 
 `spec/fake_runtime/interrupt_safety_spec.rb` pins all of this against the real
 extension, driving it with a fake `msb` (`spec/support/fake_runtime/`) whose
@@ -148,23 +164,62 @@ Linux and die with `SIGTRAP` on macOS — and so does *destroying* it, because
 the destructors wake the same missing threads (on macOS, replacing an
 inherited `LocalBackend` was enough to kill the child). One rule covers all of
 it: **inherited native state is never used and never dropped in the child. It
-is leaked, once per fork, and replaced by state built in the child.** Three
-pieces implement it, all keyed on the pid (`runtime::current_pid`):
-
-- **Runtime cell** (`runtime.rs`). The runtime and the pid it was built under
-  live in one heap cell behind one `AtomicPtr`. `runtime()` returns the cell's
-  runtime when its pid is ours; otherwise it builds a new cell and publishes
-  it with a compare-exchange (a loser of that race in the same process drops
-  its own, never-published runtime). There is no mutex, so nothing can be
-  inherited locked or poisoned, and no window in which pointer and pid
-  disagree. A cell built by a parent process is leaked: `Runtime`'s `Drop`
-  joins worker threads that do not exist.
-- **Backend generation** (`backend.rs`). The binding records how the default
+is leaked, once per fork, and replaced by state built in the child.**
+
+That needs a reliable answer to "was this built by the process I am?". The
+binding's answer is a **process identity** (`runtime::ProcessIdentity`): the
+pid together with a *fork generation*. At extension load the binding
+registers a `pthread_atfork` child handler whose only work is one atomic
+increment of a counter; the child inherits its parent's counter as plain
+memory, and the handler, running in the child before `fork` returns there,
+makes it one higher. `Kernel#fork` calls libc's `fork`, which runs atfork
+handlers on Linux and macOS, so a child, grandchild, … of the loading process
+has generation 1, 2, …, whatever its pid. Everything the binding builds is
+tagged with the identity of the process that built it, and two identities
+are equal only when both halves are:
+
+- the generation tells apart a descendant that was handed an ancestor's pid
+  again by the kernel (the pid counter wrapped onto exactly that value)
+  without any SDK call in between — pid alone would take it for the
+  ancestor;
+- the pid tells apart a process created without running atfork handlers
+  (`vfork`, a raw `clone`), whose generation equals its parent's.
+
+The handler is async-signal-safe (a lock-free atomic add, no allocation, no
+lock, no Ruby), as a child handler must be; `Relaxed` ordering suffices
+because the forked child is single-threaded until it starts threads, which
+see the counter through the spawn's own synchronization. Handlers cannot be
+unregistered, and Ruby never unloads an extension, so the handler stays
+valid for the life of the process. Should registration fail (`ENOMEM`), the
+generation stays 0 and the identity is effectively the pid alone.
+Three spec-only diagnostics on `Native` expose it: `fork_generation` returns
+the counter, and `fork_identity_equal` / `fork_identity_guard` run the real
+comparisons (`==`, the packed backend word, a handle's ownership check) on
+identities a spec chooses — the only way to pin that both halves decide,
+since a real fork changes both and pid reuse cannot be staged
+(`spec/unit/fork_identity_spec.rb`).
+
+Three pieces use the identity:
+
+- **Runtime cell** (`runtime.rs`). The runtime and the identity of the process
+  that built it live in one heap cell behind one `AtomicPtr`. `runtime()`
+  returns the cell's runtime when that identity is ours; otherwise it builds a
+  new cell and publishes it with a compare-exchange (a loser of that race in
+  the same process drops its own, never-published runtime). There is no mutex,
+  so nothing can be inherited locked or poisoned, and no window in which
+  pointer and identity disagree. A cell built by a parent process is leaked:
+  `Runtime`'s `Drop` joins worker threads that do not exist.
+- **Backend record** (`backend.rs`). The binding records how the default
   backend was chosen — the core's own ladder (environment, profile, config
   file), or an explicit `set_default_backend`/`with_backend` selection — and
-  the pid it belongs to. `ensure_this_process_backend` runs, with the GVL
-  held, at the start of every `block_on` and of every synchronous entry that
-  reads the backend. In a process whose pid differs from the recorded one it
+  the identity of the process it belongs to (one `AtomicU64`, pid and
+  generation, written and read whole). `ensure_this_process_backend` runs,
+  with the GVL held, at the start of every `block_on` and of every synchronous
+  entry that reads the backend. The one exception is the runtime installer
+  (`Native.install`, `Native.setup`): it never reads the backend, so it runs
+  through `block_on_runtime_install`, which skips the check, and a child that
+  installs leaves the record alone for its first call that does use the
+  backend. In a process whose identity differs from the recorded one it
   builds a fresh backend from the record, swaps it into the core and
   `mem::forget`s the inherited one, along with the backends that open
   `with_backend` scopes had saved for their restore. A scope the parent opened
@@ -185,20 +240,23 @@ pieces implement it, all keyed on the pid (`runtime::current_pid`):
   the error is reported (by `with_backend` as a warning when the block itself
   raised, so that the block's exception is the one that propagates).
 - **`ForkGuarded<T>`** (`runtime.rs`). The payload of every `#[magnus::wrap]`
-  type sits in one, tagged with the creating pid. `get()` is the only way to
-  it for anything that acts on the value, and in another process it returns
-  `Microsandbox::ForkedHandleError` (there is no `Deref`, so an unchecked
-  access does not compile). Its `Drop` runs the payload's destructor only in
-  the creating process; a child that garbage-collects an inherited handle —
-  at the latest when it exits, since Ruby frees every wrapped object then —
-  leaks it. Accessors that only copy plain data out of the value (`name`,
-  `id`, the `SandboxHandle` snapshot fields, `ExecHandle#id`) skip the check
-  through `peek()`, so a child can still read the name it needs to open a
-  handle of its own.
-
-What a child leaks is bounded: one runtime, the inherited default backend, the
-saved backend of each open scope, and each inherited handle it collects; plus
-one backend for each parent-opened scope it closes.
+  type sits in one, tagged with the identity of the creating process. `get()`
+  is the only way to it for anything that acts on the value, and in another
+  process it returns `Microsandbox::ForkedHandleError` (there is no `Deref`,
+  so an unchecked access does not compile). The message names the creating pid
+  and the current one; when they are equal — a reused pid — it says so rather
+  than naming the same pid twice as two processes. Its `Drop` runs the
+  payload's destructor only in the creating process; a child that
+  garbage-collects an inherited handle — at the latest when it exits, since
+  Ruby frees every wrapped object then — leaks it. Accessors that only copy
+  plain data out of the value (`name`, `id`, the `SandboxHandle` snapshot
+  fields, `ExecHandle#id`) skip the check through `peek()`, so a child can
+  still read the name it needs to open a handle of its own.
+
+What a child leaks is bounded: one runtime; once it uses the backend, the
+inherited default backend and the saved backend of each open scope; each
+inherited handle it collects; plus one backend for each parent-opened scope it
+closes. A child that only installs the runtime builds no backend.
 
 The mutexes involved (`backend.rs`) are only taken with the GVL held, and
 nothing that runs under them calls into Ruby or releases the GVL — Ruby
@@ -223,10 +281,45 @@ Limits, by design:
   with any threaded native library.
 - **Other libraries.** The SDK no longer touches inherited state; code that
   reaches it some other way can still hang or trap.
-- **Pid reuse.** Process identity is the pid. A descendant that ends up with
-  the pid of an ancestor whose state it inherited without any SDK use in
-  between would be mistaken for that ancestor. This needs the pid counter to
-  wrap onto exactly that value.
+- **macOS system frameworks.** On macOS a forked child that has not called
+  `exec` cannot use the system frameworks the core reaches for network and
+  credential work: CoreFoundation and libobjc are not fork-safe, and the
+  child dies — `SIGSEGV`, or `SIGABRT` from libobjc's fork check — inside the
+  framework. It is a crash, not an exception; nothing can rescue it. Two such
+  calls sit on SDK paths. Every HTTP client the core builds (reqwest, with the
+  `system-proxy` feature that the core crate enables; a downstream crate
+  cannot turn a Cargo feature off) looks up the system proxy settings through
+  SystemConfiguration (`SCDynamicStoreCopyProxies`) while it is built; and a
+  pull without explicit `registry_auth:` first looks for registry credentials
+  in the Keychain (`keyring`). So in a forked child on macOS, each of these
+  kills the child:
+  - any use of a cloud backend, however it is chosen (`set_default_backend`,
+    `with_backend`, `MSB_BACKEND`/`MSB_API_KEY`, a profile) — the child's
+    rebuild of the backend described above builds a client;
+  - `Sandbox.create` with an image that is not in the image cache yet, or
+    with `pull_policy: :always` (the Keychain lookup, then the registry
+    client; with `registry_auth:` only the latter);
+  - `Image.load` (it builds a registry client even for a local archive);
+  - runtime provisioning: `Microsandbox.install`, `Microsandbox.setup`, and
+    the first-use install in `ensure_runtime!`.
+
+  Whether the parent used the SDK makes no difference: a child of a parent
+  that only required the gem dies the same way, and
+  `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` does not prevent it. Calls that
+  stay on the local catalog and runtime are unaffected, including
+  `Sandbox.create` with an image already in the cache. On Linux the cloud
+  case is exercised by `spec/unit/fork_safety_spec.rb` and works (those
+  examples are skipped on macOS). On macOS, do this work in a process that
+  was not forked — the parent before it forks, or a fresh one
+  (`Process.spawn`, or `fork` followed by `exec`) — for example, pull the
+  images the workers need in the master before forking them.
+- **Forks that skip atfork handlers.** A process created with `vfork` or a
+  raw `clone` keeps its parent's generation, so only its pid identifies it.
+  Ruby itself never forks that way — `Kernel#fork` runs the handlers, and
+  `spawn`/`system` `exec` at once, which discards all of this state — so
+  mistaking such a process for its ancestor needs a native library that
+  clones without the handlers and then runs Ruby, together with exact pid
+  reuse.
 
 `spec/unit/fork_safety_spec.rb` (catalog only, no runtime),
 `spec/fake_runtime/fork_safety_spec.rb` (a live handle over the fake `msb`)

data/README.md

@@ -209,7 +209,7 @@ share the upstream tag, but the numbers have diverged since and the gem version
 is **not** an indicator of the embedded runtime. Ask the build instead:
 
 ```ruby
-Microsandbox::VERSION          # => "0.17.3"  (the gem's own version)
+Microsandbox::VERSION          # => "0.17.5"  (the gem's own version)
 Microsandbox.runtime_version   # => "v0.6.18" (the embedded upstream runtime tag)
 ```
 
@@ -245,9 +245,11 @@ constants against this gem's. Every release records its runtime in
 | `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:` |
-| `0.17.1` | `v0.6.18` | gem-only security and hardening release: relative host paths pinned at create time (GHSA-mcw9-9rf6-p4rm), `Volume.fs` path validation, `Cargo.lock` advisory updates, argument-guard and cleanup fixes, `SECURITY.md` |
+| `0.17.1` | `v0.6.18` | gem-only security and hardening release: relative host paths pinned at create time (GHSA-mcw9-9rf6-p4rm), `Volume.fs` path validation (mitigates GHSA-rh2c-vm8j-5gg6), `Cargo.lock` advisory updates, argument-guard and cleanup fixes, `SECURITY.md` |
 | `0.17.2` | `v0.6.18` | gem-only fix and release-pipeline hardening release: an interrupted native call no longer loses its result (a sandbox the call owns is stopped on `Timeout`/`Thread#kill`), release preflight, SHA-pinned workflow actions and `cargo deny` advisory checks, RBS and docs contract specs |
 | `0.17.3` | `v0.6.18` | gem-only fix release, fork safety: a forked child (Puma, Resque, Solid Queue) rebuilds its backend and runtime on its first SDK call instead of hanging or crashing, a handle created before the fork raises `ForkedHandleError` in the child, and nothing inherited from the parent is dropped there |
+| `0.17.4` | `v0.6.18` | gem-only fix release: fork safety identifies a process by pid and fork generation (survives pid reuse), `install`/`setup` leave the backend alone in a forked child, a `Sandbox` subclass's `initialize` runs outside the interrupt mask, and the macOS limit that a forked child must not build network clients is documented; rustls 0.23.46 fixes four TLS advisories (RUSTSEC-2026-0346 to -0349) |
+| `0.17.5` | `v0.6.18` | gem-only security release: dependency updates clear RUSTSEC-2026-0381 to -0410, including the zstd used for image-layer decompression (three zstd advisories remain only on an external-kernel path the runtime never takes, see `CHANGELOG.md`); `SECURITY.md` maps more upstream advisories to gem versions |
 
 ## Development
 

data/SECURITY.md

@@ -32,12 +32,20 @@ entry in some of them refers to the upstream project's own Ruby gem, not to
 
 | Advisory | Severity | Affected `microsandbox-rb` | Status |
 |---|---|---|---|
+| [GHSA-rh2c-vm8j-5gg6](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-rh2c-vm8j-5gg6) — `Volume.fs` paths that pass through a missing directory escape the volume root | Critical | `0.7.0`–`0.17.0` | Mitigated in `0.17.1`: every `Volume.fs` / `VolumeInfo#fs` method refuses a path with a `..` segment, in both the Ruby and the native layer, which closes the published bypass (`write`, `mkdir`, `copy` and `rename` through a directory that does not exist). The complete fix is upstream's rewrite of host-side volume access in runtime `v0.7.6`, which also closes the window between checking a path and using it; it arrives with the first gem release on runtime `v0.7.6` or later, and there is none yet. The upstream advisory lists only `microsandbox <= 0.6.16` with no patched version, but the affected resolver is unchanged in every runtime up to `v0.7.5`, so gem `0.17.0` (runtime `v0.6.18`) is affected too. `Volume.fs` first appeared in `0.7.0`. |
 | [GHSA-mcw9-9rf6-p4rm](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-mcw9-9rf6-p4rm) — relative bind-mount paths re-resolved against the working directory on restart | High | `<= 0.17.0` | Fixed in `0.17.1` for sandboxes created through this gem (paths are pinned at create time in the binding). Sandboxes created earlier with a relative path keep it: recreate them. The `msb` CLI this gem installs is still runtime `v0.6.18`, so a sandbox created with `msb` directly is not covered: use absolute paths there. Tracked for this gem as [GHSA-qrhv-m6hf-9cmg](https://github.com/ya-luotao/microsandbox-rb/security/advisories/GHSA-qrhv-m6hf-9cmg). |
 | [GHSA-cg9x-2vfm-3j58](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-cg9x-2vfm-3j58) — NAT64 addresses can bypass destination-group network policy | High | all versions (runtime `< v0.7.5`) | **Not fixed in this gem yet**; needs the runtime fix. Only exploitable where the host network routes a NAT64 prefix. Mitigate by denying the prefix explicitly (see below) or blocking it at the host. |
 | [GHSA-3mpp-52gc-935r](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-3mpp-52gc-935r) — hostname allowlist bypass via mismatched HTTP `Host` / `:authority` | High | `<= 0.16.0` | Runtime fix included from `0.17.0`. If you rely on a hostname allowlist for HTTPS without TLS interception, also pass `strict: true` (off by default in this gem). |
 | [GHSA-gj24-29j2-3x78](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-gj24-29j2-3x78) — egress allowlist bypass on malformed HTTP/1 request lines | Medium | `<= 0.12.0` | Runtime fix included from `0.13.0`. |
 | [GHSA-4vq3-cjpp-v7fg](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-4vq3-cjpp-v7fg) — guest-controlled symlinks in `msb copy` | High | `<= 0.10.0` (the bundled `msb` CLI) | Runtime fix included from `0.11.0`. |
+| [GHSA-v693-3rfr-6q3q](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-v693-3rfr-6q3q) — IPv4-mapped IPv6 addresses bypass DNS rebind protection | Critical | `<= 0.9.1` | Runtime fix included from `0.9.2` (runtime `v0.6.3`). Affects network-enabled sandboxes. |
 | [GHSA-m8f5-rh7h-vgg3](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-m8f5-rh7h-vgg3) — secret values in world-readable process arguments | Medium | `<= 0.7.0` | Runtime fix included from `0.8.0`. |
+| [GHSA-89j4-256r-3pcq](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-89j4-256r-3pcq) — symlink traversal when importing a snapshot archive | High | `0.5.7`–`0.5.9` (`Snapshot.import` and the bundled `msb snapshot import`) | Runtime fix included from `0.5.10` (runtime `v0.5.8`). |
+
+[GHSA-xgg5-hjwq-2gw8](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-xgg5-hjwq-2gw8)
+(domain deny rules bypassed by direct-IP TLS) does not affect any release of
+this gem: it was fixed in runtime `v0.5.0`, and the first release, `0.5.7`,
+embeds runtime `v0.5.7`.
 
 ### Mitigating GHSA-cg9x-2vfm-3j58 before the runtime fix
 

data/docs/filesystem.md

@@ -42,4 +42,5 @@ through `Microsandbox::Volume.fs(name)` / `VolumeInfo#fs` (a `VolumeFs`). See
 
 Paths are relative to the volume root; a leading `/` is the volume root, not the
 host root. A path containing a `..` segment is refused with `FilesystemError` in
-every operation.
+every operation. Versions `0.7.0`–`0.17.0` did not refuse such paths and are
+affected by GHSA-rh2c-vm8j-5gg6; see [SECURITY.md](../SECURITY.md).

data/docs/runtime.md

@@ -114,7 +114,9 @@ backend), chosen the same way as the parent's: an explicit
 `set_default_backend`, an enclosing `with_backend` block, or — when neither
 was used — the environment and config file as the child sees them at that
 call. Everything addressed by name works in the child from then on:
-`Sandbox.create`/`get`/`list`/`start`, `Volume`, `Image`, `Snapshot`.
+`Sandbox.create`/`get`/`list`/`start`, `Volume`, `Image`, `Snapshot` — except
+that on macOS a forked child must not do anything that builds a network
+client (see [macOS](#macos-no-network-clients-in-a-forked-child) below).
 
 If the parent's choice cannot be made again in the child (say the child's
 environment now selects the cloud backend without credentials), SDK calls
@@ -126,6 +128,7 @@ does not depend on the inherited choice and works regardless.
 Microsandbox::Sandbox.list             # the parent has used the SDK
 
 pid = fork do
+  # On macOS "alpine" must already be in the image cache (see below).
   Microsandbox::Sandbox.create("job-#{Process.pid}", image: "alpine") do |sb|
     puts sb.exec("echo", ["hello from the worker"]).stdout
   end
@@ -137,8 +140,8 @@ What does **not** cross a fork is an object created before it. A `Sandbox`,
 `SandboxHandle`, `ExecHandle`, `ExecStdin`, `PullSession`, log/metrics/file
 stream, `SshClient`/`SftpClient`/`SshServer`, `AgentClient` or `VolumeFs`
 belongs to the process that created it. In a forked child, any call that acts
-on one raises `Microsandbox::ForkedHandleError` (the message names both
-pids); the original keeps working in the parent. Reading `name` or `id` — and
+on one raises `Microsandbox::ForkedHandleError` (the message names the
+pids involved); the original keeps working in the parent. Reading `name` or `id` — and
 the snapshot fields of a `SandboxHandle` — still works, so a child can open
 its own handle:
 
@@ -189,6 +192,33 @@ Things to know:
   parent's runtime, backend and whichever inherited handles it collects)
   instead of destroying it — destroying it is what used to crash.
 
+### macOS: no network clients in a forked child
+
+On macOS, a forked child that has not called `exec` dies — `SIGSEGV` or
+`SIGABRT`, not an exception, so it cannot be rescued — as soon as the SDK
+builds a network client or reads registry credentials from the Keychain
+there. macOS's system frameworks do not support being used after `fork`
+without `exec`, and every HTTP client the SDK builds looks up the system proxy
+settings through them. In a forked child on macOS, do not:
+
+- use a cloud backend at all, however it is selected (`set_default_backend`,
+  `with_backend`, `MSB_BACKEND`/`MSB_API_KEY`, a profile);
+- `Sandbox.create` with an image that is not in the image cache yet, or with
+  `pull_policy: :always`;
+- `Image.load`;
+- install the runtime: `Microsandbox.install`, `Microsandbox.setup`, or the
+  first-use install `ensure_runtime!` performs.
+
+It makes no difference whether the parent used the SDK, and
+`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` does not help. Local work is
+unaffected, including `Sandbox.create` with an image that is already cached.
+On Linux the cloud backend works in a forked child.
+
+Do that work in a process that was not forked: in the parent before it forks
+(install the runtime and pull the images the workers will use — creating a
+sandbox from the image pulls it), or in a fresh process started with
+`Process.spawn` (or `fork` followed by `exec`).
+
 ## One runtime line per home
 
 The runtime home (`MSB_HOME`, default `~/.microsandbox`) belongs to one

data/docs/surface.md

@@ -59,7 +59,10 @@ counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
 - **Errors** — the typed hierarchy in [errors.md](errors.md).
 - **Process model** — the SDK may be used before and after `fork`; objects
   created before a fork are refused in the child with `ForkedHandleError`
-  (see [runtime.md](runtime.md#forking-puma-resque-solid-queue)).
+  (see [runtime.md](runtime.md#forking-puma-resque-solid-queue)). On macOS a
+  forked child must not build network clients — cloud backends, image pulls,
+  `Image.load`, runtime install — or it crashes (see
+  [runtime.md](runtime.md#macos-no-network-clients-in-a-forked-child)).
 
 Create options span resources (`cpus`/`memory`/`max_cpus`/`max_memory`),
 `env`/`workdir`/`labels`/`user`/`hostname`/`shell`, named `scripts`, the image

data/ext/microsandbox/Cargo.toml

@@ -8,7 +8,7 @@ description = "Ruby SDK native extension for microsandbox — secure, fast micro
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
 # The core-crate dependencies below stay on their own tag, which is
 # Microsandbox::RUNTIME_VERSION and moves independently of this version.
-version = "0.17.3"
+version = "0.17.5"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -25,12 +25,19 @@ crate-type = ["cdylib"]
 [dependencies]
 # "rb-sys" exposes `magnus::rb_sys::protect` (rb_protect), which the GVL bridge
 # uses to check interrupts without letting Ruby longjmp over Rust frames.
-magnus = { version = "0.8", features = ["rb-sys"] }
+# Default features are off: `old-api` (the free functions that conjure a `Ruby`
+# handle unchecked in release builds) must not creep back, and `io` only gates
+# `magnus::io`, which the extension does not use.
+magnus = { version = "0.9", default-features = false, features = ["rb-sys"] }
 # Low-level Ruby C API — used directly for rb_thread_call_without_gvl2 (GVL
 # release during blocking sandbox calls) and rb_thread_check_ints. Kept in
 # lock-step with magnus's own rb-sys.
 rb-sys = "0.9"
 
+# `pthread_atfork`, for the fork generation (runtime::ProcessIdentity). Already
+# in the dependency graph; listed so the binding can call it directly.
+libc = "0.2"
+
 # The microsandbox core runtime, wrapped via FFI exactly like the official
 # Python (pyo3) and Node (napi) SDKs. Pinned to the matching upstream tag so the
 # gem is self-contained and buildable anywhere (CI, release containers, end-user

data/ext/microsandbox/src/backend.rs

@@ -16,14 +16,14 @@
 //! matching Python and Node.
 
 use std::collections::HashMap;
-use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex, MutexGuard, OnceLock, PoisonError};
 
 use magnus::{function, prelude::*, Error, RModule, Ruby};
 use microsandbox::{Backend, MicrosandboxError, Operation};
 
 use crate::error;
-use crate::runtime::{block_on, current_pid};
+use crate::runtime::{block_on, ProcessIdentity};
 
 /// Resolve the ambient default backend, requiring it to be local.
 ///
@@ -99,7 +99,7 @@ fn build_backend(
 }
 
 //--------------------------------------------------------------------------------------------------
-// Fork safety: the backend generation
+// Fork safety: the backend record
 //--------------------------------------------------------------------------------------------------
 //
 // `fork(2)` copies only the calling thread. A child of a process that used the
@@ -114,7 +114,7 @@ fn build_backend(
 // So the child never touches what it inherited: the first native call after a
 // fork builds a fresh backend the same way the inherited one was chosen and
 // swaps it in, and every inherited `Arc` is `mem::forget`-ed — leaked once per
-// fork generation — instead of dropped.
+// forked process — instead of dropped.
 //
 // Locking. The three mutexes below are only ever taken on a Ruby thread that
 // holds the GVL, and nothing that runs while one is held calls into Ruby or
@@ -158,9 +158,11 @@ impl Selection {
 
 static SELECTION: Mutex<Selection> = Mutex::new(Selection::Ladder);
 
-/// The pid of the process whose default backend the core currently holds.
-/// 0 = no native operation has touched the backend in this process lineage.
-static BACKEND_PID: AtomicU32 = AtomicU32::new(0);
+/// The identity of the process whose default backend the core currently holds
+/// ([`ProcessIdentity::to_bits`]: pid and fork generation in one word, so it
+/// is read and written whole). 0 = no native operation has touched the
+/// backend in this process lineage.
+static BACKEND_OWNER: AtomicU64 = AtomicU64::new(0);
 
 static REBUILD_LOCK: Mutex<()> = Mutex::new(());
 
@@ -183,7 +185,7 @@ fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
 /// above).
 pub fn ensure_this_process_backend() -> Result<(), Error> {
     // The Ruby exception is built here, after the locks are released.
-    adopt_backend(current_pid(), None)
+    adopt_backend(ProcessIdentity::current(), None)
         .map(|_| ())
         .map_err(error::to_ruby)
 }
@@ -204,23 +206,24 @@ pub fn ensure_this_process_backend() -> Result<(), Error> {
 /// Returns `Some(inherited selection)` when `replacement` was installed here
 /// (the caller has nothing left to install), `None` when the caller proceeds
 /// as in any process that already owns its backend. On an error nothing has
-/// changed, `BACKEND_PID` included, so the next call tries again.
+/// changed, `BACKEND_OWNER` included, so the next call tries again.
 fn adopt_backend(
-    cur: u32,
+    cur: ProcessIdentity,
     replacement: Option<&Selection>,
 ) -> Result<Option<Selection>, MicrosandboxError> {
-    if BACKEND_PID.load(Ordering::Acquire) == cur {
+    let cur_bits = cur.to_bits();
+    if BACKEND_OWNER.load(Ordering::Acquire) == cur_bits {
         return Ok(None);
     }
     let _rebuild = lock(&REBUILD_LOCK);
-    let seen = BACKEND_PID.load(Ordering::Acquire);
-    if seen == cur {
+    let seen = BACKEND_OWNER.load(Ordering::Acquire);
+    if seen == cur_bits {
         return Ok(None);
     }
     if seen == 0 {
         // Nothing was inherited; the core resolves its default lazily, in this
         // process, on first use.
-        BACKEND_PID.store(cur, Ordering::Release);
+        BACKEND_OWNER.store(cur_bits, Ordering::Release);
         return Ok(None);
     }
 
@@ -233,14 +236,14 @@ fn adopt_backend(
     // The inherited default must never be dropped (see above).
     std::mem::forget(microsandbox::swap_default_backend(fresh));
     // Neither may the backends that open `with_backend` scopes saved for their
-    // restore. The entries themselves stay — pid and selection — so a scope
+    // restore. The entries themselves stay — owner and selection — so a scope
     // the parent opened can still be closed here (see `pop_default_backend`).
     for scope in lock(backend_scopes()).values_mut() {
         std::mem::forget(scope.previous.take());
     }
     let inherited =
         replacement.map(|selection| std::mem::replace(&mut *lock(&SELECTION), selection.clone()));
-    BACKEND_PID.store(cur, Ordering::Release);
+    BACKEND_OWNER.store(cur_bits, Ordering::Release);
     Ok(inherited)
 }
 
@@ -261,7 +264,7 @@ fn set_default_backend(
     // A forked child that starts by selecting a backend: the inherited default
     // is forgotten and this selection installed in its place, without ever
     // rebuilding the inherited one.
-    if adopt_backend(current_pid(), Some(&selection))
+    if adopt_backend(ProcessIdentity::current(), Some(&selection))
         .map_err(error::to_ruby)?
         .is_some()
     {
@@ -283,7 +286,7 @@ static BACKEND_SCOPES: OnceLock<Mutex<HashMap<u32, Scope>>> = OnceLock::new();
 /// What an open `with_backend` scope restores when it closes.
 struct Scope {
     /// The process that opened the scope.
-    pid: u32,
+    owner: ProcessIdentity,
     /// The backend that was the default before the push, kept to be put back
     /// by a pop in the same process. `None` when there is no such backend of
     /// this process's own: a forked child took it out to leak it, or the push
@@ -308,7 +311,7 @@ fn push_default_backend(
     api_key: Option<String>,
     profile: Option<String>,
 ) -> Result<u32, Error> {
-    let cur = current_pid();
+    let cur = ProcessIdentity::current();
     let selection = Selection::Explicit {
         kind,
         url,
@@ -332,7 +335,7 @@ fn push_default_backend(
     lock(backend_scopes()).insert(
         token,
         Scope {
-            pid: cur,
+            owner: cur,
             previous,
             selection: before,
         },
@@ -352,7 +355,7 @@ fn push_default_backend(
 /// is a state the caller can describe and leave with `set_default_backend`;
 /// a token nobody can retry (`with_backend` never hands it out) would not be.
 fn pop_default_backend(token: u32) -> Result<(), Error> {
-    let cur = current_pid();
+    let cur = ProcessIdentity::current();
     // (The registry lock is not held while an exception is built.)
     let Some(scope) = lock(backend_scopes()).remove(&token) else {
         return Err(error::base_error("unknown backend scope token"));
@@ -384,7 +387,7 @@ fn pop_default_backend(token: u32) -> Result<(), Error> {
 
     match scope.previous {
         // Opened and closed in the same process: put the saved backend back.
-        Some(previous) if scope.pid == cur => microsandbox::set_default_backend(previous),
+        Some(previous) if scope.owner == cur => microsandbox::set_default_backend(previous),
         // No backend of this process's own was saved (see `Scope::previous`):
         // restore one built here from how the saved one had been chosen. On
         // failure the temporary backend stays installed (see above). The
@@ -393,8 +396,9 @@ fn pop_default_backend(token: u32) -> Result<(), Error> {
         // forked child ever drops a backend it might have inherited. That
         // leaks at most one backend per scope closed this way.
         previous => {
-            // `None` unless the pid of the process that opened the scope was
-            // reused; an inherited `Arc` is leaked either way.
+            // Always `None` here: a process that is not the scope's opener
+            // took the saved backend out when it adopted (`adopt_backend`).
+            // An inherited `Arc` would be leaked either way.
             std::mem::forget(previous);
             let fresh = scope.selection.build().map_err(error::to_ruby)?;
             std::mem::forget(microsandbox::swap_default_backend(fresh));