saboteur 0.8.1 → 0.9.0

data/lib/saboteur/execution/bundle_gemfile_pin.rb

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "shellwords"
+
+require_relative "test_command_shape"
+
+module Saboteur
+  module Execution
+    # The test command's pinned BUNDLE_GEMFILE, or nil when it does not
+    # set one. Every wrapper unwrap strips (VAR= words, env and its
+    # flags, timeout, nice, time, bundle exec) keeps assignments in the
+    # command's environment, so the prefix it removes is exactly the
+    # assignment scope; the LAST BUNDLE_GEMFILE wins like the shell,
+    # and an empty last value unsets (#722). A token like
+    # A="x"BUNDLE_GEMFILE=g is one assignment to A and sets nothing.
+    # Anything BUNDLE_GEMFILE-shaped the scan cannot prove refuses
+    # rather than guessing the wrong Gemfile.
+    module BundleGemfilePin
+      # Raised when BUNDLE_GEMFILE shows up where the scan cannot prove it (#722).
+      PIN_UNVERIFIABLE = "the test command sets BUNDLE_GEMFILE where its value cannot be verified; " \
+                         "pin BUNDLE_GEMFILE as a leading assignment"
+
+      # A pin value must be a literal: a substitution, tilde, glob, or
+      # shell metacharacter makes it unknowable without running the shell (#722).
+      PIN_UNVERIFIABLE_VALUE = /[$`\\~;&|<>()*?{}]/
+
+      module_function
+
+      def pinned_in(command)
+        tokens = Shellwords.split(command)
+      rescue ArgumentError
+        raise ConfigError, PIN_UNVERIFIABLE if command.include?("BUNDLE_GEMFILE")
+      else
+        pin = pin_value(tokens)
+        raise ConfigError, PIN_UNVERIFIABLE if pin == :unverifiable
+
+        pin
+      end
+
+      # nil for no pin, :unverifiable for a BUNDLE_GEMFILE the scan
+      # cannot prove, the literal value otherwise.
+      def pin_value(tokens)
+        prefix = tokens.first(tokens.size - TestCommandShape.unwrap(tokens).size)
+        value = prefix.reverse.find { |word| word.match?(/\ABUNDLE_GEMFILE=/) }&.split("=", 2)&.last
+        return :unverifiable if unverifiable_shape?(tokens, value)
+        return nil if value.nil? || value.empty?
+        return :unverifiable if value.match?(PIN_UNVERIFIABLE_VALUE)
+
+        value
+      end
+
+      # BUNDLE_GEMFILE in a shape the scan cannot prove: env rewriting the
+      # run's cwd or variables, or the pin outside the leading assignments.
+      def unverifiable_shape?(tokens, value)
+        mentioned = tokens.any? { |word| word.include?("BUNDLE_GEMFILE") }
+        (mentioned && env_unverifiable?(tokens)) ||
+          (value.nil? && tokens.any? { |word| word.match?(/(?:\A|[^A-Za-z0-9_])BUNDLE_GEMFILE=/) })
+      end
+
+      # env(1) carrying a cwd-repointing (-C/--chdir), word-reparsing
+      # (-S/--split-string), or variable-unsetting (-u/--unset) flag: the
+      # pin scan cannot prove the environment the command runs in (#722).
+      def env_unverifiable?(tokens)
+        tokens.each_index.select { |i| %w[env /usr/bin/env].include?(tokens[i]) }.any? do |i|
+          tokens[(i + 1)..].take_while { |word| word.start_with?("-") }
+                           .any? { |flag| flag.match?(/\A(?:-C|-S|-u|--chdir|--split-string|--unset)/) }
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/execution/external_runner.rb

@@ -74,12 +74,19 @@ module Saboteur
       # holding the pipe past this no longer blocks the run.
       DRAIN_GRACE = 0.5
 
-      def initialize(command:, root:)
+      def initialize(command:, root:, path_sources: nil)
         @command = command
         # realpath, not expand_path: the tree must be judged by where it
         # really is, so a subject path can be checked against the same
         # canonical root without a symlink making it look outside (#305 QA).
         @root = File.realpath(root)
+        # The Gemfile the command actually loads, root-relative: its own
+        # pinned BUNDLE_GEMFILE when it sets one (Appraisal style), else
+        # the root Gemfile (#644).
+        pinned = pinned_gemfile
+        @gemfile_name = pinned || "Gemfile"
+        sources = path_sources || GemfilePathSources.resolve(@root, gemfile: pinned)
+        @path_sources = classify_path_sources(sources)
         @copy_root = nil
         at_exit { close }
       rescue SystemCallError
@@ -211,9 +218,106 @@ module Saboteur
         @copy_root = File.realpath(Dir.mktmpdir("saboteur-external-"))
         FileUtils.cp_r(File.join(@root, "."), @copy_root, preserve: true)
         rebuild_symlinks
+        rebase_path_sources
         yield
       end
 
+      # path: sources are judged against the canonical root (#644): a
+      # RELATIVE source resolving outside the tree would escape the
+      # disposable copy, so it refuses the run at startup naming the
+      # source; an ABSOLUTE source pointing into the original tree is
+      # rebased into the copy below so bundler loads the copy's (possibly
+      # mutated) code, never the original's. Anything unresolved or
+      # ambiguous refuses - never a guess that could load unmutated code.
+      def classify_path_sources(sources)
+        sources.each_with_object(rebase: []) do |src, groups|
+          expanded = GemfilePathSources.canonical_path(src.expanded)
+          # The root itself counts as inside: a `gemspec` line makes
+          # Bundler report the gem's own path source ".", expanded to the
+          # project root - refusing it would refuse every gem-style
+          # project (#644 security).
+          inside = expanded == @root || expanded.start_with?("#{@root}/")
+          next if inside && !Pathname.new(src.original).absolute?
+          next if !inside && Pathname.new(src.original).absolute?
+
+          unless inside
+            raise ConfigError, "the Gemfile's path: source \"#{src.name}\" (#{src.original}) resolves outside the " \
+                               "project root (#{expanded}); external test commands need a self-contained tree"
+          end
+
+          groups[:rebase] << [src, expanded]
+        end
+      end
+
+      # Rewrites each rebased source in the COPY's Gemfile (quoted option)
+      # and Gemfile.lock (PATH remote line). Zero or several matches mean
+      # the file computes the path or disagrees with Bundler's resolution -
+      # refuse rather than risk loading the original tree (#644).
+      def rebase_path_sources
+        @path_sources[:rebase].each do |src, expanded|
+          copy_path = expanded == @root ? @copy_root : File.join(@copy_root, expanded.delete_prefix("#{@root}/"))
+          rewrite_gemfile_source(src, copy_path)
+          rewrite_lockfile_source(src, expanded, copy_path)
+        end
+      end
+
+      def rewrite_gemfile_source(src, copy_path)
+        path = File.join(@copy_root, @gemfile_name)
+        text = File.read(path)
+        pattern = /(path:\s*["'])#{Regexp.escape(src.original)}(["'])/
+        raise ConfigError, ambiguous_source_message(src) unless text.scan(pattern).size == 1
+
+        File.write(path, text.sub(pattern) { "#{Regexp.last_match(1)}#{copy_path}#{Regexp.last_match(2)}" })
+      end
+
+      def rewrite_lockfile_source(src, expanded, copy_path)
+        # Bundler names the lockfile after the Gemfile: <gemfile>.lock.
+        path = File.join(@copy_root, "#{@gemfile_name}.lock")
+        return unless File.file?(path)
+
+        text = File.read(path)
+        # Bundler spells an in-project absolute path: as the root-relative
+        # remote ("vend/g" for /root/vend/g, "." for the root), and that
+        # spelling already resolves inside the copy (#722): accept it as
+        # is. Only the absolute spelling needs the rewrite, and only a
+        # duplicate or a total miss refuses - the lockfile then disagrees
+        # with Bundler's own resolution. The relative spelling must come
+        # from the CANONICAL expanded: src.expanded is Bundler's textual
+        # expand_path, which never matches the realpath'd root behind a
+        # symlinked one (macOS /var -> /private/var, #732).
+        spellings = ([src.original, expanded == @root ? "." : expanded.delete_prefix("#{@root}/")] - [""]).uniq
+        unless text.scan(/^(\s*remote: )(?:#{spellings.map { |s| Regexp.escape(s) }.join('|')})$/).size == 1
+          raise ConfigError, "could not rebase the lockfile's PATH remote for path: source \"#{src.name}\" " \
+                             "(#{src.original}); the lockfile must record it exactly once - run bundle install"
+        end
+        absolute = /^(\s*remote: )#{Regexp.escape(src.original)}$/
+        # Write back only when the absolute spelling matched: a no-match sub
+        # would write identical bytes, which still fails on a read-only
+        # lockfile carried into the copy (#729 security).
+        File.write(path, text.sub(absolute) { "#{Regexp.last_match(1)}#{copy_path}" }) if text.match?(absolute)
+      end
+
+      def ambiguous_source_message(src)
+        "could not rebase the Gemfile's path: source \"#{src.name}\" (#{src.original}) into the disposable copy; " \
+          "external test commands need a literal path: option they can rewrite"
+      end
+
+      # A command-pinned Gemfile must live inside the tree, or the copy
+      # would read a Gemfile - and its path: sources - from outside (#644).
+      # Returns its root-relative path, or nil for the root Gemfile.
+      def pinned_gemfile
+        pinned = BundleGemfilePin.pinned_in(@command)
+        return nil unless pinned
+
+        expanded = GemfilePathSources.canonical_path(File.expand_path(pinned, @root))
+        unless expanded == @root || expanded.start_with?("#{@root}/")
+          raise ConfigError, "the test command pins BUNDLE_GEMFILE (#{pinned}) outside the project root " \
+                             "(#{expanded}); external test commands need the Gemfile inside the tree"
+        end
+
+        expanded.delete_prefix("#{@root}/")
+      end
+
       # cp_r keeps symlinks, and a write through a link that escapes the
       # copy would land in the real tree. Links resolving inside the tree
       # are REBUILT as relative links inside the copy: alias identity is

data/lib/saboteur/execution/gemfile_path_sources.rb

@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Saboteur
+  module Execution
+    # Resolves a Gemfile's path: sources with Bundler's OWN parser in a
+    # short-lived child process (#644). Never a line scan: a wrong guess
+    # about a path: source silently loads unmutated code in the disposable
+    # copy. Fail closed - a Gemfile that cannot be parsed, a resolver that
+    # times out, or a path: source outside the project root refuses the
+    # run with exit 2 (ConfigError) naming the source.
+    # Resolving EVALUATES the project's Gemfile in that child at
+    # ExternalRunner.new - arbitrary Ruby with the caller's permissions,
+    # the same trust level as the bundle exec in the test command itself.
+    module GemfilePathSources
+      Source = Data.define(:name, :original, :expanded)
+
+      RESOLVE_TIMEOUT = 15
+
+      # Bundler::Dsl, not Bundler::Definition: the Gemfile must be PARSED by
+      # Bundler itself (it is arbitrary Ruby; a line scan can silently miss
+      # or invent a path: source and load unmutated code), but resolving the
+      # whole bundle is not needed and fails on half-installed projects.
+      RESOLVER = <<~RUBY
+        dsl = Bundler::Dsl.new
+        dsl.eval_gemfile(ENV["BUNDLE_GEMFILE"] || "Gemfile")
+        out = dsl.dependencies.filter_map do |dep|
+          src = dep.source
+          next unless src.is_a?(Bundler::Source::Path)
+
+          { "name" => dep.name, "original" => src.path.to_s, "expanded" => src.expanded_original_path.to_s }
+        end
+        puts JSON.generate(out)
+      RUBY
+
+      module_function
+
+      # Every path: source in the project's Gemfile, resolved by Bundler
+      # itself. Raises ConfigError on any failure to parse or resolve.
+      # gemfile pins the command's own BUNDLE_GEMFILE (Appraisal style):
+      # that file's path: sources are the ones the run loads, so it is
+      # the one parsed (#644).
+      def resolve(root, env: ENV, timeout: RESOLVE_TIMEOUT, gemfile: nil)
+        path = gemfile ? File.expand_path(gemfile, root) : File.join(root, "Gemfile")
+        if gemfile && !File.file?(path)
+          raise ConfigError, "the test command pins BUNDLE_GEMFILE (#{gemfile}) but #{path} does not exist"
+        end
+
+        return [] unless File.file?(path)
+
+        stdout, stderr, status = run_resolver(root, env, timeout, gemfile: path)
+        unless status.success?
+          detail = stderr.to_s.lines.first(3).join.strip
+          detail = "resolver exited #{status.exitstatus}" if detail.empty?
+          raise ConfigError, "could not parse the Gemfile's path: sources (#{detail}); " \
+                             "external test commands need the Gemfile to resolve"
+        end
+
+        JSON.parse(stdout).map do |row|
+          Source.new(name: row["name"], original: row["original"], expanded: row["expanded"])
+        end
+      rescue JSON::ParserError
+        raise ConfigError, "could not parse the Gemfile's path: sources (resolver returned unreadable output); " \
+                           "external test commands need the Gemfile to resolve"
+      end
+
+      # realpath, canonicalizing the deepest EXISTING ancestor when the
+      # path itself does not exist yet: behind a symlinked root (macOS
+      # /var -> /private/var) a textual expand_path can never match the
+      # realpath'd root, so an absolute path: source into the tree read
+      # as outside and silently skipped the rebase (#644, #721 macOS).
+      def canonical_path(path)
+        missing = []
+        current = path
+        until File.exist?(current)
+          missing.unshift(File.basename(current))
+          parent = File.dirname(current)
+          break if parent == current
+
+          current = parent
+        end
+        base = File.exist?(current) ? File.realpath(current) : File.expand_path(current)
+        File.join(base, *missing)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      def run_resolver(root, env, timeout, gemfile: nil)
+        # Spawn env semantics: a key ABSENT from the hash is inherited, so
+        # the bundler anchors must be explicitly unset with nil, or the
+        # child resolves saboteur's own Gemfile instead of the project's.
+        # Both prefixes: rubygems itself requires ENV["BUNDLER_SETUP"] in
+        # gem_prelude, which would resolve the whole bundle at child boot.
+        child_env = env.each_key.with_object({}) do |key, memo|
+          memo[key] = nil if key.start_with?("BUNDLE_", "BUNDLER_") || key == "RUBYOPT"
+        end
+        # The Gemfile to parse, re-pinned after the anchor wipe: the
+        # command's own BUNDLE_GEMFILE when it sets one (Appraisal style),
+        # else the root Gemfile (#644).
+        child_env["BUNDLE_GEMFILE"] = gemfile || File.join(root, "Gemfile")
+        # Plain ruby, NOT bundle exec: bundle exec resolves the whole bundle
+        # before running, which refuses half-installed projects we are only
+        # trying to parse (#644). The child leads its own process group so a
+        # timeout can KILL the whole group, not only the ruby pid (#644).
+        cmd = ["ruby", "-rbundler", "-rjson", "-e", RESOLVER]
+        stdin, stdout, stderr, wait = Open3.popen3(child_env, *cmd, chdir: root, pgroup: true)
+        stdin.close
+        await_resolver(stdout, stderr, wait, timeout)
+      ensure
+        [stdin, stdout, stderr].each { |io| io&.close unless io&.closed? }
+      end
+
+      # Drains both pipes while waiting: a child that fills a pipe buffer
+      # (~64 KB) blocks on write and never exits, which would read as a
+      # fake timeout (#644). The readers accumulate partial chunks, so a
+      # still-open pipe (a spawned grandchild that left the process group
+      # holds the write end) can be abandoned after a short grace instead
+      # of blocking on EOF - on the timeout path the captured output is
+      # discarded, and on a clean exit incomplete output cannot be
+      # trusted, so the run refuses either way (#722).
+      def await_resolver(stdout, stderr, wait, timeout)
+        out_buffer = +""
+        err_buffer = +""
+        readers = [pipe_reader(stdout, out_buffer), pipe_reader(stderr, err_buffer)]
+        timed_out = resolver_timed_out?(wait, timeout)
+        readers_done = readers.all? { |reader| reader.join(2) }
+        readers.each { |reader| reader.kill if reader.alive? }
+        if timed_out
+          raise ConfigError, "could not parse the Gemfile's path: sources (resolver timed out after #{timeout} s); " \
+                             "external test commands need the Gemfile to resolve"
+        end
+        unless readers_done
+          raise ConfigError, "could not parse the Gemfile's path: sources (a resolver-spawned process still holds " \
+                             "its pipes open); external test commands need the Gemfile to resolve"
+        end
+
+        [out_buffer, err_buffer, wait.value]
+      end
+
+      # true when the resolver missed its deadline and its whole process
+      # group was KILLed.
+      def resolver_timed_out?(wait, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        until wait.join(0.05)
+          next unless Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          Process.kill("KILL", -wait.pid)
+          wait.join
+          return true
+        end
+        false
+      end
+
+      def pipe_reader(io, buffer)
+        Thread.new do
+          loop { buffer << io.readpartial(65_536) }
+        rescue IOError # EOFError < IOError
+          buffer
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/execution/sandbox.rb

@@ -62,17 +62,18 @@ module Saboteur
         @abi_version = probed_abi_version
       end
 
+      # Fiddle holds the GVL for the call (need_gvl: true) and saves errno in
+      # Fiddle.last_error in the same C function, right after ffi_call, so no
+      # Ruby code or GVL hand-off runs between the failed syscall and its
+      # errno. Without need_gvl, Fiddle releases the GVL for the call and reads
+      # errno only after reacquiring it, and the old second Fiddle call to
+      # __errno_location came later still: a stale errno could replace the
+      # real answer, first 0 (#350), then EINVAL, which the kernel never
+      # returns for a valid version probe (it answers EINVAL only for a
+      # non-NULL attr or a non-zero size).
       def probed_abi_version
-        # Build the errno reader BEFORE the probe: its lazy dlopen/dlsym run
-        # libc calls that can set errno, so building it between the probe and
-        # the read can replace the real answer with a stale 0.
-        LibC.errno_location_fn
-        version, errno = probe_once
-        # A failed syscall always sets errno, so (failure, errno 0) is never
-        # the kernel's real answer - the read was clobbered between the call
-        # and here. Probe once more, now with every Fiddle function warm.
-        version, errno = probe_once if !version.positive? && errno.zero?
-        probe_abi(version, errno)
+        version = LibC.probe_fn.call(SYS_CREATE_RULESET, 0, 0, CREATE_RULESET_VERSION, 0)
+        probe_abi(version, Fiddle.last_error)
       rescue Fiddle::DLError
         # No usable libc (an unusual musl/ldso layout): the sandbox cannot
         # be built here, so degrade to the unsandboxed note, not a crash.
@@ -83,17 +84,19 @@ module Saboteur
       # no Landlock to give: run unsandboxed, noted once. Anything else
       # (EPERM under a seccomp policy, ...) means the kernel is there but
       # refused - fail closed rather than run without the promised sandbox.
-      # One create-ruleset version probe with its errno read paired to it.
-      def probe_once
-        version = LibC.syscall_fn.call(SYS_CREATE_RULESET, 0, 0, CREATE_RULESET_VERSION, 0)
-        [version, last_errno]
-      end
-
+      # The message names the kernel so a run on an unexpected runner says
+      # what it ran on.
       def probe_abi(version, errno)
         return version if version.positive?
         return 0 if UNSUPPORTED_ERRNOS.include?(errno)
 
-        raise SystemCallError.new("landlock_create_ruleset probe", errno)
+        raise SystemCallError.new("landlock_create_ruleset probe (kernel #{kernel_release})", errno)
+      end
+
+      def kernel_release
+        File.read("/proc/sys/kernel/osrelease").strip
+      rescue SystemCallError
+        "unknown"
       end
 
       def available?
@@ -255,6 +258,16 @@ module Saboteur
           nil
         end
 
+        # The same syscall, built to run with the GVL held: see probed_abi_version.
+        def probe_fn
+          @probe_fn ||= Fiddle::Function.new(
+            handle["syscall"],
+            [Fiddle::TYPE_LONG, Fiddle::TYPE_LONG, Fiddle::TYPE_LONG, Fiddle::TYPE_LONG, Fiddle::TYPE_LONG],
+            Fiddle::TYPE_LONG,
+            need_gvl: true
+          )
+        end
+
         def syscall_fn
           @syscall_fn ||= Fiddle::Function.new(
             handle["syscall"],

data/lib/saboteur/execution/supervisor.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require_relative "process_tree"
 require_relative "protocol"
 require_relative "fiddle_loader"
+require_relative "supervisor_batch"
 
 module Saboteur
   module Execution
@@ -30,6 +31,8 @@ module Saboteur
     #      intermediate parent between polls (#365), so kill_all also sweeps
     #      the process table for the marker, which survives both escapes.
     class Supervisor
+      include SupervisorBatch
+
       # Set in every child to its nesting depth (1 for a child of a top-level
       # run). Engine refuses to start when it is set; the supervisor itself
       # refuses to fork past MAX_DEPTH, so even a run with that guard removed
@@ -132,7 +135,20 @@ module Saboteur
       # on_tick is called from the parent's wait loop after the fork, about
       # every poll, so callers can report progress without a thread alive
       # at fork time.
-      def run(timeout:, cpu_seconds: nil, on_tick: nil, label: "supervised child died", &block)
+      def run(timeout:, cpu_seconds: nil, on_tick: nil, label: "supervised child died", &)
+        pid, reader, started = start(timeout, cpu_seconds, label, &)
+        begin
+          contain(pid, reader, started, timeout, on_tick)
+        ensure
+          reader.close unless reader.closed?
+        end
+      end
+
+      private
+
+      # Forks the child and returns [pid, reader, started]; the caller owns
+      # supervising it with contain and closing the reader.
+      def start(timeout, cpu_seconds, label, &block)
         depth = ENV.fetch(CHILD_ENV, "0").to_i
         raise Error, "refusing to fork: saboteur children nested #{depth} deep (limit #{MAX_DEPTH})" if
           depth >= MAX_DEPTH
@@ -150,13 +166,12 @@ module Saboteur
         @marker = SecureRandom.hex(6)
         pid = fork { child(reader, writer, supervisor, cpu_seconds, depth + 1, &block) }
         writer.close
-        contain(pid, reader, started, timeout, on_tick)
-      ensure
+        [pid, reader, started]
+      rescue Exception # rubocop:disable Lint/RescueException
         reader&.close unless reader&.closed?
+        raise
       end
 
-      private
-
       # --- child ----------------------------------------------------------
 
       def child(reader, writer, supervisor, cpu_seconds, depth)
@@ -259,12 +274,30 @@ module Saboteur
         # only ours to claim if we see it alive: stop it first.
         exit_status, supervisor_killed = freeze_child(pid) if grace_expired
         # Notes name the leftovers before the kill erases their command lines (#486).
-        leftover_pids, notes = tree.kill_all_except(pid)
+        # A blind process table must not skip containment: when the snapshot
+        # raises through kill_all_except (both backends down), reap still
+        # SIGKILLs and reaps the root and reap_group its group - only the
+        # table-driven orphan sweep is lost, and the entry must still leave
+        # the live registry (#762).
+        # Containment first, honesty after: a blind scan never becomes a
+        # clean Result - the guards reading leftover_pids would treat [] as
+        # no leak while setsid grandchildren survive (#762).
+        scan_error = nil
+        begin
+          leftover_pids, notes = tree.kill_all_except(pid)
+        rescue SystemCallError, Fiddle::DLError => e
+          scan_error = e
+          leftover_pids = []
+          notes = ["leftover scan skipped: #{e.class}: #{e.message}"]
+        end
         exit_status ||= reap(pid)
-        self.class.live.delete(pid)
         reap_adopted(leftover_pids)
         reap_group(pid)
+        raise scan_error if scan_error
+
         [exit_status, supervisor_killed, leftover_pids, notes]
+      ensure
+        self.class.live.delete(pid)
       end
 
       # After EOF, waits for the child to exit by itself while still checking

data/lib/saboteur/execution/supervisor_batch.rb

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Execution
+    # Several supervised children at once (#741), mixed into Supervisor. It
+    # relies on Supervisor's start and contain.
+    module SupervisorBatch
+      # Runs count children at once, each supervised with the same limits and
+      # deadline as run, and returns their Results in index order (#741). The
+      # block gets (writer, index). Every child is forked from this thread
+      # before any watcher thread exists, so no fork happens beside a live
+      # thread; each child has its own copy of this supervisor, so its marker,
+      # label and memory peak never mix with a sibling's. Watching runs on one
+      # thread per child; on_tick is called only from the calling thread. A
+      # child that fails or is stopped does not cut its siblings short: every
+      # child is still contained and reaped before this returns, and the
+      # caller decides what a failed part means.
+      def run_many(count, timeout:, cpu_seconds: nil, on_tick: nil, label: "supervised child died", &block)
+        raise ArgumentError, "count must be at least 1, got #{count}" if count < 1
+
+        started = []
+        begin
+          count.times do |index|
+            part = dup
+            started << [part, *part.send(:start, timeout, cpu_seconds, label) { |writer| block.call(writer, index) }]
+          end
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          reap_started(started)
+          raise e
+        end
+        watch_all(started, timeout, on_tick)
+      end
+
+      private
+
+      # One watcher thread per started child. Waits for all of them, even
+      # when one raises, so no child outlives this call; then re-raises the
+      # first failure. When the calling thread's loop is interrupted (on_tick
+      # raised, Interrupt), every child is killed at once instead of being
+      # left to run to its deadline.
+      def watch_all(started, timeout, on_tick)
+        watchers = start_watchers(started, timeout)
+        begin
+          until watchers.none?(&:alive?)
+            on_tick&.call
+            sleep 0.01
+          end
+        rescue Exception # rubocop:disable Lint/RescueException
+          kill_started(started, watchers)
+          raise
+        ensure
+          watchers.each(&:join)
+        end
+        outcomes = watchers.map(&:value)
+        failure = outcomes.find { |outcome| outcome.is_a?(Exception) }
+        raise failure if failure
+
+        outcomes
+      end
+
+      # A watcher that cannot start leaves its child unwatched: reap every
+      # child, then report the original error.
+      def start_watchers(started, timeout)
+        started.map do |part, pid, reader, began|
+          Thread.new do
+            part.send(:contain, pid, reader, began, timeout, nil)
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            e
+          ensure
+            reader.close
+          end
+        end
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        reap_started(started)
+        raise e
+      end
+
+      # Only a child whose watcher is still running can still be ours: once
+      # its watcher has reaped it, its pid may belong to another process.
+      def kill_started(started, watchers = nil)
+        started.each_with_index do |(part, pid, _reader, _began), index|
+          next if watchers && !watchers[index].alive?
+
+          part.send(:signal, "KILL", -pid)
+          part.send(:signal, "KILL", pid)
+        end
+      end
+
+      # Containment for children already forked when a later fork failed:
+      # kill every one, then contain each; one child's failure to be
+      # contained never leaves a later one running.
+      def reap_started(started)
+        kill_started(started)
+        started.each do |part, pid, reader, began|
+          part.send(:contain, pid, reader, began, 0, nil)
+        rescue Exception # rubocop:disable Lint/RescueException
+          nil
+        ensure
+          reader.close
+        end
+      end
+    end
+  end
+end