evilution 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07051270c176d0d26e28c2978c6bfa2eb0d76dd2e6ba453387f9731f04a0d79b
-  data.tar.gz: 1562d91a064d05af5b6264c89eacf93077630bc09b4a149010d6e4e5514409ed
+  metadata.gz: 005b0edbf9ced13a00a85d07939564cec9f38d93dec0e1d923f30a9d7cb2c779
+  data.tar.gz: a7554571383f34fd21ca7d8d61f733e446d1d2c6349816267459b19309605689
 SHA512:
-  metadata.gz: 9957755214557a006e461cadd076d57b5c1d55536e9cec5105df1b1b37580150a6ff5fc8a33c816c0356a8e890eab1ac8e5fcfccac1acb6a46e18c76ba8ec909
-  data.tar.gz: 8a2a4000adbaf10f178cbed4cb117644d25bd27ec2730fb02024fa68b3cf8424181b0d5e45bbfbe53b3c9a9a37266e306de7592f16443d0d8545ad46f878f4af
+  metadata.gz: 6227ee0e3df976329f59f286b21cfaa69bbd4455d00a1fe37dc4c77a9ff553f9e2c4fa7e112b7b19d7e6cc45c5ef2f98ccb2e03f7733fbd97ff7be6ad8582c71
+  data.tar.gz: e4a36d7eaa5826c8621d042beb1bedb7c612a67118b4456a909caa1f813bb0863098b57e113684faf9a8797ac0993f2d2d2ee2ee92562376c6e3a35cbb92ecad

data/.beads/interactions.jsonl

@@ -421,3 +421,19 @@
 {"id":"int-cdc02b29","kind":"field_change","created_at":"2026-06-06T15:19:26.153490037Z","actor":"Denis Kiselev","issue_id":"EV-dlnn","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1344. Flaky /tmp glob replaced with parent-side sandbox capture (spy Dir.mktmpdir, assert the evilution-run dir gone after timeout). Deterministic, fork.rb untouched."}}
 {"id":"int-af4ca762","kind":"field_change","created_at":"2026-06-06T17:23:17.168065946Z","actor":"Denis Kiselev","issue_id":"EV-dwqw","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1345. Real carrier was RSpec.configuration @preferred_options (color_mode getter reads it first); inner Runner.run --no-color force-merges color_mode=:off in place. StateGuard::ConfigurationState snapshots @preferred_options by dup + stream ivars and restores them; in-process example re-enabled. Visual dots green, suite 4881 green."}}
 {"id":"int-f7253919","kind":"field_change","created_at":"2026-06-07T04:14:56.864785049Z","actor":"Denis Kiselev","issue_id":"EV-z7f5","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #1347 (master). opt1+2+3 + Copilot review fixes. Empirical 4-repro re-run remains under EV-rxob canary harness (the dep)."}}
+{"id":"int-41c70ee3","kind":"field_change","created_at":"2026-06-15T07:26:55.682158325Z","actor":"Denis Kiselev","issue_id":"EV-9f3b","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #1358: ProcessSupervisor unit + specs"}}
+{"id":"int-9f3581f4","kind":"field_change","created_at":"2026-06-15T08:27:50.649632334Z","actor":"Denis Kiselev","issue_id":"EV-3aw3","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #1359: Isolation::Fork routed through ProcessSupervisor"}}
+{"id":"int-9abff5aa","kind":"field_change","created_at":"2026-06-15T09:18:55.659697892Z","actor":"Denis Kiselev","issue_id":"EV-dg69","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #1360: outer path (Worker/Runner trap) routed through ProcessSupervisor; WorkerRegistry removed"}}
+{"id":"int-42f490de","kind":"field_change","created_at":"2026-06-15T11:28:14.219616586Z","actor":"Denis Kiselev","issue_id":"EV-7a91","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #1361: worker INT/TERM handler reaps inner children, kill_and_reap_all + reset_for_child!, cross-path lifecycle stress spec"}}
+{"id":"int-68e95598","kind":"field_change","created_at":"2026-06-15T11:28:31.205819027Z","actor":"Denis Kiselev","issue_id":"EV-5rrh","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"All 4 Track A steps merged: ProcessSupervisor owns spawn/register/signal-safe registry/group-kill/reap. Inner (Fork) + outer (Worker) paths routed through it; WorkerRegistry removed; Runner trap + worker trap reap on interrupt; cross-path stress spec proves no orphan/zombie."}}
+{"id":"int-0bc92dbf","kind":"field_change","created_at":"2026-06-15T11:49:47.527861306Z","actor":"Denis Kiselev","issue_id":"EV-1q84","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged: Coverage::Map + Recorder + MapBuilder (forked full-suite per-example coverage map)"}}
+{"id":"int-207eba53","kind":"field_change","created_at":"2026-06-15T12:01:00.790784019Z","actor":"Denis Kiselev","issue_id":"EV-k1xr","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged: Coverage::MapStore + Digest (per-file digest cache, prune-to-fresh partial invalidation, corrupt rebuild)"}}
+{"id":"int-1e19ca1d","kind":"field_change","created_at":"2026-06-15T13:01:49.951898163Z","actor":"Denis Kiselev","issue_id":"EV-lqqk","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #1364: CoverageExampleFilter + example_targeting_strategy config/CLI + build_example_filter wiring + executed-lines accuracy fix"}}
+{"id":"int-1e5b072e","kind":"field_change","created_at":"2026-06-15T13:37:22.697876987Z","actor":"Denis Kiselev","issue_id":"EV-51d4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #1365: scripts/compare_targeting 3-mode comparison harness (lost_kills gate + wall-time ratios) + example manifest"}}
+{"id":"int-c50dc4d6","kind":"field_change","created_at":"2026-06-15T17:19:15.781802557Z","actor":"Denis Kiselev","issue_id":"EV-7uui","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #1368: direction C — per-resolved-file coverage (absolute locations, resolved-spec capture, accuracy-first empty->lexical). factory_bot 16 lost kills -> 0"}}
+{"id":"int-2e23cd44","kind":"field_change","created_at":"2026-06-16T07:17:22.764949718Z","actor":"Denis Kiselev","issue_id":"EV-5hk5","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1373 (master)"}}
+{"id":"int-8e319322","kind":"field_change","created_at":"2026-06-16T07:17:22.312793419Z","actor":"Denis Kiselev","issue_id":"EV-bi41","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-93c675ea","kind":"field_change","created_at":"2026-06-16T07:54:16.348995872Z","actor":"Denis Kiselev","issue_id":"EV-bi41","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1374 (master)"}}
+{"id":"int-555de29c","kind":"field_change","created_at":"2026-06-16T07:54:17.438977358Z","actor":"Denis Kiselev","issue_id":"EV-z03y","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-616ccd27","kind":"field_change","created_at":"2026-06-16T09:31:30.217250542Z","actor":"Denis Kiselev","issue_id":"EV-z03y","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1375 (master). Dep on EV-rxob is provenance only; code fix shipped."}}
+{"id":"int-6d2f9b35","kind":"field_change","created_at":"2026-06-16T10:00:18.493013642Z","actor":"Denis Kiselev","issue_id":"EV-rxob","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"1.0 real-world validation complete. Rounds 2-4 ran 30+ gems across rspec/minitest/test-unit; no crash/memory blowup. All findings filed+fixed+merged: EV-z7f5/#1347, EV-gl1e/#1329, EV-52hf/#1341, EV-5hk5/#1373, EV-bi41/#1374, EV-z03y/#1375. Round-4 OOB re-verify confirmed fixes compound (state_machines 0->0.922, factory_bot/webmock/http real OOB scores, errors=0). Residual resolution-coverage gaps (behavior-named/flat-prefixed/non-std helper) tracked low-pri: EV-ajby/#1376, EV-6rbd/#1377, EV-no5u/#1378."}}

data/.rubocop_todo.yml

@@ -12,9 +12,9 @@ Metrics/ClassLength:
     - "lib/evilution/isolation/fork.rb"
     - "lib/evilution/integration/minitest.rb"
     - "lib/evilution/mcp/mutate_tool.rb"
-    - "lib/evilution/parallel/work_queue/dispatcher.rb"
     - "lib/evilution/runner.rb"
     - "lib/evilution/runner/isolation_resolver.rb"
+    - "lib/evilution/cli/parser/options_builder.rb"
 
 Metrics/MethodLength:
   Exclude:

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 Versioning policy: see [docs/versioning.md](docs/versioning.md).
 
+## [0.34.0] - 2026-06-16
+
+### Added
+
+- **Coverage-based example targeting (`--example-targeting coverage` / `example_targeting_strategy: coverage`)** — the default `lexical` strategy picks per-mutation examples by name-grepping example bodies for the mutated method/class token, which over-selects (any example that merely *mentions* the name) and under-selects (examples that exercise the code without naming it). The new `coverage` strategy instead runs exactly the examples that **execute the mutated line**, derived from a cached full-suite line-coverage map (`Coverage` stdlib), and falls back to `lexical` for any file the map has not built yet. Enable it with `--example-targeting coverage` (CLI) or `example_targeting_strategy: coverage` (`.evilution.yml`); the YAML key accepts `lexical` or `coverage`. The CLI flag additionally accepts `full_file` to run every resolved example (equivalent to `example_targeting: false` in `.evilution.yml`). See [docs/superpowers/specs/2026-06-07-coverage-based-targeting-design.md](docs/superpowers/specs/2026-06-07-coverage-based-targeting-design.md) (PRs #1364/#1365)
+- **Auto spec-resolution now expands dir-grouped test layouts (`test/unit/<class>/*_test.rb`)** — `Evilution::SpecResolver` resolved a source file only to a single mirror test file, so projects that group a class's tests in a *directory* named after the source (e.g. `state_machines`: `lib/state_machines/branch.rb` → `test/unit/branch/*_test.rb`, 51 files) resolved nothing and scored 0.0 out of the box. The resolver now also matches a grouped directory and expands it into its test files (`*_test.rb` plus the `test_*.rb` prefix convention), ranked below the deterministic file mirror so a 1:1 spec still wins. `SpecSelector` consumes the resulting list and keeps working with custom resolvers that implement only the older `#call` contract. Repro that went 0.0 → 0.92 out of the box: state_machines (EV-bi41, PR #1374, GH #1371)
+
+### Fixed
+
+- **Non-Rails gems now preload and score out-of-the-box instead of erroring on every mutation** — auto-preload fired only for Rails projects, so a plain rspec/minitest **gem** run with the default `auto` isolation got no parent-process preload (its library and test framework were never loaded), and every mutation errored with `0 examples loaded` / a `NameError` (e.g. `undefined method 'delegate'`) — a 0.0 score with a cryptic cause. `auto` isolation now resolves to `fork` when a `*.gemspec` is detected (not just a Rails root), and the non-Rails autodetect chain now prefers the conventional test helper (`spec/spec_helper.rb` → `test/test_helper.rb` → `test/helper.rb`) — which loads the library *and* the suite's framework/support setup so example groups register — falling back to the gem's `lib/<gem>.rb` entry. When a gem is detected but no conventional helper exists, evilution prints an actionable warning naming the locations it searched and the `--preload` escape hatch, instead of a silent 0%. Out-of-box repros: factory_bot, webmock, http (442 errors → real scores) (EV-z03y, PR #1375, GH #1372)
+- **Parent-process preload puts the test root on `$LOAD_PATH` for minitest/Test::Unit projects** — `IsolationResolver` only ever added `spec/` to `$LOAD_PATH` before requiring the preload file, even for `--integration minitest`. A `test/test_helper.rb` that does a non-relative `require "support/..."` (relying on the runner's `-Itest`) then failed preload with a `LoadError`. Preload is now integration-aware: rspec stays `spec/`-only (so a bare `require "support/foo"` still resolves from `spec/` in projects that have both dirs), while minitest/Test::Unit routes through `Integration::Loading::TestLoadPath` — the same policy the per-mutation test load uses — putting the test root on `$LOAD_PATH`. Repro: httprb/http (`require "support/capture_warning"`) now resolves without `RUBYOPT=-Itest` (EV-5hk5, PR #1373, GH #1370)
+- **Worker and per-mutation child process lifecycle consolidated into `ProcessSupervisor`** — process-group creation (`setpgid`), signal forwarding (SIGINT/SIGTERM → worker groups), and child reaping were spread across `Isolation::Fork`, the parallel worker, and a separate `WorkerRegistry`. They are now centralized in a single `Evilution::ProcessSupervisor`, which removes `WorkerRegistry`, tolerates benign `setpgid` races (`ESRCH`) silently, warns rather than raises on unexpected `EPERM`, and ensures sandbox cleanup on failure — closing process/FD-leak windows on interrupted or worker-recycling runs (PRs #1358 fixes GH #1337, #1360 fixes GH #1339)
+- **`WorkQueue::Dispatcher` per-worker timeout tracking extracted into `DeadlineTracker`** — the per-worker deadline bookkeeping that kills and recycles only a stuck worker (rather than aborting the whole run) is now an isolated, separately-tested `DeadlineTracker` collaborator, simplifying the dispatcher and hardening timeout management under load (PR #1369)
+
 ## [0.33.0] - 2026-06-07
 
 ### Added

data/README.md

@@ -94,10 +94,11 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `-f`, `--format FORMAT`      | String  | `text`       | Output format: `text`, `json`, or `html`.         |
 | `--target EXPR`              | String  | _(none)_     | Only mutate matching methods. Supports method name (`Foo::Bar#calculate`), class (`Foo`), namespace wildcards (`Foo::Bar*`), method-type selectors (`Foo#`, `Foo.`), descendants (`descendants:Foo`), and source globs (`source:lib/**/*.rb`). |
 | `--min-score FLOAT`          | Float   | 0.0          | Minimum mutation score (0.0–1.0) to pass.         |
-| `--spec FILES`               | Array   | _(none)_     | Spec files to run (comma-separated). Defaults to auto-detection via `SpecResolver`. |
+| `--spec FILES`               | Array   | _(none)_     | Spec files to run (comma-separated). Defaults to auto-detection via `SpecResolver`, which also resolves non-mirrored (`spec/unit`, `test/unit`) and dir-grouped (`test/unit/<class>/*_test.rb`) layouts. |
 | `--spec-dir DIR`             | String  | _(none)_     | Include all `*_spec.rb` files in DIR recursively. Composable with `--spec`. |
 | `--spec-pattern GLOB`        | String  | _(none)_     | Restrict resolved spec candidates to files matching GLOB (e.g. `spec/models/**/*_spec.rb`). |
 | `--no-example-targeting`     | Boolean | _(enabled)_  | Disable per-mutation example targeting (always run every example in the resolved spec file). Example targeting scans each example body for symbols from the mutated method and runs only the matching subset. |
+| `--example-targeting MODE`   | String  | `lexical`    | How targeting picks examples: `lexical` (name-grep example bodies for the mutated method/class), `coverage` (run only the examples that actually execute the mutated line, from a cached line-coverage map), or `full_file` (run all resolved examples). |
 | `--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`. |
@@ -113,8 +114,8 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `--no-progress`              | Boolean | _(enabled)_  | Disable the TTY progress bar.                      |
 | `--quiet-children`           | Boolean | false        | Redirect each forked worker's stdout/stderr to per-pid files under `tmp/evilution_children/<pid>.{out,err}` so noisy app initializers (Datadog, Bullet, etc.) don't merge with parent output. Trade-off: live worker errors only appear in the side files, not the terminal — `tail -f tmp/evilution_children/*.err` to watch them. |
 | `--quiet-children-dir DIR`   | String  | `tmp/evilution_children` | Override the directory used by `--quiet-children`.    |
-| `--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. Auto-detect chain for Rails projects: `spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb`. Errors with the full chain listed if none exist; pass `--no-preload` to opt out. |
+| `--isolation MODE`           | String  | `auto`       | Isolation strategy: `auto`, `fork`, or `in_process`. `auto` selects `fork` for Rails projects and packaged gems (`*.gemspec`), `in_process` otherwise. See [docs/isolation.md](docs/isolation.md). |
+| `--preload FILE`             | String  | _(auto)_     | File to require in parent before forking workers. Auto-detect chain for Rails projects: `spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb`. For non-Rails gems: `spec/spec_helper.rb` → `test/test_helper.rb` → `test/helper.rb`, falling back to the gem entry `lib/<gem>.rb` (with a warning naming the searched paths). Pass `--no-preload` to opt out. |
 | `--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. |
@@ -172,9 +173,9 @@ schema_version: 1            # opts into strict validation (rejects unknown keys
 # 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)
+# isolation: auto          # auto | fork | in_process (auto selects fork for Rails + gems)
 # 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
+# preload: null            # path to preload before forking; false to disable; auto-detects for Rails + gems
 # 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
 # baseline_session: null   # path to session file for HTML comparison
@@ -219,7 +220,7 @@ All keys recognised under `schema_version: 1`:
 | `jobs`                       | Integer                       | `1`                                    | Number of parallel workers.                                                                                                              |
 | `fail_fast`                  | Integer / null                | `null`                                 | Stop after N surviving mutants. `null` = disabled.                                                                                       |
 | `baseline`                   | Boolean                       | `true`                                 | Run baseline test suite to detect pre-existing failures (marked `:neutral`).                                                             |
-| `isolation`                  | String                        | `auto`                                 | Isolation strategy: `auto`, `fork`, `in_process`. `auto` selects `fork` for Rails projects.                                              |
+| `isolation`                  | String                        | `auto`                                 | Isolation strategy: `auto`, `fork`, `in_process`. `auto` selects `fork` for Rails projects and packaged gems (`*.gemspec`).              |
 | `incremental`                | Boolean                       | `false`                                | Cache killed/timeout results across runs.                                                                                                |
 | `suggest_tests`              | Boolean                       | `false`                                | Generate concrete test code in survivor suggestions (matches `integration`).                                                             |
 | `progress`                   | Boolean                       | `true`                                 | TTY progress bar.                                                                                                                        |
@@ -232,10 +233,11 @@ All keys recognised under `schema_version: 1`:
 | `skip_heredoc_literals`      | Boolean                       | `false`                                | Skip string literal mutations inside heredocs.                                                                                           |
 | `related_specs_heuristic`    | Boolean                       | `false`                                | Append related request/integration/feature/system specs for `includes(...)` mutations.                                                   |
 | `fallback_to_full_suite`     | Boolean                       | `false`                                | When no matching spec resolves, run the entire suite instead of marking the mutation `:unresolved`.                                      |
-| `preload`                    | String / Boolean / null       | `null`                                 | File to preload in parent before forking. `false` to disable. `null` to auto-detect for Rails.                                           |
+| `preload`                    | String / Boolean / null       | `null`                                 | File to preload in parent before forking. `false` to disable. `null` to auto-detect for Rails projects and packaged gems.                |
 | `spec_mappings`              | Hash&lt;String, String/Array&gt; | `{}`                                | Custom mapping from source path to spec path(s).                                                                                         |
 | `spec_pattern`               | String / null                 | `null`                                 | Glob restricting resolved spec candidates.                                                                                               |
 | `example_targeting`          | Boolean                       | `true`                                 | Per-mutation example-level targeting.                                                                                                    |
+| `example_targeting_strategy` | String                        | `lexical`                              | How targeting picks examples: `lexical` (name-grep) or `coverage` (examples that execute the mutated line, from a cached coverage map).  |
 | `example_targeting_fallback` | String                        | `full_file`                            | When targeting finds no example: `full_file` or `unresolved`.                                                                            |
 | `example_targeting_cache`    | Hash                          | `{ max_files: 50, max_blocks: 10000 }` | LRU cache bounds for the example-targeting AST parser.                                                                                   |
 | `quiet_children`             | Boolean                       | `false`                                | Redirect each worker's stdout/stderr to per-pid files under `quiet_children_dir`.                                                        |
@@ -670,7 +672,7 @@ Use when you know which file was modified and want to verify its test coverage.
 bundle exec evilution run lib/models/user.rb lib/models/account.rb lib/models/order.rb
 ```
 
-Pass multiple file paths on a single invocation to amortise startup cost. The framework (Rails, Sorbet, etc.) and the `preload` chain (`spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb`) load **once** in the parent process. When `--isolation=fork` is selected (the default `--isolation=auto` resolves to `fork` on Rails projects), every subsequent mutation across all files forks from that warmed parent — materially faster than scripting a `for f in ...; do bundle exec evilution run "$f"; done` loop, which pays the bootstrap per file. With `--isolation=in_process` (default for non-Rails projects under `auto`), there is no per-mutation fork, but the parent-process boot still runs once instead of N times. Per-file paths and line numbers are preserved in the report (`survived[].file`, HTML grouping by source file).
+Pass multiple file paths on a single invocation to amortise startup cost. The framework (Rails, Sorbet, etc.) and the `preload` chain (`spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb`) load **once** in the parent process. When `--isolation=fork` is selected (the default `--isolation=auto` resolves to `fork` on Rails projects and packaged gems), every subsequent mutation across all files forks from that warmed parent — materially faster than scripting a `for f in ...; do bundle exec evilution run "$f"; done` loop, which pays the bootstrap per file. With `--isolation=in_process` (default for non-Rails, non-gem projects under `auto`), there is no per-mutation fork, but the parent-process boot still runs once instead of N times. Per-file paths and line numbers are preserved in the report (`survived[].file`, HTML grouping by source file).
 
 ### 6. Fixing surviving mutants
 
@@ -773,7 +775,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** — 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
+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 (no gemspec) and fork for Rails projects and packaged gems (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, 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/isolation.md

@@ -9,7 +9,7 @@ is used.
 
 | 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. |
+| `auto`       | Default. Picks `fork` for Rails projects and packaged gems, `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. |
 
@@ -42,6 +42,15 @@ 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.
 
+`auto` also resolves to `fork` when the target files live under a packaged
+gem (a directory containing a `*.gemspec`). A gem's library and test
+framework must be loaded in the parent before forking — see [Automatic
+preload](#automatic-preload) — and `in_process` cannot preload them without
+polluting the host process. A non-Rails gem run under the old `in_process`
+default therefore produced 0 examples / 100% errors out of the box; defaulting
+gems to `fork` lets auto-preload fire (EV-z03y, PR #1375). A plain non-Rails,
+non-gem project (no gemspec) still defaults to `in_process`.
+
 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
@@ -67,7 +76,27 @@ 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)
+2. `spec/spec_helper.rb` (RSpec)
+3. `test/test_helper.rb` (Minitest)
+
+For a packaged gem (auto-detected via `*.gemspec`, no Rails root), evilution
+preloads the conventional test helper — which loads both the gem's library
+and the suite's framework/support setup so example groups register — in this
+order, falling back to the gem's library entry point (`lib/<gem>.rb`):
+
+1. `spec/spec_helper.rb` (RSpec)
+2. `test/test_helper.rb` (Minitest / Test::Unit)
+3. `test/helper.rb` (flat-layout convention)
+
+When a gem is detected but none of those helpers exist, evilution prints a
+warning naming the locations it looked in and pointing at `--preload`, so a
+non-standard test layout reads as a fixable configuration issue rather than a
+silent 0% (EV-z03y, PR #1375).
+
+Minitest/Test::Unit helpers that `require "test_helper"` (or any non-relative
+`require "support/..."`) work without `-Itest`: evilution puts the test root
+on `$LOAD_PATH` for the preload just as the test runner would (EV-5hk5, PR
+#1373).
 
 No configuration needed.
 

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

@@ -66,6 +66,11 @@ class Evilution::CLI::Parser::OptionsBuilder
             "Disable per-mutation example targeting (run all examples in resolved spec files)") do
       @options[:example_targeting] = false
     end
+    opts.on("--example-targeting MODE", %w[lexical coverage full_file],
+            "Per-mutation targeting: lexical (default, name-grep), coverage (run only the",
+            "examples that execute the mutated line), or full_file (run all resolved examples)") do |m|
+      apply_example_targeting_mode(m)
+    end
     opts.on("--example-targeting-fallback MODE", %w[full_file unresolved],
             "Fallback when example targeting finds no match: full_file (default) or unresolved") do |m|
       @options[:example_targeting_fallback] = m
@@ -77,6 +82,18 @@ class Evilution::CLI::Parser::OptionsBuilder
     end
   end
 
+  # Map the single --example-targeting flag onto the two underlying config axes:
+  # full_file is "targeting off" (run all resolved examples); lexical/coverage
+  # turn targeting on and select the strategy.
+  def apply_example_targeting_mode(mode)
+    if mode == "full_file"
+      @options[:example_targeting] = false
+    else
+      @options[:example_targeting] = true
+      @options[:example_targeting_strategy] = mode.to_sym
+    end
+  end
+
   def add_flag_options(opts)
     opts.on("--fail-fast", "Stop after N surviving mutants " \
                            "(default: disabled; if provided without N, uses 1; use --fail-fast=N)") { @options[:fail_fast] ||= 1 }

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::ExampleTargetingStrategy < Evilution::Config::Validators::Base
+  STRATEGIES = %i[lexical coverage].freeze
+
+  def self.call(value)
+    unless value.is_a?(String) || value.is_a?(Symbol)
+      raise Evilution::ConfigError,
+            "example_targeting_strategy must be lexical or coverage, got #{value.inspect}"
+    end
+
+    sym = value.to_sym
+    unless STRATEGIES.include?(sym)
+      raise Evilution::ConfigError,
+            "example_targeting_strategy must be lexical or coverage, got #{sym.inspect}"
+    end
+
+    sym
+  end
+end

data/lib/evilution/config.rb

@@ -17,7 +17,7 @@ class Evilution::Config
     show_disabled: false, baseline_session: nil, skip_heredoc_literals: false,
     related_specs_heuristic: false, fallback_to_full_suite: false, preload: nil,
     spec_mappings: {}, spec_pattern: nil, example_targeting: true,
-    example_targeting_fallback: :full_file,
+    example_targeting_fallback: :full_file, example_targeting_strategy: :lexical,
     example_targeting_cache: { max_files: 50, max_blocks: 10_000 },
     quiet_children: false, quiet_children_dir: "tmp/evilution_children",
     profile: :default, canary: true
@@ -30,7 +30,8 @@ class Evilution::Config
               :ignore_patterns, :show_disabled, :baseline_session,
               :skip_heredoc_literals, :related_specs_heuristic,
               :fallback_to_full_suite, :preload, :spec_mappings, :spec_pattern,
-              :example_targeting, :example_targeting_fallback, :example_targeting_cache,
+              :example_targeting, :example_targeting_fallback, :example_targeting_strategy,
+              :example_targeting_cache,
               :spec_selector, :quiet_children, :quiet_children_dir, :profile, :canary
 
   def initialize(**options)
@@ -104,6 +105,10 @@ class Evilution::Config
     example_targeting
   end
 
+  def coverage_targeting?
+    example_targeting && example_targeting_strategy == :coverage
+  end
+
   def fallback_to_full_suite?
     fallback_to_full_suite
   end
@@ -187,6 +192,13 @@ class Evilution::Config
       # without editing the file by exporting EV_DISABLE_EXAMPLE_TARGETING=1.
       # example_targeting: true
 
+      # How targeting picks examples (default: lexical).
+      # lexical  - text-grep resolved spec files for the mutated method/class name
+      # coverage - run exactly the examples that EXECUTE the mutated line, from a
+      #            cached full-suite line-coverage map (falls back to lexical for
+      #            any file the map has not fully built)
+      # example_targeting_strategy: lexical
+
       # Behavior when targeting finds no matching example (default: full_file).
       # full_file  - run every example in the resolved spec files
       # unresolved - mark the mutation :unresolved and skip
@@ -275,6 +287,7 @@ class Evilution::Config
   def assign_example_targeting(merged)
     @example_targeting          = merged[:example_targeting] ? true : false
     @example_targeting_fallback = Validators::ExampleTargetingFallback.call(merged[:example_targeting_fallback])
+    @example_targeting_strategy = Validators::ExampleTargetingStrategy.call(merged[:example_targeting_strategy])
     @example_targeting_cache    = Validators::ExampleTargetingCache.call(merged[:example_targeting_cache])
   end
 end
@@ -294,6 +307,7 @@ require_relative "config/validators/ignore_patterns"
 require_relative "config/validators/spec_pattern"
 require_relative "config/validators/spec_mappings"
 require_relative "config/validators/example_targeting_fallback"
+require_relative "config/validators/example_targeting_strategy"
 require_relative "config/validators/example_targeting_cache"
 require_relative "config/validators/profile"
 require_relative "config/builders"

data/lib/evilution/coverage/digest.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../coverage"
+
+# Stable, content-addressed digest of a source file, used by MapStore to detect
+# when a cached coverage entry has gone stale. Path-independent: the digest
+# depends only on the bytes, so moving a file does not invalidate it. Returns
+# nil for a missing file so callers treat it as "not fresh".
+class Evilution::Coverage::Digest
+  def for_file(path)
+    return nil unless File.file?(path)
+
+    ::Digest::SHA256.hexdigest(File.binread(path))
+  end
+end

data/lib/evilution/coverage/map.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../coverage"
+
+# Immutable query over a per-example line-coverage index:
+#   source file -> line -> [example locations ("spec.rb:line")].
+# built_files records the source files for which the build completed, so
+# callers can distinguish "line genuinely uncovered" (file built, no entry)
+# from "we never built this file" (must fall back, not assert a gap).
+class Evilution::Coverage::Map
+  def self.from_h(hash)
+    index = (hash["index"] || {}).transform_values do |lines|
+      lines.transform_keys(&:to_i)
+    end
+    executed = (hash["executed_lines"] || {}).transform_values { |lines| lines.map(&:to_i) }
+    new(index: index, built_files: hash["built_files"] || [], executed_lines: executed)
+  end
+
+  # executed_lines records, per file, the lines that ran at all during the build
+  # (including lines covered only at load, e.g. a `def` line, which are
+  # attributed to no single example). It lets a caller tell a TRUE coverage gap
+  # (line never executed) from a load-covered line an example may still exercise
+  # indirectly -- so the latter falls back instead of being mis-skipped.
+  def initialize(index:, built_files:, executed_lines: {})
+    @index = deep_freeze_index(index)
+    @built_files = built_files.to_a.freeze
+    @executed_lines = deep_freeze_executed(executed_lines)
+    freeze
+  end
+
+  def examples_for(file, line)
+    @index.dig(file, line) || []
+  end
+
+  def built?(file)
+    @built_files.include?(file)
+  end
+
+  def executed?(file, line)
+    lines = @executed_lines[file]
+    !lines.nil? && lines.include?(line)
+  end
+
+  def to_h
+    { "index" => @index, "built_files" => @built_files, "executed_lines" => @executed_lines }
+  end
+
+  private
+
+  def deep_freeze_index(index)
+    index.each_with_object({}) do |(file, lines), out|
+      frozen_lines = lines.each_with_object({}) do |(line, locs), inner|
+        inner[line] = locs.uniq.sort.freeze
+      end
+      out[file] = frozen_lines.freeze
+    end.freeze
+  end
+
+  def deep_freeze_executed(executed)
+    executed.each_with_object({}) do |(file, lines), out|
+      out[file] = lines.map(&:to_i).uniq.sort.freeze
+    end.freeze
+  end
+end

data/lib/evilution/coverage/map_builder.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "coverage"
+require "stringio"
+require_relative "../coverage"
+require_relative "map"
+require_relative "recorder"
+
+# Builds a per-example coverage Map by running the given spec files under
+# ::Coverage (lines mode) with the Recorder installed as an around(:each)
+# hook. The run happens in a FORKED CHILD so the global ::RSpec.configure
+# hook, ::RSpec.world mutation, and ::Coverage state never leak into the
+# calling process; the parent receives only the serialized map over a pipe.
+class Evilution::Coverage::MapBuilder
+  LOCATION_LINE_SUFFIX = /\A(.+?)(:\d+(?::\d+)*)\z/
+
+  # RSpec reports example locations relative to its run dir as "./spec/x.rb:5".
+  # Store them ABSOLUTE (path expanded against the project root, line suffix
+  # preserved) so they replay regardless of the per-mutation run's CWD --
+  # Integration::RSpec#resolve_target passes absolute targets through unchanged.
+  def self.absolute_location(raw, root)
+    match = LOCATION_LINE_SUFFIX.match(raw)
+    path, suffix = match ? [match[1], match[2]] : [raw, ""]
+    "#{File.expand_path(path, root)}#{suffix}"
+  end
+
+  def initialize(spec_files:, target_files:, project_root: Evilution::PROJECT_ROOT)
+    @spec_files = spec_files
+    @target_files = target_files
+    @project_root = project_root.to_s
+  end
+
+  def call
+    read_io, write_io = IO.pipe
+    read_io.binmode
+    write_io.binmode
+    pid = fork do
+      read_io.close
+      Marshal.dump(build_in_child.to_h, write_io)
+      write_io.close
+      exit!(0)
+    end
+    write_io.close
+    payload = read_io.read
+    read_io.close
+    Process.wait(pid)
+    # Trust boundary: payload is a Marshal dump this process's own forked child
+    # produced over a private pipe -- same rationale as Channel::Frame.
+    Evilution::Coverage::Map.from_h(Marshal.load(payload))
+  end
+
+  private
+
+  # Runs entirely inside the forked child.
+  def build_in_child
+    recorder = Evilution::Coverage::Recorder.new(target_files: @target_files)
+    ::Coverage.start(lines: true) unless ::Coverage.running?
+    # The child inherited the parent's fully-loaded RSpec.world; wipe it so the
+    # nested runner executes ONLY @spec_files and never re-enters the host suite
+    # (which would recursively fork this builder).
+    reset_world
+    install_hook(recorder)
+    ::RSpec::Core::Runner.run(@spec_files, StringIO.new, StringIO.new)
+    recorder.to_map(built_files: @target_files)
+  end
+
+  def reset_world
+    ::RSpec.respond_to?(:clear_examples) ? ::RSpec.clear_examples : ::RSpec.reset
+  end
+
+  def install_hook(recorder)
+    root = @project_root
+    ::RSpec.configure do |config|
+      config.around(:each) do |example|
+        location = Evilution::Coverage::MapBuilder.absolute_location(
+          example.metadata[:location].to_s, root
+        )
+        recorder.around_example(location) { example.run }
+      end
+    end
+  end
+end

data/lib/evilution/coverage/map_store.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "../coverage"
+require_relative "map"
+require_relative "digest"
+
+# Disk cache for a per-example coverage Map under .evilution/coverage/, keyed by
+# a per-file content digest so a map survives across runs and invalidates one
+# file at a time.
+#
+# load is partial: it returns a Map pruned to the files whose on-disk content
+# still matches the cached digest. A stale or deleted file is dropped (so its
+# `built?` is false and the caller falls back to lexical targeting) while every
+# fresh file stays queryable. A missing or corrupt cache returns nil, signalling
+# the caller to rebuild from scratch.
+class Evilution::Coverage::MapStore
+  DEFAULT_ROOT = ".evilution/coverage"
+  CACHE_FILE = "map.json"
+
+  def initialize(root: DEFAULT_ROOT, digest: Evilution::Coverage::Digest.new)
+    @root = root
+    @digest = digest
+  end
+
+  def save(map, source_files)
+    payload = { "digests" => digests_for(source_files), "map" => map.to_h }
+    FileUtils.mkdir_p(@root)
+    File.write(cache_path, JSON.generate(payload))
+  end
+
+  def load(source_files)
+    payload = read_payload
+    return nil unless payload
+
+    cached_digests = payload["digests"] || {}
+    fresh = source_files.select { |file| fresh?(file, cached_digests) }
+    pruned_map(payload["map"] || {}, fresh)
+  end
+
+  # Source files whose on-disk content no longer matches the cache (changed,
+  # deleted, or never cached) -- the caller rebuilds these. Every file is stale
+  # when there is no cache at all.
+  def stale_files(source_files)
+    payload = read_payload
+    return source_files.dup unless payload
+
+    cached_digests = payload["digests"] || {}
+    source_files.reject { |file| fresh?(file, cached_digests) }
+  end
+
+  private
+
+  def fresh?(file, cached_digests)
+    cached = cached_digests[file]
+    !cached.nil? && cached == @digest.for_file(file)
+  end
+
+  def pruned_map(raw_map, fresh_files)
+    index = (raw_map["index"] || {}).slice(*fresh_files)
+    built = (raw_map["built_files"] || []) & fresh_files
+    executed = (raw_map["executed_lines"] || {}).slice(*fresh_files)
+    Evilution::Coverage::Map.from_h(
+      "index" => index, "built_files" => built, "executed_lines" => executed
+    )
+  end
+
+  def digests_for(source_files)
+    source_files.each_with_object({}) do |file, out|
+      digest = @digest.for_file(file)
+      out[file] = digest unless digest.nil?
+    end
+  end
+
+  def read_payload
+    return nil unless File.file?(cache_path)
+
+    JSON.parse(File.read(cache_path))
+  rescue JSON::ParserError, Errno::ENOENT
+    nil
+  end
+
+  def cache_path
+    File.join(@root, CACHE_FILE)
+  end
+end