microsandbox-rb 0.17.3 → 0.17.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d3b616f0ff13a9961eab2e0cdd3812f859754efd7489d5857db0e49588f2b73
-  data.tar.gz: a172d9b8b62bb19f8b4cc2accfadec90f56b83b0e99112109a42032b7ca9a6f4
+  metadata.gz: 7d72d5c6e7a8d135e93d02d64c8966cf6cd4b7dcbf17d02bb65d074a963a977c
+  data.tar.gz: cde0f1e7c9d8b8270a98dd333e7e49709d24bd237ee2c7a6c671b8913f1b3393
 SHA512:
-  metadata.gz: 9357333f88d8061e822da080bdc014438b7ca8bda1b94584a01e89fa1278c9d661b5a5eb2a7e5e36e5879076c2e9f6e82cb067dd6a4aa86023f16360953369ed
-  data.tar.gz: e7b24e0067df67c76a57f5b204f743d9420c4cd9d43f717bd3576e0324023493b68821d65e1c910168ad87a3e76261dcbb825b1476184b6c9318891cb4a99c1a
+  metadata.gz: 5c1ceaecff30c64f9fd7f138c75acf080202468f56859b613a52d7ef482f8da32b82c4bf0f4191a50e0804e0938fa62c4ceff1b771b8df4cd0d1e10b06a19c81
+  data.tar.gz: 4a817a61508dd57b041c56b351be03d6dfc317d1a84079c9e0049e9dde374583252afe91522fdb7c61fbce547d87dc326d4c3bb2aaa77fb27b69e68669907b69

data/CHANGELOG.md

@@ -8,6 +8,72 @@ wraps, and the README's Versioning section keeps the full gem→runtime map.
 
 ## [Unreleased]
 
+## [0.17.4] - 2026-10-14
+
+Gem-only fix release; the embedded runtime stays at **`v0.6.18`**. Fork safety
+now also survives pid reuse (a process is identified by its pid and fork
+generation together), `install`/`setup` in a forked child no longer touch the
+backend, a `Sandbox` subclass's `initialize` no longer runs with interrupts
+masked, and the macOS limit that a forked child must not build network clients
+is documented. It also picks up dependency updates: magnus 0.9, tokio 1.53,
+rb-sys 0.9.130, and rustls 0.23.46 for four TLS advisories (see Security).
+
+### Fixed
+
+- **A `Sandbox` subclass's `initialize` no longer runs with interrupts
+  masked.** `Sandbox.create`, `.connect_or_create` and `.start` (and
+  `PullSession#sandbox`) hold a queued `Thread#raise`/`Timeout`/`Thread#kill`
+  back only while the native call runs; the wrapper is now built after that,
+  so a subclass whose constructor blocks or runs long no longer delays a
+  `Timeout.timeout` or `Thread#kill` until the constructor returns. The
+  best-effort interrupt cleanup moved to the native handle with it: an
+  interrupt that lands before or during `initialize`, or an exception
+  `initialize` raises, still stops the sandbox when the call owns it and
+  leaves one it merely connected to running.
+  Behaviour of `Sandbox` itself is unchanged.
+
+- **`Microsandbox.install` and `Microsandbox.setup` no longer take over the
+  backend in a forked child.** They went through the same entry as every
+  other native call, so in a child they first rebuilt the backend inherited
+  from the parent — which they never use — and failed with the configuration
+  error when the parent's selection no longer resolved in the child (say its
+  environment selected the cloud backend without an API key). They now leave
+  the backend alone; the child's first call that uses it takes it over, as
+  before.
+
+- **Fork safety no longer identifies a process by its pid alone.** A forked
+  process that the kernel had given the pid of an ancestor whose SDK state it
+  inherited (the pid counter wrapped onto exactly that value, with no SDK call
+  in between) was taken for that ancestor: it would have used the inherited
+  runtime, backend and handles instead of rebuilding them or raising
+  `ForkedHandleError`. The extension now counts forks with a `pthread_atfork`
+  child handler and identifies a process by its pid and that count together.
+  `ForkedHandleError`'s message no longer names one pid as two processes when
+  the pids are equal.
+
+### Security
+
+- **rustls 0.23.45 → 0.23.46** (a transitive dependency, through the network
+  stack's DNS client and the HTTP client). Fixes RUSTSEC-2026-0346 (`Debug`
+  output of client session values exposed TLS secrets), RUSTSEC-2026-0347
+  (buffered application data sent to the outer server after ECH rejection),
+  RUSTSEC-2026-0348 (Brotli certificate decompression could allocate up to
+  1 GiB before authentication) and RUSTSEC-2026-0349 (an unauthenticated
+  ServerHello could downgrade later connections to classical key exchange).
+
+### Docs
+
+- **Known limitation: on macOS a forked child must not build network
+  clients.** A child forked (without `exec`) from a Ruby process on macOS
+  crashes — `SIGSEGV` or `SIGABRT`, which cannot be rescued — when the SDK
+  builds an HTTP client or reads the Keychain there: any cloud backend use,
+  `Sandbox.create` with an image not yet cached (or `pull_policy: :always`),
+  `Image.load`, and runtime install/setup. The macOS system frameworks behind
+  the proxy lookup and the Keychain are not usable after `fork`. Do that work
+  in the parent before forking, or in a process started with `Process.spawn`.
+  On Linux the cloud backend works in a forked child; new fork specs cover it
+  there (they are skipped on macOS). See [runtime.md](docs/runtime.md#macos-no-network-clients-in-a-forked-child).
+
 ## [0.17.3] - 2026-10-13
 
 Gem-only fix release; the embedded runtime stays at **`v0.6.18`**. A process
@@ -1513,7 +1579,8 @@ microsandbox runtime, aligned with the official Python/Node/Go SDKs.
   core crate has Apple-native deps). Until precompiled gems are published,
   installing from source requires a Rust toolchain (stable >= 1.91).
 
-[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.3...HEAD
+[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.4...HEAD
+[0.17.4]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.3...v0.17.4
 [0.17.3]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.2...v0.17.3
 [0.17.2]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.1...v0.17.2
 [0.17.1]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.17.0...v0.17.1

data/Cargo.lock

@@ -971,9 +971,9 @@ checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 
 [[package]]
 name = "chacha20"
-version = "0.10.0"
+version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
+checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
 dependencies = [
  "cfg-if",
  "cipher 0.5.2",
@@ -1597,9 +1597,9 @@ dependencies = [
 
 [[package]]
 name = "der"
-version = "0.8.0"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "71fd89660b2dc699704064e59e9dba0147b903e85319429e131620d022be411b"
+checksum = "a878c850e9e421b20262e9b41f9c860e4785fa07541c266b62ff9d1ef998a80a"
 dependencies = [
  "const-oid",
  "pem-rfc7468",
@@ -1923,7 +1923,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -2051,7 +2051,7 @@ checksum = "94e7099f6313ecacbe1256e8ff9d617b75d1bcb16a6fddef94866d225a01a14a"
 dependencies = [
  "io-lifetimes 2.0.4",
  "rustix",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -2858,7 +2858,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "20fd6de4ccfcc187e38bc21cfa543cb5a302cb86a8b114eb7f0bf0dc9f8ac00f"
 dependencies = [
  "io-lifetimes 3.0.1",
- "windows-sys 0.52.0",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -3289,9 +3289,9 @@ dependencies = [
 
 [[package]]
 name = "magnus"
-version = "0.8.2"
+version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
+checksum = "b9068710e00d21be762edca59b9c4c8946dbdb29820d4f76ad559afea07982c9"
 dependencies = [
  "magnus-macros",
  "rb-sys",
@@ -3301,9 +3301,9 @@ dependencies = [
 
 [[package]]
 name = "magnus-macros"
-version = "0.8.0"
+version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
+checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3660,11 +3660,12 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.17.3"
+version = "0.17.4"
 dependencies = [
  "chrono",
  "futures",
  "ipnetwork",
+ "libc",
  "magnus",
  "microsandbox",
  "microsandbox-network",
@@ -4312,9 +4313,9 @@ dependencies = [
 
 [[package]]
 name = "pageant"
-version = "0.2.1"
+version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f3a5ae18f65a85c67a77d18d42d3606c07948e3c17c1e5f74852b26589e88a5"
+checksum = "f0786409b5aaa884655c9b4065681db0835db0cc185a6fb19fb17a5d38656866"
 dependencies = [
  "base16ct",
  "byteorder",
@@ -4733,7 +4734,7 @@ dependencies = [
  "once_cell",
  "socket2",
  "tracing",
- "windows-sys 0.52.0",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -4870,18 +4871,18 @@ dependencies = [
 
 [[package]]
 name = "rb-sys"
-version = "0.9.128"
+version = "0.9.130"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "45ca28513560e56cfb79a62b1fce363c73af170a182024ce880c77ee9429920a"
+checksum = "02faf625bb10ba893e3ae620f19c9fb1b5f8fcae0fe4eb86bb3f2230fad75edb"
 dependencies = [
  "rb-sys-build",
 ]
 
 [[package]]
 name = "rb-sys-build"
-version = "0.9.128"
+version = "0.9.130"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce04b2c55eff3a21aaa623fcc655d94373238e72cac6b3e1a3641ff31649f99a"
+checksum = "05be6f9c86fe5482808162826f6c047d093b3670582296c770de1d94f8066694"
 dependencies = [
  "bindgen",
  "lazy_static",
@@ -5270,7 +5271,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -5285,9 +5286,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.45"
+version = "0.23.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
+checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf"
 dependencies = [
  "aws-lc-rs",
  "log",
@@ -5339,7 +5340,7 @@ dependencies = [
  "security-framework 3.7.0",
  "security-framework-sys",
  "webpki-root-certs",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -5969,9 +5970,9 @@ dependencies = [
 
 [[package]]
 name = "spin"
-version = "0.9.8"
+version = "0.9.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6980e8d7511241f8acf4aebddbb1ff938df5eebe98691418c4468d0b72a96a67"
+checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"
 dependencies = [
  "lock_api",
 ]
@@ -6413,7 +6414,7 @@ dependencies = [
  "getrandom 0.4.2",
  "once_cell",
  "rustix",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -6531,9 +6532,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.52.3"
+version = "1.53.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+checksum = "e95f91fcc7a621e8b030f6aa23c71fe9838ae2fb4d8118b75602a328f5144044"
 dependencies = [
  "bytes",
  "libc",
@@ -7210,7 +7211,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -7521,7 +7522,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3f3fd376f71958b862e7afb20cfe5a22830e1963462f3a17f49d82a6c1d1f42d"
 dependencies = [
  "bitflags 2.13.0",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -7620,13 +7621,14 @@ dependencies = [
 
 [[package]]
 name = "wnaf"
-version = "0.14.0"
+version = "0.14.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ab12e7090f27e2ffd9322651492942d50c2926094af30601e1964337db39daf1"
+checksum = "795ca18b3fdb5e62bf982199278341ddcf7ebf7d32e25e212ad05d496e95f6fa"
 dependencies = [
  "ff",
  "group",
  "hybrid-array",
+ "primefield",
 ]
 
 [[package]]

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.4"  (the gem's own version)
 Microsandbox.runtime_version   # => "v0.6.18" (the embedded upstream runtime tag)
 ```
 
@@ -248,6 +248,7 @@ constants against this gem's. Every release records its runtime in
 | `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.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) |
 
 ## Development
 

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