evilution 0.22.1 → 0.22.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41de783fc5459691618f0638cbbe4d47b4f41173b38ffaa357ad00f51831724d
-  data.tar.gz: 5db9acf814e90669a1d2596b29b71f72e405328b28354f82121bcc23f0ad1a90
+  metadata.gz: 05657264e506e5a6b5041d68b5eb46bfcbbf9a17780caeb3c44feaf5f5d18794
+  data.tar.gz: a7e6333fc26d21799b3807d3fbc2758ae54e00de2c7f1028e5ad30cf8777e8d2
 SHA512:
-  metadata.gz: 4ed3a8f8c3ce59bcb13e18c115c7a1013e2aaa53aab8672e486ff0ef1abe6857b3771628f0f4d8f2c7925c46610c4be315f9c2b13bc60d124e44cf69773b1100
-  data.tar.gz: e77b777bbb7030ce89904e504a118adbffe7e7a991f8bc5f9504097b7becc311f3b93676bb0914b5ab5b4155d061448ca387025e86a785b1cbb31ed4e69f1f73
+  metadata.gz: 8d791eba8e795dcaa34c6ff3cc82a4b9653cfc282fcff1f7a75911bdfbd192689d21324ad793077700644a497c8320b2fb77e874bff63cd98c1a788390a27309
+  data.tar.gz: 5ee22113b3b0343c60c08ca4c4c4160492617827376c783fbe0052d5a5a59ab37199fc16de349502c6c7d26f2c64814abf7ad31228e325dcdc1be86e1a7930d7

data/.beads/interactions.jsonl

@@ -14,3 +14,6 @@
 {"id":"int-3a6ffc92","kind":"field_change","created_at":"2026-04-10T10:26:29.483210031Z","actor":"Denis Kiselev","issue_id":"EV-sgsb","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #656"}}
 {"id":"int-1df69312","kind":"field_change","created_at":"2026-04-10T10:40:18.391377715Z","actor":"Denis Kiselev","issue_id":"EV-1l8w","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged"}}
 {"id":"int-427bdc14","kind":"field_change","created_at":"2026-04-10T12:40:12.974701482Z","actor":"Denis Kiselev","issue_id":"EV-k6cz","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged as PR #659 — capture error_class and error_backtrace in MutationResult, thread through isolators + runner + JSON reporter, log in --verbose"}}
+{"id":"int-d3431bcd","kind":"field_change","created_at":"2026-04-12T02:57:43.902279367Z","actor":"Denis Kiselev","issue_id":"EV-86l6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-f409d79d","kind":"field_change","created_at":"2026-04-12T02:57:44.180309214Z","actor":"Denis Kiselev","issue_id":"EV-o28o","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-ba5d5d3e","kind":"field_change","created_at":"2026-04-12T03:42:58.408103757Z","actor":"Denis Kiselev","issue_id":"EV-1fq8","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.22.3] - 2026-04-12
+
+### Fixed
+
+- **`LoadError: cannot load such file -- spec_helper`** — projects with `--require spec_helper` in `.rspec` failed on every mutation because `spec/` was not on `$LOAD_PATH`; RSpec's CLI normally adds it, but evilution calls `RSpec::Core::Runner.run` directly, bypassing the CLI; now adds `spec/` to `$LOAD_PATH` in both `ensure_framework_loaded` and `baseline_runner` (#669)
+
+## [0.22.2] - 2026-04-12
+
+### Added
+
+- **Rails-aware isolation auto-selection** — `isolation: :auto` (the default) now detects Rails projects by walking up from target files looking for `config/application.rb`; when Rails is detected, isolation resolves to `:fork` instead of `:in_process`, preventing indefinite hangs caused by Rails' `Thread.handle_interrupt(Exception => :never)` masking `Timeout.timeout`'s `Thread#raise` (#662, #663, PR #665)
+- **Parent-process preload for fork isolation** — new `--preload FILE` / `--no-preload` CLI flags and `preload:` config key; when fork isolation is active on a Rails project, evilution auto-detects and preloads `spec/rails_helper.rb` or `test/test_helper.rb` in the parent process so forked children inherit the loaded framework via copy-on-write, eliminating per-mutation Rails boot cost (#662, PR #665)
+- **`Evilution::RailsDetector` module** — lightweight filesystem-only detection of Rails roots with memoized cache and thread-safe mutex; used by both isolation resolution and preload auto-detection (#662, PR #665)
+- **Isolation strategy documentation** — `docs/isolation.md` explains the three strategies, the `handle_interrupt` hazard, and preload configuration (#662, PR #665)
+
+### Fixed
+
+- **`run_mutations_parallel` ignoring `--isolation`** — parallel mode hardcoded `Isolation::InProcess.new` for its worker isolator, silently overriding `config.isolation`; now uses `build_isolator` so `--jobs N --isolation fork` correctly uses fork per-mutation inside workers (#663, PR #665)
+- **Rails detection failing for auto-resolved targets** — `detected_rails_root` used `config.target_files` which is empty in git-changed or source-glob modes; now uses memoized `resolve_target_files` so Rails is detected regardless of how targets were specified (PR #665)
+- **`SyntaxError` in preload file escaping rescue** — `perform_preload` rescued `LoadError, StandardError` but `SyntaxError` is a `ScriptError` (not `StandardError`); now rescues `ScriptError, StandardError` (PR #665)
+- **Isolator built eagerly before targets resolved** — `build_isolator` ran in `initialize` before `resolve_target_files`; now lazy-initialized on first use, ensuring Rails detection has resolved targets available (PR #665)
+
+### Changed
+
+- **Isolation warning for explicit `in_process` under Rails** — when a user explicitly passes `--isolation in_process` on a detected Rails project, evilution emits a one-shot stderr warning about the `handle_interrupt` hang hazard and proceeds; suppressed by `--quiet` (#662, PR #665)
+
 ## [0.22.1] - 2026-04-10
 
 ### Added

data/README.md

@@ -64,6 +64,9 @@ evilution [command] [options] [files...]
 | `--incremental`              | Boolean | false        | Cache killed/timeout results; skip unchanged mutations on re-runs. |
 | `--save-session`             | Boolean | false        | Persist results as timestamped JSON under `.evilution/results/`. |
 | `--no-progress`              | Boolean | _(enabled)_  | Disable the TTY progress bar.                      |
+| `--isolation MODE`           | String  | `auto`       | Isolation strategy: `auto`, `fork`, or `in_process`. `auto` selects `fork` for Rails projects. See [docs/isolation.md](docs/isolation.md). |
+| `--preload FILE`             | String  | _(auto)_     | File to require in parent before forking workers (e.g. `spec/rails_helper.rb`). Auto-detected for Rails. |
+| `--no-preload`               | Boolean | _(enabled)_  | Disable parent-process preload.                     |
 | `--skip-heredoc-literals`    | Boolean | false        | Skip all string literal mutations inside heredocs.  |
 | `--show-disabled`            | Boolean | false        | Report mutations skipped by `# evilution:disable` comments. |
 | `--baseline-session PATH`    | String  | _(none)_     | Saved session file for HTML report comparison.     |
@@ -90,6 +93,8 @@ Creates `.evilution.yml`:
 # integration: rspec       # test framework: rspec, minitest
 # suggest_tests: false     # concrete test code in suggestions (matches integration)
 # save_session: false      # persist results under .evilution/results/
+# isolation: auto          # auto | fork | in_process (auto selects fork for Rails)
+# preload: null            # path to preload before forking; false to disable; auto-detects for Rails
 # skip_heredoc_literals: false  # skip all string literal mutations inside heredocs
 # show_disabled: false     # report mutations skipped by disable comments
 # baseline_session: null   # path to session file for HTML comparison
@@ -405,7 +410,7 @@ Tests 4 paths (InProcess isolation, Fork isolation, mutation generation + stripp
 2. **Extract** — Methods are identified as mutation subjects
 3. **Filter** — Disable comments, Sorbet `sig` blocks, and AST ignore patterns exclude mutations before execution
 4. **Mutate** — 72 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default
-5. **Isolate** — Mutations are applied to temporary file copies (never modifying originals); load-path redirection ensures `require` resolves the mutated copy. Default isolation is in-process; `--isolation fork` uses forked child processes. Parallel mode (`--jobs N`) always uses in-process isolation inside pool workers to avoid double forking
+5. **Isolate** — Mutations are applied to temporary file copies (never modifying originals); load-path redirection ensures `require` resolves the mutated copy. Default isolation is in-process for plain Ruby projects and fork for Rails projects (auto-detected); `--isolation fork` forces forked child processes. Both sequential and parallel (`--jobs N`) modes respect the configured isolation strategy
 6. **Test** — The configured test framework (RSpec or Minitest) executes against the mutated source
 7. **Collect** — Source strings and AST nodes are released after use to minimize memory retention
 8. **Report** — Results aggregated into text, JSON, or HTML, including efficiency metrics and peak memory usage

data/docs/isolation.md

@@ -0,0 +1,115 @@
+# Isolation strategies
+
+Evilution runs every mutant inside an isolated environment so a misbehaving
+mutant cannot corrupt the runner's state or the surrounding test suite. The
+`--isolation` flag (and the `isolation:` config key) selects which strategy
+is used.
+
+## Strategies
+
+| Strategy     | What it does                                                           | When to use                                                |
+| ------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `auto`       | Default. Picks `fork` for Rails projects, `in_process` otherwise.      | Leave this on unless you have a specific reason to change. |
+| `fork`       | Forks a fresh child process per mutant. Parent `SIGKILL`s on timeout.  | Rails / ActiveRecord projects; any code that uses mutexes, monitors, or async-interrupt masks. |
+| `in_process` | Runs the mutant inside the runner process under `Timeout.timeout`.     | Pure-Ruby libraries that do not use async-interrupt masks. |
+
+## Why fork is the default for Rails projects
+
+Rails wraps every ActiveRecord transaction in
+`Thread.handle_interrupt(Exception => :never)` to guarantee that a transaction
+either commits cleanly or rolls back cleanly — it must never exit the
+transaction block with a half-delivered exception. The mask is
+[load-bearing for transaction correctness][rails-handle-interrupt].
+
+That mask interacts badly with `Timeout.timeout`. The Timeout gem schedules a
+timer thread which fires `Thread#raise Timeout::Error` at the main thread when
+the deadline hits. Ruby receives the `raise`, inspects the interrupt mask, sees
+`Exception => :never`, and **queues the exception for later delivery** — "later"
+meaning "when the masked block exits". If the mutant is stuck in an infinite
+loop inside the transaction, the block never exits, the queued exception is
+never delivered, and the runner hangs indefinitely.
+
+This is not a bug in Timeout or in Rails. Each component is correct in
+isolation. They simply do not compose for in-process timeout-based
+cancellation. The only primitive that can escape a masked-interrupt section
+in the same thread is an out-of-band kernel signal — `SIGKILL` from another
+process. That is exactly what the `fork` strategy provides.
+
+Because of this, `auto` resolves to `fork` whenever the target files live
+under a detected Rails root (i.e. a directory containing
+`config/application.rb`). If you explicitly pass `--isolation in_process` on
+a Rails project, evilution emits a warning naming the hazard and proceeds
+anyway — sometimes you know the code under test never enters a masked
+section, and that is your call to make.
+
+The same hazard applies to any Ruby code that uses
+`Thread.handle_interrupt(... => :never)`: `Mutex#synchronize`, `Monitor#synchronize`,
+`Queue`, `ActiveSupport::Notifications::Fanout` listeners, and custom cleanup
+blocks that wrap "must complete" sections. If your target code can touch any
+of those, prefer `--isolation fork`.
+
+## Parent-process preload
+
+Fork isolation's one downside is that every child pays the cost of loading
+its test framework from scratch. For a Rails app, that is 5–15 seconds of
+`require "rails/all"` per mutant — multiplied by hundreds of mutants, the
+run takes hours.
+
+To avoid that cost, evilution preloads a bootstrap file in the **parent**
+process before the mutation loop begins. Once Rails is loaded in the parent,
+every forked child inherits the loaded state via copy-on-write, and the child
+runs its test near-instantly against an already-loaded framework.
+
+### Automatic preload
+
+For Rails projects (auto-detected via `config/application.rb`), evilution
+automatically looks for these files in order and preloads the first one it
+finds:
+
+1. `spec/rails_helper.rb` (RSpec)
+2. `test/test_helper.rb` (Minitest)
+
+No configuration needed.
+
+### Explicit preload
+
+Override the auto-detected path with the `--preload` flag or the `preload:`
+config key:
+
+```bash
+bundle exec evilution run app/models/user.rb --preload config/evilution_boot.rb
+```
+
+```yaml
+# .evilution.yml
+preload: config/evilution_boot.rb
+```
+
+The path is resolved relative to the working directory. Preload failures
+(the file does not exist, or it raises during `require`) are fatal —
+evilution aborts with an `Evilution::ConfigError` that includes the original
+exception.
+
+### Disabling preload
+
+Pass `--no-preload` on the CLI or set `preload: false` in `.evilution.yml`:
+
+```bash
+bundle exec evilution run app/models/user.rb --no-preload
+```
+
+The MCP tool (`evilution-mutate`) disables preload unconditionally, because
+the MCP server is a long-lived process that handles runs from different
+projects — preloading one project's Rails stack into a shared process would
+poison subsequent runs.
+
+## Related flags
+
+- `--timeout N` sets the per-mutation time limit. Under `fork`, this drives
+  SIGKILL. Under `in_process`, this drives `Timeout.timeout` and is subject
+  to the interrupt-mask hazard described above.
+- `--jobs N` runs N workers in parallel. The parallel pool respects the
+  configured isolation strategy, so `--jobs 4 --isolation fork` uses fork
+  isolation per-mutation inside each worker.
+
+[rails-handle-interrupt]: https://github.com/rails/rails/blob/main/activesupport/lib/active_support/concurrency/thread_monitor.rb

data/lib/evilution/cli.rb

@@ -249,6 +249,9 @@ class Evilution::CLI
     opts.on("--incremental", "Cache killed/timeout results; skip re-running them on unchanged files") { @options[:incremental] = true }
     opts.on("--integration NAME", "Test integration: rspec, minitest (default: rspec)") { |i| @options[:integration] = i }
     opts.on("--isolation STRATEGY", "Isolation: auto, fork, in_process (default: auto)") { |s| @options[:isolation] = s }
+    opts.on("--preload FILE", "Preload FILE in the parent process before forking " \
+                              "(default: auto-detect spec/rails_helper.rb for Rails projects)") { |f| @options[:preload] = f }
+    opts.on("--no-preload", "Disable parent-process preload even for Rails projects") { @options[:preload] = false }
     opts.on("--stdin", "Read target file paths from stdin (one per line)") { @options[:stdin] = true }
     opts.on("--suggest-tests", "Generate concrete test code in suggestions (RSpec or Minitest)") { @options[:suggest_tests] = true }
     opts.on("--no-progress", "Disable progress bar") { @options[:progress] = false }

data/lib/evilution/config.rb

@@ -26,7 +26,8 @@ class Evilution::Config
     ignore_patterns: [],
     show_disabled: false,
     baseline_session: nil,
-    skip_heredoc_literals: false
+    skip_heredoc_literals: false,
+    preload: nil
   }.freeze
 
   attr_reader :target_files, :timeout, :format,
@@ -34,7 +35,7 @@ class Evilution::Config
               :jobs, :fail_fast, :baseline, :isolation, :incremental, :suggest_tests,
               :progress, :save_session, :line_ranges, :spec_files, :hooks,
               :ignore_patterns, :show_disabled, :baseline_session,
-              :skip_heredoc_literals
+              :skip_heredoc_literals, :preload
 
   def initialize(**options)
     file_options = options.delete(:skip_config_file) ? {} : load_config_file
@@ -140,6 +141,11 @@ class Evilution::Config
       # Skip all string literal mutations inside heredocs (default: false)
       # skip_heredoc_literals: false
 
+      # Preload file required in the parent process before forking workers.
+      # For Rails projects, spec/rails_helper.rb or test/test_helper.rb is
+      # auto-detected when isolation resolves to :fork. Set to false to disable.
+      # preload: spec/rails_helper.rb # or test/test_helper.rb
+
       # Hooks: Ruby files returning a Proc, keyed by lifecycle event
       # hooks:
       #   worker_process_start: config/evilution_hooks/worker_start.rb
@@ -190,6 +196,15 @@ class Evilution::Config
     @baseline_session = merged[:baseline_session]
     @skip_heredoc_literals = merged[:skip_heredoc_literals]
     @hooks = validate_hooks(merged[:hooks])
+    @preload = validate_preload(merged[:preload])
+  end
+
+  def validate_preload(value)
+    return nil if value.nil?
+    return false if value == false
+    return value if value.is_a?(String)
+
+    raise Evilution::ConfigError, "preload must be nil, false, or a String path, got #{value.inspect}"
   end
 
   def validate_integration(value)

data/lib/evilution/integration/rspec.rb

@@ -12,6 +12,8 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
   def self.baseline_runner
     lambda { |spec_file|
       require "rspec/core"
+      spec_dir = File.expand_path("spec")
+      $LOAD_PATH.unshift(spec_dir) unless $LOAD_PATH.include?(spec_dir)
       ::RSpec.reset
       status = ::RSpec::Core::Runner.run(
         ["--format", "progress", "--no-color", "--order", "defined", spec_file]
@@ -43,6 +45,7 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
 
     fire_hook(:setup_integration_pre, integration: :rspec)
     require "rspec/core"
+    add_spec_load_path
     Evilution::Integration::CrashDetector.register_with_rspec
     @rspec_loaded = true
     fire_hook(:setup_integration_post, integration: :rspec)
@@ -163,4 +166,12 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     warn "[evilution] No matching spec found for #{file_path}, running full suite. " \
          "Use --spec to specify the spec file."
   end
+
+  # RSpec's CLI adds spec/ to $LOAD_PATH so that `--require spec_helper`
+  # (commonly in .rspec) resolves. We call Runner.run directly, bypassing
+  # the CLI, so we must replicate this.
+  def add_spec_load_path
+    spec_dir = File.expand_path("spec")
+    $LOAD_PATH.unshift(spec_dir) unless $LOAD_PATH.include?(spec_dir)
+  end
 end

data/lib/evilution/mcp/mutate_tool.rb

@@ -111,7 +111,11 @@ class Evilution::MCP::MutateTool < MCP::Tool
     end
 
     def build_config_opts(files, line_ranges, target, timeout, jobs, fail_fast, spec, suggest_tests)
-      opts = { target_files: files, line_ranges: line_ranges, format: :json, quiet: true, skip_config_file: true }
+      # Preload is disabled for MCP invocations: `require`-ing Rails into the
+      # long-lived MCP server would poison subsequent runs against other
+      # projects. MCP users who want the speedup should use the CLI.
+      opts = { target_files: files, line_ranges: line_ranges, format: :json, quiet: true, skip_config_file: true,
+               preload: false }
       opts[:target] = target if target
       opts[:timeout] = timeout if timeout
       opts[:jobs] = jobs if jobs

data/lib/evilution/rails_detector.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Evilution::RailsDetector
+  MARKER = File.join("config", "application.rb").freeze
+
+  @cache = {}
+  @mutex = Mutex.new
+
+  class << self
+    def rails_root_for(path)
+      return nil if path.nil?
+
+      dir = starting_dir(path)
+      return nil if dir.nil?
+
+      @mutex.synchronize do
+        return @cache[dir] if @cache.key?(dir)
+
+        @cache[dir] = walk_up(dir)
+      end
+    end
+
+    def rails_root_for_any(paths)
+      Array(paths).each do |path|
+        root = rails_root_for(path)
+        return root if root
+      end
+      nil
+    end
+
+    def reset_cache!
+      @mutex.synchronize { @cache.clear }
+    end
+
+    private
+
+    def starting_dir(path)
+      return File.expand_path(path) if File.directory?(path)
+      return File.expand_path(File.dirname(path)) if File.file?(path)
+
+      parent = File.expand_path(File.dirname(path))
+      File.directory?(parent) ? parent : nil
+    end
+
+    def walk_up(dir)
+      current = dir
+      loop do
+        return current if File.file?(File.join(current, MARKER))
+
+        parent = File.dirname(current)
+        return nil if parent == current
+
+        current = parent
+      end
+    end
+  end
+end

data/lib/evilution/runner.rb

@@ -25,6 +25,7 @@ require_relative "ast/pattern/filter"
 require_relative "temp_dir_tracker"
 require_relative "disable_comment"
 require_relative "ast/sorbet_sig_detector"
+require_relative "rails_detector"
 
 class Evilution::Runner
   INTEGRATIONS = {
@@ -32,6 +33,11 @@ class Evilution::Runner
     minitest: Evilution::Integration::Minitest
   }.freeze
 
+  PRELOAD_CANDIDATES = [
+    File.join("spec", "rails_helper.rb"),
+    File.join("test", "test_helper.rb")
+  ].freeze
+
   attr_reader :config
 
   def initialize(config: Evilution::Config.new, on_result: nil, hooks: nil)
@@ -40,7 +46,6 @@ class Evilution::Runner
     @hooks = hooks
     @parser = Evilution::AST::Parser.new
     @registry = Evilution::Mutator::Registry.default
-    @isolator = build_isolator
     @cache = config.incremental? ? Evilution::Cache.new : nil
     @disable_detector = Evilution::DisableComment.new
     @disabled_ranges_cache = {}
@@ -55,6 +60,9 @@ class Evilution::Runner
     subjects = parse_and_filter_subjects
     log_memory("after parse_subjects", "#{subjects.length} subjects")
 
+    perform_preload
+    log_memory("after preload") if rails_root_detected?
+
     baseline_result = run_baseline(subjects)
 
     mutations, skipped_count, disabled_mutations = generate_mutations(subjects)
@@ -89,7 +97,11 @@ class Evilution::Runner
 
   private
 
-  attr_reader :parser, :registry, :isolator, :cache, :on_result, :hooks, :disable_detector, :sig_detector
+  attr_reader :parser, :registry, :cache, :on_result, :hooks, :disable_detector, :sig_detector
+
+  def isolator
+    @isolator ||= build_isolator
+  end
 
   def parse_subjects
     files = resolve_target_files
@@ -97,10 +109,13 @@ class Evilution::Runner
   end
 
   def resolve_target_files
-    return resolve_source_glob if source_glob_target?
-    return config.target_files unless config.target_files.empty?
-
-    Evilution::Git::ChangedFiles.new.call
+    @resolve_target_files ||= if source_glob_target?
+                                resolve_source_glob
+                              elsif !config.target_files.empty?
+                                config.target_files
+                              else
+                                Evilution::Git::ChangedFiles.new.call
+                              end
   end
 
   def source_glob_target?
@@ -340,7 +355,7 @@ class Evilution::Runner
   def run_mutations_parallel(mutations, baseline_result = nil)
     integration = build_integration
     pool = Evilution::Parallel::Pool.new(size: config.jobs, hooks: @hooks, item_timeout: config.timeout ? config.timeout * 2 : nil)
-    worker_isolator = Evilution::Isolation::InProcess.new
+    worker_isolator = build_isolator
     spec_resolver = baseline_result&.failed? ? build_neutralization_resolver : nil
     state = { results: [], survived_count: 0, truncated: false, completed: 0 }
 
@@ -483,9 +498,80 @@ class Evilution::Runner
   end
 
   def resolve_isolation
-    return :fork if config.isolation == :fork
+    case config.isolation
+    when :fork
+      :fork
+    when :in_process
+      warn_in_process_under_rails if rails_root_detected?
+      :in_process
+    else # :auto
+      rails_root_detected? ? :fork : :in_process
+    end
+  end
+
+  def rails_root_detected?
+    return @rails_root_detected if defined?(@rails_root_detected)
+
+    @rails_root_detected = !detected_rails_root.nil?
+  end
+
+  def detected_rails_root
+    return @detected_rails_root if defined?(@detected_rails_root)
+
+    @detected_rails_root = Evilution::RailsDetector.rails_root_for_any(resolve_target_files)
+  end
+
+  def perform_preload
+    return if config.preload == false
+    return unless resolve_isolation == :fork
 
-    :in_process
+    path = resolve_preload_path
+    return unless path
+
+    require File.expand_path(path)
+  rescue ScriptError, StandardError => e
+    raise Evilution::ConfigError.new(
+      "failed to preload #{path.inspect}: #{e.class}: #{e.message}",
+      file: path
+    )
+  end
+
+  def resolve_preload_path
+    if config.preload.is_a?(String)
+      unless File.file?(config.preload)
+        raise Evilution::ConfigError.new(
+          "preload file not found: #{config.preload.inspect}",
+          file: config.preload
+        )
+      end
+      return config.preload
+    end
+
+    root = detected_rails_root
+    return nil unless root
+
+    PRELOAD_CANDIDATES.each do |rel|
+      abs = File.join(root, rel)
+      return abs if File.file?(abs)
+    end
+    nil
+  end
+
+  # When the user explicitly requests InProcess on a Rails project, warn once
+  # per run. Rails wraps ActiveRecord transactions in
+  # Thread.handle_interrupt(Exception => :never), which defers Timeout's
+  # Thread#raise indefinitely — making InProcess unable to kill runaway mutants.
+  def warn_in_process_under_rails
+    return if config.quiet
+    return if @warned_in_process_under_rails
+
+    @warned_in_process_under_rails = true
+    $stderr.write(
+      "[evilution] warning: --isolation in_process is unsafe on Rails projects. " \
+      "ActiveRecord wraps transactions in Thread.handle_interrupt(Exception => :never), " \
+      "which swallows Timeout.timeout and can cause evilution to hang indefinitely on " \
+      "mutants that introduce infinite loops. Use --isolation fork for reliable interruption.\n"
+    )
   end
 
   def resolve_integration_class

data/lib/evilution/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Evilution
-  VERSION = "0.22.1"
+  VERSION = "0.22.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.22.1
+  version: 0.22.3
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+date: 2026-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -81,6 +81,7 @@ files:
 - comparison_results/operator_classification.md
 - comparison_results/operator_prioritization.md
 - docs/ast_pattern_syntax.md
+- docs/isolation.md
 - docs/mutation_density_benchmark.md
 - exe/evilution
 - lib/evilution.rb
@@ -210,6 +211,7 @@ files:
 - lib/evilution/parallel.rb
 - lib/evilution/parallel/pool.rb
 - lib/evilution/parallel/work_queue.rb
+- lib/evilution/rails_detector.rb
 - lib/evilution/related_spec_heuristic.rb
 - lib/evilution/reporter.rb
 - lib/evilution/reporter/cli.rb