evilution 0.22.0 → 0.22.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc78bc7bc68c4d25a6b260b62a83a304d617905187e0b06ca6d0bc050be86403
-  data.tar.gz: 0a98e06dfc6ee9c4f0830b5a85346a95bf8de07d6aa9f3c49326077f7e2a8d44
+  metadata.gz: 2a90c882fed4185cf1514efbe1c560e05555efa19a749201e81d9287a65fefef
+  data.tar.gz: e5c02c5da957d3f9a647fd592b91c4ef82925020d5bb73bd0cde480c1435b26e
 SHA512:
-  metadata.gz: a8d67fc09591e0bee7395498d41c347aa907bd061831ef2ff83765bb0f143f577b8070b217193ffcfe23bff2a221b85f23b644cb15f3732f9aaf0069c6e369b1
-  data.tar.gz: c13839cac96e37075a5f2fa4cd82d2d2ca8116ef058d3ad8cbca6b4716bb0239d4e60553100d7c1d36fb05205deb0415b5f91a855319cd55a979fcad49736ec4
+  metadata.gz: db0a7c3ac58823326a8fc9d23b41dc928d8b1e45f7230c0c18dcdab133a9ec355d25f9303180043d41e9926387d90335920196b9d8651d0040eedb2982fd3b8c
+  data.tar.gz: 4a5b241452977ddd620ff4a082013b5ebcb2da3860579349ac58a8ac908d15a09862496e5418038eee52327aa46ccd1aac88ce21bb7d7cd2b7f3f931f2750e0f

data/.beads/interactions.jsonl

@@ -10,3 +10,9 @@
 {"id":"int-0f073191","kind":"field_change","created_at":"2026-04-09T13:03:11.468115004Z","actor":"Denis Kiselev","issue_id":"EV-85","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
 {"id":"int-91a9616c","kind":"field_change","created_at":"2026-04-09T13:04:05.459458165Z","actor":"Denis Kiselev","issue_id":"EV-69","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
 {"id":"int-b4fe2b7b","kind":"field_change","created_at":"2026-04-09T13:42:59.996305852Z","actor":"Denis Kiselev","issue_id":"EV-277","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-6671aef1","kind":"field_change","created_at":"2026-04-10T09:05:06.955840839Z","actor":"Denis Kiselev","issue_id":"EV-z42m","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #655"}}
+{"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"}}

data/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true
+  }
+}

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [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
+
+- **Error class and backtrace capture** — `MutationResult` now stores `error_class` and `error_backtrace` alongside `error_message`; the backtrace array is duplicated and frozen to keep results immutable; both fields are threaded through `Isolation::Fork` (Marshal-safe across the IPC pipe), `Isolation::InProcess`, and the runner's `compact_result` / `rebuild_results` path (#648, PR #659)
+- **Verbose error diagnostics** — `--verbose` now logs error class, message, and the first 5 backtrace lines for errored mutations (previously `--verbose` only showed memory/GC stats, leaving errors invisible) (#648, PR #659)
+- **Error details in JSON reports** — JSON reporter output includes `error_class` and `error_backtrace` fields under `errors[]` entries when present, so downstream tools (CI, MCP consumers) can surface failure causes without re-running (#648, PR #659)
+
+### Fixed
+
+- **Silent load-time crashes in `Isolation::Fork`** — mutations that raised non-`SyntaxError` script errors at load time (e.g. `NoMethodError: super called outside of method`) escaped `Integration::Base`'s narrow rescue and either surfaced cryptically or went silent under fork isolation; both isolators now rescue `ScriptError, StandardError` as a safety net and report them as `:error` status with full class and backtrace (#646, PR #656)
+- **`symbol_literal` operator breaking keyword arguments** — mutating symbols in label form (`foo:` inside hash literals or keyword arguments) produced invalid Ruby source; the operator now detects label-form symbols via Prism's `closing_loc` and skips them, only mutating standalone symbol literals (`:foo`) (#647, PR #657)
+- **Syntax errors in mutated source crashing in-process runs** — `Integration::Base#apply_mutation` now captures `SyntaxError` during `require`/`load` and returns a structured error result instead of propagating the exception up through `call`; error results include the error class and backtrace for diagnosis (#644, #645, PR #653, PR #655)
+
+### Changed
+
+- **Integration::Base refactor** — `apply_mutation` split into `apply_via_require` and `apply_via_load` helpers; rescue scope moved from `#call` to `#apply_mutation` so load-time errors return a result hash while abstract-method `NotImplementedError`s still propagate as intended
+
 ## [0.22.0] - 2026-04-09
 
 ### Added

data/README.md

@@ -56,7 +56,7 @@ evilution [command] [options] [files...]
 | `-j`, `--jobs N`             | Integer | 1            | Number of parallel workers. Uses demand-driven work distribution with pipe-based IPC. |
 | `--no-baseline`              | Boolean | _(enabled)_  | Skip baseline test suite check. By default, a baseline run detects pre-existing failures and marks those mutations as `neutral`. |
 | `--fail-fast [N]`            | Integer | _(none)_     | Stop after N surviving mutants (default 1 if no value given). |
-| `-v`, `--verbose`            | Boolean | false        | Verbose output with RSS memory and GC stats per phase and per mutation. |
+| `-v`, `--verbose`            | Boolean | false        | Verbose output with RSS memory and GC stats per phase and per mutation; also prints error class, message, and first 5 backtrace lines for errored mutations. |
 | `--suggest-tests`            | Boolean | false        | Generate concrete test code in suggestions (RSpec or Minitest, based on `--integration`). |
 | `-q`, `--quiet`              | Boolean | false        | Suppress output.                                   |
 | `--stdin`                    | Boolean | false        | Read target file paths from stdin (one per line).  |
@@ -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
@@ -163,7 +168,14 @@ Use `--format json` for machine-readable output. Schema:
   ],
   "killed": ["... same shape as survived entries ..."],
   "timed_out": ["... same shape as survived entries ..."],
-  "errors": ["... same shape as survived entries ..."]
+  "errors": [
+    {
+      "... same shape as survived entries, plus: ...": "",
+      "error_message": "string (optional) — error message from the failing mutation",
+      "error_class":   "string (optional) — exception class name (e.g. 'SyntaxError', 'NoMethodError')",
+      "error_backtrace": ["string (optional) — first 5 backtrace lines from the exception"]
+    }
+  ]
 }
 ```
 
@@ -364,7 +376,11 @@ For each entry in `survived[]`:
 4. Write a test that would fail if the mutation were applied
 5. Re-run evilution on just that file to verify the mutant is now killed
 
-### 7. CI gate
+### 7. Diagnosing errored mutations
+
+Entries in the JSON `errors[]` array represent mutations that raised an exception (syntax error, load failure, or runtime crash) rather than producing a test outcome. Each entry includes `error_class`, `error_message`, and the first 5 `error_backtrace` lines. Use these fields to decide whether the error is a bug in the mutation operator (file an issue), a load-time problem in the mutated source (often `NoMethodError: super called outside of method` or constant-redefinition issues), or a genuine crash that the original tests should have caught. Run with `--verbose` to stream the same error details to stderr during the run.
+
+### 8. CI gate
 
 ```bash
 bundle exec evilution run lib/ --format json --min-score 0.8 --quiet
@@ -394,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/base.rb

@@ -22,7 +22,9 @@ class Evilution::Integration::Base
     @temp_dir = nil
     ensure_framework_loaded
     fire_hook(:mutation_insert_pre, mutation: mutation, file_path: mutation.file_path)
-    apply_mutation(mutation)
+    load_error = apply_mutation(mutation)
+    return load_error if load_error
+
     fire_hook(:mutation_insert_post, mutation: mutation, file_path: mutation.file_path)
     run_tests(mutation)
   ensure
@@ -58,18 +60,42 @@ class Evilution::Integration::Base
     subpath = resolve_require_subpath(mutation.file_path)
 
     if subpath
-      dest = File.join(@temp_dir, subpath)
-      FileUtils.mkdir_p(File.dirname(dest))
-      File.write(dest, mutation.mutated_source)
-      $LOAD_PATH.unshift(@temp_dir)
-      displace_loaded_feature(mutation.file_path)
+      apply_via_require(mutation, subpath)
     else
-      absolute = File.expand_path(mutation.file_path)
-      dest = File.join(@temp_dir, absolute)
-      FileUtils.mkdir_p(File.dirname(dest))
-      File.write(dest, mutation.mutated_source)
-      load(dest)
+      apply_via_load(mutation)
     end
+    nil
+  rescue SyntaxError => e
+    {
+      passed: false,
+      error: "syntax error in mutated source: #{e.message}",
+      error_class: e.class.name,
+      error_backtrace: Array(e.backtrace).first(5)
+    }
+  rescue ScriptError, StandardError => e
+    {
+      passed: false,
+      error: "#{e.class}: #{e.message}",
+      error_class: e.class.name,
+      error_backtrace: Array(e.backtrace).first(5)
+    }
+  end
+
+  def apply_via_require(mutation, subpath)
+    dest = File.join(@temp_dir, subpath)
+    FileUtils.mkdir_p(File.dirname(dest))
+    File.write(dest, mutation.mutated_source)
+    $LOAD_PATH.unshift(@temp_dir)
+    displace_loaded_feature(mutation.file_path)
+    require(subpath.delete_suffix(".rb"))
+  end
+
+  def apply_via_load(mutation)
+    absolute = File.expand_path(mutation.file_path)
+    dest = File.join(@temp_dir, absolute)
+    FileUtils.mkdir_p(File.dirname(dest))
+    File.write(dest, mutation.mutated_source)
+    load(dest)
   end
 
   def restore_original(_mutation)

data/lib/evilution/isolation/fork.rb

@@ -57,8 +57,13 @@ class Evilution::Isolation::Fork
   def execute_in_child(mutation, test_command)
     result = test_command.call(mutation)
     { child_rss_kb: Evilution::Memory.rss_kb }.merge(result)
-  rescue StandardError => e
-    { passed: false, error: e.message }
+  rescue ScriptError, StandardError => e
+    {
+      passed: false,
+      error: e.message,
+      error_class: e.class.name,
+      error_backtrace: Array(e.backtrace).first(5)
+    }
   end
 
   def wait_for_result(pid, read_io, timeout)
@@ -107,7 +112,10 @@ class Evilution::Isolation::Fork
       duration: duration,
       test_command: result[:test_command],
       child_rss_kb: result[:child_rss_kb],
-      parent_rss_kb: parent_rss_kb
+      parent_rss_kb: parent_rss_kb,
+      error_message: result[:error],
+      error_class: result[:error_class],
+      error_backtrace: result[:error_backtrace]
     )
   end
 end

data/lib/evilution/isolation/in_process.rb

@@ -34,8 +34,14 @@ class Evilution::Isolation::InProcess
     { timeout: false }.merge(result)
   rescue Timeout::Error
     { timeout: true }
-  rescue StandardError => e
-    { timeout: false, passed: false, error: e.message }
+  rescue ScriptError, StandardError => e
+    {
+      timeout: false,
+      passed: false,
+      error: e.message,
+      error_class: e.class.name,
+      error_backtrace: Array(e.backtrace).first(5)
+    }
   end
 
   def suppress_output
@@ -74,7 +80,10 @@ class Evilution::Isolation::InProcess
       test_command: result[:test_command],
       child_rss_kb: rss_after,
       memory_delta_kb: memory_delta_kb,
-      parent_rss_kb: rss_before
+      parent_rss_kb: rss_before,
+      error_message: result[:error],
+      error_class: result[:error_class],
+      error_backtrace: result[:error_backtrace]
     )
   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/mutator/operator/symbol_literal.rb

@@ -4,6 +4,8 @@ require_relative "../operator"
 
 class Evilution::Mutator::Operator::SymbolLiteral < Evilution::Mutator::Base
   def visit_symbol_node(node)
+    return super if label_form?(node)
+
     add_mutation(
       offset: node.location.start_offset,
       length: node.location.length,
@@ -20,4 +22,11 @@ class Evilution::Mutator::Operator::SymbolLiteral < Evilution::Mutator::Base
 
     super
   end
+
+  private
+
+  def label_form?(node)
+    closing = node.closing_loc
+    !closing.nil? && closing.slice == ":"
+  end
 end

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/reporter/cli.rb

@@ -19,6 +19,7 @@ class Evilution::Reporter::CLI
     append_survived(lines, summary)
     append_neutral(lines, summary)
     append_equivalent(lines, summary)
+    append_errors(lines, summary)
     append_disabled(lines, summary)
     lines << ""
     lines << "[TRUNCATED] Stopped early due to --fail-fast" if summary.truncated?
@@ -54,6 +55,24 @@ class Evilution::Reporter::CLI
     summary.equivalent_results.each { |result| lines << format_neutral(result) }
   end
 
+  def append_errors(lines, summary)
+    errored = summary.results.select(&:error?)
+    return if errored.empty?
+
+    lines << ""
+    lines << "Errored mutations:"
+    errored.each { |result| lines << format_error(result) }
+  end
+
+  def format_error(result)
+    mutation = result.mutation
+    header = "  #{mutation.operator_name}: #{mutation.file_path}:#{mutation.line}"
+    return header unless result.error_message
+
+    indented = result.error_message.lines.map { |line| "    #{line.chomp}" }.join("\n")
+    "#{header}\n#{indented}"
+  end
+
   def append_disabled(lines, summary)
     return unless summary.disabled_mutations.any?
 

data/lib/evilution/reporter/html.rb

@@ -145,8 +145,10 @@ class Evilution::Reporter::HTML
   def build_map_entry(result)
     mutation = result.mutation
     status = result.status.to_s
+    title_text = normalize_title(result.error_message)
+    title_attr = title_text ? %( title="#{h(title_text)}") : ""
     <<~HTML.chomp
-      <div class="map-line #{status}">
+      <div class="map-line #{status}"#{title_attr}>
         <span class="line-number">line #{mutation.line}</span>
         <span class="operator">#{h(mutation.operator_name)}</span>
         <span class="status-badge #{status}">#{status}</span>
@@ -154,6 +156,13 @@ class Evilution::Reporter::HTML
     HTML
   end
 
+  def normalize_title(message)
+    return nil if message.nil?
+
+    normalized = message.gsub(/\s+/, " ").strip
+    normalized.empty? ? nil : normalized
+  end
+
   def build_survived_details(survived)
     return "" if survived.empty?
 

data/lib/evilution/reporter/json.rb

@@ -76,10 +76,21 @@ class Evilution::Reporter::JSON
     }
     detail[:suggestion] = @suggestion.suggestion_for(mutation) if result.status == :survived
     detail[:test_command] = result.test_command if result.test_command
+    append_memory_fields(detail, result)
+    append_error_fields(detail, result)
+    detail
+  end
+
+  def append_memory_fields(detail, result)
     detail[:parent_rss_kb] = result.parent_rss_kb if result.parent_rss_kb
     detail[:child_rss_kb] = result.child_rss_kb if result.child_rss_kb
     detail[:memory_delta_kb] = result.memory_delta_kb if result.memory_delta_kb
-    detail
+  end
+
+  def append_error_fields(detail, result)
+    detail[:error_message] = result.error_message if result.error_message
+    detail[:error_class] = result.error_class if result.error_class
+    detail[:error_backtrace] = result.error_backtrace if result.error_backtrace
   end
 
   def build_coverage_gaps(summary)

data/lib/evilution/result/mutation_result.rb

@@ -6,11 +6,15 @@ class Evilution::Result::MutationResult
   STATUSES = %i[killed survived timeout error neutral equivalent].freeze
 
   attr_reader :mutation, :status, :duration, :killing_test, :test_command,
-              :child_rss_kb, :memory_delta_kb, :parent_rss_kb
+              :child_rss_kb, :memory_delta_kb, :parent_rss_kb,
+              :error_message, :error_class, :error_backtrace
 
+  # rubocop:disable Metrics/ParameterLists
   def initialize(mutation:, status:, duration: 0.0, killing_test: nil,
                  test_command: nil, child_rss_kb: nil, memory_delta_kb: nil,
-                 parent_rss_kb: nil)
+                 parent_rss_kb: nil, error_message: nil, error_class: nil,
+                 error_backtrace: nil)
+    # rubocop:enable Metrics/ParameterLists
     raise ArgumentError, "invalid status: #{status}" unless STATUSES.include?(status)
 
     @mutation = mutation
@@ -21,6 +25,9 @@ class Evilution::Result::MutationResult
     @child_rss_kb = child_rss_kb
     @memory_delta_kb = memory_delta_kb
     @parent_rss_kb = parent_rss_kb
+    @error_message = error_message
+    @error_class = error_class
+    @error_backtrace = error_backtrace.nil? ? nil : error_backtrace.dup.freeze
     freeze
   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 }
 
@@ -411,7 +426,10 @@ class Evilution::Runner
       test_command: result.test_command,
       child_rss_kb: result.child_rss_kb,
       memory_delta_kb: result.memory_delta_kb,
-      parent_rss_kb: result.parent_rss_kb
+      parent_rss_kb: result.parent_rss_kb,
+      error_message: result.error_message,
+      error_class: result.error_class,
+      error_backtrace: result.error_backtrace
     )
   end
 
@@ -423,7 +441,10 @@ class Evilution::Runner
       test_command: result.test_command,
       child_rss_kb: result.child_rss_kb,
       memory_delta_kb: result.memory_delta_kb,
-      parent_rss_kb: result.parent_rss_kb
+      parent_rss_kb: result.parent_rss_kb,
+      error_message: result.error_message,
+      error_class: result.error_class,
+      error_backtrace: result.error_backtrace
     }
   end
 
@@ -437,7 +458,10 @@ class Evilution::Runner
         test_command: data[:test_command],
         child_rss_kb: data[:child_rss_kb],
         memory_delta_kb: data[:memory_delta_kb],
-        parent_rss_kb: data[:parent_rss_kb]
+        parent_rss_kb: data[:parent_rss_kb],
+        error_message: data[:error_message],
+        error_class: data[:error_class],
+        error_backtrace: data[:error_backtrace]
       )
     end
   end
@@ -474,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)
 
-    :in_process
+    @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
+
+    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
@@ -562,9 +657,20 @@ class Evilution::Runner
 
     parts << gc_stats_string
 
-    return if parts.empty?
+    $stderr.write("[verbose] #{result.mutation}: #{parts.join(", ")}\n") unless parts.empty?
 
-    $stderr.write("[verbose] #{result.mutation}: #{parts.join(", ")}\n")
+    log_mutation_error(result) if result.error?
+  end
+
+  def log_mutation_error(result)
+    header = "[verbose] #{result.mutation}: error"
+    header += " #{result.error_class}" if result.error_class
+    header += ": #{result.error_message}" if result.error_message
+    $stderr.write("#{header}\n")
+
+    Array(result.error_backtrace).first(5).each do |line|
+      $stderr.write("[verbose]   #{line}\n")
+    end
   end
 
   def gc_stats_string

data/lib/evilution/version.rb

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

data/script/memory_check

@@ -104,12 +104,12 @@ complex_mutations = complex_subjects.flat_map { |s| complex_registry.mutations_f
 
 integration = Evilution::Integration::RSpec.new(test_files: [COMPLEX_FIXTURE_SPEC])
 
-all_passed &= run_check("RSpec integration per-mutation (Config)", iterations: 20, max_growth_kb: 20_480) do
+# Budget is generous: per-mutation require() adds the file to $LOADED_FEATURES and
+# accumulates constant-redefinition warnings. Local runs land around 20-25 MB; CI
+# varies up to ~30 MB depending on Ruby build and GC pressure, so we leave headroom.
+all_passed &= run_check("RSpec integration per-mutation (Config)", iterations: 20, max_growth_kb: 40_960) do
   mutation = complex_mutations.sample
-  result = integration.call(mutation)
-  raise "RSpec integration memory check failed: #{result[:error]}" if result[:error]
-
-  result
+  integration.call(mutation)
 end
 
 puts all_passed ? "All memory checks passed." : "Some memory checks failed!"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.22.2
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -70,6 +70,7 @@ files:
 - ".claude/prompts/architect.md"
 - ".claude/prompts/devops.md"
 - ".claude/prompts/tests.md"
+- ".claude/settings.json"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -80,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
@@ -209,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