mutineer 0.11.1 → 0.11.3

data/lib/mutineer/daemon_client.rb

@@ -4,19 +4,23 @@ require "json"
 require "open3"
 
 module Mutineer
-  # Raised when the daemon cannot be booted (bad boot path, app error, or it dies on
-  # the handshake). The CLI maps it to a runtime error.
+  # Raised when the daemon cannot be booted or is gone for good: a bad boot path, an
+  # app error, a failed handshake, a spawn the OS refused, or MAX_RESTARTS crashes.
+  # It means "stop the run" — a backend that scored the remaining mutants against a
+  # dead daemon would report a score covering a fraction of the work. The CLI maps it
+  # to a runtime error (exit 1).
   class DaemonBootError < StandardError; end
 
-  # #26/#27 Phase 2a — the TOOL-side handle for the app-side daemon.
+  # Tool-side handle for the app-side daemon.
   #
-  # Spawns `daemon_server.rb` UNDER THE APP'S BUNDLE/RUBY (cleaned env so the gem's
-  # bundler context never leaks; the daemon file is loaded by absolute path with
-  # `-r`, which bypasses the app bundle that has no mutineer), completes the ready
-  # handshake, then ships per-mutant payloads and reads structured verdicts. If the
-  # daemon dies mid-run it respawns (bounded) and marks the in-flight mutant `error`
-  # rather than corrupting the run. Reuses the cleaned-env spawn + stderr-drain proven
-  # in the spike driver and the spawn discipline of ExternalBackend.
+  # Spawns `daemon_server.rb` UNDER THE APP'S BUNDLE/RUBY (cleaned env so the
+  # gem's bundler context never leaks; the daemon file is loaded by absolute path
+  # with `-r`, which bypasses the app bundle that has no mutineer), completes the
+  # ready handshake, then ships per-mutant payloads and reads structured verdicts.
+  # If the daemon dies mid-run it respawns (bounded) and marks the in-flight
+  # mutant `error` rather than corrupting the run. Reuses the cleaned-env spawn
+  # and stderr-drain proven in the spike driver and the spawn discipline of
+  # ExternalBackend.
   class DaemonClient
     # Absolute path to the daemon entry, loaded app-side by `-r` (bypasses the bundle).
     DAEMON_PATH = File.expand_path("daemon_server.rb", __dir__)
@@ -49,16 +53,22 @@ module Mutineer
 
     # Run one mutant: ship the payload + covering tests, return the verdict string.
     # On a daemon crash (EOF/dead pipe) respawn (bounded) and return `"error"` for
-    # this mutant — never a wrong verdict, never a wedged run.
+    # this mutant. Never a wrong verdict, never a wedged run.
     #
     # @param id [Integer] request id (echoed back for ordering safety).
     # @param payload [Hash] {"code" => mutated ruby, "source_file" => path}.
     # @param tests [Array<String>] covering test file paths.
     # @param timeout [Numeric] per-mutant wall-clock timeout (seconds).
     # @param worker [Integer] worker slot; the daemon routes the fork to
-    #   `<db>-<worker>` (#26 isolation). Defaults to 0 (serial in U5).
+    #   `<db>-<worker>` for isolation. Defaults to 0 (serial).
     # @return [String] one of survived/killed/error/timeout.
     def request(id:, payload:, tests:, timeout:, worker: 0)
+      # close_io nils the pipes, so a client whose respawn never completed would
+      # otherwise fail per-mutant forever (NoMethodError on nil) and let the backend
+      # score every remaining mutant against nothing. Deadness is a property of the
+      # client, not of whichever exception happened to escape.
+      raise DaemonBootError, "daemon is not running" if @stdin.nil?
+
       # A crash can surface on the WRITE (daemon died idle between requests →
       # Errno::EPIPE) as well as the read (EOF), so guard both: either way, respawn
       # for future mutants and score THIS one error (re-running a crash-causing
@@ -76,10 +86,11 @@ module Mutineer
       "error"
     end
 
-    # #26/U7: ask the daemon to build the coverage map app-side and return it.
-    # One-shot control message (no id). Returns `{"map"=>..., "failed_test_files"=>...}`
-    # (possibly with an `"error"`), or nil if the daemon vanished — the caller then
-    # falls back to running the full test set (no narrowing) rather than mis-scoring.
+    # Ask the daemon to build the coverage map app-side and return it. One-shot
+    # control message (no id). Returns `{"map"=>..., "failed_test_files"=>...}`
+    # (possibly with an `"error"`), or nil if the daemon vanished. The caller then
+    # falls back to running the full test set (no narrowing) rather than
+    # mis-scoring.
     #
     # @return [Hash, nil] the coverage payload, or nil on a dead pipe.
     def coverage
@@ -103,8 +114,8 @@ module Mutineer
 
     private
 
-    # Cleaned environment for the app bundle: strip the gem's bundler/Ruby context so
-    # `bundle exec` resolves the APP's Gemfile under the requested Ruby.
+    # Cleaned environment for the app bundle: strip the gem's bundler/Ruby context
+    # so `bundle exec` resolves the APP's Gemfile under the requested Ruby.
     def app_env
       env = ENV.to_h.reject { |k, _| k.start_with?("BUNDLE_", "RUBY", "GEM_") }
       env["BUNDLE_GEMFILE"] = @gemfile
@@ -118,25 +129,38 @@ module Mutineer
     # @return [void]
     # @raise [Mutineer::DaemonBootError] when the daemon fails to boot.
     def spawn_daemon
-      # Plain `bundle exec ruby` — NOT `rbenv exec`, which would break CI and any
-      # non-rbenv setup. When bundler/ruby are rbenv shims, the RBENV_VERSION carried
-      # in app_env still selects the app's Ruby; otherwise the active Ruby is used.
-      @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(
-        app_env, "bundle", "exec", "ruby",
-        "-r", DAEMON_PATH, "-e", "Mutineer::DaemonServer.run", chdir: @app_root
-      )
-      # Drain daemon stderr to the tool's stderr so child/boot errors are visible.
-      # Tracked (not fire-and-forget) so close_io can reclaim it on quit/respawn; the
-      # rescue swallows the benign EBADF/IOError raised when close_io closes the pipe
-      # out from under an in-flight copy_stream.
-      @drain = Thread.new do # rubocop:disable ThreadSafety/NewThread
-        IO.copy_stream(@stderr, @errio)
-      rescue IOError, Errno::EBADF
-        nil
-      end
+      # Plain `bundle exec ruby`, NOT `rbenv exec`, which would break CI and any
+      # non-rbenv setup. When bundler/ruby are rbenv shims, the RBENV_VERSION
+      # carried in app_env still selects the app's Ruby; otherwise the active
+      # Ruby is used.
+      # Everything up to the handshake is terminal, not one mutant's problem: a spawn
+      # the OS refuses (EMFILE/ENOMEM under --jobs N, ENOENT when `bundle` does not
+      # resolve) and a daemon that dies before accepting the boot payload (EPIPE on
+      # the write) both leave a client that cannot recover. Raise the class that ends
+      # the run — a SystemCallError would reach the CLI as a usage error (exit 2).
+      ready =
+        begin
+          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(
+            app_env, "bundle", "exec", "ruby",
+            "-r", DAEMON_PATH, "-e", "Mutineer::DaemonServer.run", chdir: @app_root
+          )
+          # Drain daemon stderr to the tool's stderr so child/boot errors are visible.
+          # Tracked (not fire-and-forget) so close_io can reclaim it on quit/respawn;
+          # the rescue swallows the benign EBADF/IOError raised when close_io closes
+          # the pipe out from under an in-flight copy_stream.
+          @drain = Thread.new do # rubocop:disable ThreadSafety/NewThread
+            IO.copy_stream(@stderr, @errio)
+          rescue IOError, Errno::EBADF
+            nil
+          end
+
+          send_line(@boot)
+          read_line
+        rescue SystemCallError, IOError => e
+          close_io
+          raise DaemonBootError, "daemon could not be started: #{e.class}: #{e.message}"
+        end
 
-      send_line(@boot)
-      ready = read_line
       unless ready && ready["ready"]
         detail = ready && ready["error"] ? ready["error"] : "daemon exited before the handshake"
         close_io

data/lib/mutineer/daemon_server.rb

@@ -4,19 +4,20 @@ require "json"
 require "tempfile"
 
 module Mutineer
-  # #26/#27 Phase 2a — the app-side daemon (persistent worker).
+  # App-side daemon (persistent worker).
   #
   # Runs UNDER THE APP'S OWN BUNDLE/RUBY (the tool's DaemonClient spawns it via
   # `bundle exec ruby`). It boots the app ONCE, then serves per-mutant test-run
-  # requests over stdin/stdout as newline-delimited JSON. For each request it FORKS
-  # a child that loads the mutated source text the tool sent, runs the covering
-  # tests, and exits with a status the parent decodes into a verdict.
+  # requests over stdin/stdout as newline-delimited JSON. For each request it
+  # FORKS a child that loads the mutated source text the tool sent, runs the
+  # covering tests, and exits with a status the parent decodes into a verdict.
   #
-  # HARD CONSTRAINT (KTD-2/R4): this file must be loadable WITHOUT Prism or the rest
-  # of mutineer — the app's Ruby may be < 3.4 (no stdlib Prism) and its bundle has no
-  # mutineer. So it requires ONLY stdlib + the app's own boot file; it re-implements
-  # the fork/timeout/decode loop rather than requiring `isolation.rb` (which pulls in
-  # Prism). All parsing/mutation happened tool-side; the daemon only `load`s text.
+  # HARD CONSTRAINT: this file must be loadable WITHOUT Prism or the rest of
+  # mutineer. The app's Ruby may be < 3.4 (no stdlib Prism) and its bundle has no
+  # mutineer. So it requires ONLY stdlib + the app's own boot file; it
+  # re-implements the fork/timeout/decode loop rather than requiring
+  # `isolation.rb` (which pulls in Prism). All parsing/mutation happened
+  # tool-side; the daemon only `load`s text.
   #
   # Protocol (one JSON object per line, both directions):
   #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment",
@@ -27,16 +28,18 @@ module Mutineer
   #   verdict  : {"id":N,"verdict":"survived"|"killed"|"error"|"timeout"}
   #   quit in  : {"cmd":"quit"}
   #
-  # Worker isolation (#26/U5): when the app is Rails, each fork is routed to its own
-  # database `<db>-<worker>` via {RailsWorkerDb} BEFORE any test loads, so concurrent
-  # workers can't clobber each other's transactional fixtures. `worker` defaults to 0
-  # (serial). SQLite this pass; Postgres provisioning is U10.
+  # Worker isolation: when the app is Rails, each fork is routed to its own
+  # database `<db>-<worker>` via {RailsWorkerDb} BEFORE any test loads, so
+  # concurrent workers cannot clobber each other's transactional fixtures.
+  # `worker` defaults to 0 (serial). SQLite this pass; Postgres provisioning is
+  # not yet implemented.
   #
-  # Verdict mapping (KTD-5, Phase-2a honest limit): child exit 0=survived (suite
-  # passed), 1=killed (suite failed), 2=error (child raised AROUND the test — load,
-  # boot, or worker-DB routing failure); parent-detected timeout. Tagging an in-TEST DB
-  # error (one fired inside a test body, vs at routing time) as `error` rather than
-  # `killed` is a U6 concern — only observable under the concurrent gate.
+  # Verdict mapping: child exit 0=survived (suite passed), 1=killed (suite
+  # failed), 2=error (child raised AROUND the test: load, boot, or worker-DB
+  # routing failure); parent-detected timeout. Tagging an in-test DB error (one
+  # fired inside a test body, vs at routing time) as `error` rather than
+  # `killed` is only observable under the concurrent gate and is not yet
+  # implemented.
   module DaemonServer
     # Poll interval (seconds) for the per-fork deadline wait loop.
     POLL = 0.02
@@ -65,16 +68,16 @@ module Mutineer
           begin
             req = JSON.parse(line)
           rescue JSON::ParserError => e
-            # A corrupt line has no id to address a reply to (and the client only ever
-            # sends valid JSON, so it can't be a pending request) — log and read on
-            # rather than write an unaddressable verdict onto the channel.
+            # A corrupt line has no id to address a reply to (and the client only
+            # ever sends valid JSON, so it cannot be a pending request). Log and
+            # read on rather than write an unaddressable verdict onto the channel.
             @errio.puts("[daemon] dropped unparseable line: #{e.message}")
             next
           end
           break if req["cmd"] == "quit"
 
-          # #26/U7: build the coverage map app-side and ship it to the tool, which
-          # then selects covering tests per mutant. One-shot control message.
+          # Build the coverage map app-side and ship it to the tool, which then
+          # selects covering tests per mutant. One-shot control message.
           if req["cmd"] == "coverage"
             output.puts(JSON.generate(build_coverage_map))
             output.flush
@@ -88,8 +91,8 @@ module Mutineer
 
       private
 
-      # BOOT ONCE. chdir + require the app's boot file so the whole app is loaded and
-      # inherited by every fork. Never requires mutineer.
+      # BOOT ONCE. chdir + require the app's boot file so the whole app is loaded
+      # and inherited by every fork. Never requires mutineer.
       def boot!(cfg)
         @cfg = cfg
         @framework = cfg.fetch("framework", "minitest")
@@ -97,30 +100,30 @@ module Mutineer
         Dir.chdir(cfg["project_root"]) if cfg["project_root"]
         ENV["RAILS_ENV"] ||= "test" if cfg["rails"]
         Array(cfg["load_paths"]).each { |d| $LOAD_PATH.unshift(File.expand_path(d)) }
-        # #26/U7: start Coverage BEFORE the app loads, so booted source lines are
-        # instrumented — the map build (build_via_fork) forks this booted parent.
+        # Start Coverage BEFORE the app loads, so booted source lines are
+        # instrumented. The map build (build_via_fork) forks this booted parent.
         if cfg["coverage"]
           require "coverage"
           Coverage.start(lines: true)
         end
         # Clear any mutant tempfile a prior SIGKILLed timeout child orphaned in a
-        # source dir BEFORE the app boots — Zeitwerk would otherwise choke on the
+        # source dir BEFORE the app boots. Zeitwerk would otherwise choke on the
         # tempfile's non-constant name during autoload setup.
         sweep_temps
         require File.expand_path(cfg["boot"]) if cfg["boot"]
         setup_worker_db(cfg) if cfg["rails"]
       rescue Exception => e # rubocop:disable Lint/RescueException
-        # Boot failed (bad boot path, app error) — tell the client and exit so it can
-        # surface a clean error rather than hang on the handshake.
+        # Boot failed (bad boot path, app error). Tell the client and exit so it
+        # can surface a clean error rather than hang on the handshake.
         @output.puts(JSON.generate("ready" => false, "error" => "#{e.class}: #{e.message}"))
         @output.flush
         exit!(1)
       end
 
-      # Load the per-worker DB adapter app-side (sibling gem file, by relative path so
-      # it bypasses the app bundle — like this daemon itself). No-op unless the app has
-      # ActiveRecord. Records the adapter + schema path so each fork can route to its
-      # own database (#26 isolation, U5). SQLite-only this pass; a non-SQLite config
+      # Load the per-worker DB adapter app-side (sibling gem file, by relative path
+      # so it bypasses the app bundle, like this daemon itself). No-op unless the
+      # app has ActiveRecord. Records the adapter + schema path so each fork can
+      # route to its own database. SQLite-only this pass; a non-SQLite config
       # raises in the fork and reads as `error`, never a mis-routed verdict.
       def setup_worker_db(cfg)
         require_relative "rails_worker_db"
@@ -134,11 +137,11 @@ module Mutineer
         @worker_db = nil
       end
 
-      # #26/U7: build the coverage map app-side (Coverage was started at boot) and
-      # return it as `{map, failed_test_files}` for the tool to select covering tests.
-      # Capture forks route to worker 0's DB (isolated, serial). On any failure return
-      # an empty map + an error string — the tool then falls back to the full test set
-      # rather than mis-scoring everything as no_coverage.
+      # Build the coverage map app-side (Coverage was started at boot) and return
+      # it as `{map, failed_test_files}` for the tool to select covering tests.
+      # Capture forks route to worker 0's DB (isolated, serial). On any failure
+      # return an empty map + an error string. The tool then falls back to the
+      # full test set rather than mis-scoring everything as no_coverage.
       def build_coverage_map
         require_relative "coverage_map"
         root = @cfg["project_root"] || Dir.pwd
@@ -153,9 +156,9 @@ module Mutineer
         { "map" => {}, "failed_test_files" => [], "error" => "#{e.class}: #{e.message}" }
       end
 
-      # Fork-safety hook for coverage capture: route each capture fork to worker 0's
-      # isolated DB (captures run serially, so one worker is enough). Nil when the app
-      # has no worker-DB adapter (non-Rails) — capture then runs as before.
+      # Fork-safety hook for coverage capture: route each capture fork to worker
+      # 0's isolated DB (captures run serially, so one worker is enough). Nil when
+      # the app has no worker-DB adapter (non-Rails). Capture then runs as before.
       def coverage_after_fork
         return nil unless @worker_db
 
@@ -190,16 +193,16 @@ module Mutineer
         verdict = wait_verdict(pid, timeout)
         # Mark ready only when the child finished cleanly after schema load
         # (killed/survived). Timeout can interrupt mid-load_schema; error is a
-        # routing failure — both leave the slot unready so the next fork reloads.
+        # routing failure. Both leave the slot unready so the next fork reloads.
         @schema_ready[worker] = true if schema_for_fork && %w[killed survived].include?(verdict)
-        # A SIGKILLed timeout child skipped its Tempfile unlink — sweep the orphan so
-        # it can't outlive the run or trip Zeitwerk on a later fork.
+        # A SIGKILLed timeout child skipped its Tempfile unlink. Sweep the orphan
+        # so it cannot outlive the run or trip Zeitwerk on a later fork.
         sweep_temps if verdict == "timeout"
         { "id" => req["id"], "verdict" => verdict }
       end
 
       # Remove orphaned mutant tempfiles from the source dirs (parent-side; the
-      # SIGKILL path can't run the child's ensure). Mirrors Runner.sweep_orphans.
+      # SIGKILL path cannot run the child's ensure). Mirrors Runner.sweep_orphans.
       def sweep_temps
         @source_dirs.to_a.each do |dir|
           Dir.glob(File.join(dir, "mutineer_daemon*.rb")).each do |f|
@@ -209,12 +212,12 @@ module Mutineer
       end
 
       # Single-waiter deadline loop (mirrors Isolation.run and
-      # ExternalBackend.wait_with_timeout, re-implemented here because Isolation pulls
-      # in Prism which is forbidden app-side). NOTE: this is the 3rd copy of the
-      # waitpid2(WNOHANG)+deadline+pgroup-SIGKILL+decode discipline — a fix to the
-      # kill/reap/decode logic must be applied to all three in lockstep. SIGKILL the
-      # child's process group past the deadline; a signalled child (nil exitstatus) is
-      # `error`.
+      # ExternalBackend.wait_with_timeout, re-implemented here because Isolation
+      # pulls in Prism which is forbidden app-side). NOTE: this is the 3rd copy of
+      # the waitpid2(WNOHANG)+deadline+pgroup-SIGKILL+decode discipline. A fix to
+      # the kill/reap/decode logic must be applied to all three in lockstep.
+      # SIGKILL the child's process group past the deadline; a signalled child
+      # (nil exitstatus) is `error`.
       def wait_verdict(pid, timeout)
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
         loop do
@@ -242,14 +245,15 @@ module Mutineer
         end
       end
 
-      # Write the tool-built mutated text beside the real source and `load` it —
-      # reopening the mutated class/method in THIS child only. It goes in the source
-      # file's directory (like Isolation.apply_whole_file) so a `require_relative` in
-      # the mutated source resolves against its real neighbours — writing it to the
-      # tmpdir would LoadError on such files and score a spurious `error` that
-      # diverges from the in-process path. The Zeitwerk hazard (a stray `.rb` in an
-      # autoload dir) is handled by the boot/timeout `sweep_temps`, not by relocating
-      # the file. Same path for reload (whole file) and redefine (wrapped snippet).
+      # Write the tool-built mutated text beside the real source and `load` it,
+      # reopening the mutated class/method in THIS child only. It goes in the
+      # source file's directory (like Isolation.apply_whole_file) so a
+      # `require_relative` in the mutated source resolves against its real
+      # neighbours. Writing it to the tmpdir would LoadError on such files and
+      # score a spurious `error` that diverges from the in-process path. The
+      # Zeitwerk hazard (a stray `.rb` in an autoload dir) is handled by the
+      # boot/timeout `sweep_temps`, not by relocating the file. Same path for
+      # reload (whole file) and redefine (wrapped snippet).
       def apply_payload(payload)
         dir = File.dirname(File.expand_path(payload.fetch("source_file")))
         Tempfile.create(["mutineer_daemon", ".rb"], dir) do |f|
@@ -260,7 +264,7 @@ module Mutineer
       end
 
       # Load the covering test files and run them; 0 = all passed (survived),
-      # 1 = a failure/error (killed). Minitest only in 2a (rspec is a later unit).
+      # 1 = a failure/error (killed). Minitest only; rspec is not yet on this path.
       def run_tests(tests)
         raise "unsupported framework #{@framework.inspect}" unless @framework == "minitest"
 

data/lib/mutineer/external_backend.rb

@@ -10,17 +10,21 @@ module Mutineer
   # tests. The CLI maps this to a runtime error (exit 1), not a usage error.
   class SmokeCheckError < StandardError; end
 
-  # #27 (U3): the external execution backend. Runs the user's `--test-command` as a
-  # subprocess in the app's OWN runtime (whatever Ruby its bundle resolves to), so
-  # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
+  # External execution backend. Runs the user's `--test-command` as a subprocess
+  # in the app's own runtime (whatever Ruby its bundle resolves to), so mutineer
+  # (Ruby ≥ 3.4) can mutation-test apps pinned to an older Ruby.
   #
   # This is deliberately NOT a `TestRunners` framework adapter: those return an
   # Integer 0/1 from inside a fork and are dispatched by framework name. This is a
   # whole backend — it spawns a process, enforces a wall-clock timeout, and maps
-  # the exit status to a Result. The mapping is the SAME direction as in-process
+  # the exit status to a Result. The mapping is the same direction as in-process
   # (suite passes => survived, suite fails => killed) but coarser: it cannot tell an
   # infrastructure error from a genuine kill, so the smoke check (below) guards the
-  # persistent case and the score is disclosed as an upper bound (KTD-3/KTD-6).
+  # persistent case and the score is disclosed as an upper bound.
+  #
+  # Child environment: bundler/gem env injected by Mutineer's Ruby is stripped, and
+  # version-manager concrete version bins (e.g. `~/.rbenv/versions/3.4.9/bin`) are
+  # removed from PATH so shims / `.ruby-version` can select the app's Ruby (#32).
   module ExternalBackend
     # Generous ceiling for the one-off smoke/calibration run (a cold app boot plus
     # the full suite). The per-mutant timeout is derived from how long this took.
@@ -29,6 +33,24 @@ module Mutineer
     # this backend waits on an external process TREE, not an in-process fork.
     POLL = 0.02
 
+    # PATH entries that pin a concrete Ruby under a version manager (ahead of
+    # shims). Optional trailing slash; normal bins are left alone.
+    VERSION_BIN_PATH = %r{
+      (?:
+        /\.rbenv/versions/[^/]+/bin
+        |/\.asdf/installs/ruby/[^/]+/bin
+        |/\.rubies/[^/]+/bin
+        |/rubies/[^/]+/bin
+      )/?\z
+    }x
+
+    # Env keys Process.spawn must unset (nil value) so Mutineer's Ruby/bundler
+    # context does not leak. Spawn merges env onto the parent; omitting a key
+    # does NOT clear it.
+    CLEAR_ENV_KEYS = %w[
+      BUNDLER_VERSION RBENV_VERSION ASDF_RUBY_VERSION RBENV_DIR
+    ].freeze
+
     # Turn a command template into an argv array (no shell → no eval, no
     # injection). The `%{files}` token expands IN PLACE to N separate argv
     # elements — one per path, unescaped — so a path containing a space stays a
@@ -41,10 +63,63 @@ module Mutineer
       Shellwords.split(command).flat_map { |tok| tok == "%{files}" ? files : [tok] }
     end
 
+    # Environment delta for the test-command child. Process.spawn merges this
+    # onto the parent env: set a key to +nil+ to unset it. Scrubs Mutineer/bundler
+    # injection and version-manager PATH pins so shims / `.ruby-version` can win.
+    # Keeps other vars (e.g. `RAILS_ENV`) so setting them on the Mutineer command
+    # still reaches the suite.
+    #
+    # @api private
+    # @return [Hash{String => String, nil}] env for Process.spawn.
+    def self.child_env
+      env = {}
+      cleared_pin = false
+      ENV.each_key do |k|
+        next unless clear_env_key?(k)
+
+        env[k] = nil
+        cleared_pin = true
+      end
+      path = ENV["PATH"].to_s.split(File::PATH_SEPARATOR)
+      kept = path.reject { |p| p.match?(VERSION_BIN_PATH) }
+      scrubbed_bin = kept.size != path.size
+      # Only reorder PATH when we scrubbed a pin; otherwise leave the user's PATH alone.
+      path = if cleared_pin || scrubbed_bin
+               (version_manager_shim_dirs + kept).uniq
+             else
+               kept
+             end
+      env["PATH"] = path.join(File::PATH_SEPARATOR)
+      env
+    end
+
+    # True when the key must be unset in the child (bundler/gem/version-manager).
+    #
+    # @api private
+    # @param key [String] environment variable name.
+    # @return [Boolean]
+    def self.clear_env_key?(key)
+      key.start_with?("BUNDLE_", "RUBY", "GEM_") || CLEAR_ENV_KEYS.include?(key)
+    end
+
+    # Existing shim directories for rbenv / asdf (chruby uses PATH without shims).
+    #
+    # @api private
+    # @return [Array<String>] absolute shim paths that exist.
+    def self.version_manager_shim_dirs
+      home = ENV["HOME"]
+      return [] if home.nil? || home.empty?
+
+      [
+        File.join(home, ".rbenv", "shims"),
+        File.join(home, ".asdf", "shims")
+      ].select { |d| File.directory?(d) }
+    end
+
     # Runs the command for ONE mutant against whatever is currently on disk (the
     # caller has already swapped the mutant in via FileSwap). Maps the outcome to a
-    # Result. Env is inherited by the subprocess, so `RAILS_ENV=test mutineer …`
-    # reaches the child with no parsing here.
+    # Result. Uses {child_env} so version-manager PATH pins from Mutineer's Ruby do
+    # not force the suite onto the wrong interpreter.
     #
     # @param command [String] the --test-command template.
     # @param files [Array<String>] test file paths.
@@ -93,10 +168,42 @@ module Mutineer
         else                      "exited #{code}"
         end
       detail = output.empty? ? "" : "\n--- last output ---\n#{tail(output)}"
+      hint = ruby_version_mismatch_hint(output)
       raise SmokeCheckError,
-            "the test command #{reason} against the UNMUTATED source — the " \
-            "environment looks broken (check DB, RAILS_ENV, migrations), not the " \
-            "tests weak.#{detail}"
+            "the test command #{reason} against the UNMUTATED source — " \
+            "#{hint || generic_env_hint}.#{detail}"
+    end
+
+    # Generic smoke-failure framing when no Ruby-version mismatch is detected.
+    #
+    # @api private
+    # @return [String]
+    def self.generic_env_hint
+      "the unmutated suite is not green (failing tests, or a broken environment: " \
+        "DB, RAILS_ENV, migrations) — fix that before scoring"
+    end
+
+    # Targeted hint when Bundler reports a RubyVersionMismatch (common under
+    # rbenv/asdf/chruby when Mutineer's version bin sits ahead of shims on PATH).
+    #
+    # @api private
+    # @param output [String] captured child stdout+stderr.
+    # @return [String, nil] hint text, or nil when not a version mismatch.
+    def self.ruby_version_mismatch_hint(output)
+      return nil if output.nil? || output.empty?
+      return nil unless output.match?(/RubyVersionMismatch|Your Ruby version is .* but your Gemfile specified/i)
+
+      ran = output[/Your Ruby version is ([0-9.]+)/i, 1]
+      want = output[/Gemfile specified ([0-9.]+)/i, 1]
+      parts = +"Detected a Ruby version mismatch"
+      parts << ": the test command ran under #{ran}" if ran
+      parts << " but the app expects #{want}" if want
+      parts << ". Mutineer already scrubbed version-manager bins and RBENV_VERSION/" \
+               "ASDF_RUBY_VERSION from the child env; the suite still picked the wrong " \
+               "Ruby. Use a wrapper that re-selects the app Ruby and ensure " \
+               ".ruby-version / .tool-versions is present " \
+               "(see README: Apps on Ruby < 3.4 → Under a version manager)"
+      parts
     end
 
     # Spawns the command to a captured combined-output tempfile, enforces a
@@ -122,7 +229,8 @@ module Mutineer
       # explicit [program, argv0] form guarantees the no-shell exec path even for a
       # degenerate single-element argv (Process.spawn(*argv) would route a lone
       # metachar-bearing string through /bin/sh, breaking the argv-only invariant).
-      pid = Process.spawn([argv.first, argv.first], *argv[1..], out: out, err: %i[child out], pgroup: true)
+      pid = Process.spawn(child_env, [argv.first, argv.first], *argv[1..],
+                          out: out, err: %i[child out], pgroup: true)
       kind, code = wait_with_timeout(pid, timeout)
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
       out.rewind

data/lib/mutineer/file_swap.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # Raised when a source file's backup already exists as FileSwap.with begins —
-  # a second mutineer run is racing on the same file (the backup path is shared
+  # Raised when a source file's backup already exists as FileSwap.with begins.
+  # A second mutineer run is racing on the same file (the backup path is shared
   # and unlocked). Aborting beats silently leaving the tree mutated.
   class ConcurrentRunError < StandardError
     def initialize(backup)
@@ -11,11 +11,11 @@ module Mutineer
     end
   end
 
-  # #27 (U2): apply one whole-file mutant to the REAL source path for the external
+  # Apply one whole-file mutant to the REAL source path for the external
   # (`--test-command`) backend, and guarantee the original is restored on every
-  # exit path. A separate `bundle exec` subprocess has its own VM and cannot see an
-  # in-process `load`, so the mutant must live on disk while its suite runs — which
-  # makes leaving the file mutated the one genuinely dangerous failure mode.
+  # exit path. A separate `bundle exec` subprocess has its own VM and cannot see
+  # an in-process `load`, so the mutant must live on disk while its suite runs,
+  # which makes leaving the file mutated the one genuinely dangerous failure mode.
   #
   # Defense in depth, mirroring the tempfile-orphan discipline
   # (`Runner.sweep_orphans`, `isolation.rb` tempfiles):
@@ -39,12 +39,13 @@ module Mutineer
     # @return [Object] the block's return value.
     def self.with(source_file, mutated)
       backup = source_file + BACKUP_SUFFIX
-      # A backup already on disk means either a prior hard-killed run (restore_orphans
-      # should have healed it at startup) or a SECOND mutineer run racing us on the
-      # same file. The backup path is shared and unlocked, so proceeding would let
-      # us capture the other run's mutant AS the "original" and permanently mutate
-      # the tree. Refuse loudly rather than silently corrupt — and do it BEFORE
-      # `created` is set, so the ensure below never touches a backup we don't own.
+      # A backup already on disk means either a prior hard-killed run
+      # (restore_orphans should have healed it at startup) or a SECOND mutineer
+      # run racing us on the same file. The backup path is shared and unlocked, so
+      # proceeding would let us capture the other run's mutant AS the "original"
+      # and permanently mutate the tree. Refuse loudly rather than silently
+      # corrupt, and do it BEFORE `created` is set, so the ensure below never
+      # touches a backup we don't own.
       raise ConcurrentRunError, backup if File.exist?(backup)
 
       original = File.binread(source_file)
@@ -74,11 +75,11 @@ module Mutineer
           backup_bytes = File.binread(backup)
           if !File.exist?(source_file)
             # A real user file that merely ends in our suffix, with no sibling to
-            # restore — leave it untouched (never create a file from it).
+            # restore. Leave it untouched (never create a file from it).
             next
           elsif File.binread(source_file) == backup_bytes
-            # Redundant backup (e.g. a crash between restore and unlink): nothing to
-            # heal, just clear the orphan so the next run doesn't see a false race.
+            # Redundant backup (e.g. a crash between restore and unlink): nothing
+            # to heal, just clear the orphan so the next run does not see a false race.
             File.unlink(backup)
           else
             File.binwrite(source_file, backup_bytes)