mutineer 1.5.0 → 1.6.0

data/lib/mutineer/daemon_backend.rb

@@ -5,10 +5,7 @@ require_relative "result"
 require_relative "coverage_map"
 require_relative "daemon_client"
 require_relative "progress"
-# No require_relative "runner" on purpose: runner.rb requires this file, and the
-# reverse edge makes Ruby warn "circular require considered harmful" on every -w
-# load. Runner is loaded first on every real path; requiring this file alone leaves
-# it undefined. Rationale and the real fix: #75.
+require_relative "job_plan"
 
 module Mutineer
   # Daemon execution backend. Boots the app ONCE in a persistent subprocess under
@@ -19,12 +16,12 @@ module Mutineer
   # When jobs > 1 each worker runs against its OWN database, which is what makes
   # `--jobs N` safe under Rails (#26): parallel verdicts are identical to serial.
   #
-  # Job collection, `--since` filtering and coverage selection stay on {Runner} and
-  # are called from here, so the daemon path can never drift from the in-process
-  # path on which mutants run or which tests narrow a mutant (score parity).
+  # Job collection, `--since` filtering and coverage selection live in {JobPlan},
+  # which the in-process path calls too, so the daemon path can never drift from
+  # it on which mutants run or which tests narrow a mutant (score parity).
   #
   # Unlike {ExternalBackend}, which is a leaf {Runner} calls into, this module owns
-  # its orchestration and calls back for that shared vocabulary.
+  # its orchestration and takes that shared vocabulary from {JobPlan}.
   module DaemonBackend
     # Default per-mutant timeout on the daemon path (seconds), overridden by
     # config.daemon_timeout. Coverage narrowing usually keeps each job short; this
@@ -44,10 +41,10 @@ module Mutineer
     # @param config [Mutineer::Config] run configuration (daemon set).
     # @param operator_classes [Array<Class>] resolved operators.
     # @return [Array(Mutineer::AggregateResult, Hash<String,String>, Hash)] aggregate,
-    #   source map, and the {Runner.collect_jobs} extras.
+    #   source map, and the {JobPlan.collect_jobs} extras.
     def self.execute(config, operator_classes)
-      jobs, ignored_results, source_map, extras = Runner.collect_jobs(config, operator_classes)
-      jobs = Runner.filter_since(jobs, source_map, config) if config.since
+      jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
+      jobs = JobPlan.filter_since(jobs, source_map, config) if config.since
       abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
 
       # Nothing to mutate (`--since` matched no changed line, or every mutant is
@@ -58,7 +55,7 @@ module Mutineer
         # The daemon sweeps orphaned temps at boot and nothing boots here, so sweep
         # tool-side. A file a hard-killed run left in app/models breaks the app's own
         # Zeitwerk boot, not just Mutineer's next run.
-        Runner.sweep_orphans(Runner.source_dirs(config), DAEMON_TEMP_GLOB)
+        JobPlan.sweep_orphans(JobPlan.source_dirs(config), DAEMON_TEMP_GLOB)
         return [AggregateResult.new(ignored_results), source_map, extras]
       end
 
@@ -91,8 +88,11 @@ module Mutineer
     # Build the coverage map via a short-lived daemon (boots the app once, captures
     # per-test coverage app-side, ships the map back). Returns a query-only
     # CoverageMap, or nil when the build fails / returns empty. Callers then run the
-    # full --test set. Coverage-build IPC has no wall-clock (same limitation as
-    # in-process build_via_fork). A normal nonempty map scores like in-process;
+    # full --test set. An empty map that came with boot lines returns a map with
+    # those lines only: it narrows nothing, but still classifies `ran_at_load`.
+    # Each capture is bounded by capture_timeout (#101); the client's wait for
+    # the whole map is not, because its length grows with the number of test
+    # files. A normal nonempty map scores like in-process;
     # nil falls back to the full suite (more testing, not comparable).
     #
     # @param config [Mutineer::Config] the run config.
@@ -109,7 +109,7 @@ module Mutineer
       # A red unmutated suite must abort, even when the shipped map is empty.
       # Falling back to the full --test set would treat those failures as kills.
       if data.is_a?(Hash) && Array(data["failed_clean_tests"]).any?
-        Runner.abort_if_unclean!(CoverageMap.from_data(
+        JobPlan.abort_if_unclean!(CoverageMap.from_data(
           map: data["map"] || {},
           failed_test_files: data["failed_test_files"] || [],
           project_root: config.project_root,
@@ -120,11 +120,21 @@ module Mutineer
       unless data && !(data["map"] || {}).empty?
         reason = data.is_a?(Hash) && data["error"] ? data["error"] : "empty map"
         warn_coverage_fallback(reason)
-        return nil
+        # No narrowing ({job_result} runs every test), but the lines and
+        # methods that ran at boot still classify a survivor on one of them.
+        load_lines = data.is_a?(Hash) ? Array(data["load_lines"]) : []
+        load_methods = data.is_a?(Hash) ? Array(data["load_methods"]) : []
+        return nil if load_lines.empty? && load_methods.empty?
+
+        return CoverageMap.from_data(map: {}, failed_test_files: [], project_root: config.project_root,
+                                     load_lines: load_lines, load_methods: load_methods)
       end
 
       CoverageMap.from_data(map: data["map"], failed_test_files: data["failed_test_files"] || [],
-                            project_root: config.project_root)
+                            project_root: config.project_root, load_lines: data["load_lines"] || [],
+                            load_methods: data["load_methods"] || [])
+    rescue DaemonBootTimeout
+      raise # a second daemon for the mutant runs would hang just as long
     rescue DaemonBootError => e
       warn_coverage_fallback("#{e.class}: #{e.message}")
       nil
@@ -246,10 +256,10 @@ module Mutineer
       # Skip an invalid mutant tool-side: never ship a payload that would fail to
       # load and read as a false `killed`.
       # Narrow to covering tests (shared with the in-process path via
-      # Runner.coverage_selection, so scores match). :verdict = no_coverage/uncapturable,
-      # no fork. No map (build failed) → run the full --test set (fallback, not
-      # narrowed).
-      sel = coverage_map && Runner.coverage_selection(subject.file, mutation, subject, source, coverage_map)
+      # JobPlan.coverage_selection, so scores match). :verdict = no_coverage/uncapturable,
+      # no fork. No map, or an empty one (build failed) → run the full --test set
+      # (fallback, not narrowed).
+      sel = coverage_map && !coverage_map.map.empty? && JobPlan.coverage_selection(subject.file, mutation, subject, source, coverage_map)
       r =
         if Parser.parse_string(mutated).errors.any?
           Result.skipped
@@ -261,14 +271,16 @@ module Mutineer
             payload: { "code" => mutated, "source_file" => File.expand_path(subject.file, config.project_root) },
             tests: sel ? sel[1] : abs_tests
           )
-          result_for(verdict)
+          # A survivor whose line ran at load, as in-process (Runner.run).
+          JobPlan.load_verdict(result_for(verdict), subject.file, mutation, subject, source, coverage_map)
         end
       r.with(subject: subject, mutation: mutation, id: id)
     end
 
-    # The boot config the daemon needs to boot the app once: where to boot, the test
-    # load roots (so `require "test_helper"` resolves in every fork), framework, and
-    # whether this is Rails.
+    # The boot config the daemon needs to boot the app once: where to boot, the
+    # --require files to load after it, the test load roots (so
+    # `require "test_helper"` resolves in every fork), framework, and whether this
+    # is Rails.
     #
     # @param config [Mutineer::Config] the run config.
     # @param abs_tests [Array<String>] absolute --test paths.
@@ -278,13 +290,16 @@ module Mutineer
       {
         project_root: config.project_root,
         boot: File.expand_path(config.boot || "config/environment", config.project_root),
-        load_paths: Runner.test_load_roots(abs_tests),
+        # Required after the boot, as in-process (Runner.execute); also part of
+        # the coverage digest.
+        require_paths: config.require_paths.map { |f| File.expand_path(f, config.project_root) },
+        load_paths: JobPlan.test_load_roots(abs_tests),
         cache_dir: File.expand_path(config.cache_dir, config.project_root),
-        source_dirs: Runner.source_dirs(config), # so the daemon can sweep orphan mutant temps
+        source_dirs: JobPlan.source_dirs(config), # so the daemon can sweep orphan mutant temps
         framework: config.framework,
         rails: config.rails,
-        # Schema for per-worker DB isolation. Sent when present; the daemon
-        # skips worker-DB schema loading if the path is absent (e.g. structure.sql apps).
+        # Schema for per-worker DB isolation. Sent when present; the daemon loads
+        # it over a worker's copy of the test DB only when that copy is out of date.
         schema: schema_path(config),
         # Coverage narrowing. Only the short-lived map-building daemon starts
         # Coverage (before boot); worker daemons boot with it OFF (no wasted
@@ -298,10 +313,10 @@ module Mutineer
       }
     end
 
-    # Absolute path to the app's `db/schema.rb` if it exists, else nil. Used by the
-    # daemon to schema-load each fork's isolated worker database. Only `schema.rb`
-    # is supported this pass; `structure.sql` apps get nil and fall back to
-    # whatever the worker DB already holds.
+    # Absolute path to the app's `db/schema.rb` if it exists, else nil. Each worker
+    # DB starts as a copy of the test DB; the daemon loads this file over the copy
+    # when the copy's schema differs. `structure.sql` apps get nil and keep the
+    # copy as it is.
     #
     # @param config [Mutineer::Config] the run config.
     # @api private

data/lib/mutineer/daemon_client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "io/wait"
 require "open3"
 require_relative "external_backend"
 
@@ -12,6 +13,11 @@ module Mutineer
   # to a runtime error (exit 1).
   class DaemonBootError < StandardError; end
 
+  # A boot that has not answered the handshake within DaemonClient::BOOT_TIMEOUT
+  # (#101). Unlike other boot errors it is not worth retrying with a second
+  # daemon, which would wait just as long.
+  class DaemonBootTimeout < DaemonBootError; end
+
   # Tool-side handle for the app-side daemon.
   #
   # Spawns `daemon_server.rb` UNDER THE APP'S BUNDLE/RUBY. The child gets the
@@ -29,6 +35,13 @@ module Mutineer
     DAEMON_PATH = File.expand_path("daemon_server.rb", __dir__)
     # How many times to respawn a crashing daemon before aborting the run.
     MAX_RESTARTS = 3
+    # Seconds a verdict may lag the request's own timeout. The daemon enforces
+    # that timeout on the mutant child, so a reply later than this means the
+    # daemon itself is wedged (#101): it is killed and respawned.
+    REPLY_GRACE = 30
+    # Seconds the daemon gets to boot the app and answer the handshake. A boot
+    # that never returns ends the run instead of hanging it (#101).
+    BOOT_TIMEOUT = 600
     # Bundler's marker for a variable that was unset before it activated.
     BUNDLER_UNSET = "BUNDLER_ENVIRONMENT_PRESERVER_INTENTIONALLY_NIL"
 
@@ -83,7 +96,7 @@ module Mutineer
       reply =
         begin
           send_line("id" => id, "worker" => worker, "payload" => payload, "tests" => tests, "timeout" => timeout)
-          read_line
+          read_line(timeout + REPLY_GRACE)
         rescue Errno::EPIPE, IOError
           nil
         end
@@ -117,7 +130,7 @@ module Mutineer
       return unless @stdin
 
       send_line("cmd" => "quit") rescue nil # rubocop:disable Style/RescueModifier
-      @wait_thr&.join
+      @wait_thr&.join(REPLY_GRACE) # a wedged daemon is killed by close_io
     ensure
       close_io
     end
@@ -315,16 +328,21 @@ module Mutineer
           end
 
           send_line(@boot)
-          read_line
+          read_line(BOOT_TIMEOUT)
         rescue SystemCallError, IOError => e
           close_io
           raise DaemonBootError, "daemon could not be started: #{e.class}: #{e.message}"
         end
 
       unless ready && ready["ready"]
-        detail = ready && ready["error"] ? ready["error"] : "daemon exited before the handshake"
+        detail =
+          if ready && ready["error"] then ready["error"]
+          elsif @timed_out then "the daemon did not finish booting within #{BOOT_TIMEOUT}s"
+          else "daemon exited before the handshake"
+          end
+        timed_out = @timed_out
         close_io
-        raise DaemonBootError, "daemon failed to boot under the app bundle: #{detail}"
+        raise (timed_out ? DaemonBootTimeout : DaemonBootError), "daemon failed to boot under the app bundle: #{detail}"
       end
     end
 
@@ -333,10 +351,11 @@ module Mutineer
       close_io
       @restarts += 1
       if @restarts > MAX_RESTARTS
-        raise DaemonBootError, "daemon crashed #{@restarts} times; aborting the run"
+        raise DaemonBootError, "daemon crashed or stopped answering #{@restarts} times; aborting the run"
       end
 
-      @errio.puts("[mutineer] daemon crashed — respawning (#{@restarts}/#{MAX_RESTARTS})")
+      cause = @timed_out ? "stopped answering" : "crashed"
+      @errio.puts("[mutineer] daemon #{cause} — respawning (#{@restarts}/#{MAX_RESTARTS})")
       spawn_daemon
     end
 
@@ -349,8 +368,15 @@ module Mutineer
       @stdin.flush
     end
 
-    # Read one JSON reply line; nil on EOF/dead pipe (caller treats as a crash).
-    def read_line
+    # Read one JSON reply line; nil on EOF/dead pipe, or when no line arrives
+    # within `timeout` seconds (caller treats either as a crash).
+    #
+    # @param timeout [Numeric, nil] seconds to wait; nil waits for the reply.
+    # @return [Hash, nil]
+    def read_line(timeout = nil)
+      @timed_out = timeout && !@stdout.wait_readable(timeout)
+      return nil if @timed_out
+
       line = @stdout.gets
       line && JSON.parse(line.strip)
     rescue IOError, Errno::EPIPE, JSON::ParserError
@@ -362,6 +388,13 @@ module Mutineer
     #
     # @return [void]
     def close_io
+      # A wedged daemon may never read the closed stdin, so the reap below would
+      # wait forever: kill it first. An exited daemon makes this a no-op.
+      begin
+        Process.kill(:KILL, @wait_thr.pid) if @wait_thr&.alive?
+      rescue Errno::ESRCH
+        nil # it exited between the check and the kill
+      end
       @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

data/lib/mutineer/daemon_server.rb

@@ -3,15 +3,18 @@
 require "json"
 require "tempfile"
 require_relative "child_stdout"
+require_relative "orphan_guard"
 
 module Mutineer
   # App-side daemon (persistent worker).
   #
   # Runs UNDER THE APP'S OWN BUNDLE/RUBY (the tool's DaemonClient spawns it via
   # `bundle exec ruby`). It boots the app ONCE, then serves per-mutant test-run
-  # requests over stdin/stdout as newline-delimited JSON. For each request it
-  # FORKS a child that loads the mutated source text the tool sent, runs the
-  # covering tests, and exits with a status the parent decodes into a verdict.
+  # requests over stdin/stdout as newline-delimited JSON (the protocol keeps a
+  # private copy of the original stdout; the app's own stdout goes to stderr).
+  # For each request it FORKS a child that loads the mutated source text the
+  # tool sent, runs the covering tests, and exits with a status the parent
+  # decodes into a verdict.
   #
   # HARD CONSTRAINT: this file must be loadable WITHOUT Prism or the rest of
   # mutineer. The app's Ruby may be < 3.4 (no stdlib Prism) and its bundle has no
@@ -21,7 +24,7 @@ module Mutineer
   # tool-side; the daemon only `load`s text.
   #
   # Protocol (one JSON object per line, both directions):
-  #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment",
+  #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment","require_paths":[...],
   #               "load_paths":["test"],"framework":"minitest","rails":true,"schema":"db/schema.rb"}
   #   ready out: {"ready":true,"ruby":"3.3.6"}   (or {"ready":false,"error":"..."} then exit)
   #   run  in  : {"id":N,"worker":I,"payload":{"code":"<ruby>","source_file":"app/models/order.rb"},
@@ -49,10 +52,14 @@ module Mutineer
       # Serve the protocol on the given IO pair (defaults to stdio). Returns on quit.
       #
       # @param input [IO] request stream.
-      # @param output [IO] verdict stream.
+      # @param output [IO, nil] verdict stream. nil (the default) reserves the
+      #   process's original stdout for the protocol and points fd 1 at stderr.
       # @param errio [IO] diagnostics stream (never the IPC channel).
       # @return [void]
-      def run(input: $stdin, output: $stdout, errio: $stderr)
+      def run(input: $stdin, output: nil, errio: $stderr)
+        # Only a stream `run` reserved itself is the daemon's to close in a fork.
+        @protocol = output ? nil : reserve_protocol_output
+        output ||= @protocol
         @errio = errio
         @output = output
         boot_line = input.gets
@@ -92,6 +99,21 @@ module Mutineer
 
       private
 
+      # Move the protocol channel off fd 1 before the app boots. The app may
+      # print through `puts`, `STDOUT`, or a raw fd 1 write (a logger, a
+      # subprocess). A line like that ahead of the ready message would break
+      # the client's JSON read. The protocol keeps a private dup of the
+      # original stdout. Fd 1 then points at stderr, so app output stays
+      # visible in the tool's diagnostics.
+      #
+      # @return [IO] the reserved protocol stream.
+      def reserve_protocol_output
+        protocol = STDOUT.dup
+        STDOUT.reopen(STDERR)
+        $stdout = STDOUT
+        protocol
+      end
+
       # BOOT ONCE. chdir + require the app's boot file so the whole app is loaded
       # and inherited by every fork. Never requires mutineer.
       def boot!(cfg)
@@ -105,13 +127,16 @@ module Mutineer
         # instrumented. The map build (build_via_fork) forks this booted parent.
         if cfg["coverage"]
           require "coverage"
-          Coverage.start(lines: true)
+          Coverage.start(lines: true, methods: true)
         end
         # Clear any mutant tempfile a prior SIGKILLed timeout child orphaned in a
         # source dir BEFORE the app boots. Zeitwerk would otherwise choke on the
         # tempfile's non-constant name during autoload setup.
         sweep_temps
         require File.expand_path(cfg["boot"]) if cfg["boot"]
+        # The --require files, after the boot as in-process (Runner.execute), so
+        # the coverage peek sees what they ran at load.
+        Array(cfg["require_paths"]).each { |f| require File.expand_path(f) }
         setup_worker_db(cfg) if cfg["rails"]
       rescue Exception => e # rubocop:disable Lint/RescueException
         # Boot failed (bad boot path, app error). Tell the client and exit so it
@@ -131,15 +156,15 @@ module Mutineer
         @worker_db = RailsWorkerDb.available? ? RailsWorkerDb : nil
         schema = cfg["schema"] && File.expand_path(cfg["schema"])
         @schema_path = schema if schema && File.exist?(schema)
-        # Schema is loaded once per worker slot on first use (not every mutant fork).
-        @schema_ready = {}
+        # Each worker slot is seeded once, on first use (not every mutant fork).
+        @slot_ready = {}
       rescue LoadError => e
         @errio.puts("[daemon] worker-DB routing unavailable: #{e.message}")
         @worker_db = nil
       end
 
       # Build the coverage map app-side (Coverage was started at boot) and return
-      # it as `{map, failed_test_files}` for the tool to select covering tests.
+      # it as `{map, failed_test_files, load_lines, load_methods}` for the tool to select covering tests.
       # Capture forks route to worker 0's DB (isolated, serial). On any failure
       # return an empty map + an error string. The tool then falls back to the
       # full test set rather than mis-scoring everything as no_coverage.
@@ -149,42 +174,61 @@ module Mutineer
         cmap = CoverageMap.new(
           source_paths: Array(@cfg["sources"]), test_paths: Array(@cfg["tests"]),
           load_paths: Array(@cfg["load_paths"]), project_root: root,
-          boot_path: @cfg["boot"], framework: @framework, cache_dir: @cfg["cache_dir"] || File.join(root, ".mutineer"),
+          boot_path: @cfg["boot"], require_paths: Array(@cfg["require_paths"]),
+          framework: @framework, cache_dir: @cfg["cache_dir"] || File.join(root, ".mutineer"),
           capture_timeout: @cfg["capture_timeout"] || CoverageMap::DEFAULT_CAPTURE_TIMEOUT
         ).build_via_fork(after_fork: coverage_after_fork)
+        # Nothing reads Coverage after the map, so a mutant forked from this
+        # daemon does not pay for it (#228).
+        Coverage.suspend if Coverage.running?
         { "map" => cmap.map, "failed_test_files" => cmap.failed_test_files,
-          "failed_clean_tests" => cmap.failed_clean_tests }
+          "failed_clean_tests" => cmap.failed_clean_tests, "load_lines" => cmap.load_lines.to_a,
+          "load_methods" => cmap.load_methods.to_a }
       rescue Exception => e # rubocop:disable Lint/RescueException
         @errio.puts("[daemon] coverage build failed: #{e.class}: #{e.message}")
         { "map" => {}, "failed_test_files" => [], "error" => "#{e.class}: #{e.message}" }
       end
 
-      # Fork-safety hook for coverage capture: route each capture fork to worker
-      # 0's isolated DB (captures run serially, so one worker is enough). Nil when
-      # the app has no worker-DB adapter (non-Rails). Capture then runs as before.
+      # Fork-safety hook for coverage capture. Each capture fork drops its copy
+      # of the protocol channel (see close_protocol) and, when the app has a
+      # worker-DB adapter, routes to a fresh copy of the base DB in worker 0's
+      # slot (captures run serially, so one worker is enough).
       def coverage_after_fork
-        return nil unless @worker_db
-
+        worker_db = @worker_db
         schema = @schema_path
-        -> { @worker_db.after_fork(0, schema) }
+        lambda do
+          close_protocol
+          worker_db&.after_fork(0, schema, seed: true)
+        end
+      end
+
+      # A forked child never answers on the protocol channel. Closing its
+      # inherited copy lets a daemon crash read as EOF on the client at once,
+      # not only after a slow or hung child exits. A caller-supplied output
+      # (for example STDOUT) is left open.
+      def close_protocol
+        @protocol&.close rescue nil # rubocop:disable Style/RescueModifier
       end
 
       # Fork a child to run one mutant in isolation; decode its exit into a verdict.
       def run_mutant(req)
         timeout = req.fetch("timeout", 30)
         worker  = req.fetch("worker", 0)
-        # Load schema until the first killed/survived fork for this worker slot.
-        schema_for_fork = (@worker_db && @schema_path && !@schema_ready[worker]) ? @schema_path : nil
+        # Seed the slot's DB until the first killed/survived fork for this worker slot.
+        first_use = @worker_db && !@slot_ready[worker]
+        daemon = Process.pid
         pid = fork do
           # New process group so a per-fork timeout can SIGKILL the whole subtree,
-          # and silence the child's stdout so test output never corrupts the IPC pipe.
+          # and silence the child's stdout so test output stays out of the diagnostics.
           Process.setpgid(0, 0) rescue nil # rubocop:disable Style/RescueModifier
+          OrphanGuard.start(daemon)
           code =
             begin
               ChildStdout.silence
+              close_protocol
               # Route THIS fork at its own worker database before any test loads.
               # A routing failure raises here and is scored `error`, never a false verdict.
-              @worker_db&.after_fork(worker, schema_for_fork)
+              @worker_db&.after_fork(worker, first_use ? @schema_path : nil, seed: first_use)
               apply_payload(req["payload"])
               run_tests(Array(req["tests"]))
             rescue Exception => e # rubocop:disable Lint/RescueException
@@ -194,10 +238,10 @@ module Mutineer
           exit!(code)
         end
         verdict = wait_verdict(pid, timeout)
-        # Mark ready only when the child finished cleanly after schema load
-        # (killed/survived). Timeout can interrupt mid-load_schema; error is a
-        # routing failure. Both leave the slot unready so the next fork reloads.
-        @schema_ready[worker] = true if schema_for_fork && %w[killed survived].include?(verdict)
+        # Mark ready only when the child finished cleanly after seeding
+        # (killed/survived). Timeout can interrupt mid-copy; error is a routing
+        # failure. Both leave the slot unready so the next fork seeds again.
+        @slot_ready[worker] = true if first_use && %w[killed survived].include?(verdict)
         # A SIGKILLed timeout child skipped its Tempfile unlink. Sweep the orphan
         # so it cannot outlive the run or trip Zeitwerk on a later fork.
         sweep_temps if verdict == "timeout"
@@ -205,7 +249,7 @@ module Mutineer
       end
 
       # Remove orphaned mutant tempfiles from the source dirs (parent-side; the
-      # SIGKILL path cannot run the child's ensure). Mirrors Runner.sweep_orphans.
+      # SIGKILL path cannot run the child's ensure). Mirrors JobPlan.sweep_orphans.
       def sweep_temps
         @source_dirs.to_a.each do |dir|
           Dir.glob(File.join(dir, "mutineer_daemon*.rb")).each do |f|
@@ -219,6 +263,8 @@ module Mutineer
       # pulls in Prism which is forbidden app-side). NOTE: this is the 3rd copy of
       # the waitpid2(WNOHANG)+deadline+pgroup-SIGKILL+decode discipline. A fix to
       # the kill/reap/decode logic must be applied to all three in lockstep.
+      # CoverageMap#await_child applies the same deadline and group kill to
+      # coverage capture.
       # SIGKILL the child's process group past the deadline; a signalled child
       # (nil exitstatus) is `error`.
       def wait_verdict(pid, timeout)

data/lib/mutineer/file_swap.rb

@@ -21,7 +21,7 @@ module Mutineer
   # which makes leaving the file mutated the one genuinely dangerous failure mode.
   #
   # Defense in depth, mirroring the tempfile-orphan discipline
-  # (`Runner.sweep_orphans`, `isolation.rb` tempfiles):
+  # (`JobPlan.sweep_orphans`, `isolation.rb` tempfiles):
   #   - exclusive OS ownership (flock) is acquired before swap or recovery;
   #   - the original bytes are held in memory AND written to a sibling backup;
   #   - `ensure` restores from memory around every mutant;

data/lib/mutineer/isolation.rb

@@ -234,6 +234,7 @@ module Mutineer
         else
           mutated_def
         end
+      inner = "#{subject.block_owner}.class_eval do\n#{inner}\nend" if subject.block_owner
       wrapped = "#{prefix}#{inner}#{"\nend" * keywords.size}"
 
       # A snippet that fails to reparse must NOT silently fall through to