saboteur 0.6.0 → 0.8.0

data/lib/saboteur/doctor.rb

@@ -3,6 +3,8 @@
 
 require "coverage"
 require_relative "baseline_health"
+require_relative "engine/sandbox_policy"
+require_relative "execution/sandbox"
 
 module Saboteur
   # Reports the current environment, never mutations. The two unchanged suite
@@ -27,7 +29,8 @@ module Saboteur
       @out.puts "Rails: #{@config['rails'] ? 'enabled' : 'disabled'}"
       check_database_hosts
       @out.puts "SimpleCov: #{defined?(::SimpleCov) ? 'present; start suppressed for this process' : 'not loaded'}"
-      check_coverage
+      verify_coverage
+      check_sandbox
       check_suite(integration, hooks)
       true
     end
@@ -63,15 +66,60 @@ module Saboteur
             "doctor supports the rspec integration; set integration: rspec"
     end
 
+    # Printed once; verified twice. Boot must not wake coverage up, so the
+    # post-boot check re-reads the state without printing a second line.
     def check_coverage
       state = Coverage.state
       @out.puts "Coverage: #{state}"
+      verify_coverage(state)
+    end
+
+    def verify_coverage(state = Coverage.state)
       return if Coverage.supported?(:lines) && Coverage.supported?(:methods) && state == :suspended
 
       raise Error, "Coverage must be suspended with line and method support before boot; use the saboteur " \
                    "executable, disable SimpleCov and remove other Coverage.start calls"
     end
 
+    # A kernel capability probe, not verified isolation: what the kernel
+    # would let mutant children do, and what the run does with that - the
+    # engine's sandbox policy owns the refusal or degradation itself.
+    def check_sandbox
+      if @config["sandbox"] == false
+        @out.puts "Sandbox: off (c.sandbox = false)"
+        return
+      end
+      abi = sandbox_abi
+      if abi >= 3
+        @out.puts "Sandbox: kernel Landlock ABI #{abi} - capability probe only, not verified isolation"
+      elsif @config["sandbox"] == "strict"
+        @out.puts "Sandbox: #{Engine::SandboxPolicy.sandbox_gap(abi)}; " \
+                  'c.sandbox = "strict" refuses to run - children never run degraded'
+      else
+        @out.puts "Sandbox: #{Engine::SandboxPolicy.sandbox_gap(abi)}; " \
+                  "children would run with the hazard guard and canary only"
+        if RUBY_PLATFORM.match?(/darwin/i) && @config["sandbox"] == "seatbelt"
+          @out.puts %(Seatbelt (opt-in, #436): probe #{Execution::Seatbelt.probe} - capability probe only, ) \
+                    "not verified isolation"
+        elsif RUBY_PLATFORM.match?(/darwin/i)
+          @out.puts "macOS: mutants run unsandboxed (Landlock is Linux-only) - a container contains " \
+                    "filesystem writes outside the project"
+          @out.puts "Network: never restricted on any platform, and a plain container keeps outbound " \
+                    "access - deny or stub the network when a mutant could reach real APIs"
+        end
+      end
+    end
+
+    # The probe contract the engine's policy already keeps: an errored probe
+    # (EPERM under a seccomp policy, ...) is an actionable tool error, not a
+    # CLI internal error - doctor stays read-only.
+    def sandbox_abi
+      Execution::Sandbox.abi_version
+    rescue SystemCallError => e
+      raise Error, "sandbox is on but the Landlock probe failed (#{e.message}); a run would refuse the same way - " \
+                   "set c.sandbox = false to check without the sandbox"
+    end
+
     # Match against all included source definitions, not the current diff or
     # selected tests. A limited run must not make a valid ignore look stale.
     def check_ignore_subjects

data/lib/saboteur/engine/baseline_guard.rb

@@ -3,6 +3,8 @@
 
 require "json"
 require "fileutils"
+require_relative "../text"
+require_relative "../frameworks/sqlite_memory_database"
 
 module Saboteur
   class Engine
@@ -10,16 +12,28 @@ module Saboteur
     # or mutation source is used. This catches observed instability, not all
     # possible flaky behaviour.
     class BaselineGuard
+      # How many unchanged-suite checks actually completed and validated:
+      # the number of order comparisons a run can claim is one less.
+      attr_reader :completed_passes
+
       EXCERPT_LINES = 10
       EXCERPT_WIDTH = 200
       EXCERPT_SCAN_LINES = 5000
 
-      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:)
+      # full_passes: every full-suite pass the run will make, including the
+      # coverage build when the cache is cold, so the first timed pass can
+      # price the rest (#260).
+      def initialize(config:, integration:, hooks:, supervisor:, diagnostics:, full_passes: 2, between_passes: nil,
+                     timeout_cap: nil)
         @config = config
         @integration = integration
         @hooks = hooks
         @supervisor = supervisor
         @diagnostics = diagnostics
+        @full_passes = full_passes
+        @between_passes = between_passes
+        @timeout_cap = timeout_cap
+        @completed_passes = 0
       end
 
       def call
@@ -27,40 +41,126 @@ module Saboteur
         raise Error, "baseline has no tests. Check rspec_args and the suite filters before running saboteur again." if
           expected.empty?
 
-        @diagnostics.inform("checking the unchanged suite twice (seed #{@config['seed']})")
+        passes = @config["baseline_passes"]
+        @diagnostics.inform(announce(passes))
         previous = nil
-        2.times do |index|
+        passes.times do |index|
+          break if budget_spent?(index)
+
           number = index + 1
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           data = check(number)
+          announce_first_pass_cost(number, started)
           unless data["passed"] && data["failed"].empty?
             refuse(number,
-                   "the suite failed: #{Array(data['failed']).join(', ')}")
+                   with_hint("the suite failed: #{Array(data['failed']).join(', ')}", data))
           end
           executed = data["executed"]
           refuse(number, "executed tests do not match the loaded suite") unless
             executed.sort == expected.sort
           refuse(number, "test order changed between baseline checks") if previous && executed != previous
           previous = executed
+          @completed_passes += 1
         end
         nil
       end
 
       private
 
+      # A spent --max-duration budget skips the remaining passes - including
+      # the first, when boot alone already spent it (#245).
+      def budget_spent?(_index)
+        !@between_passes.nil? && @between_passes.call
+      end
+
+      def announce(passes)
+        case passes
+        when 1
+          "checking the unchanged suite once (seed #{@config['seed']}); " \
+          "order stability between passes is not checked (baseline_passes: 1)"
+        when 2
+          "checking the unchanged suite twice (seed #{@config['seed']})"
+        else
+          "checking the unchanged suite #{passes} times (seed #{@config['seed']})"
+        end
+      end
+
+      # Once the first pass is timed, the total cost stops being a guess:
+      # the remaining full passes cost roughly the same each. full_passes
+      # includes the cold-cache coverage build (#260), so name what actually
+      # remains: with baseline_passes 1 the one remaining pass is the coverage
+      # build, not another baseline check (#465).
+      def announce_first_pass_cost(number, started)
+        return unless number == 1
+
+        coverage_pending = @full_passes > @config["baseline_passes"]
+        remaining = @full_passes - number - (coverage_pending ? 1 : 0)
+        return if remaining.zero? && !coverage_pending
+
+        elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round
+        work = []
+        work << "the remaining #{remaining} full #{remaining == 1 ? 'pass' : 'passes'}" if remaining.positive?
+        work << "the coverage map build" if coverage_pending
+        total = remaining + (coverage_pending ? 1 : 0)
+        @diagnostics.inform("baseline check #{number} took #{elapsed} s; about #{elapsed * total} s left for " \
+                            "#{work.join(' and ')} at that rate")
+      end
+
+      # An admitted pass still gets only the time left in the run budget:
+      # without the cap it would overrun a spent --max-duration by its
+      # whole coverage_timeout.
+      def phase_timeout
+        @timeout_cap ? @timeout_cap.call(@config["coverage_timeout"]) : @config["coverage_timeout"]
+      end
+
+      # A pass that hit its deadline only because --max-duration shortened
+      # the admission below the configured phase timeout: the budget ended
+      # the run, the suite is not broken (#296).
+      def budget_stopped?(result, admitted)
+        result.stopped_by == :timeout && admitted < @config["coverage_timeout"]
+      end
+
+      def refuse_budget_stop(number, admitted)
+        raise BudgetPhaseTimeout, "the --max-duration budget stopped baseline check #{number} " \
+                                  "(admitted #{admitted.round(1)}s of the #{@config['coverage_timeout']}s " \
+                                  "phase timeout)"
+      end
+
+      # A containment limit stopping a healthy suite means the limit, not
+      # the suite: name the knob and its current value, like the sqlite
+      # :memory: hint (#387), so the user is not sent debugging a green
+      # suite (#459).
+      def stopped_reason(result)
+        reason = "the suite stopped: #{result.stopped_by} (#{result.detail})"
+        case result.stopped_by
+        when :processes
+          "#{reason}. If this suite forks heavily by design, raise the limit with " \
+          "c.max_processes (currently #{@config['max_processes']})"
+        when :memory
+          "#{reason}. If this suite legitimately needs more memory, raise the limit with " \
+          "c.max_memory_mb (currently #{@config['max_memory_mb']} MB)"
+        else
+          reason
+        end
+      end
+
       def check(number)
         Execution::ForkReadiness.prepare_heap
         heartbeat = @diagnostics.progress_heartbeat("baseline check #{number}").watch(log_path(number))
-        result = @supervisor.run(timeout: @config["coverage_timeout"], on_tick: heartbeat.method(:tick)) do |writer|
+        admitted = phase_timeout
+        result = @supervisor.run(timeout: admitted, on_tick: heartbeat.method(:tick),
+                                 label: "baseline child died during setup/run") do |writer|
           record(writer, number)
         end
-        refuse(number, "the suite stopped: #{result.stopped_by} (#{result.detail})") if result.stopped_by
+        refuse_budget_stop(number, admitted) if budget_stopped?(result, admitted)
+        refuse(number, stopped_reason(result)) if result.stopped_by
         # Before the payload checks: a child killed by a signal (the OOM
         # killer, say) writes nothing, and the signal is the explanation. A
         # child the supervisor itself killed after it had reported is not a
         # failure: its payload is checked below.
         refuse(number, unsuccessful_exit(result.exit_status, result.memory_pressure)) if result.child_failed?
         refuse(number, "the child did not report a result") if result.payload.empty?
-        refuse(number, "the suite left child processes behind") if result.leftover_pids.any?
+        refuse(number, leftover_message(result), excerpt: false) if result.leftover_pids.any?
         parse_result(number, result.payload)
       end
 
@@ -78,7 +178,7 @@ module Saboteur
       def parse_result(number, payload)
         data = JSON.parse(payload)
         refuse(number, "the child reported an invalid result") unless data.is_a?(Hash)
-        refuse(number, data["error"]) if data["error"]
+        refuse(number, with_hint(data["error"], data)) if data["error"]
         refuse(number, "the child reported invalid test results") unless valid_result?(data)
         data
       rescue JSON::ParserError
@@ -99,21 +199,42 @@ module Saboteur
         @hooks.run(:after_fork)
         Kernel.srand(@config["seed"])
         result = @integration.run_baseline(seed: @config["seed"])
-        writer.write(JSON.generate(passed: result.passed, failed: result.failed_ids, executed: result.executed_ids))
+        payload = { passed: result.passed, failed: result.failed_ids, executed: result.executed_ids }
+        payload[:hint] = Frameworks::SqliteMemoryDatabase.fork_loss_hint unless result.passed
+        writer.write(JSON.generate(payload))
       rescue Exception => e # rubocop:disable Lint/RescueException
-        writer.write(JSON.generate(error: "#{e.class}: #{e.message}"))
+        writer.write(JSON.generate(error: "#{e.class}: #{e.message}",
+                                   hint: Frameworks::SqliteMemoryDatabase.fork_loss_hint))
       ensure
         writer.close
       end
 
+      # A child that recognises its own failure shape (an empty sqlite
+      # :memory: database after the fork, #387) says how to fix it.
+      def with_hint(reason, data)
+        data["hint"] ? "#{reason}. #{data['hint']}" : reason
+      end
+
       def log_path(number)
         File.join(@config.path("cache_dir"), "baseline-#{number}.log")
       end
 
-      def refuse(number, reason)
+      # Leftover children are a pass-with-leaks verdict, not a suite
+      # failure: the message names the leaked processes (the supervisor's
+      # pre-kill notes) and skips the log excerpt, which holds only RSpec
+      # output and can never show them (#486).
+      def leftover_message(result)
+        notes = result.leftover_notes
+        detail = notes.empty? ? result.leftover_pids.join(", ") : notes.join(", ")
+        count = result.leftover_pids.size
+        "the suite passed but left #{count} child #{count == 1 ? 'process' : 'processes'} behind: #{detail}"
+      end
+
+      def refuse(number, reason, excerpt: true)
         raise Error, "baseline check #{number} failed at seed #{@config['seed']}: #{reason}. " \
-                     "#{failure_excerpt(number)}See the full log at #{log_path(number)}. Fix the suite or its " \
-                     "setup, then run saboteur again with the same seed. No mutants were started."
+                     "#{failure_excerpt(number) if excerpt}See the full log at #{log_path(number)}. " \
+                     "Fix the suite or its setup, then run saboteur again with the same seed. " \
+                     "No mutants were started."
       end
 
       # The first lines of the failure, inline, so the cause is readable
@@ -129,7 +250,8 @@ module Saboteur
       end
 
       def log_lines(number)
-        File.foreach(log_path(number), chomp: true).first(EXCERPT_SCAN_LINES).reject { |line| line.strip.empty? }
+        File.foreach(log_path(number), chomp: true).first(EXCERPT_SCAN_LINES)
+            .map { |line| Text.utf8(line) }.reject { |line| line.strip.empty? }
       rescue SystemCallError
         []
       end

data/lib/saboteur/engine/boot.rb

@@ -10,6 +10,10 @@ module Saboteur
       # A test suite that (perhaps only under a mutant) starts a saboteur run
       # would otherwise run saboteur inside a saboteur child, recursively.
       def self.refuse_recursion!
+        if ENV[Execution::ExternalRunner::CHILD_MARKER]
+          raise Error, "refusing to start: this process runs inside a saboteur external test command " \
+                       "(#{Execution::ExternalRunner::CHILD_MARKER} is set); a nested run could race its tree"
+        end
         return unless ENV[Execution::Supervisor::CHILD_ENV]
 
         raise Error, "refusing to start: this process is a saboteur child " \
@@ -83,10 +87,21 @@ module Saboteur
 
       def load_hooks
         Saboteur.current_hooks = @hooks
-        @config["hooks"].each { |file| load File.expand_path(file, @root) }
+        @config["hooks"].each { |file| load hook_path(file) }
       ensure
         Saboteur.current_hooks = nil
       end
+
+      # Kernel#load does not append .rb the way Kernel#require does, and
+      # doctor accepts the extensionless form (#257), so resolve it the same
+      # way here: the exact path first, then path.rb.
+      def hook_path(file)
+        path = File.expand_path(file, @root)
+        rb = "#{path}.rb"
+        return rb if !File.exist?(path) && File.extname(path).empty? && File.file?(rb)
+
+        path
+      end
     end
   end
 end

data/lib/saboteur/engine/canary.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../text"
 
 module Saboteur
   class Engine
@@ -15,7 +16,9 @@ module Saboteur
       GIT_DIR = ".git"
 
       def initialize(root, cache_dir: ".saboteur")
-        @root = root
+        # Retag losslessly: path bytes are identity here, and later
+        # File.join calls must not mix encodings.
+        @root = Text.utf8_identity(root.to_s)
         @cache_dir = cache_dir.to_s
         @snapshot = inventory
       end
@@ -29,16 +32,40 @@ module Saboteur
 
         of = " of #{subject.id}" if subject
         culprit = digest ? " The most recent mutant, #{digest}#{of}, is the likely cause." : ""
-        raise Saboteur::CanaryTripped,
-              "canary: #{missing.size} watched file(s) vanished from the working tree while mutants ran " \
-              "(first: #{missing.first}).#{culprit} The canary watches tracked files and .git presence " \
-              "and only detects the loss after the fact; it cannot restore anything. Recover from your " \
-              "own backup, a fresh checkout, or a reclone - a deleted .git or uncommitted work is gone " \
-              "unless you have another copy."
+        raise Saboteur::CanaryTripped, message(missing, culprit)
+      end
+
+      # The cheap per-mutant probe (#235): stats the snapshot paths only -
+      # no git, no glob - so it can run after every mutant.
+      def probe
+        @snapshot.reject { |rel| present?(rel) }
+      end
+
+      # Like check!, but for the per-mutant probe: the mutant whose run just
+      # ended is named, never the subject's most recent mutant.
+      def probe!(subject: nil, digest: nil)
+        missing = probe
+        return if missing.empty?
+
+        of = " of #{subject.id}" if subject
+        culprit = digest ? " The mutant that just ran, #{digest}#{of}, is the likely cause." : ""
+        raise Saboteur::CanaryTripped.new(message(missing, culprit), culprit_digest: digest)
       end
 
       private
 
+      def present?(rel)
+        File.exist?(File.join(@root, rel)) || File.symlink?(File.join(@root, rel))
+      end
+
+      def message(missing, culprit)
+        "canary: #{missing.size} watched file(s) vanished from the working tree while mutants ran " \
+          "(first: #{Text.utf8(missing.first)}).#{culprit} The canary watches tracked files and .git presence " \
+          "and only detects the loss after the fact; it cannot restore anything. Recover from your " \
+          "own backup, a fresh checkout, or a reclone - a deleted .git or uncommitted work is gone " \
+          "unless you have another copy."
+      end
+
       def inventory
         files = git? ? git_tracked_files : walk_files
         files << GIT_DIR if File.exist?(File.join(@root, GIT_DIR))
@@ -54,15 +81,19 @@ module Saboteur
         return walk_files unless status.success?
 
         # ls-files reads the index, which still names a deleted file; keep
-        # only paths present in the worktree so a deletion shows up.
-        out.split("\0").reject { |rel| cache_path?(rel) }
+        # only paths present in the worktree so a deletion shows up. Split
+        # the raw bytes first and retag each path losslessly: scrubbing a
+        # raw-byte name would make the File.exist? probe fail and drop the
+        # file from the watch, so its deletion would go unseen.
+        out.b.split("\0".b).map { |rel| Text.utf8_identity(rel) }
+           .reject { |rel| cache_path?(rel) }
            .select { |rel| File.exist?(File.join(@root, rel)) || File.symlink?(File.join(@root, rel)) }
       end
 
       def walk_files
         Dir.glob(File.join(@root, "**", "*"), File::FNM_DOTMATCH)
            .select { |path| File.file?(path) }
-           .map { |path| path.delete_prefix("#{@root}/") }
+           .map { |path| Text.utf8_identity(path).delete_prefix("#{@root}/") }
            .reject { |rel| rel.start_with?("#{GIT_DIR}/") || cache_path?(rel) }
       end
 

data/lib/saboteur/engine/candidate_selection.rb

@@ -6,7 +6,7 @@ module Saboteur
     # Selects a bounded list for each covered subject before workers fork.
     # Subject skips are not mutants and do not enter the mutation score.
     class CandidateSelection
-      attr_reader :skipped_subjects, :selected
+      attr_reader :skipped_subjects, :selected, :unscoped_digests
 
       def initialize(candidates:, map:, limit:, diagnostics:)
         @candidates = candidates
@@ -15,16 +15,28 @@ module Saboteur
         @diagnostics = diagnostics
         @skipped_subjects = {}
         @selected = {}
+        @unscoped_digests = {}
       end
 
       def for(subject, scope: nil)
         reason = subject.skip_reason || (skip_reason_for(subject) if @map.tests_for(subject).empty?)
         if reason
           @skipped_subjects[subject] = reason
+          # In a scoped run every subject is part of the change under
+          # review, so a skip is said up front, not only in the end-of-run
+          # summary (#574).
+          @diagnostics.announce(skip_announcement(subject, reason)) if scope
           return @selected[subject] = []
         end
 
         list = @candidates.for(subject)
+        # The full pre-scope digests let IgnoreList#apply tell "mutation gone"
+        # from "mutation scoped out of this run" (#284).
+        if scope
+          @unscoped_digests[subject.id] = list.map do |mutation, _|
+            mutation.digest(subject_start: subject.start_byte, original_source: subject.file_source)
+          end
+        end
         list = scope.restrict(subject, list) if scope
         omitted = list.size - @limit
         if omitted.positive?
@@ -36,6 +48,21 @@ module Saboteur
 
       private
 
+      # A scoped no-coverage skip names the specs the run loaded: coverage
+      # living in a sibling spec file is otherwise invisible, and the false
+      # read is "untestable" when the truth is "not loaded" (#636). Names
+      # at most five, like the other selection notes.
+      def skip_announcement(subject, reason)
+        line = "#{subject.id}: skipped (#{reason}); its change is not verified by this run"
+        return line unless reason == "no coverage"
+
+        loaded = @map.tests.map { |id| id.split("[").first.delete_prefix("./") }.uniq.sort
+        more = loaded.size > 5 ? ", ..." : ""
+        names = loaded.empty? ? "none" : loaded.first(5).join(", ")
+        "#{line} - loaded specs: #{names}#{more}; " \
+          "other spec files may cover it, pass --test to load them"
+      end
+
       # Load-only code is not "no coverage": it ran, just never inside a
       # test, and no forked test can re-run it (see CoverageMap::RAN_AT_LOAD).
       def skip_reason_for(subject)

data/lib/saboteur/engine/candidates.rb

@@ -10,6 +10,25 @@ module Saboteur
     # a subject into runnable candidates: applied, re-parsed, de-duplicated,
     # coarse first. Returns [[mutation, mutated_text]].
     class Candidates
+      # The generator for constant hash/array literal subjects (#306); the
+      # method operators walk a def body a constant does not have.
+      def self.build(config, diagnostics, hazard_guard:)
+        new(build_sources(config), diagnostics, hazard_guard: hazard_guard,
+                                                constant_source: build_constant_source(config))
+      end
+
+      # Constants are generated by the builtin operator family, so a
+      # config that drops "builtin" from c.sources drops constant mutation
+      # too: the configured sources are the boundary for every subject
+      # kind (#319). Custom sources never see constants.
+      def self.build_constant_source(config)
+        return nil unless config["sources"].include?("builtin")
+
+        MutationSource::ConstantLiterals.new(operators: config["operators"],
+                                             exclude_operators: config["exclude_operators"],
+                                             arid: config["arid"])
+      end
+
       def self.build_sources(config)
         root = File.realpath(config.root)
         config["sources"].map do |entry|
@@ -19,15 +38,26 @@ module Saboteur
           end
 
           file, const = entry.split(":", 2)
-          raise ConfigError, "mutation source #{entry.inspect} must be builtin or path.rb:ClassName" unless const
+          unless const
+            if entry.include?("*")
+              raise ConfigError, "mutation source #{entry.inspect} looks like a source glob; " \
+                                 "did you mean c.include? c.sources registers custom operator sources " \
+                                 "(builtin or path.rb:ClassName)"
+            end
+            raise ConfigError, "mutation source #{entry.inspect} must be builtin or path.rb:ClassName"
+          end
 
           require File.expand_path(file, root)
           Object.const_get(const).new
         end
       end
 
-      def initialize(sources, diagnostics, hazard_guard: nil, bytecode: BytecodeEquivalence.new)
+      # constant_source: the generator for ConstantSubject instances; nil
+      # leaves constants with no candidates (a safe empty list).
+      def initialize(sources, diagnostics, hazard_guard: nil, bytecode: BytecodeEquivalence.new,
+                     constant_source: nil)
         @sources = sources
+        @constant_source = constant_source
         @diagnostics = diagnostics
         @hazard_guard = hazard_guard
         @bytecode = bytecode
@@ -40,7 +70,7 @@ module Saboteur
         end
 
         seen = Set[subject.source]
-        list = @sources.flat_map { |source| proposals(source, subject) }.filter_map do |mutation|
+        list = sources_for(subject).flat_map { |source| proposals(source, subject) }.filter_map do |mutation|
           candidate(subject, mutation, seen)
         end
         list = suppress_inline(list, subject)
@@ -50,6 +80,15 @@ module Saboteur
 
       private
 
+      # Constant literals have their own generator; external custom sources
+      # implement the def-subject contract and never see constants (#306).
+      def sources_for(subject)
+        return @sources unless subject.is_a?(ConstantSubject)
+        return [] unless @constant_source
+
+        [@constant_source]
+      end
+
       def suppress_inline(list, subject)
         directives = InlineSuppression.new(subject.file, subject.file_source)
         list.reject do |mutation, _text|
@@ -95,6 +134,7 @@ module Saboteur
         seen << text
         unless parses?(text)
           @diagnostics.count_invalid_mutation
+          @diagnostics.warn("#{subject.id}: dropped #{mutation.operator} mutation (did not parse)")
           return record_drop(subject, mutation, "invalid_syntax")
         end
 

data/lib/saboteur/engine/coverage_guard.rb

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Owns the host process's Coverage state across a run: suspends after
+    # boot, and at the end resumes only its own suspension. A CLI process
+    # exits right after, so resume matters to hosts that embed the engine -
+    # a spec, or the dogfood's own coverage-map build (#254).
+    class CoverageGuard
+      def initialize(diagnostics)
+        @diagnostics = diagnostics
+      end
+
+      def suspend
+        @was_running = Coverage.state == :running
+        Coverage.suspend if @was_running
+      end
+
+      # Best-effort: a host that disturbed Coverage mid-run gets a warning,
+      # never a masked run outcome.
+      def resume
+        Coverage.resume if @was_running && Coverage.state == :suspended
+      rescue StandardError => e
+        @diagnostics.warn("coverage resume failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end