mutineer 1.7.0 → 1.8.0

data/lib/mutineer/daemon_server.rb

@@ -28,12 +28,15 @@ module Mutineer
   #
   # Protocol (one JSON object per line, both directions):
   #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment","require_paths":[...],
-  #               "load_paths":["test"],"framework":"minitest","rails":true,"schema":"db/schema.rb"}
-  #   ready out: {"ready":true,"ruby":"3.3.6","database_count":1}
+  #               "load_paths":["test"],"framework":"minitest","rails":true}
+  #   ready out: {"ready":true,"ruby":"3.3.6","databases":{"names":["primary"],"primary":"primary"}}
+  #              ("databases" is null with no worker-DB adapter, {"error":"...","primary":"primary"|null} when the lookup fails)
   #              (or {"ready":false,"error":"..."} then exit)
   #   provision: {"cmd":"provision","slots":N} -> {"ok":true} or {"ok":false,"error":"..."}
   #   run  in  : {"id":N,"worker":I,"payload":{"code":"<ruby>","source_file":"app/models/order.rb"},
   #               "tests":["test/models/order_test.rb"],"timeout":30}
+  #              (a mutant of a def in a concern's hook block adds to the payload
+  #               "hook_def":{"line":12,"name":"total","singleton":false}, #297)
   #   verdict  : {"id":N,"verdict":"survived"|"killed"|"error"|"timeout"}
   #   quit in  : {"cmd":"quit"}
   #
@@ -45,29 +48,23 @@ module Mutineer
   #
   # 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.
+  # routing failure); parent-detected timeout. Exit 2 also covers a run whose
+  # first failing test failed with an Active Record connection or lock error
+  # inside the test (#296): {MinitestIntegration::InTestDatabaseError} decides.
   module DaemonServer
     # Poll interval (seconds) for the per-fork deadline wait loop.
     POLL = 0.02
-    # Basename glob for a mutant file written beside a source file.
-    # Tempfile puts hyphens in the name, so it is not a constant name. The
-    # leading dot hides a new file from Zeitwerk (#253); a file an older
-    # version left behind has none, so the glob matches both.
-    DAEMON_TEMP_BASENAME = "{.,}mutineer_daemon*.rb"
-
-    # Skips daemon mutant files when Zeitwerk scans an autoload directory.
-    # The boot sweep keeps a file another process still holds. Zeitwerk skips a
-    # hidden one (#253), but one an older version wrote has no dot, and it would
-    # stop the next boot, because its name is not a constant.
+    # Skips mutant files of both modes ({OrphanGuard::TEMP_BASENAME}) when
+    # Zeitwerk scans an autoload directory. The boot sweep keeps a file another
+    # process still holds. Zeitwerk skips a hidden one (#253), but one an older
+    # version wrote has no dot, and it would stop the next boot, because its
+    # name is not a constant.
     module DaemonTempIgnore
       # @return [void]
       def setup
         dirs = Array(Mutineer::DaemonServer.instance_variable_get(:@source_dirs))
         dirs.each do |dir|
-          ignore(File.join(dir, Mutineer::DaemonServer::DAEMON_TEMP_BASENAME))
+          ignore(File.join(dir, Mutineer::OrphanGuard::TEMP_BASENAME))
         end
         super
       end
@@ -87,11 +84,13 @@ module Mutineer
         output ||= @protocol
         @errio = errio
         @output = output
+        # The client sends UTF-8 JSON; with LANG unset the pipe would read as US-ASCII (#303).
+        input.set_encoding(Encoding::UTF_8)
         boot_line = input.gets
         return if boot_line.nil? # client vanished before boot
 
         boot!(JSON.parse(boot_line.strip))
-        output.puts(JSON.generate("ready" => true, "ruby" => RUBY_VERSION, "database_count" => database_count))
+        output.puts(JSON.generate("ready" => true, "ruby" => RUBY_VERSION, "databases" => databases))
         output.flush
 
         input.each_line do |line|
@@ -197,8 +196,10 @@ module Mutineer
       def setup_worker_db(cfg)
         require_relative "rails_worker_db"
         @worker_db = RailsWorkerDb.available? ? RailsWorkerDb : nil
-        schema = cfg["schema"] && File.expand_path(cfg["schema"])
-        @schema_path = schema if schema && File.exist?(schema)
+        # Only the booted app knows its schema file (`schema_dump:` can rename it).
+        @schema_path = @worker_db&.ruby_schema_path
+        # Only a parallel worker daemon gets these names (DaemonBackend.boot_config).
+        @shared_databases = Array(cfg["shared_databases"]).map(&:to_s)
         # Each SQLite slot is seeded once, on first use (not every mutant fork).
         # Postgres and MySQL slots are copied at provision time, so this flag is unused there.
         @slot_ready = {}
@@ -217,16 +218,44 @@ module Mutineer
         @worker_db = nil
       end
 
-      # Database configs in the booted test environment. 1 when the app has no
-      # worker-DB adapter. The tool uses this to force a single worker.
+      # The booted test environment's database config names and the one each
+      # worker copies, for the tool's worker count. nil when the app has no
+      # worker-DB adapter. A failed lookup is reported, not hidden: the tool
+      # then keeps one worker. That report still names the primary when it
+      # resolves, so the tool still rejects a `shared_databases` that lists it.
       #
-      # @return [Integer]
-      def database_count
-        return 1 unless @worker_db
+      # @return [Hash, nil]
+      def databases
+        return nil unless @worker_db
 
-        @worker_db.database_count
+        @worker_db.database_names
+      rescue StandardError => e
+        { "error" => describe_error(e), "primary" => primary_database_name }
+      end
+
+      # The primary config name alone, or nil when it does not resolve either.
+      #
+      # @return [String, nil]
+      def primary_database_name
+        @worker_db.primary_database_name
       rescue StandardError
-        1
+        nil
+      end
+
+      # Raise when a test in this fork used a database that parallel workers
+      # share (`shared_databases`). Its verdict may rest on another worker's
+      # rows, so the mutant is scored `error`. A serial run sends no names.
+      #
+      # @return [void]
+      # @raise [RuntimeError] when a shared database holds a connection.
+      def check_shared_databases!
+        return if @worker_db.nil? || @shared_databases.nil? || @shared_databases.empty?
+
+        used = @worker_db.touched_shared_databases(@shared_databases)
+        return if used.empty?
+
+        raise "shared database used during a parallel run: #{used.join(", ")}. " \
+              "Remove it from shared_databases, or see https://github.com/davidteren/mutineer/blob/main/docs/rails-setup.md#more-than-one-database"
       end
 
       # Run {RailsWorkerDb.provision} and report success or the cause. A failure
@@ -270,11 +299,13 @@ module Mutineer
 
       # `Class: message` for an error the daemon reports, with credentials hidden.
       # Rails parses DATABASE_URL itself, so its URI error can carry the password.
+      # {Redaction.describe} never raises, so a rescue that calls this cannot
+      # make the raw error the cause of a new one.
       #
       # @param error [Exception]
       # @return [String]
       def describe_error(error)
-        redact("#{error.class}: #{error.message}")
+        Redaction.describe(error)
       end
 
       # Hide database credentials in text bound for the client or stderr.
@@ -327,7 +358,12 @@ module Mutineer
               # A routing failure raises here and is scored `error`, never a false verdict.
               @worker_db&.after_fork(worker, first_use ? @schema_path : nil, seed: first_use)
               apply_payload(req["payload"])
-              run_tests(Array(req["tests"]))
+              # A parallel worker records each pool that runs SQL, so a test
+              # that closes its shared connection is still caught below.
+              @worker_db.watch_sql if @worker_db && @shared_databases&.any?
+              result = run_tests(Array(req["tests"]))
+              check_shared_databases!
+              result
             rescue Exception => e # rubocop:disable Lint/RescueException
               @errio.puts("[daemon-child] #{describe_error(e)}")
               2
@@ -336,8 +372,12 @@ module Mutineer
         end
         verdict = wait_verdict(pid, timeout)
         # Mark ready only when the child finished cleanly after seeding
-        # (killed/survived). Timeout can interrupt mid-copy; error is a routing
-        # failure. Both leave the slot unready so the next fork seeds again.
+        # (killed/survived). Timeout can interrupt mid-copy; error can be a
+        # routing failure or a database error inside a test (#296). Both leave
+        # the slot unready so the next fork seeds again. A shared-database
+        # error (check_shared_databases!) also exits 2, so it seeds again too:
+        # the exit code cannot tell it from a routing failure. That costs only
+        # time, in a run where that check then fails every mutant.
         @slot_ready[worker] = true if first_use && %w[killed survived].include?(verdict)
         # A SIGKILLed timeout child skipped its Tempfile unlink. Sweep the orphan
         # so it cannot outlive the run.
@@ -371,12 +411,13 @@ module Mutineer
         Zeitwerk::Loader.prepend(DaemonTempIgnore)
       end
 
-      # Remove orphaned mutant tempfiles from the source dirs (parent-side; the
-      # SIGKILL path cannot run the child's ensure). Mirrors JobPlan.sweep_orphans.
-      # Skips a file another process still owns ({OrphanGuard.mutant_file_in_use?}).
+      # Remove orphaned mutant tempfiles of both modes from the source dirs
+      # (parent-side; the SIGKILL path cannot run the child's ensure). Mirrors
+      # JobPlan.sweep_orphans. Skips a file another process still owns
+      # ({OrphanGuard.mutant_file_in_use?}).
       def sweep_temps
         @source_dirs.to_a.each do |dir|
-          Dir.glob(File.join(dir, DAEMON_TEMP_BASENAME)).each do |path|
+          Dir.glob(File.join(dir, OrphanGuard::TEMP_BASENAME)).each do |path|
             next if OrphanGuard.mutant_file_in_use?(path)
 
             File.unlink(path) rescue nil # rubocop:disable Style/RescueModifier
@@ -432,6 +473,9 @@ module Mutineer
       # removes orphans and never touches a live file. Same path for reload
       # (whole file) and redefine (wrapped snippet). The backend sends the whole
       # file, so the concern blocks it stores replace the forgotten ones (#256).
+      # With a `"hook_def"`, the loaded file stored a mutated hook-block def, and
+      # {ConcernBlocks.place_hook_def} loads it into each class that has the
+      # method; it raises when none was stored, so the mutant scores `error` (#297).
       def apply_payload(payload)
         dir = File.dirname(File.expand_path(payload.fetch("source_file")))
         Tempfile.create([".mutineer_daemon", ".rb"], dir) do |f|
@@ -442,17 +486,25 @@ module Mutineer
           f.flush
           ConcernBlocks.replace(payload.fetch("source_file")) { load f.path }
         end
+        hook = payload["hook_def"] or return
+
+        ConcernBlocks.place_hook_def(source_file: payload.fetch("source_file"), line: hook.fetch("line"),
+                                     name: hook.fetch("name").to_sym, singleton: hook.fetch("singleton"))
       end
 
       # Load the covering test files and run them; 0 = all passed (survived),
-      # 1 = a failure/error (killed). Minitest only; rspec is not yet on this path.
+      # 1 = a failure/error (killed), 2 = the first failure was an in-test
+      # database error (error, #296). Minitest only; rspec is not yet on this path.
+      # {MinitestIntegration.run} is the method the daemon's clean check uses,
+      # so each mutant fork gets the same seed and class list (#282). It loads
+      # only stdlib, so the daemon still needs no Prism. The fork requires
+      # nothing else first: the test files' `require "test_helper"` loads
+      # rails/test_help after the class list is reset, as in the clean check.
       def run_tests(tests)
         raise "unsupported framework #{@framework.inspect}" unless @framework == "minitest"
 
-        require "minitest"
-        require "rails/test_help" if defined?(Rails)
-        tests.each { |t| load File.expand_path(t) }
-        Minitest.run([]) ? 0 : 1
+        require_relative "minitest_integration"
+        MinitestIntegration.run(tests.map { |t| File.expand_path(t) })
       end
     end
   end

data/lib/mutineer/external_backend.rb

@@ -4,6 +4,7 @@ require "shellwords"
 require "tempfile"
 require_relative "result"
 require_relative "rails_run_env"
+require_relative "redaction"
 
 module Mutineer
   # Raised when the smoke check (the unmutated suite) is not green, so the run
@@ -18,15 +19,18 @@ module Mutineer
   # 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
-  # (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.
+  # the exit status to a Result. The mapping follows Isolation.decode: exit 0 is
+  # survived, exit 1 is killed, and any other exit is error (#292). When the clean
+  # smoke run printed a Minitest or RSpec summary line, exit 1 is a kill only when
+  # the output also shows a failing test, so a suite that crashed before its tests
+  # ran is not a kill. The smoke check (below) guards a persistently broken
+  # environment, 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).
-  # PARALLEL_WORKERS and DISABLE_SPRING are set to 1 ({RailsRunEnv}).
+  # PARALLEL_WORKERS and DISABLE_SPRING are set to 1 ({RailsRunEnv}), and so is
+  # DISABLE_BOOTSNAP_COMPILE_CACHE ({child_env}).
   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.
@@ -37,6 +41,26 @@ module Mutineer
     # Exit codes a shell or wrapper uses when the command could not run at all
     # (126: not executable, 127: not found). Scored `error`, never `killed`.
     CANNOT_RUN_CODES = [126, 127].freeze
+    # The exit code Minitest, `bin/rails test` and RSpec use for a failing test.
+    # Any other non-zero code is scored `error`, the same rule as Isolation.decode.
+    FAILURE_CODE = 1
+
+    # The end-of-run summary line of Minitest 5 and 6 ("N runs") and of
+    # minitest-reporters ("N tests"). Captures the failure and error counts.
+    MINITEST_SUMMARY = /\d+ (?:runs|tests), \d+ assertions, (\d+) failures, (\d+) errors/
+    # The end-of-run summary line of RSpec ("N examples, N failures").
+    # Captures the failure count.
+    RSPEC_SUMMARY = /\d+ examples?, (\d+) failures?/
+    # The line Minitest prints once every test file has loaded, before the first
+    # test runs. Exit 1 after it with no summary line means code under test
+    # called `exit 1` or `abort`, which the in-process backend also scores killed.
+    MINITEST_RUNNING = "# Running:"
+    # The line SimpleCov prints when its minimum_coverage gate fails the run.
+    SIMPLECOV_GATE = /SimpleCov failed with exit \d+ due to a coverage related error/
+    # RSpec's note that a file raised outside any example, such as at load.
+    RSPEC_OUTSIDE_ERROR = /errors? occurred outside of examples/
+    # ANSI colour codes, removed before matching so a coloured summary still counts.
+    ANSI_CODE = /\e\[[\d;]*m/
 
     # PATH entries that pin a concrete Ruby under a version manager (ahead of
     # shims). Optional trailing slash; normal bins are left alone.
@@ -72,8 +96,15 @@ module Mutineer
     # 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. Also sets +PARALLEL_WORKERS+ to 1 and
-    # +DISABLE_SPRING+ to 1. A wrapper that sets either variable again wins.
+    # still reaches the suite. Also sets +PARALLEL_WORKERS+, +DISABLE_SPRING+ and
+    # +DISABLE_BOOTSNAP_COMPILE_CACHE+ to 1. A wrapper can change them again.
+    # Bootsnap checks only that its variable is set, so only unsetting it turns
+    # the cache back on. The Bootsnap pin is here, not in
+    # {RailsRunEnv.pin_child!}: this backend rewrites each source file in place,
+    # and Bootsnap keys its compile cache on path, size and whole-second mtime,
+    # so a same-size mutant written in the same second can load the previous
+    # mutant's cached code (#285). The daemon loads each mutant from a new file
+    # and keeps the cache.
     #
     # @api private
     # @return [Hash{String => String, nil}] env for Process.spawn.
@@ -97,6 +128,7 @@ module Mutineer
              end
       env["PATH"] = path.join(File::PATH_SEPARATOR)
       RailsRunEnv.pin_child!(env, spring: true)
+      env["DISABLE_BOOTSNAP_COMPILE_CACHE"] = "1"
       env
     end
 
@@ -132,46 +164,142 @@ module Mutineer
     # @param files [Array<String>] test file paths.
     # @param timeout [Numeric] per-mutant wall-clock timeout in seconds.
     # @param verbose [Boolean] print the child's captured output on a non-pass.
+    # @param check_summary [Boolean] score exit 1 as killed only when the output
+    #   has a summary line that reports a failing test (see {failure_reported?}).
+    #   The runner turns this on when the clean smoke run printed a summary line.
     # @return [Mutineer::Result]
-    def self.run(command, files, timeout:, verbose: false)
+    def self.run(command, files, timeout:, verbose: false, check_summary: false)
       kind, code, output, = spawn_capture(command, files, timeout)
       case kind
       when :timeout
         # A timeout is the one non-pass we flag by default — a normal kill is also
         # a non-zero exit, so notifying on every non-zero would spam every kill.
         warn "[mutineer] test-command exceeded #{timeout}s and was killed (scored timeout)."
-        warn output if verbose && !output.empty?
+        warn Redaction.text(output) if verbose && !output.empty?
         Result.timeout
       else # :exited
         return Result.survived if code&.zero?
         # Signal death (nil exitstatus) is infrastructure, not a suite assertion
         # failure — match Isolation/daemon (error), do not inflate kill rate.
         if code.nil?
-          warn output if verbose && !output.empty?
+          warn Redaction.text(output) if verbose && !output.empty?
           return Result.error("test-command terminated by signal")
         end
 
-        warn output if verbose && !output.empty?
+        warn Redaction.text(output) if verbose && !output.empty?
         # 126 (cannot execute) and 127 (command not found) come from a wrapper
         # such as `bundle exec` that could not start the suite: no test ran.
         return Result.error("test-command could not start (exit #{code})") if CANNOT_RUN_CODES.include?(code)
 
+        text = summary_text(output)
+        # SimpleCov's minimum_coverage gate replaced the exit code. Under
+        # Minitest it runs in Minitest.after_run even after a failing test, so a
+        # failing summary plus its message is still a kill. A passing summary
+        # plus its message means no test caught the mutant: in process, the
+        # fork exits before that hook, and the mutant survives. Keyed on
+        # SimpleCov's own message, so code under test that calls `exit 2`
+        # still scores error. Ceiling: with `SimpleCov.print_error_status =
+        # false` the gate prints nothing, and its exit scores error too.
+        if text.match?(SIMPLECOV_GATE)
+          return Result.killed if failure_reported?(text)
+          return Result.survived if tests_passed?(text)
+        end
+
+        unless code == FAILURE_CODE
+          return Result.error("test-command exited #{code} (only exit 1 counts as a kill; " \
+                              "check RSpec --failure-exit-code, a coverage gate, or your wrapper)")
+        end
+
+        if check_summary && !failure_reported?(text) && !exited_during_tests?(text)
+          return Result.error("test-command exited 1 but its output shows no failing test " \
+                              "(the suite or the mutant crashed before tests ran; --verbose shows the output)")
+        end
+
         Result.killed
       end
     end
 
+    # True when the text has a Minitest or RSpec summary line.
+    #
+    # @api private
+    # @param text [String] output from {summary_text}.
+    # @return [Boolean]
+    def self.summary_line?(text)
+      text.match?(MINITEST_SUMMARY) || text.match?(RSPEC_SUMMARY)
+    end
+
+    # True when a summary line reports a failing test: a Minitest failure or
+    # error, or an RSpec failure. An RSpec error outside examples alone (a spec
+    # file that raised while loading) is not one, as in TestRunners::RSpec.
+    # Any matching line counts, so a wrapper that runs two suites still kills.
+    # A test that prints a fake summary line to stdout fools this check.
+    #
+    # @api private
+    # @param text [String] output from {summary_text}.
+    # @return [Boolean]
+    def self.failure_reported?(text)
+      text.scan(MINITEST_SUMMARY).any? { |failures, errors| (failures.to_i + errors.to_i).positive? } ||
+        text.scan(RSPEC_SUMMARY).any? { |(failures)| failures.to_i.positive? }
+    end
+
+    # True when Minitest started its tests and the process then ended with no
+    # summary line after that start: code under test called `exit 1` or
+    # `abort` mid-run. Only the last start counts, so a wrapper whose earlier
+    # suite printed a summary still kills. A load crash ends before Minitest
+    # prints {MINITEST_RUNNING}, so it stays false.
+    # Only the default Minitest reporter prints that line: under RSpec or
+    # minitest-reporters, such an exit scores error, not killed. Ceiling: an
+    # exception that escapes Minitest.run itself (a reporter plugin bug) also
+    # reads as a kill here, where the in-process backend scores error.
+    #
+    # @api private
+    # @param text [String] output from {summary_text}.
+    # @return [Boolean]
+    def self.exited_during_tests?(text)
+      running_at = text.rindex(MINITEST_RUNNING)
+      return false unless running_at
+
+      summary_at = [text.rindex(MINITEST_SUMMARY), text.rindex(RSPEC_SUMMARY)].compact.max
+      summary_at.nil? || summary_at < running_at
+    end
+
+    # True when a recognized summary line is present and none shows a failing
+    # test or an RSpec error outside examples. With no recognized summary line
+    # (a JUnit or custom reporter), it is false, so a SimpleCov gate exit there
+    # scores error rather than a survivor the output cannot prove.
+    #
+    # @api private
+    # @param text [String] output from {summary_text}.
+    # @return [Boolean]
+    def self.tests_passed?(text)
+      summary_line?(text) && !failure_reported?(text) && !text.match?(RSPEC_OUTSIDE_ERROR)
+    end
+
+    # The output as binary with ANSI colour codes removed. Binary, so bytes that
+    # are invalid in the default encoding (an unset locale) cannot raise.
+    # Computed once per run and passed to the predicates above.
+    #
+    # @api private
+    # @param output [String] captured child stdout+stderr.
+    # @return [String]
+    def self.summary_text(output)
+      output.b.gsub(ANSI_CODE, "")
+    end
+
     # Pre-flight: run the command once against the UNMUTATED tree. Green (exit 0)
-    # returns the elapsed seconds (used to calibrate the per-mutant timeout);
-    # anything else raises SmokeCheckError so the run aborts before scoring.
+    # returns the elapsed seconds (used to calibrate the per-mutant timeout) and
+    # whether the output has a Minitest or RSpec summary line (used to turn on
+    # the summary check in {run}); anything else raises SmokeCheckError so the
+    # run aborts before scoring.
     #
     # @param command [String] the --test-command template.
     # @param files [Array<String>] test file paths.
     # @param timeout [Numeric] ceiling for the calibration run.
-    # @return [Float] elapsed seconds of the clean run.
+    # @return [Array(Float, Boolean)] `[elapsed_seconds, summary_seen]`.
     # @raise [Mutineer::SmokeCheckError] when the clean suite is not green.
     def self.smoke_check!(command, files, timeout: SMOKE_TIMEOUT)
       kind, code, output, elapsed = spawn_capture(command, files, timeout)
-      return elapsed if kind == :exited && code&.zero?
+      return [elapsed, summary_line?(summary_text(output))] if kind == :exited && code&.zero?
 
       reason =
         if kind == :timeout then "did not finish within #{timeout}s"
@@ -213,7 +341,7 @@ module Mutineer
                "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)"
+               "(see https://github.com/davidteren/mutineer/blob/main/docs/rails-setup.md#apps-on-ruby--34, section Under a version manager)"
       parts
     end
 
@@ -245,7 +373,12 @@ module Mutineer
       kind, code = wait_with_timeout(pid, timeout)
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
       out.rewind
-      [kind, code, out.read, elapsed]
+      # Test output is arbitrary bytes. Read it as UTF-8 whatever the locale (#303).
+      # Each invalid byte becomes `\xNN`, as in Reporter#printable, so the
+      # smoke-failure checks can match on the text and nothing is lost.
+      output = out.read.force_encoding(Encoding::UTF_8)
+                  .scrub { |bytes| bytes.unpack("C*").map { |b| format("\\x%02X", b) }.join }
+      [kind, code, output, elapsed]
     ensure
       if out
         out.close

data/lib/mutineer/isolation.rb

@@ -7,6 +7,7 @@ require_relative "child_stdout"
 require_relative "child_coverage"
 require_relative "kill_channel"
 require_relative "concern_blocks"
+require_relative "redaction"
 
 module Mutineer
   # Fork-based isolation for running one mutant. The block runs in a child
@@ -66,7 +67,7 @@ module Mutineer
           code = e.status
         rescue Exception => e # rubocop:disable Lint/RescueException
           # STDERR, not `warn`: a test may have left `$stderr` as a StringIO.
-          STDERR.puts "[mutineer-child] #{e.class}: #{e.message}"
+          STDERR.puts "[mutineer-child] #{Redaction.describe(e)}"
           code = 2
         end
         STDERR.flush
@@ -138,9 +139,10 @@ module Mutineer
     #
     # The verdict matches a run without `--matrix`, which skips everything after
     # the first failing serial test except the code around it (see
-    # {KillChannel}). So when a serial test has named a kill and the child then
+    # {KillChannel}). So when a serial test has named a failure and the child then
     # ended inside a region that run would skip (an exit, a crash or the
-    # timeout in a later test, class or group), the mutant is `killed`: the
+    # timeout in a later test, class or group), its first failure decides:
+    # `error` for an unavailable database outcome, otherwise `killed`. The
     # plain run never reached that point. An end anywhere else keeps the exit
     # status, because the plain run reaches that code too: the rest of the
     # failing test's class wrapper or group hooks, or the suite hooks. A kill in
@@ -167,6 +169,7 @@ module Mutineer
       return result.with(kills: Kills.new(killed_by: [], ran: [], complete: false)) if report.invalid
 
       result = Result.killed if report.started && report.serial_kill && report.skipping.positive?
+      result = Result.error if report.started && report.serial_error && report.skipping.positive?
       agrees = result.killed? ? report.killed.any? : result.survived? && report.killed.empty?
       complete = finished && report.started && report.finished && report.lost.zero? && agrees
       result.with(kills: Kills.new(killed_by: report.killed, ran: report.ran, complete: complete))
@@ -189,17 +192,43 @@ module Mutineer
     #
     # A concern's stored `included` and `prepended` blocks from the source file
     # are forgotten around the load, so ActiveSupport accepts the blocks the
-    # temp file stores (#256).
+    # temp file stores (#256). For a def in such a block, the caller passes the
+    # text from {JobPlan.hook_mutant} and then calls
+    # {ConcernBlocks.place_hook_def} (#297).
     #
     # @api private
     # @param mutated [String] mutated source text.
     # @param source_file [String] original source file path.
     # @return [Object] whatever `load` returns.
     def self.apply_whole_file(mutated, source_file)
-      Tempfile.create([".mutineer_mutant", ".rb"], File.dirname(File.expand_path(source_file))) do |f|
-        f.write(mutated)
+      write_beside(mutated, source_file) { |path| ConcernBlocks.replace(source_file) { load path } }
+    end
+
+    # Writes `code` to a hidden `.mutineer_mutant` file beside `source_file`,
+    # yields its path, and removes it after the block. Both strategies write
+    # through here. Only redefine enables the system-temp fallback when the
+    # source directory is not writable.
+    #
+    # The file is locked until the block ends, as the daemon locks its own file
+    # (#295). A SIGKILL drops the lock too. The pid in the name and the lock
+    # tell another run's sweep that the file is in use, so the sweep does not
+    # delete it between the write and the `load`.
+    #
+    # @api private
+    # @param code [String] the Ruby source to write.
+    # @param source_file [String] the source file the code replaces.
+    # @param fallback [Boolean] use the system temp directory when the source
+    #   directory is not writable; redefine only.
+    # @yieldparam path [String] absolute path of the written file.
+    # @return [Object] whatever the block returns.
+    def self.write_beside(code, source_file, fallback: false)
+      dir = File.dirname(File.expand_path(source_file))
+      dir = Dir.tmpdir if fallback && !File.writable?(dir)
+      Tempfile.create([".mutineer_mutant", ".rb"], dir) do |f|
+        f.flock(File::LOCK_EX) rescue nil # rubocop:disable Style/RescueModifier
+        f.write(code)
         f.flush
-        ConcernBlocks.replace(source_file) { load f.path }
+        yield f.path
       end
     end
 
@@ -218,13 +247,6 @@ module Mutineer
     # @param source [String] full source text.
     # @return [Object] whatever `load` returns.
     def self.apply_surgical(mutation, subject, source)
-      loc = subject.def_node.location
-      def_start = loc.start_offset
-      snippet = source.byteslice(def_start...loc.end_offset)
-      rel_s = mutation.start_offset - def_start
-      rel_e = mutation.end_offset - def_start
-      mutated_def = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..)
-
       # Rebuild the FULL namespace nesting textually so unqualified enclosing-
       # namespace constants resolve exactly as the reload strategy would. A
       # bare redefinition on the owner would collapse Module.nesting to [owner]
@@ -240,12 +262,7 @@ module Mutineer
       # falsely survives. Re-open the singleton class so the redefinition lands on
       # the same method the test calls. `def self.foo` already carries its
       # receiver, so it is left as-is (wrapping it would mis-target).
-      inner =
-        if subject.singleton && subject.def_node.receiver.nil?
-          "class << self\n#{mutated_def}\nend"
-        else
-          mutated_def
-        end
+      inner = mutated_def(mutation, subject, source)
       inner = "#{subject.block_owner}.class_eval do\n#{inner}\nend" if subject.block_owner
       wrapped = "#{prefix}#{inner}#{"\nend" * keywords.size}"
 
@@ -267,15 +284,40 @@ module Mutineer
       # Module.nesting identically, with no dynamic string execution for
       # scanners to flag. The input is the project's OWN source (the enclosing
       # method, textually mutated), loaded only in this forked child.
-      Tempfile.create(["mutineer_surgical", ".rb"]) do |f|
-        f.write(wrapped)
-        f.flush
-        load f.path
-      end
+      #
+      # The file sits beside the source, as in apply_whole_file, so `__dir__`
+      # and `require_relative` in the method resolve against its real
+      # neighbours (#279). In the temp dir they raise ENOENT or LoadError, and
+      # every mutant of the method dies whatever it changes. The hidden
+      # `.mutineer_mutant` name keeps Zeitwerk away (#253) and lets the parent
+      # sweep an orphan after a timeout kill.
+      #
+      # A read-only source dir keeps the 1.x system-temp location, so redefine
+      # still runs there (only path-relative methods mis-score, as before: #339).
+      write_beside(wrapped, subject.file, fallback: true) { |path| load path }
 
       target.send(vis, subject.name) if vis && vis != :public
     end
 
+    # The enclosing def with the mutation applied, wrapped in `class << self`
+    # for a singleton def with no receiver (#20). Pure text: it reads no live
+    # module, so the tool process can call it too ({JobPlan.hook_mutant}).
+    #
+    # @api private
+    # @param mutation [Mutineer::Mutation] mutation to apply.
+    # @param subject [Mutineer::Subject] subject being mutated.
+    # @param source [String] full source text.
+    # @return [String] the mutated def.
+    def self.mutated_def(mutation, subject, source)
+      loc = subject.def_node.location
+      def_start = loc.start_offset
+      snippet = source.byteslice(def_start...loc.end_offset)
+      rel_s = mutation.start_offset - def_start
+      rel_e = mutation.end_offset - def_start
+      mutated = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..)
+      subject.singleton && subject.def_node.receiver.nil? ? "class << self\n#{mutated}\nend" : mutated
+    end
+
     # Resolve each namespace ELEMENT to its live Module and pick the correct
     # keyword (reopening a class with `module` — or vice versa — raises
     # TypeError), so the textual wrapper matches the real definitions.