evilution 0.30.4 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bd9eaca72cb973c6e11841144b8bae68d2a838aef1ff64c429e18b4090505f1
-  data.tar.gz: bbdedbc5ef66ca367deeec89a53399ce83a235616fe2ac179ed98bf880f8be9b
+  metadata.gz: dc948250a218198fef7420e04ab49e5a2f8e01ff50ae279f5299bb85db07ab77
+  data.tar.gz: df6e3a2ea4ee5512f9c946f4df514f8a1a2df8308ac77236ceafa3de81b435d8
 SHA512:
-  metadata.gz: b7cf12d8381e05d66b1a2ffcf1c243e3e18d66f8f073de892d40ff139bb6952214ac5c6bdcff3ab026dd475601629790e7c4d5f86f8315a8baf989bcb5b4aa7b
-  data.tar.gz: 21a523a1f2753c5e70b9fb2d53262d28b169661b75c2bd2ca44ce5f9e5c6234591f6d8dcc935fea8c49a79689d7be5a2883cae6ff4517b711379b80b8d8315bf
+  metadata.gz: 43c08e6baa4904c1122d639c957cc1139c9e4760e3e38aed8664a70ff46388aab91b64924816739d4c7a9f00abb049f2da579c50f3b5a585c49b2175f3461dff
+  data.tar.gz: e30f5845c332781de9431c9a4238df1ac9048960d3ef36323dac0a8beaf2f5c5d56eb1d3132d618a7e076bb7547520286fc127347499b0b95640331e16912fb8

data/.beads/interactions.jsonl

@@ -387,3 +387,25 @@
 {"id":"int-011584d4","kind":"field_change","created_at":"2026-05-15T15:55:27.437673072Z","actor":"Denis Kiselev","issue_id":"EV-vxgl","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed PR (merged). MutationApplier#mark_feature_loaded registers realpath in $LOADED_FEATURES post-eval — spec require() no longer reloads original. pagy jobs=4: 0% -> 82.81%. Residual gap vs jobs=1 is separate (EV-wu8w in_process inflation)."}}
 {"id":"int-c44e7652","kind":"field_change","created_at":"2026-05-16T12:45:46.793709029Z","actor":"Denis Kiselev","issue_id":"EV-xfaj","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed in PR #1260 — run_minitest counts test methods from Minitest::Runnable.runnables registry instead of an evictable reporter"}}
 {"id":"int-eea19850","kind":"field_change","created_at":"2026-05-16T14:22:49.671269232Z","actor":"Denis Kiselev","issue_id":"EV-wu8w","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed in PR #1264 — run_minitest reads verdict from evilution's own per-run SummaryReporter attached after plugin init"}}
+{"id":"int-cf85d538","kind":"field_change","created_at":"2026-05-16T15:40:28.573223389Z","actor":"Denis Kiselev","issue_id":"EV-5dxk","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Part A (required guard: 0 dispatched test methods -> :error) shipped in 0.30.3 PR #1257. Acceptance met. Part B (test-unit integration) split into its own epic."}}
+{"id":"int-6efa8613","kind":"field_change","created_at":"2026-05-16T15:55:20.799858411Z","actor":"Denis Kiselev","issue_id":"EV-174x","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed and merged 2026-05-12; GH #1194 / #1195 closed. RedefinitionRecovery widened (already registered/initialized/exists); splice approach reverted for memory leak. Bead-close missed at merge time — syncing now."}}
+{"id":"int-ddb8370f","kind":"field_change","created_at":"2026-05-16T15:55:21.07310729Z","actor":"Denis Kiselev","issue_id":"EV-wwx3","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed and merged 2026-05-12; GH #1194 / #1195 closed. RedefinitionRecovery widened (already registered/initialized/exists); splice approach reverted for memory leak. Bead-close missed at merge time — syncing now."}}
+{"id":"int-4ea24fb5","kind":"field_change","created_at":"2026-05-16T16:04:54.395246914Z","actor":"Denis Kiselev","issue_id":"EV-s24s","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Already fixed — both named specs (unparseable_short_circuit_spec.rb, neutralization_integration_spec.rb) pass and destructure via execution.results. Stale in_progress; syncing."}}
+{"id":"int-8b699158","kind":"field_change","created_at":"2026-05-16T17:22:07.345408768Z","actor":"Denis Kiselev","issue_id":"EV-kcuf","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Proof-of-life canary implemented + merged. Runner::Canary runs a synthetic unobservable mutation at session start; aborts if not scored :survived. --[no-]canary flag, config.canary default true."}}
+{"id":"int-e4dcc2b3","kind":"field_change","created_at":"2026-05-27T04:19:00.738936734Z","actor":"Denis Kiselev","issue_id":"EV-qbd6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fix landed on master in commit 0f1781f (require 'bundler/setup' at bin/evilution-self:16). Verified 2026-05-27: crash dir lib/evilution/result/*.rb scores 91.11% (744 muts, 656 killed, 64 survived, 24 equivalent, 0 errors); canary passes; dual-runtime harness measures crash dirs again."}}
+{"id":"int-4cb27d5a","kind":"field_change","created_at":"2026-05-28T06:42:48.564599548Z","actor":"Denis Kiselev","issue_id":"EV-pyx6","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Fix merged on master in commit 72b43a3 (PR #1292). Added Evilution.project_base_dir helper + anchored spec/ via Evilution.project_base_dir in framework_loader.rb and baseline_runner.rb. Verified 2026-05-28: bin/evilution-self run lib/evilution/config/env_loader.rb scores 94.59% (was 0 before fix). 4705 examples pass, rubocop clean."}}
+{"id":"int-4cd16cba","kind":"field_change","created_at":"2026-05-29T04:54:00.815774086Z","actor":"Denis Kiselev","issue_id":"EV-8tmc","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Partial fix landed in commit 525787b: 18 of 20 lib/ subdirs now measurable (was 11/20). Two follow-up causes diagnosed and addressed: (1) auto-isolation picking in_process for non-Rails projects + RSpec swallowing Timeout::Error per-example, fixed by script using --isolation=fork explicitly; (2) ChildOutput log_dir relative-path bug under EV-wqxu sandbox CWD, fixed by absolutizing in runner.rb#configure_child_output. Remaining 2 dirs (parallel + toplevel) hang via different root cause — grandchild fork leak — tracked separately as EV-dgjv (GH #1295)."}}
+{"id":"int-991e5acf","kind":"field_change","created_at":"2026-05-30T15:56:24.341278813Z","actor":"Denis Kiselev","issue_id":"EV-auk5","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-df2bd661","kind":"field_change","created_at":"2026-05-30T15:56:24.686504141Z","actor":"Denis Kiselev","issue_id":"EV-9d62","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-6a1dc0ce","kind":"field_change","created_at":"2026-05-30T15:56:25.04815512Z","actor":"Denis Kiselev","issue_id":"EV-unar","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-defdc095","kind":"field_change","created_at":"2026-05-30T15:56:25.406639346Z","actor":"Denis Kiselev","issue_id":"EV-04sc","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-bc5a7747","kind":"field_change","created_at":"2026-05-30T17:33:33.191722982Z","actor":"Denis Kiselev","issue_id":"EV-8qiy","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-796e3efc","kind":"field_change","created_at":"2026-05-30T17:33:34.539604057Z","actor":"Denis Kiselev","issue_id":"EV-uv11","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-5fb67d2b","kind":"field_change","created_at":"2026-05-30T17:46:39.956899342Z","actor":"Denis Kiselev","issue_id":"EV-bcjp","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-6ba88696","kind":"field_change","created_at":"2026-05-30T17:59:44.432841837Z","actor":"Denis Kiselev","issue_id":"EV-aqxd","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-34eb133e","kind":"field_change","created_at":"2026-05-31T02:20:26.61836178Z","actor":"Denis Kiselev","issue_id":"EV-vumz","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-9527af14","kind":"field_change","created_at":"2026-05-31T02:47:48.910182696Z","actor":"Denis Kiselev","issue_id":"EV-zhqc","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-dfe331ef","kind":"field_change","created_at":"2026-05-31T02:59:12.044281579Z","actor":"Denis Kiselev","issue_id":"EV-akt2","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-c7bcc360","kind":"field_change","created_at":"2026-05-31T03:12:47.029582311Z","actor":"Denis Kiselev","issue_id":"EV-6az9","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-fa3ade4f","kind":"field_change","created_at":"2026-05-31T08:47:32.000198989Z","actor":"Denis Kiselev","issue_id":"EV-d3av","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-b1831323","kind":"field_change","created_at":"2026-05-31T08:47:50.244781995Z","actor":"Denis Kiselev","issue_id":"EV-d7re","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}

data/.rubocop_todo.yml

@@ -8,7 +8,13 @@ Metrics/AbcSize:
 
 Metrics/ClassLength:
   Exclude:
+    - "lib/evilution/config.rb"
     - "lib/evilution/isolation/fork.rb"
     - "lib/evilution/integration/minitest.rb"
     - "lib/evilution/mcp/mutate_tool.rb"
+    - "lib/evilution/runner.rb"
     - "lib/evilution/runner/isolation_resolver.rb"
+
+Metrics/MethodLength:
+  Exclude:
+    - "lib/evilution/runner.rb"

data/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Versioning policy: see [docs/versioning.md](docs/versioning.md).
 
+## [0.32.0] - 2026-05-31
+
+### Added
+
+- **`--integration test-unit` runs mutations against projects whose suites use the `test-unit` gem** — Rails projects that `require "test/unit/rails/test_help"` make `ActiveSupport::TestCase` inherit from `Test::Unit::TestCase`, and the existing Minitest integration could not dispatch them (`Minitest::Runnable.runnables` is empty because the test classes are not Minitest runnables at all). A dedicated `Evilution::Integration::TestUnit` orchestrator now wires a framework loader (disables the `Test::Unit::AutoRunner` at_exit handler so it does not fire on evilution exit), a subject-class registry (diffs `Test::Unit::TestCase` descendants across `load` to scope each mutation to freshly-loaded suites without a public registry-clear API), a dispatcher (`Test::Unit::UI::Console::TestRunner` with output captured to a `StringIO`), a spec resolver (`test/foo_test.rb` convention, matching Minitest), and a result builder shaping the `passed`/`test_crashed`/`no_tests_ran`/`unresolved` hashes that `classify_status` consumes. `Evilution::Integration::TestUnitCrashDetector` mirrors the Minitest analogue, distinguishing `Test::Unit::Failure` (assertion) from `Test::Unit::Error` (exception/crash) via `TestResult.add_listener(FAULT, ...)`. CLI accepts both `--integration test-unit` and `--integration test_unit`; the MCP `evilution-mutate` tool advertises `test-unit` in its JSON schema enum. Kaminari canary (`kaminari-core/lib/kaminari/models/page_scope_methods.rb`) now scores 63.60% (272 mutations dispatched) where 0.30.x scored 0.00% with the Minitest integration. See [docs/integrations.md](docs/integrations.md). Suggest-tests templates for test-unit are not yet implemented; runs with `--suggest-tests --integration test-unit` fall back to the generic operator-level phrasing (EV-d7re epic + sub-beads EV-8qiy/EV-uv11/EV-bcjp/EV-aqxd/EV-vumz/EV-zhqc/EV-akt2/EV-6az9/EV-d3av, PRs #1314/#1315/#1316/#1318/#1320/#1321, GH #1267)
+
+### Fixed
+
+- **Pool workers no longer hang indefinitely in `Process.wait` when a per-mutation child writes a payload but does not exit promptly** — `Evilution::Isolation::Fork#reap_and_decode` called unbounded `Process.wait(pid)` after reading a length-prefixed payload from the marshal pipe. If the per-mutation child had written the payload but was still stuck in `execute_in_child` waiting on a subject grandchild the mutation broke (or a grandchild had written garbage bytes that looked like a valid header+body to the parent's inherited write fd), the pool worker blocked forever; the per-mutation timeout had no effect because `wait_for_result` had already returned. `Evilution::Parallel::WorkQueue::Dispatcher`'s `item_timeout` then fired `"worker timed out after 30s"` and SIGKILLed the pool worker, leaving the per-mutation child orphaned to init. `reap_and_decode` now bounds the wait by `REAP_DEADLINE = 1.0`s and falls through to the TERM → GRACE_PERIOD → KILL → safe_wait ladder when the child has not exited, so a stuck child takes ~3s worst-case instead of indefinite. Previously-unmeasurable parallel/ + toplevel/ self-baseline directories (parallel/work_queue.rb, parallel/work_queue/dispatcher.rb, parallel/work_queue/worker.rb, isolation/, toplevel) now all produce real summaries (EV-dgjv, PR #1296, GH #1295)
+- **`script/run_self_baseline` toplevel batch invocation now passes `--isolation=fork`** — every subdir invocation explicitly passed `--isolation=fork`, but the trailing toplevel batch (`lib/evilution/*.rb` files) omitted it. Default isolation auto-picked in_process for the non-Rails self-mutation, which (combined with RSpec's per-example `Timeout::Error` swallow) caused the toplevel batch to hit dispatcher item_timeout and report `NO_SUMMARY`. The toplevel cmd now matches the per-subdir cmd, so all 20 self-baseline dirs are measurable (EV-dgjv, PR #1296, GH #1295)
+
+## [0.31.0] - 2026-05-27
+
+### Added
+
+- **Proof-of-life canary at session start** — before any real mutation runs, `Evilution::Runner::Canary` evals a synthetic, guaranteed-unobservable mutation through the configured integration + isolation. A healthy pipeline must score it `:survived`; any other status aborts the run with a diagnostic, so the user never sees a score that was produced by a broken pipeline (autoload mismatch, reporter-plugin eviction, isolation defect, `fail_if_no_examples` config drift, etc.). On by default; toggle with `--[no-]canary` or `canary: true|false` in `.evilution.yml`. Mirrors the configured `--isolation` so isolation-specific defects are caught too (EV-kcuf, PR #1268, GH #1233)
+
+### Fixed
+
+- **Mutation children no longer pollute the working tree with files written to relative paths** — every isolator (fork and in_process) now `Dir.chdir`s into a per-mutation sandbox directory for the duration of `test_command.call`, and removes the sandbox on the way out. Any mutation that turns an absolute path into a relative one — `argument_removal` on `File.join(dir, name)`, `method_call_removal` on `File.expand_path(rel, base)`, etc. — used to write `File.write(name, …)` into the parent process's CWD (typically the repo root) and leak past the run; baselining `lib/evilution/runner/canary.rb` deposited 43 stray files (`canary_<pid>_<hex>_spec.rb`, `evilutioncanary_<pid>_<hex>.rb`) before this fix. Spec resolution and source eval anchor project-relative paths to `Evilution::PROJECT_ROOT` (captured at load), so the sandbox CWD does not break `SpecResolver`, `SpecSelector`, `MutationApplier`, `SourceEvaluator`, or the `RSpec::Core::Runner` / `Minitest.load` invocation sites (EV-wqxu, PR #1281, GH #1278)
+- **`MutationApplier` registers the mutation in `$LOADED_FEATURES` BEFORE evaluating the source, not after** — a sibling `require_relative` chain that loops back to the mutated file during the eval itself (e.g. `lib/evilution/mcp/*.rb` tools whose body requires a peer that requires this file back) re-read the *original* source from disk and clobbered the mutation mid-eval. Every such mutation silently survived. The feature-loaded marker now runs immediately before `@source_evaluator.call`, so the in-progress eval is the canonical source any concurrent require sees. Without this, fork workers started from the same pre-`require` snapshot and the whole file scored 0% (EV-ekax, PR #1272, GH #1269)
+
 ## [0.30.4] - 2026-05-16
 
 ### Fixed

data/README.md

@@ -101,12 +101,13 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `--example-targeting-fallback MODE` | String | `full_file` | Behavior when no example matches: `full_file` (run the whole spec file) or `unresolved` (skip the mutation as `:unresolved`). |
 | `-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`. |
+| `--[no-]canary`              | Boolean | _(enabled)_  | Run a proof-of-life synthetic mutation at session start; abort the run if the pipeline misreports it. Catches misconfigured isolation, broken autoload, and reporter-plugin eviction before any real score is produced. Pass `--no-canary` to skip (e.g. CI speed, or when the canary itself is the thing under test). |
 | `--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; 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`). |
+| `--suggest-tests`            | Boolean | false        | Generate concrete test code in suggestions (RSpec or Minitest, based on `--integration`; falls back to generic phrasing for `test-unit`). |
 | `-q`, `--quiet`              | Boolean | false        | Suppress output.                                   |
 | `--stdin`                    | Boolean | false        | Read target file paths from stdin (one per line).  |
-| `--integration NAME`         | String  | `rspec`      | Test framework integration: `rspec` or `minitest`.  |
+| `--integration NAME`         | String  | `rspec`      | Test framework integration: `rspec`, `minitest`, or `test-unit`. See [docs/integrations.md](docs/integrations.md). |
 | `--[no-]incremental`         | Boolean | false        | Cache killed/timeout results; skip unchanged mutations on re-runs. Pass `--no-incremental` to override `incremental: true` from the config file for one invocation (e.g. cold-cache debugging). Last flag wins when both are given. |
 | `--save-session`             | Boolean | false        | Persist results as timestamped JSON under `.evilution/results/`. |
 | `--no-progress`              | Boolean | _(enabled)_  | Disable the TTY progress bar.                      |
@@ -168,10 +169,11 @@ schema_version: 1            # opts into strict validation (rejects unknown keys
 # timeout: 30              # seconds per mutation
 # format: text             # text | json | html
 # min_score: 0.0           # 0.0–1.0
-# integration: rspec       # test framework: rspec, minitest
+# integration: rspec       # test framework: rspec, minitest, test_unit
 # 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)
+# canary: true             # proof-of-life synthetic mutation at session start (false to skip)
 # preload: null            # path to preload before forking; false to disable; auto-detects for Rails
 # skip_heredoc_literals: false  # skip string literal mutations inside heredocs (recommended for Rails: heredoc SQL/templates rarely have test coverage)
 # show_disabled: false     # report mutations skipped by disable comments
@@ -211,7 +213,7 @@ All keys recognised under `schema_version: 1`:
 | `format`                     | String                        | `text`                                 | Output format: `text`, `json`, `html`.                                                                                                   |
 | `target`                     | String / null                 | `null`                                 | Filter expression: method (`Foo#bar`), class (`Foo`), namespace (`Foo*`), descendants (`descendants:Foo`), source glob (`source:**/*.rb`). |
 | `min_score`                  | Float                         | `0.0`                                  | Minimum mutation score (0.0–1.0) for exit code 0.                                                                                        |
-| `integration`                | String                        | `rspec`                                | Test framework: `rspec` or `minitest`.                                                                                                   |
+| `integration`                | String                        | `rspec`                                | Test framework: `rspec`, `minitest`, or `test_unit`.                                                                                     |
 | `verbose`                    | Boolean                       | `false`                                | Verbose output (RSS/GC stats per phase, error details for errored mutations).                                                            |
 | `quiet`                      | Boolean                       | `false`                                | Suppress output.                                                                                                                         |
 | `jobs`                       | Integer                       | `1`                                    | Number of parallel workers.                                                                                                              |
@@ -515,7 +517,7 @@ These fields are added in addition to the existing `operator`, `file`, `line`, `
 
 The `evilution-mutate` tool accepts a `suggest_tests` boolean parameter (default: `false`). When enabled, survived mutation suggestions contain concrete test code that an agent can drop into a test file, instead of static description text. It currently generates RSpec-style suggestions (`it`/`expect` blocks).
 
-Pass `suggest_tests: true` in the `evilution-mutate` call to activate this mode. The CLI also supports `--suggest-tests`; when using the CLI, generated suggestions match the `--integration` setting (RSpec `it`/`expect` blocks or Minitest `def test_`/`assert_equal` methods).
+Pass `suggest_tests: true` in the `evilution-mutate` call to activate this mode. The CLI also supports `--suggest-tests`; when using the CLI, generated suggestions match the `--integration` setting (RSpec `it`/`expect` blocks or Minitest `def test_`/`assert_equal` methods). Concrete templates for `test-unit` are not yet implemented — `test-unit` runs fall back to generic suggestion text.
 
 ### Project Config File
 
@@ -530,7 +532,7 @@ Pass `skip_config: true` to ignore the project config file. This skips loading `
 | Parameter | Purpose |
 |---|---|
 | `incremental` | Cache killed/timeout results across runs — set `true` when iterating on the same files |
-| `integration` | `rspec` or `minitest` |
+| `integration` | `rspec`, `minitest`, or `test_unit` |
 | `isolation` | `auto`, `fork`, or `in_process` |
 | `baseline` | `false` to skip the baseline suite check when you already know it's green |
 | `save_session` | Persist results to `.evilution/results/` for inspection via `evilution-session` |
@@ -772,7 +774,7 @@ Tests 4 paths (InProcess isolation, Fork isolation, mutation generation + stripp
 3. **Filter** — Disable comments, Sorbet `sig` blocks, and AST ignore patterns exclude mutations before execution
 4. **Mutate** — 74 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default. Identical byte-mutations from different operators are deduplicated by `(file_path, mutated_source)` so the count is not inflated by overlap
 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
+6. **Test** — The configured test framework (RSpec, Minitest, or Test::Unit) 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/integrations.md

@@ -0,0 +1,126 @@
+# Test Framework Integrations
+
+Evilution supports three test framework integrations, selected via the
+`--integration NAME` CLI flag (or the `integration:` key in `.evilution.yml`).
+Each integration owns its own framework loader, dispatcher, spec resolver,
+and result builder so they can evolve independently.
+
+| Integration   | Flag value    | Default test dir | Default test suffix | Gem dep                |
+|---------------|---------------|------------------|---------------------|------------------------|
+| RSpec         | `rspec`       | `spec/`          | `_spec.rb`          | `rspec-core`           |
+| Minitest      | `minitest`    | `test/`          | `_test.rb`          | `minitest`             |
+| Test::Unit    | `test-unit`   | `test/`          | `_test.rb`          | `test-unit`            |
+
+## When to pick which
+
+- **`rspec`** (default) — Suites built on `RSpec.describe` / `it` / `expect`.
+- **`minitest`** — Suites that subclass `Minitest::Test` or use
+  `Minitest::Spec`'s `describe` / `it`. Includes Rails apps where
+  `ActiveSupport::TestCase` inherits from `Minitest::Test`.
+- **`test-unit`** — Suites that subclass `Test::Unit::TestCase`, including
+  Rails projects that `require "test/unit/rails/test_help"` (which makes
+  `ActiveSupport::TestCase < Test::Unit::TestCase`). The `test-unit` gem's
+  `TestCase` classes are *not* `Minitest::Runnable` subclasses, so the
+  `minitest` integration cannot dispatch them — pick this integration whenever
+  your test helper pulls in `test/unit/rails/test_help`, `test-unit-activerecord`,
+  or similar test-unit-specific glue.
+
+## CLI examples
+
+```bash
+# RSpec — default; specs in spec/, named *_spec.rb
+bundle exec evilution run lib/foo.rb
+
+# Minitest
+bundle exec evilution run lib/foo.rb \
+  --integration minitest --spec test/foo_test.rb
+
+# Test::Unit (gem name uses hyphen; symbol value uses underscore)
+bundle exec evilution run lib/foo.rb \
+  --integration test-unit --spec test/foo_test.rb
+```
+
+The CLI accepts both `test-unit` and `test_unit` strings; the internal config
+symbol is always `:test_unit`.
+
+## MCP examples
+
+The `evilution-mutate` MCP tool exposes `integration` as a JSON schema enum
+of `["rspec", "minitest", "test-unit"]`:
+
+```json
+{
+  "tool": "evilution-mutate",
+  "args": {
+    "files": ["lib/foo.rb"],
+    "integration": "test-unit",
+    "spec": ["test/foo_test.rb"]
+  }
+}
+```
+
+## Spec resolution conventions
+
+When `--spec` is not supplied, evilution resolves a test file from the source
+path using the integration's spec resolver. Strips `lib/` or `app/` prefix
+and rewrites the suffix:
+
+| Source                              | rspec                               | minitest / test-unit               |
+|-------------------------------------|-------------------------------------|------------------------------------|
+| `lib/foo.rb`                        | `spec/foo_spec.rb`                  | `test/foo_test.rb`                 |
+| `lib/foo/bar.rb`                    | `spec/foo/bar_spec.rb`              | `test/foo/bar_test.rb`             |
+| `app/models/user.rb`                | `spec/models/user_spec.rb`          | `test/models/user_test.rb`         |
+| `app/controllers/users_controller.rb` | `spec/requests/users_spec.rb` *or* `spec/controllers/users_controller_spec.rb` | `test/integration/users_test.rb` *or* `test/controllers/users_controller_test.rb` |
+
+For controllers, the resolver tries the request-spec / integration-test
+location first, then falls back to the controller-spec / controller-test
+location.
+
+## Suggest-tests caveat
+
+The `--suggest-tests` mode emits ready-to-paste test snippets for survived
+mutations. Concrete templates currently exist for **rspec** and **minitest**
+only; the **test-unit** integration falls back to the generic operator-level
+suggestion text. Adding test-unit templates is a small follow-up.
+
+## Other Ruby test frameworks
+
+No additional integrations are planned at the moment. The three integrations
+above cover the overwhelming majority of Ruby projects with unit / integration
+test suites. Frameworks we considered and deferred:
+
+- **Cucumber / Spinach** — BDD scenarios over Gherkin step definitions, a
+  fundamentally coarser granularity than mutation testing rewards. Not a
+  natural fit; no plans to add.
+- **Sus** — Socketry's async-focused framework, small but actively maintained
+  user base. Could be added under the same orchestrator/collaborator pattern
+  if a real project surfaces needing it.
+- **Bacon, Test::Spec** — early RSpec-style clones, effectively dormant.
+- **Minitest::Spec** — already covered by the `minitest` integration.
+
+If you maintain a project on another framework and would benefit from
+mutation-testing it through evilution, open an issue describing the project
+and the framework's dispatch entry-point — the existing integration layout
+makes new entries cheap to add.
+
+## Behind the scenes
+
+Each integration has an orchestrator class at
+`lib/evilution/integration/<name>.rb`. RSpec and Test::Unit additionally
+decompose their collaborators into a sibling directory of the same name
+(`lib/evilution/integration/rspec/...`,
+`lib/evilution/integration/test_unit/...`); Minitest remains a single file.
+The test-unit collaborators are:
+
+- `framework_loader.rb` — `require "test-unit"` + disables the at_exit
+  auto-run handler so it doesn't fire on evilution exit.
+- `subject_class_registry.rb` — ObjectSpace tracking of newly-loaded
+  `Test::Unit::TestCase` subclasses (test-unit has no public
+  registry-clear analog to `Minitest::Runnable.runnables`).
+- `dispatcher.rb` — assembles a `Test::Unit::TestSuite` from the new
+  classes and runs it via `Test::Unit::UI::Console::TestRunner` with
+  output captured to a `StringIO`.
+- `test_file_resolver.rb` — explicit-override + spec-selector +
+  fallback glob + warn-once for unresolved sources.
+- `result_builder.rb` — shapes the `passed`/`test_crashed`/
+  `no_tests_ran`/`unresolved` Hash that flows into `classify_status`.

data/docs/isolation.md

@@ -103,6 +103,33 @@ 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.
 
+## Sandboxed working directory
+
+Every isolator runs `test_command.call` inside a per-mutation scratch
+directory (`Dir.mktmpdir("evilution-run")`) that is removed on the way out.
+Mutations that turn an absolute path into a relative one — for example
+`argument_removal` on `File.join(dir, name)` collapsing to `File.write(name,
+…)` — would otherwise drop files into the parent process's CWD (typically
+the repo root) and leak past the run.
+
+Project-relative paths used by `SpecResolver`, `SpecSelector`, the
+`RSpec::Core::Runner` / `Minitest.load` invocation sites, and the mutated
+file's `__FILE__` in `SourceEvaluator` are anchored at
+`Evilution::PROJECT_ROOT` (captured at load time), so the sandbox CWD does
+not break spec lookup or `require_relative` chains inside the mutant.
+
+## Proof-of-life canary
+
+Before any real mutation runs, `Evilution::Runner::Canary` evals a
+synthetic, guaranteed-unobservable mutation through the configured
+integration + isolation. A healthy pipeline must score it `:survived`; any
+other status aborts the run with a diagnostic so the user never sees a
+score produced by a broken pipeline (autoload mismatch, reporter-plugin
+eviction, isolation defect, `fail_if_no_examples` config drift, etc.).
+On by default; toggle with `--[no-]canary` or `canary: true|false` in
+`.evilution.yml`. The canary mirrors the configured `--isolation` so
+isolation-specific defects are caught too.
+
 ## Related flags
 
 - `--timeout N` sets the per-mutation time limit. Under `fork`, this drives
@@ -111,5 +138,6 @@ poison subsequent runs.
 - `--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.
+- `--[no-]canary` toggles the proof-of-life pre-flight check (see above).
 
 [rails-handle-interrupt]: https://github.com/rails/rails/blob/main/activesupport/lib/active_support/concurrency/thread_monitor.rb

data/lib/evilution/cli/parser/options_builder.rb

@@ -86,11 +86,16 @@ class Evilution::CLI::Parser::OptionsBuilder
             "Use --no-incremental to override `incremental: true` from the config file for one run.") do |v|
       @options[:incremental] = v
     end
+    opts.on("--[no-]canary",
+            "Run a proof-of-life synthetic mutation at session start; abort if " \
+            "the pipeline misreports it (default: enabled). Use --no-canary to skip.") do |v|
+      @options[:canary] = v
+    end
     opts.on("--stdin", "Read target file paths from stdin (one per line)") { @options[:stdin] = true }
   end
 
   def add_runner_mode_options(opts)
-    opts.on("--integration NAME", "Test integration: rspec, minitest (default: rspec)") { |i| @options[:integration] = i }
+    opts.on("--integration NAME", "Test integration: rspec, minitest, test-unit (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 -> spec/spec_helper.rb -> " \

data/lib/evilution/config/validators/integration.rb

@@ -3,9 +3,13 @@
 require_relative "base"
 
 class Evilution::Config::Validators::Integration < Evilution::Config::Validators::Base
-  ALLOWED = %i[rspec minitest].freeze
+  ALLOWED = %i[rspec minitest test_unit].freeze
 
+  # CLI users naturally write the gem name `test-unit`; the internal symbol
+  # uses underscore form to match the file path and registry key. Normalize
+  # hyphenated string input before coercion.
   def self.call(value)
+    value = value.tr("-", "_") if value.is_a?(String)
     coerce_symbol!(value, allowed: ALLOWED, name: "integration")
   end
 end

data/lib/evilution/config.rb

@@ -20,7 +20,7 @@ class Evilution::Config
     example_targeting_fallback: :full_file,
     example_targeting_cache: { max_files: 50, max_blocks: 10_000 },
     quiet_children: false, quiet_children_dir: "tmp/evilution_children",
-    profile: :default
+    profile: :default, canary: true
   }.freeze
 
   attr_reader :target_files, :schema_version, :timeout, :format,
@@ -31,7 +31,7 @@ class Evilution::Config
               :skip_heredoc_literals, :related_specs_heuristic,
               :fallback_to_full_suite, :preload, :spec_mappings, :spec_pattern,
               :example_targeting, :example_targeting_fallback, :example_targeting_cache,
-              :spec_selector, :quiet_children, :quiet_children_dir, :profile
+              :spec_selector, :quiet_children, :quiet_children_dir, :profile, :canary
 
   def initialize(**options)
     skip_file = options.delete(:skip_config_file) ? true : false
@@ -68,6 +68,10 @@ class Evilution::Config
     baseline
   end
 
+  def canary?
+    canary
+  end
+
   def incremental?
     incremental
   end
@@ -130,7 +134,12 @@ class Evilution::Config
       # Minimum mutation score to pass (0.0 to 1.0, default: 0.0)
       # min_score: 0.0
 
-      # Test integration: rspec, minitest (default: rspec)
+      # Proof-of-life canary: run a synthetic, guaranteed-unobservable
+      # mutation at session start and abort if the pipeline misreports it
+      # (default: true). Set false to skip (e.g. for CI speed).
+      # canary: true
+
+      # Test integration: rspec, minitest, test_unit (default: rspec)
       # integration: rspec
 
       # Number of parallel workers (default: 1)
@@ -237,7 +246,8 @@ class Evilution::Config
     related_specs_heuristic: nil,
     fallback_to_full_suite: nil,
     quiet_children: nil,
-    quiet_children_dir: nil
+    quiet_children_dir: nil,
+    canary: nil
   }.freeze
   private_constant :SIMPLE_ATTR_TRANSFORMS
 

data/lib/evilution/integration/loading/mutation_applier.rb

@@ -56,21 +56,29 @@ class Evilution::Integration::Loading::MutationApplier
   def apply(mutation, eval_target)
     @constant_pinner.call(mutation.original_source)
     @concern_state_cleaner.call(mutation.file_path)
+    mark_feature_loaded(mutation.file_path)
     @redefinition_recovery.call(mutation.original_source) do
       @source_evaluator.call(eval_target, mutation.file_path)
     end
-    mark_feature_loaded(mutation.file_path)
   end
 
   # The mutated source is eval'd straight into the VM — `eval` does not register
-  # a `$LOADED_FEATURES` entry. If the spec then `require`s the same file (common
-  # when the project lazy-loads it and only the test references it), `require`
-  # reloads the ORIGINAL from disk and clobbers the mutation, so every mutation
-  # silently survives. Under fork isolation each worker starts from the same
-  # pre-`require` snapshot, so the whole file scores 0%. Registering the
-  # canonical path makes a later `require`/`require_relative` a no-op.
+  # a `$LOADED_FEATURES` entry. Any later `require`/`require_relative` of the
+  # same file then reloads the ORIGINAL from disk and clobbers the mutation, so
+  # every mutation silently survives. Two paths trigger that reload:
+  #   - the spec `require`s the file (it lazy-loads it and only the test
+  #     references it);
+  #   - the mutated source's OWN body `require_relative`s a sibling whose body
+  #     `require_relative`s this file back (e.g. lib/evilution/mcp/*.rb tools).
+  # The second reload happens DURING the eval, so registration must precede it:
+  # `mark_feature_loaded` runs before `@source_evaluator.call`, not after. Under
+  # fork isolation each worker starts from the same pre-`require` snapshot, so
+  # without this the whole file scores 0%.
   def mark_feature_loaded(file_path)
-    absolute = File.realpath(File.expand_path(file_path))
+    # When the isolator has chdir'd into a per-mutation sandbox (EV-wqxu /
+    # GH #1278), anchor against PROJECT_ROOT so File.realpath does not chase
+    # file_path into a non-existent /tmp path.
+    absolute = File.realpath(File.expand_path(file_path, Evilution.project_base_dir))
     $LOADED_FEATURES << absolute unless $LOADED_FEATURES.include?(absolute)
   rescue Errno::ENOENT
     nil

data/lib/evilution/integration/loading/source_evaluator.rb

@@ -13,7 +13,10 @@ require_relative "../loading"
 # substitute the mutated bytes — the privilege level is identical.
 class Evilution::Integration::Loading::SourceEvaluator
   def call(source, file_path)
-    absolute = File.expand_path(file_path)
+    # When the isolator has chdir'd into a per-mutation sandbox (EV-wqxu /
+    # GH #1278), anchor the eval __FILE__ against PROJECT_ROOT so siblings
+    # `require_relative` can find each other from the real source tree.
+    absolute = File.expand_path(file_path, Evilution.project_base_dir)
     eval(source, TOPLEVEL_BINDING, absolute, 1)
   end
 end

data/lib/evilution/integration/minitest.rb

@@ -128,7 +128,7 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
   end
 
   def execute_minitest(mutation, files, command)
-    files.each { |f| load(File.expand_path(f)) }
+    files.each { |f| load(File.expand_path(f, Evilution.project_base_dir)) }
 
     detector = reset_crash_detector
     run = run_minitest(build_args(mutation), detector)

data/lib/evilution/integration/rspec/baseline_runner.rb

@@ -5,7 +5,9 @@ require_relative "../rspec"
 class Evilution::Integration::RSpec::BaselineRunner
   def call(spec_file)
     require "rspec/core"
-    spec_dir = File.expand_path("spec")
+    # Anchor against PROJECT_ROOT under EV-wqxu sandbox CWD; see
+    # FrameworkLoader#add_spec_load_path for rationale.
+    spec_dir = File.expand_path("spec", Evilution.project_base_dir)
     $LOAD_PATH.unshift(spec_dir) unless $LOAD_PATH.include?(spec_dir)
     ::RSpec.reset
     status = ::RSpec::Core::Runner.run(

data/lib/evilution/integration/rspec/framework_loader.rb

@@ -22,7 +22,11 @@ class Evilution::Integration::RSpec::FrameworkLoader
   private
 
   def add_spec_load_path
-    spec_dir = File.expand_path("spec")
+    # Anchor against PROJECT_ROOT inside an isolated worker (EV-wqxu /
+    # GH #1278) so the project's spec/ dir lands on $LOAD_PATH — otherwise
+    # `require "spec_helper"` resolves to a non-existent sandbox/spec and
+    # every mutation errors as "loaded 0 examples".
+    spec_dir = File.expand_path("spec", Evilution.project_base_dir)
     $LOAD_PATH.unshift(spec_dir) unless $LOAD_PATH.include?(spec_dir)
   end
 end

data/lib/evilution/integration/rspec.rb

@@ -70,13 +70,50 @@ class Evilution::Integration::RSpec < Evilution::Integration::Base
     targets = @example_filter_applier.call(mutation, files)
     return @result_builder.unresolved_example(mutation) if targets.nil?
 
-    args = ["--format", "progress", "--no-color", "--order", "defined", *targets]
+    args = ["--format", "progress", "--no-color", "--order", "defined", *resolve_targets(targets)]
     command = "rspec #{args.join(" ")}"
 
     reset_examples
     execute_run(args, command)
   end
 
+  # Targets are passed straight through when they resolve against Dir.pwd,
+  # preserving the relative-path contract for callers/tests. When the CWD
+  # cannot find them — workers chdir'd into a per-mutation sandbox by the
+  # isolator (EV-wqxu / GH #1278) — the targets are expanded against
+  # Evilution::PROJECT_ROOT so RSpec::Core::Runner can still load the files.
+  def resolve_targets(targets)
+    targets.map { |target| resolve_target(target) }
+  end
+
+  # Splits a target into (path, line). RSpec example locations end in
+  # `:LINE` (or `:LINE:LINE...` for nested groups), so the suffix is
+  # anchored to the END of the string — that way path components which
+  # themselves contain colons (e.g. a Windows-style `C:/proj/spec/x.rb`)
+  # are not mis-split by a naive `partition(":")`.
+  TARGET_LINE_SUFFIX = /\A(.+?)(:\d+(?::\d+)*)\z/
+  private_constant :TARGET_LINE_SUFFIX
+
+  def resolve_target(target)
+    return target if target.start_with?("/")
+
+    if (match = TARGET_LINE_SUFFIX.match(target))
+      path = match[1]
+      line_suffix = match[2]
+    else
+      path = target
+      line_suffix = ""
+    end
+
+    return target if File.exist?(path)
+    return target unless Evilution.in_isolated_worker?
+
+    absolute = File.expand_path(path, Evilution::PROJECT_ROOT)
+    return target unless File.exist?(absolute)
+
+    "#{absolute}#{line_suffix}"
+  end
+
   def execute_run(args, command)
     detector = @crash_detector_lifecycle.current
     snapshot = @state_guard.snapshot

data/lib/evilution/integration/test_unit/dispatcher.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../test_unit"
+
+# Builds a Test::Unit::TestSuite from a list of TestCase subclasses and runs
+# it via the console runner with output captured to a StringIO. Owning this
+# responsibility separately keeps the runner library require + suite assembly
+# in one place — used by both the baseline path (Evilution::Integration::TestUnit
+# .run_baseline_test_file) and the per-mutation path (#run_tests).
+module Evilution::Integration::TestUnit::Dispatcher
+  module_function
+
+  def call(test_case_classes, name: "evilution")
+    require "test/unit/ui/console/testrunner"
+    suite = ::Test::Unit::TestSuite.new(name)
+    test_case_classes.each { |klass| suite << klass.suite }
+    out = StringIO.new
+    runner = ::Test::Unit::UI::Console::TestRunner.new(suite, output: out)
+    runner.start
+  end
+
+  def test_method_count(test_case_classes)
+    test_case_classes.sum { |klass| klass.suite.tests.length }
+  end
+end