mutineer 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d61c927b33961995a0d38b691cdf0b34a6e9041213980c0cd7a3a01f457f875
-  data.tar.gz: 8e4f32e923344837ab664805a3099a9e67d405bbe7b63d83986d1af0b488ead5
+  metadata.gz: 2dd1784f527b49eaed8d13a3e03c59c8a30082a44cf625f3a6ce1f252ffb3a60
+  data.tar.gz: 164d53165ea6f85c31158783ea43f8f2c88c3df058240d748df01f960da23897
 SHA512:
-  metadata.gz: 5ea750d511b52ef0f9d320c39ef0b4a3b51189116c09811b3bf4f2d5752b026d1ddc62411387a261f6f60ba73e23e2b76af1e553a745bd63f9a3d56a0cd068cb
-  data.tar.gz: 6dc10950ea34998e459e5007095bd43df87a633a4ca18e19afee1812a8fed154e086f3ae3a7b808bd84ba93336bb61208195d001efd846fea367502a23167ef2
+  metadata.gz: a8bcaae29c133ca1ac0f9da31dc143b7b5deeef347104e209386cf6029252e77586d1240440e97bcec082e9e11a355087ffda91e7ca5495de85ac0f6bf1c2155
+  data.tar.gz: 06f108bfbb0f4b32318ca120e086ce88516b036ebc622e37b81963f4f93b7a87d5cdb6403b95cd69aa7a196e910718ba52b632d376a10f2763bf05f9f94a8fc8

data/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.11.0] - 2026-07-02
+
+### Added
+- **`--daemon` backend — fast, parallel-safe Rails mutation testing** (#26/#27
+  Phase 2). Boots the app **once** in a persistent daemon and forks per mutant
+  (restoring shared-boot speed), and gives **each parallel worker its own
+  database** so `--jobs N` is safe under Rails for the first time — parallel
+  verdicts are proven identical to serial (no fixture cross-talk). Coverage
+  narrowing is restored on this path (each mutant runs only its covering tests;
+  a mutant on an uncovered line is `no_coverage`), so the daemon score is
+  comparable to the in-process `--rails` score. Opt in with `--rails --daemon`
+  (also `daemon: true` in `.mutineer.yml`); `--daemon` can't be combined with
+  `--test-command`. **SQLite** today (hermetic, CI-proven); **Postgres**
+  per-worker provisioning is in progress (#34/#35). The gem core stays Prism +
+  stdlib, zero runtime dependencies — worker-DB routing uses the app's own
+  ActiveRecord.
+
+## [0.10.0] - 2026-07-02
+
+### Added
+- **`--test-command` external backend** (#27) — mutation-test apps pinned to Ruby
+  < 3.4. Mutineer stays on ≥ 3.4 but runs your suite as a subprocess in the app's
+  own runtime via `--test-command "bundle exec rails test %{files}"` (`%{files}`
+  expands to the `--test` paths; env is inherited). The mutant is applied on disk
+  with crash-safe backup/restore (self-heals a hard-killed run on next startup); a
+  smoke check aborts before scoring if the unmutated suite isn't green. This path
+  is reload-only, serial (`--jobs` forced to 1), and does no coverage narrowing —
+  so its score is an upper bound, not comparable to an in-process `--rails` score
+  (Mutineer prints this caveat). Also settable as `test_command:` in `.mutineer.yml`.
+  Safe parallelism for this path is tracked in #26.
+
 ## [0.9.1] - 2026-07-01
 
 ### Fixed
@@ -184,6 +217,8 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[0.11.0]: https://github.com/davidteren/mutineer/releases/tag/v0.11.0
+[0.10.0]: https://github.com/davidteren/mutineer/releases/tag/v0.10.0
 [0.9.1]: https://github.com/davidteren/mutineer/releases/tag/v0.9.1
 [0.9.0]: https://github.com/davidteren/mutineer/releases/tag/v0.9.0
 [0.8.0]: https://github.com/davidteren/mutineer/releases/tag/v0.8.0

data/README.md

@@ -56,6 +56,8 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 | `--jobs N` | Parallel worker count (default: processor count; `1` under `--rails`) |
 | `--verbose` | Surface the real error when a fork capture fails (alias `--debug`) |
 | `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
+| `--test-command CMD` | Run the suite as a subprocess in the app's own runtime (for apps on Ruby < 3.4); `CMD` must contain `%{files}`. See [Apps on Ruby < 3.4](#apps-on-ruby--34) |
+| `--daemon` | Boot the app once in a persistent daemon and fork per mutant, with per-worker DB isolation so `--jobs N` is safe under Rails (needs `--rails`/`--boot`; not with `--test-command`). See [the daemon backend](#faster-parallel-safe-rails-the---daemon-backend) |
 | `--format human\|json\|html` | Report format (default: human; `html` is a self-contained file) |
 | `--output FILE` | Write the report to FILE instead of stdout |
 | `--dry-run` | List candidate mutations without executing (honors suppression) |
@@ -103,6 +105,68 @@ Add Mutineer to your Gemfile's test group:
 gem "mutineer", group: :test, require: false
 ```
 
+### Faster, parallel-safe Rails (the `--daemon` backend)
+
+`--rails` boots your app once but runs mutants **serially** — parallel `--jobs`
+under Rails is unsafe, because every worker shares one test database and clobbers
+the others' fixtures. `--daemon` fixes both: it boots the app once in a persistent
+helper and forks per mutant, and gives **each parallel worker its own database**,
+so `--jobs N` is safe and its verdicts are proven identical to a serial run.
+
+```sh
+RAILS_ENV=test bundle exec mutineer run \
+  app/models/order.rb --test test/models/order_test.rb \
+  --rails --daemon --jobs 4
+```
+
+- **One boot, forked per mutant** — restores the shared-boot speed.
+- **Coverage-guided** — each mutant runs only its covering tests (like `--rails`);
+  a mutant on an uncovered line is `no_coverage`, so the score stays comparable to
+  the in-process `--rails` score.
+- **Safe `--jobs N`** — each worker routes to its own copy of the test database, so
+  parallel verdicts equal serial (no fixture cross-talk).
+- **One backend at a time** — `--daemon` can't be combined with `--test-command`
+  (choose one), and it needs an app to boot (`--rails` or `--boot`).
+
+Status: **SQLite** today (hermetic, CI-proven). **Postgres** per-worker
+provisioning is in progress (#34/#35); until it lands, use `--daemon` with a
+SQLite test database, or drop `--jobs` to run serially on other adapters.
+
+### Apps on Ruby < 3.4
+
+Mutineer's own process needs Ruby ≥ 3.4 (it parses with stdlib Prism), and the
+`--rails` path above boots your app *inside Mutineer's process* — so it can't run
+against an app pinned to an older Ruby (`ruby "3.1.6"` in the Gemfile), where the
+bundle rejects 3.4.
+
+`--test-command` decouples the two: Mutineer stays on ≥ 3.4, but your suite runs
+as a **subprocess in your app's own runtime** (whatever Ruby its bundle resolves
+to). Run Mutineer with a 3.4+ Ruby and hand it the command that runs your tests:
+
+```sh
+RAILS_ENV=test mutineer run app/models/order.rb \
+  --test test/models/order_test.rb \
+  --test-command "bundle exec rails test %{files}"
+```
+
+- **`%{files}`** is required; it expands to the `--test` paths as separate
+  arguments (a path with a space stays one argument — there is no shell).
+- **Environment** is inherited by the subprocess, so set it on the Mutineer
+  command (e.g. the leading `RAILS_ENV=test` above). Don't put `KEY=val` inside
+  `--test-command`.
+
+Tradeoffs (Phase 1) — this path is correct but not free:
+
+- **Slower:** your app re-boots for every mutant (no shared boot yet).
+- **No coverage narrowing:** every mutant runs the *full* `--test` set, so the
+  score is an **upper bound and not comparable to an in-process (`--rails`)
+  score** — uncovered mutants count as survivors, and an infrastructure failure
+  is scored as a kill. Mutineer prints this caveat on every run and aborts up
+  front (a "smoke check") if your unmutated suite isn't green.
+- **Reload strategy only** (`--strategy redefine` is rejected on this path) and
+  **serial** (`--jobs` is forced to 1). For apps on Ruby ≥ 3.4, `--daemon` gives
+  safe parallelism instead (see [the daemon backend](#faster-parallel-safe-rails-the---daemon-backend)).
+
 ## Suppressing equivalent mutants
 
 Some mutants are equivalent (behaviour-identical) and survive forever — keeping a
@@ -166,7 +230,9 @@ walking up). CLI flags override config; config overrides defaults.
 
 Sources are positional CLI arguments and test files come from `--test`; the
 config file accepts these keys: `operators`, `threshold`, `jobs`, `only`,
-`require` (extra files to load before mutating), and `boot`/`rails`.
+`require` (extra files to load before mutating), `boot`/`rails`, and
+`test_command` (the external-runtime suite command — see
+[Apps on Ruby < 3.4](#apps-on-ruby--34)).
 
 ```yaml
 # .mutineer.yml

data/lib/mutineer/cli.rb

@@ -47,6 +47,13 @@ module Mutineer
         --boot FILE          Require FILE once in the parent to boot the app env, then
                              fork per mutant (Rails apps; requires --test)
         --rails              Sugar for --boot config/environment --strategy redefine
+        --test-command CMD   Run the target suite in the app's own runtime as a
+                             subprocess (for apps on Ruby < 3.4). CMD must contain
+                             %{files} (expands to the --test paths). Env is inherited,
+                             e.g. RAILS_ENV=test mutineer run ... --test-command "..."
+        --daemon             Boot the app ONCE in a persistent daemon and fork per
+                             mutant, with per-worker DB isolation so --jobs N is safe
+                             under Rails (needs --rails/--boot; not with --test-command)
         --format human|json|html  Report format (default: human)
         --output FILE        Write the report to FILE instead of stdout
         --dry-run            List mutations without executing
@@ -105,6 +112,12 @@ module Mutineer
         # typed (CLI wins over the file). --baseline-epsilon is CLI-only.
         o.on("--baseline FILE") { |v| opts[:baseline] = v; explicit << :baseline }
         o.on("--baseline-epsilon FLOAT") { |v| opts[:baseline_epsilon] = v.to_f }
+        # #27: run the target suite as a subprocess in the app's OWN runtime so
+        # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
+        o.on("--test-command CMD") { |v| opts[:test_command] = v; explicit << :test_command }
+        # #26/#27 Phase 2: boot the app ONCE in a persistent daemon and fork per
+        # mutant, with per-worker DB isolation so --jobs N is safe under Rails.
+        o.on("--daemon") { opts[:daemon] = true; explicit << :daemon }
       end
 
       begin
@@ -188,6 +201,11 @@ module Mutineer
     rescue Mutineer::ParseError => e
       warn "mutineer: error reading: #{e.message}"
       exit 1
+    rescue Mutineer::SmokeCheckError => e
+      # #27: the unmutated suite isn't green under --test-command — a broken
+      # environment, not weak tests. Runtime error (exit 1), not usage (exit 2).
+      warn "mutineer: #{e.message}"
+      exit 1
     end
 
     # Flag validation: every flag/usage failure exits 2 (C7), consistent with the
@@ -229,6 +247,9 @@ module Mutineer
         exit 2
       end
 
+      validate_test_command!(config) if config.test_command
+      validate_daemon!(config, explicit) if config.daemon
+
       validate_since!(config) if config.since
       preflight_output!(config.output) if config.output
       preflight_baseline!(config.baseline) if config.baseline
@@ -250,6 +271,66 @@ module Mutineer
       validate_paths!(config)
     end
 
+    # #27: --test-command runs the target suite in the app's own runtime. Validate
+    # its shape up front (usage errors → exit 2) and force serial execution: each
+    # subprocess boots the app and opens its own fixture transaction against the
+    # same DB, so --jobs > 1 would corrupt results (the #12 fixture-contention
+    # hazard). Unlike --rails, this path has NO per-worker DB isolation to opt into,
+    # so an explicit --jobs N is forced to 1 rather than honored (KTD-5).
+    # Validates the --test-command configuration.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
+    def self.validate_test_command!(config)
+      if config.test_command.strip.empty?
+        warn "mutineer: --test-command must not be empty"
+        exit 2
+      end
+      unless config.test_command.include?("%{files}")
+        warn "mutineer: --test-command must contain %{files} (where the --test paths are substituted)"
+        exit 2
+      end
+      if config.boot
+        warn "mutineer: --test-command cannot be combined with --boot/--rails " \
+             "(the external subprocess boots the app itself)"
+        exit 2
+      end
+      if config.strategy == "redefine"
+        warn "mutineer: --test-command supports only --strategy reload " \
+             "(surgical redefine needs a shared VM; the subprocess has its own)"
+        exit 2
+      end
+      return unless config.jobs > 1
+
+      warn "[mutineer] --test-command runs serially (no per-worker DB isolation yet); forcing --jobs 1."
+      config.jobs = 1
+    end
+
+    # #26/#27 Phase 2 (U8): --daemon selects the persistent-daemon backend (boot once,
+    # fork per mutant, per-worker DB isolation). Two usage errors, both exit 2 (KTD-10):
+    # it cannot be combined with --test-command (choose ONE backend — never silently
+    # pick one), and it requires an app to boot (--rails or --boot). Under Rails,
+    # Config.resolve already keeps --jobs serial unless the user explicitly asks for
+    # parallelism, and each worker gets its own SQLite database on demand — so there is
+    # no "missing worker DB" precondition to check here for SQLite. Postgres worker-DB
+    # provisioning + its missing-DB error (KTD-9) arrives with the Postgres adapter (U10).
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @param explicit [Set<Symbol>] explicit CLI fields.
+    # @return [void]
+    def self.validate_daemon!(config, _explicit = Set.new)
+      if config.test_command
+        warn "mutineer: choose one backend — --daemon and --test-command cannot be combined"
+        exit 2
+      end
+      return if config.rails || config.boot
+
+      warn "mutineer: --daemon needs an app to boot; add --rails (or --boot FILE)"
+      exit 2
+    end
+
     # --since needs a real git repo and a resolvable ref; either failure is a
     # usage error (exit 2) so CI sees "bad invocation," not "tests too weak."
     # Validates the --since ref.
@@ -377,6 +458,25 @@ module Mutineer
       reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
                       format: config.format, output: config.output, baseline: delta)
 
+      # #27/KTD-6: warn (stderr, so it never pollutes json/html) that an external
+      # run's score is not comparable to an in-process run — it has no coverage
+      # narrowing, so uncovered mutants count as survivors, and an infra failure is
+      # scored as a kill (upper bound).
+      if config.test_command
+        warn "[mutineer] --test-command score is an upper bound, not comparable to an " \
+             "in-process run: no coverage narrowing (uncovered mutants count as survivors) " \
+             "and an infra failure is scored as a kill."
+      end
+
+      # #26/U8: same disclosure as --test-command above — the daemon backend has no
+      # coverage narrowing yet (Phase 2c), so this score is a lower bound (uncovered
+      # mutants count as survivors) and not comparable to an in-process run.
+      if config.daemon
+        warn "[mutineer] --daemon score is a lower bound, not comparable to an " \
+             "in-process run: no coverage narrowing yet (uncovered mutants count as " \
+             "survivors)."
+      end
+
       # #14: nudge toward the opt-in tier-2 operators (human report only — never
       # pollute JSON output).
       if !%w[json html].include?(config.format) && (hint = tier2_hint(config.operators))

data/lib/mutineer/config.rb

@@ -25,13 +25,16 @@ module Mutineer
     :cache_dir, :project_root, :load_paths,
     :jobs, :format, :output, :strategy, :require_paths,
     :boot, :rails, :since, :framework, :verbose, :ignore,
-    :baseline, :baseline_epsilon, :fail_fast,
+    # :daemon is user-facing as of U8 (--daemon flag + KNOWN_KEYS + boolean coerce).
+    # :daemon_timeout stays programmatic (set by tests/Runner; no flag yet).
+    :baseline, :baseline_epsilon, :fail_fast, :test_command,
+    :daemon, :daemon_timeout,
     keyword_init: true
   ) do
     # Config file name.
     CONFIG_FILE = ".mutineer.yml"
     # Keys accepted in .mutineer.yml (R7). `require` maps to the :require_paths field.
-    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast].freeze
+    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast test_command daemon].freeze
 
     def initialize(**kwargs)
       super
@@ -51,6 +54,7 @@ module Mutineer
       self.ignore        ||= []
       self.baseline_epsilon ||= 0.0
       self.fail_fast     = false if fail_fast.nil?
+      self.daemon        = false if daemon.nil?
     end
 
     # Walk from `start` toward `home`, returning the first .mutineer.yml path found
@@ -163,9 +167,11 @@ module Mutineer
       when "boot"      then value.to_s
       when "framework" then value.to_s
       when "rails"     then value == true || value.to_s == "true"
+      when "daemon"    then value == true || value.to_s == "true"
       when "verbose"   then value == true || value.to_s == "true"
       when "ignore"    then Array(value).map(&:to_s)
       when "baseline"  then value.to_s
+      when "test_command" then value.to_s
       else value
       end
     end

data/lib/mutineer/coverage_map.rb

@@ -21,7 +21,24 @@ module Mutineer
   class CoverageMap
     DEFAULT_CAPTURE_TIMEOUT = 120 # seconds, per coverage subprocess (R3)
 
-    attr_reader :project_root, :failed_test_files, :phase_a_ran
+    attr_reader :project_root, :failed_test_files, :phase_a_ran, :map
+
+    # Build a QUERY-ONLY map from data captured elsewhere (the daemon builds the map
+    # app-side and ships `map` + `failed_test_files` over IPC; the tool reconstructs it
+    # here for per-mutant selection). Skips the capture machinery entirely — only the
+    # three fields #tests_for / #method_uncapturable? read are set (U7).
+    #
+    # @param map [Hash] the "file:line" => [test_files] map.
+    # @param failed_test_files [Array<String>] test files whose capture failed.
+    # @param project_root [String] project root (for path relativization).
+    # @return [Mutineer::CoverageMap] a query-only map.
+    def self.from_data(map:, failed_test_files:, project_root:)
+      instance = allocate
+      instance.instance_variable_set(:@map, map || {})
+      instance.instance_variable_set(:@failed_test_files, failed_test_files || [])
+      instance.instance_variable_set(:@project_root, project_root)
+      instance
+    end
 
     def initialize(source_paths:, test_paths:, cache_dir: ".mutineer",
                    load_paths: ["lib"], project_root: Dir.pwd,
@@ -54,9 +71,9 @@ module Mutineer
     # the booted parent instead. Inverts into the same map #tests_for reads, and
     # reuses the digest cache (the digest mixes in the boot file so a boot cache
     # never collides with a standalone one).
-    def build_via_fork(rails: false)
+    def build_via_fork(after_fork: nil)
       warn_external_sources
-      cached_or { run_phase_a_via_fork(rails: rails) }
+      cached_or { run_phase_a_via_fork(after_fork: after_fork) }
     end
 
     # Phase B lookup: the test files that cover `file:line`, or [] when none do.
@@ -159,7 +176,7 @@ module Mutineer
     # per-source coverage counts. record() inverts them exactly as the subprocess
     # path does. ponytail: serial fork (one test at a time) — boot apps fork
     # cheaply via COW and per-test isolation matters more than throughput here.
-    def run_phase_a_via_fork(rails:)
+    def run_phase_a_via_fork(after_fork:)
       @phase_a_ran = true
       @map = {}
       @failed_test_files = []
@@ -169,7 +186,7 @@ module Mutineer
         # Tri-state payload (KTD-1): Hash = coverage, String = error diagnostic
         # from the child, nil = pipe gone / empty.
         # ponytail/#9: this String diagnostic is what #9 turns into an :uncapturable status.
-        case (coverage = fork_capture(absolute(test_path), abs_sources, rails))
+        case (coverage = fork_capture(absolute(test_path), abs_sources, after_fork))
         when Hash   then record(coverage, test_path)
         when String
           fail_test(test_path, @verbose ? "fork capture failed: #{coverage}" :
@@ -182,7 +199,7 @@ module Mutineer
     # Fork the booted parent, run one test under the inherited Coverage, and
     # return its per-source counts hash (or nil on failure). Reuses the same
     # fork + Marshal-over-pipe + hard-exit! discipline as WorkerPool/Isolation.
-    def fork_capture(abs_test, abs_sources, rails)
+    def fork_capture(abs_test, abs_sources, after_fork)
       rd, wr = IO.pipe
       # #19: Marshal output is binary — an un-binmoded pipe can raise
       # Encoding::UndefinedConversionError on write, which the child's rescue then
@@ -193,7 +210,10 @@ module Mutineer
         rd.close
         payload =
           begin
-            Runner.send(:reconnect_active_record) if rails
+            # Fork-safety hook: the in-process path reconnects AR; the daemon routes
+            # to its worker DB. Nil (non-Rails) = no-op. Injected so this file needs
+            # neither Runner (Prism) nor Rails.
+            after_fork&.call
             Coverage.result(clear: true, stop: false) # discard pre-test delta
             TestRunners.for(@framework).run([abs_test])
             # lines:true yields {file => {lines: [...]}}; reduce to the counts

data/lib/mutineer/daemon_client.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Mutineer
+  # Raised when the daemon cannot be booted (bad boot path, app error, or it dies on
+  # the handshake). The CLI maps it to a runtime error.
+  class DaemonBootError < StandardError; end
+
+  # #26/#27 Phase 2a — the TOOL-side handle for the app-side daemon.
+  #
+  # Spawns `daemon_server.rb` UNDER THE APP'S BUNDLE/RUBY (cleaned env so the gem's
+  # bundler context never leaks; the daemon file is loaded by absolute path with
+  # `-r`, which bypasses the app bundle that has no mutineer), completes the ready
+  # handshake, then ships per-mutant payloads and reads structured verdicts. If the
+  # daemon dies mid-run it respawns (bounded) and marks the in-flight mutant `error`
+  # rather than corrupting the run. Reuses the cleaned-env spawn + stderr-drain proven
+  # in the spike driver and the spawn discipline of ExternalBackend.
+  class DaemonClient
+    # Absolute path to the daemon entry, loaded app-side by `-r` (bypasses the bundle).
+    DAEMON_PATH = File.expand_path("daemon_server.rb", __dir__)
+    # How many times to respawn a crashing daemon before aborting the run.
+    MAX_RESTARTS = 3
+
+    # @param boot [Hash] boot config sent to the daemon: project_root, boot,
+    #   load_paths, framework, rails.
+    # @param app_root [String] directory to spawn the daemon in (the app root).
+    # @param ruby_version [String, nil] RBENV_VERSION for the app's Ruby (nil = inherit).
+    # @param gemfile [String, nil] BUNDLE_GEMFILE for the app's bundle (nil = app_root/Gemfile).
+    # @param errio [IO] where daemon stderr is drained.
+    def initialize(boot:, app_root:, ruby_version: nil, gemfile: nil, errio: $stderr)
+      @boot = boot
+      @app_root = app_root
+      @ruby_version = ruby_version
+      @gemfile = gemfile || File.join(app_root, "Gemfile")
+      @errio = errio
+      @restarts = 0
+    end
+
+    # Spawn the daemon and complete the ready handshake. Raises DaemonBootError on
+    # failure (surfaced by the CLI as a clean runtime error, not a hang).
+    #
+    # @return [self]
+    def start
+      spawn_daemon
+      self
+    end
+
+    # Run one mutant: ship the payload + covering tests, return the verdict string.
+    # On a daemon crash (EOF/dead pipe) respawn (bounded) and return `"error"` for
+    # this mutant — never a wrong verdict, never a wedged run.
+    #
+    # @param id [Integer] request id (echoed back for ordering safety).
+    # @param payload [Hash] {"code" => mutated ruby, "source_file" => path}.
+    # @param tests [Array<String>] covering test file paths.
+    # @param timeout [Numeric] per-mutant wall-clock timeout (seconds).
+    # @param worker [Integer] worker slot; the daemon routes the fork to
+    #   `<db>-<worker>` (#26 isolation). Defaults to 0 (serial in U5).
+    # @return [String] one of survived/killed/error/timeout.
+    def request(id:, payload:, tests:, timeout:, worker: 0)
+      # A crash can surface on the WRITE (daemon died idle between requests →
+      # Errno::EPIPE) as well as the read (EOF), so guard both: either way, respawn
+      # for future mutants and score THIS one error (re-running a crash-causing
+      # mutant could loop). Never let a dead pipe abort the whole run.
+      reply =
+        begin
+          send_line("id" => id, "worker" => worker, "payload" => payload, "tests" => tests, "timeout" => timeout)
+          read_line
+        rescue Errno::EPIPE, IOError
+          nil
+        end
+      return reply["verdict"] if reply && reply["id"] == id
+
+      restart!
+      "error"
+    end
+
+    # #26/U7: ask the daemon to build the coverage map app-side and return it.
+    # One-shot control message (no id). Returns `{"map"=>..., "failed_test_files"=>...}`
+    # (possibly with an `"error"`), or nil if the daemon vanished — the caller then
+    # falls back to running the full test set (no narrowing) rather than mis-scoring.
+    #
+    # @return [Hash, nil] the coverage payload, or nil on a dead pipe.
+    def coverage
+      send_line("cmd" => "coverage")
+      read_line
+    rescue Errno::EPIPE, IOError
+      nil
+    end
+
+    # Graceful shutdown; leaves no orphaned daemon/child.
+    #
+    # @return [void]
+    def quit
+      return unless @stdin
+
+      send_line("cmd" => "quit") rescue nil # rubocop:disable Style/RescueModifier
+      @wait_thr&.join
+    ensure
+      close_io
+    end
+
+    private
+
+    # Cleaned environment for the app bundle: strip the gem's bundler/Ruby context so
+    # `bundle exec` resolves the APP's Gemfile under the requested Ruby.
+    def app_env
+      env = ENV.to_h.reject { |k, _| k.start_with?("BUNDLE_", "RUBY", "GEM_") }
+      env["BUNDLE_GEMFILE"] = @gemfile
+      env["RBENV_VERSION"] = @ruby_version if @ruby_version
+      env["RAILS_ENV"] ||= "test" if @boot[:rails] || @boot["rails"]
+      env
+    end
+
+    # Spawn the daemon under the app bundle and complete the ready handshake.
+    #
+    # @return [void]
+    # @raise [Mutineer::DaemonBootError] when the daemon fails to boot.
+    def spawn_daemon
+      # Plain `bundle exec ruby` — NOT `rbenv exec`, which would break CI and any
+      # non-rbenv setup. When bundler/ruby are rbenv shims, the RBENV_VERSION carried
+      # in app_env still selects the app's Ruby; otherwise the active Ruby is used.
+      @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(
+        app_env, "bundle", "exec", "ruby",
+        "-r", DAEMON_PATH, "-e", "Mutineer::DaemonServer.run", chdir: @app_root
+      )
+      # Drain daemon stderr to the tool's stderr so child/boot errors are visible.
+      # Tracked (not fire-and-forget) so close_io can reclaim it on quit/respawn; the
+      # rescue swallows the benign EBADF/IOError raised when close_io closes the pipe
+      # out from under an in-flight copy_stream.
+      @drain = Thread.new do # rubocop:disable ThreadSafety/NewThread
+        IO.copy_stream(@stderr, @errio)
+      rescue IOError, Errno::EBADF
+        nil
+      end
+
+      send_line(@boot)
+      ready = read_line
+      unless ready && ready["ready"]
+        detail = ready && ready["error"] ? ready["error"] : "daemon exited before the handshake"
+        close_io
+        raise DaemonBootError, "daemon failed to boot under the app bundle: #{detail}"
+      end
+    end
+
+    # Respawn after a crash, up to MAX_RESTARTS, then hard-fail loudly.
+    def restart!
+      close_io
+      @restarts += 1
+      if @restarts > MAX_RESTARTS
+        raise DaemonBootError, "daemon crashed #{@restarts} times; aborting the run"
+      end
+
+      @errio.puts("[mutineer] daemon crashed — respawning (#{@restarts}/#{MAX_RESTARTS})")
+      spawn_daemon
+    end
+
+    # Write one JSON object as a line to the daemon.
+    #
+    # @param obj [Hash] the message to encode.
+    # @return [void]
+    def send_line(obj)
+      @stdin.puts(JSON.generate(obj))
+      @stdin.flush
+    end
+
+    # Read one JSON reply line; nil on EOF/dead pipe (caller treats as a crash).
+    def read_line
+      line = @stdout.gets
+      line && JSON.parse(line.strip)
+    rescue IOError, Errno::EPIPE, JSON::ParserError
+      nil
+    end
+
+    # Close the IPC pipes, stop the stderr-drain thread, and reap the daemon so a
+    # respawn or quit leaves no leaked fd, thread, or zombie.
+    #
+    # @return [void]
+    def close_io
+      @drain&.kill # stop the drain BEFORE closing its fd (avoids a copy_stream EBADF)
+      [@stdin, @stdout, @stderr].each { |io| io&.close rescue nil } # rubocop:disable Style/RescueModifier
+      @wait_thr&.join # reap the exited daemon so respawn/quit leaves no zombie
+      @stdin = @stdout = @stderr = @drain = @wait_thr = nil
+    end
+  end
+end